# 默认算分逻辑说明

## 两个模块的默认算分逻辑对比

### 1. `semantic_similarity.py` 的默认算分逻辑

#### 默认方法
**AI 直接判断**（唯一方法）

#### 工作原理
```
用户输入: "深度学习" vs "神经网络"
    ↓
发送给 AI 的 Prompt:
    从语意角度,判断【深度学习】和【神经网络】的相似度,从0-1打分，输出json格式
    ```json
    {
      "说明": "简明扼要说明理由",
      "相似度": 0.0,
    }
    ```
    ↓
AI 理解语义后返回:
    {
      "说明": "两者都是人工智能领域的核心概念，深度学习是基于神经网络的...",
      "相似度": 0.85
    }
```

#### 特点
- ✅ **优点**: AI 深度理解语义，准确度高
- ✅ **优点**: 能理解上下文、隐含关系
- ⚠️ **缺点**: 需要调用 AI，速度较慢（首次）
- ⚠️ **缺点**: 有 token 成本

---

### 2. `text_embedding.py` 的默认算分逻辑

#### 默认方法
**AI 直接判断** (`method="ai_direct"`)

与 `semantic_similarity.py` 完全相同！

#### 工作原理（默认）
```
用户输入: "深度学习" vs "神经网络"
    ↓
发送给 AI 的 Prompt:
    请计算以下两个文本的语义相似度，输出 0-1 之间的分数。

    文本A：【深度学习】
    文本B：【神经网络】

    输出格式：
    ```json
    {
      "similarity": 0.0,
      "method": "semantic_analysis",
      "explanation": "相似度判断的理由"
    }
    ```
    ↓
AI 返回结果后，转换为兼容格式:
    {
      "说明": "相似度判断的理由",
      "相似度": 0.85
    }
```

#### 额外支持的算分方法

除了默认的 AI 直接判断，还支持基于向量的计算方法：

---

## 详细算分方法对比

### 方法 1: `ai_direct` （默认，推荐）⭐

**原理**: AI 直接理解语义并打分

**优点**:
- ✅ 准确度最高
- ✅ 能理解复杂的语义关系
- ✅ 能理解上下文、同义词、隐含意义

**缺点**:
- ⚠️ 需要调用 AI（但有缓存，第二次很快）
- ⚠️ 有 token 成本

**适用场景**:
- 需要高准确度的语义分析
- 文本有复杂的语义关系
- 不在意首次调用的时间成本

**示例**:
```python
result = await compare_phrases("深度学习", "神经网络", method="ai_direct")
# 相似度: 0.85
# 说明: "两者都是AI领域的核心概念..."
```

---

### 方法 2: `cosine` （余弦相似度）

**原理**:
1. 先把两段文字转换成向量（数字数组）
2. 计算两个向量的夹角
3. 夹角越小 → 相似度越高

**数学公式**:
```
相似度 = cos(θ) = (A·B) / (|A| × |B|)

其中:
- A, B 是两个向量
- A·B 是点积
- |A|, |B| 是向量的模（长度）
```

**取值范围**: -1 到 1
- 1: 完全相同
- 0: 无关
- -1: 完全相反

**优点**:
- ✅ 计算速度快（向量生成后）
- ✅ 数学方法，结果稳定
- ✅ 不受向量长度影响

**缺点**:
- ⚠️ 需要先生成向量（首次需要调用 AI）
- ⚠️ 对语义的理解不如 AI 直接判断

**适用场景**:
- 需要批量计算相似度
- 需要结果稳定可复现
- 已经有向量，不想再调用 AI

**示例**:
```python
result = await compare_phrases("深度学习", "神经网络", method="cosine", dim=128)
# 相似度: 0.78
# 说明: "基于 cosine 方法计算的向量相似度"
```

---

### 方法 3: `euclidean` （欧氏距离）

**原理**:
1. 把文字转换成向量（多维空间中的点）
2. 计算两点之间的直线距离
3. 距离越近 → 相似度越高

**数学公式**:
```
距离 = √[(a1-b1)² + (a2-b2)² + ... + (an-bn)²]

相似度 = 1 / (1 + 距离)  # 归一化到 0-1
```

**取值范围**: 0 到 1
- 1: 完全相同（距离=0）
- 0: 完全不同（距离→∞）

**优点**:
- ✅ 直观（就是空间距离）
- ✅ 计算简单

**缺点**:
- ⚠️ 受向量长度影响
- ⚠️ 高维空间中可能不够准确

**适用场景**:
- 需要直观的距离度量
- 向量长度有意义的场景

**示例**:
```python
result = await compare_phrases("深度学习", "神经网络", method="euclidean", dim=128)
# 相似度: 0.65
# 说明: "基于 euclidean 方法计算的向量相似度"
```

---

### 方法 4: `manhattan` （曼哈顿距离）

**原理**:
类似走城市街道，只能沿坐标轴方向移动

**数学公式**:
```
距离 = |a1-b1| + |a2-b2| + ... + |an-bn|

相似度 = 1 / (1 + 距离)  # 归一化到 0-1
```

**取值范围**: 0 到 1

**优点**:
- ✅ 对噪声不敏感
- ✅ 计算快

**缺点**:
- ⚠️ 不适合高维空间

**适用场景**:
- 数据有噪声
- 需要对异常值鲁棒

**示例**:
```python
result = await compare_phrases("深度学习", "神经网络", method="manhattan", dim=128)
# 相似度: 0.62
# 说明: "基于 manhattan 方法计算的向量相似度"
```

---

### 方法 5: `dot_product` （点积）

**原理**:
计算两个向量的点积，用 sigmoid 归一化

**数学公式**:
```
点积 = a1×b1 + a2×b2 + ... + an×bn

相似度 = 1 / (1 + e^(-点积))  # sigmoid 归一化
```

**取值范围**: 0 到 1

**优点**:
- ✅ 计算最快
- ✅ 考虑向量长度（方向+幅度）

**缺点**:
- ⚠️ 受向量长度影响大

**适用场景**:
- 向量长度有意义
- 需要极快的计算速度

**示例**:
```python
result = await compare_phrases("深度学习", "神经网络", method="dot_product", dim=128)
# 相似度: 0.71
# 说明: "基于 dot_product 方法计算的向量相似度"
```

---

## 方法选择指南

### 📊 准确度排名
```
ai_direct > cosine > euclidean ≈ manhattan ≈ dot_product
```

### ⚡ 速度排名（向量已生成）
```
dot_product > manhattan > euclidean > cosine >> ai_direct
```

### 💰 成本排名
```
ai_direct (需要调用 AI) >> 向量方法 (首次需要生成向量)
```

---

## 实际测试对比

```python
# 测试短语
phrase_a = "深度学习"
phrase_b = "神经网络"

# 不同方法的结果（示例）
┌──────────────┬──────────┬────────────────────────────┐
│ 方法         │ 相似度   │ 说明                       │
├──────────────┼──────────┼────────────────────────────┤
│ ai_direct    │ 0.850    │ AI 深度理解，最准确        │
│ cosine       │ 0.780    │ 向量夹角，次准确           │
│ euclidean    │ 0.650    │ 欧氏距离                   │
│ manhattan    │ 0.620    │ 曼哈顿距离                 │
│ dot_product  │ 0.710    │ 点积                       │
└──────────────┴──────────┴────────────────────────────┘
```

---

## 默认选择建议

### 如果你不确定用哪个，建议：

**1. 默认使用 `ai_direct`** ⭐
```python
# 不传 method 参数，默认就是 ai_direct
result = await compare_phrases("深度学习", "神经网络")
```

**原因**:
- ✅ 准确度最高
- ✅ 有缓存机制，第二次很快
- ✅ 与 semantic_similarity 完全一致

---

**2. 批量计算时可以考虑 `cosine`**
```python
# 如果要计算大量相似度，可以先生成所有向量
model = SentenceModel(dim=128)

# 生成向量（只需一次）
vectors = await model.encode(all_texts)

# 然后用 cosine 快速计算
for i in range(len(all_texts)):
    for j in range(i+1, len(all_texts)):
        result = await compare_phrases(
            all_texts[i], all_texts[j],
            method="cosine"
        )
```

---

## 总结

### `semantic_similarity.py`
- **唯一方法**: AI 直接判断
- **返回格式**: `{说明, 相似度}`

### `text_embedding.py` 的 `compare_phrases()`
- **默认方法**: AI 直接判断（与 semantic_similarity 相同）
- **返回格式**: `{说明, 相似度}` （完全兼容）
- **额外功能**: 支持 5 种计算方法
  - `ai_direct` - AI 判断（默认）⭐
  - `cosine` - 余弦相似度
  - `euclidean` - 欧氏距离
  - `manhattan` - 曼哈顿距离
  - `dot_product` - 点积

### 推荐
- **日常使用**: 默认 `ai_direct`，不需要指定 method
- **批量计算**: 考虑 `cosine`
- **完全兼容**: 可以直接替换 `semantic_similarity.compare_phrases()`