how/examples

text_embedding 使用说明

这是什么？

text_embedding.py 是一个文本语义分析工具，做两件事：

1. 文本向量化 - 把文字变成数字向量
2. 相似度计算 - 判断两段文字有多相似

为什么需要它？

传统的文字比较只能看字面：

• "深度学习" vs "神经网络" → 完全不同 ❌

使用语义分析可以理解含义：

• "深度学习" vs "神经网络" → 相似度 0.85 ✅
• "深度学习" vs "今天吃饭" → 相似度 0.05 ✅

---

快速开始

安装依赖

pip install numpy
# agents 和 lib.client 需要在项目中配置

基础使用

import asyncio
from lib.text_embedding import encode, similarity

async def main():
    # 1. 文本向量化
    vector = await encode("人工智能很有趣")
    print(vector.shape)  # (1536,) - 1536个数字

    # 2. 计算相似度
    result = await similarity("深度学习", "神经网络")
    print(result['similarity'])  # 0.85

asyncio.run(main())

---

三种使用方式

方式1: 直接调用函数（推荐）

文件: examples/example_text_embedding_basic.py

from lib.text_embedding import encode, similarity

# 单个文本转向量
vector = await encode("你好世界", dim=128)

# 批量转换
vectors = await encode(["文本1", "文本2", "文本3"], dim=128)

# 计算相似度（AI直接判断，最准确）
result = await similarity("深度学习", "神经网络")
print(result['similarity'])  # 0.85

运行:

python examples/example_text_embedding_basic.py

---

方式2: 使用 SentenceModel 类

文件: examples/example_text_embedding_model.py

from lib.text_embedding import SentenceModel

# 创建模型
model = SentenceModel(dim=128)

# 文本向量化
vector = await model.encode("机器学习")
vectors = await model.encode(["文本1", "文本2"])

# 计算相似度
score = await model.similarity("深度学习", "神经网络")
print(score)  # 0.85

运行:

python examples/example_text_embedding_model.py

---

方式3: 实际应用场景

文件: examples/example_text_embedding_usecase.py

包含三个实际应用：

应用1: 语义搜索

从大量文档中找出与查询最相关的内容

query = "什么是深度学习？"
documents = ["文档1", "文档2", ...]

# 找出最相关的文档
for doc in documents:
    score = await model.similarity(query, doc)
    # 按相似度排序

应用2: 文本聚类

把意思相近的文本自动分组

texts = ["AI很强大", "深度学习很好", "今天吃饭", "晚餐美味"]
# 自动找出相似的文本对（如："AI很强大" 和 "深度学习很好"）

应用3: 重复检测

识别意思相同但表述不同的文本

q1 = "如何学习Python？"
q2 = "怎样学好Python？"
# 检测相似度 > 0.7 的问题，视为重复

运行:

python examples/example_text_embedding_usecase.py

---

API 接口说明

0. compare_phrases() - 兼容 semantic_similarity.py 的接口 ⭐

返回格式与 semantic_similarity.compare_phrases() 完全一致

await compare_phrases(
    phrase_a,          # 第一个短语
    phrase_b,          # 第二个短语
    model_name='openai/gpt-4.1-mini',
    temperature=0.0,
    method="ai_direct",  # 计算方法
    use_cache=True
)

返回格式:

{
    "说明": "简明扼要说明理由",
    "相似度": 0.85  # 0-1之间的分数
}

例子:

# 与 semantic_similarity 完全兼容
result = await compare_phrases("深度学习", "神经网络")
print(result['相似度'])  # 0.85
print(result['说明'])     # "两者都是AI领域的核心概念..."

# 额外支持多种计算方法
result = await compare_phrases("文本1", "文本2", method="cosine")

与 semantic_similarity 的区别:

• ✅ 返回格式完全一致
• ✅ 支持 AI 直接判断（与 semantic_similarity 相同）
• ✨ 额外支持多种向量计算方法（cosine, euclidean 等）

---

1. encode() - 文本向量化

await encode(
    text,              # 单个文本或文本列表
    dim=1536,          # 向量维度
    model_name='openai/gpt-4.1-mini',  # 模型
    use_cache=True,    # 是否使用缓存
    return_dict=False  # 是否返回完整信息
)

返回:

• return_dict=False: numpy 数组（默认）
• return_dict=True: 完整字典（含语义摘要）

例子:

# 返回向量
vector = await encode("你好")  # numpy 数组 (1536,)

# 返回完整信息
result = await encode("你好", return_dict=True)
print(result['semantic_summary'])  # 语义摘要
print(result['embedding'])         # 向量

---

2. similarity() - 相似度计算

await similarity(
    text_a,            # 第一个文本
    text_b,            # 第二个文本
    method="ai_direct",  # 计算方法
    model_name='openai/gpt-4.1-mini',
    use_cache=True
)

计算方法:

• ai_direct: AI 直接判断（最准确，推荐）
• cosine: 余弦相似度（基于向量）
• euclidean: 欧氏距离
• manhattan: 曼哈顿距离
• dot_product: 点积

返回:

{
    "similarity": 0.85,          # 相似度分数 (0-1)
    "method": "ai_direct",       # 使用的方法
    "explanation": "两者高度相关..."  # 说明
}

---

3. SentenceModel - 模型类

model = SentenceModel(
    model_name='openai/gpt-4.1-mini',
    dim=1536,
    use_cache=True
)

# 向量化
vector = await model.encode("文本")
vectors = await model.encode(["文本1", "文本2"])

# 相似度（直接返回分数）
score = await model.similarity("文本A", "文本B")
print(score)  # 0.85

---

参数说明

向量维度 dim

• 向量的长度（数字个数）
• 默认: 1536（与 OpenAI embeddings 兼容）
• 建议: 测试时用 128 或 256，节省时间

模型 model_name

'openai/gpt-4.1-mini'        # 默认，速度快
'anthropic/claude-sonnet-4.5' # 质量高
'google/gemini-2.5-pro'      # Google 模型

缓存 use_cache

• True: 相同输入会从缓存读取（速度快 10-100倍）
• False: 每次都调用 AI（用于测试）

---

与 text2vec 的对比

特性	text2vec	text_embedding.py
文本向量化	✅ BERT 模型	✅ AI Agent 生成
相似度计算	✅ 余弦距离	✅ AI 判断 + 多种方法
缓存机制	❌ 无	✅ 自动缓存
多模型支持	❌ 固定模型	✅ GPT/Claude/Gemini
API 风格	encode(), similarity()	✅ 完全兼容 + 扩展
中文支持	✅	✅

---

常见问题

Q1: 为什么要用 await 和 async？

因为调用 AI 需要时间，使用异步可以提高效率。

# 错误 ❌
result = similarity("A", "B")

# 正确 ✅
result = await similarity("A", "B")

# 必须在 async 函数中
async def main():
    result = await similarity("A", "B")

asyncio.run(main())

Q2: 向量维度选多大？

• 测试: 128 或 256（速度快）
• 生产: 1536（质量高，与 OpenAI 兼容）

Q3: 使用哪种相似度计算方法？

• 推荐: ai_direct（最准确）
• 快速: cosine（基于向量，速度快但需要生成向量）

Q4: 缓存文件在哪？

在 cache/text_embedding/ 目录下，可以手动删除。

---

完整示例运行

# 示例1: 基础用法
python examples/example_text_embedding_basic.py

# 示例2: SentenceModel 类
python examples/example_text_embedding_model.py

# 示例3: 实际应用场景
python examples/example_text_embedding_usecase.py

# 模块自带示例
python lib/text_embedding.py

---

总结

简单来说:

• encode() → 把文字变成数字
• similarity() → 判断两段文字有多像
• SentenceModel → 封装好的类，更方便使用

什么时候用:

• 语义搜索（在大量文档中找相关内容）
• 文本聚类（自动分组相似内容）
• 重复检测（找出意思相同的文本）
• 推荐系统（找相似的文章/商品）