# huggingface/sentence-transformers architecture

> Architecture diagram of the GitHub repository huggingface/sentence-transformers, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/huggingface/sentence-transformers
- Repository: https://github.com/huggingface/sentence-transformers

## Overview

Sentence Transformers is a Python framework for producing dense, sparse, and token-level embeddings, scoring text pairs with rerankers, and training or evaluating these model families. The principal workflow is user input to a model’s encode or predict operation, then embeddings or scores; similarity and retrieval utilities support downstream search tasks. The graph also preserves the documented training and evaluation branches. Relationships are based on the README and supplied source excerpts/index; unsampled implementation details are not inferred.

Main entry points: [`sentence_transformers/sentence_transformer/model.py`](https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/sentence_transformer/model.py) (SentenceTransformer), [`sentence_transformers/cross_encoder/model.py`](https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/cross_encoder/model.py) (CrossEncoder), [`sentence_transformers/sparse_encoder/model.py`](https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/sparse_encoder/model.py) (SparseEncoder), [`sentence_transformers/multi_vector_encoder/model.py`](https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/multi_vector_encoder/model.py) (MultiVectorEncoder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dense["Dense embeddings"]
  node_sentence_model["SentenceTransformer<br/>[model.py]"]
  node_dense_vectors["Dense embeddings"]
  node_similarity["Similarity functions<br/>[similarity.py]"]
  node_retrieval["Retrieval utilities<br/>[retrieval.py]"]
end

subgraph group_rerank["Cross-encoder reranking"]
  node_cross_model["CrossEncoder<br/>[model.py]"]
  node_pair_scores["Pair scores"]
end

subgraph group_sparse["Sparse embeddings"]
  node_sparse_model["SparseEncoder<br/>[model.py]"]
  node_sparse_vectors["Sparse embeddings"]
  node_sparse_search["Sparse search engines<br/>[search_engines.py]"]
end

subgraph group_multi["Multi-vector retrieval"]
  node_multi_model["MultiVectorEncoder<br/>[model.py]"]
  node_token_vectors["Token embeddings"]
  node_late_score["Late-interaction scoring<br/>[colbert.py]"]
end

subgraph group_train_eval["Training and evaluation"]
  node_dense_trainer["SentenceTransformer trainer<br/>[trainer.py]"]
  node_cross_trainer["CrossEncoder trainer<br/>[trainer.py]"]
  node_sparse_trainer["SparseEncoder trainer<br/>[trainer.py]"]
  node_multi_trainer["MultiVectorEncoder trainer<br/>[trainer.py]"]
  node_dense_eval["Embedding and retrieval evaluators"]
  node_cross_eval["Reranking evaluators<br/>[reranking.py]"]
  node_sparse_eval["Sparse evaluators"]
  node_multi_eval["Multi-vector evaluators"]
end

node_user(("Application user"))

node_user -->|"encodes text"| node_sentence_model
node_sentence_model -->|"returns embeddings"| node_dense_vectors
node_user -->|"compares vectors"| node_similarity
node_user -->|"runs search"| node_retrieval
node_user -->|"scores text pairs"| node_cross_model
node_cross_model -->|"returns scores"| node_pair_scores
node_user -->|"encodes text"| node_sparse_model
node_sparse_model -->|"returns embeddings"| node_sparse_vectors
node_user -.->|"searches sparse vectors"| node_sparse_search
node_user -->|"encodes query and document"| node_multi_model
node_multi_model -->|"returns token vectors"| node_token_vectors
node_user -->|"scores late interaction"| node_late_score
node_user -->|"trains dense model"| node_dense_trainer
node_user -->|"trains reranker"| node_cross_trainer
node_user -->|"trains sparse model"| node_sparse_trainer
node_user -->|"trains multi-vector model"| node_multi_trainer
node_user -->|"evaluates retrieval"| node_dense_eval
node_user -->|"evaluates reranking"| node_cross_eval
node_user -->|"evaluates sparse retrieval"| node_sparse_eval
node_user -->|"evaluates retrieval"| node_multi_eval

click node_sentence_model "https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/sentence_transformer/model.py"
click node_similarity "https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/util/similarity.py"
click node_retrieval "https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/util/retrieval.py"
click node_cross_model "https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/cross_encoder/model.py"
click node_sparse_model "https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/sparse_encoder/model.py"
click node_sparse_search "https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/sparse_encoder/search_engines.py"
click node_multi_model "https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/multi_vector_encoder/model.py"
click node_late_score "https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/multi_vector_encoder/scoring/colbert.py"
click node_dense_trainer "https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/sentence_transformer/trainer.py"
click node_cross_trainer "https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/cross_encoder/trainer.py"
click node_sparse_trainer "https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/sparse_encoder/trainer.py"
click node_multi_trainer "https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/multi_vector_encoder/trainer.py"
click node_dense_eval "https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/sentence_transformer/evaluation/information_retrieval.py"
click node_cross_eval "https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/cross_encoder/evaluation/reranking.py"
click node_sparse_eval "https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/sparse_encoder/evaluation/sparse_information_retrieval.py"
click node_multi_eval "https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/multi_vector_encoder/evaluation/information_retrieval.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sentence_model,node_dense_vectors,node_similarity,node_retrieval,node_user toneBlue
class node_cross_model,node_pair_scores toneAmber
class node_sparse_model,node_sparse_vectors,node_sparse_search toneMint
class node_multi_model,node_token_vectors,node_late_score toneRose
class node_dense_trainer,node_cross_trainer,node_sparse_trainer,node_multi_trainer,node_dense_eval,node_cross_eval,node_sparse_eval,node_multi_eval toneIndigo
```

## Components

### Dense embeddings

- [SentenceTransformer](https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/sentence_transformer/model.py): `sentence_transformers/sentence_transformer/model.py`
- **Dense embeddings**
- [Similarity functions](https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/util/similarity.py): `sentence_transformers/util/similarity.py`
- [Retrieval utilities](https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/util/retrieval.py): `sentence_transformers/util/retrieval.py`

### Cross-encoder reranking

- [CrossEncoder](https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/cross_encoder/model.py): `sentence_transformers/cross_encoder/model.py`
- **Pair scores**

### Sparse embeddings

- [SparseEncoder](https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/sparse_encoder/model.py): `sentence_transformers/sparse_encoder/model.py`
- **Sparse embeddings**
- [Sparse search engines](https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/sparse_encoder/search_engines.py): `sentence_transformers/sparse_encoder/search_engines.py`

### Multi-vector retrieval

- [MultiVectorEncoder](https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/multi_vector_encoder/model.py): `sentence_transformers/multi_vector_encoder/model.py`
- **Token embeddings**
- [Late-interaction scoring](https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/multi_vector_encoder/scoring/colbert.py): `sentence_transformers/multi_vector_encoder/scoring/colbert.py`

### Training and evaluation

- [SentenceTransformer trainer](https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/sentence_transformer/trainer.py): `sentence_transformers/sentence_transformer/trainer.py`
- [CrossEncoder trainer](https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/cross_encoder/trainer.py): `sentence_transformers/cross_encoder/trainer.py`
- [SparseEncoder trainer](https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/sparse_encoder/trainer.py): `sentence_transformers/sparse_encoder/trainer.py`
- [MultiVectorEncoder trainer](https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/multi_vector_encoder/trainer.py): `sentence_transformers/multi_vector_encoder/trainer.py`
- [Embedding and retrieval evaluators](https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/sentence_transformer/evaluation/information_retrieval.py): `sentence_transformers/sentence_transformer/evaluation/information_retrieval.py`
- [Reranking evaluators](https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/cross_encoder/evaluation/reranking.py): `sentence_transformers/cross_encoder/evaluation/reranking.py`
- [Sparse evaluators](https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/sparse_encoder/evaluation/sparse_information_retrieval.py): `sentence_transformers/sparse_encoder/evaluation/sparse_information_retrieval.py`
- [Multi-vector evaluators](https://github.com/huggingface/sentence-transformers/blob/main/sentence_transformers/multi_vector_encoder/evaluation/information_retrieval.py): `sentence_transformers/multi_vector_encoder/evaluation/information_retrieval.py`

### Other components

- **Application user**

## Connections

- Application user → SentenceTransformer: encodes text (evidence: `README.md`)
- SentenceTransformer → Dense embeddings: returns embeddings (evidence: `README.md`)
- Application user → Similarity functions: compares vectors (evidence: `README.md`)
- Application user → Retrieval utilities: runs search (evidence: `README.md`)
- Application user → CrossEncoder: scores text pairs (evidence: `README.md`)
- CrossEncoder → Pair scores: returns scores (evidence: `README.md`)
- Application user → SparseEncoder: encodes text (evidence: `README.md`)
- SparseEncoder → Sparse embeddings: returns embeddings (evidence: `README.md`)
- Application user → Sparse search engines: searches sparse vectors
- Application user → MultiVectorEncoder: encodes query and document (evidence: `README.md`)
- MultiVectorEncoder → Token embeddings: returns token vectors (evidence: `README.md`)
- Application user → Late-interaction scoring: scores late interaction (evidence: `README.md`)
- Application user → SentenceTransformer trainer: trains dense model (evidence: `README.md`)
- Application user → CrossEncoder trainer: trains reranker (evidence: `README.md`)
- Application user → SparseEncoder trainer: trains sparse model (evidence: `README.md`)
- Application user → MultiVectorEncoder trainer: trains multi-vector model (evidence: `README.md`)
- Application user → Embedding and retrieval evaluators: evaluates retrieval (evidence: `README.md`)
- Application user → Reranking evaluators: evaluates reranking (evidence: `README.md`)
- Application user → Sparse evaluators: evaluates sparse retrieval (evidence: `README.md`)
- Application user → Multi-vector evaluators: evaluates retrieval (evidence: `README.md`)
