StaffML Vault 大规模构建 Runbook 实战:基于覆盖率分析与 Gemini 迭代生成的题库批量扩充管线
StaffML Vault 大规模构建 Runbook 实战:基于覆盖率分析与 Gemini 迭代生成的题库批量扩充管线
导读
本指南完整讲解 cs249r / StaffML 项目中 vault 题库大规模构建(Massive-Build) 的可重复流水线:如何通过「预检清理 → 覆盖率分析 → Gemini 迭代批量生成 → 质量门 → 提升与重建 → 论文刷新 → GUI 验证 → 原子提交」八个环节,在一天内为 ML Systems 面试题库新增数百道高质量题目。读完本文,你将掌握每条命令的语义与参数权衡、三种饱和自动停机的处理策略,以及如何基于仓库中的 vault-cli 命令与质量规范复跑整个构建会话。
1. 为什么需要一份"大规模构建"Runbook
StaffML vault(interviews/vault)维护着一个以 YAML 为载体的 ML Systems 面试题库,题目按 topic × zone × track × level × phase 多维度打标,并配套 vault build / vault check 等 CLI 工具(见 build.py、check.py)与严格的质量规范(见 QUESTION_QUALITY_RUBRIC.md)。当语料规模需要跨越式增长时,零散的手工写作无法满足吞吐要求,于是有了本文所述的、以 2026-04-25 大规模构建为动机的可重复流水线。
Runbook 对流程持有三条明确立场,理解它们才能理解后续每个 Phase 的设计:
- 预检不可跳过(Pre-flight is non-negotiable):在生成新内容前清理既有语料中的畸形取值,防止"坏数据进、更坏数据出"的放大效应;
- 最大化每一次 Gemini 调用:每日 250 次调用上限是硬约束,因此纯文本单元用 30–40 个/批、含图单元用 15–20 个/批的批量尺寸,更小的批次只会浪费上下文;
- 迭代而非批量一把梭(Iterate, don't bulk-generate):用充裕的预算运行迭代式覆盖率循环,让"饱和"自动停止工作,避免过度填充分析器已不再标记的单元。
这套流水线面向"任意一次语料扩容会话",而非仅限当初的那次构建。
2. Phase 0 — 预检清理(一次性,约 10 分钟)
任何新生成开始前先执行。目标:把语料恢复到干净基线,确保新内容基于合法数据创作。
2.1 具体任务
-
普查畸形
competency_area取值:找出不属于 13 个规范领域(deployment、parallelism、networking、latency、memory、compute、data、power、precision、reliability、optimization、architecture、cross-cutting)的值; -
编写重映射表:将每个畸形值映射到最接近的规范领域,Runbook 给出的实测样例映射如下:
发现的畸形值 规范领域 data-pipeline-engineeringdataduty-cyclingpowerkv-cache-managementarchitecturememory-hierarchy-designmemoryinterconnect-topologynetworkingnetwork-bandwidth-bottlenecksnetworkingpipeline-parallelismparallelismqueueing-theorylatencyfault-tolerance-checkpointingreliabilityquantization-fundamentalsprecisioncommunication-computation-overlapoptimizationcompute-cost-estimationcomputediagnosis/evaluation(区域名混入!)cross-cutting<track> / <topic>斜杠形式按上方主题映射逐条对应 -
就地修复(in-place):一次提交、原子化落地;
-
为 LinkML schema 增加枚举约束:让
competency_area在校验阶段直接拒绝 13 个规范值之外的任何输入,并从更新后的 LinkML schema 重新生成 Pydantic 模型(vault-cli中的 codegen.py 负责模型代码生成); -
重建 bundle:执行
vault build --local-json,并验证 GUI 的面积筛选器恰好显示 13 个条目加 "All"。
2.2 验收标准
vault check --strict通过;- GUI 面积筛选器为 14 个条目(
All+ 13 个规范领域),不再出现主题形状的字符串; - 预提交钩子
vault-schema-drift通过。
从源码看,
vault check --strict由 check.py 实现:--strict会同时执行 fast 层与 structural 层的校验(对应fast_tier与structural_tier),退出码 0 表示通过、1 表示任一失败;而vault build --local-json在 build.py 中的语义是:把本地开发产物物化到interviews/staffml/src/data/corpus.json并镜像到interviews/staffml/public/data/corpus.json(Next.js loader 在NEXT_PUBLIC_VAULT_FALLBACK=static时读取的正是该路径,生产环境从不读取这两个文件)。
3. Phase 1 — 确立当日目标(5 分钟)
运行覆盖率分析器,暴露当日缺口优先级:
python3 interviews/vault/scripts/analyze_coverage_gaps.py \
--total 100 --published-only
输出的 report.md 按优先级排列每个薄弱单元,取前 40–60 个单元作为 Phase 2 的批量目标。随后将推荐项归类为三类目标族:
| 目标族 | 单元来源 | 关注原因 |
|---|---|---|
| A. Track × area 空白区 | track_area_gaps 且优先级 > 1.0 |
语料存在整块象限空白(如 TinyML × parallelism) |
| B. Global track 的 L4–L6+ | track_zone_level_gaps 且 track == global |
Global track 仅达到期望密度的约 13%,跨 track 概念题稀缺 |
| C. 视觉原型缺口 | visual_topic_counts < 3 |
视觉筛选池是面向用户的"亮点",需要密度支撑 |
4. Phase 2 — 迭代生成(当天主体,约 80 次调用)
这是流水线的核心单命令。运行后即可离开(或盯日志):
python3 interviews/vault/scripts/iterate_coverage_loop.py \
--max-iters 30 \
--max-calls 80 \
--gen-batch-size 30 \
--gen-calls-per-iter 4 \
--judge-chunk-size 25 \
--visual-each-iter \
--gap-threshold 0.8 \
--max-drop-rate 0.35
4.1 每个迭代内部做什么
- 重新运行分析器(随着新单元被填充,缺口优先级实时更新);
- 选取
30 × 4 = 120个最高优先级单元; - 发起 4 次 Gemini 调用、每次喂 30 个单元(每次调用一次性返回 30 道题的 JSON 数组——这就是"有效利用上下文"规则的落地);
- 渲染 DOT / matplotlib 视觉图;
- 以 25 个为一组运行 LLM-as-judge 校验新草稿;
- 丢弃
verdict: DROP项,将PASS与NEEDS_FIX保留为草稿; - 将每次迭代记录到
_validation_results/coverage_loop/<ts>/; - 在以下任一饱和条件下停机:丢弃率 > 35%、缺口优先级 < 0.8、或连续两次迭代命中同一最高优先级单元。
4.2 参数为什么是这些数字
--gen-batch-size 30:Gemini 的上下文轻松容纳 30 个单元 × 约 600 token 题目 + 约 1500 token 常量参考,单次调用约 75K 输入 token,远低于 1M 上下文上限;--gen-calls-per-iter 4:每次迭代在评审前最多产生 120 道题,4 次生成 + 1 次评审 = 每迭代 5 次调用;--max-iters 30 / --max-calls 80:给循环留出持续推进空间(只要语料持续产生健康丢弃率),同时用预算上限防止失控;--gap-threshold 0.8:当最差剩余缺口的优先级低于 0.8(约为期望值的 20%,对任意单元都算"足够好")时停机;--max-drop-rate 0.35:35% 的丢弃率意味着 Gemini 开始出现幻觉,在浪费预算在垃圾内容上之前停机。
4.3 预期产出(基于既往循环运行)
- 约 600–1,200 道生成草稿;
- 经 judge 的通过率约 65–75%,即可提升约 400–900 道;
- 饱和自动停机前通常经历 8–15 次迭代。
说明:Runbook 所引用的
analyze_coverage_gaps.py、iterate_coverage_loop.py位于interviews/vault/scripts/,属于生成管线脚本;当前仓库快照中可直接查阅的同族工具包括 generate_question_for_gap.py(针对缺口单题生成)、audit_corpus_batched.py(批量语料审计)与 promote_drafts.py(草稿提升)。生成质量的对齐基准可参见 QUESTION_QUALITY_RUBRIC.md:A 级题要求场景、提问、解法、常见错误与 napkin math 全部指向同一项系统能力,且按recall / fluency / analyze / diagnosis / design / specification / evaluation / realization / optimization / mastery十个 zone 分别定义评分证据。
5. Phase 3 — 质量门(15 分钟)
提升前先人工目检生成内容:
- 视觉渲染检查:用 Playwright 抽查 5 个随机视觉草稿,确认 SVG 在列宽内内联渲染且不溢出、alt 文本存在、布局干净;
- MCQ / 非 MCQ 比例检查:若语料 MCQ 占比从当前的 17% 跌破 12%(新草稿通常是非 MCQ),说明正在向开放式倾斜,需决定在后续环节补充 MCQ 还是接受该漂移;
- 每题每 track 抽查 3 个随机草稿:快速核实场景真实性、数学正确性、硬件引用合理性。
MCQ 干扰项的质量底线同样由质量规范约束:干扰项应编码真实错误(KV 缓存因子遗漏、位 vs 字节、峰值 vs 有效带宽、计算受限 vs 内存受限混淆等),禁止明显荒唐或语法与题干不兼容的选项。
6. Phase 4 — 提升 + 重建 bundle(5 分钟)
python3 interviews/vault/scripts/promote_validated.py
PYTHONPATH=interviews/vault-cli/src \
python3 -m vault_cli.main build --local-json
PYTHONPATH=interviews/vault-cli/src \
python3 -m vault_cli.main check --strict
验收:vault check --strict 通过、manifest 与语料一致、无孤儿链(orphan chains)。
从源码看,这一步有两个可验证的底层行为:
build --local-json实际调用 compiler.py 的build函数把vault/questions/下的 YAML 编译进 SQLite,并把通过 Pydantic 校验与策略的题目写入产物;load/validation 错误会被报告但不会中断构建(build.py);check --strict的 CI 语义默认即为 fast + structural 两层,任何一层失败都令退出码为 1(check.py)。
草稿提升的"status: draft → 发布"门槛在质量规范中有明确五条:schema/gate 校验通过、数学(如适用)被核验、topic/zone/level 适配已评审、满足对应 zone 的评分标准、视觉素材能在 StaffML UI 渲染。
7. Phase 5 — 论文刷新(10 分钟)
cd interviews/paper
python3 scripts/analyze_corpus.py
python3 scripts/generate_figures.py
PYTHONPATH=../vault-cli/src python3 scripts/generate_macros.py
pdflatex -interaction=nonstopmode paper.tex
验收:论文构建干净、页数稳定、§sec:coverage 中按 zone 统计的散文更新为新的 top-3 zone。
注意:paper.tex 中硬编码的 zone 计数在顺序或数值发生实质变化时需要手工编辑(脚本只重写宏、不重写散文)。上述四个脚本均在 interviews/paper/scripts 下,generate_macros.py 依赖 PYTHONPATH=../vault-cli/src 导入 vault-cli 的宏生成逻辑。
8. Phase 6 — 验证 GUI(5 分钟)
cd interviews/staffml
npx playwright test tests/practice-smoke.spec.ts --reporter=list
全部 8 条测试必须通过:
1–3:既有布局 + 保护性检查;
4:L5 视觉筛选返回非空池且含内联 SVG;
5:仅链式(chained-only)筛选后池变小但仍非空;
6:?q=<known> 深链正确命中对应题目;
7:?q=<unknown> 展示 not-found 横幅;
8:?q=<legacy-cohort-id> 通过重定向映射解析。
随后在 /practice 页面做一次人工目检:打开面积筛选器,确认恰好 13 个规范条目(见 practice-smoke.spec.ts)。
9. Phase 7 — 原子提交与交接(5 分钟)
git add -A interviews/
git commit -m "feat(vault): massive build — N drafts generated, M promoted"
提交信息须写明各阶段计数(Phase 1 的 N、Phase 2 的 N 等)以及触发循环停机的饱和原因,这将成为当天的审计轨迹。
10. 重跑整套 Runbook
整套流程天然可重复,下周再跑一次大规模构建只需:
- Phase 0 预检清理(schema 枚举约束就位后通常是 no-op);
- Phase 1 分析器;
- Phase 2 循环(同样参数);
- Phase 3–7 照旧。
每次会话约新增 600–1,200 道题;随着语料成熟,饱和会越来越早触发。
11. 饱和处理 Playbook
循环自动停机有三种触发原因,处理方式各不相同:
若因丢弃率 > 35% 停机:
- 检查最近一次
_validation_results/coverage_loop/.../iter_NN/judge_summary.json; - 常见原因:(a) 分析器推荐的单元其主题不适用于该 track(如 TinyML × pipeline-parallelism 本身无意义);(b) 生成提示词中的硬件参考缺少非常规单元的常量;
- 修复:前者更新
analyze_coverage_gaps.py中的TRACK_TOPIC_BLOCKLIST,后者扩展生成器中的硬件参考块。
若因缺口优先级 < 0.8 停机:
- 这是成功信号:语料已足够均衡,分析器找不到关键缺口;
- 次日重跑分析器——新语料状态(尤其提升之后)可能浮现不同的优先级。
若因同一最高单元连续两次被推荐而停机:
- 说明分析器持续推荐一个生成器填不上的单元(通常是源素材渲染失败的视觉单元);
- 检查该迭代中对应单元的 SVG 渲染输出,核对 matplotlib 脚本语法。
12. 开放问题与演进方向
- MCQ 补强:当前草稿清一色开放式;已发布语料的 MCQ 占比为 17%,若不干预会随时间下降,值得为生成器构建独立的"MCQ-only"模式;
- 视觉原型扩展:
audit_visual_questions.py中的 10 个原型是高置信度教学视觉,扩展到 15–18 个原型(如 attention 计算图、MoE 洗牌等)是独立的创作任务——一旦目录列出原型,生成器即可产出; - 跨模型评审:当前生成与评审都用
gemini-3.1-pro-preview,引入 Claude 侧评审(经 Anthropic API)可获得真正的跨模型一致性,值得在生产级发布前落实。
13. 关键文件索引
| 用途 | 路径 |
|---|---|
| 本文档(Runbook 原文) | interviews/vault/docs/MASSIVE_BUILD_RUNBOOK.md |
| 题目质量规范(zone 评分 / MCQ 干扰项 / 视觉题标准) | interviews/vault/docs/QUESTION_QUALITY_RUBRIC.md |
| 题库 ID 方案 | interviews/vault/docs/ID_SCHEMES.md |
vault build --local-json 实现 |
interviews/vault-cli/src/vault_cli/commands/build.py |
vault check --strict 实现 |
interviews/vault-cli/src/vault_cli/commands/check.py |
| 草稿提升脚本 | interviews/vault-cli/scripts/promote_drafts.py |
| 缺口单题生成脚本 | interviews/vault-cli/scripts/generate_question_for_gap.py |
| 论文语料分析 / 插图 / 宏生成 | analyze_corpus.py、generate_figures.py、generate_macros.py |
| GUI 冒烟测试(8 条用例) | interviews/staffml/tests/practice-smoke.spec.ts |
适用前提:Runbook 面向 StaffML vault 语料扩容会话,命令基于 Python 3 与 bash;
vault build/vault check需通过PYTHONPATH=interviews/vault-cli/src指向 vault-cli 包;Gemini 调用与每日 250 次上限以实际 API 配额为准。文中涉及的覆盖率分析脚本、生成循环脚本位于interviews/vault/scripts/,其存在与语义以 Runbook 描述为准;仓库快照中可直接核验的是 vault-cli 侧的生成、审计、提升与校验工具。