最完整sentence-transformers入门指南：从安装到生产部署全流程

原创 于 2025-09-19 04:14:29 发布 · 1.1k 阅读 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。

最完整sentence-transformers入门指南：从安装到生产部署全流程

🔥【免费下载链接】sentence-transformers Multilingual Sentence & Image Embeddings with BERT 🔥【免费下载链接】sentence-transformers 项目地址: https://gitcode.com/gh_mirrors/se/sentence-transformers

引言：你还在为文本嵌入效率低而烦恼吗？

在当今的自然语言处理（NLP）领域，文本嵌入（Text Embedding）技术扮演着至关重要的角色。然而，许多开发者在实际应用中面临着诸多挑战：模型体积庞大导致部署困难、推理速度慢影响用户体验、多语言支持不足限制应用范围等。sentence-transformers作为一款强大的Python库，正是为解决这些痛点而生。

本文将带你从零开始，全面掌握sentence-transformers的安装、核心功能使用、模型训练与优化，直至生产环境部署的完整流程。读完本文后，你将能够：

  • 熟练安装和配置sentence-transformers及其各种扩展组件
  • 掌握Sentence Transformer、Cross Encoder和Sparse Encoder三种核心模型的使用方法
  • 学会如何根据实际需求选择合适的预训练模型
  • 理解并应用模型优化技术提升推理速度
  • 了解模型训练的基本流程和关键参数
  • 掌握将模型部署到生产环境的多种方案

1. 环境准备与安装

sentence-transformers支持多种安装方式，以满足不同场景的需求。我们推荐使用Python 3.9+、PyTorch 1.11.0+和transformers v4.41.0+。

1.1 安装方式对比

安装方式命令主要功能适用场景
默认安装pip install -U sentence-transformers模型加载、保存和推理仅需获取嵌入向量的场景
ONNX支持pip install -U "sentence-transformers[onnx-gpu]" (GPU) 或 pip install -U "sentence-transformers[onnx]" (CPU)支持ONNX后端，包括优化和量化需要提升推理速度的场景
OpenVINO支持pip install -U "sentence-transformers[openvino]"支持OpenVINO后端Intel硬件环境下的部署
含训练功能pip install -U "sentence-transformers[train]"包含默认功能及训练能力需要自定义训练模型的场景
开发模式pip install -U "sentence-transformers[dev]"包含所有功能及开发依赖参与sentence-transformers开发

1.2 从源码安装

如果你需要使用最新的开发版本，可以从源码安装：

git clone https://gitcode.com/gh_mirrors/se/sentence-transformers
cd sentence-transformers
pip install -e ".[train,dev]"

1.3 安装GPU支持

为了充分利用GPU加速，需要安装带CUDA支持的PyTorch：

# 根据你的CUDA版本选择合适的命令
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

2. 核心模型快速上手

sentence-transformers提供了三种核心模型：Sentence Transformer（双编码器）、Cross Encoder（交叉编码器）和Sparse Encoder（稀疏编码器）。它们各有特点，适用于不同的应用场景。

2.1 Sentence Transformer（双编码器）

Sentence Transformer模型能够将文本转换为固定长度的稠密向量表示（嵌入），具有计算效率高、相似度计算快的特点，适用于语义相似度计算、语义搜索、聚类等多种任务。

from sentence_transformers import SentenceTransformer

# 1. 加载预训练模型
model = SentenceTransformer("all-MiniLM-L6-v2")

# 2. 待编码的句子列表
sentences = [
    "The weather is lovely today.",
    "It's so sunny outside!",
    "He drove to the stadium.",
]

# 3. 计算嵌入向量
embeddings = model.encode(sentences)
print(f"嵌入向量形状: {embeddings.shape}")  # 输出: (3, 384)

# 4. 计算相似度矩阵
similarities = model.similarity(embeddings, embeddings)
print("相似度矩阵:")
print(similarities)

上述代码将输出：

嵌入向量形状: (3, 384)
相似度矩阵:
tensor([[1.0000, 0.6660, 0.1046],
        [0.6660, 1.0000, 0.1411],
        [0.1046, 0.1411, 1.0000]])

从相似度矩阵可以看出，前两个句子（"The weather is lovely today."和"It's so sunny outside!"）之间的相似度较高（0.6660），而它们与第三个句子的相似度较低，这符合我们的语义理解。

2.2 Cross Encoder（交叉编码器）

Cross Encoder模型直接计算文本对的相似度分数，通常性能优于Sentence Transformer，但计算速度较慢。它常用于对Sentence Transformer检索出的候选结果进行重排序。

from sentence_transformers.cross_encoder import CrossEncoder

# 1. 加载预训练CrossEncoder模型
model = CrossEncoder("cross-encoder/stsb-distilroberta-base")

# 2. 查询句子和语料库
query = "A man is eating pasta."
corpus = [
    "A man is eating food.",
    "A man is eating a piece of bread.",
    "The girl is carrying a baby.",
    "A man is riding a horse.",
    "A woman is playing violin.",
    "Two men pushed carts through the woods.",
    "A man is riding a white horse on an enclosed ground.",
    "A monkey is playing drums.",
    "A cheetah is running behind its prey.",
]

# 3. 对语料库中的句子进行排序
ranks = model.rank(query, corpus)

# 4. 输出排序结果
print("Query:", query)
for rank in ranks:
    print(f"{rank['score']:.2f}\t{corpus[rank['corpus_id']]}")

上述代码将输出：

Query: A man is eating pasta.
0.67    A man is eating food.
0.34    A man is eating a piece of bread.
0.08    A man is riding a horse.
0.07    A man is riding a white horse on an enclosed ground.
0.01    The girl is carrying a baby.
0.01    Two men pushed carts through the woods.
0.01    A monkey is playing drums.
0.01    A woman is playing violin.
0.01    A cheetah is running behind its prey.

2.3 Sparse Encoder（稀疏编码器）

Sparse Encoder模型生成稀疏向量表示，大多数维度为零，适用于大规模检索系统，具有效率高、可解释性强的特点，常与稠密嵌入结合使用构建混合搜索系统。

from sentence_transformers import SparseEncoder

# 1. 加载预训练SparseEncoder模型
model = SparseEncoder("naver/splade-cocondenser-ensembledistil")

# 2. 待编码的句子列表
sentences = [
    "The weather is lovely today.",
    "It's so sunny outside!",
    "He drove to the stadium.",
]

# 3. 计算稀疏嵌入向量
embeddings = model.encode(sentences)
print(f"嵌入向量形状: {embeddings.shape}")  # 输出: (3, 30522)

# 4. 计算相似度
similarities = model.similarity(embeddings, embeddings)
print("相似度矩阵:")
print(similarities)

# 5. 检查稀疏性
stats = SparseEncoder.sparsity(embeddings)
print(f"稀疏度: {stats['sparsity_ratio']:.2%}")
print(f"每个嵌入的平均非零维度数: {stats['active_dims']:.2f}")

上述代码将输出：

嵌入向量形状: (3, 30522)
相似度矩阵:
tensor([[   35.629,     9.154,     0.098],
        [    9.154,    27.478,     0.019],
        [    0.098,     0.019,    29.553]])
稀疏度: 99.97%
每个嵌入的平均非零维度数: 92.33

3. 模型选择指南

sentence-transformers提供了丰富的预训练模型，选择合适的模型对于获得良好性能至关重要。以下是一些常用的模型类型及其适用场景：

3.1 模型性能对比

模型类型代表模型优势劣势适用场景
通用模型all-MiniLM-L6-v2速度快，体积小性能适中对速度要求高的场景
高性能模型all-mpnet-base-v2性能优秀速度较慢，体积较大对精度要求高的场景
多语言模型paraphrase-multilingual-MiniLM-L12-v2支持100+语言单语言性能略低多语言应用场景
领域特定模型all-scalabert-large-v2特定领域性能好泛化能力可能有限学术、法律等专业领域
小型模型all-MiniLM-L12-v2超轻量，速度极快性能较低移动端或嵌入式设备

3.2 模型选择流程图

mermaid

4. 高级功能与优化

4.1 嵌入计算优化

为了提高嵌入计算的效率，可以采用以下方法：

from sentence_transformers import SentenceTransformer

# 加载模型时指定设备
model = SentenceTransformer("all-MiniLM-L6-v2", device="cuda")

# 批量编码
sentences = [" sentence 1", " sentence 2", ...]  # 大量句子
embeddings = model.encode(sentences, batch_size=32, show_progress_bar=True)

# 使用GPU加速
embeddings = model.encode(sentences, device="cuda")

# 多线程处理
embeddings = model.encode(sentences, num_workers=4)

# 量化模型以提高速度并减少内存占用
model = SentenceTransformer("all-MiniLM-L6-v2")
model.quantize("int8")  # 量化为int8
embeddings = model.encode(sentences)

4.2 相似度计算方法

sentence-transformers支持多种相似度计算方法：

from sentence_transformers import SentenceTransformer
import torch

model = SentenceTransformer("all-MiniLM-L6-v2")
sentences = ["The weather is lovely today.", "It's so sunny outside!"]
embeddings = model.encode(sentences)

# 方法1: 使用内置similarity方法
similarity = model.similarity(embeddings[0], embeddings[1])
print(f"余弦相似度: {similarity.item():.4f}")

# 方法2: 手动计算余弦相似度
cos_sim = torch.nn.functional.cosine_similarity(embeddings[0].unsqueeze(0), embeddings[1].unsqueeze(0))
print(f"余弦相似度: {cos_sim.item():.4f}")

# 方法3: 计算欧氏距离
euclidean_distance = torch.nn.functional.pairwise_distance(embeddings[0].unsqueeze(0), embeddings[1].unsqueeze(0), p=2)
print(f"欧氏距离: {euclidean_distance.item():.4f}")

5. 应用场景实战

5.1 语义搜索

语义搜索是sentence-transformers最常见的应用场景之一。下面是一个完整的语义搜索实现：

from sentence_transformers import SentenceTransformer, util
import numpy as np

# 1. 加载模型
model = SentenceTransformer("all-MiniLM-L6-v2")

# 2. 构建文档库
corpus = [
    "A man is eating food.",
    "A man is eating a piece of bread.",
    "The girl is carrying a baby.",
    "A man is riding a horse.",
    "A woman is playing violin.",
    "Two men pushed carts through the woods.",
    "A man is riding a white horse on an enclosed ground.",
    "A monkey is playing drums.",
    "A cheetah is running behind its prey.",
]

# 3. 编码文档库
corpus_embeddings = model.encode(corpus, convert_to_tensor=True)

# 4. 定义查询
queries = ["A man is eating pasta.", "Someone is playing an instrument."]

# 5. 搜索每个查询
for query in queries:
    query_embedding = model.encode(query, convert_to_tensor=True)
    
    # 计算余弦相似度
    cos_scores = util.cos_sim(query_embedding, corpus_embeddings)[0]
    
    # 获取排名前3的结果
    top_results = torch.topk(cos_scores, k=3)
    
    print(f"\n查询: {query}")
    for score, idx in zip(top_results[0], top_results[1]):
        print(f"{corpus[idx]} (分数: {score.item():.4f})")

5.2 文本聚类

使用sentence-transformers结合聚类算法可以实现文本的自动分组：

from sentence_transformers import SentenceTransformer
from sklearn.cluster import KMeans
import numpy as np

# 1. 加载模型
model = SentenceTransformer("all-MiniLM-L6-v2")

# 2. 准备文本数据
sentences = [
    "The quick brown fox jumps over the lazy dog.",
    "A fox is quick and brown.",
    "The dog is lazy and lies on the ground.",
    "I like to eat pizza for dinner.",
    "Pizza is my favorite food.",
    "Dinner tonight will be pizza.",
    "The stock market is volatile today.",
    "Stock prices are fluctuating rapidly.",
    "Investors are worried about the market."
]

# 3. 生成嵌入向量
embeddings = model.encode(sentences)

# 4. 应用K-means聚类
num_clusters = 3
clustering_model = KMeans(n_clusters=num_clusters)
clustering_model.fit(embeddings)
cluster_assignment = clustering_model.labels_

# 5. 输出聚类结果
clustered_sentences = [[] for _ in range(num_clusters)]
for sentence_id, cluster_id in enumerate(cluster_assignment):
    clustered_sentences[cluster_id].append(sentences[sentence_id])

for i, cluster in enumerate(clustered_sentences):
    print(f"\n集群 {i+1}:")
    for sentence in cluster:
        print(f"- {sentence}")

6. 生产环境部署

将sentence-transformers模型部署到生产环境需要考虑性能、可扩展性和稳定性等因素。以下是几种常见的部署方案：

6.1 使用FastAPI构建API服务

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from sentence_transformers import SentenceTransformer
import torch

app = FastAPI(title="Sentence Transformers API")

# 加载模型
model = SentenceTransformer("all-MiniLM-L6-v2")

class EmbeddingRequest(BaseModel):
    sentences: list[str]
    normalize_embeddings: bool = True

class SimilarityRequest(BaseModel):
    sentence1: str
    sentence2: str

@app.post("/embed")
async def embed_text(request: EmbeddingRequest):
    try:
        embeddings = model.encode(
            request.sentences,
            normalize_embeddings=request.normalize_embeddings
        )
        return {"embeddings": embeddings.tolist()}
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

@app.post("/similarity")
async def calculate_similarity(request: SimilarityRequest):
    try:
        embeddings = model.encode([request.sentence1, request.sentence2])
        similarity = torch.nn.functional.cosine_similarity(
            torch.tensor(embeddings[0]), 
            torch.tensor(embeddings[1]), 
            dim=0
        )
        return {"similarity": similarity.item()}
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

6.2 模型优化与量化

为了提高部署性能，可以对模型进行优化和量化：

from sentence_transformers import SentenceTransformer

# 加载模型
model = SentenceTransformer("all-MiniLM-L6-v2")

# 保存原始模型
model.save("original_model")

# 优化模型（ONNX格式）
model = SentenceTransformer("original_model")
model.save("onnx_model", format="onnx")

# 量化模型（INT8）
from sentence_transformers.backend import QuantizedModel

quantized_model = QuantizedModel.from_pretrained("onnx_model", quantize=True)
quantized_model.save("quantized_model")

# 加载量化模型
model = SentenceTransformer("quantized_model")

6.3 Docker部署

以下是一个Dockerfile示例，用于部署sentence-transformers服务：

FROM python:3.9-slim

WORKDIR /app

# 安装依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY app.py .

# 下载模型
RUN python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')"

# 暴露端口
EXPOSE 8000

# 启动服务
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

requirements.txt内容：

fastapi==0.104.1
uvicorn==0.23.2
sentence-transformers>=2.2.2
pydantic==2.4.2
torch>=1.11.0

7. 模型训练与自定义

sentence-transformers不仅提供了预训练模型，还支持自定义训练。以下是一个简单的训练示例：

7.1 训练数据准备

from sentence_transformers.readers import InputExample
from sentence_transformers.datasets import SentencesDataset
from torch.utils.data import DataLoader

# 准备训练数据
train_examples = [
    InputExample(texts=["Sentence 1", "Sentence 2"], label=0.8),
    InputExample(texts=["This is a sentence", "This is another sentence"], label=0.3),
    InputExample(texts=["A long sentence about machine learning", "Machine learning techniques"], label=0.6),
]

# 创建数据集和数据加载器
train_dataset = SentencesDataset(train_examples, model)
train_dataloader = DataLoader(train_dataset, shuffle=True, batch_size=16)

7.2 模型训练

from sentence_transformers import SentenceTransformer, losses
from sentence_transformers.evaluation import EmbeddingSimilarityEvaluator

# 加载基础模型
model = SentenceTransformer("all-MiniLM-L6-v2")

# 定义损失函数
train_loss = losses.CosineSimilarityLoss(model)

# 准备评估数据
evaluator = EmbeddingSimilarityEvaluator(
    sentences1=["Sentence 1", "This is a sentence"],
    sentences2=["Sentence 2", "This is another sentence"],
    scores=[0.8, 0.3]
)

# 训练模型
model.fit(
    train_objectives=[(train_dataloader, train_loss)],
    evaluator=evaluator,
    epochs=3,
    evaluation_steps=100,
    warmup_steps=100,
    output_path="./trained_model"
)

8. 常见问题与解决方案

8.1 性能优化

问题解决方案预期效果
推理速度慢使用ONNX或OpenVINO后端提速2-3倍
模型体积大量化模型为INT8体积减少75%
内存占用高降低batch size或使用更小模型内存占用减少50%+
GPU利用率低增加batch size或使用数据并行提高GPU利用率至80%+

8.2 常见错误解决

错误原因解决方案
模型下载失败网络问题或HF访问限制使用国内镜像或手动下载模型
CUDA out of memorybatch size过大减小batch size或使用更小模型
性能不如预期模型与任务不匹配尝试更适合的预训练模型
多语言支持不佳使用了单语言模型切换到多语言模型

9. 总结与展望

sentence-transformers作为一个强大的文本嵌入库，提供了简单易用但功能强大的API，使开发者能够轻松地将最先进的NLP模型集成到自己的应用中。从简单的相似度计算到复杂的语义搜索，从快速原型开发到大规模生产部署，sentence-transformers都能满足各种需求。

随着NLP技术的不断发展，sentence-transformers也在持续进化。未来，我们可以期待更多创新功能，如更高效的模型压缩技术、更好的多模态支持、更强的领域适应性等。无论你是NLP新手还是资深开发者，sentence-transformers都是一个值得深入学习和掌握的工具。

10. 学习资源与进阶阅读

为了帮助你进一步掌握sentence-transformers，以下是一些推荐的学习资源：

  1. 官方文档：详细介绍了所有API和使用方法
  2. GitHub仓库：包含大量示例代码和教程
  3. 论文《Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks》：了解核心算法原理
  4. Hugging Face模型库：探索更多预训练模型
  5. 社区论坛：交流使用经验和解决问题

通过不断实践和探索，你将能够充分发挥sentence-transformers的潜力，构建出更智能、更高效的NLP应用。

🔥【免费下载链接】sentence-transformers Multilingual Sentence & Image Embeddings with BERT 🔥【免费下载链接】sentence-transformers 项目地址: https://gitcode.com/gh_mirrors/se/sentence-transformers

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值