how/examples/scoring_logic_explanation.md

默认算分逻辑说明

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

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 成本

适用场景:

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

示例:

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

示例:

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: 完全不同（距离→∞）

优点:

• ✅ 直观（就是空间距离）
• ✅ 计算简单

缺点:

• ⚠️ 受向量长度影响
• ⚠️ 高维空间中可能不够准确

适用场景:

• 需要直观的距离度量
• 向量长度有意义的场景

示例:

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

优点:

• ✅ 对噪声不敏感
• ✅ 计算快

缺点:

• ⚠️ 不适合高维空间

适用场景:

• 数据有噪声
• 需要对异常值鲁棒

示例:

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

优点:

• ✅ 计算最快
• ✅ 考虑向量长度（方向+幅度）

缺点:

• ⚠️ 受向量长度影响大

适用场景:

• 向量长度有意义
• 需要极快的计算速度

示例:

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) >> 向量方法 (首次需要生成向量)

---

实际测试对比

# 测试短语
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 ⭐

# 不传 method 参数，默认就是 ai_direct
result = await compare_phrases("深度学习", "神经网络")

原因:

• ✅ 准确度最高
• ✅ 有缓存机制，第二次很快
• ✅ 与 semantic_similarity 完全一致

---

2. 批量计算时可以考虑 cosine

# 如果要计算大量相似度，可以先生成所有向量
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()