Hugging Face 提出模型集成契约：用小模型夹具在 PR 阶段拦截回归

11 月 3 日，Hugging Face 博客刊出由 Tarek Ziadé 撰写的文章，提出“模型集成契约”（Model Integration Contracts，简称 MIC）方案：不再在每个 PR 上加载真实权重跑完整集成测试，而是用一份被冻结的小模型夹具、一段可运行的用法示例和一组人工审核过的基线输出来判断回归。配套的 transformers-mic 包、huggingface-mic 契约集合以及能自动起草契约、构建夹具的 tmic 命令行工具一并公开。

动机来自规模压力。Transformers 目前支持 750 多种模型类型，主干上有 8.8 万多个 CPU 测试，每日任务还要跑 20 多万个 GPU 测试，覆盖流水线、训练、分布式执行、量化和注意力内核。若每个 PR 都用真实硬件加载真实 checkpoint，等于让一大批 GPU 全天候待命，因此集成测试只能定时执行；等到定时任务发现问题，缺陷往往已经进入主干。

文章的核心案例是一个 T5/UMT5 缺陷。2026 年 7 月 30 日，Transformers 为 T5 启用 PyTorch 的缩放点积注意力（SDPA），副作用是 UMT5 的解码器可以看到未来的 token，训练时等于偷看它本该预测的答案。程序没有崩溃，缺陷在主干里待了将近两个月，直到 9 月 28 日才被修复。团队用一个小型 UMT5 夹具回放五个月的提交，在每一次提交上都命中该回归：标签对数概率与审核基线相差 1.22，训练损失相差约 0.20。

一个细节决定了这项检查是否有效：契约走的是默认的 SDPA 注意力路径，只跑 eager 变体会完全漏掉这个 bug。作者由此强调，夹具只有和真实 checkpoint 走同一段代码才有意义。UMT5 夹具的权重为 66MB，源 checkpoint 为 1,227MB；被选中的 T5 契约在 CPU 上跑完 runner 步骤耗时 13.4 秒（不含准备时间）。

夹具的构建有一套四步配方：先缩小配置，但保留每一种层类型，包括滑动注意力与全注意力、稠密层与 MoE 层的混合；分词器和处理器文件逐字节保留；然后构建并验证权重，若固定种子的随机权重对输入没有反应，就用契约自带的小批量样本短暂训练；最后冻结结果，并为每个支持的平台和精度记录基线。公开的 Llama 4 Scout 收缩报告展示了这一方法在超大规模模型上的效果：1086 亿参数被压到 4470 万，视觉栈从 34 层减到 2 层，语言栈从 48 层减到 4 层。

一份契约由三部分组成：一个被钉住版本的夹具、一段可运行的 Markdown 用法路径（例如生成文本或跑一步训练），以及运行该示例后记录并由人工审核的输出。契约覆盖的是某种架构加某条用法路径，而不是单个 checkpoint，因此兼容的 checkpoint 可以共享夹具，但各自保留期望结果。以 SmolLM 契约为��，它用“The capital of France is”之类的提示生成文本，把 token ID 与记录答案比对，同时检查训练损失、梯度是否为有限值，以及优化器更新一步后权重是否改变。Hub 上的 fleet 数据集把每份契约固定到冻结版本，并记录生成基线时使用的包版本。

权重该怎么造，仍是开放问题。随机权重下的 Whisper 夹具对音频变化几乎没有反应，团队于是用几段音调配对“red”“green”等词做轻微训练。在故障注入实验中，随机权重夹具抓住 24 个注入故障中的 18 个，过拟合夹具全部抓住；但作者说明，目前还没有发现只有过拟合版本才能抓到的真实回归，而两个版本都漏掉了一个真实 Whisper checkpoint 才能暴露的 assisted-decoding 缺陷。

截至 2026 年 11 月 1 日，Transformers CI 中的 MIC 任务只报告失败，不阻断 PR。是否应当阻断，取决于几个尚未测量的变量：它在真实 PR 上而非回放中能抓到多少 bug、误报频率有多高、基线审核要花多少人力。模型家族和 API 的覆盖率也仍不完整；团队还希望把 Hub 上的原始模型页与对应契约关联起来，让开发者或 agent 从某个 checkpoint 出发时，能直接看到一个在该 checkpoint、该环境和该期望输出上验证过的示例。把测试本身变成可冻结、可复用的契约，等于为 750 多个模型集成的合并流程加了一道能在 CPU 上跑的门禁。