为 🤗 Transformers 做贡献

贡献规则

打开 PR 有两种方式：修复一个开放贡献的 issue，或者提交一个自带证据的独立 PR。也可以通过独立 PR 添加新模型，参见添加新模型。Hugging Face 员工、维护者以及部分资深贡献者不受这些规则的限制。

修复问题。 在 PR 描述中，使用诸如 Fixes #123 之类的关闭关键字来关联该问题。您可以处理以下问题：

您提交的 issue，在维护者将其标记为 triaged 之后
一个标记为 contributions-welcome 的问题
一个标记为 New model 的问题，请参阅添加新模型

除非维护者明确说明，否则他人的问题不开放用于提交 PR。链接到您无法处理的问题的 PR 将会被关闭。

对于符合条件的 issue，你无需事先询问即可着手处理，我们也不会将 issue 分配给特定人员。诸如“我可以处理这个吗？”或“请把这个分配给我”之类的评论只会增加噪音，因此请跳过这些评论，直接提交你的 PR。针对某个 issue 的第一个 PR 会获得优先处理。

在处理 contributions-welcome 或 New model 问题之前，请检查是否已有人为此提交了 PR。如果有，请勿再提交另一个。如果你发现错误，请在现有 PR 上留下建议。只有当现有 PR 存在根本性缺陷或已停滞时，才提交竞争性的 PR：即其作者两周未回复审查评论或未推送更改。等待维护者审查的 PR 不算停滞。无论如何，在提交你的 PR 之前，请先在问题中说明原因。

独立的 PR。如果还没有人报告该问题，你可以直接提交 PR 而无需先创建 issue。独立的 PR 适用于具有实际影响的简短更改，例如修复 bug、提升性能，或修复文档中损坏的示例。PR 描述需要提供与 issue 相同的证据：

针对某个 bug，提供一个简短的脚本，该脚本在 main 分支上运行失败，但在应用你的修复后运行成功，并且使用已发布的检查点、默认配置或文档中记载的工作流
以实现性能提升为目的，需提供在真实工作负载（例如已发布的检查点或默认配置）下运行前后的性能数据，以及你所使用的硬件。针对非关键路径上某个函数的更快的微基准测试不计入在内。

如果该问题已存在对应的 issue，无论你是否在 PR 中关联该 issue，你的 PR 都将通过该 issue 进行处理。独立提交且用于修复已有 issue 的 PR，或没有提供相关证据的 PR，将会被关闭。这些要求不适用于新模型。

需要先创建 issue 的更改。 不影响正确性或性能的机械式清理，以及对文档中拼写错误或措辞的批量修正，在提交 PR 之前需要先创建 issue。请提出更改内容、具体实现方式以及涉及的文件数量。单个拼写错误修正太小，无论走哪条路径都不适合单独提交 PR。

审查他人的 PR。 当社区成员的审查意见能带来新信息时，我们非常欢迎。不过，维护者会阅读 PR 上的每一条评论，并且我们也会运行自己的审查工具。在评论一个并非由你发起的 PR 之前，请确保你有具体的内容要表达：

如果您发现了问题或有具体的修改建议，请在相关行留下内联评论，最好以 GitHub 建议的形式提交，以便作者可以直接应用。如果您在报告 bug，提供复现步骤会有所帮助。
如果您报告了该 PR 所修复的问题，请简短说明它是否解决了您的情况，这将非常有帮助。
请不要发布笼统的总结或“我测试过了，可以正常工作”之类的报告。非维护者的批准不会影响 PR 是否被合并，而一条重复 PR 内容的长评论只会浪费我们的时间，却不会改变结果。

代码的编写方式由您自行决定，但您需对提交的所有内容负责。对于反复提交低质量 issue 或 PR 的账户，我们可能会将其封禁。同时，请遵守我们的行为准则。

What we look for in issues and PRs

准确诊断 bug。快速的临时解决方案往往会导致代码臃肿或与其他模型不兼容。花时间追踪问题的确切原因，尤其是定位首次出现该问题的提交（例如使用 git bisect），是很有价值的。
最小化差异。检查你的 PR，消除任何不必要的更改。确保你没有提交任何测试脚本或不相关的文件。仅在真正必要时添加注释。如果你的 PR 可以是一个单行修复，那就让它保持为单行修复。这会让 PR 更容易审查，并提高其被接受的可能性。
花些时间复现该问题。用户报告的 issue 往往实际上是由其机器上的环境问题引起的，或者他们误诊了问题并提出了无效的解决方案。过度信任报告会导致糟糕的解决方案，有时甚至是针对根本不存在的问题！编写一个简单的复现脚本并运行它，以确认你确实能看到该问题，这是非常有价值的。
与其他模型进行比较。Transformers 仓库非常庞大，许多模型都在做类似的事情。在修复 bug 时，查看该 bug 是否也存在于其他模型中是很有价值的。如果你的 PR 中写道“通过采用与（其他模型）相同的方法来修复”，并附上相关代码的链接，这对维护者非常有帮助，因为这表明该修复方案很可能是正确的，并且与代码库的其余部分兼容。
避免提交“琐碎”的 PR。我们没有时间处理小的样式更改或注释中的拼写错误，也不接受针对代码分析发现的“理论性 bug”的修复，除非这些 bug 在实际中几乎从不引发问题，或者可以被攻击者利用。
在本地和 CI 中验证测试。在提交 PR 之前，请运行 make fix-repo，并使用 utils/tests_fetcher.py 查看覆盖你在 PR 分支中修改的文件的测试列表。在本地运行这些测试，并确保在提交 PR 之前它们全部通过。提交 PR 后，请确认 CI 状态为绿色，并在通知任何人进行审查之前修复所有问题！这能大幅减少通知干扰，让维护者保持理智。

设置

在 GitHub 上点击 Fork 按钮，将 Transformers 分叉到你自己的账户下，然后在本地克隆该仓库。
```
git clone git@github.com:<your Github handle>/transformers.git
cd transformers
```

将 Transformers 仓库添加为名为 upstream 的远程仓库。origin 指向你的 fork，upstream 指向权威源。这样你就可以在推送到 origin 并打开 PR 之前，先同步本地的 main。

git remote add upstream https://github.com/huggingface/transformers.git
git remote -v
# origin    git@github.com:<your Github handle>/transformers.git (fetch)
# origin    git@github.com:<your Github handle>/transformers.git (push)
# upstream  https://github.com/huggingface/transformers.git (fetch)
# upstream  https://github.com/huggingface/transformers.git (push)

保持你的 fork 为最新状态，并创建一个分支开始工作。你也可以通过 GitHub 界面使用 Sync fork 按钮来同步你的 fork。
```
git checkout main && git pull upstream main && git push origin main
git switch -c a-descriptive-name-for-my-branch
```
以可编辑模式安装该库。对于大多数贡献，请使用 [dev]，因为它包含了用于样式和质量检查所需的开发工具。对于模型贡献，请使用 [torch,testing]；对于仅涉及文档的更改或小型修复，当不需要完整的开发依赖集时，请使用 [quality]。
```
pip install -e ".[dev]"

# for model contributions
pip install -e ".[torch,testing]"

# for docs-only changes and small fixes
pip install -e ".[quality]"
```

Windows

在 Windows 上，除非你正在使用 WSL，否则请配置 git 将 CRLF 行尾转换为 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。

提交问题

请使用问题模板，并确保该问题尚未被报告（使用 GitHub 上 Issues 下的搜索栏）。Bug 报告应针对 Transformers 中的 bug，而非您自己代码中的 bug，并且应影响实际使用场景和实际的检查点；通过阅读代码发现的、需要非常规配置才能触发的“理论性 bug”不会被分诊，除非它是安全问题。请包含一个简短且自包含的脚本，用于在最新发布的版本或 main 上复现该 bug，并使用已发布的检查点或默认配置。没有可运行复现脚本的 Bug 报告将不会被分诊。

如果您不确定 bug 是出在自己的代码中还是库中，请先在论坛或 Discord 上提问。这有助于让 GitHub 专注于可操作的库问题。

添加新模型

将模型添加到 Transformers 后，任何人都可以加载该模型并进行微调或执行推理。在开始实现之前，请梳理你的架构与 Transformers 中已有的最新先进模型之间的差异。在 issue 或 PR 中说明这些差异，以便审阅者能够快速理解该模型带来的挑战、哪些部分可以复用现有模式，以及哪些部分需要在各模型之间进行标准化。

请按照以下指南操作。

使用模块化 Transformers 添加模型 — 使用模块化文件实现模型，并生成独立的建模文件。
自动生成文档字符串 — 使用 @auto_docstring 装饰器，无需样板代码即可生成一致的文档字符串。
测试 — 编写并运行模型测试以验证正确性，确保贡献易于维护。对于因果语言模型，尽可能继承自因果语言模型测试器。优先进行集成测试，因为它们针对真实检查点验证完整的处理器、分词器和模型路径。
模型结构规则 — 请检查您的文件是否通过了 make typing 强制执行的静态模型结构规则。

某些模型的添加需要额外的集成工作。

如果模型需要图像或视频输入，请添加视觉处理组件。
当已发布的检查点参数名称与 Transformers 实现不匹配时，使用动态权重加载。

模型添加时间线

根据模型贡献者的情况以及社区对特定架构的需求，模型添加有四种不同的时间线。

Day-0 集成：在模型发布当天，通过发布新版本使其在 Transformers 中可用。我们提供支持以实现最重要的核心功能（量化、FlashAttention、KV-cache 等），审阅早期草稿，并可根据时间安排负责模型实现。

请提前几周向 transformers@huggingface.co 发送邮件，尤其是针对新颖的架构。我们将会在私有分支上与您进行迭代，直到您的检查点和发布准备就绪。
同周集成：高需求模型通常在一周内上线，即使作者没有主动联系。

使用新模型模板提交一个 issue 以提出请求。互动越多的 issue 在队列中排得越快。
发布后集成：对于需求不强烈或我们没有足够资源承接的模型，将在上游版本发布之后才进行集成。

外部贡献者可以直接为新的模型提交 PR，无论是否已创建 issue。在开始之前，请检查已打开的 “New model” issue 和已打开的 PR，以确保没有其他人正在添加该模型。我们将进行审查并指导你完成整个过程。
优先在 Hub 上发布：借助 Transformers 的 remote-code 支持，您可以直接在 Hub 上发布模型，无需提交上游 PR。

许多流行的 Hub 优先模型通常会在后续版本中被集成到 Transformers 中，从而获得一流的文档、维护和优化支持。Hub 优先是添加模型时摩擦最小的方式。不过，如果模型需要权重转换或存在其他向后兼容性问题，这种方式可能会更加脆弱。

文档

对于从源文件生成的 API 参考，在适用时使用 @auto_docstring 装饰器。有关如何编辑文档以及我们使用的语法的更多详细信息，请参阅文档的 README。

Update on GitHub