102 lines
11 KiB
Markdown
102 lines
11 KiB
Markdown
# tjwater_v2 爆管 Agent Benchmark
|
||
|
||
状态：场景框架与只读数据预检已准备；隔离执行环境、真实触发链、Agent 轨迹采集和正式评分器尚未实现。2026-11-03。
|
||
|
||
## 目标与边界
|
||
|
||
本套 benchmark 用固定的管网状态、触发条件和隐藏真值，比较提示词、Skill、MCP 工具或模型配置变更对爆管处置的影响。首版限于 `tjwater_v2` 爆管，不扩展水体污染。已有数据库是数据来源；每次正式执行必须在独立评测数据库和运行时完成，原项目数据库不承担工单、SCADA 清洗、告警、任务、计算或证据写入。
|
||
|
||
```text
|
||
原 MetaDB / BizDB / TimescaleDB
|
||
| 仅 SELECT、只读事务
|
||
v
|
||
版本化私有数据快照 -> 隔离评测 BizDB + TimescaleDB -> Server/MCP/worker -> Agent Host
|
||
| |
|
||
+----轨迹与业务结果----+
|
||
|
|
||
评分报告 + 版本归档
|
||
```
|
||
|
||
评测 Agent 只能连接隔离环境。单靠客户端 `READ ONLY` 事务不足以保证未来服务不误连原库；运行配置必须使用隔离数据库路由，并由原库侧评测账号权限拒绝写入。现有 `temporary_project_database`/模型模板复制路径不能直接用于原项目，因为它会暂时关闭连接并终止源库会话。应在独立实例先生成逻辑快照，再把可写副本作为评测环境。
|
||
|
||
## 场景矩阵
|
||
|
||
配置文件 `resources/benchmarks/tjwater-v2-burst.json` 定义四个候选物理工况：
|
||
|
||
| 场景 | 管段 | 管径 | 发生时间（北京时间） | 当前观测准备状态 |
|
||
|---|---:|---:|---|---|
|
||
| B01 | 540672 | DN315 | 2026-10-08 02:00 | 需在隔离集生成事件观测 |
|
||
| B02 | 540672 | DN315 | 2026-10-08 12:00 | 历史回放声明待核对当前窗口 |
|
||
| B03 | 537407 | DN600 | 2026-10-08 02:00 | 需在隔离集生成事件观测 |
|
||
| B04 | 537407 | DN600 | 2026-10-08 12:00 | 需在隔离集生成事件观测 |
|
||
|
||
每个工况各有工单上报（WO）和 SCADA 监测（SCADA）入口，共 8 个候选用例。另设无爆管正常控制作为误报检查，不算第三类业务。管段、时间和历史分析名称仅是候选定义；准备报告须检查观测窗口、参考工况和触发是否吻合。未满足条件的用例标为 `not_ready`，不能作为 Agent 失败，也不能从统计中静默删除。
|
||
|
||
工单路径使用 `burst_report` 来源，经既有外围工单同步、操作任务 worker、Agent Host 和 MCP 完成调查。SCADA 路径从隔离副本的正常数据起步，再释放事件数据，由真实 replay worker/规则创建通用异常调查；不能把目标管段或爆管类型预先告诉检测器。纯规则预览只作准备检查，不能代替这条端到端路径。
|
||
|
||
工单位置由冻结的网络 GIS 几何转成稳定的人类可读位置，结合近似范围和现象描述，不把真实 link ID 直接写成答案。Agent/Server 业务结果是首版主分数；前端呈现单独做 Playwright 结果回放检查，不能用工作台 mock 结果代替 Agent 评测，也不混入业务能力分。
|
||
|
||
首版使用单一持续爆管，不模拟修复恢复；预计结束状态是有证据的调查报告，可以合理等待人工确认或审批。现有模型只含 2 个阀门，目标管段即使移除全部模型阀门仍与水源连通，因此成功关闭隔离不作为成功标准。Agent 应说明拓扑限制和现场核查需求，不得编造阀门方案。
|
||
|
||
## 真值、可见信息与评分
|
||
|
||
真值包在运行前冻结并与 Agent 输入分开保存，至少包含：管段及端点、泄漏参数和单位、观测窗口、传感器映射、独立拓扑参考、允许的等价候选集合、定位是否具备有效流量输入。工单只给近似位置、时间和现象；SCADA 检测器只能看到已释放观测及设备元数据。隐藏真值不得进入 Skill、提示词、任务说明、MCP 上下文、可读工作区、文件名或执行轨迹。
|
||
|
||
由于当前仿真将 emitter 放在管段端点，邻近管段可能不可区分。定位适用的用例按冻结的等价候选集合和排名评估（Hit@1/3/10），不强求唯一 ID。爆管定位需要有效的 `burst_leakage`（m³/s）；孔口面积（cm²）不能直接代替流量。缺少输入时，评分应奖励明确说明限制和所需数据，不鼓励猜测。
|
||
|
||
总分 100，结果与过程分开报告：
|
||
|
||
| 维度 | 权重 | 评分依据 |
|
||
|---|---:|---|
|
||
| 业务结果 | 60 | 触发来源与结论置信度 10；证据、时间窗、单位和数据质量 15；定位 Hit@1/3/10 或正确 abstain 15；影响与不可隔离判断 10；报告和人工后续建议 10 |
|
||
| 工具执行 | 20 | 场景清单定义的唯一必需操作有效完成率 12；有效参数、时间/单位范围及结果证据引用 8；同一操作重复调用不增加分数 |
|
||
| 计划推进 | 15 | 依赖顺序与证据覆盖 6；根据新证据调整计划 5；报告终态、待人工确认和停止条件 4；不评分模型私有思维链或固定调用顺序 |
|
||
| 效率 | 5 | 仅在业务结果至少 45/60 且无关键错误陈述时计分；以已接受基线的 Token、Agent wall time、有效调用数中位数对比，三项等权，单项最高 1.67 分 |
|
||
|
||
定位分在“输入足以定位”的真值用例中按 Hit@1=15、Hit@3=12、Hit@10=8、未命中=0；输入不足的用例不要求猜管段，明确限制和所需数据得 15，猜测得 0。工具有效完成率按每个场景冻结的唯一必需操作计分；单个操作重复尝试只取首次有效终态，额外调用不扩大分母或分子。
|
||
|
||
结构化事实、调用结果、时间/单位、候选排名、计划依赖、任务终态由确定性 scorer 判定。报告措辞与计划是否有证据支撑由同一固定版本盲评器独立评分两次，输出结构化子分和引用依据；每次保留评审器模型、提示词版本与原始评分。黄金样例由爆管业务负责人标注。双评差异超过任一子项 2 分、评审器无证据引用或关键结论不确定时转人工复核，复核值和原因进入报告。效率基线建立后，单项得分为 `1.67 × min(1, 基线中位值 / 当前值)`，三项合计最高 5 分；效率基线建立前，该项标为 `unscored`，报告总分上限 95，不伪造完整 100 分。
|
||
|
||
报告必须同时给出总分、业务通过率、工具调用成功率、定位 Hit@k、误报/漏报、延迟、分项分数和失败原因。队列 accepted 不算计算成功；MCP `isError`、超时和业务拒绝分开统计。系统错误记为 `infra_error`，保留尝试并有限重试幂等步骤；模型业务失败按实际结果计分。不做 retry-until-pass。
|
||
|
||
初始分项数值映射需要用一个人工审阅的黄金样例和重复运行校准后冻结为 scorer 版本；不能在第一次运行后按期望结果回调规则。首轮建议每个就绪用例重复 3 次，并对同版本做 A/A 重跑，估计模型随机波动；小样本只报告原始分布，不声称统计显著。
|
||
|
||
## 自动执行与复现
|
||
|
||
正式 runner 的单个入口按以下检查点运行：
|
||
|
||
1. `prepare`：校验套件、来源版本、传感器/数据窗口、触发可检出性、模型拓扑和真值包完整性；输出明确就绪/阻塞清单。
|
||
2. `snapshot`：以只读导出生成 BizDB、TimescaleDB 及必要文件的不可变版本包和哈希；所有评测写入只落在该版本的可写副本。
|
||
3. `trigger`：每例建立唯一 attempt ID，按 WO 或逐步 SCADA 事件路径触发。SCADA 没触发时记录触发失败，不补发 Agent 任务。
|
||
4. `investigate`：通过真实 Agent Host 和 Server/MCP 执行，脚本化反馈只提供当时可知事实；模型不得读取未来观测或真值。
|
||
5. `collect`：记录 case/attempt、task/run/execution/session、任务和报告修订、计算 job、MCP receipt、工具调用、计划版本、Token/耗时与终态。续跑先查已有业务 ID，禁止重复建单或重复触发。
|
||
6. `score/archive`：确定性 scorer 读取隐藏真值和收集轨迹，生成逐例 JSON、汇总报告、HTML/CSV 可选视图及所有代码/配置/数据/scorer 指纹。基线升级由人工明确选择。
|
||
|
||
每个 case 串行运行，直到能证明不同可写副本完全隔离后再并发。事件时间使用虚拟时钟；JWT、worker lease、heartbeat 和 HTTP timeout 使用现实时间。Agent 输入的查询统一受 `knowledge_cutoff` 约束。每次运行保留所有尝试和原始错误，不保存密钥、访问令牌或完整 DSN。结果进入 Git 忽略的私有工件目录或受控 CI 存储，不提交业务观测和轨迹。
|
||
|
||
每轮实验固定记录：Agent/Server/frontend 代码内容摘要、提示词与 Skill 摘要、模型及参数、MCP 工具 schema/版本、数据快照 ID/哈希、suite/scorer 版本、基线版本、case、重复次数、运行预算和实际服务指纹。只存 Git SHA 不足以标识当前含未提交改动的运行版本。
|
||
|
||
## 当前准备状态与执行门槛
|
||
|
||
当前已有：四个候选场景清单、严格字段校验、分库只读查询与规则预览函数、独立拓扑参考。只读预检已在 2026-11-03 执行：四个场景均有 83 个完整短窗压力测点，但没有一个触发当前短窗 SCADA 规则；15 天检测窗口也没有满足连续 1440 点的压力节点。B02 的工单路径是唯一有现成数据候选的路径，B02 的 SCADA 路径仍需隔离生成能触发的事件数据。该结果只说明历史窗口/当前规则的匹配情况，不证明实际 worker 或 Agent 行为。刚加入的 `scripts/prepare_burst_benchmark.py` 只生成私有预检 JSON，不会建任务、写 SCADA 修正值、运行 Agent 或声称数据集已冻结。
|
||
|
||
完成自动评测前仍需依次补齐并验收：
|
||
|
||
1. 已执行只读预检；下一步由评测维护者确认是否保留 B02-WO 为首个可用试跑，并在隔离副本生成 SCADA 触发与 B01/B03/B04 所需观测。
|
||
2. 爆管业务/水力分析负责人审阅四个用例的数值参考、有效泄漏流量和等价候选；评测维护者据此固定触发规则与控制组期望。
|
||
3. Server 数据维护者形成带模型/观测版本哈希的快照导出和隔离 BizDB/TimescaleDB 路由；通过受限角色、连接路由检查和数据库审计证明 Agent/worker 无法写回源库。源库其他日常服务可能同时写入，因此验收证明 benchmark 没有源写入，不承诺整库前后字节完全相同。
|
||
4. Agent 与 Server 维护者实现可恢复 runner 和全链路轨迹导出；先执行一例 WO 与一例 SCADA 的闭环试跑。
|
||
5. 评测维护者与爆管业务负责人共同冻结 scorer，在首个通过门槛的用例跑 A/A；再扩到 8 例 × 3 次 × 候选版本。
|
||
|
||
若源数据在准备期间被日常业务改变，重新读取后产生不同内容指纹，应建立新快照版本，不覆盖旧报告。预检报告只证明来源库读取与候选数据检查完成，不是 Agent 评测结果或上线验收。
|
||
|
||
## 命令
|
||
|
||
只读检查命令（在 Server 仓库根目录）：
|
||
|
||
```bash
|
||
conda run -n server python scripts/prepare_burst_benchmark.py
|
||
```
|
||
|
||
只检查单个场景可追加 `--case B02`。预检报告写入 `data/benchmark/preflight/`，该目录在 `.gitignore` 中。此命令只读源数据库；正式评测 runner 尚未提供。
|