211 lines
8.6 KiB
Markdown
211 lines
8.6 KiB
Markdown
# zcbot 技术评测
|
||
|
||
该目录是独立于生产执行链的黑盒评测旁路。它只通过 zcbot `/v1` API 创建
|
||
隔离任务、发送指令、读取回复和下载产物，不直连数据库。
|
||
|
||
## 评测框架
|
||
|
||
当前实际采用的是仓库内的轻量 `zcbot evaluation harness`，通过 `/v1` API 做
|
||
端到端黑盒执行，用确定性断言、重复运行、`pass@1`/`pass^k` 和五维加权完成计分。
|
||
工程与安全审计实际调用 `unittest`、coverage.py、Ruff、Mypy、Bandit 和
|
||
`pip-audit`。
|
||
|
||
开源框架采用状态必须与报告证据一致：
|
||
|
||
- **Inspect AI**：已实现 JSONL 导出桥接，但因 Click 依赖冲突需在隔离环境运行；
|
||
当前基线报告没有直接使用 Inspect runner。
|
||
- **Promptfoo**：计划用于测试环境的提示注入与越权红队，本次生产安全评测未执行。
|
||
- **ScienceAgentBench**：作为材料科研公共任务候选来源，当前任务集尚未直接采用其
|
||
verified 样本。
|
||
|
||
每份 Markdown/JSON 报告都会记录上述框架和采用状态，防止把“兼容/规划接入”误写
|
||
成“已经用该框架完成跑分”。
|
||
|
||
## 当前完整基线（2026-08-03）
|
||
|
||
本基线由生产安全任务集和本地工程/安全审计合并生成：
|
||
|
||
| 维度 | 权重 | 得分 | 主要证据 |
|
||
|---|---:|---:|---|
|
||
| 任务质量 | 40 | 100.00 | 方解石材料问答通过 |
|
||
| 可靠性 | 20 | 100.00 | 固定答案连续 3/3 次通过 |
|
||
| 安全性 | 15 | 0.00 | Bandit、pip-audit 均未达标 |
|
||
| 工程质量 | 15 | 66.67 | 编译、445 项测试、Ruff 通过；覆盖率和 Mypy 未达标 |
|
||
| 性能 | 10 | 100.00 | 短回答时延和成本均达标 |
|
||
|
||
- 安全封顶前加权分：**80.00 / 100**
|
||
- 最终总分：**59.00 / 100**（安全失败触发 59 分封顶）
|
||
- 测试：445 项通过，17 项跳过；覆盖率 51%，目标 70%
|
||
- Mypy：203 个错误，涉及 59 个文件；Ruff 阻断级检查通过
|
||
- Bandit：9 个高严重性问题；pip-audit：7 个包共 41 个已知漏洞
|
||
- 本轮线上 5 次调用总耗时约 11.11 秒，总成本约 ¥0.083307
|
||
|
||
完整证据由命令生成到 `reports/full/report.md` 和 `reports/full/report.json`。这里
|
||
记录的是带日期的基线快照；代码或依赖变化后应重新运行，报告文件才是最新事实源。
|
||
`reports/` 包含 task_id、扫描日志等运行产物，已加入 Git ignore，不提交仓库。
|
||
|
||
## 安全约束
|
||
|
||
- 默认只允许连接 `localhost`、`127.0.0.1` 或 `::1`。
|
||
- 实际运行必须显式传 `--execute`，避免误触发模型费用。
|
||
- Token 只从环境变量读取，不写入配置或报告。
|
||
- HTTP 客户端忽略 `HTTP_PROXY` / `HTTPS_PROXY`，避免评测 JWT 被透明代理转发。
|
||
- 每次重复运行使用独立工作目录；第一版不自动删除任务或文件，便于复盘轨迹。
|
||
- 必须使用专门的评测用户和测试环境。不得把 `.env` 中经隧道连接生产库的实例
|
||
当作评测目标。
|
||
|
||
## 快速开始
|
||
|
||
一条命令运行本地工程审计并生成统一报告：
|
||
|
||
```powershell
|
||
.\scripts\evaluate.ps1
|
||
```
|
||
|
||
```sh
|
||
sh scripts/evaluate.sh local
|
||
```
|
||
|
||
统一报告固定写入 `evaluation/reports/latest/report.md` 和 `report.json`。本地模式
|
||
不调用模型、不产生模型费用；因为只覆盖工程维度，报告显示暂定分，完整总分保持
|
||
`N/A`。
|
||
|
||
先校验任务集，不调用服务：
|
||
|
||
```powershell
|
||
.venv\Scripts\python.exe -m evaluation validate
|
||
```
|
||
|
||
准备专用测试实例和评测用户的 JWT：
|
||
|
||
```powershell
|
||
$env:ZCBOT_EVAL_TOKEN = "<test-user-jwt>"
|
||
.venv\Scripts\python.exe -m evaluation run --execute
|
||
```
|
||
|
||
报告写入 `evaluation/reports/report.json` 和 `report.md`。JSON 保存逐次 task_id、
|
||
成本、耗时和断言，Markdown 是便于评审的汇总。
|
||
|
||
单独运行本地工程审计：
|
||
|
||
```powershell
|
||
.venv\Scripts\python.exe -m evaluation audit
|
||
```
|
||
|
||
工程审计固定检查全量单测、Python 编译、覆盖率、Ruff、Mypy、Bandit 和
|
||
`pip-audit`。其中 Bandit 和 `pip-audit` 计入安全维度，其余计入工程维度。缺失
|
||
工具会明确显示 `unavailable` 并不得分。工程工具统一记录在
|
||
`evaluation/requirements.txt`，不进入生产依赖。在线评测加 `--with-audit` 可把
|
||
工程审计结果并入同一份百分制报告。
|
||
|
||
Inspect AI 单独记录在 `evaluation/requirements-inspect.txt`。它当前要求的 Click
|
||
版本与 zcbot 已有 Hugging Face 依赖冲突，禁止直接安装到项目 `.venv`；后续通过
|
||
隔离容器运行，并以本目录 JSON 任务集和报告格式作为两边交换契约。
|
||
|
||
远程测试实例必须额外显式确认：
|
||
|
||
```powershell
|
||
.venv\Scripts\python.exe -m evaluation run --execute --allow-remote `
|
||
--config evaluation\config.staging.json
|
||
```
|
||
|
||
仓库提供了线上地址的**低风险单次冒烟集**，不包含密钥探测、文件写入、并发或
|
||
跨用户操作：
|
||
|
||
```powershell
|
||
$env:ZCBOT_EVAL_TOKEN = "<dedicated-eval-user-jwt>"
|
||
.venv\Scripts\python.exe -m evaluation run --execute --allow-remote `
|
||
--config evaluation\config.production-smoke.json `
|
||
--suite evaluation\datasets\production_smoke.json `
|
||
--output evaluation\reports\production-smoke
|
||
```
|
||
|
||
该结果只覆盖任务质量和性能，因此总分按规则保持 `N/A`，不能冒充完整评估。
|
||
|
||
如需一条命令同时刷新工程审计、运行上述生产低风险冒烟并合并报告：
|
||
|
||
```powershell
|
||
$env:ZCBOT_EVAL_TOKEN = "<dedicated-eval-user-jwt>"
|
||
.\scripts\evaluate.ps1 -Mode production-smoke
|
||
```
|
||
|
||
```sh
|
||
ZCBOT_EVAL_TOKEN="<dedicated-eval-user-jwt>" \
|
||
sh scripts/evaluate.sh production-smoke
|
||
```
|
||
|
||
生产模式会实际调用模型并产生少量费用，只允许使用专用评测账号。它不会运行安全
|
||
攻击、并发、跨用户或文件写入用例。即使合并工程与冒烟结果，可靠性和安全维度仍
|
||
未覆盖，因此完整总分仍为 `N/A`。
|
||
|
||
运行生产可安全执行的完整五维流程：
|
||
|
||
```powershell
|
||
$env:ZCBOT_EVAL_TOKEN = "<dedicated-eval-user-jwt>"
|
||
.\scripts\evaluate.ps1 -Mode production-full
|
||
```
|
||
|
||
```sh
|
||
ZCBOT_EVAL_TOKEN="<dedicated-eval-user-jwt>" \
|
||
sh scripts/evaluate.sh production-full
|
||
```
|
||
|
||
结果写入 `evaluation/reports/full/report.{md,json}`。线上部分包含任务质量 1 次、
|
||
固定答案可靠性 3 次和性能 1 次；安全维度来自本地 Bandit 与依赖漏洞审计。该流程
|
||
不执行密钥读取、跨用户、压力测试或文件写入。
|
||
|
||
也可以手动合并任意已有 JSON 报告：
|
||
|
||
```powershell
|
||
.venv\Scripts\python.exe -m evaluation combine `
|
||
--report evaluation\reports\engineering-audit.json `
|
||
--report evaluation\reports\production-smoke-calibrated\report.json `
|
||
--output evaluation\reports\latest
|
||
```
|
||
|
||
同一维度出现在多份报告中时，按各报告的 `case_count` 加权；五个一级维度再按
|
||
40/20/15/15/10 固定权重汇总。Markdown 会列出每个输入报告及其生成时间。
|
||
|
||
## 任务集
|
||
|
||
任务集是 JSON 文件。每个 case 声明：
|
||
|
||
- `dimension`：`task_quality`、`reliability`、`security`、`engineering` 或
|
||
`performance`；
|
||
- `prompt`：发送给 zcbot 的真实用户指令；
|
||
- `assertions`：可审计的确定性断言；
|
||
- `repetitions`：可选，覆盖任务集默认重复次数；
|
||
- `model_profile`、`skill`：可选，创建任务时传给 zcbot。
|
||
|
||
当前支持的断言：
|
||
|
||
- 回复：`response_nonempty`、`response_contains`、`response_not_contains`、
|
||
`response_regex`；
|
||
- 运行：`run_succeeded`、`max_duration_s`、`max_cost_cny`；
|
||
- 产物：`artifact_exists`、`artifact_min_bytes`、`artifact_zip_valid`、
|
||
`artifact_text_contains`。
|
||
|
||
断言按 `weight` 加权。用例得分是其断言加权通过率；重复运行取平均，并同时报告
|
||
`pass@1` 和要求全部重复均通过的 `pass^k`。
|
||
|
||
缺少任何一级维度时，完整总分显示为 `N/A`，只展示“已覆盖维度暂定分”，防止用
|
||
不完整任务集制造虚高总分。安全维度存在失败时，完整总分最高封顶为 59。
|
||
|
||
## 后续扩展
|
||
|
||
- `materials_core.json` 提供 10 个首批材料研发/产物任务；它仍是校准集，不是
|
||
最终院内金标准。
|
||
- 用 `export-inspect` 生成隔离 Inspect 环境可摄取的 JSONL：
|
||
|
||
```powershell
|
||
.venv\Scripts\python.exe -m evaluation export-inspect `
|
||
--suite evaluation\datasets\materials_core.json `
|
||
--output evaluation\exports\materials_core.inspect.jsonl
|
||
```
|
||
|
||
- 在隔离环境用 Inspect Agent Bridge 包装 zcbot HTTP 适配器，复用其公共任务集和
|
||
查看器；
|
||
- 用 Promptfoo 的自定义 provider 调用同一客户端，运行提示注入与越权红队集；
|
||
- 接入 ScienceAgentBench verified 子集和 PPT benchmark；
|
||
- 增加只在测试数据库运行的并发、取消恢复、知识库和跨用户隔离用例。
|