贡献 🤗 Transformers

我们欢迎所有人做出贡献，并珍视每个人的贡献。代码贡献并不是帮助社区的唯一方式。回答问题、帮助他人和改进文档也具有巨大的价值。

如果您能口口相传，也会对我们有所帮助！在关于其实现的精彩项目的博客文章中引用该库，在 Twitter 上每次它帮助到您时都大声宣传，或者仅仅给仓库加星以示感谢。

无论您选择如何贡献，请注意并遵守我们的行为准则。

本指南深受出色的scikit-learn 贡献指南的启发。

贡献方式

有几种方式可以为 🤗 Transformers 做出贡献

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

如果您不知道从何开始，有一个特殊的首个良好问题列表。它会为您提供一份对初学者友好的开放问题列表，帮助您开始为开源做贡献。最好的方法是打开一个拉取请求并将其链接到您想要处理的问题。我们尽量优先处理已打开的拉取请求，因为我们可以轻松跟踪修复进度，如果贡献者没有时间，其他人可以接手拉取请求。

对于稍微更具挑战性的任务，您也可以查看第二个良好问题列表。但总的来说，如果您觉得您知道自己在做什么，尽管去做，我们会帮助您实现目标！🚀

所有贡献对社区都同样有价值。🥰

修复未决问题

如果您发现现有代码存在问题并已有修复方案，请随时开始贡献并开启一个拉取请求！

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

提交与错误相关的问题或功能请求时，请尽量遵循以下准则。这将使我们能够更快地回复您并提供良好的反馈。

您发现错误了吗？

🤗 Transformers 库之所以健壮可靠，归功于用户报告他们遇到的问题。

在您报告问题之前，如果您能**确保该错误尚未被报告**（使用 GitHub 上“问题”下的搜索栏），我们将不胜感激。您的问题也应与库本身的错误相关，而非您的代码。如果您不确定错误是在您的代码中还是在库中，请先在论坛或我们的Discord上提问。这有助于我们更快地解决与库相关的错误，而不是一般性问题。

我们有一个文档机器人，我们强烈建议您在那里提出所有问题。您的错误总有可能通过一个简单的标志来修复 👾🔫

一旦您确认该错误尚未被报告，请在您的问题中包含以下信息，以便我们快速解决：

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

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

transformers env

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

python src/transformers/commands/transformers_cli.py env

您想要一个新功能吗？

如果您希望在 🤗 Transformers 中看到新功能，请开启一个问题并描述

此功能背后的*动机*是什么？它是否与库中的问题或挫败感相关？它是否是您项目所需的功能？它是否是您研究过并认为可能对社区有益的功能？

无论是什么，我们都乐意听到！
尽可能详细地描述您请求的功能。您提供的信息越多，我们就能更好地帮助您。
提供一个*代码片段*来演示该功能的使用。
如果该功能与某篇论文相关，请附上链接。

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

我们添加了模板来帮助您开始您的问题。

您想实现新模型吗？

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

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

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

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

您想添加文档吗？

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

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

创建拉取请求

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

您需要基本的 `git` 熟练度才能为 🤗 Transformers 做出贡献。虽然 `git` 不是最容易使用的工具，但它拥有最棒的手册。在 shell 中输入 `git --help` 即可享受！如果您更喜欢书籍，Pro Git 是一个非常好的参考。

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

通过点击仓库页面上的**Fork**按钮来派生仓库。这会在您的 GitHub 用户账号下创建一个代码副本。

将您的 fork 克隆到本地磁盘，并将基础仓库添加为远程仓库。

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，请使用 `pip uninstall transformers` 将其删除，然后使用 `-e` 标志以可编辑模式重新安装。

根据您的操作系统，并且由于 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
```
要了解有关这些检查以及如何解决其中任何问题的更多信息，请查看拉取请求检查指南。

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

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

为了使您的代码副本与原始仓库保持同步，在您打开拉取请求之前或在维护者要求时，请在 `upstream/branch` 上重新设置您的分支
```
git fetch upstream
git rebase upstream/main
```
将您的更改推送到您的分支
```
git push -u origin a-descriptive-name-for-my-changes
```
如果您已经打开了一个拉取请求，您需要使用 `—force` 标志进行强制推送。否则，如果拉取请求尚未打开，您可以正常推送您的更改。
现在您可以访问您在 GitHub 上的仓库派生，然后单击**拉取请求**以打开一个拉取请求。请确保您勾选了下面清单中的所有框。准备就绪后，您可以将更改发送给项目维护者进行审查。
维护者要求更改是正常的，我们的核心贡献者也会遇到！为了让所有人都能在拉取请求中看到更改，请在您的本地分支中工作并将更改推送到您的派生。它们将自动显示在拉取请求中。

拉取请求清单

☐ 拉取请求标题应概括您的贡献。
☐ 如果您的拉取请求解决了某个问题，请在拉取请求描述中提及问题编号，以确保它们已链接（并且查看该问题的人知道您正在处理它）。
☐ 为了表明正在进行中的工作，请在标题前加上 `[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 成员合并。

有关拉取请求上运行的检查的更多信息，请查看我们的拉取请求检查指南。

测试

包含一个广泛的测试套件，用于测试库行为和几个示例。库测试可以在 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` 来运行它们。这将下载许多千兆字节的模型，因此请确保您有足够的磁盘空间、良好的互联网连接或足够的耐心！

请记住指定*子文件夹或测试文件的路径*来运行测试。否则，您将运行 `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`: 启用自定义分词器的测试。

更多环境变量和附加信息可在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 上（除非您在适用于 Linux 的 Windows 子系统或 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 上更新