Loading...

文章背景图
AI大模型 # 若琳部署

Sentence-Transformers：句向量嵌入库部署指南

周若琳
周若琳
2026-10-27
0
- 字
- 分钟
|

Sentence-Transformers：句向量嵌入库部署指南

huggingface/sentence-transformers 是 Hugging Face 维护的句向量嵌入库，实时 Star 数约 19.2k，是做语义搜索、RAG、相似度计算的事实标准工具。本文基于官方 README 完整翻译整理，从项目定位、安装方式、四种模型类型用法、预训练模型、训练与应用场景逐一说明。

这个框架提供了一种简单的方法来计算嵌入向量，用于访问、使用和训练 SOTA 嵌入模型与重排序模型。它支持四种模型：Sentence Transformer（稠密嵌入）、Cross-Encoder（重排序）、Sparse Encoder（稀疏嵌入）、Multi-Vector Encoder（ColBERT 式多向量）。Hugging Face Hub 上有超过 15000 个预训练模型可直接使用，包括 MTEB 排行榜上的大多数 SOTA 模型。

对做 RAG、语义搜索、推荐系统的开发者来说，sentence-transformers 是绕不开的工具。它解决的核心问题是：把一段文本变成一个固定维度的向量，让计算机可以用数学方法衡量两段文本的语义相似度。没有嵌入模型，搜索只能靠关键词匹配；有了嵌入模型，搜索才能理解「怎么烤好蛋糕」和「蛋糕烘焙技巧」是同一个意思。

这个框架之所以能成为事实标准，一方面是因为它免费开源、模型可本地部署，另一方面是因为它和 Hugging Face 生态深度集成——Hub 上 15000+ 模型即装即用，训练和推理用同一套 API，和 vLLM、FAISS、Chroma 等下游工具无缝对接。

对做 RAG 的开发者来说，sentence-transformers 就是整个系统的「前半步」：没有好的嵌入模型，后面的向量数据库和大模型再强也白搭——因为检索出来的片段语义不对，大模型再聪明也回答不好。选对嵌入模型、按需微调，是 RAG 效果调优里投入产出比最高的一步。

这个项目最初由德国 TU Darmstadt 大学的 UKP 实验室开发，论文作者是 Nils Reimers 和 Iryna Gurevych，2019 年发表在 EMNLP 上。后来项目捐赠给 Hugging Face，由 Tom Aarsen 持续维护，模型数量从最初几个增长到现在的 15000+，覆盖 100+ 语言。

从一个学术项目成长为工业界标准，sentence-transformers 靠的是「简单、免费、好用」三个特点：API 简单到三行代码就能跑，模型免费下载可本地部署，文档和示例齐全，是每个做 NLP 和 RAG 应用的开发者都应该认真学习和熟练掌握的非常实用的优秀开源基础开发工具。

一、项目官方信息

项目 信息
GitHub 仓库 huggingface/sentence-transformers
官方文档 www.SBERT.net
Star 数 约 19.2k
开源协议 Apache 2.0
主要语言 Python
预训练模型数 15000+（100+ 语言）
原作者 TU Darmstadt UKP Lab，现由 Hugging Face 的 Tom Aarsen 维护

二、官方图片

封面取 GitHub 仓库官方图，本文不重复贴图。

三、环境要求

官方推荐 Python 3.10+、PyTorch 2.2+、transformers v5.0+。做推理跑 1.5B 级以下嵌入模型，8GB 显存即可；做训练建议 24GB 以上显存。首次使用建议 hf auth login 登录 Hugging Face 账号以提高 API 限流并访问私有模型。

硬件方面，嵌入模型推理比大模型推理轻得多：all-MiniLM-L6-v2 只有 22MB，CPU 都能跑；7B 级嵌入模型需要 16GB 显存。磁盘方面，常用模型从几十 MB 到几 GB 不等，建议预留 50GB 给 Hugging Face 缓存。网络上需要能访问 Hugging Face Hub，国内用户建议配镜像端点。

操作系统上，Linux 是首选；Windows 和 macOS 也支持，但训练多 GPU 场景在 Linux 上最稳定。建议在虚拟环境（venv 或 uv）里安装，避免和系统包冲突。

四、完整部署步骤

1. 安装

pip install -U sentence-transformers

文档还提供 uv、conda、源码、可编辑安装方式，以及 CUDA 设置和可选依赖（[image]、[audio]、[video]、[train]、[onnx]、[openvino]、[dev]），详见 安装文档。

安装完成后，建议先跑一个最简单的嵌入例子验证环境，比如用 sentence-transformers/all-MiniLM-L6-v2 编码三句话算相似度，能正常输出向量和相似度矩阵就说明装好了。第一次运行会自动下载模型权重，国内用户建议先配镜像。

整个流程是：pip install → 加载模型 → encode 句子 → 算相似度。四步就能跑通一个语义搜索最小 Demo。如果要做 RAG，把文档切块 encode 存向量库，查询时 encode 查询做最近邻，再喂给大模型生成答案。

2. 嵌入模型（Sentence Transformer）

from sentence_transformers import SentenceTransformer

model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")

sentences = [
    "The weather is lovely today.",
    "It's so sunny outside!",
    "He drove to the stadium.",
]
embeddings = model.encode(sentences)
print(embeddings.shape)
# => (3, 384)

算相似度：

similarities = model.similarity(embeddings, embeddings)
print(similarities)

这就是最常用的稠密嵌入用法：把文本编码成固定维度向量，用余弦相似度比较。

稠密嵌入是 RAG 系统的基石。你把知识库文档切成块，每块编码成向量存进向量数据库（Chroma、Qdrant、Milvus、FAISS 等），用户查询时也编码成向量，做最近邻搜索就能找到语义最相近的文档片段。这个流程每天在全球数百万个 RAG 应用里跑。

3. 重排序模型（Cross-Encoder）

from sentence_transformers import CrossEncoder

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

query = "How many people live in Berlin?"
passages = [
    "Berlin had a population of 3,520,031 registered inhabitants in an area of 891.82 square kilometers.",
    "Berlin has a yearly total of about 135 million day visitors, making it one of the most-visited cities in the European Union.",
    "In 2013 around 600,000 Berliners were registered in one of the more than 2,300 sport and fitness clubs.",
]

scores = model.predict([(query, passage) for passage in passages])
print(scores)

也可以用 model.rank 直接排序：

ranks = model.rank(query, passages, return_documents=True)
for rank in ranks:
    print(f"- #{rank['corpus_id']} ({rank['score']:.2f}): {rank['text']}")

Cross-Encoder 是「检索-重排」两段式管道的第二段：第一段用 Sentence Transformer 从十万文档里粗筛出 100 篇，第二段用 Cross-Encoder 精排到 top 10。

为什么需要两段式？因为 Sentence Transformer 是双编码器，查询和文档分别编码，速度快但精度有限；Cross-Encoder 是交叉编码器，查询和文档拼在一起过一次模型，精度高但慢。两段式结合了两者的优点：用快模型粗筛保证召回率，用慢模型精排保证准确率。这是工业界 RAG 系统的标准架构。

粗筛阶段从十万文档里召回 100 篇相关度高的候选，精排阶段再对这 100 篇两两打分，选出 top 3 喂给大模型。这样既保证了召回率（不漏掉相关文档），又保证了精度（精排后的 top 结果很准），还控制了计算成本（精排只跑 100 次而不是 10 万次）。

4. 稀疏嵌入模型（Sparse Encoder）

from sentence_transformers import SparseEncoder

model = SparseEncoder("naver/splade-cocondenser-ensembledistil")

sentences = [
    "The weather is lovely today.",
    "It's so sunny outside!",
    "He drove to the stadium.",
]
embeddings = model.encode(sentences)
print(embeddings.shape)
# [3, 30522] - 稀疏表示，维度等于词表大小

similarities = model.similarity(embeddings, embeddings)
stats = SparseEncoder.sparsity(embeddings)
print(f"Sparsity: {stats['sparsity_ratio']:.2%}")
# Sparsity: 99.84%

稀疏嵌入（SPLADE）在稀疏向量维度上工作，99% 以上是零，可以和传统倒排索引结合做混合检索。

稀疏嵌入的好处是可解释、可和 BM25 传统搜索融合。稠密嵌入擅长语义泛化但不懂精确匹配，稀疏嵌入（SPLADE）会学习词权重，对关键词敏感。混合检索把两者结合，既懂语义又懂关键词，在企业搜索场景里效果最好。

5. 多向量编码器（Multi-Vector / ColBERT）

from sentence_transformers import MultiVectorEncoder

model = MultiVectorEncoder("lightonai/GTE-ModernColBERT-v1")

queries = ["What is the capital of France?"]
documents = [
    "Paris is the capital of France.",
    "Berlin is the capital of Germany.",
]

query_embeddings = model.encode_query(queries)
document_embeddings = model.encode_document(documents)
scores = model.similarity(query_embeddings, document_embeddings)
print(scores)

Multi-Vector 是 ColBERT 式的 late-interaction：每个 token 一个向量，相似度用 MaxSim 计算，精度比单向量高但存储和计算成本也更大。

ColBERT 是介于双编码器和交叉编码器之间的中间路线：它把每个 token 编码成向量，查询时做 token 级别的 MaxSim 匹配，精度接近交叉编码器，速度接近双编码器。代价是存储成本高——每个文档要存几百个 token 向量。适合对精度要求极高、文档量不大的场景。

五、预训练模型与训练

预训练模型

提供 100+ 语言的预训练模型列表，通用模型和特定场景模型都有：

选模型时看两个维度：一是 MTEB 排行榜上你任务的分数，二是模型大小和速度。all-MiniLM-L6-v2 是最小最快的入门款；bge-large-zh-v1.5 是中文场景常用款；商用级精度可以选 MTEB 榜上的大模型。预训练模型覆盖了 100+ 语言，中文、英文、多语言场景都有现成模型可用，不需要自己训练。

训练

这个框架允许你微调自己的句向量模型，得到任务特定的嵌入。支持 BERT、RoBERTa、XLM-R、DistilBERT、Electra、BART 等多种 Transformer 网络；支持多语言和多任务学习；训练时可评估找最优模型；嵌入模型有 20+ 损失函数，重排序模型有 10+ 损失函数，稀疏嵌入模型有 10+ 损失函数。

为什么要微调？通用嵌入模型在特定领域（比如法律、医疗、代码）上效果不一定好，因为这些领域的词汇和日常用语差异很大。用你自己领域的几百对相关/不相关句子微调一下，模型就能学会你的领域语义，搜索效果会有质的提升。微调成本不高，一张 24GB 显存的显卡就能跑。

AI 编码代理用户（Claude Code、Codex、Cursor、Gemini CLI）可以用 hf skills add train-sentence-transformers [--claude] [--global] 安装 Hugging Face Agent Skill，让代理自动帮你微调模型。

训练流程一般是：准备几百对「相关句子对」和「不相关句子对」，选一个损失函数（MultipleNegativesRankingLoss 是默认推荐），在消费级 GPU 上跑几个 epoch，训练过程中用验证集评估 Recall@k，选最优 checkpoint 保存。整个过程代码量不大，但数据质量决定最终效果——垃圾数据进，垃圾模型出。

六、应用场景与 FAQ

典型应用

官方博客

FAQ

  • 和 OpenAI text-embedding 比有什么优势？ 可以本地部署、数据不出内网、免费、可微调。
  • RAG 里怎么用？ 第一段用 Sentence Transformer 把文档切块编码存向量库，查询时编码查询做相似度粗筛，再用 Cross-Encoder 精排 top-k。
  • 支持中文吗？ 支持，100+ 语言的预训练模型里有专门的中文模型。
  • 遇到问题去哪？ GitHub Issues，贡献指南见 CONTRIBUTING.md。
  • 和 Hugging Face 官方是什么关系？ 这个项目最初由德国 TU Darmstadt 大学的 UKP 实验室开发（Sentence-BERT 论文作者），后来捐赠给 Hugging Face 并由 Tom Aarsen 维护。它是 Hugging Face 生态的一等公民。
  • 支持 GPU 加速吗？ 支持，PyTorch 后端自动用 CUDA；也有 ONNX 和 OpenVINO 可选依赖用于 CPU 加速部署。
  • 怎么选模型？ 先看 MTEB 排行榜选你任务上排名高的模型，再看模型大小和速度 trade-off。新手从 all-MiniLM-L6-v2 开始，快、小、够用。
  • 支持多模态吗？ 支持，见 多模态嵌入与重排序模型博客，文本、图像、音频、视频用同一个 API。
  • 怎么部署到生产？ 推理可以用 ONNX Runtime 或 OpenVINO 加速 CPU 部署；向量数据库选 Chroma、Qdrant、Milvus、FAISS 等；重排阶段用 Cross-Encoder 精排。
  • 和 FAISS 是什么关系？ FAISS 是向量索引库，sentence-transformers 是嵌入模型库。两者配套：sentence-transformers 把文本变成向量，FAISS 负责向量相似度搜索。
  • 推理速度怎么样？ MiniLM 级模型在 CPU 上每秒可编码几十句，GPU 上更快；生产部署建议 ONNX 量化或选 Matryoshka 截断维度。
  • 和 LangChain 是什么关系？ LangChain 把 sentence-transformers 作为默认嵌入后端集成进去，你可以直接在 LangChain 里传模型名用。

七、跳转链接

本文所有命令与版本号均与官方 README 一致，不做任何臆造。sentence-transformers 是做语义搜索和 RAG 的必备工具，建议从 all-MiniLM-L6-v2 开始上手，理解嵌入-检索-重排三段式架构后再按需微调。它是大模型工程化里「检索增强」这条路线的基础组件，和向量数据库、重排模型、大模型一起构成完整的 RAG 系统。

引用方式：

@inproceedings{reimers-2019-sentence-bert,
    title = "Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks",
    author = "Reimers, Nils and Gurevych, Iryna",
    booktitle = "Proceedings of the 2019 Conference on Empirical Methods in Natural Language Processing",
    year = "2019",
    publisher = "Association for Computational Linguistics",
    url = "https://arxiv.org/abs/1908.10084",
}
上一篇 Meilisearch：轻量极速全文搜索引擎自托管部署与使用指南
下一篇 BetterGI（更好的原神）：基于计算机视觉的原神自动化工具｜Windows 部署与使用全指南
评论交流

文章目录