2026 年 7 月 30 日，Hugging Face Transformers 库为 PyTorch 的 T5 模型启用了缩放点积注意力（SDPA）。这一变更引发了一个隐蔽的副作用：UMT5 解码器在处理未来 token 时出现异常，导致训练过程中能够“窥探”到预测答案。尽管未造成系统崩溃，但该 Bug 在代码主线中潜伏了将近两个月。
最终，一个在 CPU 上运行的微型 UMT5 测试模型捕获了这一回归问题。本文旨在探讨该测试模型的构建逻辑及其背后的集成测试策略。
为何 Bug 能潜入主线？
Transformers 支持超过 750 种模型架构，其测试套件规模庞大：主分支每日需运行逾 88,000 个 CPU 测试和 200,000 多个 GPU 测试。测试范围涵盖模型本身、Pipeline、训练流程、分布式执行、量化及注意力核心机制等。
传统的集成测试通常加载真实检查点并在真实硬件上运行 API。然而，在每个 Pull Request (PR) 上执行全量集成测试需要占用大量 GPU 资源，这在工程实践中并不具备可行性。因此，当 CI 计划任务发现回归问题时，Bug 往往已经合并至主线。
为解决这一矛盾，团队采取了缩小模型规模的策略：构建基于真实检查点配置的测试夹具（Fixture）。这些夹具保留了所有类型的层结构、Tokenizer 和处理器文件，但减少了层数并降低了宽度。通过在低成本 CPU 运行器上执行“快速集成测试”，显著提升了效率。例如，实验性的 UMT5 夹具权重仅占 66 MB，而源检查点大小高达 1,227 MB。
这种方案同样适用于超大模型——那些无法在标准 GPU 运行器上测试的模型，其缩小版可在 CPU 上运行。此前，模型贡献者已建立微小的随机初始化检查点，但新的通用配方不仅验证模型加载，更通过前向传播捕捉如 UMT5 这类深层逻辑错误，从而在 PR 阶段拦截 Bug。
引入模型集成合约（MIC）
transformers-mic 包确立了此类测试的标准规范。模型集成合约（Model Integration Contract, MIC）包含三个核心要素：
- 固定装置：上述描述的缩小模型，发布一次后保持固定。
- 使用路径：可运行的 Markdown 示例，演示典型操作（如文本生成或训练步骤）。
- 基线：运行示例时记录的输出结果，需经人工审查确认。
若固定装置在执行使用路径后仍产生符合基线的输出，则视为合约有效。一个合约涵盖一种架构和一个使用路径，而非单一检查点；兼容的检查点可共享同一固定装置，但各自保留独立的预期结果。
以 SmolLM 合约为例，它从提示词“The capital of France is”生成文本，并将生成的 Token ID 与记录的答案进行比对。加载模型和分词器后，生成代码简化如下：
inputs = tokenizer("The capital of France is", return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=4, do_sample=False)
new_tokens = outputs[:, inputs["input_ids"].shape[1]:]
print(tokenizer.batch_decode(new_tokens, skip_special_tokens=True))
此外，合约还比较训练损失，检查梯度是否有限，并验证优化步骤是否改变权重。完整的用法文档见 usage.md。
Hugging Face Hub 上的数据集将每个 MIC 与其基线修订版本及用于记录基线的包版本关联起来。每次 CI 运行都会记录所使用的数据集修订版本，以确保结果的可复现性。在 PR 处理过程中，系统根据补丁修改的文件自动选择相应的 MIC。
UMT5 回归案例复盘
团队重放了五个月的 Transformers 历史 MIC 数据。小型 UMT5 夹具成功标记出从 2026 年 7 月 30 日引入至 9 月 28 日修复期间的回归问题。日志显示，标签概率与审查基线的差异为 1.22，训练损失差异约为 0.20。
值得注意的是，合约默认使用 SDPA 注意力路径。仅运行急切注意力（Eager Attention）变体未能捕获该错误。这表明固定装置必须通过与真实检查点相同的代码路径进行测试。
随后，团队在 Transformers CI 中恢复了证明分支的修复。检查结果显示，选定的 T5 合约在排除设置时间后，CPU 运行步耗时仅为 13.4 秒。复制结果和 CI 演示均提供了详细的测量与复现指南。
如何构建缩小模型
简单的缩小尺寸和减少层数对于混合架构而言并不足够。如果滑动注意力和全注意力层同时存在，移除其中一类会导致剩余层失效。
当前的构建配方包含四个步骤：
- 缩小配置：从真实检查点开始，减小隐藏维度、注意力头数和深度。保留不同的层类型（包括滑动/全注意力混合，或密集/MoE 层混合）。部分架构需额外规则以保持组件兼容性。参考
test_modeling_<model>.py中的ModelTester手动选择的小配置，填补通用规则未覆盖的宽度参数。 - 保持预处理不变：保存词汇表、特殊标记和输入尺寸，逐字节复制 Tokenizer 和处理器文件。加载和预处理是测试的关键环节。
- 构建并验证权重：尝试种子随机权重并变换输入以检查模型响应。在合约的小批量样本上进行训练测试。重新加载保存的模型，检查输出、损失和梯度是否有限。拒绝失败的构建。
- 录制基线：保存接受的权重，并在已知良好的 Transformers 构建中测量可重复的输出。审查每个支持平台和精度的基线，然后发布固定快照。这避免了为每个 PR 重建固定装置。
原始权重文件格式也被保留，以免跳过用户加载真实检查点时触发的转换代码。完整配方详见官方文档。
Llama 4 侦探报告展示了该方法在大模型上的应用效果：1086 亿参数缩减至 4470 万。视觉堆栈从 34 层减至 2 层，语言堆栈从 48 层减至 4 层，同时保持了检查过的层类型和 MoE 路由风格。
利用代理构建 MIC
CLI 工具 tmic 用于创建合约并构建固定装置。对于新模型，LLM 起草使用代码和声明，CPU 和 GPU 运行器测量候选基线。法律士课程草稿由 LLM 生成，但未获批准；任何期望值的变更均需人类审查。
在本地机器上使用源检查点（替换 org/model）进行测试的命令如下：
pip install "transformers-mic[runtime]" "hf-doc-builder @ git+https://github.com/huggingface/doc-builder.git"
hf auth login
tmic run org/model --local-only --fixtures-only --no-history --bill-to ''
该命令起草合约，构建设备，在本地记录基线，并要求逐步检查。对于新模型，草案来自通过推理提供商调用的 LLM，费用计入用户账户（--bill-to ''）。各步骤细节参见 CLI 文档。
团队利用代理构建跨模型家族的 MIC，并在模型专家协助下修正配方本身，而非单个固定装置。已公布模型和剩余差距均在覆盖空间内。
随机权重与过拟合权衡
Whisper 测试夹具对音频变化反应微弱，虽然能运行，但对音频路径的测试能力较差。为此，团队对其进行微调，使其将特定音调与“红色”、“绿色”等词汇配对。这并非教授语音识别，而是确保输出反映音频变化。
在故障注入实验中，随机初始化的 Whisper 夹具从 24 个注入故障中捕获了 18 个，而过拟合夹具捕获了全部 24 个。
这提供了两种权重构建方法：
- 从随机权重和固定种子开始。
- 针对特定提示（如"The capital of France is" => "Paris"）进行微调。
实验结果并未明确哪种方法更优。这些都是合成故障，未发现仅被过拟合版本捕获的真实回归。两种版本都错过了真实 Whisper 检查点暴露的辅助解码漏洞。
因此，当随机权重通过检查时予以保留；当需要更高灵敏度或可读答案时使用微调版本。微调仅需几秒钟，但这增加了维护步骤。对比两者均有价值。
开放性问题
截至 2026 年 11 月 1 日，Transformers CI 中的 MIC 工作报告失败但不阻止 PR 合并。是否应阻塞 PR 取决于尚未测量的指标：
- 它在 PR 中捕获了多少真实 Bug（而非仅在重放中）？
- 它是否频繁导致误报追踪？
- 基线审查需要多长时间？
目前尚不清楚有多少 Bug（如 Whisper 辅助解码 Bug）仅在真实权重下才会显现。
覆盖范围目前在模型家族和用户使用的 API 方面仍不完整。团队将继续添加缺失的使用路径，并在破碎和固定版本上进行重放。现有测试将被保留，直到其覆盖范围被完全计算出来。
最终目标是链接原始 Hub 模型页面与其 MIC，使开发者或使用检查点的代理能够从检查点、环境和预期输出中获取测试示例。
社区参与方式：从覆盖空间中选择一个未覆盖的模型，尝试 tmic 工作流程，并提供使用路径或审查生成的合约。
