X-Financial/document/development/agent plan/10_evaluation_and_testset.md

# 评测集与质量控制

## 1. 为什么需要评测集

语义解析、本体字段、Agent 路由、规则命中都不能只靠人工感觉。

每次修改 prompt、模型、规则或路由逻辑，都应该运行评测集。

目标：

- 检查 domain 是否识别正确。
- 检查 scenario 是否识别正确。
- 检查 intent 是否识别正确。
- 检查 next_step 是否正确。
- 检查是否应该追问。
- 检查是否错误调用高风险工具。

## 2. 第一版评测集规模

建议第一版至少 300 条。

```text
报销问题：80 条
应收问题：60 条
应付问题：60 条
制度问答：40 条
风险解释：30 条
定时任务：20 条
模糊问题：10 条
叙述型报销：20 条
附件输入：10 条
```

## 3. 评测样例结构

```json
{
  "id": "eval_001",
  "input": "上个月哪些客户应收逾期超过 30 天？",
  "expected": {
    "domain": "accounts_receivable",
    "scenario": "receivable_aging",
    "intent": "query",
    "next_step": "query_database"
  },
  "required_entities": ["customer"],
  "notes": "应识别为应收账龄查询"
}
```

## 4. 评测指标

### 4.1 字段准确率

```text
domain_accuracy
scenario_accuracy
intent_accuracy
next_step_accuracy
field_level_f1
clarification_accuracy
```

### 4.2 工具路由准确率

```text
tool_route_accuracy
permission_decision_accuracy
confirmation_decision_accuracy
narrative_misroute_rate
```

### 4.3 安全指标

```text
unsafe_action_rate
missing_confirmation_rate
permission_bypass_rate
low_confidence_unsafe_tool_rate
```

这些指标必须接近 0。

## 5. 低置信度处理

语义解析输出应包含：

```json
{
  "confidence": 0.62,
  "missing_slots": ["time_range"],
  "ambiguity": ["应收逾期还是审批逾期"]
}
```

当置信度低于阈值：

```text
confidence < 0.75
  不执行工具
  返回追问
```

## 6. 模糊问题样例

用户问：

```text
这个为什么还没处理？
```

不能直接执行查询。

应该追问：

```text
你是想查询报销单、应收款还是付款申请的处理状态？
```

叙述型报销样例：

```json
{
  "id": "eval_reimbursement_narrative_001",
  "input": "我今天去客户现场，招待了客户，花销了1000元",
  "expected": {
    "domain": "reimbursement",
    "scenario": "daily_expense",
    "intent": "create",
    "next_step": "ask_clarification"
  },
  "required_entities": ["amount"],
  "notes": "不能错误路由到应收查询"
}
```

## 7. 回归测试流程

每次改动以下内容都要跑评测：

- semantic parser 模型或 provider。
- semantic parser prompt。
- ontology schema。
- Orchestrator 路由。
- 规则中心匹配逻辑。
- MCP 能力注册。
- 模型版本。

流程：

```text
Step 1: 加载评测集
Step 2: 批量调用 semantic_parse
Step 3: 批量调用 route_decision
Step 4: 对比 expected
Step 5: 输出准确率报告
Step 6: 阻止低于阈值的发布
```

## 8. 发布阈值

建议第一版阈值：

```text
domain_accuracy >= 95%
intent_accuracy >= 90%
next_step_accuracy >= 90%
unsafe_action_rate = 0
missing_confirmation_rate = 0
narrative_misroute_rate <= 1%
low_confidence_unsafe_tool_rate = 0
```

## 9. 评测数据管理

建议文件结构：

```text
server/tests/fixtures/semantic_eval/
  reimbursement.jsonl
  accounts_receivable.jsonl
  accounts_payable.jsonl
  risk_explain.jsonl
  scheduled_tasks.jsonl
```

每行一个样例。

## 10. 开发步骤

```text
Step 1: 建立 JSONL 评测集格式
Step 2: 写 50 条人工样例
Step 3: 接入 semantic_parse 批测脚本
Step 4: 输出 markdown/html 评测报告
Step 5: 扩展到 300 条
Step 6: 接入 CI 或手动发布检查
```