Transformers PR 检查机制解析:测试选择、代码风格与仓库一致性的本地调试指南【免费下载链接】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本文为 Hugging Face Transformers 的 Pull Request 检查机制技术指南。当你在 Transformers 仓库中提交 PR 时,CI 会运行常规测试、文档构建、代码与文档风格、仓库一致性四类检查;本文基于 docs/source/de/pr_checks.md 的完整内容,结合当前仓库的 Makefile、utils/checkers.py、utils/tests_fetcher.py 等源码实现,逐类讲清每种检查在做什么、失败时如何在本地复现与修复,并深入剖析# Copied from代码拷贝同步机制的语法规则与底层校验逻辑。一、总览:PR 上会运行哪些检查当开发者向 Transformers 仓库发起 Pull Request 时,CI 会执行一系列检查,确保新提交的补丁不会破坏任何已有功能。按 pr_checks 文档 的分类,共有四类:常规测试(reguläre Tests):针对改动文件受影响的测试子集;文档创建(Dokumentation erstellen):构建文档预览并校验可构建性;代码与文档风格(Stil von Code und Dokumentation):格式化与静态检查;仓库一致性(allgemeine Konsistenz des Repository):一组保证仓库内部自洽的校验脚本。文档建议读者本地调试前准备一个开发环境安装。在仓库根目录执行:pip install transformers[dev]或可编辑安装:pip install -e .[dev]由于 Transformers 的可选依赖数量庞大,完整 dev 依赖可能安装失败。若 dev 安装失败,可退而求其次,只安装质量检查所需的依赖以及你所使用的深度学习框架(PyTorch、TensorFlow 和/或 Flax):pip install transformers[quality]或可编辑形式:pip install -e .[quality]对照当前仓库的 setup.py 可以确认这两个 extra 的实际构成:quality包含datasets、ruff、GitPython、urllib3、libcst、rich、ty、tomli、transformers-mlinter等检查器依赖;dev则等于all testing ja sklearn。也就是说,只做风格/一致性检查时quality已经足够,而要跑测试才需要完整的dev。二、测试:tests_fetcher 如何只运行受影响的测试CI 上的测试作业所有以ci/circleci: run_tests_开头的作业都在运行 Transformers 测试套件的一部分。每个作业聚焦库的一个子集、在一个特定环境中运行,例如ci/circleci: run_tests_pipelines_tf只在安装了 TensorFlow 的环境中运行 Pipelines 测试。值得注意的是,CI 每次只运行测试套件的一部分,以避免在模块没有实质变化时白跑测试。实现原理是:一个工具脚本会计算 PR 前后库的差异(即 GitHub Files changed 页签展示的内容),并据此挑选受影响的测试。该工具就是 utils/tests_fetcher.py,可在本地直接运行:python utils/tests_fetcher.py(在 Transformers 仓库根目录执行。)它的内部流程分四步,与文档描述一致:检查 diff 中每个文件的改动是真实代码变更,还是仅在注释/Docstring 中;只保留含真实代码变更的文件;构建一张内部映射表:对库中每个源码文件,列出它递归影响的所有文件(当模块 B import 模块 A 时,认为 A 影响 B;递归影响需要一条从 A 到 B 的模块链,链上每个模块 import 前一个);将该映射应用于第 1 步收集到的文件,得到受 PR 影响的模型文件列表;把这些文件映射到对应的测试文件,得到最终要运行的测试列表。从源码看,当前版本自述为 tests_fetcher V2,其模块文档给出了两个重要补充细节:当受影响的模型数量过多时,它只会运行一组核心模型子集的测试(源码中NUM_MODELS_TO_TRIGGER_FULL_CI 15作为触发全量 CI 的启发式阈值);存在一份CORE_FILES列表(如setup.py、src/transformers/modeling_utils.py、src/transformers/core_model_loading.py等),改动这些核心文件会直接触发全部测试,而不只是受影响的子集。在 CircleCI 流水线中,它的实际调用方式可以在 .circleci/config.yml 中看到:先执行python utils/tests_fetcher.py | tee tests_fetched_summary.txt汇总,再执行python utils/tests_fetcher.py --filter_tests过滤。本地复现 CI 的测试运行本地运行脚本时,会看到第 1、3、4 步的输出,从而知道 CI 会跑哪些测试。脚本的默认输出文件即test_list.txt(源码中--output_file参数默认值),其中是要运行的测试清单,可用如下命令本地执行:python -m pytest -n 8 --distloadfile -rA -s $(cat test_list.txt)此外,tests_fetcher.py还提供几个实用参数:--diff_with_last_commit(针对 main 分支,与上一个 commit 比对)、--fetch_all(强制获取全部测试)、--print_dependencies_of 文件(打印依赖某文件的所有模块树)、--json_output_file(以 JSON 字典形式按类别输出)。作为兜底,即使本地有遗漏,完整测试套件每天都会运行一次。三、文档构建:build_pr_documentation 作业build_pr_documentation作业会构建并生成文档预览,确保 PR 合并后文档一切正常。机器人会把文档预览链接添加到你的 PR 中,你对 PR 做的每次修改都会自动更新到预览里。如果文档构建失败,点击失败任务旁边的Details查看报错位置。文档中提到的一个高频故障原因是:toctree中缺少某个文件条目。Transformers 的文档位于docs/source/lang/下,使用 doc-builder 构建(见 docs/README.md)。本地构建或预览文档的命令为:# 构建 doc-builder build transformers docs/source/en/ --build_dir ~/tmp/test-build # 预览 doc-builder preview transformers docs/source/en/docs 的 README 还提醒:doc-builder 支持标准 Markdown 加上若干扩展语法(可运行示例代码块、文件包含、链接自动解析等),写文档时若用到了这些语法,本地用普通 Markdown 查看器可能渲染异常,以 doc-builder 的输出为准。四、代码与文档风格:make style 与 ruff原文档的说明原文档指出:所有源码文件、示例和测试的代码格式化由black与ruff完成;另有一个自定义工具负责 docstring 与rst文件的格式化(当时的实现是utils/style_doc.py),以及 Transformers 各__init__.py文件中 Lazy-Import 的排序(utils/custom_init_isort.py)。它们可以通过一条命令触发:make styleCI 在检查ci/circleci: check_code_quality中验证这些格式是否已应用,并同时运行ruff做一次基础静态检查——它会抱怨未定义的变量或未使用的变量。要在本地执行该检查:make check-repo由于全量检查可能耗时很长,文档建议只对当前分支改动过的文件运行:make style当前仓库的实际实现从源码结构看,当前仓库已把上述检查统一收敛到 Makefile 与 utils/checkers.py 中,utils/style_doc.py已不存在,其职责由 ruff 与 docstring 检查器接管。Makefile 定义了三组检查器:STYLE_CHECKERS : ruff_check, ruff_format, init_isort, sort_auto_mappings TYPING_CHECKERS : types, modeling_structure CODE_QUALITY_CHECKERS : $(TYPING_CHECKERS), $(STYLE_CHECKERS)对应的 make 目标(节选自 Makefile):make style:以--fix模式运行ruff_check, ruff_format, init_isort, sort_auto_mappings,即 Ruff 静态检查与格式化 __init__.pyimport 排序 Auto-mapping 排序,覆盖风格自动修复的诉求;make typing:运行类型检查(ty)与模型结构规则校验;make check-code-quality:CI 侧的代码质量作业实际执行的入口(对应.circleci/config.yml中的make check-code-quality),等于 typing style 全部检查器;make check-repo:运行全部检查器并加--keep-going(某项失败不中断,最后统一报告)。make style与 CI 检查的对应关系:CI 的check_code_quality作业跑make check-code-quality(只检查不修复),而本地先用make style自动修复、再跑检查,是最省事的顺序。utils/checkers.py 作为统一运行器有几个值得了解的工程细节:插件式发现:它通过 AST 扫描utils/下每个脚本的顶层CHECKER_CONFIG字典(含name、label、cache_globs、check_args、fix_args五个键)来注册检查器,不需要 import 执行任何检查器代码;磁盘缓存:对每个检查器,按其cache_globs匹配到的文件内容计算 SHA-256 摘要并缓存于utils/.checkers_cache.json;若自上次干净运行以来相关文件无变化则直接跳过(可用--no-cache强制全量重跑);修复模式:每个检查器可声明fix_args(fix_argsNone表示只读检查,修复模式会自动跳过);依赖自举:个别检查器需要额外包,checkers.py会在首次需要时自动安装 utils/checkers-requirements.txt(以文件内容 解释器为 stamp 保证每环境只装一次,离线时降级为提示而非阻断)。因此,本地只针对改动文件调试时,推荐顺序是:先make style修复风格,再用make check-repo做整体只读校验。五、仓库一致性:check-repo 背后的检查清单仓库一致性检查汇总了所有确保 PR 把仓库留在良好状态的测试。本地执行:make check-repo原文档列出的检查项原文档列出的检查项与执行脚本如下(完整继承自 pr_checks 文档):检查内容执行脚本所有新加入__init__的对象都必须有文档utils/check_repo.py所有__init__.py文件的两个代码段(Type-Checking 段与运行时段)内容一致utils/check_inits.py所有被识别为另一模块拷贝的代码,必须与原始版本一致utils/check_copies.py所有配置类都至少有文档中提及的有效检查点utils/check_config_docstrings.py所有配置类只包含在对应建模文件中被使用的属性utils/check_config_attributes.pyREADME 的各语言翻译与文档索引的模型列表与主 README 一致utils/check_copies.py(LOCALIZED_READMES部分)文档中自动生成的表格保持最新原文档指向utils/check_table.py(当前仓库已由元数据/文档相关检查器承接)即使未安装全部可选依赖,库也提供全部对象utils/check_dummies.py文档同时给出修复策略:若该检查失败,前两项需要手工修正,其余可自动修复的项目用一条命令解决:make fix-repo此外还有针对添加新模型的 PR 的专项检查,主要保证:所有新增模型都注册进了 Auto-mapping(由 utils/check_repo.py 执行);所有模型都被正确测试(由 utils/check_repo.py 执行)。当前仓库的完整检查器清单对照 Makefile 中REPO_CONSISTENCY_CHECKERS的定义,当前一致性检查已扩展为 19 个命名检查器:REPO_CONSISTENCY_CHECKERS : \ auto_mappings, \ imports, \ import_complexity, \ copies, \ modular_conversion, \ inits, \ doc_toc, \ reviewers, \ modeling_rules_doc, \ docstrings, \ dummies, \ repo, \ pipeline_typing, \ config_docstrings, \ config_attributes, \ doctest_list, \ update_metadata, \ add_dates, \ deps_table它们与上表的对应关系:文档中的init 文档化检查对应repo(check_repo.py)、__init__.py两段一致对应inits(check_inits.py)、拷贝一致对应copies(check_copies.py)、配置类检查点/属性分别对应config_docstrings、config_attributes、可选依赖下的完整对象对应dummies(check_dummies.py)、本地化 README 模型列表一致由 check_copies.py 的LOCALIZED_READMES逻辑处理(源码中可见对README.md、README_zh-hans.md、README_zh-hant.md、README_ko.md等翻译文件的start_prompt/end_prompt段落比对)。新增的检查器还包括auto_mappings(Auto-mapping 排序,对应utils/sort_auto_mappings.py)、modular_conversion(modular 生成文件与源文件同步)、doc_toc(文档目录树校验)、deps_table(依赖版本表setup.py deps_table_update与 src/transformers/dependency_versions_table.py 是否过期)、imports(执行from transformers import *验证无未保护的 import)等。CI 侧对应作业在 .circleci/config.yml 中调用make check-repository-consistency。一个实用技巧:python utils/checkers.py --list可以列出当前所有检查器及其标签、脚本、是否支持修复,python utils/checkers.py copies,docstrings还能只运行指定子集——这比全量make check-repo更快,适合迭代调试。六、# Copied from机制:代码拷贝的同步校验这是原 pr_checks 文档着墨最多的部分,值得单独展开。为什么需要这个机制Transformers 库的模型代码组织方式很特殊:每个模型应完整实现在单一文件中,不依赖其他模型。这导致大量类/方法在不同模型间是复制的(比如很多模型共享同一套 attention 实现)。为此仓库引入了一个校验机制:检查某个模型的某一层代码拷贝是否与原始版本一致。这样在调试(例如修复一个 bug)时,能一眼看到所有受影响的模型,并决定是把改动传播出去还是破坏这份拷贝、允许分叉。该机制的实现在 utils/check_copies.py,其检查范围由文件头 docstring 写明,覆盖三类对象:所有带# Copied from注释的代码;在本脚本FULL_COPIES常量中注册的整文件拷贝对;文档中被识别为拷贝的代码片段(如 docstring 中的代码块)。Tip:若一个文件是另一文件的完整拷贝,应在utils/check_copies.py的FULL_COPIES常量中注册。注释语法机制依赖形如# Copied from xxx的注释,其中xxx必须是被拷贝类/函数的完整路径。文档给出的历史示例是:# Copied from transformers.models.bert.modeling_bert.BertSelfOutput注意两个使用规则:不要对整个类加注释,而是对每个被拷贝的方法/类分别加。文档以RobertaPreTrainedModel._init_weights为例:# Copied from transformers.models.bert.modeling_bert.BertPreTrainedModel._init_weights简单字符串替换:有时拷贝只是名字不同,例如RobertaAttention中把BertSelfAttention换成RobertaSelfAttention,其余代码完全一致。此时用with foo-bar语法:# Copied from transformers.models.bert.modeling_bert.BertAttention with Bert-Roberta注意箭头-两侧不能有空格(除非空格本身就是待替换模式的一部分)。多个替换模式用逗号分隔,从左到右依次执行(顺序重要,当某个替换可能与前面的冲突时)。文档举例:# Copied from transformers.models.roberta.modeling_roberta.RobertaForMaskedLM with Roberta-Camembert, ROBERTA-CAMEMBERTTip:若替换会改变代码格式(比如用很长的名字替换短名字),拷贝会按应用自动格式化之后的状态来校验,避免行宽规则干扰比较。all-casing选项:当多个模式只是同一替换的大小写变体时(大写与小写形式),可加all-casing。文档中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)。在当前仓库中验证上述语法在当前 main 分支依然活跃。两个可直接打开核对的现存实例:src/transformers/models/mobilebert/modeling_mobilebert.py:# Copied from transformers.models.bert.modeling_bert.BertForSequenceClassification with Bert-MobileBert all-casing class MobileBertForSequenceClassification(MobileBertPreTrainedModel):src/transformers/models/data2vec/modeling_data2vec_vision.py,展示了多模式替换(含大小写对):# Copied from tests.models.beit.modeling_beit.BeitAttention with Beit-Data2VecVision, BEIT-DATA2VEC_VISION class Data2VecVisionAttention(nn.Module):需要说明的是,原文档引用的modeling_roberta.py、modeling_camembert.py中的示例链接指向历史 commit(如2bd7a27a);从源码结构看,这些模型当前已迁移到 modular 生成流程,文件中的# Copied from注释已不复存在。对新模型,仓库现行推荐是优先使用 modular 工作流(modular_*.py),尽量避免手写# Copied from——# Copied from更多是存量代码的维护机制。拷贝失同步时如何修复当copies检查失败(拷贝与源不一致)时,修复方式是让检查器反向同步:其CHECKER_CONFIG声明了fix_args: [--fix_and_overwrite],即python utils/check_copies.py --fix_and_overwrite或统一走make fix-repo。原则是:永远修改源头文件,然后由工具把变更传播到所有拷贝;直接改拷贝会被下一次--fix_and_overwrite覆盖。check_copies.py中的正则(如_re_copy_warning)还支持# Copied from tests....形式,即测试文件也可以引用库内代码。七、速查表:CI 检查与本地命令对照CI 检查本地等价命令说明ci/circleci: run_tests_*系列python utils/tests_fetcher.pypython -m pytest -n 8 --distloadfile -rA -s $(cat test_list.txt)只跑 PR 受影响测试;--fetch_all可跑全量build_pr_documentationdoc-builder build transformers docs/source/en/ --build_dir ~/tmp/test-build失败多为 toctree 缺条目,详见 docs/README.mdci/circleci: check_code_qualitymake style(修复)→make check-code-quality(校验)ruff 检查/格式化、__init__import 排序、Auto-mapping 排序、类型与模型结构检查仓库一致性作业make check-repo(校验) /make fix-repo(自动修复)19 个一致性检查器,可用python utils/checkers.py --list查看全部,或只跑子集八、小结Transformers 的 PR 检查体系可以概括为三层防线:测试层用tests_fetcher的 import 依赖反向图精准圈定受影响的测试,配合每日全量回归兜底;风格层由 ruff 排序/类型检查器构成,make style一条命令完成绝大多数自动修复;一致性层通过utils/checkers.py统一调度近 20 个检查器(带磁盘缓存、--fix、--keep-going能力),保证 Auto-mapping、__init__结构、docstring、dummy 对象、本地化 README 模型列表、# Copied from拷贝等仓库级不变量不被破坏。遇到 CI 失败时的标准动作是:定位对应类别 → 先跑make style(风格类失败)或make fix-repo(一致性类失败)自动修复 → 用utils/tests_fetcher.py pytest 命令本地复跑受影响测试 → 重新提交。掌握了这套流程,基本可以在推送前把绝大多数 PR 检查问题拦截在本地。【免费下载链接】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 PR 检查机制解析:测试选择、代码风格与仓库一致性的本地调试指南【免费下载链接】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本文为 Hugging Face Transformers 的 Pull Request 检查机制技术指南。当你在 Transformers 仓库中提交 PR 时,CI 会运行常规测试、文档构建、代码与文档风格、仓库一致性四类检查;本文基于 docs/source/de/pr_checks.md 的完整内容,结合当前仓库的 Makefile、utils/checkers.py、utils/tests_fetcher.py 等源码实现,逐类讲清每种检查在做什么、失败时如何在本地复现与修复,并深入剖析# Copied from代码拷贝同步机制的语法规则与底层校验逻辑。一、总览:PR 上会运行哪些检查当开发者向 Transformers 仓库发起 Pull Request 时,CI 会执行一系列检查,确保新提交的补丁不会破坏任何已有功能。按 pr_checks 文档 的分类,共有四类:常规测试(reguläre Tests):针对改动文件受影响的测试子集;文档创建(Dokumentation erstellen):构建文档预览并校验可构建性;代码与文档风格(Stil von Code und Dokumentation):格式化与静态检查;仓库一致性(allgemeine Konsistenz des Repository):一组保证仓库内部自洽的校验脚本。文档建议读者本地调试前准备一个开发环境安装。在仓库根目录执行:pip install transformers[dev]或可编辑安装:pip install -e .[dev]由于 Transformers 的可选依赖数量庞大,完整 dev 依赖可能安装失败。若 dev 安装失败,可退而求其次,只安装质量检查所需的依赖以及你所使用的深度学习框架(PyTorch、TensorFlow 和/或 Flax):pip install transformers[quality]或可编辑形式:pip install -e .[quality]对照当前仓库的 setup.py 可以确认这两个 extra 的实际构成:quality包含datasets、ruff、GitPython、urllib3、libcst、rich、ty、tomli、transformers-mlinter等检查器依赖;dev则等于all testing ja sklearn。也就是说,只做风格/一致性检查时quality已经足够,而要跑测试才需要完整的dev。二、测试:tests_fetcher 如何只运行受影响的测试CI 上的测试作业所有以ci/circleci: run_tests_开头的作业都在运行 Transformers 测试套件的一部分。每个作业聚焦库的一个子集、在一个特定环境中运行,例如ci/circleci: run_tests_pipelines_tf只在安装了 TensorFlow 的环境中运行 Pipelines 测试。值得注意的是,CI 每次只运行测试套件的一部分,以避免在模块没有实质变化时白跑测试。实现原理是:一个工具脚本会计算 PR 前后库的差异(即 GitHub Files changed 页签展示的内容),并据此挑选受影响的测试。该工具就是 utils/tests_fetcher.py,可在本地直接运行:python utils/tests_fetcher.py(在 Transformers 仓库根目录执行。)它的内部流程分四步,与文档描述一致:检查 diff 中每个文件的改动是真实代码变更,还是仅在注释/Docstring 中;只保留含真实代码变更的文件;构建一张内部映射表:对库中每个源码文件,列出它递归影响的所有文件(当模块 B import 模块 A 时,认为 A 影响 B;递归影响需要一条从 A 到 B 的模块链,链上每个模块 import 前一个);将该映射应用于第 1 步收集到的文件,得到受 PR 影响的模型文件列表;把这些文件映射到对应的测试文件,得到最终要运行的测试列表。从源码看,当前版本自述为 tests_fetcher V2,其模块文档给出了两个重要补充细节:当受影响的模型数量过多时,它只会运行一组核心模型子集的测试(源码中NUM_MODELS_TO_TRIGGER_FULL_CI 15作为触发全量 CI 的启发式阈值);存在一份CORE_FILES列表(如setup.py、src/transformers/modeling_utils.py、src/transformers/core_model_loading.py等),改动这些核心文件会直接触发全部测试,而不只是受影响的子集。在 CircleCI 流水线中,它的实际调用方式可以在 .circleci/config.yml 中看到:先执行python utils/tests_fetcher.py | tee tests_fetched_summary.txt汇总,再执行python utils/tests_fetcher.py --filter_tests过滤。本地复现 CI 的测试运行本地运行脚本时,会看到第 1、3、4 步的输出,从而知道 CI 会跑哪些测试。脚本的默认输出文件即test_list.txt(源码中--output_file参数默认值),其中是要运行的测试清单,可用如下命令本地执行:python -m pytest -n 8 --distloadfile -rA -s $(cat test_list.txt)此外,tests_fetcher.py还提供几个实用参数:--diff_with_last_commit(针对 main 分支,与上一个 commit 比对)、--fetch_all(强制获取全部测试)、--print_dependencies_of 文件(打印依赖某文件的所有模块树)、--json_output_file(以 JSON 字典形式按类别输出)。作为兜底,即使本地有遗漏,完整测试套件每天都会运行一次。三、文档构建:build_pr_documentation 作业build_pr_documentation作业会构建并生成文档预览,确保 PR 合并后文档一切正常。机器人会把文档预览链接添加到你的 PR 中,你对 PR 做的每次修改都会自动更新到预览里。如果文档构建失败,点击失败任务旁边的Details查看报错位置。文档中提到的一个高频故障原因是:toctree中缺少某个文件条目。Transformers 的文档位于docs/source/lang/下,使用 doc-builder 构建(见 docs/README.md)。本地构建或预览文档的命令为:# 构建 doc-builder build transformers docs/source/en/ --build_dir ~/tmp/test-build # 预览 doc-builder preview transformers docs/source/en/docs 的 README 还提醒:doc-builder 支持标准 Markdown 加上若干扩展语法(可运行示例代码块、文件包含、链接自动解析等),写文档时若用到了这些语法,本地用普通 Markdown 查看器可能渲染异常,以 doc-builder 的输出为准。四、代码与文档风格:make style 与 ruff原文档的说明原文档指出:所有源码文件、示例和测试的代码格式化由black与ruff完成;另有一个自定义工具负责 docstring 与rst文件的格式化(当时的实现是utils/style_doc.py),以及 Transformers 各__init__.py文件中 Lazy-Import 的排序(utils/custom_init_isort.py)。它们可以通过一条命令触发:make styleCI 在检查ci/circleci: check_code_quality中验证这些格式是否已应用,并同时运行ruff做一次基础静态检查——它会抱怨未定义的变量或未使用的变量。要在本地执行该检查:make check-repo由于全量检查可能耗时很长,文档建议只对当前分支改动过的文件运行:make style当前仓库的实际实现从源码结构看,当前仓库已把上述检查统一收敛到 Makefile 与 utils/checkers.py 中,utils/style_doc.py已不存在,其职责由 ruff 与 docstring 检查器接管。Makefile 定义了三组检查器:STYLE_CHECKERS : ruff_check, ruff_format, init_isort, sort_auto_mappings TYPING_CHECKERS : types, modeling_structure CODE_QUALITY_CHECKERS : $(TYPING_CHECKERS), $(STYLE_CHECKERS)对应的 make 目标(节选自 Makefile):make style:以--fix模式运行ruff_check, ruff_format, init_isort, sort_auto_mappings,即 Ruff 静态检查与格式化 __init__.pyimport 排序 Auto-mapping 排序,覆盖风格自动修复的诉求;make typing:运行类型检查(ty)与模型结构规则校验;make check-code-quality:CI 侧的代码质量作业实际执行的入口(对应.circleci/config.yml中的make check-code-quality),等于 typing style 全部检查器;make check-repo:运行全部检查器并加--keep-going(某项失败不中断,最后统一报告)。make style与 CI 检查的对应关系:CI 的check_code_quality作业跑make check-code-quality(只检查不修复),而本地先用make style自动修复、再跑检查,是最省事的顺序。utils/checkers.py 作为统一运行器有几个值得了解的工程细节:插件式发现:它通过 AST 扫描utils/下每个脚本的顶层CHECKER_CONFIG字典(含name、label、cache_globs、check_args、fix_args五个键)来注册检查器,不需要 import 执行任何检查器代码;磁盘缓存:对每个检查器,按其cache_globs匹配到的文件内容计算 SHA-256 摘要并缓存于utils/.checkers_cache.json;若自上次干净运行以来相关文件无变化则直接跳过(可用--no-cache强制全量重跑);修复模式:每个检查器可声明fix_args(fix_argsNone表示只读检查,修复模式会自动跳过);依赖自举:个别检查器需要额外包,checkers.py会在首次需要时自动安装 utils/checkers-requirements.txt(以文件内容 解释器为 stamp 保证每环境只装一次,离线时降级为提示而非阻断)。因此,本地只针对改动文件调试时,推荐顺序是:先make style修复风格,再用make check-repo做整体只读校验。五、仓库一致性:check-repo 背后的检查清单仓库一致性检查汇总了所有确保 PR 把仓库留在良好状态的测试。本地执行:make check-repo原文档列出的检查项原文档列出的检查项与执行脚本如下(完整继承自 pr_checks 文档):检查内容执行脚本所有新加入__init__的对象都必须有文档utils/check_repo.py所有__init__.py文件的两个代码段(Type-Checking 段与运行时段)内容一致utils/check_inits.py所有被识别为另一模块拷贝的代码,必须与原始版本一致utils/check_copies.py所有配置类都至少有文档中提及的有效检查点utils/check_config_docstrings.py所有配置类只包含在对应建模文件中被使用的属性utils/check_config_attributes.pyREADME 的各语言翻译与文档索引的模型列表与主 README 一致utils/check_copies.py(LOCALIZED_READMES部分)文档中自动生成的表格保持最新原文档指向utils/check_table.py(当前仓库已由元数据/文档相关检查器承接)即使未安装全部可选依赖,库也提供全部对象utils/check_dummies.py文档同时给出修复策略:若该检查失败,前两项需要手工修正,其余可自动修复的项目用一条命令解决:make fix-repo此外还有针对添加新模型的 PR 的专项检查,主要保证:所有新增模型都注册进了 Auto-mapping(由 utils/check_repo.py 执行);所有模型都被正确测试(由 utils/check_repo.py 执行)。当前仓库的完整检查器清单对照 Makefile 中REPO_CONSISTENCY_CHECKERS的定义,当前一致性检查已扩展为 19 个命名检查器:REPO_CONSISTENCY_CHECKERS : \ auto_mappings, \ imports, \ import_complexity, \ copies, \ modular_conversion, \ inits, \ doc_toc, \ reviewers, \ modeling_rules_doc, \ docstrings, \ dummies, \ repo, \ pipeline_typing, \ config_docstrings, \ config_attributes, \ doctest_list, \ update_metadata, \ add_dates, \ deps_table它们与上表的对应关系:文档中的init 文档化检查对应repo(check_repo.py)、__init__.py两段一致对应inits(check_inits.py)、拷贝一致对应copies(check_copies.py)、配置类检查点/属性分别对应config_docstrings、config_attributes、可选依赖下的完整对象对应dummies(check_dummies.py)、本地化 README 模型列表一致由 check_copies.py 的LOCALIZED_READMES逻辑处理(源码中可见对README.md、README_zh-hans.md、README_zh-hant.md、README_ko.md等翻译文件的start_prompt/end_prompt段落比对)。新增的检查器还包括auto_mappings(Auto-mapping 排序,对应utils/sort_auto_mappings.py)、modular_conversion(modular 生成文件与源文件同步)、doc_toc(文档目录树校验)、deps_table(依赖版本表setup.py deps_table_update与 src/transformers/dependency_versions_table.py 是否过期)、imports(执行from transformers import *验证无未保护的 import)等。CI 侧对应作业在 .circleci/config.yml 中调用make check-repository-consistency。一个实用技巧:python utils/checkers.py --list可以列出当前所有检查器及其标签、脚本、是否支持修复,python utils/checkers.py copies,docstrings还能只运行指定子集——这比全量make check-repo更快,适合迭代调试。六、# Copied from机制:代码拷贝的同步校验这是原 pr_checks 文档着墨最多的部分,值得单独展开。为什么需要这个机制Transformers 库的模型代码组织方式很特殊:每个模型应完整实现在单一文件中,不依赖其他模型。这导致大量类/方法在不同模型间是复制的(比如很多模型共享同一套 attention 实现)。为此仓库引入了一个校验机制:检查某个模型的某一层代码拷贝是否与原始版本一致。这样在调试(例如修复一个 bug)时,能一眼看到所有受影响的模型,并决定是把改动传播出去还是破坏这份拷贝、允许分叉。该机制的实现在 utils/check_copies.py,其检查范围由文件头 docstring 写明,覆盖三类对象:所有带# Copied from注释的代码;在本脚本FULL_COPIES常量中注册的整文件拷贝对;文档中被识别为拷贝的代码片段(如 docstring 中的代码块)。Tip:若一个文件是另一文件的完整拷贝,应在utils/check_copies.py的FULL_COPIES常量中注册。注释语法机制依赖形如# Copied from xxx的注释,其中xxx必须是被拷贝类/函数的完整路径。文档给出的历史示例是:# Copied from transformers.models.bert.modeling_bert.BertSelfOutput注意两个使用规则:不要对整个类加注释,而是对每个被拷贝的方法/类分别加。文档以RobertaPreTrainedModel._init_weights为例:# Copied from transformers.models.bert.modeling_bert.BertPreTrainedModel._init_weights简单字符串替换:有时拷贝只是名字不同,例如RobertaAttention中把BertSelfAttention换成RobertaSelfAttention,其余代码完全一致。此时用with foo-bar语法:# Copied from transformers.models.bert.modeling_bert.BertAttention with Bert-Roberta注意箭头-两侧不能有空格(除非空格本身就是待替换模式的一部分)。多个替换模式用逗号分隔,从左到右依次执行(顺序重要,当某个替换可能与前面的冲突时)。文档举例:# Copied from transformers.models.roberta.modeling_roberta.RobertaForMaskedLM with Roberta-Camembert, ROBERTA-CAMEMBERTTip:若替换会改变代码格式(比如用很长的名字替换短名字),拷贝会按应用自动格式化之后的状态来校验,避免行宽规则干扰比较。all-casing选项:当多个模式只是同一替换的大小写变体时(大写与小写形式),可加all-casing。文档中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)。在当前仓库中验证上述语法在当前 main 分支依然活跃。两个可直接打开核对的现存实例:src/transformers/models/mobilebert/modeling_mobilebert.py:# Copied from transformers.models.bert.modeling_bert.BertForSequenceClassification with Bert-MobileBert all-casing class MobileBertForSequenceClassification(MobileBertPreTrainedModel):src/transformers/models/data2vec/modeling_data2vec_vision.py,展示了多模式替换(含大小写对):# Copied from tests.models.beit.modeling_beit.BeitAttention with Beit-Data2VecVision, BEIT-DATA2VEC_VISION class Data2VecVisionAttention(nn.Module):需要说明的是,原文档引用的modeling_roberta.py、modeling_camembert.py中的示例链接指向历史 commit(如2bd7a27a);从源码结构看,这些模型当前已迁移到 modular 生成流程,文件中的# Copied from注释已不复存在。对新模型,仓库现行推荐是优先使用 modular 工作流(modular_*.py),尽量避免手写# Copied from——# Copied from更多是存量代码的维护机制。拷贝失同步时如何修复当copies检查失败(拷贝与源不一致)时,修复方式是让检查器反向同步:其CHECKER_CONFIG声明了fix_args: [--fix_and_overwrite],即python utils/check_copies.py --fix_and_overwrite或统一走make fix-repo。原则是:永远修改源头文件,然后由工具把变更传播到所有拷贝;直接改拷贝会被下一次--fix_and_overwrite覆盖。check_copies.py中的正则(如_re_copy_warning)还支持# Copied from tests....形式,即测试文件也可以引用库内代码。七、速查表:CI 检查与本地命令对照CI 检查本地等价命令说明ci/circleci: run_tests_*系列python utils/tests_fetcher.pypython -m pytest -n 8 --distloadfile -rA -s $(cat test_list.txt)只跑 PR 受影响测试;--fetch_all可跑全量build_pr_documentationdoc-builder build transformers docs/source/en/ --build_dir ~/tmp/test-build失败多为 toctree 缺条目,详见 docs/README.mdci/circleci: check_code_qualitymake style(修复)→make check-code-quality(校验)ruff 检查/格式化、__init__import 排序、Auto-mapping 排序、类型与模型结构检查仓库一致性作业make check-repo(校验) /make fix-repo(自动修复)19 个一致性检查器,可用python utils/checkers.py --list查看全部,或只跑子集八、小结Transformers 的 PR 检查体系可以概括为三层防线:测试层用tests_fetcher的 import 依赖反向图精准圈定受影响的测试,配合每日全量回归兜底;风格层由 ruff 排序/类型检查器构成,make style一条命令完成绝大多数自动修复;一致性层通过utils/checkers.py统一调度近 20 个检查器(带磁盘缓存、--fix、--keep-going能力),保证 Auto-mapping、__init__结构、docstring、dummy 对象、本地化 README 模型列表、# Copied from拷贝等仓库级不变量不被破坏。遇到 CI 失败时的标准动作是:定位对应类别 → 先跑make style(风格类失败)或make fix-repo(一致性类失败)自动修复 → 用utils/tests_fetcher.py pytest 命令本地复跑受影响测试 → 重新提交。掌握了这套流程,基本可以在推送前把绝大多数 PR 检查问题拦截在本地。【免费下载链接】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），仅供参考
)
