Hugging Face 提出 Transformers 模型集成契约 MIC

为什么缺陷会进入主分支

Transformers 支持超过 750 种模型类型，其测试套件规模庞大：主分支上有 88,000 多个 CPU 测试，每日运行中还有 200,000 多个 GPU 测试。模型测试只是其中一部分：我们还会测试流水线、训练、分布式执行、量化和注意力内核。

集成测试会加载真实检查点，并在真实硬件上调用模型的 API。如果每个 PR 都运行全部这些测试，就意味着要整天占用大量 GPU，这并不现实。等到定时运行发现回归时，它可能已经进入主分支了。

我们的做法是把模型缩小。我们构建一个 fixture：用真实检查点的配置生成一个小模型，层数更少、宽度更窄，但保留它拥有的每一种层，并且其分词器和处理器文件保持不变。它只发布一次，之后重复使用。我们在廉价的 CPU runner 上针对它运行“快速集成测试”。在我们的 CPU 研究中，实验性的 UMT5 fixture 使用了 66 MB 权重；源检查点为 1,227 MB。

这也覆盖了非常大的模型：有些模型无法装进我们的标准 GPU runner，但它们的 fixture 可以在 CPU 上运行。

模型集成者已经在构建微型测试模型（Transformers 的 tiny-random-* 检查点）。我们想要一个通用的配方，以及超越加载模型和运行前向传播的检查。UMT5 的缺陷本来可以顺利通过前向传播。

Fixture 不会取代完整的集成测试，但在 PR 上，它们让我们有机会在缺陷进入主分支之前将其捕获。

引入模型集成契约

transformers-mic 是打包这些测试的拟议标准。一个模型集成契约（MIC）包含三部分：

一个 fixture：上述缩小后的模型，发布一次并固定版本

一条用法路径：一个可运行的 Markdown 示例，展示人们使用该模型做的事情，例如生成文本或运行一个训练步骤

基线：运行该示例时记录的输出，由人工审核

如果在该 fixture 上运行用法路径仍能产生基线，则契约成立。

一个契约覆盖一种架构和一条用法路径，而不是单个检查点：兼容的检查点可以共享一个 fixture，同时各自保留自己的预期结果。我们将它们发布在 huggingface-mic 中。

例如，SmolLM 契约会根据“The capital of France is”等提示进行生成，并将其 token ID 与记录的答案进行比较。加载模型和分词器后，生成代码简化为单个提示如下：

它还会比较训练损失，检查梯度是否有限，并验证优化器步骤会改变权重。参见完整的 usage.md。

Hub 上的 fleet 数据集将每个 MIC 固定到一个冻结的修订版本，以及用于记录其基线的包版本。每次 CI 运行都会记录它使用的 fleet 修订版本，以便我们日后复现。

在 PR 上，我们根据补丁更改的文件来选择 MIC。

UMT5 回归

我们在五个月的 Transformers 提交上回放了冻结的 MIC。小型 UMT5 fixture 从该回归于 2026 年 7 月 30 日引入起，一直到 9 月 28 日修复，都标记出了它。标签对数概率与审核过的基线相差 1.22，训练损失相差约 0.20。

有一个细节很重要：该契约使用了 SDPA，即默认的注意力路径。只运行 eager 注意力变体会漏掉这个缺陷。只有当 fixture 走与真实检查点相同的代码路径时，它才有帮助。

随后我们在 Transformers 的 CI 中于一个证明分支上回退了该修复。检查以相同的差异失败，并且所选 T5 契约的 runner 步骤在 CPU 上耗时 13.4 秒，不包括设置时间。

回放结果和 CI 演示中有测量数据和复现细节。

模型如何被缩小

最初的配方很简单：把维度变小，保留更少的层。这对混合架构来说还不够。如果两层都使用滑动注意力，而全注意力层消失了，那么保留两层也没有用。

现在的配方有四个步骤：

缩小配置。从真实检查点开始，减小隐藏大小、注意力头数和深度。保留不同的层类型，包括滑动注意力和全注意力的混合，或稠密层和 MoE 层的混合。有些架构需要额外规则来保持其组件兼容。我们还会查看模型自身的 Transformers 测试：test_modeling_ .py 中的 ModelTester 已经手工挑选了一个小配置，因此对于我们的通用规则不知道名称的任何宽度，我们采用它的尺寸。

保持预处理不变。保留词汇表、特殊 token 和输入维度，并逐字节复制分词器和处理器文件。加载和预处理是我们想要测试的一部分。

构建并验证权重。尝试带种子的随机权重，并更改输入以检查模型是否有响应。如果没有响应，尝试在契约的小批量示例上训练它。重新加载保存的模型，并检查输出、损失和梯度是否有限。拒绝失败的构建。

冻结并记录。保存接受的权重，并在已知良好的 Transformers 构建上测量可重复的输出。审核每个受支持平台和精度的基线，然后发布一个固定快照。CI 复用它；它不会为每个 PR 重建 fixture。

我们还会保留原始的权重文件格式。否则，我们就会跳过用户加载真实检查点时运行的转换代码。完整配方有更多细节。

Llama 4 Scout 的缩小报告展示了这在大型模型上的效果。1086 亿参数变成 4470 万。视觉栈从 34 层减到 2 层，语言栈从 48 层减到 4 层，同时保留所检查的层类型和 MoE 路由风格。

用智能体构建 MIC

我们的 CLI，tmic，创建契约并构建 fixture。对于新模型，LLM 起草用法代码和清单，CPU 和 GPU 运行测量候选基线。LLM 只起草，不批准。更改预期需要人工审核。

要在你的机器上试用，请用你的源检查点替换 org/model：

它起草契约、构建 fixture 并在你的机器上记录其基线，要求你审核每一步，并在上传任何内容之前停止。对于新模型，草稿来自通过 Inference Providers 的 LLM，费用计入你自己的账户（ --bill-to '' ）。CLI 文档涵盖了各个步骤。

我们使用智能体跨模型家族构建 MIC。当它们遇到边缘情况时，我们在模型专家的帮助下修复配方本身，而不是修复单个 fixture。已发布的模型和剩余缺口在覆盖空间中。

随机权重与过拟合

使用随机权重时，我们的 Whisper fixture 对音频变化几乎没有响应。它能运行，但这使它成为音频路径的糟糕测试。

因此，我们用几个音调与“red”和“green”等词配对来训练它。我们并不是在教它语音识别，只是让音频变化在其输出中可见。在我们的权重初始化研究中，随机 Whisper fixture 捕获了 24 个注入故障中的 18 个。过拟合 fixture 捕获了全部 24 个。

这给了我们两种构建权重的方法：

从随机权重和固定种子开始。

在几个示例上过拟合，比如“The capital of France is” => “Paris”。

Whisper 的结果并不能决定哪种更好。那些是合成故障，我们还没有发现只有过拟合版本才能捕获的真实回归。两个版本都漏掉了真实 Whisper 检查点暴露的一个辅助解码 bug。

因此，当随机权重通过检查时，我们保留它们；当我们需要更好的灵敏度或可读答案时，我们使用过拟合。训练只需几秒钟，但它是多一个可能无法收敛的步骤，也是多一个需要维护的东西。比较中有两者的结果。

未解决的问题

截至 2026 年 11 月 1 日，Transformers CI 中的 MIC 任务报告失败但不阻塞 PR。它是否应该阻塞取决于我们尚未测量的事情：

它在 PR 上（而不仅仅是在回放中）能捕获多少真实 bug？

它多久会让我们追逐误报？

基线审核需要多少工作？

我们也不知道有多少 bug（比如 Whisper 辅助解码那个）只在真实权重下出现，或者过拟合是否能捕获随机权重漏掉的真实 bug。

覆盖仍然是部分的，跨模型家族和人们使用的 API。当回归漏过时，我们可以添加缺失的用法路径，并在损坏和修复版本上回放它。我们将保留现有测试，直到它们的覆盖被计入。

最后，我们希望将原始 Hub 模型页面链接到它们的 MIC，这样使用检查点的开发者或智能体可以从在该检查点、其环境和预期输出上测试过的示例开始。

想帮忙？从覆盖空间中选择一个未覆盖的模型，尝试 tmic 工作流，并贡献一个用法路径或审核生成的契约。

本文提到的模型 1

huggingface-mic/smollm-mic

本文提到的数据集 1

huggingface-mic/transformers-fleet

本文提到的 Space 1

MIC 覆盖

Transformers 模型类型的 MIC 契约覆盖

来自我们博客的更多文章

超越 LoRA：你能击败最流行的微调技术吗？