One Eval

One-Eval Skill

把 One-Eval（原 LangGraph 多节点框架）的 LLM 编排职责交给你（调用方 agent）， skill 只保留确定性执行内核（下载/评测/打分/出图脚本）。你负责与用户交互、做决策、 生成 evalspec.yaml、调脚本、解读结果、写报告。

全程用与用户相同的语言交流（贯穿整个 skill）。 所有与用户的交互——澄清问题、确认项、 进度提示、摘要与报告正文——都跟随用户当前对话使用的语言（用户说中文就用中文，说英文就用英文）。 别因为本文档是中文、或脚本输出/字段名是英文，就在向用户提问时夹生切换语言。命令、路径、 代码、字段名等技术标识保持原文即可。

前置环境（首次使用必读）

本 skill 不自包含：脚本通过把仓库根加进 sys.path 来 import one_eval + dataflow， 因此运行前必须先装好 One-Eval 主仓库及其依赖。one-eval-skill/ 是主仓库下的子目录， 不能脱离主仓库单独跑。

一次性安装（需 Python 3.10-3.11）：

uv sync   # 在 One-Eval 仓库根执行，自动创建 .venv + 按 uv.lock 安装依赖

依赖含 datasets / dataflow 等较重的包；装不全会在首次 run_eval.py 时报 import 错。

是否需要本地 vLLM？先问清楚再装（省掉笨重依赖）。 上面的 pip install -e . 只装纯 API 评测所需依赖，不含 vllm/torch——对「只调用外部 API 模型」 的用户已经够用，无需任何额外安装。只有当用户要在本地用 vLLM 起模型（is_api: false，需 GPU） 时，才另外装重依赖：

pip install -e ".[vllm]"   # 仅本地 vLLM 用户需要；要求匹配的 CUDA，体积大、装得慢

所以接入前务必先问用户走哪条路（见 step 0），别默认把 vllm 装上去拖慢环境、占满磁盘。

装完先自检（确认依赖齐全，避免跑到一半才发现缺包）：

python scripts/doctor.py     # 必需项齐全则退出码 0；缺啥会列出并给修复命令

自动注册为 skill（仓库自带，无需手动操作）：本仓库根带一个相对软链 .claude/skills/one-eval -> ../../one-eval-skill，clone 下来即被 Claude Code 当作 项目级 skill 自动发现——重启 Claude Code 后 /skills 列表里会出现 one-eval。 doctor.py 末尾会回显这条注册状态。若软链缺失（极少数情况），按 doctor 提示在仓库根执行 mkdir -p .claude/skills && ln -s ../../one-eval-skill .claude/skills/one-eval 补建即可。 即使不注册，把 SKILL.md 当普通文档丢给 agent 读、照流程跑同样可用——注册只是让 /skills 能自动发现。

装好之后：用户直接用自然语言对话即可，不需要手敲脚本——你（agent）会按下方流程 替用户调脚本。例如用户说「用 gpt-4o-mini 评一下 mmlu-redux 和 polymath，API 地址 xxx、 key xxx」，你就从测连通一路跑到出报告。脚本路径、evalspec 都由你生成与调用。

运行脚本统一用主仓库的 Python 环境（上面装的那个），且 cwd 在 one-eval-skill/ 下时 用 python scripts/xxx.py。API key 由用户自备，只写进本地 evalspec.yaml（已 gitignore）， 不要回显到对话或入库。

0. 先确认运行环境（优先复用已有环境，能不装就不装）

第一步先探测，别一上来就让用户装环境或选环境管理器。 很多机器上已经有可直接用的环境 （如仓库里的 .venv/、已激活的 venv），这种情况直接用，不要问任何问题、不进安装流程：

1. 先扫现有环境：看仓库根有没有 .venv/（有就用 .venv/bin/python）、环境变量 VIRTUAL_ENV 是否已指向某环境。命中就直接跑 <该环境>/bin/python scripts/doctor.py：doctor 通过（必需项齐全）→ 环境就绪， 跳过下面全部安装步骤，直接开始评测。这是最常见、最快的路径，别画蛇添足。

2. 只有在没有可用环境时才安装：用 uv sync 一步到位（自动创建 .venv + 按 uv.lock 安装依赖）。若机器上没有 uv，退回 python -m venv .venv + pip install -e .。这是一次性操作，不要逐项反复确认。

3. 是否要 vLLM 重依赖：纯 API 评测（is_api: true，本机 Mac 走这条）→ 基础 pip install -e . 即可，别刻意预装 vllm/torch；只有要本地用 vLLM 起模型 （is_api: false，需 GPU）才去 GPU 机 pip install -e ".[vllm]"。 注：torch 等是 GB 级重包，首次从零装最耗时；纯 API 评测不需要为它们专门等待或反复确认。

拿到可用环境后，所有脚本一律用该环境 python 的绝对路径调用 （如 /path/to/.venv/bin/python scripts/xxx.py），别用裸 python，避免误用到别的环境。 doctor.py 会打印当前解释器路径、是否隔离、以及探测到的可复用环境，按它的提示走即可。

标准流程（按序执行，不要跳步）

1. 选模型 + 测连通性（强制门槛）

评测数据量大、耗时长，接入任何模型前必须先测连通。

被测模型必须由用户明确指定，禁止默认填充、禁止张冠李戴。 你（agent，自身是 Claude） 和「被测模型」是两回事——不要把自己的名字混进被测模型名（曾出现过把 gpt-4o-mini 说成 claude-sonnet-4-6o-mini 的错误）。主动问用户要测哪个模型、模型在哪：

• API 模型（is_api: true）：openai_compatible / deepseek
• 本地 vLLM（is_api: false）：需 GPU 环境（本机无 GPU 则交由用户在 GPU 机验证）

测连通：

python scripts/check_model.py --api --model <名> --api-url <url> --api-key <key>
# 或从已写好的 spec 读：python scripts/check_model.py --spec evalspec.yaml

连通失败不要往下走，先按 stderr 的可读原因排查（鉴权/端点/网络）。

写完 evalspec 后，把 model 段回显给用户确认（"本次被测模型是 X，API/vLLM，参数如下，对吗？"）， 得到确认再开跑。全程对话里始终明说被测模型是谁，摘要/报告里的模型名以 evalspec.yaml 的 model_name_or_path 为准——run_eval.py 启动首行也会打印 被测模型: <名>，以此为准核对。

连通后，确认采样参数（别用默认值闷头跑）：

model 段的采样参数（temperature、top_p、max_tokens、seed）仅对 dataflow bench 生效。若本次只跑 external_repo bench，无需填写此块——external_repo bench 的参数由 bench_gallery.json 中各自的默认值决定，如需覆盖在 benchmarks[].params 中显式填写。

若包含 dataflow bench，主动与用户确认这些参数。给出推荐并说明影响——评测默认 temperature=0+固定 seed 求可复现；max_tokens 对数学/CoT 题不要太小（截断会导致 抽不出答案、假阴性，宁可放大到 2048+）。若用户想测模型「发挥上限」或多样性，再调高 temperature 并说明分数会抖动。最终确认值写进 evalspec.yaml，会随结果落盘并在报告 「评测设置」里如实记录（见 step 8 / report_template）。

2. 选 benchmark

• 先看 references/bench_gallery.md：READY 区（已测通、可直接复用）优先； 否则从候选区（103 个未验证 bench）选，接入前需走 smoke 验证。
• 用户要评测 gallery 之外的新数据集 → 用 scripts/prepare_bench.py 下载并预览嵌套结构， 再按 references/eval_types.md 判断 eval_type、规划 key_mapping（嵌套字段须先拍平）。
• external_repo bench（LiveCodeBench、BFCL、EvalPlus 等）→ 从 bench_gallery.md 末尾 External Repo Benchmarks 区选择，确认前置条件； 参数契约见 bench_gallery.json 的 meta.repo_eval.params，只在 benchmarks[].params 中覆盖需要改的参数。不填 eval_type/key_mapping，ExternalRepoRunner 自动处理 clone→安装→运行→解析全流程。接入 gallery 中不存在的新 bench 时才读 references/external_bench.md。

3. 选 metric（默认已给主分，额外维度可选）

先告诉用户每个 bench 默认用什么主分、它衡量什么能力（dataflow 内核按 eval_type 自动选）。 external_repo bench 直接使用官方 harness 返回的主指标，默认不追加 One-Eval metric。

• 主分够用就够用；但要主动问用户是否补充维度，并解释每个维度查什么： 正确性（exact_match/numerical_match/set_f1，短答案、数值、开放答案集合）、相似度（bleu/rouge_l/chrf/token_f1/jaccard_similarity，翻译摘要长答案/关键词覆盖）、 格式遵循（extraction_rate/format_compliance_score/json_validity，低分会拖累正确性或结构化输出可用性）、 生成健康度（repetition_rate 抓复读、garbled_text_rate 抓乱码/异常编码）、弃答率与空输出率（missing_answer_rate/empty_or_whitespace_rate 做正确性归因）、 代码/SQL 合法性（code_validity / sql_parse_validity，注意只验能否解析、非逻辑正确）。
• python scripts/run_metrics.py --list 查看当前注册表里的全部 metric（按维度分组，含适用场景）。
• 用户想要注册表里没有的维度 → 参考 references/metric_registry.md + assets/custom_metric.template.py 跟用户聊清楚需求后写新 metric，落到 custom_metrics/。