StaffML Vault 问题写作权威指南从 YAML 脚手架到 26 项不变量校验的完整规范【免费下载链接】cs249r_bookMachine Learning Systems项目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book本指南以 interviews/vault/AUTHORING.md 为唯一权威来源系统讲解 StaffML Vault 面试题库中每道题目的 YAML 编写规范如何用vault new脚手架生成草稿、如何填写 11 个必填字段与推荐字段、如何遵守 Pitfall/Rationale/Consequence 与 Assumptions/Calculations/Conclusion 两套三段式标记、如何通过vault check --strict与 LLM-judge 多门校验并对照 Pydantic 模型、校验器 与 CLI 实现 从源码层面印证每条规范的强制力。读完你将掌握从零编写一道可入库、可通过 CI 的 StaffML 面试题并理解题库 4 轴分类track / level / zone / bloom背后的教育学设计。一、AUTHORING.md 的定位一切约定的唯一事实源interviews/vault/AUTHORING.md开篇即声明其地位This is the single-source authoring reference. If a convention isnt documented here, it isnt a convention — open an issue.即任何未写入该文档的写法都不构成约定需要约定先开 issue 讨论。这意味着字段名、枚举取值、标题规范、标记结构均以本文档为准文档中描述的约定多数被下游校验器硬性强制不是可选项该文档是人工流程vault new的入口而 LLM 批量生成走vault generate --help但两条路径最终都校验于同一套 schema。配套的题库本体位于 interviews/vault/questions/按cloud / edge / mobile / tinyml / global五个 track 组织Pydantic 数据模型在 models.py不变量检查器在 validator.pyCLI 命令实现位于 commands/authoring.py。二、快速上手从vault new到提交2.1 脚手架命令vault new --title KV Cache Bandwidth Bottleneck on H100 \ --topic kv-cache-management \ --track cloud --level L4 --zone diagnosisvault new完成三件事分配内容寻址 ID、在规范路径下生成 YAML 脚手架、用$EDITOR打开文件。从 authoring.py 源码可见其完整流程分配 ID 前执行git pull --rebase --autostash origin降低多人并发时注册表冲突概率可用--skip-rebase跳过仅限离线开发通过_new_question_id生成形如track-yyyymm-4hex的 IDhash 内容为sha256(title \n topic)的前 4 位十六进制把 topic 纳入 hash 可防止两个同名题目撞 hash碰撞时在 65,536 槽位内递增十六进制后缀把{id, created_at, created_by}追加写入 interviews/vault/id-registry.yamlappend-only 日志禁止改写历史从git config user.email自动填充authors字段用模块级常量模板预填common_mistakePitfall/Rationale/Consequence与napkin_mathAssumptions/Calculations/Conclusion的标记骨架作者只需填充TODO内容。2.2 填写、保存、迭代脚手架会留下若干TODO占位符包括competency_area字段脚手架刻意留空。作者需要填完所有TODO与competency_area保存后校验器立即运行通过则接受文件失败则在文件顶部注入一段# ─── VALIDATION FAILURE ───错误注释块并重新打开文件供迭代_inject_validation_error_comment实现且会剥除旧的错误块避免累积。2.3 全量校验与提交vault check --strict # 对全量语料执行全部 26 项不变量 git add interviews/vault/questions/track/area/id.yaml git commit--strict模式运行 fast structural 两层检查slow 层跑在 nightly CI。提交路径为track/area/id.yaml与文件内字段一一对应详见下文路径镜像。三、必填字段11 项 推荐字段每个 YAML 必须包含以下字段对应 models.py 中的QuestionPydantic模型字段类型约束示例schema_versionstring恒为1.01.0idstring内容寻址track-NNNN由vault new分配cloud-4539trackenumcloud / edge / mobile / tinyml / globalcloudlevelenumL1 / L2 / L3 / L4 / L5 / L6L3zoneenum11 个 zone 之一见下文 Zones 节implementtopicstring需属于taxonomy.yaml中的 87 个 topicquantization-fundamentalscompetency_areaenum13 个领域之一见下文 Competency areas 节precisiontitlestring≤ 120 字符纯文本无句号结尾无 LaTeXW8A16 KV Cache Expansionscenariostring≥ 30 字符纯文本禁 HTML1-3 句见 worked exampledetails.realistic_solutionstring1-3 句权威答案见 worked examplestatusenumdraft / published / flagged / archived / deleted新写作填draftprovenanceenumhuman / llm-draft / llm-then-human-edited / importedvault new流程填human强烈推荐字段字段类型使用时机bloom_levelenumremember / understand / apply / analyze / evaluate / create总是填写——参与 zone × bloom 一致性检查phaseenumtraining / inference / both总是填写questionstring ≤ 200 字符显式疑问句练习页渲染为 Your taskdetails.common_mistakestring总是填写——见标记约定节details.napkin_mathstringL3 且有定量推理时expected_time_minutesinteger ≥ 0通常 5-15源码视角Pydantic 模型如何强制这些约束在 models.py 中Question对每个枚举字段都注册了field_validator_track/_level/_zone/_area/_bloom/_phase/_status/_provenance逐一比对 frozenset 白名单非法取值直接抛ValueError_scenario_plaintextXSS 防御——拒绝script、javascript:、data:text/html、onerror、onload等令牌_zone_bloom_compatiblemodel_validator当zone与bloom_level语义冲突时在数据边界直接拒绝加载使未来任何生成流程都不可能写入自相矛盾的题目_visual_path_resolves若声明了visual:块则校验 SVG 文件真实存在于磁盘跳过生产环境无工作树的情形。值得注意的细节Details模型当前extraforbid任何未声明的 details 键都会报错而Question顶层是extraallow这是为了容纳validation_*、math_*等审计戳字段——见后文何时偏离一节。四、标记约定两套三段式结构被 CI 强制common_mistake与napkin_math两个字段使用三段式加粗标记结构。该结构由vault check --strict强制即 validator.py 中的不变量 #19不符合会直接导致 CI 失败。4.1common_mistakePitfall / Rationale / Consequencedetails: common_mistake: | **The Pitfall:** 候选人会采用的错误直觉或捷径 **The Rationale:** 该直觉为何错误一句话 **The Consequence:** 操作层面的症状——延迟、成本、故障模式三个标记缺一不可、顺序固定。必须使用|字面块标量保留换行渲染器依赖换行。4.2napkin_mathAssumptions / Calculations / Conclusiondetails: napkin_math: | **Assumptions Constraints:** - 假设 1——硬件、模型规模、batch 等 - 假设 2 **Calculations:** - 带单位的步骤 1 - 步骤 2 **Conclusion:** 对结果的一句话解读Assumptions标记允许两种写法**Assumptions Constraints:**或**Assumptions:**Conclusion标记允许两种写法**Conclusion:**或**Conclusion Interpretation:**Calculations标记必须精确写作**Calculations:**。源码视角不变量 #19 的正则validator.py 中的_check_format_markers实现了format-markers检查_CM_MARKER_RE re.compile( r(?s).*\*\*The Pitfall:\*\*.*\*\*The Rationale:\*\*.*\*\*The Consequence:\*\*.* ) _NM_MARKER_RE re.compile( r(?s).*\*\*Assumptions.*\*\*Calculations:\*\*.*\*\*Conclusion.* )语义要点两个字段都是可选的只有存在但格式错误才触发失败空值 / 缺省通过。该检查只作用于status: published的题目草稿豁免——因为草稿可能尚在写作中。这对应validate_drafts.py中的gate_format门被提升为语料级不变量CORPUS_HARDENING_PLAN.md Phase 6 计划进一步将其从正则提升为 LinkML pattern。五、完整范例cloud-4539W8A16 KV Cachecloud-4539L3, zoneimplement, areaprecision经 2026-04-28 专家评审验证可直接作为模板schema_version: 1.0 id: cloud-4539 track: cloud level: L3 zone: implement topic: quantization-fundamentals competency_area: precision bloom_level: apply phase: both title: W8A16 KV Cache Expansion scenario: A 14B parameter LLM is being prepared for serving on a single GPU. The weights in FP16 take 28 GB. The serving target is a concurrent batch of 32 users, each at 4096 max-context tokens. Llama-2-13B-class architecture (40 layers, 40 KV heads, head_dim128) keeps KV at FP16. question: Calculate the W8A16 weight footprint, then compute the maximum sustainable batch size given the 32-user, 4096-token KV cache requirement, and determine if W8A16 is sufficient. details: realistic_solution: W8A16 quantization compresses weights but leaves the massive KV cache footprint untouched. To hit the 32-user target, W8A16 is insufficient on its own. The team must additionally quantize the KV cache to INT8, cap the maximum context length, or implement PagedAttention to reduce fragmentation. common_mistake: | **The Pitfall:** Reporting the weight savings without calculating the corresponding KV cache requirements. **The Rationale:** Candidates often assume that if the model weights fit, the system is ready for production serving. **The Consequence:** The deployed model experiences immediate Out-Of-Memory (OOM) errors as concurrent users fill up the KV cache. napkin_math: | **Assumptions Constraints:** - 14B params at W8A16 (1 byte/param), 80GB HBM. - 40 layers, 40 KV heads, 128 head_dim, FP16 (2 bytes). **Calculations:** - W8 Weights: 14B * 1 byte 14 GB. - Available HBM: 80 GB - 14 GB 66 GB. - KV Cache per Token: 2 (K,V) * 40 * 40 * 128 * 2 bytes 819,200 bytes (~800 KB). - KV Cache per User: 800 KB * 4096 ~3.125 GB. - Max Users Supported: floor(66 GB / 3.125 GB) 21 users. **Conclusion Interpretation:** - **Result: Memory-Bound (OOM)**. W8A16 is insufficient to hit the 32-user target by 11 users. status: published provenance: llm-draft expected_time_minutes: 6这道题展示了范例的全部要素场景给出明确的硬件与架构参数、问题要求执行计算、答案给出量化权重 ≠ 系统就绪的判别结论、common_mistake 指向只看权重不看 KV cache的典型误判、napkin_math 逐行带单位计算并落到Memory-Bound (OOM)结论。每个(track, level)单元格的金标准参考题由 CORPUS_HARDENING_PLAN.md Phase 4 的审计结果从全库中挑选填充。仓库中还可找到早期 exemplar 供对照例如 interviews/vault/exemplars/cloud/cloud-0104.yamltail-latency 主题的 SLA 排队论题含完整三段式标记。六、标题规范12 条铁律长度≤ 120 字符Pydantic 强制Field(max_length120)无句号结尾KV Cache Expansion而非KV Cache Expansion.无 LaTeX禁$math$与\command否则索引构建崩溃无下划线写KV-Cache或KV Cache绝不写KV_Cache——下划线会破坏 LaTeX\index{}宏与索引排序键无 Markdown禁**bold**、_italic_纯文本描述性而非泛化KV Cache Bandwidth Bottleneck on H100✓KV Cache Q1✗真实点名厂商题目确实涉及硬件时写Apple Neural Engine✓只有题目刻意抽象硬件时才允许写 the on-device accelerator禁止虚构厂商名——审计的 vendor-fabrication 失败模式专门抓Coral Edge TPU XL之类的编造。七、Level 与 Bloom 映射LevelBloom verb认知要求L1remember回忆事实、定义、比值L2understand解释概念识别类别L3apply根据给定输入执行计算选出匹配技术L4analyze分解问题根因定位在竞争性权衡中做选择L5evaluate评判设计定量权衡备选方案L6create在非常规约束下综合新设计Staff 范围审计的level_fit门专门打击level 通胀把实际上只是填空式乘法L1/L2的题标成 L4。判断标准是——如果你无法说清候选人必须执行的分解或权衡这道题就不是 L4。教学能力门槛teaching-power bar按 Bloom 分级teaching_power门确保题目交付其level 所承诺的认知深度Bloom 阶梯底端是回忆顶端是推理。它不是每道题都必须计算的一刀切——回忆本身就是一等技能L1/Remember 与 L2/Understand 是热身与筛选题干净的回忆题在那里通过。门只在题目得分低于其 level 对应的地板值时失败Level (Bloom)地板含义L1 remember / L2 understandtp 1回忆就是任务——通过L3 applytp 2必须套用公式而非仅回忆L4 analyze / L5 evaluate / L6 createtp 3必须推理伪装成难题的回忆题失败失败模式是不匹配标成 L5/evaluate 实为 L1 查表的题。修复方式是提升推理深度到与 level 相称或改标到它实际测试的 level。校准基准是金标准 exemplar而非同格中等水平者。从 validate_drafts.py 源码可见_BLOOM_FLOOR {remember: 1, understand: 1, apply: 2, analyze: 3, evaluate: 3, create: 3}与_LEVEL_FLOOR的精确映射以及 5 分制的判定锚点tp5 GOLD — 强制计算权衡干扰项编码真实误解可迁移的系统原理如 Partitioning an A100 MIG for 7B1Btp1-2 VACUOUS — 凭记忆/直觉可答napkin-math 只做姿态不真算。八、Zones11 个技能区域四个纯 zone、六个复合 zone、一个 masteryZone所需技能recallrememberanalyzeanalyzedesigncreateimplementapplyfluencyrecall quantifydiagnosisrecall analyzespecificationrecall designoptimizationanalyze quantifyevaluationanalyze designrealizationdesign quantifymastery全部四项——Staff 综合九、Zone × Bloom 亲和矩阵HARD 约束vault check --strict拒绝zone与bloom_level不一致的 YAML。完整矩阵zone允许的 bloom levelsrecallremember, understandfluencyremember, understand, applyanalyzeapply, analyzediagnosisapply, analyze, evaluateevaluationanalyze, evaluatedesignapply, analyze, evaluate, createspecificationapply, analyze, evaluate, createoptimizationapply, analyze, evaluate, createrealizationapply, analyze, evaluate, createmasteryanalyze, evaluate, createimplementunderstand, apply, analyze, evaluate, create如果校验器报 zone × bloom 不匹配说明两字段中有一个错了——选更能反映题目真实认知需求的那个拿不准时相信bloom_level调整zone。该约束在 models.py 中由_zone_bloom_compatible模型校验器在数据加载边界强制执行报错信息会直接列出该 zone 允许的集合。十、Competency areas13 个封闭枚举compute, memory, latency, precision, power, architecture, optimization, parallelism, networking, deployment, reliability, data, cross-cutting选题目主轴对应的那个领域。例如把 KV cache 量化以适配内存预算的题同时触及 precision 与 memory但答案主要依赖约束条件 HBM 大小则应选memory。十一、Topics87 个封闭枚举87 个 topic 构成封闭枚举文档索引为interviews/vault/schema/enums.py:VALID_TOPICS。CLI 支持vault new --topic Tab自动补全。新增 topic 属于 schema 变更需要同时对 enums.py 与 taxonomy.yaml 提 PR并运行vault codegen重新生成。十二、Phasetraining、inference或both。部署前的quantization题是inferencemixed-precision-training题是training通吃吞吐-延迟权衡的题是both。十三、Gotchas写作避坑清单写I/O不写IO拼写检查器与索引标签生成器都偏好斜杠形式直引号不用弯引号’弯引号会让索引条目重复Moores Law≠Moores Lawtitle / scenario / question 中禁用 Markdown会渲染成字面星号而非加粗scenario 中禁止script、javascript:、data:text/html校验器直接拒绝对应 Pydantic 的_scenario_plaintextvisual.path必须可解析引用 SVG 前先运行render_visuals.py --id qid渲染vault check --strict对悬空引用报错对应_visual_path_resolvesprovenance取值规则vault new流程填humanvault generate输出填llm-draft历史语料填importedllm-draft被人实质改写后填llm-then-human-edited。十四、如何测试你的草稿# 1. Schema 不变量检查最快——跑全量语料60s vault check --strict # 2. 格式标记合规无 LLM 调用 python3 interviews/vault-cli/scripts/validate_drafts.py --no-llm-judge # 3. 完整 LLM-judge 门level_fit, coherence, bridge, teaching_power python3 interviews/vault-cli/scripts/validate_drafts.py第三条命令执行六门评分卡validate_drafts.py 的evaluate_draft依次运行schema— PydanticQuestion模型与发布题同一门槛originality— 与同(track, topic)最近邻的余弦相似度超过阈值默认 0.92即拒绝默认加载 BAAI/bge-small-en-v1.5 嵌入模型可用--no-originality跳过level_fit— Gemini 判官以同 track、同 topic、同 level 的已发布题上限由LEVEL_FIT_EXEMPLAR_LIMIT决定作为校准锚点判定候选题的认知负荷是否与 level 匹配该格无 published 锚点时跳过coherence— Gemini 判官scenario / question / realistic_solution 三者是否互相一致问题是否由场景自然引出、答案是否真正回答问题、数值是否自洽bridge— Gemini 判官候选题是否在_authoring.gap.between的两个锚点题之间形成教学链认知负荷递增方向、共享场景线索、插入后构成连贯的 1 递进链teaching_power— 前述tp评分门。所有门全部返回 yes或被跳过才通过。结果写入interviews/vault/draft-validation-scorecard.json。十五、端到端流程vault new ↓ (分配 id、生成 YAML 脚手架、打开 $EDITOR) 编辑 YAML —— 填 TODO、补 competency_area、写全 Pitfall/Rationale/Consequence 三段 ↓ (vault edit 保存时重新校验失败则注入错误块并重新打开) vault check --strict ↓ git add interviews/vault/questions/track/area/id.yaml git commit ↓ pushCI 运行 staffml-validate-vault.yml完整校验器 测试 lint路径镜像不变量值得单独说明的是 validator.py 中的 fast-tier 检查语料采用track/competency_area/id.yaml三层层级布局文件路径是正文字段的派生索引——正文才是事实源路径必须镜像它。path-track-match、path-area-match、path-id-match三项检查防止审计改了 track 字段但文件没移动导致目录结构与正文漂移。文件名还必须全小写。十六、何时真正需要偏离schema 演化Question模型的extraallow允许未声明的顶层字段如validation_*、math_*审计戳。而Details目前已是extraforbid——CORPUS_HARDENING_PLAN.md Phase 6 会把 Question 也翻转成extraforbid届时任何合法的额外 detail 字段都必须显式加入模型。如果你发现自己想用未识别的字段这是 schema 演化问题开 issue不要悄悄塞进去。十七、延伸阅读interviews/vault/ARCHITECTURE.md — v2.2 设计文档§3.6.1 讲解 LLM 题目落地时的_authoring私有块与gap-bridge:from-to标签§4.1 详述vault new/edit/rm/move等 authoring 原语interviews/vault/docs/ID_SCHEMES.md — ID 方案演进当前为track-NNNN单调序列interviews/vault-cli/docs/CORPUS_HARDENING_PLAN.md — 活跃工作计划Phase 4 金标准挑选、Phase 6 格式标记与 schema 收紧interviews/vault-cli/src/vault_cli/models.py — Pydantic 模型schema 的派生镜像interviews/vault-cli/src/vault_cli/validator.py — 26 项不变量检查器interviews/vault-cli/src/vault_cli/commands/authoring.py — authoring 命令实现interviews/vault/README.md — 语料库结构总览含 CC-BY-NC-4.0 许可说明【免费下载链接】cs249r_bookMachine Learning Systems项目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
