贡献给 🤗 Transformers
欢迎所有人贡献,我们珍视每个人的贡献。代码贡献并不是帮助社区的唯一方式。回答问题、帮助他人以及改进文档也是非常有价值的。
如果您能帮忙宣传,对我们也有很大帮助!在博客文章中引用这个库,介绍它实现的精彩项目,每次它在Twitter上帮助您时大声喊出来,或者简单地为仓库点个⭐️以表示感谢。
无论你选择如何贡献,请务必注意并尊重我们的 行为准则。
本指南深受精彩的scikit-learn贡献指南的启发。
贡献方式
有几种方式可以为🤗 Transformers做出贡献:
- 修复现有代码中的突出问题。
- 提交与错误或期望的新功能相关的问题。
- 实现新模型。
- 为示例或文档做出贡献。
如果你不知道从哪里开始,有一个特别的Good First Issue列表。它会给你一个适合初学者的开放问题列表,并帮助你开始为开源项目做贡献。最好的方法是打开一个Pull Request并将其链接到你想要处理的问题。我们会尽量优先处理已打开的PR,因为我们可以轻松跟踪修复的进度,如果贡献者没有时间了,其他人可以接手这个PR。
如果你想挑战一些稍微复杂的内容,你也可以查看Good Second Issue列表。不过一般来说,如果你觉得自己知道自己在做什么,那就大胆去做吧,我们会帮助你达成目标!🚀
所有的贡献对社区来说都是同等宝贵的。🥰
修复未解决的问题
如果您注意到现有代码存在问题并且有修复的想法,请随时开始贡献并打开一个拉取请求!
提交与错误相关的问题或功能请求
在提交与错误相关的问题或功能请求时,请尽力遵循这些指南。这将使我们更容易快速回复您并提供良好的反馈。
你发现了一个bug吗?
🤗 Transformers 库之所以强大且可靠,得益于用户报告他们遇到的问题。
在您报告问题之前,我们非常希望您能确认该错误尚未被报告(使用GitHub上的搜索栏在Issues下查找)。您的问题也应与库本身的错误相关,而不是您的代码。如果您不确定错误是在您的代码中还是库中,请先在论坛或我们的discord上询问。这有助于我们更快地响应与库相关的问题,而不是一般性问题。
我们有一个文档机器人,我们强烈建议您在那里提出所有问题。您的错误有可能通过一个简单的标志来修复 👾🔫
一旦确认该错误尚未被报告,请在您的问题中包含以下信息,以便我们能够快速解决它:
- 您的操作系统类型和版本以及适用的Python、PyTorch和TensorFlow版本。
- 一个简短、独立的代码片段,使我们能够在不到30秒的时间内重现错误。
- 如果引发异常,则显示完整的追溯信息。
- 附加任何其他你认为可能有帮助的附加信息,比如截图。
要自动获取操作系统和软件版本,请运行以下命令:
transformers-cli env
你也可以从仓库的根目录运行相同的命令:
python src/transformers/commands/transformers_cli.py env
你想要一个新功能吗?
如果您希望在🤗 Transformers中看到新功能,请打开一个问题并描述:
这个功能的动机是什么?它是否与库中的某个问题或挫折有关?它是否与您项目中需要的某个功能相关?是否是您曾经研究过并认为它可能对社区有益的东西?
无论是什么,我们都非常乐意听取您的意见!
尽可能详细地描述您请求的功能。您能提供的详细信息越多,我们就越能更好地帮助您。
提供一个代码片段来演示功能的使用。
如果该功能与论文相关,请包含一个链接。
如果你的问题描述得很好,那么在你创建它的时候,我们已经完成了80%的工作。
我们添加了模板来帮助您开始处理您的问题。
你想实现一个新模型吗?
新模型不断发布,如果您想实现一个新模型,请提供以下信息:
- 模型的简短描述和论文的链接。
- 如果实现是开源的,请链接到实现。
- 如果模型权重可用,则链接到模型权重。
如果您愿意自己贡献模型,请告诉我们,以便我们帮助您将其添加到🤗 Transformers中!
我们有一个技术指南,关于如何将模型添加到🤗 Transformers。
你想添加文档吗?
我们一直在寻找改进文档的方法,使其更加清晰和准确。请告诉我们如何改进文档,例如拼写错误以及任何缺失、不清楚或不准确的内容。如果您有兴趣,我们将很乐意进行更改或帮助您做出贡献!
有关如何生成、构建和编写文档的更多详细信息,请查看文档 README。
创建一个拉取请求
在编写任何代码之前,我们强烈建议您搜索现有的PR或问题,以确保没有人在做同样的事情。如果您不确定,最好先开一个问题以获得一些反馈。
你需要基本的 git
熟练度来为 🤗 Transformers 做出贡献。虽然 git
不是最容易使用的工具,但它有最全面的手册。在 shell 中输入 git --help
并享受吧!如果你更喜欢书籍,Pro Git 是一个非常好的参考。
你需要Python 3.9或更高版本来为🤗 Transformers做出贡献。按照以下步骤开始贡献:
通过点击仓库页面上的Fork按钮来分叉repository。这将在您的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
有关测试的更多信息,请查看 Testing 指南。
🤗 Transformers 依赖
black
和ruff
来一致地格式化其源代码。在您进行更改后,应用自动样式修正和代码验证,这些无法一次性自动完成,可以通过以下方式实现: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
标志进行强制推送。否则,如果拉取请求尚未打开,你可以正常推送你的更改。现在你可以前往你在 GitHub 上的仓库分支,点击Pull Request来打开一个拉取请求。请确保你勾选了我们下面检查清单中的所有选项。当你准备好后,你可以将你的更改发送给项目维护者进行审查。
如果维护者要求更改,这是可以的,我们的核心贡献者也会遇到这种情况!因此,每个人都可以在拉取请求中看到更改,在您的本地分支中工作并将更改推送到您的分支。它们将自动出现在拉取请求中。
拉取请求清单
☐ 拉取请求的标题应总结您的贡献。
☐ 如果您的拉取请求解决了某个问题,请在拉取请求描述中提及问题编号,以确保它们被链接(并且查看问题的人知道您正在处理它)。
☐ 要表示正在进行中的工作,请在标题前加上[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 文件夹中。
我们喜欢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 Subsystem for 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 仓库)
在更新分叉仓库的主分支时,请按照以下步骤操作,以避免向上游仓库发送通知,这些通知会为每个上游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