# 使用模块化 Transformers 添加模型

Modular transformers 通过允许导入和继承来减少添加模型所需的代码，这与[单模型、单文件](https://huggingface.co/blog/transformers-design-philosophy)策略形成对比。无需在不同文件中重复模型组件，只需在模型文件夹中添加一个*modular*文件，并从现有类继承即可。

转换器从模块化文件生成独立文件。用户将获得他们熟悉的单文件接口。

> [!NOTE]
> Modular transformers 并非旨在取代[旧版建模代码](./add_new_model)。如果您的模型并非基于现有模型，请手动添加`modeling.py`文件。对于无法从类似文件干净地继承的配置、分词或处理文件，同样适用此规则。
>
> 也不存在唯一正确的顺序。一些贡献者先编写模块化文件，再从中生成代码。另一些人则从手写的`modeling.py`开始，之后再将其重构为模块化文件。两种方法都可行。

## 实现模块化文件

首先，在 Transformers 中找一个与你的模型相似的模型。好的起点包括 [Mistral](./model_doc/mistral)、[Qwen2](./model_doc/qwen2)、[Cohere](./model_doc/cohere)、[Cohere2](./model_doc/cohere2) 和 [Llama](./model_doc/llama)。下表将常见组件映射到你可以继承的模型。

| 组件 | 模型 |
|---|---|
| 专家混合 | Mixtral 或 Qwen2-MoE |
| 交错（和/或部分）旋转嵌入 | GLM、Phi |
| 状态空间模型 | Jamba、Bamba、Zamba、Mamba2 |
| 循环隐藏状态 | Gemma2 |
| 每层的滑动窗口注意力/全注意力模式 | Gemma2、Cohere2 |
| QKV 裁剪 | Olmo |
| QK 归一化 | Olmo2，Cohere |
| 融合的 QKV（不推荐） | Phi3 |

> [!TIP]
> 使用 [modular-detector-v2](https://huggingface.co/spaces/Molbap/modular-detector-v2) 工具查找可继承的现有实现。粘贴一段代码片段，它会返回 Transformers 中已有的最相似方法，从而帮助你在开始编写代码前确定最佳的父类。

不要仅仅为了让新模型支持继承而修改现有模型。如果重命名或子类化父类过于繁琐，请直接复制相关代码。

创建 `src/transformers/models/<name>/modular_<name>.py`，其中 `<name>` 需与 snake_case 模型目录名一致。本节将引导你使用模块化方法，从 [Olmo](./model_doc/olmo) 实现 [Olmo2](./model_doc/olmo2)（请参阅原始的 [modular_olmo2.py](https://github.com/huggingface/transformers/blob/main/src/transformers/models/olmo2/modular_olmo2.py) 文件）。

### 配置

[Olmo2Config](/docs/transformers/v5.23.0/zh/model_doc/olmo2#transformers.Olmo2Config) 与 [OlmoConfig](/docs/transformers/v5.23.0/zh/model_doc/olmo#transformers.OlmoConfig) 有两处不同。

1. 新增了一个参数 `rms_norm_eps`。
2. `clip_qkv` 参数不再使用。

将新参数声明为带有默认值的类级别类型注解。对于已移除的参数，请为其赋值 `AttributeError()`，以在生成的文件中抑制继承的属性（参见 [移除属性](#removing-attributes)）。

```diff
- @auto_docstring(checkpoint="allenai/OLMo-7B-hf")
+ @auto_docstring(checkpoint="allenai/Olmo2-7B-1124-hf")
+ @strict
- class OlmoConfig(PreTrainedConfig):
+ class Olmo2Config(OlmoConfig):
      ...
-     model_type = "olmo"
+     model_type = "olmo2"
      ...
+     rms_norm_eps: float = 1e-5
-     clip_qkv: float | None = None
+     clip_qkv = AttributeError()
```

`@auto_docstring` 会自动生成标准的参数文档（参见 [@auto_docstring](./auto_docstring) 指南）。`@strict` 会在实例化时拒绝未知的 kwargs，从而尽早捕获拼写错误和过时的参数。请为每个配置类都添加这两个装饰器，因为装饰器不会从父类继承。即使父配置中已经声明了它们，也要显式地声明。

若要设置派生属性或处理向后兼容逻辑，请使用 `__post_init__` 而非 `__init__`。例如，Cohere2 在初始化时计算 `head_dim` 并推导出 `layer_types`。

```py
def __post_init__(self, **kwargs):
    if self.num_key_value_heads is None:
        self.num_key_value_heads = self.num_attention_heads
    self.head_dim = self.hidden_size // self.num_attention_heads
    super().__post_init__(**kwargs)
```

对于支持张量并行或流水线并行的模型，请在配置上以类级别字典的形式定义 `base_model_tp_plan` 和 `base_model_pp_plan`。这两个字典定义了如何在设备间分片模型。可参考 [Olmo2](https://github.com/huggingface/transformers/blob/main/src/transformers/models/olmo2/modular_olmo2.py) 或 [Cohere2](https://github.com/huggingface/transformers/blob/main/src/transformers/models/cohere2/modular_cohere2.py) 等现有配置作为示例。

```py
class MyNewModelConfig(PreTrainedConfig):
    model_type = "my_new_model"

    # Tensor parallelism: maps layer name patterns to sharding strategies.
    # Use "colwise" / "rowwise" for standard sharding, or the "gather_output" /
    # "split_input" variants when an extra op (e.g. a QK norm) prevents fusing.
    base_model_tp_plan = {
        "layers.*.self_attn.q_proj": "colwise",
        "layers.*.self_attn.k_proj": "colwise",
        "layers.*.self_attn.v_proj": "colwise",
        "layers.*.self_attn.o_proj": "rowwise",
        "layers.*.mlp.gate_proj": "colwise",
        "layers.*.mlp.up_proj": "colwise",
        "layers.*.mlp.down_proj": "rowwise",
    }

    # Pipeline parallelism: maps submodule names to their (input, output) tensor names.
    base_model_pp_plan = {
        "embed_tokens": (["input_ids"], ["inputs_embeds"]),
        "layers": (["hidden_states", "attention_mask"], ["hidden_states"]),
        "norm": (["hidden_states"], ["hidden_states"]),
    }
```

### 范数

若要复制父类且不做任何更改，请使用 `pass` 进行继承。linter 会复制父类的内容，并将所有引用重命名以匹配新模型。

```py
from ..olmo.modeling_olmo import OlmoRotaryEmbedding

class Olmo2RotaryEmbedding(OlmoRotaryEmbedding):
    pass
```

若要更改特定行为，只需继承并覆盖有差异的部分。`Olmo2RMSNorm` 与 `LlamaRMSNorm` 仅有一行不同。乘法运算发生在将数据类型转换回输入 dtype *之前*，而不是之后。

```diff
  from ..llama.modeling_llama import LlamaRMSNorm

  class Olmo2RMSNorm(LlamaRMSNorm):
      def forward(self, hidden_states):
          input_dtype = hidden_states.dtype
          hidden_states = hidden_states.to(torch.float32)
          variance = hidden_states.pow(2).mean(-1, keepdim=True)
          hidden_states = hidden_states * torch.rsqrt(variance + self.variance_epsilon)
-         return self.weight * hidden_states.to(input_dtype)
+         return (self.weight * hidden_states).to(input_dtype)
```

### 注意力

Olmo2 的注意力机制与 Olmo 完全相同，区别在于它对查询和键应用了 `RMSNorm`，并移除了 qkv 裁剪。`super().__init__(...)` 会复制父类的主体并追加两行新的 norm 代码。`forward` 被完全重新定义，因为查询和键现在在投影之前会先经过 norm。linter 还会将任何导入的函数拉入生成的文件中，包括 `apply_rotary_pos_emb`、`eager_attention_forward` 及其依赖项。

```diff
  class Olmo2Attention(OlmoAttention):
      def __init__(self, config: Olmo2Config, layer_idx: int | None = None):
          super().__init__(config, layer_idx=layer_idx)
+         self.q_norm = Olmo2RMSNorm(config.num_attention_heads * self.head_dim, config.rms_norm_eps)
+         self.k_norm = Olmo2RMSNorm(config.num_key_value_heads * self.head_dim, config.rms_norm_eps)

      def forward(self, ...):
          ...
-         query_states = self.q_proj(hidden_states)
-         key_states = self.k_proj(hidden_states)
+         query_states = self.q_norm(self.q_proj(hidden_states))
+         key_states = self.k_norm(self.k_proj(hidden_states))
          value_states = self.v_proj(hidden_states)

-         if self.config.clip_qkv is not None:
-             query_states.clamp_(min=-self.config.clip_qkv, max=self.config.clip_qkv)
-             key_states.clamp_(min=-self.config.clip_qkv, max=self.config.clip_qkv)
-             value_states.clamp_(min=-self.config.clip_qkv, max=self.config.clip_qkv)
-
          ...
```

### DecoderLayer

在 `super().__init__(...)` 之后，使用 `Olmo2RMSNorm` 实例覆盖 norm 属性，并将 `self.self_attn` 重新分配给新的 `Olmo2Attention` 类。`del self.input_layernorm` 会移除父类的 `input_layernorm` 赋值，因为 Olmo2 是在注意力机制*之后*而非之前应用归一化。有关 `del` 会移除和不会移除哪些内容的详细信息，请参阅[移除属性](#removing-attributes)。

`forward` 已被重写，以反映注意力后归一化的位置。只有当属性被重命名时才需要重写 `forward`，如果仅其类型发生变化则不需要。

```diff
  class Olmo2DecoderLayer(OlmoDecoderLayer):
      def __init__(self, config: Olmo2Config, layer_idx: int):
          super().__init__(config, layer_idx=layer_idx)
-         self.self_attn = OlmoAttention(config=config, layer_idx=layer_idx)
-         self.input_layernorm = OlmoLayerNorm(config.hidden_size)
-         self.post_attention_layernorm = OlmoLayerNorm(config.hidden_size)
+         self.self_attn = Olmo2Attention(config=config, layer_idx=layer_idx)
+         del self.input_layernorm
+         self.post_attention_layernorm = Olmo2RMSNorm(config.hidden_size, eps=config.rms_norm_eps)
+         self.post_feedforward_layernorm = Olmo2RMSNorm(config.hidden_size, eps=config.rms_norm_eps)

      def forward(self, ...):
          residual = hidden_states
-         hidden_states = self.input_layernorm(hidden_states)
          # Self Attention
          hidden_states, _ = self.self_attn(...)
-         hidden_states = residual + hidden_states
+         hidden_states = self.post_attention_layernorm(hidden_states)
+         hidden_states = residual + hidden_states

          # Fully Connected
          residual = hidden_states
-         hidden_states = self.post_attention_layernorm(hidden_states)
          hidden_states = self.mlp(hidden_states)
-         hidden_states = residual + hidden_states
+         hidden_states = self.post_feedforward_layernorm(hidden_states)
+         hidden_states = residual + hidden_states
          return hidden_states
```

### 模型

此处只有 `self.norm` 的类型发生了变化。`forward` 方法与父类完全相同，因此 linter 会自动将其继承过来。

```diff
  class Olmo2Model(OlmoModel):
      def __init__(self, config: Olmo2Config):
          super().__init__(config)
-         self.layers = nn.ModuleList(
-             [OlmoDecoderLayer(config, layer_idx) for layer_idx in range(config.num_hidden_layers)]
-         )
-         self.norm = OlmoLayerNorm(config.hidden_size)
+         self.norm = Olmo2RMSNorm(config.hidden_size, eps=config.rms_norm_eps)
+         self.layers = nn.ModuleList(
+             [Olmo2DecoderLayer(config, layer_idx) for layer_idx in range(config.num_hidden_layers)]
+         )
```

### 模型头部

该逻辑与 [OlmoForCausalLM](/docs/transformers/v5.23.0/zh/model_doc/olmo#transformers.OlmoForCausalLM) 完全相同，因此无需进行任何更改。

```py
from ..olmo.modeling_olmo import OlmoForCausalLM

class Olmo2ForCausalLM(OlmoForCausalLM):
    pass
```

### 其他类

由 linter 生成的 [modeling_olmo2.py](https://github.com/huggingface/transformers/blob/main/src/transformers/models/olmo2/modeling_olmo2.py) 还包含未在 `modular_olmo2.py` 中明确定义的类（`Olmo2MLP`、`Olmo2RotaryEmbedding`、`Olmo2PreTrainedModel`）。

除非您显式重新定义，否则 linter 会引入任何继承类所依赖的类。像 `apply_rotary_pos_emb` 这样的导入函数也遵循相同的规则。

例如，`OlmoDecoderLayer` 具有 `self.mlp = OlmoMLP(config)`。`Olmo2MLP` 从未在模块化文件中定义，因此 linter 会自动创建它，相当于使用 `pass`。

```py
from ..olmo.modeling_olmo import OlmoMLP

class Olmo2MLP(OlmoMLP):
    pass
```

如果您希望 `Olmo2MLP` 从其他模型继承，请明确指定。

```py
# switch to Mistral definition
from ..mistral.modeling_mistral import MistralMLP

class Olmo2MLP(MistralMLP):
    pass
```

### 完成文件

每个模块化文件都必须在模块级别声明一个 `logger` 和一个 `__all__` 列表。

```py
logger = logging.get_logger(__name__)

__all__ = [
    "Olmo2Config",
    "Olmo2ForCausalLM",
    "Olmo2Model",
    "Olmo2PreTrainedModel",
]
```

`__all__` 必须列出文件中的所有公共类。转换器和下游导入都依赖于它。如果某个类未包含在 `__all__` 中，则无法正确导出。

## 生成建模文件

`modular_model_converter.py` 脚本会根据你的模块化文件生成独立的 `modeling.py`、`configuration.py` 以及其他文件。对于每个继承类，它会将父类的主体内容复制到子类中，将所有引用重命名以匹配新模型，并引入这些父类所依赖的任何辅助函数或类。

输出文件不包含跨模型导入，也不从其他模型目录继承。linter 会将继承展平为单一层级。如果 `Olmo2Attention` 继承自 `OlmoAttention`，则生成的 `Olmo2Attention` 是完全自包含的。但如果 `OlmoAttention` 本身又继承自其他类，linter 不会内联该祖父类。

运行以下命令，从模块化文件生成文件。

```bash
python utils/modular_model_converter.py your_model
```

请勿直接编辑生成的文件，因为任何更改都会在下次运行时被覆盖。

## 模块化文件的模式

以下各部分记录了在使用模块化文件时的常见使用模式，例如删除属性或重写已装饰的方法。

### 移除属性

删除继承的属性取决于您正在处理的是配置类还是 `nn.Module` 子类。

对于配置类，请在类级别将 `AttributeError()` 分配给该属性。

```py
class MyNewConfig(ParentConfig):
    removed_attr = AttributeError()
```

linter 会完全从生成的配置文件中移除该属性声明。配置类采用 dataclass 风格的布局，没有 `__init__`，因此在类级别分配 `AttributeError()` 是正确的做法。

对于 `nn.Module` 的子类，请在 `super().__init__(...)` 之后使用 `del self.attribute`。

```py
class MyNewModel(ParentModel):
    def __init__(self, config: MyNewConfig):
        super().__init__(config)
        del self.attribute
```

`del self.attribute` 仅从复制的父类主体中移除 `self.attribute = ...` 这一赋值行。它不会移除其他任何引用 `self.attribute` 的行。如果父类的 `forward` 或其他方法也引用了该属性，请同时重写这些方法。

```py
class DummyModel(nn.Module):
    def __init__(self, config: DummyConfig):
        super().__init__()
        self.attribute = config.attribute
        if self.attribute:
            # do more stuff with `self.attribute` here
            ...

class MyNewDummyModel(DummyModel):
    def __init__(self, config: MyNewDummyConfig):
        super().__init__(config)
        del self.attribute
        # 'self.attribute = config.attribute' is removed, but the 'if self.attribute:' block remains.
        # Override forward() or any other method that references self.attribute.
```

### 使用 `super()`

`super().__init__(config)` 指示转换器将父类的主体复制到子类中。有两种模式可以覆盖此行为。

- 当需要生成的输出调用祖父类（`nn.Module.__init__`）而非模块化父类时，直接调用特定的父类。
- 使用 `**super_kwargs` 可以继承父方法的完整签名，同时添加自定义文档字符串或替换装饰器。

#### 直接调用祖父类

当需要 `super()` 指向生成的类的父类而非模块化父类时，请明确指定所调用的类。下例直接调用了 `nn.Module.__init__(self)`。`DummyModule` 本身是一个 `nn.Module`，因此转换器在生成的 `MyNewDummyModule` 中将其写为 `super().__init__()`。

```py
class MyNewDummyModule(DummyModule):                   |     class MyNewDummyModule(nn.Module):
                                                       |
  def __init__(self):                                  |       def __init__(self):
    nn.Module.__init__(self)                           |         super().__init__()
    self.foo = config.foo                              |         self.foo = config.foo
    ...                                                |         ...
```

#### super_kwargs

使用 `**super_kwargs` 可以在继承父方法的完整签名的同时，添加自定义文档字符串或替换装饰器。在被重写的签名中，它指示 linter 在生成的输出中展开所有父方法参数。

最常见的用法是添加模型特定的文档字符串，例如记录 `labels` 参数，而无需重写完整的函数签名。

```py
# modular_gemma.py
class GemmaForCausalLM(LlamaForCausalLM):
    def forward(**super_kwargs):
        r"""
        Example:

        ```python
        >>> from transformers import AutoTokenizer, GemmaForCausalLM
        >>> model = GemmaForCausalLM.from_pretrained("google/gemma-7b")
        ...
        ```"""
        return super().forward(**super_kwargs)
```

生成的 `GemmaForCausalLM.forward` 具有完整的 `LlamaForCausalLM` 签名，无需手动复制。

`**super_kwargs` 是用于特殊情况的快捷方式。如果您要更改行为，请编写完整的签名。

### 删除未使用的方法

通过用 `raise AttributeError("")` 语句重写父类方法来移除该方法。linter 会从生成的文件中删除该方法。

```py
class GemmaTokenizer(LlamaTokenizer):
    ...

    def get_spm_processor(self):
        raise AttributeError("Not needed for Gemma")

    def unk_token_length(self):
        raise AttributeError("Not needed for Gemma")
```

### 重写装饰方法

当重写带有装饰器的父类方法时，父类的装饰器会自动继承。如果您添加了自己的装饰器，它将替换父类的装饰器。

该库中出现了两个装饰器，一个用于[捕获模型的中间输出](./model_output_tracing)，另一个用于[自动生成文档字符串](./auto_docstring)。

在下面的示例中，子类重写了一个带有装饰器的父类方法，但没有添加自己的装饰器。父类的装饰器会被继承。

```py
class NewModel(DummyModel):       |   class NewModel(nn.Module):
  ...                             |     ...
                                  |
  def forward(...):               |     @decorator(...)
    ...                           |     def forward(...):
                                  |       ...
```

如果您添加了一个新的装饰器，您的装饰器将替换父类的装饰器。

```py
class NewModel(DummyModel):       |   class NewModel(nn.Module):
  ...                             |     ...
                                  |
  @my_new_decorator(...)          |     @my_new_decorator(...)
  def forward(...):               |     def forward(...):
    ...                           |       ...
```

### 特殊命名

继承自某个类时，linter 会自动重命名所有内容。请确保同一文件中的所有类使用相同的类名前缀。

避免混用前缀，如下例所示。`MyModelIncredibleMLP` 违反了命名约定，当重命名高阶依赖项时，linter 将无法确定应使用 `MyModelIncredible` 还是 `MyModel`。

```py
class MyModelIncredibleMLP(LlamaMLP):
    ...

class MyModelDecoderLayer(LlamaDecoderLayer):
    ...
```

在没有[隐式依赖](#other-classes)的情况下，您可以在本地重命名单个类。请使用新的名称模式显式重新定义该类的其他所有引用。否则，linter 会在 `MyModelIncredibleMLP` 旁边添加一个不需要的 `MyModelMLP` 类。

当 linter 检测到存在歧义的前缀时，会发出警告。

```text
We detected multiple prefix names when inheriting from transformers.models.llama.modeling_llama: ('Emu3Text', 'Emu3'). We will only use the most used 'Emu3' prefix when grabbing args and dependencies. Make sure to subclass the intermediate classes with the prefix you want (if different from 'Emu3') or use a single prefix in all the modular (best).
```

在类名包含 `Text` 等模态限定词的多模态模型中，前缀歧义最为常见。若要为某个依赖项指定特定前缀，请使用 `pass` 显式重命名它。

```py
class Emu3TextMLP(LlamaMLP):
    pass
```

### 配置文档字符串

linter 目前尚不支持部分 docstring 继承。在添加或移除配置属性时，请在模块化文件的类定义下直接添加完整的 docstring。

## 检查点转换

生成建模文件后，请验证真实权重能否正确加载。编写一个转换脚本，将上游检查点格式转换为与 Transformers 兼容的格式，然后将其保存到 Hub。

### 编写转换脚本

在 `src/transformers/models/<model>/` 中添加一个 `convert_<model>_to_hf.py` 文件。该脚本会加载上游权重，重命名并重塑键以匹配模块的参数名称，然后使用 [save_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.save_pretrained) 保存结果。

> [!TIP]
> 查找现有的脚本进行复制和修改。`src/transformers/models/` 下的模型包含一个 `convert_*_to_hf.py`，您可以将其作为起点。

运行脚本后，使用 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 加载已保存的检查点，并确认所有预期的权重均已正确加载。未使用的检查点键表示名称不匹配，因此请打印这些键以尽早发现问题。

```py
model = YourModelForTask.from_pretrained("path/to/output/")
```

在遍历键时，检查形状和名称是否匹配。形状不匹配通常意味着配置中的某个参数有误、架构与原始架构不同，或者某个权重需要转置。

```py
for key, tensor in original_state_dict.items():
    hf_tensor = hf_model.state_dict().get(mapped_key)
    assert hf_tensor.shape == tensor.shape, (
        f"Shape mismatch for {key}: expected {tensor.shape}, got {hf_tensor.shape}"
    )
```

通过在您的模块化文件、生成的 modeling 文件和转换脚本之间反复迭代，修复所有问题，直到所有权重都能顺利加载。

当检查点成功加载后，使用 [push_to_hub()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.utils.PushToHubMixin.push_to_hub) 将其推送到 Hub。有关更多详细信息，请参阅 [模型共享](./model_sharing) 指南。

```py
model.push_to_hub("username/your-model-name")
```

### 运行时转换映射

当发布的权重与模块的参数布局不匹配时，请在 `src/transformers/conversion_mapping.py` 中添加一个运行时映射。常见情况包括单独存储的融合权重以及需要堆叠的 MoE 专家张量。该映射可让 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 直接加载 Hub 上的检查点，而无需单独的导出步骤。

有关如何为`model_type`编写`WeightRenaming`和[WeightConverter](/docs/transformers/v5.23.0/zh/internal/modeling_utils#transformers.WeightConverter)规则并将其注册，请参阅[动态权重加载](./weightconverter)指南。

## 后续步骤

- [模型结构规则](./modeling_rules)是应用于所有 `modeling_*.py`、`modular_*.py` 和 `configuration_*.py` 文件的静态规则。在提交 PR 之前，请运行 `make typing` 进行检查。
- [添加视觉处理组件](./add_vision_processing_components) 介绍了如何为多模态模型添加图像处理器、视频处理器和处理器。
- [自动生成文档字符串](./auto_docstring)展示了如何使用`@auto_docstring`，这样你就不必为共享模型 API 手动编写参数文档。
- [编写模型测试](./testing)介绍了如何为新模型编写集成测试并在本地运行。
- [Pull request checks](./pr_checks) 介绍了在合并 PR 之前必须通过的 CI 检查，以及如何在本地复现和修复这些问题。

