Transformers 文档

为🤗 Transformers做出贡献

贡献给 🤗 Transformers

欢迎所有人贡献,我们珍视每个人的贡献。代码贡献并不是帮助社区的唯一方式。回答问题、帮助他人以及改进文档也是非常有价值的。

如果您能帮忙宣传,对我们也有很大帮助!在博客文章中引用这个库,介绍它实现的精彩项目,每次它在Twitter上帮助您时大声喊出来,或者简单地为仓库点个⭐️以表示感谢。

无论你选择如何贡献,请务必注意并尊重我们的 行为准则

本指南深受精彩的scikit-learn贡献指南的启发。

贡献方式

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

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

如果你不知道从哪里开始,有一个特别的Good First Issue列表。它会给你一个适合初学者的开放问题列表,并帮助你开始为开源项目做贡献。最好的方法是打开一个Pull Request并将其链接到你想要处理的问题。我们会尽量优先处理已打开的PR,因为我们可以轻松跟踪修复的进度,如果贡献者没有时间了,其他人可以接手这个PR。

如果你想挑战一些稍微复杂的内容,你也可以查看Good Second Issue列表。不过一般来说,如果你觉得自己知道自己在做什么,那就大胆去做吧,我们会帮助你达成目标!🚀

所有的贡献对社区来说都是同等宝贵的。🥰

修复未解决的问题

如果您注意到现有代码存在问题并且有修复的想法,请随时开始贡献并打开一个拉取请求!

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

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

你发现了一个bug吗?

🤗 Transformers 库之所以强大且可靠,得益于用户报告他们遇到的问题。

在您报告问题之前,我们非常希望您能确认该错误尚未被报告(使用GitHub上的搜索栏在Issues下查找)。您的问题也应与库本身的错误相关,而不是您的代码。如果您不确定错误是在您的代码中还是库中,请先在论坛或我们的discord上询问。这有助于我们更快地响应与库相关的问题,而不是一般性问题。

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

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

  • 您的操作系统类型和版本以及适用的PythonPyTorchTensorFlow版本。
  • 一个简短、独立的代码片段,使我们能够在不到30秒的时间内重现错误。
  • 如果引发异常,则显示完整的追溯信息。
  • 附加任何其他你认为可能有帮助的附加信息,比如截图。

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

transformers-cli env

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

python src/transformers/commands/transformers_cli.py env

你想要一个新功能吗?

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

  1. 这个功能的动机是什么?它是否与库中的某个问题或挫折有关?它是否与您项目中需要的某个功能相关?是否是您曾经研究过并认为它可能对社区有益的东西?

    无论是什么,我们都非常乐意听取您的意见!

  2. 尽可能详细地描述您请求的功能。您能提供的详细信息越多,我们就越能更好地帮助您。

  3. 提供一个代码片段来演示功能的使用。

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

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

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

你想实现一个新模型吗?

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

  • 模型的简短描述和论文的链接。
  • 如果实现是开源的,请链接到实现。
  • 如果模型权重可用,则链接到模型权重。

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

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

你想添加文档吗?

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

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

创建一个拉取请求

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

你需要基本的 git 熟练度来为 🤗 Transformers 做出贡献。虽然 git 不是最容易使用的工具,但它有最全面的手册。在 shell 中输入 git --help 并享受吧!如果你更喜欢书籍,Pro Git 是一个非常好的参考。

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

  1. 通过点击仓库页面上的Fork按钮来分叉repository。这将在您的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

    有关测试的更多信息,请查看 Testing 指南。

    🤗 Transformers 依赖 blackruff 来一致地格式化其源代码。在您进行更改后,应用自动样式修正和代码验证,这些无法一次性自动完成,可以通过以下方式实现:

    make fixup

    此目标也经过优化,仅适用于由您正在处理的PR修改的文件。

    如果您更喜欢逐个运行检查,以下命令将应用样式修正:

    make style

    🤗 Transformers 还使用 ruff 和一些自定义脚本来检查编码错误。质量 控制由 CI 运行,但您可以使用以下命令运行相同的检查:

    make quality

    最后,我们有很多脚本来确保在添加新模型时不会忘记更新某些文件。您可以使用以下命令运行这些脚本:

    make repo-consistency

    要了解更多关于这些检查以及如何修复其中的任何问题,请查看 Checks on a Pull Request 指南。

    如果你正在修改docs/source目录下的文档,请确保文档仍然可以构建。当你打开一个拉取请求时,这个检查也会在CI中运行。要进行本地检查,请确保你安装了文档构建器:

    pip install ".[docs]"

    从仓库的根目录运行以下命令:

    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标志进行强制推送。否则,如果拉取请求尚未打开,你可以正常推送你的更改。

  6. 现在你可以前往你在 GitHub 上的仓库分支,点击Pull Request来打开一个拉取请求。请确保你勾选了我们下面检查清单中的所有选项。当你准备好后,你可以将你的更改发送给项目维护者进行审查。

  7. 如果维护者要求更改,这是可以的,我们的核心贡献者也会遇到这种情况!因此,每个人都可以在拉取请求中看到更改,在您的本地分支中工作并将更改推送到您的分支。它们将自动出现在拉取请求中。

拉取请求清单

☐ 拉取请求的标题应总结您的贡献。
☐ 如果您的拉取请求解决了某个问题,请在拉取请求描述中提及问题编号,以确保它们被链接(并且查看问题的人知道您正在处理它)。
☐ 要表示正在进行中的工作,请在标题前加上[WIP]。这些有助于避免重复工作,并将其与准备合并的拉取请求区分开来。
☐ 确保现有测试通过。
☐ 如果添加新功能,请同时为其添加测试。

  • 如果您正在添加一个新模型,请确保使用 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 文件夹中。

我们喜欢pytestpytest-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 testmake test-examples命令的实现方式(不包括pip install)!

你也可以指定一个较小的测试集,以便仅测试你正在开发的功能。

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

记得指定一个子文件夹或测试文件的路径来运行测试。否则,你将运行testsexamples文件夹中的所有测试,这将花费很长时间!

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 Subsystem for Linux或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 了!🎉

同步分叉仓库与上游主仓库(Hugging Face 仓库)

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

  1. 如果可能,避免在分叉仓库中使用分支和PR与上游同步。相反,直接合并到分叉的主分支中。

  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
< > Update on GitHub