一个可运行的带工具 Agent 评测系统框架，支持混合任务（确定性 + 生成式），面向两类场景： 多模型选型对比 与 CI 回归门禁。
本框架用 SQLite + 进程内异步并发跑通全链路，但把存储层、适配层、编排层都做了抽象， 后续可平滑替换为 Postgres + Redis/Celery 等，以支撑千万级用例、20+ 模型、分钟级频率的目标， 而无需推翻架构。
评测系统的价值不在于"跑出一个分数"，而在于让模型选型与质量回归成为可信、可复现、可持续的工程决策。基于这一点，本框架遵循以下核心理念：
- 面向决策，而非面向跑分：评测的终点是回答两个问题——"该选哪个模型"和"这次改动是否让质量退化"。因此系统天然区分选型对比（横向多模型矩阵）与 CI 门禁（纵向阈值卡口）两类场景，而非只产出一个孤立指标。
- 抽象先行，实现随后：存储、适配、编排三层都以接口/抽象定义，框架用最轻量的实现（SQLite + 进程内 asyncio）跑通全链路，但保证从框架到生产（Postgres、分布式队列、真实 API）只需替换实现、不动架构。
- 混合任务，分而治之：确定性任务与生成式任务的评分本质不同，前者追求快、稳、可复现，后者需要语义层面的判断。系统按用例类型路由到规则裁判或 LLM 裁判，用合适的方法评合适的任务。
- 可信度是第一约束：可复现、成本可控、循环可终止不是附加功能，而是评测系统能被信任的前提。这些约束贯穿数据记录、缓存策略与 Agent 执行预算的设计。
┌─────────────────────────────────────────────┐
│ web/ 报告与可视化 (FastAPI + HTML) │ 对比矩阵 / 下钻 / 触发
├─────────────────────────────────────────────┤
│ scoring/ 评分裁判层 │ 规则裁判 + LLM 裁判（按用例类型路由）
├─────────────────────────────────────────────┤
│ orchestrator/ 执行编排层 │ 异步并发 / 限流 / 重试 / 缓存 / 聚合
├─────────────────────────────────────────────┤
│ agent/ Agent 运行器 │ ReAct 多步循环 + 工具注册 + 迭代预算
├─────────────────────────────────────────────┤
│ adapters/ 模型适配层 │ 统一接口，屏蔽各家 API；采集 token/延迟
├─────────────────────────────────────────────┤
│ store/ 数据集/结果存储 │ Store 抽象 + SQLite 实现（可换 Postgres）
├─────────────────────────────────────────────┤
│ models.py 核心数据结构 │ 用例 / 轨迹 / 结果 / 运行
└─────────────────────────────────────────────┘
EVAL/
├── config.py 全局配置（存储、并发、阈值等）
├── requirements.txt
├── run_web.py 启动 Web 服务
├── run_ci.py CI 门禁命令行入口（返回退出码）
├── seed_dataset.py 生成示例数据集
├── data/ 运行时数据（SQLite、缓存、数据集，git 忽略）
└── eval_system/
├── models.py 数据模型
├── store/ 存储层（抽象 + sqlite 实现）
├── adapters/ 模型适配层（base + mock + openai 兼容）
├── agent/ Agent 运行器 + 工具
├── scoring/ 评分层（规则 + LLM 裁判）
├── orchestrator/ 执行编排
└── web/ FastAPI 服务与模板
需要本机安装 真实的 Python 3.10+。
核心评测链路只用标准库；只有 Web 层需要 requirements.txt 里的三方库。
# 1. 创建虚拟环境并装依赖
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
# 2. 初始化数据库 + 生成示例数据集（用 mock 模型，无需任何 API Key）
python seed_dataset.py
# 3a. 启动 Web 界面
python run_web.py
# 浏览器打开 http://localhost:8000
# 3b. 或者跑 CI 门禁（对某数据集跑评测，低于阈值返回非零退出码）
python run_ci.py --dataset smoke --models mock-fast,mock-smart --threshold 0.7每条用例带 task_type：
deterministic：有标准答案（分类/抽取/工具正确性）→ 规则裁判，快、稳、可复现。generative：开放式生成（摘要/问答）→ LLM 裁判，按 rubric 打分并给理由。- Agent 轨迹层面额外评：任务完成、工具调用正确率、步数效率、成本。
| 当前（框架） | 生产替换 | 改动位置 |
|---|---|---|
| SQLite | Postgres | store/ 新增实现，接口不变 |
| 进程内 asyncio 并发 | Redis + Celery/Arq 分布式队列 | orchestrator/ |
| 全量顺序跑 | 分层数据集：分钟级只跑冒烟集，全量离线 | 数据集 tags + 编排调度 |
| Mock 适配器 | 各家真实 API 适配器 | adapters/ 新增文件 |
| 内联 HTML | 独立前端 (React) | web/ |
- 可复现是底线：记录模型版本、参数、数据集版本、prompt、时间戳，保留原始输出与裁判理由。
- 裁判也要被评测：LLM 裁判需用黄金人工标注集校准一致率。
- 成本可控：结果缓存 + 分层数据集，避免 20 模型 × 千万用例 × 多次采样的组合爆炸。
- 循环可终止：Agent 有迭代预算与重复检测，防止死循环耗尽资源。