openai/evals 深入研究：框架架构、工作流、与生态对比

摘要

openai/evals 是 OpenAI 在 2023 年开源的 LLM 评测框架（截至 2026/06 约 18.7k stars / 3k forks），它的本质是**”低代码 + 可注册”的 eval 流水线：用 JSONL 装样本、用 YAML 注册 eval、用 oaieval 命令跑分，通过 Completion Function Protocol 把”被评的模型/agent”和”评的逻辑”解耦。框架内置 5 种基础模板（Match / Includes / FuzzyMatch / JsonMatch / ModelBasedClassify），其中 ModelBasedClassify 用 LLM-as-a-judge 评开放式答案是最被复用的部分。registry/evals 下沉淀了几百个社区贡献的 eval，覆盖中英多语种、数学、推理、代码、领域知识（法律/医学/会计）。2025 年 OpenAI 进一步推出托管版 Evals API + Dashboard，让评测能直接在云端跑、接 CI/CD；与之同期，开源仓库的更新节奏放缓，子项目 simple-evals 已被弃用。结论**：选型上 openai/evals 强在”产品化的 LLM-as-a-judge 流水线 + 公开 registry”，但跨开源模型评测请用 EleutherAI lm-evaluation-harness，要做多维度（公平/鲁棒/效率）审计请用 Stanford HELM，要做生产侧 prompt/CI 评测请优先考虑托管版 Evals API、LangSmith Eval、Braintrust 或 Ragas（RAG 专用）。

研究问题

• 这个仓库到底交付什么？核心抽象是哪几层？
• 如何快速跑通一个内置 eval / 写一个自定义 eval？
• 它的”模型作为评委”（model-graded）到底怎么工作？
• 与 lm-evaluation-harness、HELM 等开源框架的差异在哪？
• 2025 年托管版 Evals API 出现后，这个开源仓库还值不值得用？

发现

1. 项目定位与活跃度

1. 定位：通用 LLM/LLM 系统评测框架，既提供”现成 eval registry”又支持”自定义 eval”，强调”做高质量 eval 是构建 LLM 应用最有杠杆的事”。来源
2. 活跃度（2026/06 抓取）：约 18.7k stars、3k forks、691 commits、125 open issues、83 PRs。整体活跃但增速放缓，重心已转向托管版 Evals API。来源
3. 2025 重要变化：① OpenAI Dashboard 内置 Evals 页面 ② 推出 Evals API（程序化、可接 CI/CD） ③ 子仓库 simple-evals 在 2025 被弃用，仅留 HealthBench 等 legacy 用途。来源

2. 仓库结构

evals/
├── evals/                  # 主包（Python）
│   ├── registry/
│   │   ├── evals/          # 数百个 YAML eval 定义
│   │   ├── completion_fns/ # CompletionFn 注册（含 LangChain 适配）
│   │   ├── modelgraded/    # 模型评委的 prompt 模板
│   │   └── data/           # 样本数据（Git-LFS）
│   ├── elsuite/            # eval 实现（model-graded、basic、自定义）
│   └── completion_fns/     # 内置补全函数实现
├── examples/               # 示例
├── docs/                   # build-eval / eval-templates / completion-fns 等
├── scripts/
└── tests/unit/evals/

数据集走 Git-LFS，clone 时若没装 LFS 会拿到 stub。来源

3. 五个核心抽象

1. Eval（评测任务） - YAML 描述 id、template、samples_jsonl 路径、metrics
2. Registry（注册表） - evals/registry/ 下的 YAML 文件，相当于”eval 商店”
3. Completion Function - 被评对象的统一接口（输入 prompt 字符串/对话，输出文本列表），任何模型/agent/RAG 链路实现该协议即可被同一套 eval 评测
4. Grader / Eval Template - 评分逻辑，5 个内置模板 + 自定义 Python class
5. Recorder - 记录每条样本的输入/输出/打分，支持本地、Snowflake 等持久化

来源

4. 五个内置 Eval 模板

模板	路径	核心逻辑	适用场景
Match	basic/match.py	any(a.startswith(b) for b in B)	选择题/简短答案
Includes	basic/includes.py	any(b in a for b in B)	子串包含
FuzzyMatch	basic/fuzzy_match.py	any(a in b or b in a for b in B)	双向包含的近似匹配
JsonMatch	basic/json_match.py	键值集合相同（顺序无关）	结构化输出验证
ModelBasedClassify	modelgraded/classify.py	用第二个 LLM 当评委	开放式回答、风格、事实性

ModelBasedClassify 支持三种 prompt 形态：

• cot_classify（推荐）- 先 chain-of-thought 再分类
• classify_cot - 反向，先分类再解释
• classify - 纯分类

来源

5. 写一个 eval 的三步法

1. 数据格式化为 JSONL，每行一个 JSON，必含 input（chat 消息或字符串）和按模板要求的 ideal 字段：

   {"input": [{"role":"user","content":"What is 2+2?"}], "ideal": "4"}

2. YAML 注册到 evals/registry/evals/<your_eval>.yaml：

   my_eval:
     id: my_eval.dev.v0
     description: "My custom eval"
     metrics: [accuracy]
   my_eval.dev.v0:
     class: evals.elsuite.basic.match:Match
     args:
       samples_jsonl: my_eval/samples.jsonl

3. 跑分：

   oaieval gpt-4 my_eval

提交 PR 前要装 pre-commit；OpenAI 接受 YAML/数据集类 PR，但不接受纯 Python 自定义代码 PR（出于审计/安全考虑）。来源

6. Completion Function Protocol（被低估的解耦层）

这是 evals 设计上最优雅的部分：所有”被评对象”实现同一个接口。

class CompletionFn(Protocol):
    def __call__(self, prompt: Union[str, List[ChatMessage]], **kwargs) -> CompletionResult: ...

注册到 evals/registry/completion_fns/<name>.yaml：

langchain/llm/flan-t5-xl:
  class: evals.completion_fns.langchain_llm:LangChainLLMCompletionFn
  args:
    llm: HuggingFaceHub
    llm_kwargs:
      repo_id: google/flan-t5-xl

跑：

oaieval langchain/llm/flan-t5-xl test-match

带来的好处：① 同一份 eval 可以跑 GPT-4、Claude、Llama、自家 RAG agent ② 可外置 registry（--registry_path）做企业内部私有 eval。来源

7. Registry 内容广度

evals/registry/evals/ 下有数百个 YAML，覆盖：

• 多语种语言任务：中文古诗、成语、翻译；阿拉伯语、保加利亚语、白俄罗斯语等的语法/常识
• 数学与推理：AIME、代数、抽象因果、类比、graph reasoning
• 领域知识：法律（巴西法）、安全（CISSP）、会计审计、棋类
• 结构化任务：JSON 提取、ASCII 识别、3D 物体操作、平面图理解
• NLP 经典：Banking77、CO-SQL、CoQA

可见 evals registry 是**”长尾、社区贡献为主”的杂烩**，质量不一致，与学术 benchmark 完整性（如 HELM、lm-eval-harness）不可同日而语，但适合”灵感 + 模板复用”。来源

8. 2025 托管版 Evals API

• 位置：OpenAI Dashboard → Evals 页面 + REST API（openai-python v1.79.0+ 内置 client.evals.*）
• 能力：定义 eval、上传数据集、调度 run、调度 LLM-as-judge、查报告、导 CSV
• CI/CD 集成：Python SDK 可在 PR 流水线里自动跑回归测试
• 与 GitHub repo 的关系：YAML/JSONL 概念基本对齐，但托管版做了产品化包装，不要求你把 PR 提到上游
• 取舍：生产侧用托管版省心、开源 repo 适合科研/社区贡献/离线敏感场景

来源

对比与判断

与同类框架的本质差异

框架	出身	核心抽象	强项	弱项
openai/evals	OpenAI 官方	YAML 注册 + CompletionFn + 5 模板（含 LLM-as-judge）	低代码、可商品化、registry 大、模型评委成熟	偏 OpenAI 生态、registry 质量参差、自定义 Python 不接受 PR
lm-evaluation-harness	EleutherAI	Task 类 + 自动化 zero/few-shot	学术 benchmark 完整度第一（MMLU、HellaSwag、TruthfulQA、ARC、GSM8K…）、跨模型一致性	偏静态客观题，不擅长 LLM-as-judge 与开放式
HELM	Stanford CRFM	多维 scenario × metric 矩阵	多维度评测：accuracy + 公平/偏见/鲁棒/效率/毒性	重，跑全套贵；更适合 audit
LangSmith Eval	LangChain	Run/Dataset/Evaluator API	RAG / agent trace 闭环、生产监控	偏 LangChain 生态、商业云
Braintrust	商业	Experiment + Trace + Eval	工程化好、UI 漂亮	商业、私有化成本
Ragas	开源	RAG 专用指标（faithfulness、context recall）	RAG 评测最专业	仅限 RAG

选型决策树

• 你在做什么？
  • 比较开源模型在标准学术基准的表现 → lm-evaluation-harness
  • 给模型/系统做”全身体检”（含偏见、毒性、效率） → HELM
  • 评 RAG / agent，要看 trace/链路 → LangSmith 或 Ragas
  • 评 prompt 改动是否回归、要 CI 跑 → 2025 OpenAI Evals API 或 Braintrust
  • 想自己写一个 LLM-as-judge 的 eval、又要开源/可控 → openai/evals 或自建
  • 公开发布让别人复用你的 eval → 提 PR 到 openai/evals registry

它最值得偷的设计

1. CompletionFn 协议 - 这是少见的、把”被评对象”做成 plug-and-play 的优雅抽象。自家评测平台可以借鉴：定义一个 Runner 接口，让 model / RAG / agent / function-calling chain 都能被同一套 eval 评。
2. YAML + JSONL 的低代码组合 - 写 90% 的 eval 不需要碰 Python，PM/researcher 也能贡献样本。
3. cot_classify 评委模板 - 让评委先 CoT 再决定，分类质量比 zero-shot 直接打分稳得多。
4. Registry 的”任意路径”机制 - --registry_path 让企业可以保留私有 eval 不上传到上游，但仍享受框架。

业务仓库里的”优雅”用法

• 轻量集成（推荐起步）：装 pip install evals，把核心评测套件（5-10 个 eval）落到本仓库 evals/private-registry/，跑 oaieval --registry_path evals/private-registry/ <model> <eval>，不污染上游。
• CI 接入：把 eval 跑成 GitHub Action，每个 PR 跑核心子集（10-30 个样本，分钟级），主分支夜里跑全量。
• LLM-as-judge 用 ModelBasedClassify：评开放式答案时复用框架，不必自己写。但 judge 模型要锁版本（如 gpt-4-0125-preview），否则评分会飘。
• 如果在 OpenAI 生态：直接上 2025 Evals API，省掉自建 recorder/dashboard 的工作。
• 如果在多模型生态（含 Claude、开源模型）：保留开源 evals + CompletionFn 适配多家 SDK；考虑同时挂 lm-eval-harness 跑学术基准做 sanity check。

与本仓库（agent-skills / vibe / researcher）的关系

• evals 是”评测层”，与本仓库的”工程纪律层”（addyosmani/agent-skills、vibe）正交：
  • 工程纪律层告诉 agent “怎么写代码 / 怎么走流程”
  • evals 层告诉团队 “agent 写出的东西到底好不好”
• 把 evals 当成 agent-skills 中 /test /review 阶段的”可量化兜底”，比”靠 reviewer 主观看输出”靠谱得多。

不确定性

• registry 内具体 eval 的质量分布：上千文件没逐一审计，社区贡献质量不均，重要决策前要单独读源 YAML。
• 托管版 Evals API 的定价/速率限制：2025 信息有限，企业级使用前需查最新计价。
• 与 simple-evals 的关系：openai/simple-evals 已部分弃用但仍在维护 HealthBench；与主仓 evals 的边界需要看 OpenAI 官方公告。
• LLM-as-judge 的 judge bias：用 GPT-4 评 GPT-4 的输出有自我偏好风险，跨模型评测时要做 cross-judge 验证，框架本身不强制。
• Git-LFS 大文件下载体验：clone 速度慢，离线/受限网络环境下需要镜像。

后续行动

• 在沙箱仓库装 pip install evals，跑一遍 oaieval gpt-4 test-match 走通最小闭环。
• 复制 cot_classify 的 prompt 模板进自家 SKILL，验证 LLM-as-judge 的稳定性。
• 设计本仓库自己的 eval registry：选 5 个最关心的能力（如 spec 撰写、代码 review 一致性、研究简报引用准确性），每个写 20-30 条样本。
• 跟踪 OpenAI Evals API 的定价/特性更新；评估”开源框架 + 托管 API”双轨方案。
• 调研 lm-evaluation-harness 是否值得作为 second opinion 框架并行接入。

来源

• openai/evals 仓库主页
• docs/eval-templates.md（5 个内置模板）
• docs/build-eval.md（写 eval 三步法）
• docs/completion-fns.md（CompletionFn 协议）
• evals/registry/evals 目录
• openai/simple-evals（2025 弃用通告）
• OpenAI Evals API 发布报道
• EleutherAI lm-evaluation-harness
• Stanford HELM
• Helicone 2025 Prompt Eval 框架综述
• OpenAI Cookbook - MCP eval notebook