README overhaul: features overview, config section, perf stats, FAQ

- accurate output structure (summary.xlsx/csv + per-bench xlsx; drop
  stale detail.md/summary.md mentions)
- dedicated YAML-config section documenting the keys that actually work
  (generation params + repeats + max_input_tokens) and precedence
- perf-stats table: what is always collected vs --perf streaming-only
- FAQ: endpoint probe, context-overflow shrink, thinking-mode notes
  (non-stream chat_template_kwargs vs cloud-API param), auto-stream
- config/README.md rewritten to match the flat-key reality (old file
  documented a directory scheme + judge/env keys that are not consumed)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
sora 2026-09-14 02:30:38 +00:00
parent a17dd88611
commit e9d7e7f4eb
2 changed files with 161 additions and 88 deletions

182
README.md
View File

@ -1,11 +1,22 @@
# EvalHarness
插件式 LLM/Agent 评测框架28 个 benchmark 开箱即用,官方口径 prompt 与判分,任意 OpenAI 兼容端点,断点续跑。
插件式 LLM / Agent 评测框架:**28 个 benchmark 开箱即用,官方口径 prompt 与判分,任意 OpenAI 兼容端点,断点续跑,与 evalscope 对齐**
```
提供端点 → 拉数据 → 渲染官方 prompt → 并发生成 → 官方判分 → 报告
提供端点 → 拉数据 → 渲染官方 prompt → 并发生成 → 官方判分 → Excel/JSON 报告
```
## 特性
- **28 个 benchmark**:数学 / 知识 / 问答 / 长上下文 / 代码Docker 沙箱)/ Agent 工具调用prompt 与判分器按官方实现逐字节复刻,与 evalscope 双层验证对齐(见 §10
- **任意端点**:单端点、多端点池(轮询 + 自适应并发 + failover、云 API 全兼容vLLM / sglang / lmdeploy / ollama / OpenAI 协议直连
- **断点续跑**:每条预测完成即落盘,中断重跑只补缺口;`repeats` 多轮采样自动隔离断点
- **YAML 配置**:逐 bench 生成参数temperature / max_tokens / repeats …)集中管理,命令行保持极简
- **长输入安全**tokenizer 中段截断(`max_input_tokens`+ 上下文溢出自适应收缩重试
- **性能统计**:延迟 / 吞吐 / token 用量默认采集;`--perf` 追加流式 TTFT / ITL
- **全链路插件化**数据集、判分、prompt 渲染、适配器、沙箱、进度条、主题、钩子均可单文件注册扩展
- **模型指纹核验**fp_fusion 五维探针电池,检测 API 换模 / 降配 / 冒充 / 套壳
## 0. Benchmarks
| 族 | benchmark |
@ -24,7 +35,11 @@ evalharness eval list # 28 个判分 recipe
## 1. 安装
Python ≥ 3.10;代码执行类 benchmark 需宿主机 Docker镜像判分时自动拉取
| 依赖 | 说明 |
|---|---|
| Python ≥ 3.10 | 核心零三方依赖pydantic 除外) |
| Docker可选 | 代码执行类 benchmarkhumaneval 等)需要;镜像判分时自动拉取 |
| `rich`(可选) | 进度条;缺失自动降级纯文本 |
```bash
git clone https://git.meta-stone.net/sora/EvalHarness.git
@ -40,7 +55,7 @@ pip install .
evalharness eval run gsm8k --model mock-boxed --limit 8
```
## 2. 运行命令
## 2. 快速开始
六个基准一次跑完(默认用法;逐 bench 生成参数自动读 `evalharness/config/default.yaml`aime 系列按配置自动跑 12 遍取均值):
@ -56,7 +71,7 @@ evalharness eval run humaneval aime25 aime26 gpqa_diamond mmlu_pro longbench_v2
--hf-endpoint https://hf-mirror.com
```
单端点最小示例
单端点最小示例:
```bash
evalharness eval run gsm8k \
@ -67,6 +82,35 @@ evalharness eval run gsm8k \
--out-dir results/run1
```
## 3. 配置YAML
逐 bench 生成参数集中在 `evalharness/config/<name>.yaml`。目录里只有一个 yaml 时**自动加载**`--config <name>` 显式指定。
```yaml
default: # 所有 bench 继承的协议级默认
temperature: 0.0
top_p: 1.0
max_tokens: 32768
aime25: # 逐 bench 覆盖
temperature: 1.0 # 采样温度temp=1 方差测量)
max_tokens: 8192 # 生成预算
repeats: 12 # 跑 12 遍报均值 ± 极差(断点按轮隔离,互不串用)
longbench_v2:
max_input_tokens: 128000 # 超长输入的 tokenizer 中段截断预算
```
优先级(低 → 高):
```
DatasetSpec.gen_config < default < bench < 命令行显式参数
```
当前支持的键:`temperature` `top_p` `max_tokens` `max_input_tokens` `repeats`
## 4. 进阶用法
多端点池(轮询 + 自适应并发 + failover
```bash
@ -93,27 +137,6 @@ evalharness eval run bfcl_v3 --api-url http://localhost:8000/v1 --model qwen3-8b
--env bfcl_mock
```
### 指纹核验fp_fusion
回答一个问题:**API 背后跑的,到底是不是它声称的那个模型?** 向 OpenAI 兼容端点发送探针电池(回答分布 / 自我身份 / 元知识 / 能力边界 / 文风五维),与内置参考指纹库比对,输出五档裁决 + 0~1 融合分 + 证据链。检测偷梁换柱、降配缩水、主动冒充(伪身份注入屈服)、套壳拼装与中转代理;`--mode full` 一次运行产出 verify / attribution / variant / adversarial / robustness 五个视图。
```bash
evalharness fingerprint list # 内置参考指纹库fp_fusion 口径 + detector 旧口径)
evalharness fingerprint run \
--api-url http://localhost:8000/v1 --model Qwen3-8B \
--mode full --cells core16 --text-skip pruned7 \
--d-samples 25 --baseline-samples 5 --timeout 90 \
--impersonate "You are Kimi, Moonshot AI virtual assistant." \
--reference glm53 \
--report-path reports/fp_qwen.json
```
- `--reference` 接受短名(如 `glm53`,见 `fingerprint list`)或 JSON 路径;省略 = 自证模式(裁决上限 LIKELY_MATCH
- `--impersonate` 注入伪身份启用对抗视图(冒充检测);剪枝定稿协议即上例参数,单次 505 条请求,公网 14.528 min本地 vllm 5.67 min
- 报告写入 `--report-path`,同目录 `raw_answers.jsonl` 存全部探针原文
- 离线分析与参考采集脚本(`cell_snr.py` / `validate_*.py` / `collect_ref.sh` 等,可直接 `python <script>` 运行)与完整方法论文档见 `evalharness/fingerprint/fp_fusion_介绍.md`
Python API
```python
@ -125,30 +148,44 @@ rep.save('gsm8k.report.json')
# notebook / async 环境用 await evalharness.arun(...)
```
## 3. 参数速查
## 5. 参数速查
| 参数 | 作用 |
|---|---|
| `--api-url` `--model` `--provider` | 端点、模型名(纯名字,无需拼 spec、协议`openai-chat`/`openai-pool` |
| `--api-key` | 显式 key优先于环境变量只进请求头不写入 spec/报告) |
| `--disable-thinking` | `enable_thinking=false`Qwen3 类模型推荐;带 tools 的请求自动退回兼容软开关) |
| `--disable-thinking` | `enable_thinking=false`Qwen3/GLM 类模型推荐;带 tools 的请求自动退回兼容软开关) |
| `--judge-model` `--judge-api-url` `--judge-api-key` `--judge-provider` | judge 端四件套,语义与主模型对称 |
| `--config NAME` | 指定 `evalharness/config/<NAME>.yaml`(省略时唯一 yaml 自动加载) |
| `--profile NAME` | 命名生成参数集(`dp4-nothink` / `qwen3-es-parity` / `t1-short` 或自定义) |
| `--limit N` / `--limit-per-task N` | 全局前 N / 每子集前 N多科目 bench 用后者;可组合取交集) |
| `--subset` `--split` `--source` | 覆盖子集 / split / 数据源(可指本地路径离线跑) |
| `--concurrency N` | 并发(默认 32长输出 bench 建议 8-16 |
| `--resume [PATH]` | 断点续跑;默认 `<cache-dir>/ckpt/<bench>.jsonl` |
| `--profile NAME` | 命名生成参数集(`dp4-nothink` / `qwen3-es-parity` / `t1-short` 或自定义) |
| `--env NAME` | agent 环境(`bfcl_mock` 等) |
| `--perf` | 采集流式 TTFT / ITL / 重试率入报告 |
| `--hf-endpoint URL` | 数据下载端点(如 `https://hf-mirror.com`,免手动 export |
| `--cache-dir DIR` | 缓存根目录(数据缓存 + 断点同根;默认 `$EVALHARNESS_CACHE``~/.cache/evalharness` |
| `--out FILE` / `--out-dir DIR` | 报告落盘;多 bench 时写 `reports/` + `viz/` + `summary.md` |
| `--out FILE` / `--out-dir DIR` | 报告落盘,见 §6 输出结构 |
| `--style text\|md\|md_compare\|excel\|radar\|errors` | 结果渲染样式 |
| `--no-progress` | 关闭 Rich 进度条(重定向日志时用) |
API key 解析顺序:`--api-key` > 按端点域名的环境变量(`api.openai.com``OPENAI_API_KEY``anthropic.com``ANTHROPIC_API_KEY``dashscope``DASHSCOPE_API_KEY``bigmodel``ZAI_API_KEY`> `OPENAI_API_KEY`。自建端点无鉴权可不管。
## 4. 评测结果
## 6. 输出结构
`--out-dir` 产出(不传时自动保存到 `evalharness-results/<时间戳>-<模型>/`
```
<out-dir>/
├── summary.xlsx 总表Summary / Perf / Categories / Samples 四 sheet主入口
├── summary.csv 同一张总表的 csv 版
└── <bench>/ 每个 benchmark 一个目录
├── report.jsonl 完整报告流式行格式首行报告头之后每行一个样本grep/tail 友好)
└── <bench>.xlsx 该 bench 的独立 ExcelSummary/Perf/Categories/Samples
```
查看与对照:
```bash
evalharness viz show gsm8k.report.json # 控制台表格
@ -157,18 +194,19 @@ evalharness viz show report.json --style excel # 4-sheet 仪表盘
evalharness viz show report.json --style errors # 失败样本下钻
```
`--out-dir` 产出结构(不传时自动保存到 `evalharness-results/<时间戳>-<模型>/`
## 7. 性能统计
```
<out-dir>/
├── summary.xlsx 总表 ExcelSummary/Perf/Categories/Samples 四 sheet主入口
├── summary.csv 同一张总表的 csv 版
└── <bench>/ 每个 benchmark 一个目录
├── report.jsonl 完整报告流式行格式首行报告头之后每行一个样本grep/tail 友好)
└── detail.md 该 bench 的 markdown 详情
```
每轮运行的延迟与 token 用量默认采集,进 `summary.csv` 的 Perf 列与 `metric_groups['perf']`
## 5. 缓存与断点
| 指标 | 采集条件 |
|---|---|
| `latency_mean/p50/p90/p95/p99_s` | 始终采集(逐请求墙钟) |
| `output_tps` `request_qps` `input/output_tokens` `success_rate` `retry_rate` | 始终采集 |
| `ttft_mean/p90/p99_s``tpot_*`(逐 token 延迟) | 仅 `--perf`(流式才有首 token 时刻) |
`repeats` 模式下:分数报**均值**`<metric>_last_run` 保留末轮值),时间 / token 报**全部轮次总和**。
## 8. 缓存与断点
```bash
evalharness data fetch gsm8k mmlu --workers 8 # 预取(首次运行也会自动下载)
@ -177,22 +215,22 @@ evalharness data show gsm8k -n 2 # 看前 2 条样本
evalharness data unload gsm8k # 删缓存
```
- 缓存根目录由 `--cache-dir` 指定(或环境变量 `$EVALHARNESS_CACHE`,默认 `~/.cache/evalharness`,结构
缓存根目录由 `--cache-dir` 指定(或 `$EVALHARNESS_CACHE`,默认 `~/.cache/evalharness`
```
<cache-dir>/
├── datasets/<bench>/<subset>_<split>-<hash>/ 数据缓存raw/ 原始字节 + samples.jsonl 统一样本)
├── .raw/<repo-hash>/ 跨条目共享的下载 blob多子集只下载一次
└── ckpt/<bench>[_<subset>].jsonl 预测断点(每条完成即追加)
└── ckpt/<bench>[_<subset>][:repN]-<hash>.jsonl 预测断点(每条完成即追加repeats 按轮隔离
```
- 数据缓存内容寻址subset/split/source 变更自动新条目),位置 `<cache-dir>/datasets/`
- 断点每条预测即写盘;**改了 prompt 模板须删旧断点**`rm <cache-dir>/ckpt/<bench>*.jsonl`),否则复用旧预测
- 网络抖动三层防护15s 连接超时快速失败 → 池内换端点 → 分钟级退避重试,断网不丢批次
- 数据缓存内容寻址subset/split/source 变更自动新条目)
- **改了 prompt 模板须删旧断点**`rm <cache-dir>/ckpt/<bench>*.jsonl`),否则复用旧预测
- 网络抖动三层防护15s 连接超时快速失败 → 池内换端点 → 指数退避重试,断网不丢批次
- 判分与生成解耦:换 recipe / grader 对存量预测直接重判(`evaluate(ds, preds)`),模型不被重复调用
- Docker 镜像源回退链可用 `EVALHARNESS_DOCKER_MIRRORS` 覆盖(逗号分隔模板,`{img}` 占位)
## 6. 扩展
## 9. 扩展
加数据集(单文件放入 `evalharness/data/datasets/`,自动注册):
@ -226,7 +264,37 @@ def mybench():
| 生命周期钩子 | `@register_hook('on_benchmark_failed'/'on_benchmark_done')` | 观察/扩展运行webhook 通知、失败重试策略),钩子报错不影响主流程 |
| 端点探针 | `@register_prober('ping'/...)` | 运行前的端点可用性验证策略(`EVALHARNESS_PROBER` 环境变量选择) |
## 7. 架构
## 10. 对齐验证
prompt 与判分器经双层验证(字符串级:同一记录双侧渲染逐字节一致;分数级:同题同参数对比 evalscope
- Qwen3-8B23/28 分差 < 0.05
- DeepSeek-V4-Flash20+/25 分差 < 0.05mmlu_pro 0.0000
残差均已定性(金标集差异 / 排列敏感 / benchmark 侧缺陷),见各 recipe 注释。
## 附录 A模型指纹核验fp_fusion
回答一个问题:**API 背后跑的,到底是不是它声称的那个模型?** 向 OpenAI 兼容端点发送探针电池(回答分布 / 自我身份 / 元知识 / 能力边界 / 文风五维),与内置参考指纹库比对,输出五档裁决 + 0~1 融合分 + 证据链。检测偷梁换柱、降配缩水、主动冒充(伪身份注入屈服)、套壳拼装与中转代理;`--mode full` 一次运行产出 verify / attribution / variant / adversarial / robustness 五个视图。
```bash
evalharness fingerprint list # 内置参考指纹库fp_fusion 口径 + detector 旧口径)
evalharness fingerprint run \
--api-url http://localhost:8000/v1 --model Qwen3-8B \
--mode full --cells core16 --text-skip pruned7 \
--d-samples 25 --baseline-samples 5 --timeout 90 \
--impersonate "You are Kimi, Moonshot AI virtual assistant." \
--reference glm53 \
--report-path reports/fp_qwen.json
```
- `--reference` 接受短名(如 `glm53`,见 `fingerprint list`)或 JSON 路径;省略 = 自证模式(裁决上限 LIKELY_MATCH
- `--impersonate` 注入伪身份启用对抗视图(冒充检测);剪枝定稿协议即上例参数,单次 505 条请求,公网 14.528 min本地 vllm 5.67 min
- 报告写入 `--report-path`,同目录 `raw_answers.jsonl` 存全部探针原文
- 离线分析与参考采集脚本(`cell_snr.py` / `validate_*.py` / `collect_ref.sh` 等,可直接 `python <script>` 运行)与完整方法论文档见 `evalharness/fingerprint/fp_fusion_介绍.md`
## 附录 B架构
```
data/ 统一 Sample schema惰性物化内容寻址缓存28 个单文件插件)
@ -242,11 +310,19 @@ progress/ Rich 每样本进度(缺 rich 自动降级)
层间严格分离:数据层只回答"题目与金标",判分层只回答"如何评判",模型层只回答"如何触达";预测是不可变 artifact。
## 8. 对齐验证
## 附录 C常见问题
prompt 与判分器经双层验证(字符串级:同一记录双侧渲染逐字节一致;分数级:同题同参数对比 evalscope
**端点不可达ConnectError跑样本前即中止**
探针在首个样本前发 1-token ping失败即给出 curl 验证命令并中止,零 token 浪费。按提示 `curl -m 5 <api-url>/chat/completions ...` 手工确认服务在跑。
- Qwen3-8B23/28 分差 < 0.05
- DeepSeek-V4-Flash20+/25 分差 < 0.05mmlu_pro 0.0000
**上下文溢出400 maximum context length**
自动截短 prompt 15% 重试(跨 tokenizer 安全边际1-2 次收敛);`max_input_tokens`YAML可预先做中段截断长上下文 bench 建议配置。
残差均已定性(金标集差异 / 排列敏感 / benchmark 侧缺陷),见各 recipe 注释。
**思考模式thinking关不掉**
`--disable-thinking``chat_template_kwargs`非流式请求完全生效sglang/vLLM 已验证)。注意:部分网关在**流式**路径会剥掉该参数——本框架仅在 `max_tokens > 100000` 时自动转流式(聚合还原为非流式响应),常规 8k/32k 预算不受影响。智谱云 API 风格的 `thinking: {"type": ...}` 参数 sglang 不识别,自建端点请用本框架的开关。
**GLM 大预算生成挂起**
非流式大 body100k+ token 输出)部分网关会缓冲到超时;自动流式路径已内置(见上条),无需手工干预。
**Docker 拉镜像慢/失败**
`EVALHARNESS_DOCKER_MIRRORS="mirror.example.com/{img},docker.io/{img}"` 覆盖回退链。

View File

@ -1,63 +1,60 @@
# 配置目录
每个模型/协议一个文件夹,内含逐 bench 的 YAML 配置
逐 bench 生成参数的 YAML`eval run` 时自动应用
```
config/
├── README.md ← 本文件
└── dp4-nothink/ ← 模型/协议名
├── default.yaml ← 协议级默认参数(所有 bench 继承)
├── aime24.yaml ← 逐 bench 覆盖
├── aime25.yaml
├── ...
└── swe_bench_verified.yaml
├── README.md ← 本文件
└── default.yaml ← 当前唯一配置(自动加载)
```
## 每个 YAML 结构
## YAML 结构(单文件,扁平键)
```yaml
# generation: 传给模型的参数
generation:
temperature: 1.0
max_tokens: 8192
default: # 协议级默认,所有 bench 继承
temperature: 0.0
top_p: 1.0
max_tokens: 32768
# run: 运行方式
run:
repeats: 12 # 跑 12 遍取均值temp=1 方差测量用)
limit: null # 全量 / limit_per_task: 10 每子集 10 条
checkpoint: true
resume: true
aime25: # 逐 bench 覆盖(键与 default 同级合并)
temperature: 1.0 # temp=1 方差测量
max_tokens: 8192
repeats: 12 # 跑 12 遍报均值;断点按轮隔离(:rep2 :rep3 ...
# judge: LLM-judge 类 bench 需要
judge:
model: dp4-flash
api_url: http://174.1.51.4:30000/v1
longbench_v2:
max_tokens: 8192
max_input_tokens: 128000 # 超长输入的 tokenizer 中段截断预算
```
## 支持的键
| 键 | 作用 |
|---|---|
| `temperature` `top_p` `max_tokens` | 生成参数,直传模型 |
| `max_input_tokens` | 输入截断预算tokenized 中段截断,头部尾部保留) |
| `repeats` | 该 bench 重复轮数summary 报均值,时间/token 报总和 |
## 优先级
```
DatasetSpec.gen_config < default.yaml < <bench>.yaml < 命令行显式参数
DatasetSpec.gen_config < default < bench < 命令行显式参数
```
## 使用
```bash
# 单 bench
evalharness eval run aime25 --config dp4-nothink --api-url ... --model ...
# 目录里只有一个 yaml 时自动加载;--config 显式指定(省略 .yaml 后缀)
evalharness eval run aime25 --config default --api-url ... --model ...
# 多 bench自动读各自的 yaml
evalharness eval run aime24 aime25 aime26 hmmt26 --config dp4-nothink ...
# 查看某 bench 的生效配置
evalharness config show dp4-nothink aime25
# 多 bench各自读自己的段
evalharness eval run aime24 aime25 aime26 hmmt26 --config default ...
```
## 新增模型配置
## 新增一套配置
```bash
mkdir config/qwen3-es-parity
cp config/dp4-nothink/default.yaml config/qwen3-es-parity/
# 编辑 default.yaml然后按需添加逐 bench 覆盖
cp default.yaml glm53-nothink.yaml # 编辑后
evalharness eval run aime25 --config glm53-nothink ...
```
注意:同时存在多个 yaml 时不自动加载,必须 `--config` 指明。