企业官网建设流程全解析

• 教程
• 文档
• AI Agent
• 人工智能
• 大模型

本练习来自仓库 examples/stage-7/02-eval 目录，对应 Stage 7 — Agent 上線工程：可測、可看、可停、可恢復 的核心练习 1。读完本文，你将掌握 Eval case 的完整结构、dev/holdout 分组、baseline 对比、固定规则评分器与 LLM-as-judge 的严格判卷约定，并能直接在本仓库中离线跑通全部测试，再接入本机 Ollama 或 Anthropic 跑真实模型评测。

一、Eval 是什么：一张每次重考的固定考卷

**Eval（Evaluation，评测）**像一张固定考卷：每次改 Prompt、换模型或改程序之后，都用同一批题目再考一次。它不是为了证明"模型很聪明"，而是为了回答一个工程问题——这次改动到底是进步、持平，还是退步。

在 Stage 7 的上线工程框架里，Eval 位于"可测"这一环：先说清楚怎样算成功，再决定怎么评。文档给出的学习目标有四条，正好对应本练习的全部知识点：

• 说清楚Eval case：一题输入、预期结果和评分方法；
• 把 **5 题 development split（开发组）**和 **3 题 holdout set（保留考卷）**分开；
• 保存Baseline（基准），判断下一版是进步、相同，还是Regression（退步）；
• 先用固定规则评分；需要LLM-as-judge时，只接受完整的PASS／FAIL。

二、五个重要词：先建立评测的公共语言

文档定义的五个核心术语，是理解整套练习的钥匙：

评测的评分器分成两类，文档用一张表说明"题目形状 → 先用什么 → 为什么"：

**Deterministic evaluator（固定规则评分器）**对同一输出会给出同一分数，例如 substring、exact match 或正则表达式；LLM-as-judge能评开放式答案，但可能有偏差或格式错误，所以仍要人工抽查。

三、先跑不花模型费的离线测试

在examples/stage-7/02-eval目录下打开 PowerShell，直接复制运行：

py -3.11 -m venv .venv .\.venv\Scripts\python.exe -m pip install -r requirements.txt .\.venv\Scripts\python.exe test.py .\.venv\Scripts\python.exe test_anthropic.py

看到两处🎉，就代表以下能力全部通过：8 题版本化资料、5／3 分组、多次 trials、baseline 比较、空回复与 Judge parser。这一步只用假回复，不联网也不需要 API key。

从源码看，requirements.txt只声明了openai>=3.5,<4与anthropic>=1.2,<2两个可选依赖，且两份测试文件都在顶部用MagicMock模拟模型回复——test.py的test_ollama_judge_adapter_returns_provider_text把llm.chat.completions.create的返回值 mock 成PASS，test_anthropic.py则 mock 了client.messages.create返回"Tokyo"文本块。这就是"零成本验证行为"的落地方式。

离线测试覆盖的行为包括（见 test.py）：

• 数据集必须存在非空的dataset_version，且恰好 8 题、dev 5 题、holdout 3 题、id 全部唯一；
• substring／exact／regex 三类固定规则评分器对空输出（""或None）一律判失败；
• Judge 缺失时调用llm_judge类型的 grader 会直接抛错（fail closed）；
• baseline 与本次运行的数据版本、split、case ids 不一致时，在调用 Agent 之前就报错；
• --trials超过 20 会在调用 Agent 之前被拒绝；
• 报告能保存 provider、model、trials、分类结果、失败题与 improved／same／regressed 统计。

四、Path A：用本机 Ollama 跑同一份考卷

Ollama 不收模型 API 费，但电力、硬件、下载与等待时间仍有成本。先启动本地模型服务：

ollama pull qwen3.5:4b ollama serve

另开一个 PowerShell 窗口，在examples/stage-7/02-eval目录运行：

.\.venv\Scripts\python.exe starter.py

第一次会跑 5 题开发组、每题 1 次，而且不写文件。要保存可比较的基准，直接复制：

.\.venv\Scripts\python.exe starter.py --split dev --trials 3 --save-report reports/dev-baseline.json

改完 Prompt 或程序后，再跑并对比基准：

.\.venv\Scripts\python.exe starter.py --split dev --trials 3 --baseline reports/dev-baseline.json --save-report reports/dev-current.json

准备发布时才跑保留考卷：

.\.venv\Scripts\python.exe starter.py --split holdout --trials 3 --save-report reports/holdout.json

几个工程约束必须遵守：

• 报告保存 case ID 与模型输出，题目则留在版本化数据集里；不要放秘密、个资或客户资料，也不要把敏感报告提交到 Git；
• --trials限制为1–20，避免手滑造成无上限的模型呼叫；
• 这 8 题只是教学样本，不能代表模型在你工作上的品质。

从 starter.py 源码看，Ollama 路径默认使用MODEL=qwen3.5:4b与OLLAMA_API_BASE=http://localhost:11434/v1，通过 OpenAI 兼容客户端连接；脚本开头还断言了MODEL非空、OLLAMA_API_BASE必须是 HTTP(S)，任何环境变量配置错误都会在启动时直接失败。

五、Path B：用 Anthropic 跑同一份考卷

$env:ANTHROPIC_API_KEY = "貼上你的金鑰" $env:MODEL = "claude-haiku-4-5-20251001" .\.venv\Scripts\python.exe starter_anthropic.py

Anthropic 路径也支持上面的--split、--trials、--save-report与--baseline。文档给出的 Haiku 4.5 单价是 input$1 / 1Mtokens、output$5 / 1Mtokens：

估算費用 = (input_tokens × $1 / 1M) + (output_tokens × $5 / 1M)

实际费用取决于每题消耗的 token。建议先在供应商 Console 设置$1spend limit，再用实际 usage 计算；不要把范例估算当账单。从 starter_anthropic.py 看，Agent 调用设置了max_tokens=200，Judge 调用只设max_tokens=10（因为只允许它回PASS或FAIL）。

六、底层原理：eval_core.py 的评测执行架构

两份 starter 只是"适配器"，真正的评测逻辑集中在共享的 eval_core.py（约 425 行）。核心流程是：载入并校验数据集 → 按 split 选题 → 对每题调用 agent_fn → 按 grader 评分 → 聚合 trials 生成报告 → 可选地对比 baseline。

值得展开的源码细节：

1. fail-closed 的空回复检查：require_text()会把回复strip()后判空，空文本直接抛ValueError；grade_output()中(output or "").strip()为空时一律返回False——空答案不可能通过。

2. 严格 Judge 解析：parse_verdict()用re.fullmatch(r"(PASS|FAIL)", ...)只接受整段回复恰好等于PASS或FAIL（不区分大小写）。若 Judge 回 "PASS because..."，程序会停止而不是猜。test.py的test_judge_is_optional_and_strict专门验证了"PASS because it looks right"、"NOT PASS"、空串与"PASS\nFAIL"都会被拒绝。

3. 数据集校验前置：validate_dataset()在任何模型调用之前检查每个 case 必须含id / split / category / input / success_criteria / grader / source七个字段，id必须唯一且非空白，split只能是dev或holdout，且数据集必须同时包含两类 split；regex 类型 grader 的正则表达式会被预编译校验，非法正则直接报错。

4. baseline 对比先校验后执行：compare_to_baseline()要求 baseline 的dataset_version、split、case_ids与本次运行完全一致，case_pass_rates必须是 0–1 的有限数值；不匹配就 fail closed，绝不猜测。test_run_rejects_bad_baseline_before_agent_calls用 spy agent 验证了错误 baseline 会在 Agent 被调用之前抛错且调用次数为 0。

5. 逐题 pass rate 与分类统计：run_eval()对每题按passed_count / trials计算case_pass_rates，用_category_summary()按 category（accuracy／honesty／format／safety）汇总pass_rate，并把所有失败项按{"trial", "id", "category", ...}收进failures列表——失败能精确指回具体 case，而不是只给一个总分。

6. 原子化报告保存：save_report()先在目标目录写临时文件、fsync后os.replace，保证报告不会因中断而写坏；run_cli()还拒绝--baseline与--save-report指向同一文件（防止覆盖自己的基准）。

七、动手改一题：把真实失败写进 eval_cases.json

打开 eval_cases.json，把一题开发组换成你工作里的真实失败案例。一个 case 的完整结构是：

{ "id": "dev_capital_japan", "split": "dev", "category": "accuracy", "input": "What is the capital of Japan?", "success_criteria": ["The answer names Tokyo."], "grader": {"type": "substring", "value": "Tokyo"}, "source": "Synthetic teaching case; replace with an observed failure before production." }

字段含义与规则：

• id：稳定且唯一的字符串（校验要求去空格、非空、不重复）；
• split：dev或holdout二选一；
• category：自由字符串，用于分类汇总（本数据集使用accuracy／honesty／format／safety）；
• input：喂给 Agent 的问题；
• success_criteria：非空字符串数组，人类可读的成功条件；
• grader：{"type": "...", "value": "..."}，type支持substring、exact、regex、llm_judge四种；
• source：不含机密的来源说明。

替换时保留唯一id、成功条件、grader 与不含机密的来源说明；只要 case 内容改了，就更新dataset_version（当前为"2026-09-13.1"）。再跑：

.\.venv\Scripts\python.exe test.py

文档特别强调：不要先抄到空白文字档再测试，直接改可执行的数据，确认报告能指出失败的id。你可以把某个grader.value故意改成错误值，观察报告在failures中列出对应 case id——这是验证"失败可定位"的最快方式。

八、Judge 判卷约定：只接受完整的 PASS／FAIL

当某题确实需要开放答案评判时，把 grader 改为{"type": "llm_judge", "value": "..."}。但本练习的硬性约定是：Judge 只接受整份回复等于PASS或FAIL。若它回 "PASS because..."，程序会要求重试或停止（parse_verdict用re.fullmatch强制整串匹配）。

从源码看，两份 starter 的 Judge prompt 结构一致：

Evaluate the answer using only the supplied criterion. Reply with exactly PASS or FAIL. Question: {input} Success criteria: {success_criteria 用分号连接} Judge rubric: {grader.value} Answer: {output}

两个值得注意的设计：其一，Judge 与 Agent 用同一模型会产生自我偏好风险，因此文档要求"至少加入固定规则或人工抽查"；其二，Judge 输出也会先经过require_text——空回复同样 fail closed。

九、成功检查清单

文档给出了七个验收标准，全部满足才算完成本练习：

• 每一题都有稳定且唯一的id；
• 改过题目、成功条件或 grader 后，dataset_version也更新了；
• 你知道开发组可以反复跑，holdout 不可边改边偷看；
• baseline 与目前报告的数据版本、split 和 case IDs 完全相同；
• 你能说明这题为什么先用固定规则，而不是 LLM Judge；
• 空答案不会被算成通过；
• 报告保留 provider、model、trials、分类结果、失败题与 improved／same／regressed。

十、从 8 题教学数据走向真正的 Eval suite

教学流程是四步闭环：

1. Agent 回答问题；
2. Evaluator 只看该题规则并打分；
3. Runner 保存每题结果与整体 pass rate；
4. 失败时回到具体 case，不只看一个总分。

正式项目还要加入真实使用者案例、边界条件、安全案例与人工标注；门槛应由你的 baseline 与风险决定，不要照抄别人的固定百分比。文档点名的常见问题与对策：

• cases 都太简单：加入过去真的答错过的问题；
• expected 写整句：只保留必要条件，避免同义句被误杀（这正是success_criteria与grader.value分开存放的原因）；
• 同一模型回答又评分：至少加入固定规则或人工抽查，降低自我偏好；
• 只保存总分：同时保存失败id、模型 ID、Prompt 版本与日期。

十一、配套学习资源

文档推荐了六份工具/资料（完整清单见 Stage 7 精选 Projects）：promptfoo（把 cases、providers 和 assertions 放进版本控制）、Anthropic Console Evals（官方界面建立与比较测试集）、datawhalechina/hello-agents（章节式中文 Agent 教材）、LangSmith（适合已用 LangChain/LangGraph 的团队）、Weights & Biases Weave（把 traces、资料与评测放在同一工作流）、Braintrust（多版本实验与结果追踪）。

仓库内的延伸阅读还包括：Stage 7 正文的 Eval 章节（Eval case 的七个组成部分、Eval Suite 版本化、Outcome Eval vs Trajectory Eval），以及同目录的 03-observability（核心练习 2）——Eval 负责"结果对不对"，Observability 负责"坏在哪一步"，两者互补。

模型、价格、套件与链接查核日期：2026-09-13 UTC（依据 README.md 标注）。

• 教程
• 文档
• AI Agent
• 人工智能
• 大模型