Hugging Face 为 Transformers 引入模型集成契约，用小型代理模型拦截回归缺陷

回到文章列表 ]:hidden"> Transformers 模型集成契约 已发布 2026年11月3日 在 GitHub 上更新 点赞 - Tarek Ziadé tarekziade 关注 :last-child]:mb-0"> 为什么 bug 能进入 main 分支 引入模型集成契约 UMT5 回归事件 模型是如何被缩小的 用 agent 构建 MIC 随机 vs 过拟合 待解问题 2026 年 7 月 30 日，Transformers 为 T5 启用了 PyTorch 的缩放点积注意力（SDPA）。副作用是，UMT5 的解码器可以关注到未来的 token。训练时，它可以偷看它本应预测的答案。没有任何崩溃，这个 bug 在 main 分支上存在了将近两个月。后来我们回放那些提交时，一个在 CPU 上运行的小型 UMT5 模型在每一次提交上都标记出了这个问题。这篇文章讲的就是那个模型以及围绕它构建的测试。

为什么 bug 能进入 main 分支 Transformers 支持超过 750 种模型类型，其测试套件非常庞大：main 分支上有 88,000 多个 CPU 测试，每日运行中还有 200,000 多个 GPU 测试。模型测试只是其中一部分：我们还会测试 pipeline、训练、分布式执行、量化和注意力 kernel。集成测试会加载真实 checkpoint，并在真实硬件上调用模型的 API。如果每个 PR 都跑这些测试，就意味着要整天占用大量 GPU，这并不现实。等到定时任务发现回归时，它可能已经进入 main 分支了。

我们的做法是把模型缩小。我们构建一个 fixture：用真实 checkpoint 的配置做一个小模型，层数更少、维度更窄，但保留它拥有的每一种层，并且 tokenizer 和 processor 文件保持不变。它发布一次，之后重复使用。我们在廉价的 CPU runner 上对它运行「快速集成测试」。在我们的 CPU 研究中，实验性的 UMT5 fixture 使用了 66 MB 的权重；源 checkpoint 是 1,227 MB。这也覆盖了非常大的模型：有些模型在我们的标准 GPU runner 上放不下，但它们的 fixture 可以在 CPU 上运行。模型集成者已经在构建微型测试模型（Transformers 的 tiny-random-* checkpoint）。我们想要一个通用的配方，以及超越加载模型和跑一次前向传播的检查。UMT5 的 bug 本来是可以轻松通过前向传播的。Fixture 不会取代完整的集成测试，但在 PR 上它们给了我们在 bug 进入 main 之前抓住它的机会。

引入模型集成契约 transformers-mic 是一个拟议的标准，用于打包这些测试。一个模型集成契约（MIC）包含三个部分：如果在该 fixture 上运行使用路径仍能产生基线结果，则契约成立。一个契约覆盖一个架构和一条使用路径，而不是单个 checkpoint：兼容的 checkpoint 可以共享一个 fixture，同时各自保留自己的预期结果。我们将它们发布在 huggingface-mic 中。例如，SmolLM 契约从「The capital of France is」这样的 prompt 生成，并将其 token ID 与记录的答案进行比较。加载模型和 tokenizer 后，生成代码简化为一个 prompt 如下： 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。Hub 上的一个 fleet 数据集将每个 MIC 固定到一个冻结的 revision，以及记录其基线时使用的包版本。每次 CI 运行都会记录它使用的 fleet revision，以便我们之后复现。在 PR 上，我们根据补丁更改的文件来选择 MIC。

UMT5 回归事件 我们在五个月的 Transformers 提交上回放了冻结的 MIC。小型 UMT5 fixture 从 2026 年 7 月 30 日引入该回归起，一直标记到 9 月 28 日修复为止。标签 log-probabilities 与经过审核的基线相差 1.22，训练损失相差约 0.20。有一个细节很重要：契约使用的是 SDPA，即默认的注意力路径。只运行 eager 注意力变体会漏掉这个 bug。只有当 fixture 走与真实 checkpoint 相同的代码路径时，它才有帮助。然后我们在 Transformers CI 的一个证明分支上回退了修复。检查以相同的差异失败，所选 T5 契约的 runner 步骤在 CPU 上耗时 13.4 秒，不含环境准备。回放结果和 CI 演示中有测量数据和复现细节。

模型是如何被缩小的 最初的配方很简单：把维度变小，保留更少的层。这对混合架构来说还不够。如果两层都使用滑动注意力，而全注意力层消失了，保留两层也没有用。我们还保留原始的权重文件格式。否则我们就会跳过用户加载真实 checkpoint 时运行的转换代码。完整配方有更多细节。Llama 4 Scout 缩小报告展示了在大模型上的效果。1086 亿参数变成 4470 万。视觉栈从 34 层变成 2 层，语言栈从 48 层变成 4 层，保留受检的层类型和 MoE 路由风格。

用 agent 构建 MIC 我们的 CLI 工具 tmic 创建契约并构建 fixture。对于新模型，由 LLM 起草使用代码和 manifest，CPU 和 GPU 运行测量候选基线。LLM 只负责起草，不负责批准。更改预期结果需要人工审核。要在你自己的机器上试用，用你的源 checkpoint 替换 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 '' 它会在你的机器上起草契约、构建 fixture 并记录其基线，要求你审核每一步，并在上传任何内容之前停止。对于新模型，草稿来自通过 Inference Providers 调用的 LLM，费用计入你自己的账户（--bill-to ''）。CLI 文档涵盖了各个步骤。

（原文较长，此处译出前 6000 字，完整内容请点「打开原文」。）