Transformers 文档

为 🤗 Transformers 贡献代码

Transformers

加入Hugging Face社区

并获得增强的文档体验

协作模型、数据集和空间

使用加速推理更快地体验示例

切换文档主题

开始使用

为 🤗 Transformers 贡献力量

欢迎所有人贡献力量，我们珍视每个人的贡献。代码贡献并不是帮助社区的唯一方式。回答问题、帮助他人以及改进文档也同样宝贵。

如果您能传播 🤗 Transformers，也将对我们有所帮助！在关于它所支持的优秀项目的博文中引用该库，每次它帮助到您时都在 Twitter 上喊话，或者简单地为存储库添加 ⭐ 以表示感谢。

无论您选择以何种方式贡献，请注意并尊重我们的行为准则。

本指南的灵感很大程度上来自优秀的 scikit-learn 贡献指南。

贡献方式

您可以通过多种方式为 🤗 Transformers 贡献力量。

修复现有代码中的未解决问题。
提交与错误或所需新功能相关的 issue。
实现新的模型。
为示例或文档做出贡献。

如果您不知道从哪里开始，有一个特殊的新手友好 issue 列表。它会为您提供一系列适合初学者且有助于您开始参与开源项目的未解决 issue。最好的方法是打开一个 Pull Request 并将其链接到您想要处理的 issue。我们会尽量优先处理已打开的 PR，因为我们可以轻松跟踪修复的进度，如果贡献者不再有时间，其他人也可以接手 PR。

对于稍微更具挑战性的任务，您还可以查看中等难度 issue 列表。不过，总的来说，如果您觉得自己知道自己在做什么，那就放手去做吧，我们会帮助您实现目标！🚀

所有贡献对社区都同等宝贵。🥰

修复未解决的问题

如果您发现现有代码存在问题并且有修复方案，请随时开始贡献并打开一个 Pull Request！

提交与错误相关的 issue 或功能请求

在提交与错误相关的 issue 或功能请求时，请尽力遵循以下指南。这将使我们更容易快速地回复您并提供良好的反馈。

您是否发现了错误？

感谢用户的报告，🤗 Transformers 库才变得强大可靠。

在您报告 issue 之前，如果您能 **确保该错误尚未被报告**（在 GitHub 的 Issues 中使用搜索栏），我们将不胜感激。您的 issue 也应该与库本身的错误相关，而不是您的代码。如果您不确定错误是在您的代码中还是在库中，请先在论坛或我们的 Discord 中询问。这有助于我们更快地响应修复与库相关的 issue，而不是一般的疑问。

我们有一个文档机器人，我们强烈建议您在那里提出所有问题。您的错误可能只需一个简单的标记就能解决 👾🔫。

确认错误尚未被报告后，请在您的 issue 中包含以下信息，以便我们快速解决它。

您的 **操作系统类型和版本** 以及 **Python**、**PyTorch** 和 **TensorFlow** 版本（如适用）。
一个简短的、独立的、代码片段，使我们能够在 30 秒内重现错误。
如果引发异常，则提供 *完整* 的回溯信息。
附加您认为可能有所帮助的任何其他附加信息，例如屏幕截图。

要自动获取操作系统和软件版本，请运行以下命令。

transformers-cli env

您也可以从存储库的根目录运行相同的命令。

python src/transformers/commands/transformers_cli.py env

您是否想要一个新功能？

如果您希望在 🤗 Transformers 中看到一个新功能，请打开一个 issue 并描述：

此功能的 *动机* 是什么？它是否与库相关的问题或困扰有关？它是否与您项目所需的功能有关？它是否为您的工作成果，且您认为可以惠及社区？

无论是什么，我们都期待了解！
尽可能详细地描述您请求的功能。您能告诉我们的信息越多，我们就越能帮助您。
提供一个 *代码片段* 来演示功能的使用。
如果该功能与论文相关，请提供链接。

如果您的 issue 写得很好，那么在您创建它时，我们就已经完成了 80% 的工作。

我们添加了模板来帮助您开始编写 issue。

您是否想要实现一个新的模型？

新的模型不断发布，如果您想实现一个新的模型，请提供以下信息：

模型的简短描述和论文链接。
如果模型是开源的，请提供实现链接。
如果模型权重可用，请提供链接。

如果您愿意自己贡献模型，请告诉我们，以便我们帮助您将其添加到 🤗 Transformers！

我们有一个关于如何将模型添加到 🤗 Transformers 的技术指南。

您想添加文档吗？

我们一直在寻求改进文档，使其更清晰、更准确。请告知我们如何改进文档，例如错别字以及任何缺失、不清楚或不准确的内容。如果您有兴趣，我们将很乐意进行更改或帮助您做出贡献！

有关如何生成、构建和编写文档的更多详细信息，请查看文档的 README。

创建 Pull Request

在编写任何代码之前，我们强烈建议您搜索现有的 PR 或问题，以确保没有人已经在处理相同的事情。如果您不确定，最好始终打开一个问题以获取一些反馈。

您需要具备基本的 git 技能才能为 🤗 Transformers 做出贡献。虽然 git 不是最容易使用的工具，但它拥有最完善的手册。在 shell 中键入 git --help 并尽情享受吧！如果您更喜欢书籍，Pro Git 是一个非常好的参考。

您需要 Python 3.8 或更高版本才能为 🤗 Transformers 做出贡献。请按照以下步骤开始贡献

通过点击代码库页面上的 Fork 按钮，分叉代码库。这将在您的 GitHub 用户帐户下创建代码副本。

将您的分叉克隆到本地磁盘，并将基础代码库添加为远程库

git clone git@github.com:<your Github handle>/transformers.git
cd transformers
git remote add upstream https://github.com/huggingface/transformers.git

创建一个新的分支来保存您的开发更改
```
git checkout -b a-descriptive-name-for-my-changes
```
🚨 不要在 main 分支上工作！
在虚拟环境中运行以下命令来设置开发环境
```
pip install -e ".[dev]"
```
如果 🤗 Transformers 已经安装在虚拟环境中，请在使用 -e 标志以可编辑模式重新安装它之前，使用 pip uninstall transformers 卸载它。

根据您的操作系统，并且由于 Transformers 的可选依赖项数量不断增加，您可能会遇到此命令失败的情况。如果是这种情况，请确保安装您正在使用的深度学习框架（PyTorch、TensorFlow 和/或 Flax），然后执行
```
pip install -e ".[quality]"
```
这对于大多数用例来说应该足够了。
在您的分支中开发功能。

在处理代码时，您应该确保测试套件通过。像这样运行受您的更改影响的测试
```
pytest tests/<TEST_TO_RUN>.py
```
有关测试的更多信息，请查看测试指南。

🤗 Transformers 依靠 black 和 ruff 来一致地格式化其源代码。在进行更改后，应用自动样式校正和无法一次自动化的代码验证
```
make fixup
```
此目标也经过优化，仅适用于您正在处理的 PR 修改的文件。

如果您更喜欢依次运行检查，则以下命令应用样式校正
```
make style
```
🤗 Transformers 还使用 ruff 和一些自定义脚本来检查编码错误。质量控制由 CI 运行，但您可以使用以下命令运行相同的检查
```
make quality
```
最后，我们有很多脚本来确保我们在添加新模型时不会忘记更新某些文件。您可以使用以下命令运行这些脚本
```
make repo-consistency
```
要了解有关这些检查以及如何修复任何问题的更多信息，请查看 Pull Request 检查指南。

如果您正在修改 docs/source 目录下的文档，请确保文档仍然可以构建。此检查也将在您打开 Pull Request 时在 CI 中运行。要运行本地检查，请确保您已安装文档构建器
```
pip install ".[docs]"
```
从代码库的根目录运行以下命令
```
doc-builder build transformers docs/source/en --build_dir ~/tmp/test-build
```
这将在 ~/tmp/test-build 文件夹中构建文档，您可以在其中使用您喜欢的编辑器检查生成的 Markdown 文件。您也可以在打开 Pull Request 时在 GitHub 上预览文档。

对更改满意后，使用 git add 添加已更改的文件，并使用 git commit 在本地记录更改
```
git add modified_file.py
git commit
```
请记住编写良好的提交信息以清楚地传达您所做的更改！

要使您代码的副本与原始代码库保持同步，请在打开 Pull Request 之前或在维护人员要求时，将您的分支重新定位到 upstream/branch 上
```
git fetch upstream
git rebase upstream/main
```
将您的更改推送到您的分支
```
git push -u origin a-descriptive-name-for-my-changes
```
如果您已经打开了一个 Pull Request，则需要使用 --force 标志强制推送。否则，如果 Pull Request 尚未打开，则可以正常推送更改。
现在，您可以转到 GitHub 上您代码库的分叉，然后点击 Pull Request 以打开一个 Pull Request。请确保勾选了我们下面清单中的所有复选框。准备好后，您可以将更改发送给项目维护人员以供审查。
如果维护人员要求更改，这是可以接受的，即使是我们核心贡献者也会遇到这种情况！因此，每个人都可以看到 Pull Request 中的更改，在您的本地分支中工作并将更改推送到您的分叉。它们将自动出现在 Pull Request 中。

Pull Request 清单

☐ Pull Request 标题应总结您的贡献。
☐ 如果您的 Pull Request 解决了某个问题，请在 Pull Request 描述中提及问题编号，以确保它们关联起来（并且查看问题的人知道您正在处理它）。
☐ 要指示正在进行的工作，请在标题前加上 [WIP]。这些对于避免重复工作以及将其与准备合并的 PR 区分开来很有用。
☐ 确保现有的测试通过。
☐ 如果添加新功能，也要为其添加测试。

如果您添加了一个新的模型，请确保使用 ModelTester.all_model_classes = (MyModel, MyModelWithLMHead,...) 来触发通用测试。
如果您添加了新的 @slow 测试，请确保它们使用 RUN_SLOW=1 python -m pytest tests/models/my_new_model/test_my_new_model.py 通过。
如果您添加了一个新的分词器，请编写测试并确保 RUN_SLOW=1 python -m pytest tests/models/{your_model_name}/test_tokenization_{your_model_name}.py 通过。
CircleCI 不会运行缓慢的测试，但 GitHub Actions 每晚都会运行！

☐ 所有公共方法都必须具有信息丰富的文档字符串（有关示例，请参阅 modeling_bert.py）。
☐ 由于代码库正在快速增长，请不要添加任何图像、视频和其他非文本文件，这些文件会显著增加代码库的体积。相反，使用 Hub 代码库（例如 hf-internal-testing）来托管这些文件，并通过 URL 引用它们。我们建议将与文档相关的图像放置在以下代码库中：huggingface/documentation-images。您可以在此数据集代码库上打开一个 PR 并要求 Hugging Face 成员合并它。

有关在 Pull Request 上运行的检查的更多信息，请查看我们的 Pull Request 检查指南。

测试

包含一个广泛的测试套件来测试库行为和一些示例。库测试可以在 tests 文件夹中找到，示例测试可以在 examples 文件夹中找到。

我们喜欢 pytest 和 pytest-xdist，因为它们速度更快。从代码库的根目录，指定要运行测试的子文件夹或测试文件的路径

python -m pytest -n auto --dist=loadfile -s -v ./tests/models/my_new_model

类似地，对于 examples 目录，指定要运行测试的子文件夹或测试文件的路径。例如，以下命令测试 PyTorch examples 目录中的文本分类子文件夹

pip install -r examples/xxx/requirements.txt  # only needed the first time
python -m pytest -n auto --dist=loadfile -s -v ./examples/pytorch/text-classification

事实上，这实际上是我们 make test 和 make test-examples 命令的实现方式（不包括 pip install）！

您还可以指定更小的测试集，以便仅测试您正在处理的功能。

默认情况下，速度慢的测试会被跳过，但您可以将RUN_SLOW环境变量设置为yes来运行它们。这将下载许多 GB 的模型，因此请确保您有足够的磁盘空间、良好的网络连接或足够的耐心！

请记住指定要运行测试的子文件夹或测试文件的路径。否则，您将运行tests或examples文件夹中的所有测试，这将花费很长时间！

RUN_SLOW=yes python -m pytest -n auto --dist=loadfile -s -v ./tests/models/my_new_model
RUN_SLOW=yes python -m pytest -n auto --dist=loadfile -s -v ./examples/pytorch/text-classification

与速度慢的测试类似，还有其他一些环境变量在测试期间默认情况下未启用。

RUN_CUSTOM_TOKENIZERS：启用自定义分词器的测试。
RUN_PT_FLAX_CROSS_TESTS：启用 PyTorch + Flax 集成的测试。
RUN_PT_TF_CROSS_TESTS：启用 TensorFlow + PyTorch 集成的测试。

更多环境变量和额外信息可以在testing_utils.py中找到。

🤗 Transformers仅使用pytest作为测试运行器。它本身的测试套件中不使用任何pytest特定的功能。

这意味着完全支持unittest。以下是如何使用unittest运行测试

python -m unittest discover -s tests -t . -v
python -m unittest discover -s examples -t examples -v

样式指南

对于文档字符串，🤗 Transformers遵循Google Python 样式指南。查看我们的文档编写指南以获取更多信息。

在 Windows 上开发

在 Windows 上（除非您在Windows 子系统 Linux 或 WSL 中工作），您需要配置 git 将 Windows 的CRLF换行符转换为 Linux 的LF换行符。

git config core.autocrlf input

在 Windows 上运行make命令的一种方法是使用 MSYS2。

下载 MSYS2，我们假设它安装在C:\msys64中。
打开命令行C:\msys64\msys2.exe（它应该可以通过**开始**菜单访问）。
在 shell 中运行：pacman -Syu并使用pacman -S make安装make。
将C:\msys64\usr\bin添加到您的 PATH 环境变量中。

您现在可以从任何终端（PowerShell、cmd.exe 等）使用make了！🎉

将分支存储库与上游主分支（Hugging Face 存储库）同步

更新分支存储库的主分支时，请按照以下步骤操作，以避免 ping 上游存储库，这会为每个上游 PR 添加参考注释，并向参与这些 PR 的开发人员发送不必要的通知。

如果可能，请避免使用分支和 PR 在分支存储库中与上游同步。而是直接合并到分支的主分支中。

如果绝对需要 PR，请在检出您的分支后执行以下步骤

git checkout -b your-branch-for-syncing
git pull --squash --no-commit upstream main
git commit -m '<your message without GitHub references>'
git push --set-upstream origin your-branch-for-syncing

< > 在 GitHub 上更新

←使用`torch.compile()`优化推理如何将模型添加到 🤗 Transformers？→