# 旧版模型贡献

> [!TIP]
> 建议先尝试采用更具[模块化](./modular_transformers)的方式添加新模型。这将大大简化向 Transformers 贡献模型的流程！

Transformers 中的许多模型由开发者和研究人员贡献。作为一个开源优先的项目，我们致力于赋能社区，使其能够主动且独立地添加更多模型。

将模型添加到 Transformers 时，您将了解：

- 了解有关开源最佳实践的更多信息
- 关于模型的架构
- 关于 Transformers 的设计原则
- 如何高效测试大型模型
- 如何使用 [Black](https://black.readthedocs.io/en/stable/) 和 [Ruff](https://docs.astral.sh/ruff/) 等 Python 实用工具来编写整洁且可读性强的代码

这是一个充满挑战但回报丰厚的过程。

本指南将指导你如何将一个示例 BrandNewLlama PyTorch 模型添加到 Transformers 中。在开始之前，建议你先熟悉一下该库。

## Transformers 概览

Transformers 是一个带有鲜明观点的库，拥有其独特的哲学和设计选择。这些选择帮助我们可持续地扩展和维护 Transformers。

> [!TIP]
> 有关我们的设计原则，请参阅[Philosophy](./philosophy)文档。

其中一些设计选择包括：

- 组合 > 过度抽象
- 如果重复代码能显著提升可读性和可访问性，那么它并不总是坏事
- 模型文件是自包含的，所有必要的模型代码都位于 `modeling_mymodel.py` 文件中

这些设计选择对于与模型交互的*每个人*都很重要。它们更易于阅读、理解和修改。

本节介绍模型类和配置类之间的交互方式，以及 Transformers 的代码风格。

### 模型和配置

所有 Transformers 模型都继承自基类 [PreTrainedModel](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel) 和 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig)。配置是模型的蓝图。

任何模型最多只有两层抽象，以保持代码的可读性。此处的示例模型 BrandNewLlama 继承自 `BrandNewLlamaPreTrainedModel` 和 [PreTrainedModel](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel)。新模型仅依赖于 [PreTrainedModel](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel) 这一点至关重要，这样才能使用 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 和 [save_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.save_pretrained) 方法。

其他重要函数（例如 forward 方法）定义在 `modeling.py` 文件中。

特定的模型头（例如序列分类或语言建模）应在前向传播中调用基础模型，而不是继承自基础模型，以保持较低的抽象层级。

新模型需要一个配置，例如 `BrandNewLlamaConfig`，它作为 [PreTrainedModel](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel) 的属性进行存储。

```py
model = BrandNewLlamaModel.from_pretrained("username/brand_new_llama")
model.config
```

[PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig) 提供了 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig.from_pretrained) 和 [save_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig.save_pretrained) 方法。

使用 [PreTrainedModel.save_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.save_pretrained) 时，它会自动调用 [PreTrainedConfig.save_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig.save_pretrained)，从而将模型和配置一起保存。

模型会保存到一个 `model.safetensors` 文件中，配置会保存到一个 `config.json` 文件中。

### 代码风格

Transformers 更倾向于简洁易读的代码，而非高度抽象的代码风格。部分代码风格选择包括：

- 代码应对非英语用户友好。请选择描述性强的变量名，避免使用缩写。例如，应使用 "activation" 而非 "act"。强烈不建议使用单字母变量名，除非它是 for 循环中的索引。

- 优先使用显式代码——即使它更长——而不是更简短的代码。

- 避免对 [nn.Sequential](https://pytorch.org/docs/stable/generated/torch.nn.Sequential.html) 进行子类化。请改为子类化 [nn.Module](https://pytorch.org/docs/stable/generated/torch.nn.Module.html#torch.nn.Module)，这样可以通过打印语句或断点快速调试代码。

- 函数签名应包含类型注解。否则，请使用清晰的变量名以提高可读性。

## 新增模型问题

打开一个 [新增模型](https://github.com/huggingface/transformers/issues/new?assignees=&labels=New+model&template=new-model-addition.yml) issue 以添加特定模型。

> [!TIP]
> 在 GitHub 上按 [New model](https://github.com/huggingface/transformers/labels/New%20model) 标签进行筛选，即可查看并添加任何现有的模型请求。

现在是熟悉 BrandNewLlama 的好时机。阅读模型的研究论文有助于理解其技术设计与实现。你不必过于纠结理论细节，而应重点关注实践层面的内容。请借助以下问题来引导你的阅读。

- BrandNewLlama 是什么类型的模型？它是编码器、解码器还是编码器-解码器模型？
- BrandNewLlama 可以用于哪些任务？
- BrandNewLlama 与其他模型有何不同？
- Transformers 中哪些模型与 BrandNewLlama 最为相似？
- BrandNewLlama 使用哪种分词器？

除了深入了解你的模型之外，还可以使用以下提示来帮助你更快地添加模型。

> [!TIP]
> 每位贡献者向 Transformers 添加模型时都有自己独特的风格和流程。例如，可以查看 [Gemma](https://github.com/huggingface/transformers/pull/29167) 是如何被添加的。

- 不要重复造轮子！花点时间探索现有的模型和分词器，看看哪些可以复制和复用。[Grep](https://www.gnu.org/software/grep/) 和 [ripgrep](https://github.com/BurntSushi/ripgrep) 是完成这项任务的绝佳工具。
- 这更像是一个工程挑战，而非科学挑战。请侧重于更实际的方面（例如搭建高效的调试环境），而非模型的理论知识。
- 别不好意思，大胆求助吧！我们随时准备为你提供支持。🤗

## 开发环境

点击 [Transformers](https://github.com/huggingface/transformers) 仓库中的 **Fork** 按钮，创建一份副本供你使用。将仓库克隆到本地磁盘，并将基础仓库添加为远程仓库。

```bash
git clone https://github.com/[your Github handle]/transformers.git
cd transformers
git remote add upstream https://github.com/huggingface/transformers.git
```

创建一个虚拟环境，并使用“dev”或开发依赖项对该库执行[可编辑安装](./installation#editable-install)。

```bash
python -m venv .env
source .env/bin/activate
pip install -e ".[dev]"
```

随着 Transformers 的可选依赖项数量不断增加，该命令可能会执行失败。在这种情况下，请安装 "quality" 依赖项。同时，请确保已安装深度学习框架。

```bash
pip install -e ".[quality]"
```

返回父目录，克隆并安装原始的 BrandNewLlama 仓库。

```bash
git clone https://github.com/org_that_created_brand_new_llama_org/brand_new_llama.git
cd brand_new_bert
pip install -e .
```

返回你的 Transformers 克隆仓库，开始移植 BrandNewLlama。

```bash
cd transformers
```

运行原始模型有两种可能的调试环境：笔记本（[Google Colab](https://colab.research.google.com/notebooks/intro.ipynb) 或 [Jupyter](https://jupyter.org/)）或本地 Python 脚本。

> [!WARNING]
> 我们不建议搭建 GPU 环境来运行原始模型，因为成本可能很高。相反，请先在 CPU 环境中验证模型能否在 Transformers 中正常运行。确认无误后，再在 GPU 上进行验证。

Notebook 非常适合逐单元格执行代码，这有助于将各个逻辑组件相互分离。由于可以保存中间结果，它还能加快调试周期。在与协作者协作时，你还可以共享 Notebook。

缺点在于，如果你不习惯使用它们，可能需要一些时间来适应。

> [!TIP]
> 如果模型架构与现有模型完全相同，请跳过此步骤，直接前往[转换检查点](#convert-checkpoints-to-transformers)，因为您可以复用现有模型的架构。

运行以下命令以启动问卷，并填写有关新模型的一些基本信息。该命令会自动生成一些模型代码，从而快速启动流程，您随后需要对这些代码进行适配。

```bash
transformers add-new-model-like
```

## 创建拉取请求

在开始修改代码之前，请创建一个拉取请求（pull request）以跟踪你的进度并获取 Transformers 团队的反馈。请将拉取请求的标题设为 **[WIP] Add BrandNewLlama**，以明确表明这是一项进行中的工作。

从主分支创建一个具有描述性名称的分支。

```bash
git checkout -b add_brand_new_bert
```

提交代码，然后拉取并变基到主分支。

```bash
git add .
git commit
git fetch upstream
git rebase upstream/main
```

将任何更改推送到你的分支，然后单击 **Compare & pull request** 在 GitHub 上打开一个拉取请求。将该拉取请求标记为 *draft*，以表明它仍在进行中。

```bash
git push -u origin a-descriptive-name-for-my-changes
```

在拉取请求中添加相关 Hugging Face 团队成员的 GitHub 用户名，以便就问题、反馈、评论和审查与他们沟通。点击 **Files changed** 选项卡，然后点击行号左侧的 **+**，即可将团队成员引导至你希望他们查看的代码特定部分并添加评论。当问题或故障得到解决时，点击 **Resolve** 以标记该问题已解决。这样可以保持对话的条理清晰和整洁。

请记住定期提交并推送你的工作，并使用当前的 main 分支更新你的工作。

```bash
git fetch upstream
git merge upstream/main
```

## 原始检查点

先花些时间研究原始模型实现，以了解其工作原理。

如果原始模型仓库缺乏文档或代码库较为复杂，这可能会带来一定难度。但你应该将此作为在 Transformers 中实现该模型的动机。你的贡献将使模型对所有人来说都更加易于访问和使用！

通过执行以下操作来熟悉原始仓库。

- 定位预训练权重。
- 弄清楚如何将预训练权重加载到模型中。
- 研究如何独立于模型运行分词器。
- 跟踪一次前向传播，以了解需要哪些类和函数。这些很可能就是您需要实现的仅有的类和函数。
- 定位模型的所有重要组件（模型类、模型子类、自注意力层等）。
- 弄清楚如何在原始仓库中调试模型。添加 print 语句，使用交互式调试器（如 [ipdb](https://github.com/gotcha/ipdb)），或使用高效的集成开发环境（IDE）（如 [PyCharm](https://www.jetbrains.com/pycharm/)）。

最后一点尤为重要，因为在用 Transformers 重新实现模型之前，你需要彻底理解原始模型内部的工作机制。如果在过程中遇到任何问题，欢迎在原始仓库中提交 issue 和 pull request。

一个好的第一步是加载一个*小型*预训练检查点，并尝试使用示例整数输入向量来复现单次前向传播。例如，用伪代码表示，可以如下所示。

```py
model = BrandNewLlamaModel.load_pretrained_checkpoint("/path/to/checkpoint/")
input_ids = [0, 4, 5, 2, 3, 7, 9]  # vector of input ids
original_output = model.generate(input_ids)
```

### 调试

如果遇到任何问题，你需要根据原始模型的代码库选择以下调试策略之一。

该策略依赖于将原始模型拆分为更小的子组件，例如当代码可以轻松地以 eager 模式运行时。尽管难度更大，但这种方法也有一些优势。

1. 之后将原始模型与你的实现进行对比会更容易。你可以自动验证每个单独组件是否与 Transformers 实现中对应的组件相匹配。这比依赖基于 print 语句的视觉对比要好。
2. 移植单个组件比移植整个模型更容易。
3. 将模型拆分为更小的部分，有助于理解其工作原理。
4. 通过逐组件测试，在后续修改代码时更容易防止回归问题。

> [!TIP]
> 请参阅 ELECTRA 的 [集成检查](https://gist.github.com/LysandreJik/db4c948f6b4483960de5cbac598ad4ed)，其中展示了如何将模型分解为更小组件的良好示例。

当原始代码库过于复杂、仅允许中间组件以编译模式运行，或者将模型拆分为更小的子组件耗时过长（甚至可能无法实现）时，此策略是可行的。

例如，[T5](https://github.com/tensorflow/mesh/tree/master/mesh_tensorflow) 的 MeshTensorFlow 实现过于复杂，且没有提供将模型分解为其子组件的简单方法。在这种情况下，你只能依赖验证打印语句。

无论您选择哪种策略，都建议先调试初始层，最后调试最终层。按照以下顺序，通过 print 语句或子组件函数获取这些层的输出。

1. 传递给模型的输入 ID
2. 词嵌入
3. 第一个 Transformer 层的输入
4. 第一个 Transformer 层的输出
5. 以下 n-1 个 Transformer 层的输出
6. 整个模型的输出

输入 ids 应该只是一个整数数组，例如 `input_ids = [0, 4, 4, 3, 2, 4, 1, 7, 19]`。

层输出通常由多维浮点数组组成。

```py
[[
 [-0.1465, -0.6501,  0.1993,  ...,  0.1451,  0.3430,  0.6024],
 [-0.4417, -0.5920,  0.3450,  ..., -0.3062,  0.6182,  0.7132],
 [-0.5009, -0.7122,  0.4548,  ..., -0.3662,  0.6091,  0.7648],
 ...,
 [-0.5613, -0.6332,  0.4324,  ..., -0.3792,  0.7372,  0.9288],
 [-0.5416, -0.6345,  0.4180,  ..., -0.3564,  0.6992,  0.9191],
 [-0.5334, -0.6403,  0.4271,  ..., -0.3339,  0.6533,  0.8694]]],
```

每个 Transformers 模型输出的精度或误差容差应为 *1e-3*。这涵盖了因使用不同库框架而产生的任何输出差异。请将原始模型的中间输出与 Transformers 实现进行对比，以确保二者几乎完全一致。拥有一个*高效的*调试环境对于此步骤至关重要。

以下是一些构建高效调试环境的技巧。

- 要调试中间结果，具体方法取决于原始模型仓库所使用的机器学习框架。对于 PyTorch，您应该编写一个脚本，将原始模型分解为更小的子组件，以获取中间值。

- 使用较小的预训练检查点进行调试比使用较大的检查点更快，因为较大检查点的前向传播耗时可能超过 10 秒。如果只有大型检查点可用，请创建一个具有随机初始化权重的虚拟模型，并将这些权重保存下来，以便与 Transformers 的实现进行对比。

- 找到调用模型前向传播的最简单方式。理想情况下，该函数（可能名为 `predict`、`evaluate`、`forward` 或 `__call__`）应只调用前向传播 *一次*。如果一个函数多次调用前向传播，调试起来会更困难。

- 将分词与正向传播分离。找到正向传播中将字符串输入转换为输入 ID 的位置，并从这里开始。你可能需要创建一个小型脚本或修改原始代码，以便直接输入输入 ID 而不是输入字符串。

- 确保模型*不*处于训练模式。由于模型中存在多个 dropout 层，这可能会导致输出结果随机。在调试环境中，前向传播应当是*确定性的*，从而避免使用 dropout 层。

一旦您能够运行原始检查点，就可以开始为 Transformers 适配模型代码了。

## 适配模型代码

`transformers add-new-model-like` 命令应该已经生成了模型和配置文件。

- `src/transformers/models/brand_new_llama/modeling_brand_new_llama.py`
- `src/transformers/models/brand_new_llama/configuration_brand_new_llama.py`

`modeling.py` 文件中自动生成的代码，如果你回答该模型是仅解码器模型，则其架构与 Llama 相同；如果你回答是编码器-解码器模型，则其架构与 BART 相同。生成的代码只是一个起点。根据你对新模型的研究，你需要通过调整生成的代码来实现这些特定的更改。这可能涉及对自注意力层、归一化层的顺序等方面的修改。

### 模型初始化

此时，你的代码不必整洁，甚至无需完全正确。更高效的做法是快速完成初稿，然后逐步迭代改进。最关键的是，你的模型能够被 Transformers 实例化。下面的命令会根据配置创建一个具有随机权重的模型，以验证 `__init__` 方法是否正常工作。

```py
from transformers import BrandNewLlama, BrandNewLlamaConfig
model = BrandNewLlama(BrandNewLlamaConfig())
```

随机初始化发生在 `BrandNewLlamaPreTrainedModel` 的 `_init_weights` 方法中。所有叶子模块都会根据配置中的变量进行初始化。请使用 `transformers.initialization` 模块中的辅助函数来设置数值，而不是直接在权重或其 `.data` 上调用原地操作。

```py
from transformers import initialization as init

def _init_weights(self, module):
    """Initialize the weights"""
    if isinstance(module, nn.Linear):
        init.normal_(module.weight, mean=0.0, std=self.config.initializer_range)
        if module.bias is not None:
            init.zeros_(module.bias)
    elif isinstance(module, nn.Embedding):
        init.normal_(module.weight, mean=0.0, std=self.config.initializer_range)
        if module.padding_idx is not None:
            init.zeros_(module.weight[module.padding_idx])
    elif isinstance(module, nn.LayerNorm):
        init.zeros_(module.bias)
        init.ones_(module.weight)
```

始终通过 `transformers.initialization` 辅助函数来初始化权重。诸如 `module.bias.zero_()` 或任何触及 `module.weight.data` 的原地操作都会绕过 `_is_hf_initialized`，而该标志用于标记哪些参数已经加载。[from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 在加载检查点后会运行 `_init_weights`，因此原地操作会静默地将已加载的权重覆盖为随机值。对于 Transformers 模型，此要求由 [TRF012](./modeling_rules#trf012) 规则强制执行。

> [!WARNING]
> During [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained), models are usually initialized on the `meta` device. The loader recreates non-persistent buffers as empty tensors, so values assigned in `__init__` aren't preserved. Initialize these buffers in `_init_weights` so they have the correct values after loading. For an example, see how BERT initializes its position IDs and token type IDs.

如果需要针对您的模型进行调整，初始化方案可能会有所不同。拥有自身 `reset_parameters` 方法的子模块可以直接调用该方法。例如，[Wav2Vec2ForPreTraining](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2ForPreTraining) 在其最后两个线性层中初始化 [nn.Linear](https://pytorch.org/docs/stable/generated/torch.nn.Linear.html)。该调用是安全的，因为在 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 运行 `_init_weights` 期间，它会修补底层的 `torch.nn.init` 函数以尊重 `_is_hf_initialized` 标志，从而确保已加载的权重不会被覆盖。

```py
def _init_weights(self, module):
    """Initialize the weights"""
    if isinstance(module, Wav2Vec2ForPreTraining):
        module.project_hid.reset_parameters()
        module.project_q.reset_parameters()
```

### 将检查点转换为 Transformers

原始检查点必须转换为与 Transformers 兼容的检查点。

> [!TIP]
> 尝试查找现有的转换脚本，以便复制、调整并复用于你的模型！
>
> - 如果您要将模型从 TensorFlow 移植到 PyTorch，一个好的起点可能是 BERT [转换脚本](https://github.com/huggingface/transformers/blob/7acfa95afb8194f8f9c1f4d2c6028224dbed35a2/src/transformers/models/bert/modeling_bert.py#L91)。 - 如果您要将模型从 PyTorch 移植到 PyTorch，一个好的起点可能是 BART [转换脚本](https://github.com/huggingface/transformers/blob/main/src/transformers/models/bart/convert_bart_original_pytorch_checkpoint_to_pytorch.py)。

确保**所有**必需的权重都已初始化，并打印出所有未用于初始化的检查点权重，以确认模型已正确转换。

在转换过程中，您可能会遇到形状错误或名称赋值错误。这通常是由于 `BrandNewLlamaConfig` 中的参数不正确、架构错误、您的实现中 `init` 方法存在 bug，或者需要对检查点权重之一进行转置所致。

持续迭代[适配模型代码](#adapt-the-model-code)部分，直到所有检查点权重都能正确加载。当你的模型能够加载检查点后，将其保存到一个文件夹中。该文件夹应包含`model.safetensors`文件和`config.json`文件。

```py
model.save_pretrained("/path/to/converted/checkpoint/folder")
```

为了便于转换，下一节将简要介绍 PyTorch 模型如何存储和定义层权重及其名称。

#### PyTorch 层权重和名称

创建一个基础的 PyTorch 模型有助于理解层名称是如何定义的，以及权重是如何初始化的。

```py
from torch import nn

class SimpleModel(nn.Module):
    def __init__(self):
        super().__init__()
        self.dense = nn.Linear(10, 10)
        self.intermediate = nn.Linear(10, 10)
        self.layer_norm = nn.LayerNorm(10)
```

PyTorch 层的名称由该层的类属性名定义（`dense`、`intermediate`、`layer_norm`）。创建一个 `SimpleModel` 实例，即可用随机权重填充所有层。

```py
model = SimpleModel()
print(model)
SimpleModel(
  (dense): Linear(in_features=10, out_features=10, bias=True)
  (intermediate): Linear(in_features=10, out_features=10, bias=True)
  (layer_norm): LayerNorm((10,), eps=1e-05, elementwise_affine=True)
)
```

特定层的权重值被随机初始化。

```py
print(model.dense.weight.data)
tensor([[-0.0818,  0.2207, -0.0749, -0.0030,  0.0045, -0.1569, -0.1598,  0.0212,
         -0.2077,  0.2157],
        [ 0.1044,  0.0201,  0.0990,  0.2482,  0.3116,  0.2509,  0.2866, -0.2190,
          0.2166, -0.0212],
        [-0.2000,  0.1107, -0.1999, -0.3119,  0.1559,  0.0993,  0.1776, -0.1950,
         -0.1023, -0.0447],
        [-0.0888, -0.1092,  0.2281,  0.0336,  0.1817, -0.0115,  0.2096,  0.1415,
         -0.1876, -0.2467],
        [ 0.2208, -0.2352, -0.1426, -0.2636, -0.2889, -0.2061, -0.2849, -0.0465,
          0.2577,  0.0402],
        [ 0.1502,  0.2465,  0.2566,  0.0693,  0.2352, -0.0530,  0.1859, -0.0604,
          0.2132,  0.1680],
        [ 0.1733, -0.2407, -0.1721,  0.1484,  0.0358, -0.0633, -0.0721, -0.0090,
          0.2707, -0.2509],
        [-0.1173,  0.1561,  0.2945,  0.0595, -0.1996,  0.2988, -0.0802,  0.0407,
          0.1829, -0.1568],
        [-0.1164, -0.2228, -0.0403,  0.0428,  0.1339,  0.0047,  0.1967,  0.2923,
          0.0333, -0.0536],
        [-0.1492, -0.1616,  0.1057,  0.1950, -0.2807, -0.2710, -0.1586,  0.0739,
          0.2220,  0.2358]]).
```

在转换脚本中，应将随机权重替换为原始检查点中对应层的精确权重。

```py
# retrieve matching layer weights with recursive algorithm
layer_name = "dense"
pretrained_weight = array_of_dense_layer

model_pointer = getattr(model, "dense")
model_pointer.weight.data = torch.from_numpy(pretrained_weight)
```

验证随机初始化的权重及其对应的预训练检查点权重具有相同的 **shape** 和 **name**。为 shape 添加 assert 语句，并打印出检查点权重的名称。

```py
assert (
    model_pointer.weight.shape == pretrained_weight.shape
), f"Pointer shape of random weight {model_pointer.shape} and array shape of checkpoint weight {pretrained_weight.shape} mismatched"

logger.info(f"Initialize PyTorch weight {layer_name} from {pretrained_weight.name}")
```

当形状或名称不匹配时，您可能将错误的检查点权重分配给了随机初始化的层。形状不匹配可能是因为 `BrandNewLlama` 的参数与原始模型的参数不完全一致。但也可能是 PyTorch 层的实现要求先对权重进行转置。

### 实现前向传播

如果模型能够正确加载，接下来应实现前向传播。它接收一些输入并返回模型输出。

```py
model = BrandNewLlamaModel.from_pretrained("/path/to/converted/checkpoint/folder")
input_ids = [0, 4, 4, 3, 2, 4, 1, 7, 19]
output = model.generate(input_ids).last_hidden_states
```

如果前向传播的结果与原始模型的输出不完全一致，或者返回了错误，请不要气馁。请检查前向传播是否抛出任何错误。这通常是因为维度不正确，或者使用了错误的数据类型（例如使用了 [torch.long](https://pytorch.org/docs/stable/generated/torch.Tensor.long.html) 而不是 [torch.float32](https://pytorch.org/docs/stable/tensors.html)）。

您的输出精度应为 *1e-3*。请确保输出形状和输出值完全一致。输出不一致的常见原因包括：

- 某些层未被添加（激活层或残差连接）。
- 词嵌入矩阵未进行绑定。
- 由于原始实现中包含一个偏移量，因此使用了错误的位置嵌入。
- Dropout 在前向传播过程中应用。请确保 `model.training` 为 `False`，并将 `self.training` 传递给 [torch.nn.functional.dropout](https://pytorch.org/docs/stable/nn.functional.html?highlight=dropout#torch.nn.functional.dropout)，以修复此错误。

比较原始模型和你的实现的前向传播，以检查是否存在任何差异。理想情况下，调试并打印出两种前向传播实现的中间输出，以精确定位原始实现与你的实现之间的差异所在。

1. 请确保两种实现中硬编码的 `input_ids` 完全一致。
2. 验证 `input_ids` 的第一次转换（通常是词嵌入）的输出是否完全一致，然后逐层检查直至最后一层。

两种实现之间的任何差异都应指向您实现中的错误。

最佳策略之一是在两个实现的相同位置添加大量打印语句，然后当中间输出值相同时，逐步移除这些语句。

当两种实现产生相同的输出时，请验证输出之间的精度差值在 *1e-3* 以内。

```py
torch.allclose(original_output, output, atol=1e-3)
```

这通常是整个过程中最困难的部分。如果你能走到这一步，恭喜你！

如果您在此步骤中遇到困难或卡住，请随时在您的拉取请求中寻求帮助。

### 添加模型测试

在模型运行期间，您仍需添加测试以确保其与 Transformers 的兼容性。测试非常重要，因为它们能帮助用户通过查看具体测试来理解您的工作，并且能在未来发生任何更改时防止您的模型出现兼容性问题。

[Cookiecutter](https://cookiecutter.readthedocs.io/en/stable/) 应该已为你的模型添加了一个测试文件。运行下方的测试文件，以确保所有通用测试均通过。

```bash
pytest tests/models/brand_new_llama/test_modeling_brand_new_llama.py
```

集成测试应首先添加，因为它们的作用与您之前用于在 Transformers 中实现新模型的调试脚本相同。Cookiecutter 已添加了这些模型测试的模板 `BrandNewLlamaModelIntegrationTests`，需要将其填写完整。为确保其通过，请运行以下命令。

```bash
RUN_SLOW=1 pytest -sv tests/models/brand_new_llama/test_modeling_brand_new_llama.py::BrandNewLlamaModelIntegrationTests
```

```bash
SET RUN_SLOW=1 pytest -sv tests/models/brand_new_llama/test_modeling_brand_new_llama.py::BrandNewLlamaModelIntegrationTests
```

所有 BrandNewLlama 独有的功能都应在 `BrandNewLlamaModelTester/BrandNewLlamaModelTest` 下的独立测试中进行测试。这个测试常常被忽视，但它极其重要，因为：

- 它有助于将您在过程中获得的知识分享给社区，通过展示模型的新特性如何发挥作用
- 未来的贡献者可以通过运行这些特殊测试来快速测试对模型的更改

## 实现分词器

> [!TIP]
> 我们建议添加快速分词器（[PreTrainedTokenizerFast](/docs/transformers/v5.23.0/zh/main_classes/tokenizer#transformers.TokenizersBackend)），以为用户提供最佳性能。在您的 PR 中，欢迎标记 [@ArthurZucker](https://github.com/ArthurZucker) 或 [@itazap](https://github.com/itazap) 以获取有关如何添加 [PreTrainedTokenizerFast](/docs/transformers/v5.23.0/zh/main_classes/tokenizer#transformers.TokenizersBackend) 的帮助。

模型部分已经搞定，现在该关注分词器了。分词器应与 Transformers 中现有的某个分词器完全相同或非常相似。

在你的实现中查找并加载原始的 tokenizer 文件。在原始仓库中创建一个脚本，该脚本接收一个字符串作为输入并返回 `input_ids`。伪代码应与下面的代码类似。

```py
input_str = "This is a long example input string containing special characters .$?-, numbers 2872 234 12 and words."
model = BrandNewLlamaModel.load_pretrained_checkpoint("/path/to/checkpoint/")
input_ids = model.tokenize(input_str)
```

您可能需要搜索原始仓库以找到正确的 tokenizer 函数，或者修改您在原始仓库克隆中的现有 tokenizer，使其仅返回 `input_ids`。您的 tokenizer 脚本应类似于以下内容。

```py
from transformers import BrandNewLlamaTokenizer

input_str = "This is a long example input string containing special characters .$?-, numbers 2872 234 12 and words."
tokenizer = BrandNewLlamaTokenizer.from_pretrained("/path/to/tokenizer/folder/")
input_ids = tokenizer(input_str).input_ids
```

当两种实现具有相同的 `input_ids` 时，请添加一个分词器测试文件。该文件与建模测试文件类似。分词器测试文件应包含几个硬编码的集成测试。

## 实现图像处理器

> [!TIP]
> 图像处理器现在采用基于后端的架构。默认后端为 [TorchvisionBackend](/docs/transformers/v5.23.0/zh/main_classes/image_processor#transformers.TorchvisionBackend)，它使用 [torchvision](https://pytorch.org/vision/stable/index.html) 库，并支持在 GPU 上执行图像处理。此外，还提供了基于 PIL/NumPy 的替代后端（[PilBackend](/docs/transformers/v5.23.0/zh/main_classes/image_processor#transformers.PilBackend)）。这两个后端均从 `image_processing_backends` 导入。如需帮助，请随时联系 [@yonigozlan](https://github.com/yonigozlan)。

虽然此示例未包含图像处理器，但如果您的模型需要图像输入，您可能需要实现一个。图像处理器负责将图像转换为适合您模型的格式。在实现新的图像处理器之前，请检查 Transformers 库中是否已有可复用的图像处理器，因为许多模型共享相似的图像处理技术。请注意，您也可以使用 [modular](./modular_transformers) 来为图像处理器复用现有组件。

如果确实需要实现新的图像处理器，每个模型都有两个处理器文件：

- `image_processing_<model>.py`：**默认**的基于 torchvision 的处理器（`<Model>ImageProcessor`），继承自 [TorchvisionBackend](/docs/transformers/v5.23.0/zh/main_classes/image_processor#transformers.TorchvisionBackend)。它取代了旧的 "fast" 处理器。
- `image_processing_pil_<model>.py`：PIL/NumPy 替代处理器（`<Model>ImageProcessorPil`），继承自 [PilBackend](/docs/transformers/v5.23.0/zh/main_classes/image_processor#transformers.PilBackend)。它取代了旧的“慢速”处理器。

torchvision 后端文件还定义了 PIL 文件所导入的任何自定义 kwargs 类。这两个文件都使用了 `@auto_docstring` 装饰器——请勿手动添加类文档字符串。有关逐步说明和完整示例，请参阅 [IMAGE_PROCESSOR_REFACTORING_GUIDE.md](https://github.com/huggingface/transformers/blob/main/IMAGE_PROCESSOR_REFACTORING_GUIDE.md)。

在 `tests/models/your_model_name/test_image_processing_your_model_name.py` 中为图像处理器添加测试。这些测试应与其他图像处理器的测试类似，并验证图像处理器能否正确处理图像输入。如果你的图像处理器包含独特的功能或处理方法，请确保也为其添加相应的特定测试。

## 实现处理器

如果模型支持多种模态（例如文本和图像），则需要添加一个处理器（processor）。处理器负责在将数据传递给模型之前，集中处理不同模态的预处理。

处理器应在其 `__call__` 函数中调用相应的模态特定处理器，以正确处理每种类型的输入。请务必查看库中现有的处理器，以了解其预期结构。Transformers 在 `__call__` 函数签名中采用以下约定。

```python
def __call__(
    self,
    images: ImageInput = None,
    text: Union[TextInput, PreTokenizedInput, list[TextInput], list[PreTokenizedInput]] = None,
    audio=None,
    videos=None,
    **kwargs: Unpack[YourModelProcessorKwargs],
) -> BatchFeature:
    ...
```

`YourModelProcessorKwargs` 是一个 `TypedDict`，包含所有常见的处理参数，以及特定处理器可能需要的额外参数。

在 `tests/models/your_model_name/test_processor_your_model_name.py` 中为处理器添加测试。这些测试应与其他处理器的测试类似，并验证处理器能够正确处理不同的模态。

## 集成测试

现在你已经拥有了模型和分词器，请在 `tests/models/brand_new_llama/test_modeling_brand_new_llama.py` 中为模型和分词器添加端到端集成测试。

测试应提供一个有意义的文本到文本示例，以展示模型按预期工作。例如，您可以包含一个源语言到目标语言的翻译对、一个文章到摘要的对，或一个问答对。

如果检查点尚未针对下游任务进行微调，那么模型测试就足够了。

最后，请尝试确保你的测试可以在 GPU 上运行，方法是在模型的内部张量中添加 `.to(self.device)` 语句。如果你没有 GPU 可用，我们可以帮你处理这部分。

## 添加文档

只有当用户知道如何使用你的模型时，它才真正有用。因此，添加文档和 docstring 非常重要。Cookiecutter 添加了一个模板文件 `docs/source/model_doc/brand_new_llama.md`，你可以填写有关你模型的信息。

这通常是用户与模型的第一次交互，因此文档应当清晰简洁。提供模型使用示例往往非常有用。

请确保在 `src/transformers/models/brand_new_llama/modeling_brand_new_llama.py` 中添加了 docstring，并包含所有必要的输入和输出。请查阅我们的 [指南](https://github.com/huggingface/transformers/tree/main/docs#writing-documentation---specification)，了解如何编写文档和 docstring。

## 重构

是时候整理一下，确保代码风格与库的其余部分保持一致。运行以下命令以自动修复不正确的风格。

```bash
make style
```

要验证代码风格是否通过质量检查，请运行以下命令。

```bash
make check-repo
```

由于 Transformers 严格的设计测试，您的拉取请求中可能存在其他失败的测试或检查（例如缺少文档字符串或命名不正确）。如果您遇到这些问题，我们可以为您提供帮助。

在确保代码能够正确运行后，您可能希望对其进行重构，以提高可读性或使其更加简洁。

## 上传到 Hub

将所有检查点转换并上传到 [Hub](https://hf.co/models)。添加模型卡片，以提供更多关于该模型的透明度和背景信息。模型卡片应突出显示检查点的具体特征、模型的训练方式，以及如何使用该模型的代码示例。

> [!TIP]
> 在许多情况下，添加一个用户可以运行的交互式 notebook 是展示如何使用该模型进行推理或在下游任务上进行微调的绝佳方式。虽然并非必需，但包含一个 notebook 有助于提高您模型的采用率。

您还应与 Transformers 团队协商，为模型确定一个合适的名称，并获取上传模型所需的访问权限。

使用 [push_to_hub()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.utils.PushToHubMixin.push_to_hub) 方法上传模型。

```py
brand_new_bert.push_to_hub("brand_new_llama")
```

有关将模型上传到 Hub 的更多信息，请参阅 [共享](./model_sharing) 指南。

## 合并你的模型

您终于准备好合并您的拉取请求，并将该模型正式添加到 Transformers 中了！请确保所有测试均已通过，并且所有评论和反馈都已得到处理。

恭喜您将新模型添加到 Transformers！🥳

这是一项非常重要的贡献。您的工作让全球的开发者和研究人员能够更轻松地使用 Transformers。您应该为自己的贡献感到自豪，并与社区分享您的成就！

## 另请参阅

- [模型结构规则](./modeling_rules) — 对所有 `modeling_*.py` 和 `configuration_*.py` 文件强制执行的静态规则。在提交 PR 之前，请运行 `make typing` 进行检查。
- [Pull request 检查](./pr_checks) — 关于 CI 在您的 PR 上运行哪些检查以及如何通过它们的完整参考。

