2026 年 7 月 30 日,Transformers 为 T5 启用了 PyTorch 的缩放点积注意力(SDPA,scaled dot-product attention)。作为副作用,UMT5 的解码器能够注意到未来的 token。在训练期间,它甚至可以窥视本应由它预测的答案。没有任何程序崩溃报错,这个 bug 在 main 分支中潜伏了近两个月。
当我们后来重放这些提交(commits)时,一个在 CPU 上运行的小型 UMT5 模型在每一次提交中都标记出了该问题。本文将介绍该模型以及围绕它构建的测试体系。
为什么 Bug 会合入 main 分支
Transformers 支持超过 750 种模型类型,其测试套件十分庞大:main 分支上有 88,000 多个 CPU 测试,日常运行中还有 200,000 多个 GPU 测试。 模型测试仅是其中的一部分:我们还要测试流水线(pipelines)、训练、分布式执行、量化以及注意力算子(attention kernels)。
集成测试会加载真实检查点(checkpoints),并在真实硬件上调用模型的 API 进行检验。在每个 PR(Pull Request)上都跑完整套测试意味着整天占用大量 GPU,这是不切实际的。而等到定时运行的任务发现回归问题(regression)时,它可能已经被合入 main 分支了。
我们的做法是对模型进行缩减。我们构建了一个 测试固件(fixture):一个基于真实检查点配置构建的小型模型,层数更少、层宽更窄,但保留了其拥有的所有层类型,且其分词器(tokenizer)和处理器(processor)文件保持不变。它只需发布一次即可重复使用。我们在廉价的 CPU runner 上对其运行“快速集成测试”。在我们的 CPU 研究 中,实验性的 UMT5 fixture 权重仅为 66 MB;而原始检查点大小为 1,227 MB。
这也涵盖了超大模型:有些模型无法放入我们的标准 GPU runner 中,但它们的 fixture 可以在 CPU 上运行。
模型集成人员已经在构建小型测试模型(如 Transformers 的 tiny-random-* 检查点)。我们希望有一套通用方案,以及超越“仅加载模型并运行前向传播(forward pass)”的检查手段。因为 UMT5 的那个 bug 完全能正常通过前向传播。
Fixture 不会取代完整的集成测试,但在 PR 阶段,它们让我们有机会在 bug 合入 main 分支之前捕获它们。
介绍模型集成契约(Model Integration Contracts)
transformers-mic 是一个用于打包这些测试的提议标准。一个模型集成契约(Model Integration Contract,简称 MIC)包含三个部分:
- fixture:上文描述的缩减模型,一次性发布并固定版本
- 使用路径(usage path):一个可运行的 Markdown 示例,展示人们对模型的常见操作,例如生成文本或运行一个训练步(training step)
- 基准数据(baselines):运行该示例时记录并经人工审查的输出结果
如果在 fixture 上运行该使用路径仍能产生相同的基准数据,则表明该契约成立。
一份契约涵盖一种架构和一个使用路径,而不是单个检查点:兼容的检查点可以共享一个 fixture,同时各自保留其预期的结果。我们将它们发布在 huggingface-mic 中。
例如,SmolLM 契约使用诸如“The capital of France is”之类的提示词(prompt)进行生成,并将其 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))它还会对比训练损失(training loss),检查梯度是否有限,并验证优化器步骤(optimizer step)是否改变了权重。完整内容请参阅 usage.md。
Hub 上的 fleet 数据集 将每个 MIC 固定到一个冻结的版本(revision),并记录了用于记录其基准数据时的依赖包版本。每次 CI 运行都会记录其使用的 fleet 版本,以便后续复现。
在 PR 中,我们会根据补丁修改的文件来筛选要运行的 MIC。
UMT5 回归问题
我们在 Transformers 过去五个月的代码提交中重放了冻结的 MIC。这个小型的 UMT5 fixture 从 2026 年 7 月 30 日引入该回归问题起就一直报错,直到