Model Integration Contracts：模型“能跑”之后，怎样证明它还算对了
Hugging Face 在 2026 年 11 月 3 日公开了 Model Integration Contracts（MIC）：给模型集成配一份可执行的行为契约，用一个能在 CPU 上运行的缩小模型，复现用户真正会调用的生成或训练路径，再把输出与人工审核过的基线比较。
它要解决的不是“模型文件能否加载”，而是更难发现的一类问题：程序没有报错，输出形状也没变，但语义已经悄悄错了。官方披露的 UMT5 回归就是例子。Transformers 在 7 月 30 日为 T5 启用 PyTorch SDPA 后，UMT5 解码器在训练时可能看到未来 token；调用照常返回，普通前向测试也能通过，这个问题却在主分支停留了近两个月。
MIC 仍处于提案和 Alpha 阶段，但它把“模型兼容性测试”拆成了可以复用的三件东西，值得做模型接入、推理框架或 AI 基础设施的人现在就理解。
为什么一次 forward() 不够
常见的模型冒烟测试大致是：构造一个很小的配置，随机生成输入，调用模型，然后确认输出不是 NaN。它能发现导入失败、维度不匹配和明显的数值崩溃，却很难回答以下问题：
- 默认注意力实现是否仍遵守因果掩码；
generate()的 token 是否改变；- tokenizer、processor 与模型是否仍按同一套约定工作；
- 训练损失、梯度和一次优化器更新是否仍符合预期；
- eager、SDPA、不同精度和不同平台的行为是否被混在一起比较。
完整检查点能回答更多问题，但下载大模型、占用 GPU，再为每个 Pull Request 跑一遍，成本通常不可接受。MIC 的思路不是二选一，而是在普通单元测试与完整检查点测试之间增加一层快速行为测试。
可以把它想成飞机的风洞模型：风洞模型不是飞机，不能证明真机一定安全；但它保留了这次测试真正关心的机翼、气流和控制面关系，因此比“确认零件能拼起来”更早暴露行为变化。
一份契约由三部分组成
1. Fixture：缩小尺寸，不随意删掉结构
MIC 从真实检查点的配置出发，减少隐藏维度、注意力头数和层数，但要保留不同类型的层。例如一个模型同时包含滑动窗口注意力与全局注意力，缩小后不能碰巧只剩前者；混合专家模型也要保留路由方式。tokenizer 和 processor 文件则原样复制，因为预处理本来就是集成的一部分。
权重可以按固定种子随机初始化；如果随机权重对输入变化不敏感，再在少量样本上过拟合，让测试路径产生可辨别的信号。构建完成后，fixture 被固定并发布，CI 直接复用，而不是每次重新随机生成。
官方给出的 UMT5 实验里，fixture 权重为 66 MB，源检查点为 1,227 MB。另一个更极端的缩小报告把 Llama 4 Scout 从 1086 亿参数压到 4470 万参数。数字说明的是测试载荷缩小，不代表模型能力被等比例保留。
2. Usage path：运行用户真的会写的代码
契约主体不是私有测试钩子，而是可执行 Markdown 中的公开 API 示例。SmolLM 契约会批量 tokenize 四个提示、调用 generate()，然后执行一次带标签的训练步骤。它记录生成 token、部分 logits、loss、指定参数的梯度是否非零且有限，以及优化器是否真的改动权重。
这一步很重要：UMT5 的问题只在默认 SDPA 路径出现，仅跑 eager 变体会漏掉。测试模型再精巧，如果没有调用出错的那条用户路径，仍然什么也抓不到。
3. Baseline：行为变化必须由人解释
在已知正确的 Transformers 版本上运行 usage path，按目标、平台和精度分别记录基线。离散 token 可以精确比较，logits 与 loss 则按审核过的容差比较。依赖版本、契约修订、fixture 修订和基线都被固定，避免今天与昨天实际上使用了不同环境。
工具可以生成候选结果，但不能自行批准新基线。否则一个回归只要自动刷新快照，就会把错误变成新的“正确答案”。行为确实需要改变时，应由维护者在代码评审里解释并接受差异。
它实际抓到了什么，也漏掉了什么
Hugging Face 把冻结的契约回放到五个月的 Transformers 提交历史上。UMT5 fixture 从回归引入一直报警到修复；把修复从 CI 证明分支撤销后，选中的 T5 契约也以相同差异失败，runner 在 CPU 上用时 13.4 秒，不含环境准备。
但早期契约面对五个已知回归时，只抓到一个，漏掉四个；原因不是 fixture 太小，而是 usage path 根本没有调用对应功能。补上缺失调用后，五个才全部被覆盖，并额外发现一个仍存在的 Whisper 问题。这组结果揭示了 MIC 最重要的边界：它能守住已经写进契约的行为，不能自动发现所有可能用法。
权重选择也没有万能答案。官方对 Whisper 注入 24 个合成故障时，随机权重 fixture 抓到 18 个，过拟合版本抓到 24 个；但团队尚未发现一个真实回归只能由过拟合版本捕获，而且两者都漏过一个需要真实 Whisper 检查点才能复现的 assisted decoding 问题。
因此 fixture 通过只是一条快速回归信号，不等于真实检查点通过。完整模型仍应在合并后、夜间任务和发布前运行。目前 Transformers 中的 MIC 任务也只报告失败，并不阻断 PR。
本地复现：先验证 runner，再跑一个轻量 fixture
下面固定到我检查时的官方仓库提交。它先安装声明的运行时和 doc-builder，再运行仓库自带的 SmolLM 1.7B 缩小 fixture；--local-contracts 与 --local-fixtures 表示使用当前提交中的契约和模型，--no-baseline 表示只验证输出结构、数值有效性、梯度和参数更新，不把不同依赖版本下的数值误当成官方基线复现。
git clone https://github.com/huggingface/transformers-mic.git
cd transformers-mic
git checkout 513ffe5db99a9db96b0a2075b9f01c819a0ad6ce
uv sync --extra dev --extra runtime
uv pip install \
'hf-doc-builder @ git+https://github.com/huggingface/doc-builder.git@6175bc655f1c949e6048b9277a90bd98eb8a4e6e'
uv run pytest -m 'not requires_runtime' -q
uv run python example/run.py \
--framework transformers \
--contract SmolLM \
--target mic-SmolLM-1.7B-slim \
--local-fixtures \
--local-contracts \
--no-baseline2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
我在 Linux x86-64、Python 3.12.14、Transformers 5.20.1、PyTorch 2.14.1 上实际执行：非运行时测试为 314 passed, 4 skipped, 23 deselected；SmolLM fixture 的生成与单步训练契约状态为 pass，契约进程报告 0.56 秒，完整 runner 约 12.5 秒。
这个环境与仓库固定的 Python 3.11、PyTorch 2.11.0 等版本不同，所以结果只能证明“当前环境下契约完整执行且自检通过”，不能声称数值与官方审核基线一致。要做严格回归比较，应使用 fleet lock 固定的依赖、契约、fixture 和对应平台基线，去掉 --no-baseline 后再运行。
如果要为自己的模型创建 MIC，官方入口是 tmic run org/model --local-only --fixtures-only --no-history --bill-to ''。它会生成候选 usage path、构建 fixture 并要求逐步审核；候选代码会被实际执行，不是沙箱，因此应先像审查普通依赖脚本一样阅读它，而不是因为由 Agent 生成就直接批准。
与现有测试怎样分工
MIC 更适合覆盖稳定、重要且能在小模型上重现的公开用法，例如默认生成、一次训练步骤、处理器输入、不同注意力实现或关键多模态路径。它不应该替代：
- 纯函数和边界条件的快速单元测试；
- 大模型权重、量化、分布式和真实硬件上的完整集成测试；
- 质量评测，因为固定样本的行为一致不等于模型效果更好；
- 安全与鲁棒性评测，因为基线只描述被选中的输入和输出；
- 新功能测试，因为契约不会替开发者定义预期行为。
实际落地时，可以先从历史回归和高频用户路径反推契约，而不是追求“每个模型都有一份”。每次漏检都要问两个问题：fixture 是否保留了触发结构，usage path 是否真的调用了出错功能。基线变化则必须单独审查，尤其不能用放宽容差掩盖原因不明的漂移。
MIC 最有价值的地方，不是把一个巨大模型压成几十 MB，而是把三件经常分离的东西重新绑在一起：文档中的真实调用、CI 中可承受的执行载荷，以及人类认可的行为基线。它让模型集成从“导入成功就算兼容”迈向“关键行为没有静默改变”，同时也诚实保留了小模型测试无法替代真模型验证的边界。
💬 评论