# text_embedding 使用说明

## 这是什么？

**精简的文本相似度计算模块**，基于 similarities 库（BERT 向量模型）。

- ✅ 只有 **1 个函数**：`compare_phrases()`
- ✅ 支持 **4 种模型**
- ✅ 返回格式兼容 `semantic_similarity.py`
- ✅ 零成本，本地运行
- ✅ 总共 163 行代码

---

## 安装

```bash
pip install -U similarities torch
```

---

## 快速开始

```python
from lib.text_embedding import compare_phrases

result = compare_phrases("如何更换花呗绑定银行卡", "花呗更改绑定银行卡")

print(result['相似度'])  # 0.855
print(result['说明'])     # "基于向量模型计算的语义相似度为 高 (0.86)"
```

---

## 支持的模型

### 简称方式（推荐）

```python
# 1. chinese（默认）- 中文通用模型
result = compare_phrases("文本1", "文本2")
result = compare_phrases("文本1", "文本2", model_name="chinese")

# 2. multilingual - 多语言模型（中英韩日德意等）
result = compare_phrases("Hello", "Hi", model_name="multilingual")

# 3. paraphrase - 中文长文本模型
result = compare_phrases("长文本1...", "长文本2...", model_name="paraphrase")

# 4. sentence - 中文短句子模型
result = compare_phrases("短句1", "短句2", model_name="sentence")
```

### 完整名称方式

```python
result = compare_phrases(
    "文本1", "文本2",
    model_name="shibing624/text2vec-base-chinese"
)
```

### 模型列表

| 简称 | 完整名称 | 说明 |
|------|---------|------|
| `chinese` | `shibing624/text2vec-base-chinese` | 中文通用（默认） |
| `multilingual` | `shibing624/text2vec-base-multilingual` | 多语言 |
| `paraphrase` | `shibing624/text2vec-base-chinese-paraphrase` | 中文长文本 |
| `sentence` | `shibing624/text2vec-base-chinese-sentence` | 中文短句子 |

---

## 接口说明

```python
compare_phrases(
    phrase_a: str,           # 第一个短语
    phrase_b: str,           # 第二个短语
    model_name: str = "chinese"  # 模型（可选）
) -> Dict[str, Any]
```

**返回格式：**
```python
{
    "说明": "基于向量模型计算的语义相似度为 高 (0.86)",
    "相似度": 0.855
}
```

---

## 运行示例

```bash
python lib/text_embedding.py
```

**输出：**
```
示例 1: 默认模型（chinese）
相似度: 0.855
说明: 基于向量模型计算的语义相似度为 高 (0.86)

示例 2: 使用默认模型
相似度: 0.486
说明: 基于向量模型计算的语义相似度为 较低 (0.49)

示例 3: 不相关的短语
相似度: 0.187
说明: 基于向量模型计算的语义相似度为 低 (0.19)

示例 4: 多语言模型（multilingual）
相似度: 0.950
说明: 基于向量模型计算的语义相似度为 极高 (0.95)

============================================================
支持的模型:
------------------------------------------------------------
  chinese         -> shibing624/text2vec-base-chinese
  multilingual    -> shibing624/text2vec-base-multilingual
  paraphrase      -> shibing624/text2vec-base-chinese-paraphrase
  sentence        -> shibing624/text2vec-base-chinese-sentence
```

---

## 使用场景

### 场景 1: 中文短文本（默认）
```python
result = compare_phrases("深度学习", "神经网络")
# 使用 chinese 模型
```

### 场景 2: 多语言文本
```python
result = compare_phrases("Hello", "Hi", model_name="multilingual")
result = compare_phrases("こんにちは", "你好", model_name="multilingual")
```

### 场景 3: 中文长文本
```python
long_text_1 = "这是一段很长的文本..."
long_text_2 = "这是另一段很长的文本..."
result = compare_phrases(long_text_1, long_text_2, model_name="paraphrase")
```

### 场景 4: 中文短句子
```python
result = compare_phrases("你好", "您好", model_name="sentence")
```

---

## 默认算分逻辑

**余弦相似度（基于 BERT 向量）**

```
输入: "深度学习" vs "神经网络"
    ↓
BERT 模型转换为向量
    ↓
计算余弦相似度
    ↓
返回: 0.486
```

---

## 与 semantic_similarity 对比

| 特性 | semantic_similarity | text_embedding |
|------|---------------------|----------------|
| **算分方法** | LLM 判断 | BERT 向量 |
| **返回格式** | `{说明, 相似度}` | `{说明, 相似度}` ✅ |
| **速度** | 慢（需要调用 AI） | 快 |
| **成本** | 有 token 成本 | **零成本** |
| **模型数量** | 1 个 | **4 个** |
| **代码行数** | 508 行 | **163 行** |

---

## 常见问题

### Q1: 第一次运行会下载模型吗？
**A**: 是的，第一次使用某个模型时会自动下载（约 400MB），之后就很快了。

### Q2: 可以同时使用多个模型吗？
**A**: 可以！代码会自动缓存已加载的模型。
```python
# 第一次调用会下载 chinese 模型
result1 = compare_phrases("文本1", "文本2")

# 第一次调用会下载 multilingual 模型
result2 = compare_phrases("Hello", "Hi", model_name="multilingual")

# 第二次调用直接使用缓存的模型，速度很快
result3 = compare_phrases("文本3", "文本4")
```

### Q3: 哪个模型最好？
**A**:
- 中文短文本：`chinese`（默认）
- 多语言：`multilingual`
- 中文长文本（段落级别）：`paraphrase`
- 中文短句子：`sentence`

### Q4: 如何选择模型？
**A**: 不确定就用默认的 `chinese`，99% 的情况都够用！

---

## 总结

**只需要记住：**

```python
from lib.text_embedding import compare_phrases

# 基础用法（99% 的情况）
result = compare_phrases("文本A", "文本B")

# 切换模型
result = compare_phrases("文本A", "文本B", model_name="multilingual")
```

**支持 4 种模型：**
- `chinese` - 默认
- `multilingual` - 多语言
- `paraphrase` - 长文本
- `sentence` - 短句子

就这么简单！