# 默认算分逻辑 - 快速总结

## 一句话回答

**默认算分逻辑是：AI 直接判断语义相似度**

---

## 详细说明

### `semantic_similarity.py`
```python
from lib.semantic_similarity import compare_phrases

result = await compare_phrases("深度学习", "神经网络")
# 使用: AI 直接判断（唯一方法）
# 返回: {"说明": "...", "相似度": 0.85}
```

### `text_embedding.py` 的 `compare_phrases()`
```python
from lib.text_embedding import compare_phrases

result = await compare_phrases("深度学习", "神经网络")
# 使用: AI 直接判断（默认，与 semantic_similarity 相同）
# 返回: {"说明": "...", "相似度": 0.85}
```

**两者默认行为完全一致！**

---

## 工作流程

```
输入: "深度学习" vs "神经网络"
  ↓
发送给 AI 的 Prompt:
  "请计算以下两个文本的语义相似度，输出 0-1 之间的分数"
  ↓
AI 理解语义
  ↓
AI 返回:
  {
    "说明": "两者都是人工智能领域的核心概念，深度学习基于神经网络...",
    "相似度": 0.85
  }
```

---

## text_embedding 的额外功能

除了默认的 AI 判断，还支持：

```python
# 方法 1: AI 直接判断（默认）⭐
result = await compare_phrases("A", "B")
# 或明确指定
result = await compare_phrases("A", "B", method="ai_direct")

# 方法 2: 余弦相似度（基于向量）
result = await compare_phrases("A", "B", method="cosine")

# 方法 3: 欧氏距离
result = await compare_phrases("A", "B", method="euclidean")

# 方法 4: 曼哈顿距离
result = await compare_phrases("A", "B", method="manhattan")

# 方法 5: 点积
result = await compare_phrases("A", "B", method="dot_product")
```

---

## 准确度对比

```
ai_direct (默认)   ⭐⭐⭐⭐⭐ 最准确
cosine             ⭐⭐⭐⭐
euclidean          ⭐⭐⭐
manhattan          ⭐⭐⭐
dot_product        ⭐⭐⭐
```

---

## 速度对比（已有缓存）

```
dot_product        ⚡⚡⚡⚡⚡ 最快
manhattan          ⚡⚡⚡⚡
euclidean          ⚡⚡⚡⚡
cosine             ⚡⚡⚡
ai_direct          ⚡⚡⚡⚡⚡ (缓存命中后极快)
```

---

## 推荐使用

### 场景 1: 日常使用（99% 的情况）
```python
# 不传 method 参数，使用默认值
result = await compare_phrases("深度学习", "神经网络")
```
**原因**: 准确度最高，有缓存，第二次极快

---

### 场景 2: 批量计算
```python
# 如果要计算大量相似度
result = await compare_phrases("A", "B", method="cosine", dim=128)
```
**原因**: 向量生成后，计算速度快

---

### 场景 3: 与 semantic_similarity 兼容
```python
# 直接替换导入，无需修改代码
from lib.text_embedding import compare_phrases  # 改这里
result = await compare_phrases("A", "B")  # 其他代码不变
```

---

## 常见问题

### Q1: 为什么默认用 AI 判断？
**A**: 因为准确度最高，且有缓存机制，第二次调用极快。

### Q2: AI 判断会不会很慢？
**A**:
- 首次调用: 需要 1-3 秒（调用 AI）
- 第二次调用: 几乎瞬间（从缓存读取）

### Q3: 什么时候用其他方法？
**A**:
- 批量计算相似度 → 用 `cosine`
- 需要极快速度 → 用向量方法
- 其他情况 → 用默认的 `ai_direct`

### Q4: 如何切换算分方法？
**A**:
```python
# 默认（AI 判断）
result = await compare_phrases("A", "B")

# 切换到余弦相似度
result = await compare_phrases("A", "B", method="cosine")
```

---

## 运行示例

```bash
# 查看详细说明
cat examples/scoring_logic_explanation.md

# 运行交互式演示
python examples/demo_scoring_methods.py

# 运行对比示例
python examples/compare_with_semantic_similarity.py
```

---

## 核心结论

1. ✅ **默认算分逻辑**: AI 直接判断语义相似度
2. ✅ **与 semantic_similarity 完全一致**: 返回格式和算分方法都相同
3. ✅ **99% 情况用默认值就好**: 不需要指定 method 参数
4. ✨ **额外功能**: 支持多种向量算分方法（可选）
5. 🚀 **有缓存机制**: 第二次调用极快

---

## 快速参考

```python
# 最简单的用法（推荐）⭐
from lib.text_embedding import compare_phrases

result = await compare_phrases("深度学习", "神经网络")
print(result['相似度'])  # 0.85
print(result['说明'])     # AI 给出的详细理由
```

就这么简单！