●Change8

Migrating to sentence-transformers v4.0.2

Version v4.0.2 introduces 2 breaking changes. This guide details how to update your code.

Released: 4/3/2025

2
Breaking Changes
3
Migration Steps
5
Affected Symbols

⚠️ Check Your Code

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

CrossEncoderSentenceTransformerget_device_nameFSDP loss wrapperpush_to_hub

Breaking Changes

●Issue #1

CrossEncoder maximum sequence length is now limited to the minimum of the tokenizer's `model_max_length` and the config `max_position_embeddings`. Models like `BAAI/bge-reranker-base` will report 512 instead of 514, so callers must truncate inputs to \u2264512 tokens.

●Issue #2

In distributed training the model is automatically placed on the CUDA device that matches the local rank. Code that assumed the model was always on GPU 0 may need to query the device or adjust manual placement.

Migration Steps

  1. 1
    If you rely on longer input sequences with CrossEncoder, truncate inputs to the new `model.max_length` (typically 512).
  2. 2
    When using distributed training, verify that any custom device placement logic accounts for the model now being on the local-rank CUDA device.
  3. 3
    No other code changes are required.

Release Summary

Version 4.0.2 introduces safer max-length handling for CrossEncoder models and improves distributed training device placement, while fixing typing, FSDP, and documentation issues.

Need More Details?

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

View Full Changelog