Transformers 贡献指南从 Issue 到 Pull Request 的完整开源协作流程【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers本篇技术指南基于 Transformers 仓库的官方贡献文档docs/source/de/contributing.md系统讲解参与 Transformers 开源贡献的完整链路如何规范地提交 Bug 报告与功能请求、如何实施一个新模型、如何配置可编辑开发环境、如何用pytest/unittest运行测试套件、如何用make style与make check-repo通过代码质量检查以及如何正确同步 fork 仓库。读完本文你将具备独立向 Transformers 提交可合并 Pull Request 所需的全部实操能力。贡献方式总览代码之外的价值同样重要Transformers 的官方贡献文档开篇明确指出任何人都可以贡献且代码贡献不是唯一途径。回答社区问题、帮助他人、改进文档都是极具价值的贡献方式甚至在博客中提及该项目、推荐该项目也被视为对社区的一种支持。无论以何种方式参与都需遵守仓库根目录的 行为准则。文档同时说明这份指南深受 scikit-learn 贡献指南的启发。具体到代码层面主要有四条贡献路径修复现有代码中的已知问题——这是新手最推荐、风险最低的切入点创建 Issue——报告 Bug 或提出新功能请求实现新模型——为社区补充新的模型架构贡献示例与文档——改进examples与docs的内容。如果不知道从哪里开始官方推荐从Good First Issue列表入手这类 Issue 面向初学者通常会先创建 Pull Request 并关联 Issue以便维护者追踪进度——如果贡献者中途没有时间继续其他人也可以接手该 PR。想要更大挑战的可以查看Good Second Issue标签。规范地提交 IssueBug 报告与功能请求报告 Bug 前必须完成的准备Transformers 文档强调报告的每一条新 Bug 都是库健壮性的来源。在创建 Issue 之前需要做到确认该 Bug 尚未被报告——使用 Issue 搜索功能排查重复项确认问题出在库本身而非你自己的代码——如果不确定官方建议先向社区论坛求助以免 Issue 区被一般性问题淹没。确认无误后Issue 中必须包含以下信息维护者才能快速复现和修复操作系统及版本以及Python、PyTorch、TensorFlow的版本如适用一个简短、独立的代码片段能在 30 秒内复现该 Bug抛出异常时的完整 Traceback其他有帮助的信息例如截图。为了自动输出操作系统与软件版本文档提供了两条命令transformers env也可以直接在仓库根目录运行python src/transformers/commands/transformers_cli.py env从当前仓库源码看env命令的实际实现位于 src/transformers/cli/system.py 的env()函数基于 typer 的 CLI 入口它会收集并打印transformers版本、平台信息、Python 版本、huggingface_hub版本、safetensors版本、accelerate版本及其配置文件、deepspeed版本以及 PyTorch 版本和加速器类型CUDA / XPU / NPU / HPU。因此 Issue 中贴出transformers env的完整输出是帮助维护者快速定位环境问题的标准做法。提交新功能请求的四要素如果希望 Transformers 增加某项新功能官方要求 Issue 包含动机——这项功能对应什么痛点或项目需求或者你是否已经尝试过实现尽可能详细的描述——提供的信息越多团队越能给出有效反馈一个演示功能用法的代码片段相关论文链接如果功能基于某篇 Paper。文档中有一句很有启发性的总结如果你的 Issue 写得足够好那么在它创建的那一刻工作就已经完成了 80%。实现一个新模型需要先提供的信息由于新模型不断涌现文档要求有意实现新模型的贡献者先在 Issue 中给出模型的简短描述与论文链接如果实现是开源的附上实现代码链接如果模型权重可获取附上权重链接。当你准备亲自完成实现时可以告知维护者官方会协助将其加入 Transformers。文档同时指向一份专门的技术指南《如何向 Transformers 添加模型》add_new_model文档页。仓库中src/transformers/models/目录下已组织了几百个模型实现每个模型一个子目录包含configuration_*、modeling_*、tokenization_*等文件新模型将遵循同样的目录结构规范。文档扩展低门槛的贡献入口官方表示始终欢迎让文档更清晰、更精确的改进错别字、缺失内容、表述不清或信息不准确的段落都可以反馈。如果自己没有兴趣动手维护团队可以代为修改如果有兴趣他们会帮助你完成贡献。关于文档的生成、创建与书写规范仓库中的 docs 目录说明 给出了完整指引该目录下source/en、source/zh等按语言组织了数百篇文档源文件docs/source/de即本文所依据的德语文档所在目录。创建 Pull Request完整开发工作流前置要求与仓库准备官方强烈建议在写任何代码之前先检索现有 PR 和 Issue确认没有人正在处理同一主题不确定时先开一个新 Issue 征求反馈。此外需要基本的git知识。Python 版本要求文档原文要求 Python 3.9 或更高版本。需要注意就当前仓库的实际代码而言setup.py 中定义的SUPPORTED_PYTHON_VERSIONS (10, 14)即当前开发版实际支持 Python 3.10 至 3.14python_requires会据此生成为3.10.0。贡献时建议以仓库构建配置为准并选择支持范围内的 Python 版本。准备工作分四步第 1 步Fork 仓库。点击仓库页面上的 Fork 按钮将代码副本创建到你的 GitHub 账号下。第 2 步克隆你的 fork 并添加 upstream remotegit clone gitgithub.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标志的可编辑模式重新安装。文档还指出由于可选依赖较多该命令在某些操作系统上可能失败此时可以先自行安装偏好的深度学习框架PyTorch、TensorFlow 和/或 Flax然后退而求其次执行pip install -e .[quality]这对大多数使用场景已足够。开发过程中的质量保障命令开发功能的同时要确保测试套件通过。运行受你改动影响的测试pytest tests/TEST_TO_RUN.py关于测试的细节见本文后面的测试一节。代码格式化Transformers 依赖ruff保持源代码风格一致。改动后用一条命令同时应用自动风格修正与静态检查make style从当前仓库的 Makefile 看style目标实际执行python utils/checkers.py ruff_check, ruff_format, init_isort, sort_auto_mappings --fix即一次性完成 ruff 检查修复、ruff 格式化、__init__导入排序和 auto 映射排序且该任务优化为只处理被 PR 修改过的文件。代码质量与仓库一致性检查CI 会做这些检查但你也可以本地执行make check-repo查看 Makefile 可知check-repo运行全部检查器代码质量 仓库一致性并带--keep-going参数继续收集所有错误仓库还额外提供fix-repo目标会对有自动修复手段的检查项尤其是 modular 转换直接执行--fix。检查项清单在 Makefile 中有明确定义风格类包括ruff_check、ruff_format、init_isort、sort_auto_mappings仓库一致性类则涵盖auto_mappings、imports、copies、dummies、docstrings、doctest_list等二十余项与 utils/checkers.py 及utils/下各检查脚本一一对应。文档构建验证如果你修改了docs/source下的文件必须确认文档仍可正常生成——这项检查在你开 PR 时也会在 CI 中运行。本地验证需先安装文档构建依赖pip install .[docs]然后在仓库根目录执行doc-builder build transformers docs/source/en --build_dir ~/tmp/test-build构建产物会写入~/tmp/test-build可以用任意编辑器检查生成的 Markdown此外打开 PR 后也可以在 GitHub 上直接预览文档效果。仓库docker/transformers-doc-builder/下也提供了文档构建的 Docker 配置。提交与推送git add modified_file.py git commit文档提醒要写好提交信息清晰传达你的改动内容。为了保持本地代码与上游同步应在打开 PR 之前或被维护者要求时将分支 rebase 到upstream/maingit fetch upstream git rebase upstream/main然后推送你的分支git push -u origin a-descriptive-name-for-my-changes注意如果 PR 已经创建rebase 后必须用--force强制推送如果 PR 尚未创建则正常推送即可。创建 PR 与应对评审意见到 GitHub 上的 fork 页面点击Pull Request逐项核对下面的检查清单后提交。维护者要求修改是常态——即使是核心成员也是如此。应对方式是在本地分支继续开发并 push 到你的 fork新提交会自动出现在 PR 中。Pull Request 检查清单文档给出了一份逐项核对的清单原文为复选框形式此处完整保留☐ PR 标题应概括你的贡献☐ 如果 PR 对应某个具体 Issue在 PR 描述中提及该 Issue 编号建立关联也让阅读 Issue 的人知道有人在处理☐ 表示持续开发中的 PR标题加[WIP]前缀——这能避免重复劳动并与可合并的 PR 区分开☐ 确保现有测试通过☐ 如果添加了新功能也要为它编写测试如果添加的是新模型确保使用ModelTester.all_model_classes (MyModel, MyModelWithLMHead, ...)以触发通用测试套件如果添加了新的slow测试用RUN_SLOW1 python -m pytest tests/models/my_new_model/test_my_new_model.py确认其通过如果添加了新 Tokenizer编写测试并用RUN_SLOW1 python -m pytest tests/models/{your_model_name}/test_tokenization_{your_model_name}.py确认其通过CircleCI 不运行慢测试但 GitHub Actions 每晚都会运行☐ 所有 public 方法必须有信息充分的 Docstring可参考 modeling_bert.py 的写法☐ 由于仓库体积增长很快不要添加图片、视频或其他显著增大仓库的非文本文件应使用 Hub 仓库托管此类文件并通过 URL 引用。文档配图推荐放入 Hugging Face 官方的documentation-images数据集仓库并可通过 PR 请求官方成员合并。关于 PR 会触发的 CI 检查的完整说明官方另有专门的《PR 检查指南》pr_checks文档页。测试体系pytest、慢测试与环境变量运行测试的标准姿势仓库附带了大量测试用于验证库本身的行为以及多个示例脚本。库测试位于 tests 目录示例测试位于 examples 目录例如 examples/pytorch 下的测试脚本。官方偏好pytest与pytest-xdist并行执行更快。从仓库根目录指定子目录或测试文件路径来运行测试python -m pytest -n auto --distloadfile -s -v ./tests/models/my_new_modelexamples目录同理例如运行 PyTorch 文本分类子目录的测试pip install -r examples/xxx/requirements.txt # 仅首次需要 python -m pytest -n auto --distloadfile -s -v ./examples/pytorch/text-classification文档特别说明这正是make test与make test-examples的实现方式不含pip install部分。查看当前仓库的 Makefile 可以看到实际命令在此基础上额外加了pytest-random-order插件-p random_order --random-order-bucketmodule用于随机化测试顺序以暴露测试间的隐藏依赖。也可以指定更少的测试用例只测你正在开发的那个功能。慢测试与其他环境变量慢测试默认被跳过但可以通过将环境变量RUN_SLOW设为yes来启用。这会触发数 GB 模型权重的下载请确保磁盘空间充足、网络连接良好注意务必指定子目录或测试文件路径否则会运行tests或examples下的全部测试耗时极长RUN_SLOWyes python -m pytest -n auto --distloadfile -s -v ./tests/models/my_new_model RUN_SLOWyes python -m pytest -n auto --distloadfile -s -v ./examples/pytorch/text-classification除RUN_SLOW外还有其他默认不启用的环境变量例如RUN_CUSTOM_TOKENIZERS启用自定义 Tokenizer 相关测试。这些变量的定义集中在 src/transformers/testing_utils.py其中RUN_SLOW与RUN_CUSTOM_TOKENIZERS都通过parse_flag_from_env(..., defaultFalse)读取即默认关闭设为真值才启用。更多环境变量说明见该文件。unittest 完全兼容Transformers 把pytest仅当作测试运行器测试套件本身不使用任何 pytest 专属特性。这意味着unittest被完整支持也可以这样运行测试python -m unittest discover -s tests -t . -v python -m unittest discover -s examples -t examples -v风格指南Docstring 遵循 Google 风格在 Docstring 方面Transformers 遵循 Google Python Style Guide。关于文档书写的更多规范Markdown 与 Sphinx 指令的使用方式等参见 docs 目录中的编写规范说明。这也与上文make check-repo中的docstrings检查项呼应——CI 会对公共方法的 Docstring 质量做自动校验。Windows 开发环境配置在 Windows 上非 WSL 环境贡献时需要两步额外配置1. 让 git 将 Windows 的 CRLF 转换为 Linux 的 LF 行尾git config core.autocrlf input2. 通过 MSYS2 使用make命令下载并安装 MSYS2 到C:\msys64打开命令行C:\msys64\msys2.exe安装后通常可在开始菜单中找到在 shell 中执行pacman -Syu更新包管理器然后pacman -S make安装make将C:\msys64\usr\bin加入 PATH 环境变量。完成后即可在 PowerShell、cmd.exe 等任意终端中使用make从而复用本文前述的make style、make check-repo、make test等全部工作流命令。同步 fork 仓库避免误触上游通知更新 fork 的main分支时直接 ping 上游仓库会在依赖它的 PR 中留下无谓的引用并通知相关开发者。文档给出了两种做法首选尽量避免通过 fork 内的分支 PR 来同步而是直接合并到 fork 自己的 main 分支如果必须走 PR在 checkout 自己的分支后执行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--squash --no-commit会把上游 main 的改动压缩成单次待提交的变更提交信息中不写 GitHub 引用从而避免误触上游通知。结语一条可验证的贡献路径纵观这份贡献文档Transformers 为贡献者设计了闭环且可自检的流程从用transformers env收集环境信息的规范 Issue到 fork → 分支 →pip install -e .[dev]可编辑安装的准备工作流从make style一次完成 ruff 格式修复与 auto 映射排序到make check-repo本地复现 CI 的二十余项仓库一致性检查从pytest -n auto --distloadfile并行测试到RUN_SLOW、RUN_CUSTOM_TOKENIZERS等环境变量控制的测试分层每个环节都能在仓库内找到对应的实现依据utils/checkers.py、Makefile、src/transformers/testing_utils.py。对希望参与该项目的开发者而言按本文清单逐项核对即可产出一份符合 CI 要求、可被顺利评审合并的 Pull Request。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Transformers 贡献指南：从 Issue 到 Pull Request 的完整开源协作流程
Transformers 贡献指南从 Issue 到 Pull Request 的完整开源协作流程【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers本篇技术指南基于 Transformers 仓库的官方贡献文档docs/source/de/contributing.md系统讲解参与 Transformers 开源贡献的完整链路如何规范地提交 Bug 报告与功能请求、如何实施一个新模型、如何配置可编辑开发环境、如何用pytest/unittest运行测试套件、如何用make style与make check-repo通过代码质量检查以及如何正确同步 fork 仓库。读完本文你将具备独立向 Transformers 提交可合并 Pull Request 所需的全部实操能力。贡献方式总览代码之外的价值同样重要Transformers 的官方贡献文档开篇明确指出任何人都可以贡献且代码贡献不是唯一途径。回答社区问题、帮助他人、改进文档都是极具价值的贡献方式甚至在博客中提及该项目、推荐该项目也被视为对社区的一种支持。无论以何种方式参与都需遵守仓库根目录的 行为准则。文档同时说明这份指南深受 scikit-learn 贡献指南的启发。具体到代码层面主要有四条贡献路径修复现有代码中的已知问题——这是新手最推荐、风险最低的切入点创建 Issue——报告 Bug 或提出新功能请求实现新模型——为社区补充新的模型架构贡献示例与文档——改进examples与docs的内容。如果不知道从哪里开始官方推荐从Good First Issue列表入手这类 Issue 面向初学者通常会先创建 Pull Request 并关联 Issue以便维护者追踪进度——如果贡献者中途没有时间继续其他人也可以接手该 PR。想要更大挑战的可以查看Good Second Issue标签。规范地提交 IssueBug 报告与功能请求报告 Bug 前必须完成的准备Transformers 文档强调报告的每一条新 Bug 都是库健壮性的来源。在创建 Issue 之前需要做到确认该 Bug 尚未被报告——使用 Issue 搜索功能排查重复项确认问题出在库本身而非你自己的代码——如果不确定官方建议先向社区论坛求助以免 Issue 区被一般性问题淹没。确认无误后Issue 中必须包含以下信息维护者才能快速复现和修复操作系统及版本以及Python、PyTorch、TensorFlow的版本如适用一个简短、独立的代码片段能在 30 秒内复现该 Bug抛出异常时的完整 Traceback其他有帮助的信息例如截图。为了自动输出操作系统与软件版本文档提供了两条命令transformers env也可以直接在仓库根目录运行python src/transformers/commands/transformers_cli.py env从当前仓库源码看env命令的实际实现位于 src/transformers/cli/system.py 的env()函数基于 typer 的 CLI 入口它会收集并打印transformers版本、平台信息、Python 版本、huggingface_hub版本、safetensors版本、accelerate版本及其配置文件、deepspeed版本以及 PyTorch 版本和加速器类型CUDA / XPU / NPU / HPU。因此 Issue 中贴出transformers env的完整输出是帮助维护者快速定位环境问题的标准做法。提交新功能请求的四要素如果希望 Transformers 增加某项新功能官方要求 Issue 包含动机——这项功能对应什么痛点或项目需求或者你是否已经尝试过实现尽可能详细的描述——提供的信息越多团队越能给出有效反馈一个演示功能用法的代码片段相关论文链接如果功能基于某篇 Paper。文档中有一句很有启发性的总结如果你的 Issue 写得足够好那么在它创建的那一刻工作就已经完成了 80%。实现一个新模型需要先提供的信息由于新模型不断涌现文档要求有意实现新模型的贡献者先在 Issue 中给出模型的简短描述与论文链接如果实现是开源的附上实现代码链接如果模型权重可获取附上权重链接。当你准备亲自完成实现时可以告知维护者官方会协助将其加入 Transformers。文档同时指向一份专门的技术指南《如何向 Transformers 添加模型》add_new_model文档页。仓库中src/transformers/models/目录下已组织了几百个模型实现每个模型一个子目录包含configuration_*、modeling_*、tokenization_*等文件新模型将遵循同样的目录结构规范。文档扩展低门槛的贡献入口官方表示始终欢迎让文档更清晰、更精确的改进错别字、缺失内容、表述不清或信息不准确的段落都可以反馈。如果自己没有兴趣动手维护团队可以代为修改如果有兴趣他们会帮助你完成贡献。关于文档的生成、创建与书写规范仓库中的 docs 目录说明 给出了完整指引该目录下source/en、source/zh等按语言组织了数百篇文档源文件docs/source/de即本文所依据的德语文档所在目录。创建 Pull Request完整开发工作流前置要求与仓库准备官方强烈建议在写任何代码之前先检索现有 PR 和 Issue确认没有人正在处理同一主题不确定时先开一个新 Issue 征求反馈。此外需要基本的git知识。Python 版本要求文档原文要求 Python 3.9 或更高版本。需要注意就当前仓库的实际代码而言setup.py 中定义的SUPPORTED_PYTHON_VERSIONS (10, 14)即当前开发版实际支持 Python 3.10 至 3.14python_requires会据此生成为3.10.0。贡献时建议以仓库构建配置为准并选择支持范围内的 Python 版本。准备工作分四步第 1 步Fork 仓库。点击仓库页面上的 Fork 按钮将代码副本创建到你的 GitHub 账号下。第 2 步克隆你的 fork 并添加 upstream remotegit clone gitgithub.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标志的可编辑模式重新安装。文档还指出由于可选依赖较多该命令在某些操作系统上可能失败此时可以先自行安装偏好的深度学习框架PyTorch、TensorFlow 和/或 Flax然后退而求其次执行pip install -e .[quality]这对大多数使用场景已足够。开发过程中的质量保障命令开发功能的同时要确保测试套件通过。运行受你改动影响的测试pytest tests/TEST_TO_RUN.py关于测试的细节见本文后面的测试一节。代码格式化Transformers 依赖ruff保持源代码风格一致。改动后用一条命令同时应用自动风格修正与静态检查make style从当前仓库的 Makefile 看style目标实际执行python utils/checkers.py ruff_check, ruff_format, init_isort, sort_auto_mappings --fix即一次性完成 ruff 检查修复、ruff 格式化、__init__导入排序和 auto 映射排序且该任务优化为只处理被 PR 修改过的文件。代码质量与仓库一致性检查CI 会做这些检查但你也可以本地执行make check-repo查看 Makefile 可知check-repo运行全部检查器代码质量 仓库一致性并带--keep-going参数继续收集所有错误仓库还额外提供fix-repo目标会对有自动修复手段的检查项尤其是 modular 转换直接执行--fix。检查项清单在 Makefile 中有明确定义风格类包括ruff_check、ruff_format、init_isort、sort_auto_mappings仓库一致性类则涵盖auto_mappings、imports、copies、dummies、docstrings、doctest_list等二十余项与 utils/checkers.py 及utils/下各检查脚本一一对应。文档构建验证如果你修改了docs/source下的文件必须确认文档仍可正常生成——这项检查在你开 PR 时也会在 CI 中运行。本地验证需先安装文档构建依赖pip install .[docs]然后在仓库根目录执行doc-builder build transformers docs/source/en --build_dir ~/tmp/test-build构建产物会写入~/tmp/test-build可以用任意编辑器检查生成的 Markdown此外打开 PR 后也可以在 GitHub 上直接预览文档效果。仓库docker/transformers-doc-builder/下也提供了文档构建的 Docker 配置。提交与推送git add modified_file.py git commit文档提醒要写好提交信息清晰传达你的改动内容。为了保持本地代码与上游同步应在打开 PR 之前或被维护者要求时将分支 rebase 到upstream/maingit fetch upstream git rebase upstream/main然后推送你的分支git push -u origin a-descriptive-name-for-my-changes注意如果 PR 已经创建rebase 后必须用--force强制推送如果 PR 尚未创建则正常推送即可。创建 PR 与应对评审意见到 GitHub 上的 fork 页面点击Pull Request逐项核对下面的检查清单后提交。维护者要求修改是常态——即使是核心成员也是如此。应对方式是在本地分支继续开发并 push 到你的 fork新提交会自动出现在 PR 中。Pull Request 检查清单文档给出了一份逐项核对的清单原文为复选框形式此处完整保留☐ PR 标题应概括你的贡献☐ 如果 PR 对应某个具体 Issue在 PR 描述中提及该 Issue 编号建立关联也让阅读 Issue 的人知道有人在处理☐ 表示持续开发中的 PR标题加[WIP]前缀——这能避免重复劳动并与可合并的 PR 区分开☐ 确保现有测试通过☐ 如果添加了新功能也要为它编写测试如果添加的是新模型确保使用ModelTester.all_model_classes (MyModel, MyModelWithLMHead, ...)以触发通用测试套件如果添加了新的slow测试用RUN_SLOW1 python -m pytest tests/models/my_new_model/test_my_new_model.py确认其通过如果添加了新 Tokenizer编写测试并用RUN_SLOW1 python -m pytest tests/models/{your_model_name}/test_tokenization_{your_model_name}.py确认其通过CircleCI 不运行慢测试但 GitHub Actions 每晚都会运行☐ 所有 public 方法必须有信息充分的 Docstring可参考 modeling_bert.py 的写法☐ 由于仓库体积增长很快不要添加图片、视频或其他显著增大仓库的非文本文件应使用 Hub 仓库托管此类文件并通过 URL 引用。文档配图推荐放入 Hugging Face 官方的documentation-images数据集仓库并可通过 PR 请求官方成员合并。关于 PR 会触发的 CI 检查的完整说明官方另有专门的《PR 检查指南》pr_checks文档页。测试体系pytest、慢测试与环境变量运行测试的标准姿势仓库附带了大量测试用于验证库本身的行为以及多个示例脚本。库测试位于 tests 目录示例测试位于 examples 目录例如 examples/pytorch 下的测试脚本。官方偏好pytest与pytest-xdist并行执行更快。从仓库根目录指定子目录或测试文件路径来运行测试python -m pytest -n auto --distloadfile -s -v ./tests/models/my_new_modelexamples目录同理例如运行 PyTorch 文本分类子目录的测试pip install -r examples/xxx/requirements.txt # 仅首次需要 python -m pytest -n auto --distloadfile -s -v ./examples/pytorch/text-classification文档特别说明这正是make test与make test-examples的实现方式不含pip install部分。查看当前仓库的 Makefile 可以看到实际命令在此基础上额外加了pytest-random-order插件-p random_order --random-order-bucketmodule用于随机化测试顺序以暴露测试间的隐藏依赖。也可以指定更少的测试用例只测你正在开发的那个功能。慢测试与其他环境变量慢测试默认被跳过但可以通过将环境变量RUN_SLOW设为yes来启用。这会触发数 GB 模型权重的下载请确保磁盘空间充足、网络连接良好注意务必指定子目录或测试文件路径否则会运行tests或examples下的全部测试耗时极长RUN_SLOWyes python -m pytest -n auto --distloadfile -s -v ./tests/models/my_new_model RUN_SLOWyes python -m pytest -n auto --distloadfile -s -v ./examples/pytorch/text-classification除RUN_SLOW外还有其他默认不启用的环境变量例如RUN_CUSTOM_TOKENIZERS启用自定义 Tokenizer 相关测试。这些变量的定义集中在 src/transformers/testing_utils.py其中RUN_SLOW与RUN_CUSTOM_TOKENIZERS都通过parse_flag_from_env(..., defaultFalse)读取即默认关闭设为真值才启用。更多环境变量说明见该文件。unittest 完全兼容Transformers 把pytest仅当作测试运行器测试套件本身不使用任何 pytest 专属特性。这意味着unittest被完整支持也可以这样运行测试python -m unittest discover -s tests -t . -v python -m unittest discover -s examples -t examples -v风格指南Docstring 遵循 Google 风格在 Docstring 方面Transformers 遵循 Google Python Style Guide。关于文档书写的更多规范Markdown 与 Sphinx 指令的使用方式等参见 docs 目录中的编写规范说明。这也与上文make check-repo中的docstrings检查项呼应——CI 会对公共方法的 Docstring 质量做自动校验。Windows 开发环境配置在 Windows 上非 WSL 环境贡献时需要两步额外配置1. 让 git 将 Windows 的 CRLF 转换为 Linux 的 LF 行尾git config core.autocrlf input2. 通过 MSYS2 使用make命令下载并安装 MSYS2 到C:\msys64打开命令行C:\msys64\msys2.exe安装后通常可在开始菜单中找到在 shell 中执行pacman -Syu更新包管理器然后pacman -S make安装make将C:\msys64\usr\bin加入 PATH 环境变量。完成后即可在 PowerShell、cmd.exe 等任意终端中使用make从而复用本文前述的make style、make check-repo、make test等全部工作流命令。同步 fork 仓库避免误触上游通知更新 fork 的main分支时直接 ping 上游仓库会在依赖它的 PR 中留下无谓的引用并通知相关开发者。文档给出了两种做法首选尽量避免通过 fork 内的分支 PR 来同步而是直接合并到 fork 自己的 main 分支如果必须走 PR在 checkout 自己的分支后执行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--squash --no-commit会把上游 main 的改动压缩成单次待提交的变更提交信息中不写 GitHub 引用从而避免误触上游通知。结语一条可验证的贡献路径纵观这份贡献文档Transformers 为贡献者设计了闭环且可自检的流程从用transformers env收集环境信息的规范 Issue到 fork → 分支 →pip install -e .[dev]可编辑安装的准备工作流从make style一次完成 ruff 格式修复与 auto 映射排序到make check-repo本地复现 CI 的二十余项仓库一致性检查从pytest -n auto --distloadfile并行测试到RUN_SLOW、RUN_CUSTOM_TOKENIZERS等环境变量控制的测试分层每个环节都能在仓库内找到对应的实现依据utils/checkers.py、Makefile、src/transformers/testing_utils.py。对希望参与该项目的开发者而言按本文清单逐项核对即可产出一份符合 CI 要求、可被顺利评审合并的 Pull Request。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考