Hugging Face 提出 transformers-mic 模型整合測試契約標準

2026 年 7 月 30 日，Transformers 為 T5 啟用了 PyTorch 的 scaled dot-product attention (SDPA)。副作用是，UMT5 的解碼器可以關注未來的詞元。訓練期間，它可以偷看本應由它預測的答案。沒有任何程式崩潰，這個錯誤在 main 中留了近兩個月。

後來我們重播那些提交時，一個在 CPU 上執行的小型 UMT5 模型，每次都偵測到問題。本文介紹這個模型，以及圍繞它建立的測試。

為何錯誤會進入 main

Transformers 支援超過 750 種模型類型，測試套件規模龐大：main 上有 88,000 多項 CPU 測試，另有 200,000 多項 GPU 測試在每日測試中執行。模型測試只是其中一部分：我們亦會測試管線、訓練、分散式執行、量化及注意力核心。

整合測試會載入真實檢查點，並在真實硬件上測試模型的 API。若每個 PR 都執行全部測試，便要讓大量 GPU 全天候運作，並不實際。等到排程測試發現回歸問題時，相關改動可能已經進入 main。

我們的做法是縮小模型。我們建立一個測試模型：根據真實檢查點的設定建立的小型模型，層數較少、每層較窄，但仍包含模型原有的每一類層；其分詞器和處理器檔案則保持不變。測試模型只發布一次，之後重複使用。我們在低成本的 CPU 執行器上，針對它執行「快速整合測試」。在我們的 CPU 研究中，實驗用 UMT5 測試模型的權重大小為 66 MB；來源檢查點則為 1,227 MB。

這也涵蓋超大型模型：有些模型無法在我們的標準 GPU 執行器上執行，但其測試模型可在 CPU 上執行。

模型整合人員本來就會建立小型測試模型（Transformers 的 tiny-random-* 檢查點）。我們希望訂出一套通用方法，並加入不只載入模型和執行前向傳播的檢查。UMT5 的錯誤即使只執行前向傳播，也完全不會被發現。

測試模型不會取代完整整合測試，但在 PR 中，它們讓我們有機會在錯誤進入 main 前將其捕捉。

推出 Model Integration Contracts

transformers-mic 是一項用於封裝這些測試的建議標準。Model Integration Contract (MIC) 包含三個部分：

一個測試模型：如上所述縮小後的模型，只發布一次並鎖定版本
一條使用流程：可執行的 Markdown 範例，展示人們如何使用模型，例如生成文字或執行訓練步驟
基準結果：執行該範例時記錄的輸出，並經人工審核

若在測試模型上執行使用流程，仍能產生基準結果，這份合約便有效。

一份合約涵蓋一種架構和一條使用流程，而非單一檢查點：相容的檢查點可以共用一個測試模型，而每個檢查點仍保留各自的預期結果。我們會在 huggingface-mic 發布這些內容。

例如，SmolLM 合約會根據「法國的首都是」等提示詞生成內容，並將其詞元 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))

它亦會比較訓練損失、檢查梯度是否為有限值，並確認最佳化器步驟會改變權重。請參閲完整的 usage.md。

Hub 上的 fleet 數據集會將每份 MIC 固定至一個凍結版本，並記錄用於產生其基準結果的套件版本。每次 CI 執行都會記錄所用的 fleet 版本，以便日後重現。

在 PR 中，我們會根據修補程式所修改的檔案挑選 MIC。

UMT5 回歸問題

我們以過去五個月 Transformers 的提交版本，重播已凍結的 MIC。小型 UMT5 測試模型從2026 年 7 月 30 日引入該回歸問題起，一直能偵測到問題，直至9 月 28 日修正為止。標籤對數機率與已審核基準的差異為 1.22，訓練損失則相差約 0.20。

有一個細節至關重要：測試契約使用 SDPA，也就是預設注意力路徑。只執行 eager attention 變體會漏掉這個錯誤。測試模型只有經過與真實檢查點相同的程式碼路徑，才有用。

隨後，我們在 Transformers 的 CI 驗證分支上還原了該修正。檢查結果出現相同差異，而所選 T5 測試契約的執行步驟在 CPU 上需時 13.4 秒，不包括設定所需時間。

重播結果和CI 示範列有量度結果及重現細節。

模型縮小方法

最初的做法很簡單：縮小維度並減少層數。但這不足以應付混合架構。如果保留下來的兩層都採用滑動注意力，而全注意力層全被刪掉，那保留兩層也沒有用。

現時的做法包含四個步驟：

縮小設定。從真實檢查點開始，縮小隱藏層大小、注意力頭數及網絡深度。保留不同類型的層，包括混合滑動注意力與全注意力，或密集層與 MoE 層的架構。部分架構需要額外規則，確保其元件保持相容。我們也會參考模型本身的 Transformers 測試：test_modeling_<model>.py 中的 ModelTester 已經手動選用較小的設定，因此，對於通用規則無法按名稱識別的寬度，我們會採用該測試所用的尺寸。
保持前處理不變。保留詞彙表、特殊標記及輸入維度，並逐個位元組複製 tokenizer 和 processor 檔案。載入及前處理都是我們要測試的部分。
建立並驗證權重。先以固定隨機種子產生隨機權重，再更改輸入，檢查模型是否有反應。如果沒有，就嘗試使用測試契約中的一小批示例訓練模型。重新載入已儲存的模型，並檢查輸出、損失及梯度是否均為有限值。捨棄未通過驗證的建置。
凍結並記錄。儲存已接納的權重，並在已確認正常的 Transformers 建置上量度可重複的輸出。審核各支援平台及精度的基準，然後發佈固定版本快照。CI 會重用該快照，不會在每個 PR 都重新建置測試模型。

我們也會保留原有的權重檔案格式。否則，就會略過用戶載入真實檢查點時執行的轉換程式碼。完整做法載有更多細節。

Llama 4 Scout 縮小報告展示了大型模型的縮小效果。參數數量由 108.6 billion 縮減至 44.7 million。視覺堆疊由 34 層縮至 2 層，語言堆疊則由 48 層縮至 4 層，同時保留經檢查的層類型及 MoE 路由方式。

使用 Agent 建立 MIC

我們的 CLI tmic會建立測試契約並建置測試模型。針對新模型，LLM 會草擬使用程式碼及清單，而 CPU 和 GPU 執行則會量度候選基準。LLM 負責草擬，不負責核准。預期結果有所變更時，必須經人工審核。

如要在你的電腦上試用，請以你的來源檢查點取代 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 ''

它會草擬合約、在你的電腦上建立測試模型並記錄基準資料，每個步驟都會請你審核，並在上載任何內容前停止。建立新模型時，草稿會透過 Inference Providers 由 LLM 產生，費用由你的帳戶支付（--bill-to ''）。CLI 文件列出各個步驟。

我們使用 Agent，在不同模型系列中建立 MIC。遇到邊界情況時，在模型專家的協助下，我們會修正整套設定流程，而非只修正單一測試模型。已發布的模型及尚未涵蓋的部分，列於覆蓋範圍 Space。

隨機權重與過度擬合

使用隨機權重時，我們的 Whisper 測試模型幾乎不會因音訊變化而有反應。它雖然能運行，但因此不適合用來測試音訊處理路徑。

因此，我們用幾種音調配上「紅色」和「綠色」等詞語來訓練它。我們不是要教它語音識別，只是讓音訊變化能在輸出中顯現。在權重初始化研究中，使用隨機權重的 Whisper 測試模型捕捉到 24 個注入故障中的 18 個；過度擬合的測試模型則捕捉到全部 24 個。

因此，我們有兩種建立權重的方法：

以隨機權重和固定種子開始。
使用少量範例進行過度擬合，例如「法國的首都是」 => 「巴黎」。

Whisper 的結果不足以判定哪種方法較好。那些都是合成故障，而我們尚未發現只有過度擬合版本才能捕捉到的真實回歸問題。兩個版本都未能捕捉到一個輔助解碼錯誤，而真實的 Whisper 檢查點則暴露出這個錯誤。

因此，隨機權重通過檢查時，我們便保留隨機權重；需要更高靈敏度或可讀答案時，則採用過度擬合方式。訓練只需數秒，但這多了一個可能無法收斂的步驟，也多了一項需要維護的內容。比較頁列出兩種方法的結果。

尚待解答的問題

截至 2026 年 11 月 1 日，Transformers CI 中的 MIC 工作會回報失敗，但不會阻擋 PR。是否應該阻擋 PR，取決於一些我們尚未量度的事項：

它在 PR 中能捕捉多少真實錯誤，而不只是重播中的錯誤？
它多常令我們追查誤報？
審核基準資料需要多少工夫？

我們也不知道有多少錯誤（例如 Whisper 的輔助解碼錯誤）只會在使用真實權重時出現，也不知道過度擬合能否捕捉到隨機權重無法發現的真實錯誤。

目前的覆蓋範圍仍不完整，涵蓋的模型系列和用戶使用的 API 仍有限。當回歸問題漏網時，我們可以加入缺少的使用路徑，並在出錯及已修正的版本上重播。在確認現有測試所涵蓋的範圍前，我們會保留這些測試。

最後，我們希望將 Hub 上的原始模型頁面連結至相應的 MIC，讓使用某個檢查點的開發者或 Agent，可以從一個已使用該檢查點及其環境測試、並附有預期輸出的範例開始。

想幫忙嗎？從覆蓋範圍 Space挑選一個尚未涵蓋的模型，試用tmic 工作流程，並提交一條使用路徑，或審核生成的合約。