Transformers PR 自动化检查机制详解tests_fetcher 精准测试、代码风格与仓库一致性校验【免费下载链接】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/ja/pr_checks.mdChecks on a Pull Request系统讲解在 Transformers 中提交 Pull Request 后 CI 会执行的四类检查——测试、文档构建、代码与文档风格、仓库整体一致性——以及每类检查背后的设计原理、对应脚本的实现逻辑和失败的本地调试方法。读完后你能够独立运行utils/tests_fetcher.py精准圈定受影响测试、用make style/make check-repo/make fix-repo在本地复现并修复 CI 检查并掌握# Copied from拷贝一致性机制的完整规则。四类 PR 检查总览在 Transformers 仓库中打开一个 PR 后系统会运行相当数量的检查来确认新补丁没有破坏现有功能。这些检查分为四类引自 docs/source/ja/pr_checks.md普通的测试Tests——运行测试套件中与改动相关的部分文档的构建Documentation build——确认 PR 合并后文档能正常渲染代码与文档的风格Code and documentation style——格式化、lint 与文档字符串规范仓库整体的一致性Repository consistency——确认 PR 没有破坏仓库的结构性约定。文档同时说明理想的本地调试环境是开发者安装由于可选依赖众多dev 安装失败时可退而求其次安装 quality 依赖见下节。本地调试环境的准备要在本地复现和调试上述检查首先需要安装依赖。文档给出两条路径pip install transformers[dev]或编辑可安装editable installpip install -e .[dev]如果开发安装因可选依赖过多而失败文档建议先安装你实际使用的深度学习框架PyTorch、TensorFlow 和/或 Flax然后只安装质量检查所需的依赖pip install transformers[quality]或编辑可安装pip install -e .[quality]这一降级方案的原因在文档中也有明确交代Transformers 的可选依赖数量较多[dev]集可能一次性拉取全部框架的依赖而[quality]集只包含运行检查脚本所需的工具。TestsCI 如何决定“只跑相关测试”以ci/circleci: run_tests_开头的所有 CI 作业都会执行 Transformers 测试套件的一部分。每个作业聚焦于特定环境与库的特定部分——例如ci/circleci: run_tests_pipelines_tf会在仅安装 TensorFlow 的环境中运行 pipelines 的测试。关键点CI 只运行测试套件的一个子集。选择哪些测试由一个“测试获取器”工具完成它计算 PR 前后库的差异找出受影响的部分并挑选对应测试。这个工具就是 utils/tests_fetcher.py在仓库根目录运行python utils/tests_fetcher.py它的完整工作流程分为四步文档原文描述并在源码中可一一对应检查 diff 中的每个文件区分“改动在真实代码里”还是“仅在注释或 docstring 里”。脚本通过 clean_code() 实现这一点先按三引号剥离 docstring再用正则去掉注释与空行若清理后的新旧内容一致则该文件的改动被视为 docstring-only不触发测试构建内部依赖映射对库源码的每个文件递归计算它影响的所有文件。所谓“模块 A 影响模块 B”是指模块 B import 了模块 A递归影响即存在一条模块链链上每个模块都 import 前一个把该映射应用到第 1 步收集的改动文件上得到 PR 所影响的模型文件列表将这些文件映射到对应的测试文件得到最终要执行的测试列表。在本地运行时脚本会打印第 1、3、4 步的结果并生成一个test_list.txt文件源码中--output_file参数默认值正是test_list.txt见 tests_fetcher.py#L1169其中包含要运行的测试。随后用以下命令本地执行python -m pytest -n 8 --distloadfile -rA -s $(cat test_list.txt)其中-n 8为 8 个并行 worker--distloadfile按文件分派负载-rA输出全部测试的结果摘要-s关闭输出捕获。仓库 Makefile 中的make test目标使用了同一套并行参数并额外启用了随机顺序插件test: python -m pytest -p random_order -n auto --distloadfile -s -v --random-order-bucketmodule ./tests/从源码结构还可以看到若干文档未展开、但决定“何时全量跑测试”的细节核心文件白名单CORE_FILEStests_fetcher.py#L76-L84 列出了setup.py、.circleci/create_circleci_config.py、src/transformers/modeling_utils.py、src/transformers/cache_utils.py、src/transformers/generation/utils.py等文件——修改这些“几乎能影响库任何角落”的文件会直接触发全部测试模型数量阈值NUM_MODELS_TO_TRIGGER_FULL_CI 15tests_fetcher.py#L72当受影响模型数量过多达到启发式阈值时脚本会推断为“所有模型都受影响”从而不再按模型过滤main 分支场景脚本 docstring 中还提供了python utils/tests_fetcher.py --diff_with_last_commit用法用于在 main 分支上以“与上一个 commit 的 diff”代替“与分支点的 diff”来圈定测试tests_fetcher.py#L44-L48。脚本 docstring 同时给出了两条使用假设它只按文件而非单个测试过滤因此不同主题的测试最好分文件存放它假设__init__.py只做 import 而不构建对象因此对象构建逻辑应放在独立子模块中。关于 CI 作业名的说明文档引用的ci/circleci: run_tests_*等名称对应 CircleCI 体系当前仓库仍保留 .circleci/create_circleci_config.py动态生成 CircleCI 配置且被 tests_fetcher 列为核心文件与此同时仓库.github/workflows/下也存在 build_pr_documentation.yml、pr-ci-caller.yml 等作业定义。两套体系并存的具体分工以仓库当前内容为准。Documentation build文档构建检查build_pr_documentation作业负责构建文档确保 PR 合并后一切能正常显示。流程要点引自文档构建完成后机器人会在 PR 中附上预览文档的链接你对 PR 的后续修改会自动反映到预览中可实时核对渲染效果构建失败时点击失败作业旁的“Details”查看详情常见问题往往很简单比如toctree中缺少文件。如需在本地构建或预览文档文档指向 docs/README.mddocs 文件夹内的说明文档其中介绍了本地构建与预览文档的完整步骤。Code and documentation style风格检查文档说明所有源文件、示例和测试都会用black与ruff做格式化此外还有自定义工具处理三类特殊问题docstring 与rst文件的格式Transformers的__init__.py文件中延迟导入lazy imports的顺序。文档中提及utils/style_doc.py与utils/custom_init_isort.py两个自定义工具一键触发全部风格处理make styleCI 会在ci/circleci: check_code_quality检查中确认这些检查均已应用并运行ruff报告未定义变量、未使用变量等错误。本地复现命令make check-repo注意结合当前仓库的演进当前快照中风格检查的具体组成以 Makefile#L13-L15 为准STYLE_CHECKERS : ruff_check, ruff_format, init_isort, sort_auto_mappings, noisy_comments TYPING_CHECKERS : types, modeling_structure即当前的“代码质量”集 类型检查types、modeling_structure 风格检查ruff_check、ruff_format、init_isort、sort_auto_mappings、noisy_comments统一由 utils/checkers.py 调度执行make style即python utils/checkers.py STYLE_CHECKERS --fix。文档中提到的utils/style_doc.py在当前仓库的utils/目录下已不存在可推断其职责已被checkers.py体系吸收或重构utils/custom_init_isort.py则仍然存在对应init_isort检查项。写作时应以 Makefile 为检查项的权威清单。Repository consistency仓库一致性检查这一类检查确认 PR 没有把仓库带离“合适的状态”由ci/circleci: check_repository_consistency作业在 CI 上执行本地统一用一条命令复现make check-repo文档列举了它验证的内容逐项对应 utils/ 下的检查脚本检查项执行脚本验证内容新增到 init 的对象已文档化utils/check_repo.pyinit 中新增的所有对象都有对应文档__init__.py双段一致性utils/check_inits.py所有__init__.py文件在其两个 section 中内容一致拷贝代码一致性utils/check_copies.py被识别为“从其他模块拷贝”的代码与原始代码一致配置类 docstring 有效检查点utils/check_config_docstrings.py每个配置类的 docstring 至少包含一个有效检查点配置属性与实际使用一致utils/check_config_attributes.py配置类只包含对应 modeling 文件实际使用的属性各语言 README/文档索引模型列表一致utils/check_copies.pyREADME 与文档索引的各语言翻译与主 README 持有相同模型列表自动生成表格最新utils/check_table.py文档提及当前快照已不存在文档的自动生成的表格保持更新可选依赖下的对象可用性utils/check_dummies.py未安装任何可选依赖时所有对象仍可用dummy 机制文档给出了失败后的处理原则前两项需要手工修复后四项可以通过命令自动修复make fix-repo在 Makefile#L62-L63 中make fix-repo对应python utils/checkers.py ALL_CHECKERS --fix --keep-going即对所有检查器尝试自动修复并继续执行与check-repo不带--fix、只报告形成对照。此外当前REPO_CONSISTENCY_CHECKERS的完整清单Makefile#L17-L36还包含auto_mappings、imports、import_complexity、modular_conversion、doc_toc、reviewers、modeling_rules_doc、docstrings、repo、pipeline_typing、doctest_list、update_metadata、add_dates、deps_table等检查项——其中Makefile头部注释特别说明两个 CI 作业check-code-quality与check-repository-consistency持有权威集合本地的check-repo/fix-repo目标是由它们派生的因此永远不会与 CI 漂移失步。针对“新增模型”PR 的额外检查点文档还指出额外检查点主要与新增模型的 PR 相关核心确认两件事均通过 utils/check_repo.py 执行所有新增的模型都注册进了Auto-mapping所有新增的模型都被适当地测试。文档中同时保留了面向维护者的 TODO 注释计划补充“所有模型已加入主 README 与主文档”“docstring 引用的所有检查点在 Hub 上真实存在”两项检查。这表明一致性检查清单本身是持续演进的引用时以仓库当前脚本行为为准。Check copies# Copied from拷贝一致性机制这是文档中最具 Transformers 特色的部分值得深入展开。其背景是Transformers 对模型代码的组织方式有强烈主张——每个模型必须完全实现于一个文件中不依赖其他模型。但实践中大量模型如 RoBERTa 之于 BERT只是换了名字的复刻为避免多份拷贝各自漂移仓库引入了拷贝一致性检查。它带来的收益是一旦发现原始代码有 bug 修复就能定位所有受影响的模型并决定是传播修复还是放弃拷贝。该机制完全依赖# Copied from xxx形式的注释xxx必须是被拷贝类或函数的完整路径。文档给出的三个典型例子例 1整类直接拷贝无替换RobertaSelfOutput是BertSelfOutput的直接拷贝在 src/transformers/models/roberta/modeling_roberta.py 中的注释为# Copied from transformers.models.bert.modeling_bert.BertSelfOutput例 2拷贝到相关方法并带名称替换RobertaPreTrainedModel._init_weights从BertPreTrainedModel拷贝注释带上Old-New替换规则# Copied from transformers.models.bert.modeling_bert.BertAttention with Bert-Roberta文档特别强调一条格式铁律箭头两侧不能有空格除非空格本身是替换模式的一部分。例 3多条逗号分隔的替换CamembertForMaskedLM是RobertaForMaskedLM的直接拷贝含两个替换Roberta→Camembert、ROBERTA→CAMEMBERT在 src/transformers/models/camembert/modeling_camembert.py 中的注释为# Copied from transformers.models.roberta.modeling_roberta.RobertaForMaskedLM with Roberta-Camembert, ROBERTA-CAMEMBERT由于先前的替换可能与后续替换冲突例如先把Roberta换成Camembert后再处理ROBERTA文档明确当顺序重要时替换按从左到右依次执行。例 4all-casing大小写变体展开如果一组替换只是同一替换的不同大小写变体可以用all-casing选项一次性声明。src/transformers/models/mobilebert/modeling_mobilebert.py 中MobileBertForSequenceClassification的注释# Copied from transformers.models.bert.modeling_bert.BertForSequenceClassification with Bert-MobileBert all-casing该声明等价于同时执行三组替换Bert→MobileBert如__init__中使用MobileBertModel处bert→mobilebert如定义self.mobilebert处BERT→MOBILEBERT如常量MOBILEBERT_INPUTS_DOCSTRING内。完整文件拷贝与自动格式化文档还给出两条提示Tip如果某个文件是另一个文件的完整拷贝需要把它注册到utils/check_copies.py的FULL_COPIES常量中。需要说明的是在当前仓库快照中check_copies.py 的 docstring 仍将FULL_COPIES列为其职责之一“注册为互为完整拷贝的文件”见 check_copies.py#L14-L36但该常量本身已不出现在脚本正文中从源码结构看可推断此注册表已被移除或迁移实际使用时应以python utils/check_copies.py --help与make check-repo的当前输出为准Tip如果替换会改变代码格式例如把短名替换为很长的名字拷贝会在自动格式化器formatter应用之后再做校验——即比对前会先对两侧代码执行格式化避免因行宽重排导致的假阳性。check_copies.py的 docstring 还说明了它的三重职责校验所有# Copied from代码、校验主 README 与 13 个本地化 README中英日韩西法德等见 check_copies.py#L68-L174 中的LOCALIZED_READMES映射模型列表一致、以及校验注册的整文件拷贝。它支持两种运行模式python utils/check_copies.py检查模式不一致即报错供make check-repo使用与python utils/check_copies.py --fix_and_overwrite自动修复模式供make fix-repo使用。检查失败时的本地调试速查把文档内容汇总成一张“CI 失败 → 本地命令”的速查表CI 失败类型本地复现命令是否可自动修复测试失败python utils/tests_fetcher.py生成test_list.txt后python -m pytest -n 8 --distloadfile -rA -s $(cat test_list.txt)—需改代码/测试文档构建失败按 docs/README.md 本地构建文档常见原因是 toctree 缺文件—需手工修正代码/文档风格make style自动修复格式make check-repo只检查是make style带--fix仓库一致性make check-repo部分可make fix-repo两条使用边界值得记住其一tests_fetcher只按文件粒度圈定测试改动核心文件如modeling_utils.py、cache_utils.py或影响面超过 15 个模型时会退化为全量其二check-repo与 CI 的检查集合通过Makefile中的派生机制保证同步本地通过make check-repo全绿是 PR 通过风格与一致性检查的充分预演。小结Transformers 的 PR 检查体系由“精准测试选择tests_fetcher 的 import 依赖反向映射 docstring-only diff 过滤”“文档预览构建”“ruff/types 驱动的风格与类型检查”“由 20 余项 checkers 组成的仓库一致性检查含# Copied from拷贝一致性”四个层面构成全部检查都可以用make style、make check-repo、make fix-repo和python utils/tests_fetcher.py在本地完整复现。对贡献者而言理解 tests_fetcher 的四步依赖分析、CORE_FILES 全量触发规则以及拷贝注释的“箭头无空格、从左到右执行、all-casing 展开、格式化后校验”四条规则就足以让绝大多数 CI 失败在推送前被拦截在本地。【免费下载链接】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），仅供参考
