Skip to content
Back to search

sentence-transformers

State-of-the-Art Embeddings, Retrieval, and Reranking

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/huggingface/sentence-transformers with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/huggingface/sentence-transformers'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/huggingface--sentence-transformers/badge.svg)](/listings/huggingface--sentence-transformers)

HTML

<a href="/listings/huggingface--sentence-transformers"><img src="/api/listings/huggingface--sentence-transformers/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

We recommend **Python 3.10+**, **[PyTorch 2.2+](https://pytorch.org/get-started/locally/)**, and **[transformers v5.0+](https://github.com/huggingface/transformers)**.

pip install -U sentence-transformers

See [Installation](https://www.sbert.net/docs/installation.html) in the docs for uv, conda, source, and editable installs, CUDA setup, and extras (`[image]`, `[audio]`, `[video]`, `[train]`, `[onnx]`, `[openvino]`, `[dev]`).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 321 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <!--- BADGES: START --->
  2. [![HF Models](https://img.shields.io/badge/%F0%9F%A4%97-models-yellow)](https://huggingface.co/models?library=sentence-transformers)
  3. [![GitHub - License](https://img.shields.io/github/license/huggingface/sentence-transformers?logo=github&style=flat&color=green)][#github-license]
  4. [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/sentence-transformers?logo=pypi&style=flat&color=blue)][#pypi-package]
  5. [![PyPI - Package Version](https://img.shields.io/pypi/v/sentence-transformers?logo=pypi&style=flat&color=orange)][#pypi-package]
  6. [![Docs - GitHub.io](https://img.shields.io/static/v1?logo=github&style=flat&color=pink&label=docs&message=sentence-transformers)][#docs-package]
  7. <!-- [![PyPI - Downloads](https://img.shields.io/pypi/dm/sentence-transformers?logo=pypi&style=flat&color=green)][#pypi-package] -->
  8. <!--- BADGES: END --->
  9. # Sentence Transformers: Embeddings, Retrieval, and Reranking
  10. This framework provides an easy method to compute embeddings for accessing, using, and training state-of-the-art embedding and reranker models. It can be used to compute embeddings using Sentence Transformer models ([quickstart](https://sbert.net/docs/quickstart.html#sentence-transformer)), to calculate similarity scores using Cross-Encoder (a.k.a. reranker) models ([quickstart](https://sbert.net/docs/quickstart.html#cross-encoder)), to generate sparse embeddings using Sparse Encoder models ([quickstart](https://sbert.net/docs/quickstart.html#sparse-encoder)) or to compute token-level embeddings for ColBERT-style late-interaction retrieval using Multi-Vector Encoder models ([quickstart](https://sbert.net/docs/quickstart.html#multi-vector-encoder)). This unlocks a wide range of applications, including [semantic search](https://sbert.net/examples/sentence_transformer/applications/semantic-search/README.html), [semantic textual similarity](https://sbert.net/docs/sentence_transformer/usage/semantic_textual_similarity.html), and [paraphrase mining](https://sbert.net/examples/sentence_transformer/applications/paraphrase-mining/README.html).
  11. A wide selection of over [15,000 pre-trained Sentence Transformers models](https://huggingface.co/models?library=sentence-transformers) are available for immediate use on 🤗 Hugging Face, including many of the state-of-the-art models from the [Massive Text Embeddings Benchmark (MTEB) leaderboard](https://huggingface.co/spaces/mteb/leaderboard). Additionally, it is easy to train or finetune your own [embedding models](https://sbert.net/docs/sentence_transformer/training_overview.html), [reranker models](https://sbert.net/docs/cross_encoder/training_overview.html), [sparse encoder models](https://sbert.net/docs/sparse_encoder/training_overview.html) or [multi-vector encoder models](https://sbert.net/docs/multi_vector_encoder/training_overview.html) using Sentence Transformers, enabling you to create custom models for your specific use cases.
  12. For the **full documentation**, see **[www.SBERT.net](https://www.sbert.net)**.
  13. ## Installation
  14. We recommend **Python 3.10+**, **[PyTorch 2.2+](https://pytorch.org/get-started/locally/)**, and **[transformers v5.0+](https://github.com/huggingface/transformers)**.
  15. ```
  16. pip install -U sentence-transformers
  17. ```
  18. See [Installation](https://www.sbert.net/docs/installation.html) in the docs for uv, conda, source, and editable installs, CUDA setup, and extras (`[image]`, `[audio]`, `[video]`, `[train]`, `[onnx]`, `[openvino]`, `[dev]`).
  19. ## Getting Started
  20. See [Quickstart](https://www.sbert.net/docs/quickstart.html) in our documentation.
  21. Log in with `hf auth login` for higher Hugging Face Hub rate limits and access to private or gated models your account can read. See the [login instructions](https://www.sbert.net/docs/installation.html#log-in-to-hugging-face).
  22. ### Embedding Models
  23. First download a pretrained embedding a.k.a. Sentence Transformer model.
  24. ```python
  25. from sentence_transformers import SentenceTransformer
  26. model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")
  27. ```
  28. Then provide some texts to the model.
  29. ```python
  30. sentences = [
  31. "The weather is lovely today.",
  32. "It's so sunny outside!",
  33. "He drove to the stadium.",
  34. ]
  35. embeddings = model.encode(sentences)
  36. print(embeddings.shape)
  37. # => (3, 384)
  38. ```
  39. And that's already it. We now have numpy arrays with the embeddings, one for each text. We can use these to compute similarities.
  40. ```python
  41. similarities = model.similarity(embeddings, embeddings)
  42. print(similarities)
  43. # tensor([[1.0000, 0.6660, 0.1046],
  44. # [0.6660, 1.0000, 0.1411],
  45. # [0.1046, 0.1411, 1.0000]])
  46. ```
  47. ### Reranker Models
  48. First download a pretrained reranker a.k.a. Cross Encoder model.
  49. ```python
  50. from sentence_transformers import CrossEncoder
  51. # 1. Load a pretrained CrossEncoder model
  52. model = CrossEncoder("cross-encoder/ms-marco-MiniLM-L6-v2")
  53. ```
  54. Then provide some texts to the model.
  55. ```python
  56. # The texts for which to predict similarity scores
  57. query = "How many people live in Berlin?"
  58. passages = [
  59. "Berlin had a population of 3,520,031 registered inhabitants in an area of 891.82 square kilometers.",
  60. "Berlin has a yearly total of about 135 million day visitors, making it one of the most-visited cities in the European Union.",
  61. "In 2013 around 600,000 Berliners were registered in one of the more than 2,300 sport and fitness clubs.",
  62. ]
  63. # 2a. predict scores for pairs of texts
  64. scores = model.predict([(query, passage) for passage in passages])
  65. print(scores)
  66. # => [8.607139 5.506266 6.352977]
  67. ```
  68. And we're good to go. You can also use [`model.rank`](https://sbert.net/docs/package_reference/cross_encoder/model.html#sentence_transformers.cross_encoder.model.CrossEncoder.rank) to avoid having to perform the reranking manually:
  69. ```python
  70. # 2b. Rank a list of passages for a query
  71. ranks = model.rank(query, passages, return_documents=True)
  72. print("Query:", query)
  73. for rank in ranks:
  74. print(f"- #{rank['corpus_id']} ({rank['score']:.2f}): {rank['text']}")
  75. """
  76. Query: How many people live in Berlin?
  77. - #0 (8.61): Berlin had a population of 3,520,031 registered inhabitants in an area of 891.82 square kilometers.
  78. - #2 (6.35): In 2013 around 600,000 Berliners were registered in one of the more than 2,300 sport and fitness clubs.
  79. - #1 (5.51): Berlin has a yearly total of about 135 million day visitors, making it one of the most-visited cities in the European Union.
  80. """
  81. ```
  82. ### Sparse Encoder Models
  83. First download a pretrained sparse embedding a.k.a. Sparse Encoder model.
  84. ```python
  85. from sentence_transformers import SparseEncoder
  86. # 1. Load a pretrained SparseEncoder model
  87. model = SparseEncoder("naver/splade-cocondenser-ensembledistil")
  88. # The sentences to encode
  89. sentences = [
  90. "The weather is lovely today.",
  91. "It's so sunny outside!",
  92. "He drove to the stadium.",
  93. ]
  94. # 2. Calculate sparse embeddings by calling model.encode()
  95. embeddings = model.encode(sentences)
  96. print(embeddings.shape)
  97. # [3, 30522] - sparse representation with vocabulary size dimensions
  98. # 3. Calculate the embedding similarities
  99. similarities = model.similarity(embeddings, embeddings)
  100. print(similarities)
  101. # tensor([[ 35.629, 9.154, 0.098],
  102. # [ 9.154, 27.478, 0.019],
  103. # [ 0.098, 0.019, 29.553]])
  104. # 4. Check sparsity stats
  105. stats = SparseEncoder.sparsity(embeddings)
  106. print(f"Sparsity: {stats['sparsity_ratio']:.2%}")
  107. # Sparsity: 99.84%
  108. ```
  109. ### Multi-Vector Encoder Models
  110. First download a pretrained multi-vector a.k.a. late-interaction (ColBERT-style) model.
  111. ```python
  112. from sentence_transformers import MultiVectorEncoder
  113. # 1. Load a pretrained MultiVectorEncoder model
  114. model = MultiVectorEncoder("lightonai/GTE-ModernColBERT-v1")
  115. queries = ["What is the capital of France?"]
  116. documents = [
  117. "Paris is the capital of France.",
  118. "Berlin is the capital of Germany.",
  119. ]
  120. # 2. Encode queries and documents into sequences of token-level embeddings
  121. query_embeddings = model.encode_query(queries)
  122. document_embeddings = model.encode_document(documents)
  123. print(query_embeddings[0].shape, document_embeddings[0].shape)
  124. # (10, 128) (9, 128) # one 128-dimensional vector per token
  125. # 3. Score them with late interaction (MaxSim)
  126. scores = model.similarity(query_embeddings, document_embeddings)
  127. print(scores)
  128. # tensor([[9.6037, 9.4055]])
  129. ```
  130. ## Pre-Trained Models
  131. We provide a large list of pretrained models for more than 100 languages. Some models are general purpose models, while others produce embeddings for specific use cases.
  132. - [Pretrained Sentence Transformer (Embedding) Models](https://sbert.net/docs/sentence_transformer/pretrained_models.html)
  133. - [Pretrained Cross Encoder (Reranker) Models](https://sbert.net/docs/cross_encoder/pretrained_models.html)
  134. - [Pretrained Sparse Encoder (Sparse Embeddings) Models](https://sbert.net/docs/sparse_encoder/pretrained_models.html)
  135. - [Pretrained Multi-Vector Encoder (Late Interaction) Models](https://sbert.net/docs/multi_vector_encoder/pretrained_models.html)
  136. ## Training
  137. > **Tip:** Using an AI coding agent (Claude Code, Codex, Cursor, Gemini CLI, ...)? Install the [`train-sentence-transformers`](skills/) Hugging Face Agent Skill via `hf skills add train-sentence-transformers [--claude] [--global]` and ask your agent to fine-tune a model on your data.
  138. This framework allows you to fine-tune your own sentence embedding methods, so that you get task-specific sentence embeddings. You have various options to choose from in order to get perfect sentence embeddings for your specific task.
  139. - Embedding Models
  140. - [Sentence Transformer > Training Overview](https://www.sbert.net/docs/sentence_transformer/training_overview.html)
  141. - [Sentence Transformer > Training Examples](https://www.sbert.net/docs/sentence_transformer/training/examples.html) or [training examples on GitHub](https://github.com/huggingface/sentence-transformers/tree/main/examples/sentence_transformer/training).
  142. - Reranker Models
  143. - [Cross Encoder > Training Overview](https://www.sbert.net/docs/cross_encoder/training_overview.html)
  144. - [Cross Encoder > Training Examples](https://www.sbert.net/docs/cross_encoder/training/examples.html) or [training examples on GitHub](https://github.com/huggingface/sentence-transformers/tree/main/examples/cross_encoder/training).
  145. - Sparse Embedding Models
  146. - [Sparse Encoder > Training Overview](https://www.sbert.net/docs/sparse_encoder/training_overview.html)
  147. - [Sparse Encoder > Training Examples](https://www.sbert.net/docs/sparse_encoder/training/examples.html) or [training examples on GitHub](https://github.com/huggingface/sentence-transformers/tree/main/examples/sparse_encoder/training).
  148. - Multi-Vector (Late Interaction) Models
  149. - [Multi-Vector Encoder > Training Overview](https://www.sbert.net/docs/multi_vector_encoder/training_overview.html)
  150. - [Training examples on GitHub](https://github.com/huggingface/sentence-transformers/tree/main/examples/multi_vector_encoder/training).
  151. Some highlights across the different types of training are:
  152. - Support of various transformer networks including BERT, RoBERTa, XLM-R, DistilBERT, Electra, BART, ...
  153. - Multilingual and multi-task learning
  154. - Evaluation during training to find optimal model
  155. - [20+ loss functions](https://www.sbert.net/docs/package_reference/sentence_transformer/losses.html) for embedding models, [10+ loss functions](https://www.sbert.net/docs/package_reference/cross_encoder/losses.html) for reranker models and [10+ loss functions](https://www.sbert.net/docs/package_reference/sparse_encoder/losses.html) for sparse embedding models, allowing you to tune models specifically for semantic search, paraphrase mining, semantic similarity comparison, clustering, triplet loss, contrastive loss, etc.
  156. ## Companion Blog Posts
  157. The following Hugging Face blog posts complement this documentation with narrative walkthroughs and full training examples:
  158. **Training guides:**
  159. - [Training and Finetuning Embedding Models](https://huggingface.co/blog/train-sentence-transformers): end-to-end training of bi-encoder embedding models.
  160. - [Training and Finetuning Reranker Models](https://huggingface.co/blog/train-reranker): training Cross Encoder models for the second stage of retrieve-and-rerank pipelines.
  161. - [Training and Finetuning Sparse Embedding Models](https://huggingface.co/blog/train-sparse-encoder): training SPLADE and other sparse encoders.
  162. **Multimodal:**
  163. - [Multimodal Embedding & Reranker Models](https://huggingface.co/blog/multimodal-sentence-transformers): using text, image, audio, and video models through a single API.
  164. - [Training and Finetuning Multimodal Embedding & Reranker Models](https://huggingface.co/blog/train-multimodal-sentence-transformers): training multimodal models, with a Visual Document Retrieval walkthrough.
  165. **Efficiency techniques:**
  166. - [Introduction to Matryoshka Embedding Models](https://huggingface.co/blog/matryoshka): variable-size embeddings that can be truncated with minimal quality loss.
  167. - [Train 400x faster Static Embedding Models](https://huggingface.co/blog/static-embeddings): CPU-friendly embedding models without attention.
  168. - [Binary and Scalar Embedding Quantization for Significantly Faster & Cheaper Retrieval](https://huggingface.co/blog/embedding-quantization): post-training compression of embedding vectors.
  169. ## Application Examples
  170. You can use this framework for:
  171. - **Computing Sentence Embeddings**
  172. - [Dense Embeddings](https://www.sbert.net/examples/sentence_transformer/applications/computing-embeddings/README.html)
  173. - [Sparse Embeddings](https://www.sbert.net/examples/sparse_encoder/applications/computing_embeddings/README.html)
  174. - **Semantic Textual Similarity**
  175. - [Dense STS](https://www.sbert.net/docs/sentence_transformer/usage/semantic_textual_similarity.html)
  176. - [Sparse STS](https://www.sbert.net/examples/sparse_encoder/applications/semantic_textual_similarity/README.html)
  177. - **Semantic Search**
  178. - [Dense Search](https://www.sbert.net/examples/sentence_transformer/applications/semantic-search/README.html)
  179. - [Sparse Search](https://www.sbert.net/examples/sparse_encoder/applications/semantic_search/README.html)
  180. - **Retrieve & Re-Rank**
  181. - [Dense only Retrieval](https://www.sbert.net/examples/sentence_transformer/applications/retrieve_rerank/README.html)
  182. - [Sparse/Dense/Hybrid Retrieval](https://www.sbert.net/examples/sentence_transformer/applications/retrieve_rerank/README.html)
  183. - [Clustering](https://www.sbert.net/examples/sentence_transformer/applications/clustering/README.html)
  184. - [Paraphrase Mining](https://www.sbert.net/examples/sentence_transformer/applications/paraphrase-mining/README.html)
  185. - [Translated Sentence Mining](https://www.sbert.net/examples/sentence_transformer/applications/parallel-sentence-mining/README.html)
  186. - [Multilingual Image Search, Clustering & Duplicate Detection](https://www.sbert.net/examples/sentence_transformer/applications/image-search/README.html)
  187. and many more use-cases.
  188. For all examples, see [examples/sentence_transformer/applications](https://github.com/huggingface/sentence-transformers/tree/main/examples/sentence_transformer/applications).
  189. ## Contributing
  190. See the [contributor guidelines](CONTRIBUTING.md) for contribution expectations, AI usage guidelines, and development setup.
  191. ## Citing & Authors
  192. If you find this repository helpful, feel free to cite our publication [Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks](https://huggingface.co/papers/1908.10084):
  193. ```bibtex
  194. @inproceedings{reimers-2019-sentence-bert,
  195. title = "Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks",
  196. author = "Reimers, Nils and Gurevych, Iryna",
  197. booktitle = "Proceedings of the 2019 Conference on Empirical Methods in Natural Language Processing",
  198. month = "11",
  199. year = "2019",
  200. publisher = "Association for Computational Linguistics",
  201. url = "https://arxiv.org/abs/1908.10084",
  202. }
  203. ```
  204. If you use one of the multilingual models, feel free to cite our publication [Making Monolingual Sentence Embeddings Multilingual using Knowledge Distillation](https://huggingface.co/papers/2004.09813):
  205. ```bibtex
  206. @inproceedings{reimers-2020-multilingual-sentence-bert,
  207. title = "Making Monolingual Sentence Embeddings Multilingual using Knowledge Distillation",
  208. author = "Reimers, Nils and Gurevych, Iryna",
  209. booktitle = "Proceedings of the 2020 Conference on Empirical Methods in Natural Language Processing",
  210. month = "11",
  211. year = "2020",
  212. publisher = "Association for Computational Linguistics",
  213. url = "https://arxiv.org/abs/2004.09813",
  214. }
  215. ```
  216. Please have a look at [Publications](https://www.sbert.net/docs/publications.html) for our different publications that are integrated into SentenceTransformers.
  217. ### Maintainers
  218. Maintainer: [Tom Aarsen](https://github.com/tomaarsen), 🤗 Hugging Face
  219. Don't hesitate to open an issue if something is broken (and it shouldn't be) or if you have further questions.
  220. ---
  221. This project was originally developed by the [Ubiquitous Knowledge Processing (UKP) Lab](https://www.ukp.tu-darmstadt.de/) at TU Darmstadt. We're grateful for their foundational work and continued contributions to the field.
  222. > This repository contains experimental software and is published for the sole purpose of giving additional background details on the respective publication.
  223. [#docs-package]: https://www.sbert.net/
  224. [#github-license]: https://github.com/huggingface/sentence-transformers/blob/main/LICENSE
  225. [#pypi-package]: https://pypi.org/project/sentence-transformers/

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.