●Change8

v4.0.2

Breaking Changes
📦 sentence-transformersView on GitHub →
⚠ 2 breaking✨ 4 features🐛 7 fixes🔧 5 symbols

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.

⚠️ Breaking Changes

  • 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.
  • 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. If you rely on longer input sequences with CrossEncoder, truncate inputs to the new `model.max_length` (typically 512).
  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. No other code changes are required.

✨ New Features

  • Safer CrossEncoder max-length handling using the minimum of tokenizer `model_max_length` and config `max_position_embeddings`.
  • Default device placement in multi-GPU distributed training now uses the CUDA device corresponding to the local rank, reducing VRAM pressure on GPU 0.
  • Typing support for `SentenceTransformer` methods outside of `encode` restored, improving IDE assistance.
  • Improved FSDP training compatibility by ensuring the wrapped model is always attached to the loss class instance.

🐛 Bug Fixes

  • Fixed typing issues for `SentenceTransformer` class outside of the `encode` method.
  • Corrected faulty "only if model is wrapped" check for FSDP training.
  • Fixed device assignment in `get_device_name` for distributed training.
  • Resolved several broken documentation links and redirects.
  • Updated examples and added missing docstrings for `push_to_hub`.
  • Adjusted .htaccess in-line comments to avoid issues.
  • CI pipeline adjustments.

🔧 Affected Symbols

CrossEncoderSentenceTransformerget_device_nameFSDP loss wrapperpush_to_hub