Transformers 模型整合合約：Hugging Face 提升模型測試效率與品質的新標準

2026 年 7 月 30 日，Transformers 函式庫為 T5 模型啟用了 PyTorch 的縮放點積注意力（SDPA）機制。然而，這項改動意外導致 UMT5 解碼器能夠在訓練期間預覽未來的 token，也就是說，它能偷看到本應預測的答案。儘管沒有導致系統崩潰，這個錯誤卻在主程式碼中潛伏了將近兩個月。

當我們後來重播這些提交紀錄時，一個在 CPU 上運行的小型 UMT5 模型在每一次重播中都標記出了這個錯誤。這篇文章將會介紹這個模型以及圍繞它建立的測試。

Transformers 函式庫支援超過 750 種模型類型，其測試套件規模龐大：主程式碼中有超過 88,000 個 CPU 測試，加上每日運行超過 200,000 個 GPU 測試。模型測試只是其中一部分，我們還會測試 pipeline、訓練、分散式執行、量化和注意力核心。

整合測試會載入真實的檢查點，並在實際硬體上執行模型的 API。在每個拉取請求（PR）上運行所有這些測試，意味著需要長時間佔用大量 GPU，這並不實際。等到排程運行發現問題時，錯誤可能已經進入主程式碼了。

我們的解決方案是縮小模型。我們建立了一個「fixture」，這是一個由真實檢查點配置構成的小型模型，它擁有較少且較窄的層，但保留了所有類型的層，同時其分詞器（tokenizer）和處理器（processor）檔案保持不變。這個 fixture 一旦發布後就會被重複使用。

我們在廉價的 CPU 執行器上，針對這些 fixture 運行「快速整合測試」。根據我們的 CPU 研究，實驗性的 UMT5 fixture 使用了 66 MB 的權重，而原始檢查點則高達 1,227 MB。這也涵蓋了非常大型的模型，有些模型無法在我們的標準 GPU 執行器上運行，但它們的 fixture 可以在 CPU 上運行。

模型整合者已經會建立微型測試模型（Transformers 的 tiny-random-* 檢查點）。我們希望有一個通用的方法，並且能進行超越載入模型和執行前向傳播（forward pass）的檢查。UMT5 的錯誤在單純的前向傳播測試中是無法被發現的。Fixture 無法取代完整的整合測試，但在拉取請求階段，它們讓我們有機會在錯誤進入主程式碼之前就將其捕獲。

transformers-mic 是一個提議中的標準，用於打包這些測試。一個模型整合合約（Model Integration Contract, MIC）包含三個部分：一個 fixture，即上述縮小版模型，一旦發布即固定；一個使用路徑，即一個可執行的 Markdown 範例，展示人們如何使用該模型，例如生成文本或執行訓練步驟；以及基準線，即運行該範例時記錄的輸出，並經過人工審查。

如果對 fixture 執行使用路徑後仍能產生基準線，則該合約成立。一個合約涵蓋一種架構和一個使用路徑，而非單一檢查點：相容的檢查點可以共用一個 fixture，同時各自保留預期的結果。我們將這些合約發布在 huggingface-mic 上。

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

它還會比較訓練損失，檢查梯度是否有限，並驗證優化器步驟是否改變了權重。完整的 usage.md 文件提供了更多細節。Hub 上的 fleet dataset 將每個 MIC 釘選到一個凍結的版本，同時也記錄了用於基準線的套件版本。每個 CI 運行都會記錄其使用的 fleet 版本，以便日後重現。在拉取請求上，我們會根據補丁更改的文件來選擇 MIC。

我們在 Transformers 函式庫五個月的提交紀錄上重播了凍結的 MIC。小型 UMT5 fixture 從 2026 年 7 月 30 日引入錯誤到 9 月 28 日修復期間，一直標記出這個錯誤。標籤對數機率（log-probabilities）與審查過的基準線相差 1.22，訓練損失約相差 0.20。

其中一個細節很重要：該合約使用了 SDPA，即預設的注意力路徑。如果只運行 eager attention 變體，就會錯過這個錯誤。Fixture 只有在它與真實檢查點經過相同的程式碼路徑時才能發揮作用。隨後，我們在 Transformers 的 CI 中，於一個驗證分支上還原了修復。

檢查失敗並顯示相同的差異，選定的 T5 合約執行器步驟在 CPU 上耗時 13.4 秒，不包括設定時間。重播結果和 CI 演示提供了測量數據和重現細節。

最初的縮小方法很簡單：減少維度並保留較少的層。但這對於混合架構來說還不夠。如果兩個層都使用滑動注意力（sliding attention），而全注意力（full-attention）層消失了，那麼保留兩個層就沒有意義了。現在的縮小方法包含四個步驟。

首先，縮小配置。從真實檢查點開始，減少隱藏層大小、注意力頭數量和深度。保留不同類型的層，包括滑動注意力與全注意力、或密集層與 MoE 層的混合。某些架構需要額外規則來保持其組件的相容性。我們也會參考模型本身的 Transformers 測試：test_modeling_<model>.py 中的 ModelTester 已經手動選擇了一個小型配置，因此對於我們通用規則中未知的任何寬度，我們都會採用其大小。

其次，保持預處理不變。保留詞彙表、特殊 token 和輸入維度，並逐字複製分詞器和處理器檔案。載入和預處理是我們想要測試的一部分。

第三，建立並驗證權重。嘗試使用帶有種子的隨機權重，並更改輸入以檢查模型是否響應。如果沒有響應，則嘗試使用合約中的一小批範例進行訓練。重新載入保存的模型，並檢查輸出、損失和梯度是否有限。拒絕失敗的建構。

第四，凍結並記錄。保存已接受的權重，並在已知良好的 Transformers 建構版本上測量可重複的輸出。審查每個支援平台和精度的基準線，然後發布一個釘選的快照。CI 會重複使用它，不會為每個拉取請求重新建構 fixture。

我們還保留了原始權重檔案格式。否則，我們將會跳過用戶載入真實檢查點時運行的轉換程式碼。完整的縮小方法有更多細節。Llama 4 Scout 的縮小報告展示了這在大模型上的效果。1086 億個參數變成了 4470 萬個。視覺堆疊從 34 層變為 2 層，語言堆疊從 48 層變為 4 層，同時保留了檢查的層類型和 MoE 路由風格。

我們的命令列介面 tmic 用於建立合約和建構 fixture。對於一個新模型，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 ''。

它會在您的機器上草擬合約、建構 fixture 並記錄其基準線，要求您審查每個步驟，並在上傳任何內容之前停止。對於新模型，草稿來自透過 Inference Providers 的 LLM，費用將計入您自己的帳戶（--bill-to ''）。

CLI 文件涵蓋了各個步驟。我們使用代理來跨模型家族建立 MIC。當它們遇到邊緣情況時，我們會在模型專家的幫助下修復方法本身，而不是修復單個 fixture。已發布的模型和剩餘的差距可在 coverage space 中查看。

使用隨機權重時，我們的 Whisper fixture 對音訊的變化幾乎沒有反應。它雖然能運行，但這使得它在測試音訊路徑方面表現不佳。因此，我們用一些音調搭配「紅色」和「綠色」等詞語來訓練它。我們並不是在教它語音識別，只是讓音訊變化在其輸出中可見。

在我們的權重初始化研究中，隨機 Whisper fixture 捕獲了 24 個注入錯誤中的 18 個。而過度擬合（overfit）的 fixture 則捕獲了所有 24 個。這給了我們兩種建立權重的方法：使用固定種子從隨機權重開始，或者在幾個範例上進行過度擬合，例如「法國的首都是」=>「巴黎」。

Whisper 的結果並不能確定哪種方法更好。這些是合成錯誤，我們尚未發現只有過度擬合版本才能捕獲的真實回歸錯誤。兩種版本都錯過了一個輔助解碼（assisted-decoding）錯誤，這個錯誤只有真實的 Whisper 檢查點才能暴露出來。

因此，當隨機權重通過檢查時，我們保留隨機權重；當我們需要更好的敏感度或可讀的答案時，則進行過度擬合。訓練只需幾秒鐘，但這是一個可能無法收斂的額外步驟，也是一個需要維護的額外項目。比較結果中包含了兩者的結果。

截至 2026 年 11 月 1 日，Transformers CI 中的 MIC 任務會報告失敗，但不會阻止拉取請求。它是否應該阻止，取決於我們尚未測量的因素：它在拉取請求上捕獲了多少真實錯誤，而不僅僅是重播中；它多久會發出一次錯誤警報；以及基準線審查需要多少工作量。

我們也不知道有多少錯誤，例如 Whisper 的輔助解碼錯誤，只有在真實權重下才會出現，或者過度擬合是否能捕獲隨機權重錯過的真實錯誤。跨模型家族和人們使用的 API，覆蓋率仍然不完整。當回歸錯誤發生時，我們可以添加缺失的使用路徑，並在錯誤和修復版本上重播。我們將保留現有測試，直到其覆蓋範圍得到解釋。

最後，我們希望將原始的 Hub 模型頁面連結到其 MIC，這樣開發人員或使用檢查點的代理就可以從一個經過該檢查點、其環境和預期輸出測試的範例開始。想要提供幫助嗎？從 coverage space 中選擇一個未被覆蓋的模型，嘗試 tmic 工作流程，並貢獻一個使用路徑或審查一個生成的合約。