>Sentence Transformers 是用于最先进文本和图像嵌入的最广泛使用的 Python 框架。Hugging Face Hub 托管数千个预训练 嵌入 和 重排序 模型，可在本地运行，无需 API 密钥，可通过以下方式访问 HuggingFaceEmbeddings class.

设置

pip install -qU langchain-huggingface

langchain-huggingface 引入 sentence-transformers 作为依赖项，这反过来会安装 transformers 和 torch.

基本用法

from langchain_huggingface import HuggingFaceEmbeddings

embeddings = HuggingFaceEmbeddings(model_name="sentence-transformers/all-mpnet-base-v2")

query_embedding = embeddings.embed_query("What is a sentence embedding?")
doc_embeddings = embeddings.embed_documents(
    [
        "Sentence embeddings map text to dense vectors.",
        "LangChain provides a standard Embeddings interface.",
    ]
)

选择模型

从以下 MTEB 排行榜开始。不同权衡下的强起点：

另请参见 权衡因素 深入了解权衡因素。

归一化嵌入

使用余弦相似度训练的模型受益于归一化输出向量。如果您的向量存储使用余弦相似度，请在源处归一化：

embeddings = HuggingFaceEmbeddings(
    model_name="BAAI/bge-m3",
    encode_kwargs={"normalize_embeddings": True},
)

设备和吞吐量

Sentence Transformers 自动选择最佳可用设备 (CUDA > MPS > CPU)，因此您无需设置 device= 在大多数情况下明确设置。在 GPU 上，提高 batch_size 以保持其运行：

embeddings = HuggingFaceEmbeddings(
    model_name="BAAI/bge-m3",
    encode_kwargs={"batch_size": 64, "normalize_embeddings": True},
)

要固定到特定设备，请传递 model_kwargs={"device": "cpu"} (or "cuda:1"等）。对于多 GPU，请设置 multi_process=True。对于 Intel CPU，请使用 model_kwargs={"backend": "ipex"} 安装后 optimum[ipex].

查询和文档提示

某些模型（intfloat/e5-*, Qwen/Qwen3-Embedding-*、许多 BAAI/bge-*）使用不同的查询和文档提示进行训练。通过以下方式传递这些 encode_kwargs 和 query_encode_kwargs:

embeddings = HuggingFaceEmbeddings(
    model_name="intfloat/e5-large-v2",
    encode_kwargs={"prompt": "passage: "},
    query_encode_kwargs={"prompt": "query: "},
)

在索引和查询时使用正确的提示通常会带来显著的检索质量提升。请查看每个模型在 Hugging Face 上的卡片以获取推荐的提示字符串。

生产环境部署

对于大规模服务 Sentence Transformers 模型，请使用 文本嵌入推理 (TEI)，这是来自 Hugging Face 的专用推理服务器，支持批处理、GPU 和 OpenAI 兼容 API。通过以下方式将 LangChain 指向 TEI 部署 HuggingFaceEndpointEmbeddings：请参阅 Hugging Face 嵌入主要指南.

重排序

同一个生态系统还托管了 交叉编码器重排序模型。有关向量存储之上的本地重排序器，请参阅 交叉编码器重排序器指南.

故障排除

如果 accelerate 包缺失或导入失败：

pip install -qU accelerate