wuyang6
452 lines
13 KiB
Markdown
452 lines
13 KiB
Markdown
# 13. Skill 评测实验台设计
|
||
|
||
## 1. 背景
|
||
|
||
当前快慢分流优化需要完成一条完整链路：
|
||
|
||
```text
|
||
已有评测集
|
||
-> 使用现成 Skill 判断快慢
|
||
-> 支持单条和批量运行
|
||
-> 对比人工标签和模型判断
|
||
-> 查看分歧及判定依据
|
||
-> 更新 Skill 或切换模型
|
||
-> 重新评测并比较变化
|
||
```
|
||
|
||
这里讨论的是离线优化和评估场景。评测过程允许 Agent 使用完整 Agent Loop，重点是判断质量、依据可追溯和标准持续收敛。线上快慢路由的耗时、成本和部署形态属于后续独立问题。
|
||
|
||
本设计假设快慢分流 Skill 已经存在。实验台负责稳定调用和评估 Skill，不负责定义 Skill 内部的分类标准。
|
||
|
||
## 2. 目标
|
||
|
||
实验台需要支持：
|
||
|
||
- 单条输入调用指定 Skill，返回判断、理由和执行记录。
|
||
- 上传 CSV、XLSX 或 JSONL，配置字段映射后批量运行。
|
||
- 选择模型和不可变的 Skill 版本。
|
||
- 后台并发执行，支持暂停、继续、取消和失败重试。
|
||
- 自动计算总体、分类别和分垂域指标。
|
||
- 集中查看人工与模型分歧，并进行人工复核。
|
||
- 查看模型声明的 Skill 判定依据和实际访问记录。
|
||
- 对比不同 Skill 版本或模型版本的修正与退化。
|
||
- 导出原始结果、复核结果和版本对比结果。
|
||
|
||
实验台不承担：
|
||
|
||
- 在线请求的实时路由。
|
||
- 快系统能力或分类原则的编写。
|
||
- 将每个普通 Skill 自动转成页面应用。
|
||
- 修改现有聊天 Agent 的会话和运行流程。
|
||
|
||
## 3. 总体架构
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
UI["快慢分流评测页面"] --> EXP["Evaluation Service"]
|
||
API["Skill Run API"] --> EXP
|
||
|
||
EXP --> MAP["Dataset Mapping"]
|
||
EXP --> SNAP["Skill Snapshot"]
|
||
EXP --> SCHED["Batch Scheduler"]
|
||
|
||
SCHED --> RUNNER["Headless Skill Runner"]
|
||
RUNNER --> AGENT["LocalCodingAgent"]
|
||
RUNNER --> MODEL["指定模型"]
|
||
RUNNER --> SKILL["固定 Skill 快照"]
|
||
|
||
EXP --> STORE["Evaluation Store"]
|
||
STORE --> RESULT["指标 / 分歧 / 复核 / 版本对比"]
|
||
```
|
||
|
||
新增能力由五个部分组成：
|
||
|
||
1. `Evaluation Service`：管理数据集、实验配置、运行和结果。
|
||
2. `Dataset Mapping`：把不同格式的数据转换为统一 case。
|
||
3. `Skill Snapshot`：固定每次实验使用的 Skill 内容。
|
||
4. `Headless Skill Runner`：使用现有 Agent Core 在后台执行指定 Skill。
|
||
5. `Batch Scheduler`：拆分、并发和恢复批量任务。
|
||
|
||
## 4. 与现有 Agent 的隔离
|
||
|
||
现有聊天链路保持不变：
|
||
|
||
```text
|
||
/api/chat
|
||
-> AgentState
|
||
-> account/session-scoped LocalCodingAgent
|
||
-> 聊天 session 和活动流
|
||
```
|
||
|
||
评测链路新增独立入口：
|
||
|
||
```text
|
||
/api/evaluations
|
||
-> EvaluationRuntime
|
||
-> evaluation-scoped LocalCodingAgent
|
||
-> 评测任务、case 结果和内部执行记录
|
||
```
|
||
|
||
两条链路可以复用：
|
||
|
||
- `LocalCodingAgent`
|
||
- `ModelConfig`
|
||
- Skill loader
|
||
- Tool handler
|
||
- `OutputSchemaConfig`
|
||
- 模型兼容层
|
||
|
||
评测链路必须独立管理：
|
||
|
||
- Agent 实例。
|
||
- Session 命名空间。
|
||
- 数据库记录。
|
||
- 运行队列。
|
||
- 并发和资源配额。
|
||
- Skill 快照。
|
||
|
||
评测产生的内部 Agent session 不进入左侧聊天会话列表，也不读取聊天历史、用户记忆或当前聊天 session 状态。
|
||
|
||
代码隔离只能保证功能不互相污染。批量任务仍可能争用模型服务资源，因此评测任务需要独立 worker pool、并发上限和低于聊天请求的调度优先级。有条件时可以为评测配置独立模型地址。
|
||
|
||
## 5. 数据集字段映射
|
||
|
||
评测文件格式由数据来源决定，不应写进 Skill，也不应要求用户临时组织成提示词。
|
||
|
||
上传文件后，系统先读取表头和样本，用户把源字段映射到统一字段：
|
||
|
||
| 统一字段 | 说明 | 必填 |
|
||
|---|---|---|
|
||
| `case_id` | case 唯一标识 | 否，可自动生成 |
|
||
| `query` | 当前用户 query | 是 |
|
||
| `gold_route` | 人工快慢标签 | 评测时必填 |
|
||
| `history` | 对话历史 | 否 |
|
||
| `context` | 设备、位置等上下文 | 否 |
|
||
| `domain` | 垂域 | 否 |
|
||
| `request_id` | 线上 RID | 否 |
|
||
| `metadata` | 其他保留字段 | 否 |
|
||
| `source_row` | 原始行 | 自动保留 |
|
||
|
||
页面需要支持：
|
||
|
||
- 列名自动推荐。
|
||
- 手动选择源字段。
|
||
- JSON path，例如 `data.query`。
|
||
- 标签值转换，例如 `快/慢`、`0/1`、`fast/slow`。
|
||
- 必要的字段组合和简单转换。
|
||
- 转换后样本预览。
|
||
- 缺失字段、非法标签和重复 ID 校验。
|
||
|
||
确认后的映射保存为可复用的 `Dataset Mapping Profile`。Skill Runner 只接收统一 case，不感知原始文件的列名和格式。
|
||
|
||
统一 case 示例：
|
||
|
||
```json
|
||
{
|
||
"case_id": "001",
|
||
"query": "到目的地电量够不够",
|
||
"gold_route": "fast",
|
||
"history": [],
|
||
"context": {},
|
||
"domain": "地图导航",
|
||
"request_id": "",
|
||
"metadata": {},
|
||
"source_row": {}
|
||
}
|
||
```
|
||
|
||
## 6. Skill 版本与快照
|
||
|
||
实验不能只记录 Skill 名称。Skill 内容会持续更新，同一个名称在不同时间可能代表不同标准。
|
||
|
||
每次创建实验时生成不可变快照，并记录：
|
||
|
||
```json
|
||
{
|
||
"skill_name": "fast-slow-routing",
|
||
"repository": "zk-data-agent",
|
||
"git_commit": "abc1234",
|
||
"content_hash": "sha256:...",
|
||
"snapshot_id": "skill_snapshot_xxx",
|
||
"status": "committed"
|
||
}
|
||
```
|
||
|
||
版本来源可以是：
|
||
|
||
- 当前部署版本。
|
||
- 指定 Git commit。
|
||
- 指定 Git tag。
|
||
- 尚未提交的草稿快照。
|
||
|
||
快照建议存放在：
|
||
|
||
```text
|
||
.port_sessions/evaluations/skill_snapshots/
|
||
<skill-name>/
|
||
<commit-or-content-hash>/
|
||
```
|
||
|
||
运行旧版本时不能切换当前项目分支，也不能覆盖线上 Skill。对于 Git 中的历史版本，可以通过 `git archive` 提取单个 Skill 目录到快照缓存。
|
||
|
||
草稿版本允许参与实验，但页面必须明确标记“未提交”，并使用内容哈希保证同一次实验可复现。
|
||
|
||
评测 Agent 始终从快照加载 Skill；聊天 Agent 继续从当前部署目录加载 Skill，两者互不影响。
|
||
|
||
## 7. Headless Skill Runner
|
||
|
||
`Headless` 表示没有聊天页面，不表示减少 Agent 能力。
|
||
|
||
Runner 接收：
|
||
|
||
```json
|
||
{
|
||
"skill_snapshot_id": "skill_snapshot_xxx",
|
||
"model_id": "model_xxx",
|
||
"case": {
|
||
"case_id": "001",
|
||
"query": "到目的地电量够不够"
|
||
}
|
||
}
|
||
```
|
||
|
||
Runner 的执行过程：
|
||
|
||
1. 从快照读取指定 Skill。
|
||
2. 创建独立的评测 Agent 实例和 session。
|
||
3. 直接把指定 Skill 注入当前任务，不等待模型自行召回 Skill。
|
||
4. 把统一 case 作为任务输入。
|
||
5. 按 Skill 约定执行完整 Agent Loop。
|
||
6. 保存最终结果、执行事件、工具调用和用量。
|
||
7. 将最终输出归一化为评测结果。
|
||
|
||
统一评测结果至少包含：
|
||
|
||
```json
|
||
{
|
||
"case_id": "001",
|
||
"prediction": "fast",
|
||
"reason": "当前快系统已有对应能力",
|
||
"confidence": 0.95,
|
||
"evidence_refs": [
|
||
"knowledge/地图能力.md#到达电量预估"
|
||
],
|
||
"status": "completed",
|
||
"raw_output": "",
|
||
"agent_session_id": ""
|
||
}
|
||
```
|
||
|
||
单条判断创建一个 Agent Run。批量判断把每条 case 拆成独立 Agent Run，避免样本间上下文污染。
|
||
|
||
## 8. 批量调度
|
||
|
||
批量调度器负责：
|
||
|
||
- 把数据集拆成独立 case 任务。
|
||
- 使用受控并发执行。
|
||
- 保存每条 case 的状态和重试次数。
|
||
- 单条失败不终止整个实验。
|
||
- 支持暂停、继续和取消。
|
||
- 服务重启后从数据库恢复未完成任务。
|
||
- 只重跑失败项、分歧项或用户选中的 case。
|
||
|
||
任务状态：
|
||
|
||
```text
|
||
pending
|
||
running
|
||
completed
|
||
failed
|
||
cancelled
|
||
```
|
||
|
||
聊天请求和评测请求需要独立并发池。评测批量任务默认低优先级，避免影响当前在线使用者。
|
||
|
||
## 9. 判定依据与可追溯性
|
||
|
||
页面需要回答“模型依据 Skill 的哪部分作出判断”，但不能把完整模型思考当作可靠因果证据。
|
||
|
||
实验台展示两类事实：
|
||
|
||
1. **实际访问记录**：Agent 读取了哪些 Skill 文件、知识文件和章节。
|
||
2. **模型声明的判定依据**：最终结果中的 `evidence_refs`。
|
||
|
||
生成 Skill 快照时，系统为 Markdown 标题和知识文件建立稳定引用，例如：
|
||
|
||
```text
|
||
SKILL.md#判断流程
|
||
knowledge/地图能力.md#到达电量预估
|
||
knowledge/边界.md#开放式行程规划
|
||
```
|
||
|
||
评测 Runner 的统一任务约定要求最终结果返回引用。页面将引用解析为可点击的原文片段。
|
||
|
||
如果模型没有引用明确规则，页面展示“未引用具体依据”，并允许按此条件筛选。这类 case 本身就是标准缺失或模型未正确使用 Skill 的候选问题。
|
||
|
||
## 10. 页面信息架构
|
||
|
||
页面采用“实验配置、结果页签、单条详情”三层结构。
|
||
|
||
### 10.1 实验配置
|
||
|
||
顶部配置区包含：
|
||
|
||
- 数据集。
|
||
- 字段映射。
|
||
- Skill 和版本。
|
||
- 模型。
|
||
- case 数量。
|
||
- 并发配置。
|
||
- 开始、暂停、继续、取消、克隆实验。
|
||
|
||
运行开始后配置区折叠，避免占用结果空间。
|
||
|
||
### 10.2 结果页签
|
||
|
||
| 页签 | 主要内容 |
|
||
|---|---|
|
||
| 概览 | 运行进度、总体指标、混淆矩阵、快慢分布、分垂域指标 |
|
||
| 分歧 | 人工标签与模型判断不一致、低置信、无明确依据的 case |
|
||
| 全部 Case | 全量结果、状态、筛选、排序和导出 |
|
||
| 版本对比 | 不同 Skill 或模型实验之间的修正、退化和指标变化 |
|
||
|
||
### 10.3 单条详情抽屉
|
||
|
||
点击一条 case 后展示：
|
||
|
||
1. 原始数据和统一后的输入。
|
||
2. 人工标签、模型判断、置信度和理由。
|
||
3. Skill 判定依据及原文片段。
|
||
4. 实际读取文件和工具调用。
|
||
5. 默认折叠的完整 Agent 执行记录。
|
||
6. 人工复核结果和备注。
|
||
|
||
人工复核至少支持：
|
||
|
||
- 人工原标签正确。
|
||
- 模型判断正确。
|
||
- 分类标准存在歧义。
|
||
- 快系统能力信息缺失。
|
||
- 暂不确定。
|
||
|
||
## 11. 实验与版本对比
|
||
|
||
一个实验由以下对象共同确定：
|
||
|
||
```text
|
||
数据集版本
|
||
+ 字段映射版本
|
||
+ Skill 快照
|
||
+ 模型版本
|
||
+ 执行参数
|
||
```
|
||
|
||
同一数据集可以克隆实验并替换 Skill 或模型：
|
||
|
||
```text
|
||
实验 A：Skill abc1234 + 模型 A
|
||
实验 B：Skill def5678 + 模型 A
|
||
实验 C：Skill def5678 + 模型 B
|
||
```
|
||
|
||
版本对比需要展示：
|
||
|
||
- 总体指标变化。
|
||
- 各垂域指标变化。
|
||
- 从错误变正确的 case。
|
||
- 从正确变错误的 case。
|
||
- 判断未变化但理由变化的 case。
|
||
- 新增或消失的无依据结果。
|
||
|
||
这样才能形成“评测、发现分歧、更新 Skill、重新评测”的优化闭环。
|
||
|
||
## 12. 数据存储
|
||
|
||
评测运行状态适合使用独立 SQLite 数据库，例如：
|
||
|
||
```text
|
||
.port_sessions/evaluations/evaluations.db
|
||
```
|
||
|
||
核心实体：
|
||
|
||
```text
|
||
evaluation_datasets
|
||
dataset_mapping_profiles
|
||
skill_snapshots
|
||
evaluation_experiments
|
||
evaluation_cases
|
||
evaluation_case_runs
|
||
evaluation_results
|
||
evaluation_reviews
|
||
```
|
||
|
||
数据库保存可查询状态、关系和人工复核结果。上传原文件、Skill 快照、导出文件和较大的 Agent transcript 保存在实验目录，数据库记录路径和摘要。
|
||
|
||
## 13. API 轮廓
|
||
|
||
```text
|
||
POST /api/evaluations/datasets
|
||
POST /api/evaluations/datasets/{id}/mapping
|
||
|
||
POST /api/evaluations/skill-snapshots
|
||
GET /api/evaluations/skill-snapshots
|
||
|
||
POST /api/evaluations
|
||
GET /api/evaluations/{id}
|
||
POST /api/evaluations/{id}/start
|
||
POST /api/evaluations/{id}/pause
|
||
POST /api/evaluations/{id}/resume
|
||
POST /api/evaluations/{id}/cancel
|
||
|
||
GET /api/evaluations/{id}/results
|
||
POST /api/evaluations/{id}/retry
|
||
POST /api/evaluations/{id}/reviews
|
||
GET /api/evaluations/{id}/export
|
||
|
||
POST /api/evaluations/compare
|
||
```
|
||
|
||
API 同时服务 Web 页面和外部批量调用。单条调用可以创建只包含一个 case 的轻量实验，复用相同运行与记录机制。
|
||
|
||
## 14. 实施顺序
|
||
|
||
### P1：后台单条运行
|
||
|
||
- Skill 快照。
|
||
- Headless Skill Runner。
|
||
- 单条输入和统一结果。
|
||
- 独立于聊天 session 的运行记录。
|
||
|
||
### P2：数据集与批量调度
|
||
|
||
- 文件上传和字段映射。
|
||
- 批量拆分、并发、暂停、恢复和重试。
|
||
- 基础指标和导出。
|
||
|
||
### P3：评测页面
|
||
|
||
- 实验配置。
|
||
- 概览、分歧、全部 Case。
|
||
- 单条详情和人工复核。
|
||
- Skill 依据引用。
|
||
|
||
### P4：版本对比
|
||
|
||
- 克隆实验。
|
||
- Skill 和模型版本矩阵。
|
||
- 修正、退化和理由变化分析。
|
||
|
||
## 15. 验收标准
|
||
|
||
- 开启评测任务后，现有聊天 Agent 可以正常创建、继续和停止会话。
|
||
- 600 条批量任务不会出现在聊天会话列表。
|
||
- 不同输入格式可以通过字段映射转换为统一 case。
|
||
- 每次实验可以确认具体 Skill commit 或内容哈希。
|
||
- Skill 更新后，历史实验仍能读取原快照并复现配置。
|
||
- 单条失败不会中断全量任务，服务重启后可以恢复。
|
||
- 页面可以定位人工与模型分歧，并查看简短理由和 Skill 引用。
|
||
- 可以比较两个实验的修正项和退化项。
|
||
- 批量评测的并发不会明显拖慢聊天 Agent。
|