StaffML Vault 发布审计工作流：确定性检查与 LLM 语义评审的完整管线

StaffML Vault 发布审计工作流：确定性检查与 LLM 语义评审的完整管线

【免费下载链接】cs249r_bookMachine Learning Systems项目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book

本文以 interviews/vault/audit/README.md 为核心文档，讲解 StaffML 面试题库（Vault）在发布前的双轨质量审计体系：以规范格式化、确定性语料审计、保守修复为主的确定性检查，以及由 LLM 驱动的语义评审（语义批量构建、冒烟测试、按 track 并行评审、结果汇总）。读完本文，你将掌握一套可直接落地的语料发布门禁流程、全部命令行参数含义，以及各阶段输出工件（JSONL/队列/汇总报告）的存放约定，并能结合仓库内已归档的 Phase 2 内容审计与 Schema 目录审计案例理解其设计动机。

一、背景：audit 目录在 Vault 质量体系中的定位

StaffML Vault 是cs249r_book仓库内维护的一套按题目组织的 YAML 面试题库，语料规模约9,657 个 YAML 文件，按cloud、edge、mobile、tinyml、global五个 track 组织（见 interviews/vault/README.md）。每道题都带有zone、level、bloom_level、competency_area、details（含realistic_solution、common_mistake、napkin_math）等结构化字段，因此语料质量不仅取决于内容本身，还取决于字段填充是否完整、分类是否合理、与论文的 zone×level 亲和表是否一致。

在 Vault 的既有质量基线之上——interviews/vault/README.md 列出 26 条分层不变量（fast / structural / LSH 场景去重 / nightly / weekly）——audit 目录承担的是发布级审计职责。按 interviews/vault/audit/README.md 的定义，该目录存放两类东西：

• 发布审计报告：确定性检查报告（fresh-yaml-audit/下的 summary、issues、stats）与语义评审结果（semantic-review-results/）；
• 归档的历史实验：如 phase2 的 zone/level 重分类审计、2026-04-25-schema-folder-audit.md 的 Schema 与目录结构审计。

其中archive/仅用于留存历史实验，不得作为发布的事实来源（"should not be used as the release source of truth"）。

二、六步发布审计工作流总览

按 interviews/vault/audit/README.md，正式发布前的审计是一个六步流程，前四步是确定性（deterministic）工具链，第五步是发布门禁，第六步是面向已发布题目的语义评审：

这一设计体现了"确定性检查打底、LLM 评审兜底"的分层思路：凡能被规则、模式、枚举、哈希等确定性手段发现的问题，绝不动用成本更高的模型评审；语义评审只处理需要"读题理解"才能判断的质量维度。

三、确定性检查：规范格式化、语料审计与卫生修复

3.1 第一步：规范格式化器（check 模式）

python3 interviews/vault/scripts/format_yaml_questions.py

该脚本以check 模式运行——只报告不符合规范格式的 YAML，不做修改。所谓"规范"（canonical）形态，在 Vault 中有着严格定义：按 interviews/vault/ARCHITECTURE.md §3.5，每道题的content_hash是对白名单语义字段的规范化 JSON做 SHA-256 得到，而非对 SQLite 字节做哈希；CANON_VERSION常量固定在vault_cli/hashing.py中，只有规范化算法本身变化（如 Unicode 归一化形式、key 排序递归深度、字段白名单调整）时才递增。这意味着"格式化是否规范"是可判定、可复现的——这正是第一步能作为门禁的前提。

3.2 第二步：确定性语料审计

python3 interviews/vault/scripts/audit_yaml_corpus.py

确定性审计基于规则和枚举检查整个语料，其判定不依赖任何模型。当前活跃的确定性报告输出到（相对interviews/vault/audit/）：

• fresh-yaml-audit/summary.md—— 审计结论汇总；
• fresh-yaml-audit/issues.jsonl—— 逐条问题记录（JSON Lines，便于 diff 与回溯）；
• fresh-yaml-audit/stats.jsonl—— 统计流水。

这类审计与仓库中已有的分层不变量体系（interviews/vault/README.md 的 26 条）互补：不变量管"结构不坏"（schema 校验、ID 唯一、路径小写、链引用存在、注册表只增不改等），audit_yaml_corpus.py管"发布级质量基线"。

3.3 第三步：保守卫生修复

python3 interviews/vault/scripts/fix_yaml_hygiene.py

"保守"（conservative）是关键约束：只修复确定性、零歧义的问题，例如明显的格式偏差、字段填充遗漏、标签语义不一致等，绝不基于猜测改动题面内容。这与 2026-04-25-schema-folder-audit.md 中"分类是数据而非寻址""重分类不应产生文件移动成本"的设计理念一致——任何会改变语义的修改都留给人工或后续语义评审，而不是由机械脚本代为决定。

四、语义评审：为已发布题目构建评审批次

4.1 第四步：构建语义评审队列

python3 interviews/vault/scripts/prepare_semantic_review_queue.py

语义评审的输入由该脚本产出，写入（相对interviews/vault/audit/）：

• semantic-review-queue/published_semantic_queue.jsonl—— 全部已发布题目的评审队列；
• semantic-review-queue/<track>_published_semantic_queue.jsonl—— 按 track 拆分的队列；
• semantic-review-queue/batches/<track>/*.jsonl—— 每个 track 内的批次文件；
• semantic-review-queue/semantic_review_prompt.md—— 喂给评审模型的提示词模板。

注意：语义评审只面向published（已发布）题目，草稿不进入该队列——这与 Vault 的生命周期设计一致：草稿尚未经过验证，先由 AUTHORING.md 的创作流程与vault promote晋升，晋升后才值得投入语义评审算力。

4.2 语义评审覆盖的五个质量维度

按 interviews/vault/audit/README.md，语义评审用于校验：

1. question quality（问题质量：题干是否清晰、可作答、无歧义）；
2. answer correctness（参考答案是否正确）；
3. napkin math（草稿计算/量级估算是否成立）；
4. physical plausibility（物理合理性，尤其针对硬件、算力、能耗类场景）；
5. level fit（题目难度是否与声明的level匹配）。

4.3 评审模型选择策略

这是一个典型的"分层模型路由"实践：便宜模型做广覆盖初筛，昂贵模型只做窄范围复核，避免为每条发现都付出高成本。

五、实战命令：冒烟测试 → 并行全量 → 汇总

5.1 先跑冒烟测试（强烈建议）

在启动全量语义评审之前，先用最小规模验证管线本身可用：

python3 interviews/vault/scripts/semantic_audit_questions.py \ --limit 2 \ --workers 1 \ --out interviews/vault/audit/semantic-review-results/smoke_semantic_findings.jsonl

参数解读：

• --limit 2：只评审 2 条题目，秒级完成；
• --workers 1：单 worker 串行执行，避免并发放大错误；
• --out interviews/vault/audit/semantic-review-results/smoke_semantic_findings.jsonl：显式指定输出路径，冒烟结果落到semantic-review-results/下的独立文件，与正式结果隔离。

冒烟测试验证三件事：脚本参数解析正常、与模型 API 连通、输出 JSONL 结构符合预期。它把"全量跑数小时才发现配置错误"的风险压缩到一次 2 条题目的试运行中。

5.2 按 track 并行运行全量评审

python3 interviews/vault/scripts/run_semantic_audit_tracks.py --workers-per-track 3 --batch-size 10 --request-timeout 120

参数解读：

• --workers-per-track 3：每个 track 内 3 个并发 worker；
• --batch-size 10：每批 10 条题目，模型按批读取与作答，兼顾上下文长度与吞吐；
• --request-timeout 120：单次请求超时 120 秒，防止个别慢请求拖死整个 worker。

"按 track 并行"意味着 5 个 track 各自拥有独立的 worker 池与批次文件，天然支持断点续跑（已完成 track 的结果落盘后即可独立汇总）。

5.3 汇总语义评审结果

python3 interviews/vault/scripts/summarize_semantic_audit.py

汇总脚本把所有<track>的发现合并为一份人类可读报告，输出到（相对interviews/vault/audit/）：

• semantic-review-results/<track>_semantic_findings.jsonl—— 每个 track 的原始发现（机器可读、可回溯）；
• semantic-review-results/summary.md—— 全局汇总报告（面向发布决策者）。

六、输出工件一览

这些文件全部以 JSONL 为主，是为了保证可 diff、可合并、可回溯——与 interviews/vault/README.md 中"SQLite 不作为源真相、YAML 才是源真相"的取舍一脉相承：审计痕迹应当像源码一样进得了 git、经得起 blame。

七、归档策略：历史实验与发布真相分离

interviews/vault/audit/README.md 明确规定：历史实验归档在archive/下，不得作为发布的事实来源。当前仓库中interviews/vault/audit/已归档两份有代表性的审计文档，可作为理解该流程实际效果的样本：

7.1 Phase 2 内容审计（zone/level 重分类）

phase2/README.md 记录了一次针对 9,657 道题的 zone/level 分类审计：vault lint标出1,606 个 zone-level 亲和度离群点，按(zone, level, id)排序后切成 11 个分片（每片约 150 题），由 11 个并行 LLM Agent 依据 phase2_rubric.md 独立判定，最终把 813 个高/中置信度重分类写入 YAML，37 个低置信度提案仅保留在 phase2_aggregated.json 而未应用。结果是离群点从 1,606 降到 847（-47%），且剩余的 847 属于"技术上游离亲和表、但内容上仍是最好标签"的合理残留——印证了论文 §3.3 中亲和表是软约束的定位。

这与本文的语义评审是同一方法论在不同阶段的应用：分片并行 + 结构化决策输出 + 置信度分级 + 只应用高置信结果。无论评审对象是分类还是题目质量，"保守应用"始终是底线。

7.2 Schema 与目录结构审计

2026-04-25-schema-folder-audit.md 在 9,982 个 YAML（9,224 published / 458 deleted / 300 draft）上审查了目录结构与 Schema 的匹配度，结论是"保持扁平目录、保持 LinkML Schema"，仅建议三项小修（新 ID 加软正则、删除未使用的details.question字段、promotion 时清理 cohort tags）。它同时记录了 v0.1 → v1.0 的失败教训（路径即分类曾导致 86 道题被静默丢弃），是理解 Vault 为何坚持"分类是数据、不是寻址"的关键一手材料。

八、发布门禁与最佳实践

综合 interviews/vault/audit/README.md 与仓库既有约束，可将这套流程提炼为四条可执行准则：

1. 先确定性、后语义：format → audit → fix三步跑完、fresh-yaml-audit/清零后再谈语义评审；确定性发现未修复前禁止发布（"Fix all deterministic findings before release"）。
2. 先冒烟、后全量：全量并行（5 track × 3 workers）之前，务必用--limit 2 --workers 1验证管线，输出隔离到smoke_semantic_findings.jsonl。
3. 模型分级路由：默认gpt-5.4-mini扫全量，gpt-5.5只复核 disputed / high-severity 发现，质量、延迟、成本三者平衡。
4. 审计痕迹可回溯：所有中间产物走 JSONL + 独立路径（queue、batches、findings 分层存放），历史实验进archive/与发布真相严格隔离；需要追溯某次重分类决策时，直接看对应的*_findings.jsonl与聚合文件。

这套"确定性检查 + LLM 语义评审 + 保守应用 + 痕迹归档"的组合，正是大规模结构化语料（近万条 YAML）在持续演进中仍能保持发布可信度的工程答案。

【免费下载链接】cs249r_bookMachine Learning Systems项目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book