| # 训练数据评估脚本使用说明 | |
| ## 一、评估结构 | |
| 解析conversations数据，分割成pairs | |
| - **Pair 1**: system+tools+user -> function_call | |
| - **Pair 2**: system+tools+user+observation -> function_call | |
| - **Pair 3**: system+tools+user+observation -> gpt | |
| ## 二、评估指标 | |
| ### 2.1 基本统计指标 | |
| - **total_conversations**: 总对话数量 | |
| - **total_pairs**: 总评估对数量 | |
| ### 2.2 Pair级别指标 | |
| #### Pair 1 指标 | |
| - **pair1.total**: Pair 1 的总数量 | |
| - **pair1.accuracy**: Pair 1 的准确率 | |
| - **pair1.precision@1**: Pair 1 的工具名称精确匹配率 | |
| #### Pair 2 指标 | |
| - **pair2.total**: Pair 2 的总数量 | |
| - **pair2.accuracy**: Pair 2 的准确率 | |
| - **pair2.precision@1**: Pair 2 的工具名称精确匹配率 | |
| - **pair2_consider_recall.total**: 考虑recall条件的Pair 2数量 | |
| - **pair2_consider_recall.accuracy**: 考虑recall条件的Pair 2准确率 | |
| - **pair2_consider_recall.precision@1**: 考虑recall条件的Pair 2工具名称精确匹配率 | |
| #### Pair 3 指标 | |
| - **pair3.total**: Pair 3 的总数量 | |
| - **pair3.answer_score**: Pair 3 的文本生成质量得分 | |
| ### 2.3 Recall指标 | |
| - **recall_metrics.total_pairs**: 参与recall评估的pair总数 | |
| - **recall_metrics.recall@5_1**: recall=1的pair数量 | |
| - **recall_metrics.recall@5_0**: recall=0的pair数量 | |
| - **recall_metrics.recall_rate**: recall率 | |
| ### 2.4 总体指标 | |
| - **overall.total**: 总体评估对数量 | |
| - **overall.accuracy**: 总体准确率 | |
| - **overall.precision@1**: 总体工具名称精确匹配率 | |
| - **overall.answer_score**: 总体文本生成质量得分 | |
| ## 三、指标说明 | |
| ### 3.1 准确率 (Accuracy) | |
| - **计算原理**: 对于工具调用pair，比较预测的工具调用与目标工具调用的一致性，包括工具名称和参数匹配 | |
| - **评分规则**: | |
| - 工具名称匹配: 50%权重 | |
| - 参数匹配: 50%权重 | |
| - 最终得分范围: 0-1 | |
| ### 3.2 精确匹配率 (Precision@1) | |
| - **计算原理**: 仅考虑工具名称是否完全匹配 | |
| - **评分规则**: 工具名称完全匹配得1分，否则得0分 | |
| ### 3.3 文本生成质量得分 (Answer Score) | |
| - **计算原理**: 使用Gemini-2.5-flash模型评估文本生成的四个维度 | |
| - **评估维度**: | |
| - 内容准确性 (0-10分) | |
| - 完整性 (0-10分) | |
| - 表达质量 (0-10分) | |
| - 格式一致性 (0-10分) | |
| - **最终得分**: 四个维度的平均分除以10，范围0-1 | |
| ### 3.4 Recall指标 | |
| - **计算原理**: 基于Pair 1的预测结果调用检索工具，检查Pair 2的目标工具是否在（调用retrieval_tool得到的）检索结果的前5个中 | |
| - **计算条件**: 仅在Pair 1的precision@1=1.0且有有效预测query时才计算 | |
| - **评分规则**: 目标工具在检索结果中得1分，否则得0分 | |
| ### 3.5 考虑Recall的指标 | |
| - **pair2_consider_recall**: 仅在recall=1的条件下计算Pair 2的指标 | |
| - **意义**: 评估在工具检索成功情况下的模型表现 | |
| ## 四、运行命令 | |
| python data_evaluation.py | |
| ## 五、默认输入输出 | |
| ### 5.1 输入文件 | |
| - **主要输入**: `data/9.17_evaluate_data_top5_final.json` | |
| - 包含待评估的对话数据，格式为conversations数组 | |
| - 每个对话包含system、tools、conversations字段 | |
| #### 5.1.1 输入文件格式要求 | |
| **顶层结构**: | |
| ```json | |
| [ | |
| { | |
| "conversations": [...], | |
| "system": "...", | |
| "tools": "..." // 可选字段 | |
| }, | |
| ... | |
| ] | |
| ``` | |
| **必需字段**: | |
| - **`conversations`** (数组，必需): 对话消息序列 | |
| - 每个消息对象必须包含: | |
| - `"from"`: 字符串，必须是 `"human"`、`"function_call"`、`"observation"`、`"gpt"` 之一 | |
| - `"value"`: 字符串，消息内容 | |
| - **`system`** (字符串，必需): 系统提示词，可包含 `<tools>` 标签 | |
| **可选字段**: | |
| - **`tools`** (字符串，可选): JSON格式的工具定义，默认为 `"[]"` | |
| #### 5.1.2 消息类型说明 | |
| | 消息类型 | from值 | 用途 | 示例 | | |
| |---------|-------------------|-------------------|------------------------------------------------| | |
| | 用户输入 | `"human"` | 用户的查询或请求 | `{"from": "human", "value": "帮我查询收入数据"}` | | |
| | 工具调用 | `"function_call"` | AI调用的工具和参数 | `{"from": "function_call", "value": "{\"name\":\"tool_name\",\"arguments\":{...}}"}` | | |
| | 工具返回 | `"observation"` | 工具执行的结果 | `{"from": "observation", "value": "工具返回的结果数据"}` | | |
| | AI回复 | `"gpt"` | AI的最终回答 | `{"from": "gpt", "value": "基于工具结果的回答"}` | | |
| #### 5.1.3 对话序列要求 | |
| 脚本会按照以下逻辑解析conversations来生成评估对： | |
| 1. **Pair 1**: `human` → `function_call` | |
| - 从 `"human"` 消息开始，寻找紧随其后的 `"function_call"` 消息 | |
| 2. **Pair 2**: `human` + `observation` → `function_call` | |
| - 从 `"observation"` 消息开始，寻找紧随其后的 `"function_call"` 消息 | |
| 3. **Pair 3**: `human` + `observation` → `gpt` | |
| - 从 `"observation"` 消息开始，寻找紧随其后的 `"gpt"` 消息 | |
| #### 5.1.4 格式验证 | |
| **严格程度**: 中等严格 | |
| - ✅ **必需字段**: `conversations`、`system` 必须存在且格式正确 | |
| - ✅ **字段类型**: 必须是正确的数据类型（数组、字符串） | |
| - ✅ **枚举值**: `"from"` 字段必须是预定义的值 | |
| - ✅ **数组结构**: conversations必须是数组格式 | |
| - ⚠️ **可选字段**: `tools` 字段可选，有默认值 | |
| - ⚠️ **内容验证**: 不验证具体的工具调用内容格式 | |
| **常见错误**: | |
| - `KeyError`: 缺少必需字段 `conversations` 或 `system` | |
| - `TypeError`: 字段类型不正确（如conversations不是数组） | |
| - `ValueError`: `"from"` 字段值不是预定义的枚举值 | |
| #### 5.1.5 完整示例 | |
| ```json | |
| [ | |
| { | |
| "conversations": [ | |
| { | |
| "from": "human", | |
| "value": "帮我看下2025年6月到8月各种收入类型的占比情况" | |
| }, | |
| { | |
| "from": "function_call", | |
| "value": "{\"name\":\"retrieval_tool\",\"arguments\":{\"query\":\"收入分析\",\"source_filter\":\"toollist\",\"user_id\":136451106,\"top_k\":5}}" | |
| }, | |
| { | |
| "from": "observation", | |
| "value": "[{\"name\":\"analyze_revenue_by_type\",\"description\":\"收入分析工具\"}]" | |
| }, | |
| { | |
| "from": "function_call", | |
| "value": "{\"name\":\"analyze_revenue_by_type\",\"arguments\":{\"start_date\":\"2025-06-01\",\"end_date\":\"2025-08-31\"}}" | |
| }, | |
| { | |
| "from": "observation", | |
| "value": "{\"result\":{\"收入\":\"1,285,893.00\",\"门票\":\"47.1%\",\"交通\":\"50.6%\"}}" | |
| }, | |
| { | |
| "from": "gpt", | |
| "value": "根据2025年6月到8月的收入数据分析，各种收入类型的占比情况如下：交通收入占50.6%，门票收入占47.1%..." | |
| } | |
| ], | |
| "system": "# 工具\n\n你可以调用一个或多个函数来协助处理用户查询。\n\n在 <tools></tools> XML 标签中提供了可用的函数签名：\n<tools>\n</tools>", | |
| "tools": "[{\"name\":\"retrieval_tool\",\"description\":\"检索工具\"}]" | |
| } | |
| ] | |
| ``` | |
| **从上述示例生成的评估对**: | |
| - **Pair 1**: `system + user查询` → `retrieval_tool调用` | |
| - **Pair 2**: `system + user查询 + 检索结果` → `analyze_revenue_by_type调用` | |
| - **Pair 3**: `system + user查询 + 分析结果` → `最终回答` | |
| ### 5.2 输出文件 | |
| - **主要输出**: `metrics/data_evaluation_results.json` | |
| - 完整的评估报告，包含详细结果和指标统计 | |
| - **实时指标**: `metrics/realtime_metrics.json` | |
| - 实时更新的指标数据，每处理一个评估对就更新 | |
| - **日志文件**: `metrics/data_evaluation.log` | |
| - 详细的运行日志，包含评估进度和错误信息 | |
| - **断点文件**: `metrics/evaluation_checkpoint.json` | |
| - 支持断点续传的中间状态文件（完成后自动删除） | |
| ## 六、技术特性 | |
| ### 6.1 断点续传 | |
| - 支持中断后从上次位置继续评估 | |
| - 自动保存处理进度到checkpoint文件 | |
| - 评估完成后自动清理断点文件 | |
| ### 6.2 实时指标更新 | |
| - 每处理一个评估对就更新实时指标 | |
| - 可随时查看当前评估进度和指标状态 | |
| ### 6.3 多模型支持 | |
| - **预测模型**: Qwen3-8B (通过API调用) | |
| - **评估模型**: Gemini-2.5-flash (用于文本生成质量评估) | |
| - **检索工具**: 调用retrieval_tool | |
| ### 6.4 容错机制 | |
| - API调用重试机制（最多3次） | |
| - 指数退避策略 | |
| - 详细的错误日志记录 | |
| ## 七、注意事项 | |
| 1. **API配置**: 确保GEMINI_API_KEY和QWEN_API_URL配置正确 | |
| 2. **网络连接**: 需要稳定的网络连接访问外部API服务 | |
| 3. **存储空间**: 确保有足够空间存储输出文件和日志 | |
| 4. **运行时间**: 完整评估可能需要数小时，建议后台运行 | |
| 5. **数据格式**: 输入文件必须严格符合指定的JSON格式 | |
| - 确保必需字段 `conversations` 和 `system` 存在 | |
| - `conversations` 必须是数组，每个消息包含 `"from"` 和 `"value"` 字段 | |
| - `"from"` 字段值必须是 `"human"`、`"function_call"`、`"observation"`、`"gpt"` 之一 | |
| - 建议使用提供的示例文件作为模板 | |
| 6. **对话序列**: 确保conversations中的消息序列符合评估逻辑要求 | |
| - 每个 `"human"` 消息后应跟随 `"function_call"` 消息 | |
| - 每个 `"observation"` 消息后应跟随 `"function_call"` 或 `"gpt"` 消息 | |