# 融合映射（实验性功能）

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

它基于以下内容构建：

- 通过 [Monkey patching](./monkey_patching) 在模型实例化之前替换模块类。
- [动态权重加载](./weightconverter)，用于在原始运行时布局与融合后的运行时布局之间映射权重。

> [!WARNING]
> Fusion mapping 是一种实验性加载功能。它会更改运行时模块结构，并可能影响模型行为。仅当您明确希望使用融合运行时布局时，才应使用此功能。

## 快速入门

通过 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 中的 `fusion_config` 启用 Fusion：

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

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

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

## 当前的融合家族

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

- `patch_embeddings` 启用方式：

  ```python
  fusion_config = {"patch_embeddings": True}
  ```

  效果：在运行时，将兼容的 `nn.Conv3d` 补丁嵌入投影替换为等效的展平 `nn.Linear` 投影。

## 扩展融合映射

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

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

注册完成后，新的融合即可通过 `fusion_config` 使用。

## 内部 API[[transformers.fusion_mapping.ModuleFusionSpec]]

#### transformers.fusion_mapping.ModuleFusionSpec[[transformers.fusion_mapping.ModuleFusionSpec]]

```python
transformers.fusion_mapping.ModuleFusionSpec()
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/fusion_mapping.py#L47)

融合家族的基础配方。

融合规范决定了哪些模块有资格进行融合、如何构建运行时替换类，以及需要哪些权重转换来在原始布局和融合布局之间映射检查点。

#### get_empty_log[[transformers.fusion_mapping.ModuleFusionSpec.get_empty_log]]

```python
get_empty_log(model_name: str)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/fusion_mapping.py#L57)

返回在未找到兼容模块时发出的日志消息。

#### is_fusable[[transformers.fusion_mapping.ModuleFusionSpec.is_fusable]]

```python
is_fusable(module: Module)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/fusion_mapping.py#L61)

返回 `module` 是否与此融合族兼容。

#### make_fused_class[[transformers.fusion_mapping.ModuleFusionSpec.make_fused_class]]

```python
make_fused_class(original_cls: type[torch.nn.Module])
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/fusion_mapping.py#L65)

为兼容的模块类构建运行时替换类。

#### make_transforms[[transformers.fusion_mapping.ModuleFusionSpec.make_transforms]]

```python
make_transforms(config: PretrainedConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/fusion_mapping.py#L69)

构建用于加载和保存融合运行时布局所需的权重转换。

#### transformers.fusion_mapping.PatchEmbeddingsFusionSpec[[transformers.fusion_mapping.PatchEmbeddingsFusionSpec]]

```python
transformers.fusion_mapping.PatchEmbeddingsFusionSpec()
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/fusion_mapping.py#L97)

将兼容的 Conv3d 补丁嵌入融合为展平的 Linear 投影。

#### transformers.fusion_mapping._register_module_fusion[[transformers.fusion_mapping._register_module_fusion]]

```python
transformers.fusion_mapping._register_module_fusion(config: PretrainedConfig, fusion_name: str, spec: ModuleFusionSpec)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/fusion_mapping.py#L193)

为 `cls` 注册一个融合族。

此函数会更新融合加载所使用的两个全局注册表：
- 猴子补丁注册表，因此兼容的模块类会在初始化之前被替换
- 检查点转换映射，因此融合运行时模块仍从原始检查点布局中加载

注意事项：
- 冲突的检查点转换会快速失败

#### transformers.fusion_mapping.register_fusion_patches[[transformers.fusion_mapping.register_fusion_patches]]

```python
transformers.fusion_mapping.register_fusion_patches(config, fusion_config: collections.abc.Mapping[str, bool | collections.abc.Mapping[str, typing.Any]] | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/fusion_mapping.py#L269)

为 `cls` 注册请求的运行时融合。

此函数：
- 根据 `_FUSION_REGISTRY` 验证 `fusion_config`
- 按用户顺序解析已启用的融合族
- 在模型实例化之前注册猴子补丁和检查点转换

