目次

Transformersのモデル統合契約(Model Integration Contracts、MIC)は、小規模な固定モデルを使い、コードの変更が実際の利用経路を壊していないかを確認します。プルリクエストに有用な回帰チェックを組み込めますが、完全なチェックポイントを使うテストを補完するものであり、人によるレビュー済みのベースラインも必要です。

要点#

  • MICは、小規模なモデルフィクスチャ、実行可能な使用例、レビュー済みの期待出力をまとめたものです。
  • フィクスチャは、関連するアーキテクチャと前処理を維持しながら、チェックの実行コストを抑えます。
  • 実験的なUMT5フィクスチャは、CPU上で66 MBの重みを使い、実際のアテンションの回帰バグを検出しました。
  • カバレッジはテストするコード経路に依存し、実際のチェックポイントの重みが必要なバグもあります。

契約で何を確認するか#

MICは、モデルを利用したときに、期待どおりに動作し続けるかをテストします。読み込みに成功し、順伝播が完了するだけでは不十分です。モデルはエラーなく実行できても、誤った結果を出すことがあります。

各契約は、バージョンを固定したフィクスチャ、Markdownで記述された実行可能な利用経路、記録済みのベースラインを組み合わせます。テキスト生成の契約では、生成されたトークンIDの比較、学習損失と勾配が有限値であることの確認、オプティマイザの更新ステップで重みが変化することの検証などを行います。ベースラインには人によるレビューが必要です。出力を記録しただけでは、その正しさは保証されません。

契約は、アーキテクチャと利用経路を対象とします。互換性のあるチェックポイントは、それぞれの期待結果を保持しながらフィクスチャを共有できます。fleetデータセットは契約のリビジョンを固定し、ベースラインの確立に使ったパッケージのバージョンを記録します。各CI実行も、再現できるようにfleetのリビジョンを記録します。

実行経路が重要な理由#

報告された中で最も有力な例は、2026年7月30日、TransformersがT5でPyTorchのスケールド内積アテンション(SDPA)を有効にした際に生じたUMT5の回帰バグです。これにより、UMT5のデコーダは学習中に未来のトークンを参照できるようになりました。クラッシュは起きませんでしたが、モデルは本来予測すべき情報にアクセスできていました。

Transformersのコミット履歴を再実行したところ、小規模なUMT5フィクスチャは、この回帰バグの導入時から9月28日の修正まで異常を検出しました。ラベルの対数確率はレビュー済みのベースラインと1.22、学習損失は約0.20異なっていました。この実験的なフィクスチャの重みは66 MBで、元のチェックポイントの1,227 MBを大きく下回りました。

契約は、デフォルトのアテンション経路であるSDPAを通じてバグを検出しました。eagerアテンションだけをテストした場合は見逃しました。メンテナーが検証用ブランチで修正を取り消すと、選択したT5の契約は再び失敗しました。その実行ステップは、セットアップを除き、CPUで13.4秒かかりました。

フィクスチャの代表性を保つ方法#

モデルを縮小するには、その実装を実際に動かす構成要素を維持する必要があります。レイヤーの種類を確認せずに深さを減らすと、テストで対象とすべき挙動そのものを取り除いてしまう可能性があります。

フィクスチャの作成手順は、次の4段階です。

1. 次元を削減する。 隠れ層のサイズ、アテンションヘッド数、深さを縮小しつつ、スライディングアテンションとフルアテンション、密なレイヤーと混合エキスパート層など、関連するレイヤーの種類を維持します。 2. 前処理を維持する。 語彙、特殊トークン、入力次元、トークナイザーとプロセッサのファイルを変更せずに保持します。 3. 重みを検証する。 入力を変えると挙動が変わることを確認し、保存したモデルを再読み込みして、出力、損失、勾配が有限値であることを検証します。 4. 結果を固定する。 対応するプラットフォームと数値精度で再現可能なベースラインをレビューし、CIで再利用できるように固定したスナップショットを公開します。

この手順では、読み込みテストで関連する変換コードが実行されるよう、元の重みファイル形式も維持します。報告されたLlama 4 Scoutのフィクスチャでは、検証対象のレイヤーの種類とMoEのルーティング方式を保ちながら、パラメータ数を1,086億から4,470万に削減しました。

MICの作成とレビュー#

tmic CLIは、契約の草案を作成し、フィクスチャを構築して、ベースライン候補を測定します。新しいモデルでは、LLMがInference Providersを通じて使用コードとマニフェストの草案を作成します。期待値は人が承認します。

ランタイムとドキュメント用の依存パッケージをインストールし、Hugging Faceで認証してから、自分のチェックポイントを指定してローカルワークフローを実行します。

snippet.txt
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 ''

org/modelを元のチェックポイントに置き換えてください。このワークフローは各段階でレビューを求め、アップロード前に停止します。LLMへのリクエストは自分のアカウントに課金されます。出力を受け入れる前に、使用例が意味のあるユーザー操作と意図したアテンションバックエンドを実際に動かしているかを確認してください。

カバレッジの限界#

ランダムな重みは保守コストを抑えられますが、テストの検出力が弱くなることがあります。ランダムなWhisperフィクスチャは、音声の変化にほとんど反応しませんでした。いくつかの音と単語の組み合わせで学習させると、その入力経路の挙動を観測しやすくなりました。ある研究では、過学習させたフィクスチャは注入した24件の不具合をすべて検出したのに対し、ランダムなフィクスチャは18件でした。

この結果だけでは、実際の回帰バグに対するカバレッジが向上したとはいえません。どちらも、実際のWhisperチェックポイントでは発覚した支援付きデコーディングのバグを見逃しました。完全な統合テストは維持し、ランダムな重みでは感度が足りない場合に過学習を活用してください。

2026年11月1日時点で、TransformersのMIC CIジョブは失敗を報告しても、プルリクエストをブロックしていませんでした。ブロックを正当化するには、実際の検出率、誤検知、ベースラインのレビュー工数を引き続き測定する必要があります。

次のステップ#

プロジェクトのカバレッジSpaceに掲載された未対応モデルを1つ選び、ローカルのtmicワークフローを実行してください。そのうえで、利用経路がユーザーの依存するバックエンドと挙動を実際に動かしているかをレビューしてください。

出典: https://huggingface.co/blog/transformers-mic

目次