●Change8

Migrating to sentence-transformers v5.1.1

Version v5.1.1 introduces 1 breaking change. This guide details how to update your code.

Released: 9/22/2025

1
Breaking Changes
5
Migration Steps
8
Affected Symbols

⚠️ Check Your Code

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

SentenceTransformer.encodeSentenceTransformer.get_model_kwargsCrossEncoderRerankingEvaluatormine_hard_negativesSparseEncoder evaluators (FLOPS calculation)InformationRetrievalEvaluatorlosses module import of SentenceTransformerforward method input handling

Breaking Changes

●Issue #1

SentenceTransformer.encode now raises a ValueError when called with keyword arguments that are not supported by the underlying model (e.g., using `normalize` instead of `normalize_embeddings`). This is a breaking change because previously such arguments were silently ignored. Fix by removing unsupported kwargs or using the correct parameter names; you can call `SentenceTransformer.get_model_kwargs()` to see which extra arguments are allowed.

Migration Steps

  1. 1
    Search your code for calls to `model.encode` that pass unsupported keyword arguments (e.g., `normalize`). Remove them or replace with the correct arguments such as `normalize_embeddings`.
  2. 2
    If you need to know which extra kwargs a model accepts, call `model.get_model_kwargs()` and adjust your calls accordingly.
  3. 3
    Review any usage of `CrossEncoderRerankingEvaluator` and ensure you are passing the `batch_size` argument if you rely on it.
  4. 4
    No code changes are required for the multi‑GPU fix, but be aware that embeddings are now moved to CPU before concatenation.
  5. 5
    If you rely on custom output directories for evaluators, you can now omit pre‑creating them; the library will create them automatically.

Release Summary

Version 5.1.1 adds explicit validation of unused kwargs in `encode`, introduces FLOPS metrics for SparseEncoder evaluators, supports Knowledgeable Passage Retriever models, and includes several bug fixes around batch size handling, multi‑GPU processing, and evaluator output paths.

Need More Details?

View the full release notes and all changes for sentence-transformers v5.1.1.

View Full Changelog