pypi / sentence-transformers
sentence-transformers
What changed in sentence-transformers 5 to 6, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-28.
9 breaking1 security2 deprecations16 new APIs and options11 performance6 behavior and defaults38 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initsentence-transformers 682 changes
Breaking changes 9
Module paths must be relative and cannot contain .. path components, including when trust_remote_code=True.
Normalizes hierarchical token pooling outputs by default.
Output tokens, including protected tokens, are now normalized by default. Set normalize_embeddings=False to opt out; older saved configurations retain prior behavior.
Raises a clear error when ranges come from a single embedding.
Fails fast when a pool worker dies.
Excludes self-matches before taking top_k and follows only duplicate pairs in the transitive closure.
Inferring int8 or uint8 calibration ranges from a single vector now raises ValueError; encode representative calibration embeddings first or provide explicit ranges.
KV caching is disabled by default when supported to reduce unnecessary inference memory use; explicit use_cache overrides in config_kwargs remain honored.
Message content now follows each input's key order, which can change embeddings or scores.
Deprecations 2
Warns when models implicitly load in low precision on CPU.
The apply_softmax parameter is deprecated.
New APIs and options 16
Call after changing dispatch hooks or adding modules following the first inference call.
Merge compatible fine-tuned checkpoints without another training run; the returned model can be used, trained, and saved normally.
HierarchicalTokenPooling can use optional fastcluster linkage for faster clustering.
Adds opt-in fp32 computation for selected linear layers.
Forwards gradient checkpointing options to Transformers.
Select CrossEncoder linear layers to compute in FP32, reducing BF16 score ties while keeping a reduced-precision backbone.
Can be passed through processing_kwargs.
Adds model merging via mergekit for all archetypes.
Merge compatible fine-tuned checkpoints without another training run; the returned model can be used, trained, and saved normally.
Accepts a string main_score_function.
Merge compatible fine-tuned checkpoints without another training run; the returned model can be used, trained, and saved normally.
Supports probability targets and matches inputs to the classifier dtype.
Adds SlideOn and mSlideOn to the pretrained models.
Merge compatible fine-tuned checkpoints without another training run; the returned model can be used, trained, and saved normally.
Schedules the regularizer weights of every SpladeLoss.
Accepts dictionary configurations.
Performance 11
Uses sorted suffix reductions with linear intermediate storage.
Removes invalid anchor-positive pairs before constructing triplets, reducing memory to quadratic for paired labels.
Uses quadratic intermediate memory instead of constructing cubic distance and mask tensors, and corrects a gradient issue when selected negative distances tie.
Avoids redundant DDP synchronization during cached-loss replay.
Uses sorted suffix reductions with linear intermediate storage.
Computes CoSENT ranking loss with linear-memory suffix reductions.
Fixes memory use for long query batches.
Score blocks are budgeted using both query and document token counts, reducing memory use for long query batches.
With huggingface_hub>=1.26.0, loading resolves the requested branch or tag to a commit once and reuses it across component downloads, reducing repeated Hub requests.
CPU cosine semantic_search is faster by normalizing each corpus chunk once.
Handles an empty list corpus and speeds up CPU search by normalizing each corpus chunk once.
Behavior and default changes 6
During DDP training, evaluators automatically share encode and predict work across training processes; rank zero combines predictions and computes metrics.
Accepts fractional pool_factor values for finer control over compression.
huggingface_hub 2.x is supported; the Hub 1.3.0 minimum is retained.
CSR training now supports k_aux=0.
Treats a string positive or negative as one document.
A single input can contain multiple items per modality.
Fixes and other changes 38
Drops communities whose centre was already claimed.
Checkpoint restoration now works for compiled models, including best-checkpoint loading.
Honors the progress-bar option.
Keeps the 4k latents off the dead-latent mask and compares reconstructions with raw input when normalize=True.
Applies per-dataset prompts and losses when a DatasetDict is reused.
Validates Dense activation classes before loading.
Keeps string features whole when output_value=None.
Keeps pairs that cross the top-k cutoff.
Only truncates sentence embeddings and truncates per-column teacher labels.
Fixes mean pooling precision and excludes flattened CLS prompts correctly.
Uses the supplied CrossEncoder for hard-negative filtering when only min_score is set.
Validates model paths before loading.
Validates paired sentence counts.
Worker exceptions reach the caller, terminated workers are detected while polling, and worker tensor outputs are moved to CPU before queueing.
Forwards advertised module kwargs during encoding.
Fixes loading Normalize modules at the model root.
Normalizes a single sparse embedding as one vector and supports non-default dtypes.
Counts rank positions from one and stabilizes position weights for long ranking lists.
Improves FP16/BF16 mean and weighted-mean arithmetic, corrects weighted positions under left padding, and fixes prompt exclusion in flattened CLS fallback selection.
Python 3.14 is supported while Python 3.10 support is retained.
Return zero ranking loss when no label pairs are ordered, and preserve gradients with weighted log-sigmoid.
Keeps modules shared between routes shared after loading.
Keeps fusion order the same from run to run.
Reuses scalar calibration ranges across ragged multi-vector embeddings, accepts BF16 inputs, and corrects FP16 range arithmetic.
Fixes calibration when rescoring scalar-quantized embeddings.
Optimizes loss weights, spans every objective's steps in the learning-rate schedule, and warns that a DataLoader batch_sampler is not used.
Supports repeated evaluation with iterator-backed evaluators.
Uses the corpus model and embeddings during evaluation.
Prevents new sparse search corpora from sharing an index name.
Corrects normalization of single sparse vectors and sparse matrices with non-default dtypes or low-precision values.
Sizes weights by the vocabulary size.
Accepts duplicate expected translation text.
Evaluates the main similarity function.
Pads batches with no known tokens and honors the sequence length limit.
Corrected load_audio_from_video routing in chat templates.
Video-frame URLs without recognizable image extensions need an explicit frame wrapper to remain one video.
PyLate prefixes are now prepended to saved prompt text, so checkpoints trained with both encode the marker they were trained with.
Router.preprocess now forwards task to routed modules, enabling task-dependent preprocessing such as length caps, query expansion, and the chat-template task keyword.
sentence-transformers 51 changes
Security 1
sentence-transformers local model loading bypasses trust_remote_code and executes custom Python