wuyang6
13 KiB
13. Skill 评测实验台设计
1. 背景
当前快慢分流优化需要完成一条完整链路：
已有评测集
-> 使用现成 Skill 判断快慢
-> 支持单条和批量运行
-> 对比人工标签和模型判断
-> 查看分歧及判定依据
-> 更新 Skill 或切换模型
-> 重新评测并比较变化
这里讨论的是离线优化和评估场景。评测过程允许 Agent 使用完整 Agent Loop，重点是判断质量、依据可追溯和标准持续收敛。线上快慢路由的耗时、成本和部署形态属于后续独立问题。
本设计假设快慢分流 Skill 已经存在。实验台负责稳定调用和评估 Skill，不负责定义 Skill 内部的分类标准。
2. 目标
实验台需要支持：
- 单条输入调用指定 Skill，返回判断、理由和执行记录。
- 上传 CSV、XLSX 或 JSONL，配置字段映射后批量运行。
- 选择模型和不可变的 Skill 版本。
- 后台并发执行，支持暂停、继续、取消和失败重试。
- 自动计算总体、分类别和分垂域指标。
- 集中查看人工与模型分歧，并进行人工复核。
- 查看模型声明的 Skill 判定依据和实际访问记录。
- 对比不同 Skill 版本或模型版本的修正与退化。
- 导出原始结果、复核结果和版本对比结果。
实验台不承担：
- 在线请求的实时路由。
- 快系统能力或分类原则的编写。
- 将每个普通 Skill 自动转成页面应用。
- 修改现有聊天 Agent 的会话和运行流程。
3. 总体架构
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["指标 / 分歧 / 复核 / 版本对比"]
新增能力由五个部分组成：
Evaluation Service：管理数据集、实验配置、运行和结果。Dataset Mapping：把不同格式的数据转换为统一 case。Skill Snapshot：固定每次实验使用的 Skill 内容。Headless Skill Runner：使用现有 Agent Core 在后台执行指定 Skill。Batch Scheduler：拆分、并发和恢复批量任务。
4. 与现有 Agent 的隔离
现有聊天链路保持不变：
/api/chat
-> AgentState
-> account/session-scoped LocalCodingAgent
-> 聊天 session 和活动流
评测链路新增独立入口：
/api/evaluations
-> EvaluationRuntime
-> evaluation-scoped LocalCodingAgent
-> 评测任务、case 结果和内部执行记录
两条链路可以复用：
LocalCodingAgentModelConfig- 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 示例：
{
"case_id": "001",
"query": "到目的地电量够不够",
"gold_route": "fast",
"history": [],
"context": {},
"domain": "地图导航",
"request_id": "",
"metadata": {},
"source_row": {}
}
6. Skill 版本与快照
实验不能只记录 Skill 名称。Skill 内容会持续更新，同一个名称在不同时间可能代表不同标准。
每次创建实验时生成不可变快照，并记录：
{
"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。
- 尚未提交的草稿快照。
快照建议存放在：
.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 接收：
{
"skill_snapshot_id": "skill_snapshot_xxx",
"model_id": "model_xxx",
"case": {
"case_id": "001",
"query": "到目的地电量够不够"
}
}
Runner 的执行过程：
- 从快照读取指定 Skill。
- 创建独立的评测 Agent 实例和 session。
- 直接把指定 Skill 注入当前任务，不等待模型自行召回 Skill。
- 把统一 case 作为任务输入。
- 按 Skill 约定执行完整 Agent Loop。
- 保存最终结果、执行事件、工具调用和用量。
- 将最终输出归一化为评测结果。
统一评测结果至少包含：
{
"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。
任务状态：
pending
running
completed
failed
cancelled
聊天请求和评测请求需要独立并发池。评测批量任务默认低优先级，避免影响当前在线使用者。
9. 判定依据与可追溯性
页面需要回答“模型依据 Skill 的哪部分作出判断”，但不能把完整模型思考当作可靠因果证据。
实验台展示两类事实：
- 实际访问记录：Agent 读取了哪些 Skill 文件、知识文件和章节。
- 模型声明的判定依据：最终结果中的
evidence_refs。
生成 Skill 快照时，系统为 Markdown 标题和知识文件建立稳定引用，例如：
SKILL.md#判断流程
knowledge/地图能力.md#到达电量预估
knowledge/边界.md#开放式行程规划
评测 Runner 的统一任务约定要求最终结果返回引用。页面将引用解析为可点击的原文片段。
如果模型没有引用明确规则，页面展示“未引用具体依据”，并允许按此条件筛选。这类 case 本身就是标准缺失或模型未正确使用 Skill 的候选问题。
10. 页面信息架构
页面采用“实验配置、结果页签、单条详情”三层结构。
10.1 实验配置
顶部配置区包含：
- 数据集。
- 字段映射。
- Skill 和版本。
- 模型。
- case 数量。
- 并发配置。
- 开始、暂停、继续、取消、克隆实验。
运行开始后配置区折叠，避免占用结果空间。
10.2 结果页签
| 页签 | 主要内容 |
|---|---|
| 概览 | 运行进度、总体指标、混淆矩阵、快慢分布、分垂域指标 |
| 分歧 | 人工标签与模型判断不一致、低置信、无明确依据的 case |
| 全部 Case | 全量结果、状态、筛选、排序和导出 |
| 版本对比 | 不同 Skill 或模型实验之间的修正、退化和指标变化 |
10.3 单条详情抽屉
点击一条 case 后展示：
- 原始数据和统一后的输入。
- 人工标签、模型判断、置信度和理由。
- Skill 判定依据及原文片段。
- 实际读取文件和工具调用。
- 默认折叠的完整 Agent 执行记录。
- 人工复核结果和备注。
人工复核至少支持：
- 人工原标签正确。
- 模型判断正确。
- 分类标准存在歧义。
- 快系统能力信息缺失。
- 暂不确定。
11. 实验与版本对比
一个实验由以下对象共同确定：
数据集版本
+ 字段映射版本
+ Skill 快照
+ 模型版本
+ 执行参数
同一数据集可以克隆实验并替换 Skill 或模型：
实验 A：Skill abc1234 + 模型 A
实验 B：Skill def5678 + 模型 A
实验 C：Skill def5678 + 模型 B
版本对比需要展示：
- 总体指标变化。
- 各垂域指标变化。
- 从错误变正确的 case。
- 从正确变错误的 case。
- 判断未变化但理由变化的 case。
- 新增或消失的无依据结果。
这样才能形成“评测、发现分歧、更新 Skill、重新评测”的优化闭环。
12. 数据存储
评测运行状态适合使用独立 SQLite 数据库，例如：
.port_sessions/evaluations/evaluations.db
核心实体：
evaluation_datasets
dataset_mapping_profiles
skill_snapshots
evaluation_experiments
evaluation_cases
evaluation_case_runs
evaluation_results
evaluation_reviews
数据库保存可查询状态、关系和人工复核结果。上传原文件、Skill 快照、导出文件和较大的 Agent transcript 保存在实验目录，数据库记录路径和摘要。
13. API 轮廓
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。