text2vec 库核心组件实战详解

一、text2vec 库整体介绍

text2vec 是一个轻量级、高性能的中文文本向量库，核心基于预训练语言模型（如 SimBERT、M3E、Text2Vec-Base 等）实现文本向量化、语义相似度计算、语义检索等功能，广泛应用于文本匹配、检索、聚类、去重等 NLP 场景。

本文重点详解从 text2vec 导入的三个核心组件：SentenceModel（文本向量化核心类）、semantic_search（语义检索函数）、Similarity（相似度计算便捷类）。

二、SentenceModel：文本向量化核心类

SentenceModel 是加载预训练模型、将文本转换为稠密向量（Embedding）的核心类，是后续所有操作的基础。

1. 核心作用

将任意长度的文本（句子/段落）转换为固定维度的数值向量（Embedding），向量的语义空间距离可反映文本的语义相似度。

2. 初始化参数

参数	说明	默认值
model_name_or_path	预训练模型名称/本地路径	'shibing624/text2vec-base-chinese'
device	运行设备（CPU/GPU）	'auto'（自动检测GPU，无则用CPU）
normalize_embeddings	是否对生成的向量归一化	True（推荐开启，提升相似度计算稳定性）
trust_remote_code	是否信任远程模型代码（加载自定义模型时需开启）	False
cache_folder	模型缓存路径	系统默认缓存目录（如 ~/.cache/huggingface/）

常用预训练模型推荐：

• 'm3e-base'/'m3e-large'：通用中文文本向量模型，效果最优（推荐）；
• 'shibing624/text2vec-base-chinese'：轻量中文模型，速度快；
• 'simbert-base-chinese'：兼顾语义匹配与生成的模型。

3. 核心方法：encode()

将文本列表转换为向量，是最常用的方法。

def encode(
    texts: List[str],          # 待编码的文本列表（必填）
    batch_size: int = 32,     # 批处理大小（大批量加速，小批量省内存）
    convert_to_tensor: bool = False,  # 是否返回torch.Tensor（False返回numpy数组）
    normalize_embeddings: Optional[bool] = None  # 覆盖初始化时的归一化设置
) -> Union[np.ndarray, torch.Tensor]:

• 返回值：形状为 [文本数量, 向量维度] 的数组/Tensor（如 M3E-Base 向量维度为 768）。

4. 使用示例

from text2vec import SentenceModel

# 1. 加载预训练模型（首次使用自动下载）
model = SentenceModel('m3e-base', device='cuda')  # 优先用GPU

# 2. 编码文本
texts = [
    "今天天气很好",
    "我想去公园散步",
    "今日晴空万里",
    "人工智能技术发展迅速"
]
embeddings = model.encode(texts)  # 返回numpy数组，形状(4, 768)

print(f"向量形状：{embeddings.shape}")
print(f"第一个文本向量前5维：{embeddings[0][:5]}")

三、semantic_search：语义检索函数

semantic_search 基于文本向量的相似度（默认余弦相似度），实现查询向量在候选向量库中的Top-K检索，适合"一对多"的语义匹配场景（如问答检索、文本召回）。

1. 核心作用

输入查询向量和候选向量库，返回每个查询的Top-K最相似候选结果（含索引和相似度分数）。

2. 函数参数

参数	说明	默认值
query_embeddings	查询向量（numpy/Tensor，形状：[查询数, 向量维度]）	必填
corpus_embeddings	候选向量库（numpy/Tensor，形状：[候选数, 向量维度]）	必填
top_k	每个查询返回的最相似结果数	5
score_function	相似度计算方式：cos_sim（余弦）/dot_score（点积）	cos_sim

3. 返回值

• 列表的列表：外层列表对应每个查询，内层列表包含top_k个字典，每个字典含：
  • corpus_id：候选向量在库中的索引；
  • score：相似度分数（余弦相似度范围[-1,1]，值越大越相似）。

4. 使用示例

from text2vec import SentenceModel, semantic_search

# 1. 加载模型并编码文本
model = SentenceModel('m3e-base')
# 查询文本
queries = ["今天天气不错"]
# 候选文本库
corpus = [
    "今日晴空万里",
    "我想去公园散步",
    "人工智能技术发展迅速",
    "明天可能下雨"
]
# 编码为向量
query_embeddings = model.encode(queries)
corpus_embeddings = model.encode(corpus)

# 2. 语义检索（返回Top-2最相似结果）
results = semantic_search(query_embeddings, corpus_embeddings, top_k=2)

# 3. 解析结果
for i, query_result in enumerate(results):
    print(f"\n查询文本：{queries[i]}")
    for item in query_result:
        corpus_id = item['corpus_id']
        score = item['score']
        print(f"  相似文本：{corpus[corpus_id]} | 相似度：{score:.4f}")

输出结果：

查询文本：今天天气不错
  相似文本：今日晴空万里 | 相似度：0.9215
  相似文本：明天可能下雨 | 相似度：0.5123

四、Similarity：相似度计算便捷类

Similarity 是封装好的相似度计算类，支持直接计算文本对的相似度（无需手动编码），适合"一对一/多对多"的相似度计算场景（如文本匹配、重复检测）。

1. 核心作用

简化相似度计算流程：无需手动调用encode()，直接输入文本即可计算相似度（内部自动完成向量化+相似度计算）。

2. 初始化参数

与SentenceModel完全一致（model_name_or_path/device/normalize_embeddings等）。

3. 核心方法

方法	说明
similarity(text1: str, text2: str)	快捷计算两个文本的余弦相似度（返回单个浮点数）
compute_score(texts1: List[str], texts2: List[str], score_type='cosine')	计算两组文本的相似度（一对一匹配，长度需一致） - score_type：cosine（余弦）/dot（点积）/euclidean（欧氏距离）
distance(text1: str, text2: str, distance_type='euclidean')	计算两个文本向量的距离（距离越小越相似）

4. 使用示例

from text2vec import Similarity

# 1. 初始化相似度计算类
sim = Similarity('m3e-base', device='cuda')

# 2. 计算两个文本的余弦相似度（快捷方法）
text1 = "今天天气很好"
text2 = "今日晴空万里"
score = sim.similarity(text1, text2)
print(f"【{text1}】与【{text2}】的相似度：{score:.4f}")

# 3. 批量计算多组文本的相似度
texts1 = ["今天天气好", "人工智能"]
texts2 = ["今日晴空万里", "大语言模型"]
scores = sim.compute_score(texts1, texts2, score_type='cosine')
print(f"\n批量相似度结果：{[f'{s:.4f}' for s in scores]}")

# 4. 计算欧氏距离（距离越小越相似）
distance = sim.distance(text1, text2, distance_type='euclidean')
print(f"\n欧氏距离：{distance:.4f}")

输出结果：

【今天天气很好】与【今日晴空万里】的相似度：0.9215

批量相似度结果：['0.9215', '0.3587']

欧氏距离：0.4061

五、关键注意事项

1. 安装 ：需先安装库：pip install text2vec（推荐安装最新版：pip install -U text2vec）；
2. 模型下载：首次使用预训练模型会自动下载，需联网（国内可配置镜像加速）；
3. 向量归一化 ：推荐开启normalize_embeddings=True，归一化后余弦相似度等价于点积，计算更稳定；
4. 设备加速：GPU（CUDA）可大幅提升大批量文本的编码速度，小批量文本CPU也可满足需求；
5. 场景选择 ：
   • 文本向量化+自定义处理：用SentenceModel；
   • 一对多语义检索：用semantic_search；
   • 直接计算文本相似度（无需手动编码）：用Similarity。

六、完整综合示例

from text2vec import SentenceModel, semantic_search, Similarity

# ====================== 1. 文本向量化（SentenceModel） ======================
model = SentenceModel('m3e-base', device='auto')
texts = ["苹果发布新款手机", "华为推出鸿蒙系统", "iPhone 15上市"]
embeddings = model.encode(texts)
print(f"向量形状：{embeddings.shape}\n")

# ====================== 2. 语义检索（semantic_search） ======================
query = ["苹果新款手机发布"]
query_emb = model.encode(query)
corpus_emb = embeddings
results = semantic_search(query_emb, corpus_emb, top_k=2)
print("语义检索结果：")
for res in results[0]:
    print(f"  文本：{texts[res['corpus_id']]} | 相似度：{res['score']:.4f}")

# ====================== 3. 直接计算相似度（Similarity） ======================
sim = Similarity('m3e-base')
score = sim.similarity("苹果发布新款手机", "iPhone 15上市")
print(f"\n直接计算相似度：{score:.4f}")

输出：

向量形状：(3, 768)

语义检索结果：
  文本：苹果发布新款手机 | 相似度：0.9892
  文本：iPhone 15上市 | 相似度：0.9105

直接计算相似度：0.9105