●Change8

Migrating to sentence-transformers v4.0.1

Version v4.0.1 introduces 3 breaking changes. This guide details how to update your code.

Released: 3/26/2025

3
Breaking Changes
7
Migration Steps
8
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

CrossEncoderCrossEncoderTrainerCrossEncoderTrainingArgumentsBinaryCrossEntropyLossCachedMultipleNegativesRankingLossSentenceEvaluatorInputExamplemodel.fit

Breaking Changes

●Issue #1

The old training workflow using `InputExample`, `DataLoader` and `model.fit()` has been removed. Switch to the new `CrossEncoderTrainer` with a `datasets.Dataset` or `DatasetDict` and a `CrossEncoderTrainingArguments` instance.

●Issue #2

The `loss` argument now expects a loss object or a dictionary of loss objects keyed by dataset names; passing a single loss for a `DatasetDict` without a matching dict will raise an error.

●Issue #3

Automatic model card generation now overwrites previous manual cards; if you relied on custom cards you must disable or edit them after training.

Migration Steps

  1. 1
    Replace any usage of `model.fit(...)` with a `CrossEncoderTrainer` instance and call `trainer.train()`.
  2. 2
    Convert training data from lists of `InputExample` or `DataLoader` objects to a HuggingFace `datasets.Dataset` (or `DatasetDict`).
  3. 3
    If you train on multiple datasets, provide a dictionary of loss objects keyed by the dataset names and pass a matching dictionary to the `loss` parameter.
  4. 4
    Import and use `CrossEncoderTrainingArguments` (or the base `TrainingArguments`) instead of the old argument objects.
  5. 5
    Update imports to include `CrossEncoderTrainer` and, if needed, `CrossEncoderTrainingArguments` from `sentence_transformers`.
  6. 6
    Install the `[train]` extra (`pip install sentence-transformers[train]==4.0.1`) to get the new training dependencies.
  7. 7
    If you rely on custom model cards, disable the automatic generation or edit the generated card after training.

Release Summary

Version 4.0.1 introduces a complete overhaul of the CrossEncoder training pipeline with a new `CrossEncoderTrainer`, dataset‑based inputs, multi‑GPU and bf16 support, and many training‑related enhancements, while keeping inference unchanged.

Need More Details?

View the full release notes and all changes for sentence-transformers v4.0.1.

View Full Changelog