Introduction

Sample weights let you tell TensorFlow that some training examples should matter more than others. This is useful for class imbalance, noisy data, or any problem where one example should contribute more strongly to the loss than another.

With TensorFlow datasets, the main rule is simple: the dataset should yield (features, labels, sample_weight) triples if you want model.fit() to consume sample weights directly. Once the dataset structure matches that expectation, the rest is straightforward.

Build a Dataset That Includes Weights

A minimal example looks like this:

1import tensorflow as tf
2
3features = tf.constant([[1.0], [2.0], [3.0], [4.0]])
4labels = tf.constant([0, 1, 0, 1])
5weights = tf.constant([1.0, 3.0, 1.0, 3.0])
6
7dataset = tf.data.Dataset.from_tensor_slices((features, labels, weights)).batch(2)

Each example now has a feature tensor, a label, and a sample weight. The larger weight means the model's loss calculation will pay more attention to that example.

Train a Keras Model with Weighted Samples

Keras understands that third dataset element automatically when using fit():

1model = tf.keras.Sequential([
2    tf.keras.layers.Input(shape=(1,)),
3    tf.keras.layers.Dense(8, activation="relu"),
4    tf.keras.layers.Dense(1, activation="sigmoid"),
5])
6
7model.compile(optimizer="adam", loss="binary_crossentropy", metrics=["accuracy"])
8model.fit(dataset, epochs=3)

No separate sample_weight= argument is needed here because the dataset already provides the weights as part of each training example.

Why This Structure Matters

Keras expects one of these shapes during training:

• '(x, y)'
• '(x, y, sample_weight)'

That means the dataset itself must yield the third component if you want weights to travel through the input pipeline cleanly. If the dataset yields only features and labels, sample weights have to be passed some other way.

Compute Weights Dynamically

Sometimes weights are derived from labels rather than stored explicitly. You can attach them with map():

1base_dataset = tf.data.Dataset.from_tensor_slices((features, labels))
2
3def add_weights(x, y):
4    weight = tf.where(tf.equal(y, 1), 3.0, 1.0)
5    return x, y, weight
6
7dataset = base_dataset.map(add_weights).batch(2)

This is useful when class weighting logic is simple and can be derived on the fly.

Use Sample Weights Deliberately

Sample weighting is powerful, but it changes the optimization objective. If weights are poorly chosen, training can become biased in the wrong direction.

That means you should use weights when there is a real modeling reason, not just because the API makes it possible.

Sample Weights Versus Class Weights

Class weights are attached to label classes, while sample weights belong to individual examples. If every example in a class should be treated the same way, class weights may be simpler. If individual rows need different influence, sample weights are the better fit.

This distinction matters because the data pipeline and training API handle those two weighting strategies in slightly different ways.

It is worth deciding that choice explicitly before the input pipeline grows more complex.

Common Pitfalls

• Building a dataset that yields only (features, labels) and expecting weights to be inferred automatically.
• Confusing sample weights with class weights. They are related but not identical.
• Applying very large weights without checking how they distort training.
• Forgetting that weighted losses may change metric interpretation.
• Adding weights late in the pipeline without confirming the dataset structure still matches Keras expectations.

Summary

• TensorFlow datasets can carry sample weights directly as (x, y, sample_weight) tuples.
• Keras fit() understands that structure automatically.
• Weights can be loaded explicitly or computed with Dataset.map().
• Use sample weighting when some examples should influence loss more than others.
• Check that the dataset structure matches what the training loop expects.