Fusion mapping（実験的機能）

Fusion mapping は、元のチェックポイント形式を維持したまま、読み込み時にモデルのサブモジュールを置き換えるためのオプトイン方式を提供します。

以下に基づいています：

• モデルのインスタンス化前にモジュールのクラスを差し替えるためのMonkey patching。
• 元のランタイムレイアウトと融合後のランタイムレイアウトの間で重みをマッピングするための動的な重み読み込み。

Fusion mapping は実験的な読み込み機能です。ランタイムのモジュール構造を変更するため、モデルの動作に影響を与える可能性があります。明示的に融合されたランタイムレイアウトを使用したい場合にのみ使用してください。

クイックスタート

from_pretrained() の fusion_config を使用して、Fusion を有効にできます。

from transformers import AutoModelForImageTextToText


model = AutoModelForImageTextToText.from_pretrained(
    "Qwen/Qwen2-VL-2B-Instruct",
    fusion_config={"patch_embeddings": True},
)

デフォルトでは、フュージョンは適用されません。 fusion_configがモデル設定に保存されている場合、from_pretrained()は自動的にそれを再利用します。

仕組み

Fusionの登録は、モデルがインスタンス化される前に実行されます:

1. from_pretrained() は明示的な fusion_config 引数を使用するか、config.fusion_config にフォールバックします。
2. フュージョンレジストリは、要求されたフュージョン名を検証します。
3. 各有効化されたfusionは、ターゲットのモデルクラスをメタ初期化し、必要に応じてモジュール名で候補モジュールをフィルタリングし、is_fusable(...)を使用して互換性のあるモジュールクラスを検出します。
4. Fused replacement classes are registered through register_patch_mapping().
5. 設定から~WeightTransformルールが生成されるため、チェックポイントの読み込み時に、重みを融合ランタイムのレイアウトにマッピングできます。
6. デフォルトでは、save_pretrained()は逆変換パスを使用して元のチェックポイントのレイアウトを復元します。変換後のランタイムレイアウトを保持するには、save_original_format=Falseを渡します。

これにより、fusion は異なるランタイムモジュール構造を使用しながらも、元のチェックポイント形式から読み込み、デフォルトではその形式に保存することができます。

注: 現在のmonkey-patchingメカニズムでは、フュージョンの登録はクラスレベルです。1つの互換性のあるモジュールクラスが、1つのフュージョン済み代替クラスに対応します。

現在の融合ファミリー

現在、fusion_configは1つのフュージョンファミリーをサポートしています：

• patch_embeddings を有効にするには:

  コピーしました

  fusion_config = {"patch_embeddings": True}

  効果: 互換性のあるnn.Conv3dパッチ埋め込みの射影を、実行時に等価なフラット化されたnn.Linear射置に置き換えます。

フュージョンマッピングの拡張

新しい融合ファミリーを追加するには:

1. is_fusable 述語を追加します。 これにより、発見されたモジュールがフュージョンと互換性があるかどうかを判定します。
2. 必要に応じてtarget_modules_patternsを追加します。これにより、is_fusable(...)の実行前に候補モジュール名を事前フィルタリングすることで、検出ステップがより明示的になります。
3. make_fused_class ファクトリを追加します。 これは、互換性のあるモジュールクラスに対するランタイムの代替クラスを返します。
4. fused レイアウトにチェックポイントの変換が必要な場合は、make_transforms ファクトリを追加します。 これは、指定された config に対して、元のレイアウトと fused レイアウトの間で重みをマッピングする ~WeightTransform ルールを返します。
5. ModuleFusionSpec の新しいものを fusion_mapping.py に登録します。

登録が完了すると、新しいフュージョンはfusion_configを通じて利用可能になります。

内部API