融合映射（实验性功能）

Fusion mapping 提供了一种可选的方式，在加载时替换模型的子模块，同时保留原始的 checkpoint 格式。

它基于以下内容构建：

通过 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 注册发生在模型实例化之前：

from_pretrained() 会使用显式的 fusion_config 参数，或者回退到 config.fusion_config。
融合注册表会验证所请求的融合名称。
每个启用的融合元初始化目标模型类，可选地按名称筛选候选模块，并使用 is_fusable(...) 来发现兼容的模块类。
融合替换类通过 register_patch_mapping() 进行注册。
~WeightTransform 匹配规则由配置生成，以便在加载检查点时将权重映射到融合后的运行时布局。
默认情况下，save_pretrained() 使用反向转换路径来恢复原始检查点布局。传入 save_original_format=False 可保留转换后的运行时布局。

这使得融合可以使用不同的运行时模块结构，同时仍然从原始检查点格式加载，并且默认情况下也保存回该格式。

注意：在当前的 monkey-patching 机制下，融合注册是类级别的：一个兼容的模块类对应一个融合替换类。

当前的融合家族

目前，fusion_config 支持一个融合族：

patch_embeddings 启用方式：
```
fusion_config = {"patch_embeddings": True}
```
效果：在运行时，将兼容的 nn.Conv3d 补丁嵌入投影替换为等效的展平 nn.Linear 投影。

扩展融合映射

要添加一个新的融合家族：

添加一个 is_fusable 谓词。该谓词用于判断发现的模块是否与融合兼容。
可选地添加 target_modules_patterns。这通过在 is_fusable(...) 之前预先筛选候选模块名称，使发现步骤更加明确。
添加 make_fused_class 工厂。它返回与兼容模块类对应的运行时替换类。
如果融合布局需要检查点转换，请添加一个 make_transforms 工厂。该工厂返回 ~WeightTransform 规则，用于在给定配置下将权重在原始布局与融合布局之间进行映射。
在 fusion_mapping.py 中注册新的 ModuleFusionSpec。