Sentence Transformers

https://www.sbert.net
Admin
A Python framework for state-of-the-art sentence, cross, and sparse encoder models, enabling easy...
Tokens:777,056
Snippets:4,828
Trust Score:9.4
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install qdrant-client

Source: https://www.sbert.net/examples/sparse_encoder/applications/semantic_search/README.html

Install the Qdrant Python client, a prerequisite for running the semantic search example.

```bash
pip install qdrant-client

```

--------------------------------

### Install OpenSearch Python client

Source: https://www.sbert.net/examples/sparse_encoder/applications/semantic_search/README.html

Install the OpenSearch Python client, required for the semantic search example.

```bash
pip install opensearch-py
```

--------------------------------

### Install Elasticsearch Python client

Source: https://www.sbert.net/examples/sparse_encoder/applications/semantic_search/README.html

Install the Elasticsearch Python client, a prerequisite for running the semantic search example.

```bash
pip install elasticsearch

```

--------------------------------

### Install splade-index with pip

Source: https://www.sbert.net/examples/sparse_encoder/applications/semantic_search/README.html

Install the splade-index Python package. Required before running the example script.

```bash
pip install splade-index

```

--------------------------------

### Finetune with SentenceTransformerTrainer (v3.x)

Source: https://www.sbert.net/docs/migration_guide.html

Shows the v3.x recommended way to finetune a SentenceTransformer model using SentenceTransformerTrainer. This is the first example in the migration guide, demonstrating the basic training loop.

```python
# Finetune the model
trainer = SentenceTransformerTrainer(
    model=model,
    args=args,
    train_dataset=train_dataset,
    loss=loss,
)
trainer.train()
```

--------------------------------

### Install sentence-transformers with video extra

Source: https://www.sbert.net/docs/installation.html

Installs the main branch with the video extra for video support.

```bash
pip install -U "sentence-transformers[video] @ git+https://github.com/huggingface/sentence-transformers.git"
```

--------------------------------

### Install sentence-transformers with OpenVINO extra

Source: https://www.sbert.net/docs/installation.html

Installs the main branch with the openvino extra for OpenVINO support.

```bash
pip install -U "sentence-transformers[openvino] @ git+https://github.com/huggingface/sentence-transformers.git"
```

--------------------------------

### Install sentence-transformers with audio extra

Source: https://www.sbert.net/docs/installation.html

Installs the main branch with the audio extra for audio support.

```bash
pip install -U "sentence-transformers[audio] @ git+https://github.com/huggingface/sentence-transformers.git"
```

--------------------------------

### Install sentence-transformers from source (default)

Source: https://www.sbert.net/docs/installation.html

Installs the latest main branch of sentence-transformers from GitHub.

```bash
pip install git+https://github.com/huggingface/sentence-transformers.git
```

--------------------------------

### Install sentence-transformers with OpenVINO support

Source: https://www.sbert.net/docs/installation.html

Installs sentence-transformers with OpenVINO support.

```bash
pip install -U "sentence-transformers[openvino]"
```

--------------------------------

### Install sentence-transformers with dev extra

Source: https://www.sbert.net/docs/installation.html

Installs the main branch with the dev extra for development.

```bash
pip install -U "sentence-transformers[dev] @ git+https://github.com/huggingface/sentence-transformers.git"
```

--------------------------------

### Install sentence-transformers with train extra

Source: https://www.sbert.net/docs/installation.html

Installs the main branch with the train extra for training support.

```bash
pip install -U "sentence-transformers[train] @ git+https://github.com/huggingface/sentence-transformers.git"
```

--------------------------------

### Install sentence-transformers with dev extra

Source: https://www.sbert.net/docs/installation.html

Installs sentence-transformers with development dependencies for contributing.

```bash
pip install -U "sentence-transformers[dev]"
```

--------------------------------

### Install optuna backend

Source: https://www.sbert.net/examples/sentence_transformer/training/hpo/README.html

Install the hyperparameter search backend of choice. The command shows the package names for optuna, sigopt, wandb, and ray[tune].

```bash
pip install optuna/sigopt/wandb/ray[tune]

```

--------------------------------

### Train with CachedMultipleNegativesSymmetricRankingLoss

Source: https://www.sbert.net/docs/package_reference/sentence_transformer/losses.html

Example of using CachedMultipleNegativesSymmetricRankingLoss with a SentenceTransformer model and a dataset of anchor-positive pairs. The loss is passed to SentenceTransformerTrainer and training is started.

```python
from sentence_transformers import SentenceTransformer, SentenceTransformerTrainer, losses
from datasets import Dataset

model = SentenceTransformer("microsoft/mpnet-base")
train_dataset = Dataset.from_dict({
    "anchor": ["It's nice weather outside today.", "He drove to work."],
    "positive": ["It's so sunny.", "He took the car to the office."],
})
loss = losses.CachedMultipleNegativesSymmetricRankingLoss(model, mini_batch_size=32)

trainer = SentenceTransformerTrainer(
    model=model,
    train_dataset=train_dataset,
    loss=loss,
)
trainer.train()

```

--------------------------------

### Example route_mappings dictionary

Source: https://www.sbert.net/docs/package_reference/base/modules.html

Shows how to configure route_mappings with exact matches, wildcards for task or modality, and a catch-all rule. Use this to route based on (task, modality) combinations with priority order.

```python
{
    # Exact matches (highest priority)
    ("query", "text"): "efficient_text_encoder",
    ("document", "text"): "powerful_text_encoder",

    # Task with any modality
    ("query", None): "query_encoder",  # All query tasks

    # Any task with specific modality
    (None, "image"): "image_encoder",  # All image inputs
    (None, ("text", "image")): "multimodal_encoder",  # Multimodal inputs

    # Catch-all (lowest priority)
    (None, None): "default_encoder",
}
```

--------------------------------

### fullname example

Source: https://www.sbert.net/docs/package_reference/util/misc.html

Shows how to get the full dotted path of a loss class instance using fullname(). Requires a SentenceTransformer model and a MultipleNegativesRankingLoss instance.

```python
>>> from sentence_transformers.sentence_transformer.losses import MultipleNegativesRankingLoss
>>> from sentence_transformers import SentenceTransformer
>>> from sentence_transformers.util import fullname
>>> model = SentenceTransformer('sentence-transformers/all-MiniLM-L6-v2')
>>> loss = MultipleNegativesRankingLoss(model)
>>> fullname(loss)
'sentence_transformers.sentence_transformer.losses.multiple_negatives_ranking.MultipleNegativesRankingLoss'
```

--------------------------------

### Install trackio for training log tracking

Source: https://www.sbert.net/docs/installation.html

Installs trackio for tracking training logs. Recommended when using Weights and Biases or Trackio.

```bash
pip install trackio
```

--------------------------------

### Initialize MultiVectorEncoderTrainingArguments

Source: https://www.sbert.net/docs/multi_vector_encoder/training_overview.html

Example of creating a MultiVectorEncoderTrainingArguments instance with required and optional parameters. The output_dir is required; other parameters are optional. The example sets batch_sampler to BatchSamplers.NO_DUPLICATES for losses using in-batch negatives, and notes that fp16 should be True if the GPU doesn't support BF16, while bf16 should be True if the GPU supports it. The run_name is used in W&B if wandb is installed.

```python
args = MultiVectorEncoderTrainingArguments(
    # Required parameter:
    output_dir="models/multivector-ModernBERT-base-msmarco",
    # Optional training parameters:
    num_train_epochs=1,
    per_device_train_batch_size=32,
    per_device_eval_batch_size=32,
    learning_rate=3e-5,
    warmup_steps=0.05,
    fp16=False,  # Set to True if your GPU doesn't support BF16
    bf16=True,  # Set to True if you have a GPU that supports BF16
    batch_sampler=BatchSamplers.NO_DUPLICATES,  # losses that use "in-batch negatives" benefit from no duplicates
    # Optional tracking/debugging parameters:
    eval_strategy="steps",
    eval_steps=0.1,
    save_strategy="steps",
    save_steps=0.1,
    save_total_limit=2,
    logging_steps=0.01,
    run_name="multivector-ModernBERT-base-msmarco",  # Will be used in W&B if `wandb` is installed
)

```

--------------------------------

### Create CrossEncoder with CrossEncoderModelCardData

Source: https://www.sbert.net/docs/package_reference/cross_encoder/cross_encoder.html

Create a CrossEncoder with a CrossEncoderModelCardData instance to populate the model card. The example sets model_id, train_datasets, eval_datasets, license, and language. Install codecarbon to automatically track carbon emission usage and include it in model cards.

```python
>>> model = CrossEncoder(
...     "microsoft/mpnet-base",
...     model_card_data=CrossEncoderModelCardData(
...         model_id="tomaarsen/ce-mpnet-base-allnli",
...         train_datasets=[{"name": "SNLI", "id": "stanfordnlp/snli"}, {"name": "MultiNLI", "id": "nyu-mll/multi_nli"}],
...         eval_datasets=[{"name": "SNLI", "id": "stanfordnlp/snli"}, {"name": "MultiNLI", "id": "nyu-mll/multi_nli"}],
...         license="apache-2.0",
...         language="en",
...     ),
... )
```

--------------------------------

### Prepare Router training dataset with query and document keys

Source: https://www.sbert.net/docs/migration_guide.html

Creates a Hugging Face Dataset with 'query' and 'answer' columns, then maps them to 'query' and 'document' keys using a mapper function. The output shows the mapped example with 'question' and 'answer' keys.

```python
train_dataset = Dataset.from_dict({
    "query": [
        "is toprol xl the same as metoprolol?",
        "are eyes always the same size?",
    ],
    "answer": [
        "Metoprolol succinate is also known by the brand name Toprol XL.",
        "The eyes are always the same size from birth to death.",
    ],
})
train_dataset = train_dataset.map(mapper)
print(train_dataset[0])
```

```python
{
    "question": "is toprol xl the same as metoprolol?",
    "answer": "Metoprolol succinate is also known by the brand name Toprol XL."
}
```

--------------------------------

### Asymmetric search example: query and passage

Source: https://www.sbert.net/examples/sentence_transformer/unsupervised_learning/query_generation/README.html

Illustrates the asymmetric semantic search setup: a short query (e.g., "What is Python?") is paired with a longer passage that provides the answer. This is the target format for the synthetic query generation approach.

```text
query: What is Python?
passage to retrieve: Python is an interpreted, high-level and general-purpose programming language. Python's design philosophy emphasizes code readability with its notable use of significant whitespace. Its language constructs and object-oriented approach aim to help programmers write clear, logical code for small and large-scale projects.

```

--------------------------------

### Create SentenceTransformer with SentenceTransformerModelCardData

Source: https://www.sbert.net/docs/package_reference/sentence_transformer/SentenceTransformer.html

Create a SentenceTransformer with a SentenceTransformerModelCardData instance to customize the model card metadata. The example sets model_id, train_datasets, eval_datasets, license, and language. Install codecarbon to automatically track carbon emission usage and include it in your model cards.

```python
>>> model = SentenceTransformer(
...     "microsoft/mpnet-base",
...     model_card_data=SentenceTransformerModelCardData(
...         model_id="tomaarsen/sbert-mpnet-base-allnli",
...         train_datasets=[{"name": "SNLI", "id": "stanfordnlp/snli"}, {"name": "MultiNLI", "id": "nyu-mll/multi_nli"}],
...         eval_datasets=[{"name": "SNLI", "id": "stanfordnlp/snli"}, {"name": "MultiNLI", "id": "nyu-mll/multi_nli"}],
...         license="apache-2.0",
...         language="en",
...     ),
... )
```

--------------------------------

### Initialize SparseEncoderTrainingArguments

Source: https://www.sbert.net/docs/sparse_encoder/training_overview.html

Initializes SparseEncoderTrainingArguments with required output_dir and optional training and tracking parameters. The example sets fp16=True and bf16=False, noting to adjust based on GPU support. It also uses BatchSamplers.NO_DUPLICATES for in-batch negatives and sets run_name for W&B if installed.

```python
args = SparseEncoderTrainingArguments(
    # Required parameter:
    output_dir="models/splade-distilbert-base-uncased-nq",
    # Optional training parameters:
    num_train_epochs=1,
    per_device_train_batch_size=16,
    per_device_eval_batch_size=16,
    learning_rate=2e-5,
    warmup_steps=0.1,
    fp16=True,  # Set to False if you get an error that your GPU can't run on FP16
    bf16=False,  # Set to True if you have a GPU that supports BF16
    batch_sampler=BatchSamplers.NO_DUPLICATES,  # losses that use "in-batch negatives" benefit from no duplicates
    # Optional tracking/debugging parameters:
    eval_strategy="steps",
    eval_steps=0.1,
    save_strategy="steps",
    save_steps=0.1,
    save_total_limit=2,
    logging_steps=0.01,
    run_name="splade-distilbert-base-uncased-nq",  # Will be used in W&B if `wandb` is installed
)
```

--------------------------------

### Install trackio for training log tracking

Source: https://www.sbert.net/docs/installation.html

Recommended for tracking training logs with Weights and Biases or Trackio. You must also add the module name to 'report_to' in Training Arguments.

```bash
uv pip install trackio

```

--------------------------------

### Convert similarity function name to callable and compute scores

Source: https://www.sbert.net/docs/package_reference/util/similarity.html

Demonstrates converting a similarity function name (e.g., "cosine") to a callable using SimilarityFunction.to_similarity_fn(), then applying it to embeddings to get a similarity matrix. The example output shows a 2x2 tensor of similarity scores.

```python
>>> similarity_fn = SimilarityFunction.to_similarity_fn("cosine")
>>> similarity_scores = similarity_fn(embeddings1, embeddings2)
>>> similarity_scores
tensor([[0.3952, 0.0554],
        [0.0992, 0.1570]])
```

--------------------------------

### Install sentence-transformers with image extra

Source: https://www.sbert.net/docs/installation.html

Installs the main branch with the image extra for image support.

```bash
pip install -U "sentence-transformers[image] @ git+https://github.com/huggingface/sentence-transformers.git"
```

--------------------------------

### CrossEncoderRerankingEvaluator with GooAQ and hard negatives

Source: https://www.sbert.net/docs/cross_encoder/training_overview.html

Loads a cross-encoder model and the GooAQ dataset, mines hard negatives with an embedding model, and initializes a CrossEncoderRerankingEvaluator. The example shows how to run evaluation and includes sample output metrics (MAP, MRR@10, NDCG@10). Requires installing faiss-gpu or faiss-cpu for use_faiss=True.

```python
from datasets import load_dataset
from sentence_transformers import SentenceTransformer
from sentence_transformers.cross_encoder import CrossEncoder
from sentence_transformers.cross_encoder.evaluation import CrossEncoderRerankingEvaluator
from sentence_transformers.util import mine_hard_negatives

# Load a model
model = CrossEncoder("cross-encoder/ms-marco-MiniLM-L6-v2")

# Load the GooAQ dataset: https://huggingface.co/datasets/sentence-transformers/gooaq
full_dataset = load_dataset("sentence-transformers/gooaq", split=f"train").select(range(100_000))
dataset_dict = full_dataset.train_test_split(test_size=1_000, seed=12)
train_dataset = dataset_dict["train"]
eval_dataset = dataset_dict["test"]
print(eval_dataset)
"""
Dataset({
    features: ['question', 'answer'],
    num_rows: 1000
})
"""

# Mine hard negatives using a very efficient embedding model
embedding_model = SentenceTransformer("sentence-transformers/static-retrieval-mrl-en-v1", device="cpu")
hard_eval_dataset = mine_hard_negatives(
    eval_dataset,
    embedding_model,
    corpus=full_dataset["answer"],  # Use the full dataset as the corpus
    num_negatives=50,  # How many negatives per question-answer pair
    batch_size=4096,  # Use a batch size of 4096 for the embedding model
    output_format="n-tuple",  # The output format is (query, positive, negative1, negative2, ...) for the evaluator
    include_positives=True,  # Key: Include the positive answer in the list of negatives
    use_faiss=True,  # Using FAISS is recommended to keep memory usage low (pip install faiss-gpu or pip install faiss-cpu)
)
print(hard_eval_dataset)
"""
Dataset({
    features: ['question', 'answer', 'negative_1', 'negative_2', 'negative_3', 'negative_4', 'negative_5', 'negative_6', 'negative_7', 'negative_8', 'negative_9', 'negative_10', 'negative_11', 'negative_12', 'negative_13', 'negative_14', 'negative_15', 'negative_16', 'negative_17', 'negative_18', 'negative_19', 'negative_20', 'negative_21', 'negative_22', 'negative_23', 'negative_24', 'negative_25', 'negative_26', 'negative_27', 'negative_28', 'negative_29', 'negative_30', 'negative_31', 'negative_32', 'negative_33', 'negative_34', 'negative_35', 'negative_36', 'negative_37', 'negative_38', 'negative_39', 'negative_40', 'negative_41', 'negative_42', 'negative_43', 'negative_44', 'negative_45', 'negative_46', 'negative_47', 'negative_48', 'negative_49', 'negative_50'],
    num_rows: 1000
})
"""

reranking_evaluator = CrossEncoderRerankingEvaluator(
    samples=[
        {
            "query": sample["question"],
            "positive": [sample["answer"]],
            "documents": [sample[column_name] for column_name in hard_eval_dataset.column_names[2:]],
        }
        for sample in hard_eval_dataset
    ],
    batch_size=32,
    name="gooaq-dev",
)
# You can run evaluation like so
results = reranking_evaluator(model)
"""
CrossEncoderRerankingEvaluator: Evaluating the model on the gooaq-dev dataset:
Queries:  1000     Positives: Min 1.0, Mean 1.0, Max 1.0   Negatives: Min 49.0, Mean 49.1, Max 50.0
          Base  -> Reranked
MAP:      53.28 -> 67.28
MRR@10:   52.40 -> 66.65
NDCG@10:  59.12 -> 71.35
"""
# {'gooaq-dev_map': 0.6728370126462222, 'gooaq-dev_mrr@10': 0.6665190476190477, 'gooaq-dev_ndcg@10': 0.7135068904582963, 'gooaq-dev_base_map': 0.5327714512001362, 'gooaq-dev_base_mrr@10': 0.5239674603174603, 'gooaq-dev_base_ndcg@10': 0.5912299141913905}
```

--------------------------------

### Semantic search with Elasticsearch using SparseEncoder

Source: https://www.sbert.net/examples/sparse_encoder/applications/semantic_search/README.html

Complete example that loads the natural-questions dataset, encodes documents and queries with SparseEncoder, and performs interactive semantic search via Elasticsearch. Requires Elasticsearch running locally and the elasticsearch Python client installed. The loop reuses the corpus index after the first search and prompts for new queries.

```python
import time

from datasets import load_dataset

from sentence_transformers import SparseEncoder
from sentence_transformers.sparse_encoder.search_engines import semantic_search_elasticsearch

# 1. Load the natural-questions dataset with 100K answers
dataset = load_dataset("sentence-transformers/natural-questions", split="train")
num_docs = 10_000
corpus = dataset["answer"][:num_docs]

# 2. Come up with some queries
queries = dataset["query"][:2]

# 3. Load the model
sparse_model = SparseEncoder("naver/splade-cocondenser-ensembledistil")

# 4. Encode the corpus
print("Start encoding corpus...")
start_time = time.time()
corpus_embeddings = sparse_model.encode_document(
    corpus, convert_to_sparse_tensor=True, batch_size=16, show_progress_bar=True
)
corpus_embeddings_decoded = sparse_model.decode(corpus_embeddings)
print(f"Corpus encoding time: {time.time() - start_time:.6f} seconds")

corpus_index = None
while True:
    # 5. Encode the queries using the full precision
    start_time = time.time()
    query_embeddings = sparse_model.encode_query(queries, convert_to_sparse_tensor=True)
    query_embeddings_decoded = sparse_model.decode(query_embeddings)
    print(f"Encoding time: {time.time() - start_time:.6f} seconds")

    # 6. Perform semantic search using Elasticsearch
    results, search_time, corpus_index = semantic_search_elasticsearch(
        query_embeddings_decoded,
        corpus_embeddings_decoded=corpus_embeddings_decoded if corpus_index is None else None,
        corpus_index=corpus_index,
        top_k=5,
        output_index=True,
    )

    # 7. Output the results
    print(f"Search time: {search_time:.6f} seconds")
    for query, result in zip(queries, results):
        print(f"Query: {query}")
        for entry in result:
            print(f"(Score: {entry['score']:.4f}) {corpus[entry['corpus_id']]}, corpus_id: {entry['corpus_id']}")
        print("")

    # 8. Prompt for more queries
    queries = [input("Please enter a question: ")]

```
Tokens:
Raw