Introduction

TensorFlow Addons metrics work with the Functional API the same way built-in Keras metrics do: you create metric objects and pass them to model.compile. The most common mistakes are treating the metric like a layer, using the wrong output shape, or forgetting to configure arguments such as num_classes, average, or threshold.

Compile With Metric Instances, Not Tensor Calls

In the Functional API, metrics are not connected into the model graph manually. You build the model graph with layers, then attach metrics during compile.

A correct example with F1Score looks like this:

1import tensorflow as tf
2import tensorflow_addons as tfa
3
4inputs = tf.keras.Input(shape=(20,))
5x = tf.keras.layers.Dense(32, activation="relu")(inputs)
6outputs = tf.keras.layers.Dense(3, activation="softmax")(x)
7
8model = tf.keras.Model(inputs=inputs, outputs=outputs)
9
10model.compile(
11    optimizer="adam",
12    loss="categorical_crossentropy",
13    metrics=[
14        tf.keras.metrics.CategoricalAccuracy(name="accuracy"),
15        tfa.metrics.F1Score(num_classes=3, average="macro", name="f1")
16    ]
17)

The important detail is that tfa.metrics.F1Score(...) is passed as a metric object. You do not call it on outputs yourself during model construction.

Match The Metric To The Output Format

Many Addons metrics are stricter than built-in accuracy metrics because they depend on class layout. That means your labels and output tensor must match the metric's expectations.

For example:

• softmax with one-hot labels pairs well with categorical_crossentropy
• sigmoid with multi-label targets often needs a thresholded metric
• sparse integer labels do not fit every Addons metric directly

Here is a full categorical example:

1import numpy as np
2import tensorflow as tf
3import tensorflow_addons as tfa
4
5X = np.random.randn(100, 20).astype("float32")
6y = tf.keras.utils.to_categorical(np.random.randint(0, 3, size=100), num_classes=3)
7
8inputs = tf.keras.Input(shape=(20,))
9x = tf.keras.layers.Dense(16, activation="relu")(inputs)
10outputs = tf.keras.layers.Dense(3, activation="softmax")(x)
11
12model = tf.keras.Model(inputs, outputs)
13model.compile(
14    optimizer="adam",
15    loss="categorical_crossentropy",
16    metrics=[tfa.metrics.F1Score(num_classes=3, average="macro")]
17)
18
19model.fit(X, y, epochs=2, batch_size=16)

If the labels were sparse integers instead of one-hot vectors, you would need to either convert them or choose a metric compatible with that representation.

Configure Thresholds For Binary And Multi-Label Problems

Metrics such as F1 need a decision rule. For sigmoid outputs, that usually means a threshold.

1import numpy as np
2import tensorflow as tf
3import tensorflow_addons as tfa
4
5X = np.random.randn(64, 10).astype("float32")
6y = np.random.randint(0, 2, size=(64, 4)).astype("float32")
7
8inputs = tf.keras.Input(shape=(10,))
9x = tf.keras.layers.Dense(12, activation="relu")(inputs)
10outputs = tf.keras.layers.Dense(4, activation="sigmoid")(x)
11
12model = tf.keras.Model(inputs, outputs)
13model.compile(
14    optimizer="adam",
15    loss="binary_crossentropy",
16    metrics=[
17        tfa.metrics.F1Score(num_classes=4, average="macro", threshold=0.5)
18    ]
19)
20
21model.fit(X, y, epochs=2, batch_size=8)

Without a threshold, the metric may not behave the way you expect because sigmoid outputs are probabilities, not hard class assignments.

Multi-Output Models Need Metric Mapping

If your Functional API model has more than one output, metrics should usually be passed as a dictionary keyed by output layer name.

1inputs = tf.keras.Input(shape=(20,))
2x = tf.keras.layers.Dense(16, activation="relu")(inputs)
3
4class_output = tf.keras.layers.Dense(3, activation="softmax", name="class_output")(x)
5score_output = tf.keras.layers.Dense(1, activation="linear", name="score_output")(x)
6
7model = tf.keras.Model(inputs, [class_output, score_output])
8
9model.compile(
10    optimizer="adam",
11    loss={
12        "class_output": "categorical_crossentropy",
13        "score_output": "mse"
14    },
15    metrics={
16        "class_output": [tfa.metrics.F1Score(num_classes=3, average="macro")],
17        "score_output": [tf.keras.metrics.MeanAbsoluteError()]
18    }
19)

This avoids accidentally applying a classification metric to a regression head.

Remember That Metrics Are Stateful

Keras metrics accumulate state across batches during an epoch. TensorFlow handles resetting them at the right time during fit, but this matters when you evaluate them manually.

If you use a metric outside model.compile, call update_state, inspect result, and reset with reset_state when needed.

That is another reason metric objects belong in the compile step unless you have a specific custom training loop.

Common Pitfalls

The biggest mistake is calling the metric on tensors inside the model graph as if it were a layer. Metrics belong in compile, not in the network architecture.

Another mistake is mismatching label format and output format. Many Addons metrics expect one-hot or multi-label tensors with a known class dimension.

People also forget parameters such as num_classes and threshold, then wonder why the metric shape or score looks wrong.

Finally, in multi-output models, passing one flat metric list can attach metrics to the wrong output. Use a metrics dictionary when the heads represent different tasks.

Summary

• Create TensorFlow Addons metric instances and pass them to model.compile.
• Match the metric to the model output shape and label encoding.
• Configure num_classes, average, and threshold explicitly when needed.
• Use per-output metric dictionaries for multi-head Functional API models.
• Do not treat metrics like layers inside the model graph.