feat: 添加 F1 Score 算法原理及应用说明文档

zhch/评估算法说明/F1.md

@@ -0,0 +1,123 @@
+# F1 Score 算法原理、作用和意义
+
+## 1. 算法原理
+
+从代码中可以看到，F1 Score的计算公式非常简洁：
+
+```python
+def f1_score(precision, recall):
+    precision, recall = max(0.0, min(1.0, precision)), max(0.0, min(1.0, recall))
+    return 0.0 if precision + recall == 0 else 2 * (precision * recall) / (precision + recall)
+```
+
+数学公式：
+F1 = 2 × (Precision × Recall) / (Precision + Recall)
+
+这实际上是 Precision 和 Recall 的**调和平均数**（Harmonic Mean）。
+
+## 2. 核心概念
+
+Precision（精确率/查准率）
+- 定义：在所有系统预测为正例的样本中，真正为正例的比例
+- 公式：Precision = TP / (TP + FP)
+- 含义：系统回答的内容中有多少是正确的
+  
+Recall（召回率/查全率）
+- 定义：在所有真正为正例的样本中，被系统正确预测为正例的比例
+- 公式：Recall = TP / (TP + FN)
+- 含义：真实答案中有多少被系统正确回答了
+  
+## 3. 在DSPy RAG系统中的应用
+
+在您的代码中，SemanticF1 用于评估RAG系统的回答质量：
+```python
+class SemanticRecallPrecision(Signature):
+    recall: float = OutputField(desc="fraction (out of 1.0) of ground truth covered by the system response")
+    precision: float = OutputField(desc="fraction (out of 1.0) of system response covered by the ground truth")
+```
+语义层面的理解：
+- Precision（语义精确率）：系统回答中有多少内容是基于真实答案的（避免幻觉）
+- Recall（语义召回率）：真实答案中的关键信息有多少被系统回答覆盖到了（避免遗漏）
+  
+## 4. F1 Score的作用和意义
+
+### 4.1 平衡性指标
+F1 Score 解决了单独使用 Precision 或 Recall 的问题：
+```python
+# 极端情况1：高Precision，低Recall
+precision = 1.0, recall = 0.1  # 系统很谨慎，但遗漏很多
+f1 = 2 * (1.0 * 0.1) / (1.0 + 0.1) = 0.18
+
+# 极端情况2：低Precision，高Recall  
+precision = 0.1, recall = 1.0  # 系统回答很全，但有很多错误
+f1 = 2 * (0.1 * 1.0) / (0.1 + 1.0) = 0.18
+
+# 平衡情况：
+precision = 0.8, recall = 0.8
+f1 = 2 * (0.8 * 0.8) / (0.8 + 0.8) = 0.8
+```
+### 4.2 调和平均数的特性
+- 对低值敏感：如果 Precision 或 Recall 中任一项很低，F1 Score 就会很低
+- 鼓励平衡：只有当两个指标都比较高时，F1 才会高
+  
+## 5. 在RAG评估中的实际意义
+
+### 5.1 质量评估维度
+```python
+# 在DSPy中的实际使用
+scores = self.module(
+    question=example.question, 
+    ground_truth=example.response, 
+    system_response=pred.response
+)
+score = f1_score(scores.precision, scores.recall)
+```
+
+### 5.2 不同场景的含义
+
+高F1分数（0.8+）：
+- 系统回答既准确又完整
+- 很少有错误信息（高Precision）
+- 很少遗漏重要信息（高Recall）
+  
+中等F1分数（0.5-0.8）：
+- 系统基本可用，但有改进空间
+- 可能存在一定程度的遗漏或错误
+  
+低F1分数（<0.5）：
+- 系统回答质量较差
+- 要么遗漏太多，要么错误太多
+  
+## 6. 代码中的实现细节
+```python
+def f1_score(precision, recall):
+    # 确保值在[0,1]范围内
+    precision, recall = max(0.0, min(1.0, precision)), max(0.0, min(1.0, recall))
+    # 避免除零错误
+    return 0.0 if precision + recall == 0 else 2 * (precision * recall) / (precision + recall)
+```
+关键特点：
+1. 边界处理：确保输入值在 [0,1] 范围内
+2. 零值处理：当两个指标都为0时，返回0（避免除零）
+3. 数值稳定性：处理了各种边界情况
+  
+## 7. 在MLflow实验中的应用
+
+从您的notebook可以看到：
+```python
+# 记录F1分数作为主要评估指标
+mlflow.log_metric("semantic_f1_score", result.score)
+```
+这使得您可以：
+- 跟踪模型改进：比较不同优化策略的效果
+- A/B测试：比较不同模型版本的性能
+- 调参指导：F1分数可以指导超参数调优
+  
+## 8. 总结
+
+F1 Score 在RAG系统评估中是一个**综合性的质量指标**：
+
+- 平衡考虑了回答的准确性和完整性
+- 避免了单一指标的局限性
+- 提供了系统整体性能的量化评估
+- 支持了模型的迭代改进和比较