# text_embedding 使用说明

## 这是什么？

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

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

## 为什么需要它？

传统的文字比较只能看字面：
- "深度学习" vs "神经网络" → 完全不同 ❌

使用语义分析可以理解含义：
- "深度学习" vs "神经网络" → 相似度 0.85 ✅
- "深度学习" vs "今天吃饭" → 相似度 0.05 ✅

---

## 快速开始

### 安装依赖
```bash
pip install numpy
# agents 和 lib.client 需要在项目中配置
```

### 基础使用

```python
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`

```python
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
```

**运行:**
```bash
python examples/example_text_embedding_basic.py
```

---

### 方式2: 使用 SentenceModel 类

**文件:** `examples/example_text_embedding_model.py`

```python
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
```

**运行:**
```bash
python examples/example_text_embedding_model.py
```

---

### 方式3: 实际应用场景

**文件:** `examples/example_text_embedding_usecase.py`

包含三个实际应用：

#### 应用1: 语义搜索
从大量文档中找出与查询最相关的内容

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

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

#### 应用2: 文本聚类
把意思相近的文本自动分组

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

#### 应用3: 重复检测
识别意思相同但表述不同的文本

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

**运行:**
```bash
python examples/example_text_embedding_usecase.py
```

---

## API 接口说明

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

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

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

**返回格式:**
```python
{
    "说明": "简明扼要说明理由",
    "相似度": 0.85  # 0-1之间的分数
}
```

**例子:**
```python
# 与 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()` - 文本向量化

```python
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`: 完整字典（含语义摘要）

**例子:**
```python
# 返回向量
vector = await encode("你好")  # numpy 数组 (1536,)

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

---

### 2. `similarity()` - 相似度计算

```python
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`: 点积

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

---

### 3. `SentenceModel` - 模型类

```python
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`
```python
'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 需要时间，使用异步可以提高效率。

```python
# 错误 ❌
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/` 目录下，可以手动删除。

---

## 完整示例运行

```bash
# 示例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`** → 封装好的类，更方便使用

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