Introduction

in_top_k is a TensorFlow utility for classification evaluation. It answers a simple question for each sample in a batch: is the true class among the top k predicted classes? To use it correctly, you need the right input shapes and the right interpretation of what each argument represents.

The Core Inputs

The function takes three main inputs:

• 'predictions: a 2D tensor of shape [batch_size, num_classes]'
• 'targets: a 1D tensor of shape [batch_size]'
• 'k: the number of top predictions to consider'

In TensorFlow, a typical call looks like this:

1import tensorflow as tf
2
3predictions = tf.constant(
4    [
5        [0.1, 0.7, 0.2],
6        [0.8, 0.1, 0.1],
7        [0.2, 0.3, 0.5],
8    ],
9    dtype=tf.float32,
10)
11
12targets = tf.constant([1, 2, 0], dtype=tf.int32)
13
14result = tf.math.in_top_k(targets=targets, predictions=predictions, k=2)
15print(result.numpy())

The result is a Boolean tensor with one value per sample.

What predictions Should Contain

predictions is not a list of class ids. It is a score matrix where each row contains one score per class for one sample.

Those scores can be:

• logits
• probabilities
• any values whose ordering reflects model confidence

The important part is ranking, not normalization. in_top_k only cares whether the true class index falls within the highest k scores for that sample.

What targets Should Contain

targets must be integer class indices, one per sample. It should not be one-hot encoded labels.

Correct:

targets = tf.constant([1, 2, 0], dtype=tf.int32)

Incorrect for in_top_k:

1targets = tf.constant(
2    [
3        [0, 1, 0],
4        [0, 0, 1],
5        [1, 0, 0],
6    ],
7    dtype=tf.int32,
8)

If your labels are one-hot encoded, convert them first with tf.argmax.

Choosing k

k=1 corresponds to top-1 accuracy, which is ordinary classification accuracy. Larger values such as k=5 are useful in problems with many classes, where it is meaningful to ask whether the correct answer was among the model's top few guesses.

For example:

• image classification with many categories often uses top-5 accuracy
• smaller-class problems usually care most about top-1 accuracy

Choosing k should match the actual evaluation goal rather than just making the metric look better.

A Useful Evaluation Pattern

You can combine in_top_k with a mean to compute top-k accuracy:

1import tensorflow as tf
2
3predictions = tf.constant([[0.1, 0.7, 0.2], [0.8, 0.1, 0.1]], dtype=tf.float32)
4targets = tf.constant([1, 2], dtype=tf.int32)
5
6hits = tf.math.in_top_k(targets=targets, predictions=predictions, k=2)
7accuracy = tf.reduce_mean(tf.cast(hits, tf.float32))
8
9print(accuracy.numpy())

This is often the simplest way to understand how in_top_k fits into a larger evaluation loop.

Use It for Ranking Metrics, Not Loss Computation

in_top_k is an evaluation helper, not a training loss. It answers a ranking question about the model output after the forward pass. That makes it appropriate for metrics and validation reports, but not as a substitute for a differentiable optimization objective.

Common Pitfalls

• Passing one-hot encoded labels instead of integer class indices as targets.
• Giving predictions the wrong shape, such as a 1D tensor or class ids instead of class scores.
• Assuming the scores must be probabilities when logits work fine too.
• Choosing a large k without asking whether that metric matches the actual product requirement.
• Forgetting that the result is per-sample Boolean output, not a final scalar accuracy by itself.

Summary

• 'predictions should be a batch-by-class score matrix.'
• 'targets should be one integer class id per sample.'
• 'k defines how many top predictions count as a hit.'
• 'in_top_k returns one Boolean result per sample.'
• To turn it into a metric, cast the result and reduce it across the batch.