Hugging Face 的标志

Transformers 文档

为 🤗 Transformers 贡献力量

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

为 🤗 Transformers 贡献力量

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

如果您能广而告之，那对我们也有帮助！在关于它实现的精彩项目的博客文章中引用该库，每次它帮助您时都在 Twitter 上大声疾呼，或者只是为存储库加星标 ⭐️ 以表示感谢。

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

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

贡献方式

您可以通过以下几种方式为 🤗 Transformers 做出贡献

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

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

对于稍微具有挑战性的内容，您还可以查看 Good Second Issue 列表。但总的来说，如果您觉得自己知道自己在做什么，那就放手去做，我们会帮助您实现目标！🚀

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

修复未解决的问题

如果您发现现有代码有问题并想到了修复方法，请随时开始贡献并打开一个 Pull Request！

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

提交与错误相关的问题或功能请求时，请尽力遵循这些准则。这将使我们更容易快速回复您并提供良好的反馈。

您发现错误了吗？

得益于报告他们遇到的问题的用户，🤗 Transformers 库是健壮且可靠的。

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

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

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

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

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

transformers-cli env

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

python src/transformers/commands/transformers_cli.py env

您想要新功能吗？

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

  1. 此功能背后的动机是什么？它是否与库的问题或挫败感有关？它是否与您项目需要的功能有关？这是您从事的工作，并且认为它可能使社区受益吗？

    无论是什么，我们都很乐意听到！

  2. 尽可能详细地描述您请求的功能。您告诉我们关于它的信息越多，我们就越能更好地帮助您。

  3. 提供一个代码片段，演示该功能的用法。

  4. 如果该功能与论文相关，请包含链接。

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

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

您想实现新模型吗？

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

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

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

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

您想添加文档吗？

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

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

创建 Pull Request

在编写任何代码之前，我们强烈建议您搜索现有的 PR 或 issue，以确保没有人已经在做同样的事情。如果您不确定，最好先打开一个 issue 以获得一些反馈。

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

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

  1. 通过单击存储库页面上的 Fork 按钮来 Fork 存储库。这会在您的 GitHub 用户帐户下创建代码副本。

  2. 将您的 Fork 克隆到本地磁盘，并将基本存储库添加为远程仓库

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

  3. 创建一个新分支来保存您的开发更改

    git checkout -b a-descriptive-name-for-my-changes

    🚨 不要在 main 分支上工作！

  4. 通过在虚拟环境中运行以下命令来设置开发环境

    pip install -e ".[dev]"

    如果虚拟环境中已安装 🤗 Transformers，请先使用 pip uninstall transformers 卸载它，然后再使用 -e 标志以可编辑模式重新安装它。

    根据您的操作系统，并且由于 Transformers 的可选依赖项数量不断增加，您可能会在此命令中遇到失败。如果发生这种情况，请确保安装您正在使用的深度学习框架（PyTorch、TensorFlow 和/或 Flax），然后执行

    pip install -e ".[quality]"

    这应该足以满足大多数用例。

  5. 在您的分支中开发功能。

    在您编写代码时，您应该确保测试套件通过。像这样运行受您的更改影响的测试

    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 hf-doc-builder

    从存储库的根目录运行以下命令

    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 尚未打开，您可以正常推送您的更改。

  6. 现在您可以转到 GitHub 上您的存储库 fork，然后单击 Pull Request 以打开 pull request。确保您勾选了下面 checklist 上的所有框。准备就绪后，您可以将您的更改发送给项目维护人员进行审核。

  7. 维护人员请求更改是可以的，我们的核心贡献者也会发生这种情况！为了让每个人都能在 pull request 中看到更改，请在您的本地分支中工作并将更改推送到您的 fork。它们将自动显示在 pull request 中。

Pull request checklist

☐ Pull request 标题应概括您的贡献。
☐ 如果您的 pull request 解决了某个 issue，请在 pull request 描述中提及 issue 编号，以确保它们已链接（并且查看 issue 的人知道您正在处理它）。
☐ 要指示正在进行的工作，请在标题前加上 [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 通过。
  • 如果您要添加新的 tokenizer，请编写测试并确保 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：启用自定义 tokenizer 的测试。

更多环境变量和其他信息可以在 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

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

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

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

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

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

  2. 如果绝对需要 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 上更新

←故障排除 Transformers 模型测试→