StaffML Vault 大规模构建 Runbook 实战:基于覆盖率分析与 Gemini 迭代生成的题库批量扩充管线

原创2026-09-11 10:15:511,847 阅读
文章标签:教育文档教程人工智能深度学习机器学习模型量化

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 的设计:

  1. 预检不可跳过(Pre-flight is non-negotiable):在生成新内容前清理既有语料中的畸形取值,防止"坏数据进、更坏数据出"的放大效应;
  2. 最大化每一次 Gemini 调用:每日 250 次调用上限是硬约束,因此纯文本单元用 30–40 个/批、含图单元用 15–20 个/批的批量尺寸,更小的批次只会浪费上下文;
  3. 迭代而非批量一把梭(Iterate, don't bulk-generate):用充裕的预算运行迭代式覆盖率循环,让"饱和"自动停止工作,避免过度填充分析器已不再标记的单元。

这套流水线面向"任意一次语料扩容会话",而非仅限当初的那次构建。


2. Phase 0 — 预检清理(一次性,约 10 分钟)

任何新生成开始前先执行。目标:把语料恢复到干净基线,确保新内容基于合法数据创作。

2.1 具体任务

  1. 普查畸形 competency_area 取值:找出不属于 13 个规范领域(deployment、parallelism、networking、latency、memory、compute、data、power、precision、reliability、optimization、architecture、cross-cutting)的值;

  2. 编写重映射表:将每个畸形值映射到最接近的规范领域,Runbook 给出的实测样例映射如下:

    发现的畸形值 规范领域
    data-pipeline-engineering data
    duty-cycling power
    kv-cache-management architecture
    memory-hierarchy-design memory
    interconnect-topology networking
    network-bandwidth-bottlenecks networking
    pipeline-parallelism parallelism
    queueing-theory latency
    fault-tolerance-checkpointing reliability
    quantization-fundamentals precision
    communication-computation-overlap optimization
    compute-cost-estimation compute
    diagnosis / evaluation(区域名混入!) cross-cutting
    <track> / <topic> 斜杠形式 按上方主题映射逐条对应
  3. 就地修复(in-place):一次提交、原子化落地;

  4. 为 LinkML schema 增加枚举约束:让 competency_area 在校验阶段直接拒绝 13 个规范值之外的任何输入,并从更新后的 LinkML schema 重新生成 Pydantic 模型(vault-cli 中的 codegen.py 负责模型代码生成);

  5. 重建 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 每个迭代内部做什么

  1. 重新运行分析器(随着新单元被填充,缺口优先级实时更新);
  2. 选取 30 × 4 = 120 个最高优先级单元;
  3. 发起 4 次 Gemini 调用、每次喂 30 个单元(每次调用一次性返回 30 道题的 JSON 数组——这就是"有效利用上下文"规则的落地);
  4. 渲染 DOT / matplotlib 视觉图;
  5. 以 25 个为一组运行 LLM-as-judge 校验新草稿;
  6. 丢弃 verdict: DROP 项,将 PASS 与 NEEDS_FIX 保留为草稿;
  7. 将每次迭代记录到 _validation_results/coverage_loop/<ts>/;
  8. 在以下任一饱和条件下停机:丢弃率 > 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 分钟)

提升前先人工目检生成内容:

  1. 视觉渲染检查:用 Playwright 抽查 5 个随机视觉草稿,确认 SVG 在列宽内内联渲染且不溢出、alt 文本存在、布局干净;
  2. MCQ / 非 MCQ 比例检查:若语料 MCQ 占比从当前的 17% 跌破 12%(新草稿通常是非 MCQ),说明正在向开放式倾斜,需决定在后续环节补充 MCQ 还是接受该漂移;
  3. 每题每 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

整套流程天然可重复,下周再跑一次大规模构建只需:

  1. Phase 0 预检清理(schema 枚举约束就位后通常是 no-op);
  2. Phase 1 分析器;
  3. Phase 2 循环(同样参数);
  4. 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 侧的生成、审计、提升与校验工具。

登录后查看全文
cs249r_book