Transformers 新模型移植实战指南从transformers add-new-model-like脚手架到 1e-3 精度验证与 Hub 发布【免费下载链接】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 官方文档《如何向 Transformers 添加一个模型》当前仓库的德语版位于 docs/source/de/add_new_model.md英文主文档见 docs/source/en/add_new_model.md为核心骨架完整还原“添加一个新模型”的全流程先理解库的设计哲学与模型/配置类继承结构再按 14 步配方完成开发环境准备、原仓库 Checkpoint 调试、模型骨架生成、权重转换、前向传播对齐1e-3 容差、测试、文档与 Hub 上传并结合仓库中 CLI 实现与 Makefile 质检器的真实源码让每个步骤都有可验证的落点。一、动手之前Transformers 的设计哲学与模型架构Transformers 是一个“有强烈主见opinionated”的库。官方文档明确指出库的基本设计决策和哲学对于在控制维护成本的同时高效扩展模型数量至关重要。阅读 philosophy 相关文档 后可以归纳出三条贯穿所有模型实现的决策原则组合Composition优先于抽象Abstraction代码重复不是原罪——只要它显著提升了某个模型的可读性或可及性模型文件尽可能自包含——读某个模型的代码时理想情况下只需要看对应的modeling_....py一个文件。同时官方强调库的代码本身既是交付产品例如用 BERT 做推理的手段也是被持续改进的产品。因此给模型写代码时读者不仅是“使用模型的人”还包括所有阅读、理解和改进你代码的人。1.1 模型与配置的继承结构最多两层抽象成功添加模型的前提是理解模型与其配置类Config之间、以及PreTrainedModel与PreTrainedConfig之间的交互。官方文档以假设要添加的BrandNewBert为例BrandNewBertModel继承自BrandNewBertPreTrainedModel后者继承自PreTrainedModel到此为止——库中一个模型的抽象层级绝不超过两层新模型通常只依赖PreTrainedModel每个新模型自动获得的核心能力是~PreTrainedModel.from_pretrained与~PreTrainedModel.save_pretrained序列化/反序列化BrandNewBertModel.forward等重要功能则应完整地定义在modeling_brand_new_bert.py中带特定头Head的模型类如BrandNewBertForMaskedLM不继承BrandNewBertModel而是把BrandNewBertModel作为可在 forward pass 中调用的组件来使用以此压低抽象层级。每个新模型都需要一个配置类如BrandNewBertConfig。配置始终作为PreTrainedModel的一个属性保存因此所有继承自BrandNewBertPreTrainedModel的类都能通过config属性访问它model BrandNewBertModel.from_pretrained(brandy/brand_new_bert) model.config # model has access to its config配置类同样从PreTrainedConfig继承基础序列化能力。注意模型与配置总是以两种不同格式序列化模型写入pytorch_model.bin文件配置写入config.json文件。调用~PreTrainedModel.save_pretrained会自动连带调用~PreTrainedConfig.save_pretrained即模型与配置同时落盘——这正是后文第 6 步转换脚本结尾model.save_pretrained(...)的行为来源。1.2 五条代码风格守则官方文档对编码风格给出了明确而具体的要求这些要求在后续make check-repo质检中都会被机器检查前向传播完全写入模型文件且不依赖库中其他模型。想复用别的模型的代码块时直接复制代码并加上# Copied from注释Copied from 机制的文档见 docs/source/de/pr_checks.md 中的 check-copies 小节代码必须对非英语母语者也完全可读使用描述性变量名、避免缩写activation优于act除 for 循环索引外强烈反对单字母变量名总体上偏好更长、更显式的代码而非简短的“魔法”代码避免子类化 PyTorch 的nn.Sequential应子类化nn.Module并手写 forward pass这样使用者才能通过插入打印或断点快速调试函数签名要有类型注解但好的变量名永远比类型注解更可读。二、模型移植的分步配方与关键经验每个人移植模型的偏好不同社区贡献者写过不少“如何移植一个模型”的经验总结。官方文档给出的三条最重要经验是不要重复造轮子。你要为新模型写的大部分代码已经以某种形式存在于 Transformers 中。花时间找到相似的已有模型和 Tokenizer 作为复制起点grep和rg是你的朋友。注意你的 Tokenizer 可能基于一种模型实现而建模代码基于另一种——例如 FSMT 的建模代码基于 BARTTokenizer 代码却基于 XLM这是技术挑战而非科学挑战。把时间花在搭建高效的调试环境上而不是试图搞懂论文的所有理论细节卡住就求助。模型是 Transformers 的核心资产团队乐于在每个环节提供帮助。官方文档同时提供了一张完整的 To-Do 清单建议直接当作移植任务的进度表☐可选理解模型的理论知识☐ 准备 Transformers 开发环境☐ 搭建原仓库的调试环境☐ 编写脚本用原仓库与 Checkpoint 成功执行一次forward()☐ 成功向 Transformers 添加模型骨架☐ 成功将原 Checkpoint 转换为 Transformers 格式☐ 成功在 Transformers 中执行 forward()输出与原 Checkpoint 完全一致☐ 完成模型测试☐ 成功向 Transformers 添加 Tokenizer☐ 执行端到端集成测试☐ 完成文档☐ 将模型权重上传到 Hub☐ 提交 Pull Request☐可选添加演示 Notebook2.1 可选第一步理解模型的理论方面如果存在论文值得花一点时间阅读但不必追求深度理论理解目标只是提取实现所需信息。需要弄清的问题包括brand_new_bert是什么类型纯 Encoder类 BERT、纯 Decoder类 GPT-2还是 Encoder-Decoder类 BART不熟悉这些区别可查阅模型总结文档model summary它的应用场景文本分类、文本生成还是摘要等 Seq2Seq 任务它与 BERT/GPT-2/BART 相比的新特性是什么已存在的 Transformers 模型中哪个与它最相似它用什么 TokenizerSentencePiece、WordPiece与 BERT 或 BART 的是否相同对模型架构形成大致印象后可以把架构、注意力层等疑问直接抛给维护团队。2.2 第二步准备开发环境按官方步骤操作下文以 git 流程说明外部仓库地址以你实际使用的为准Fork 仓库在 GitHub 仓库页面点击 Fork得到你账号下的一份副本克隆你的 Fork 并添加上游 remotegit clone https://github.com/[your Github handle]/transformers.git cd transformers git remote add upstream https://github.com/huggingface/transformers.git搭建开发虚拟环境python -m venv .env source .env/bin/activate pip install -e .[dev]由于 Transformers 可选依赖众多不同操作系统下.[dev]可能安装失败。此时可退而求其次确认已安装你所用的深度学习框架PyTorch、TensorFlow 和/或 Flax后执行pip install -e .[quality]这通常已足够覆盖开发与质检需求。从 setup.py 可以看到quality依赖包含datasets、ruff、GitPython、urllib3、libcst、rich、ty、tomli、transformers-mlinter其中libcst对后文的transformers add-new-model-like命令是硬性依赖dev则定义为all testing ja sklearn见 setup.py。官方推荐添加 PyTorch 版本实现按 PyTorch 官方本地安装指引安装即可。无需安装 CUDA——把新模型跑在 CPU 上就足够了移植还需要原仓库的可执行副本git clone https://github.com/org_that_created_brand_new_bert_org/brand_new_bert.git cd brand_new_bert pip install -e .至此开发环境准备完毕。2.3 第三~四步用原仓库跑通预训练 Checkpoint首先面对的是原始实现。研究性代码往往文档匮乏、可读性差而这正是重新实现的动机——把“站在巨人肩膀上”具体化为取一个能跑的模型重写为尽可能易及、易用、美观的形式。成功运行官方预训练模型往往是最难的一步。花时间熟悉原始代码库必须搞清楚预训练权重在哪里如何把权重加载进对应模型Tokenizer 如何脱离模型单独运行跟一遍 forward pass弄清一次前向需要哪些类与函数——通常只需重写这些定位模型的关键组件模型类在哪有没有 EncoderModel、DecoderModel 等子类自注意力层在哪是否存在多种注意力自注意力、交叉注意力如何高效调试原仓库代码加print、用ipdb还是用 IDE开始移植前你必须能高效地调试原仓库代码。由于你面对的是开源库不妨在原仓库提 issue 甚至 PR——维护者大概率会很高兴。关于调试环境官方强烈建议不要一开始就搭昂贵的 GPU 环境全程用 CPU 调试只有当模型已移植成功最后才验证 GPU 行为。可选的两类调试环境Jupyter Notebook / 在线 Colab按单元格执行便于隔离逻辑组件、加速调试循环可保存中间结果、方便与他人分享缺点是如果你不熟悉它需要适应期且可能用不惯ipdb这类调试器本地 Python 脚本。对任何代码库好的第一步是加载一个足够小的预训练 Checkpoint并用一组 dummy 整数输入 ID 复现一次前向传播。伪代码如下model BrandNewBertModel.load_pretrained_checkpoint(/path/to/checkpoint/) input_ids [0, 4, 5, 2, 3, 7, 9] # vector of input ids original_output model.predict(input_ids)调试策略二选一把原模型拆成许多小的可测试组件对每个组件单独前向验证只拆成“原始 Tokenizer 原始模型”两大件中间用打印或断点检查。如果原代码库支持 eager 模式运行并易于拆解通常值得走更难的“组件化”路线收益包括后期与 Transformers 实现对比时可以逐组件自动校验一致性而非依赖视觉比对的打印输出把“移植整个模型”这一大问题拆成若干“移植单个组件”的小问题工作结构更清晰按逻辑组件切分有助于理解模型设计后期组件级测试还能防止你改代码时引入回归。但如果原实现极其复杂、或只支持编译模式下运行中间组件文档以 T5 的 MeshTensorFlow 库为例拆解可能代价过高甚至不可行此时只能退而依赖打印检查。无论哪种策略推荐的排查顺序都是先调试浅层、最后调顶层按以下顺序取各层输出传给模型的输入 ID一组整数如input_ids [0, 4, 4, 3, 2, 4, 1, 7, 19]词嵌入word embeddings第一层 Transformer 的输入第一层 Transformer 的输出后续 n-1 层 Transformer 的输出整个模型的最终输出。各中间层输出通常是多维浮点数组形如[[ [-0.1465, -0.6501, 0.1993, ..., 0.1451, 0.3430, 0.6024], [-0.4417, -0.5920, 0.3450, ..., -0.3062, 0.6182, 0.7132], ... [-0.5334, -0.6403, 0.4271, ..., -0.3339, 0.6533, 0.8694]]],精度要求每个添加到 Transformers 的模型必须通过集成测试即原始实现与新实现输出必须一致容差为1e-30.001。不同框架/库实现的同一模型输出本就可能略有差异因此官方接受 1e-3 的误差但“几乎相同”不够必须几乎完全一致——这意味着你会反复对比中间结果。为了把原仓库的调试环境做到最高效官方给出五条实操建议找到获取中间结果的最佳路径。原仓库是 PyTorch值得写一个较长脚本把它拆成子组件以读取中间值是 TensorFlow 1可能只能依赖tf.print之类的打印操作是 JAX确保运行前向时模型未被 jitted可参考 JAX 官方 issue 的讨论用你能找到的最小的预训练 Checkpoint——调试循环中单次前向超过 10 秒就太低效了。若只有超大 Checkpoint更聪明的做法是在新环境里建一个随机初始化权重的 dummy 模型把它的权重拿去和 Transformers 版本对比选择原仓库中调用单次前向的最简入口理想是只跑一次 forward 的函数常叫 “predict”“evaluate”“forward” 或 “call”不要调试会多次调用 forward 的函数如autoregressive_sample、generate把分词与模型前向解耦。若原仓库示例必须输入字符串就找出前向中字符串转成输入 ID 的位置从该点开始调试必要时自己写个小脚本或直接改原代码以直接喂 ID确保调试设置下模型不在训练模式否则 Dropout 会引入随机性。保证前向确定性model.training False且没有 Dropout 层被误激活若新旧实现在同一框架内也可以用transformers.utils.set_seed固定随机种子。三、第五~十四步把 BrandNewBert 移植进 Transformers3.1 用transformers add-new-model-like生成模型骨架如果新模型架构与某个已有模型完全一致只需按文档中转换脚本小节补一个转换脚本直接复用已有模型架构即可否则开始创建新模型。官方推荐入口是一条 CLI 命令transformers add-new-model-like它会以交互问卷方式收集模型的基本信息。结合当前仓库源码 src/transformers/cli/add_new_model_like.py 可以看到这条命令在 src/transformers/cli/transformers.py#L27 中通过app.command()注册的实际行为比旧版文档描述的“Cookiecutter 模板”要完整得多问卷内容get_user_input函数要复制的现有模型须为CONFIG_MAPPING_NAMES中合法的小写模型名输错时会给出近似名提示、新模型名snake lowercase、文档中显示的大小写完整名随后针对参考模型已有的各类处理器逐项询问——是否新建 tokenizer、fast tokenizer、image processor、video processor、feature extractor、processor回答no则直接复用参考模型的对应类生成的产物_add_new_model_like_internal函数第 530 行起创建src/transformers/models/new_name/目录生成modular 文件对参考模型的每个类生成class NewXxx(OldXxx): pass的继承骨架并用 libcst 解析出__all__公共类清单生成模型的__init__.py基于_LazyModule惰性加载结构在src/transformers/models/__init__.py中注册新模型向 src/transformers/models/auto/auto_mappings.py 及各类 tokenization_auto/image_processing_auto 等自动映射表写入新模型条目复制参考模型的测试文件到tests/models/new_name/并替换类名生成文档模板docs/source/en/model_doc/new_name.md含 Overview、论文摘要占位符、Tips、Usage examples以及每个公共类的[[autodoc]]段落并插入 docs/source/en/_toctree.yml自动运行ruff check --fix与ruff format再执行 utils/check_doc_toc.py、utils/sort_auto_mappings.py 整理目录与映射表最后调用 utils/modular_model_converter.py 执行modular 转换由 modular 文件自动展开生成modeling_new_name.py、configuration_new_name.py等完整文件。注意该命令硬性依赖libcst源码中若未安装会直接抛出You need to install libcst to run this command - pip install libcstsrc/transformers/cli/add_new_model_like.py#L554-L555这也解释了为什么.[quality]依赖中包含了libcst。3.2 先开一个 WIP Pull Request官方建议在动生成代码之前就先向主仓库开一个形如[WIP] Add brand_new_bert的 PR以便与团队协作推进。流程如下从主分支创建描述性命名的分支git checkout -b add_brand_new_bert提交自动生成的代码git add . git commit拉取并变基到最新 maingit fetch upstream git rebase upstream/main推送到你的账号git push -u origin a-descriptive-name-for-my-changes在 Fork 页面点击 Pull request记得添加 Hugging Face 团队成员为 Reviewer将 PR 转为 DraftIn draft。之后每有进展就 commit push并定期同步主干git fetch upstream git merge upstream/main官方还特别提示所有关于模型或实现的问题都应在 PR 中提出与解决——在 Changed files 标签页对着具体行添加评论解决后点 Resolve。团队审代码时也会以同样方式评论只有极少数不适合公开的通用问题才走 Slack 或邮件。3.3 第五步适配生成的模型代码先只关注模型本身、暂不管 Tokenizer。相关代码集中在生成的src/transformers/models/brand_new_bert/modeling_brand_new_bert.py与configuration_brand_new_bert.py。生成代码的架构要么是 BERT 式纯 Encoder要么是 BART 式Encoder-Decoder你要做的正是把“该模型与 BERT/BART 有何不同”落地——通常是修改自注意力层、归一化层的顺序等。参考已有相似模型的架构往往非常有帮助。官方明确此时不必追求代码正确或整洁。最高效的路径是先塞入一份“未经修饰的”原始代码副本再通过下一节的转换脚本迭代修正。此刻唯一必须成立的验证是from transformers import BrandNewBertModel, BrandNewBertConfig model BrandNewBertModel(BrandNewBertConfig())该命令按BrandNewBertConfig()默认参数创建随机权重的模型确保所有组件的init()方法都能正常工作。权重初始化所有随机初始化应集中在BrandNewBertPreTrainedModel的_init_weights方法中依据配置变量初始化各叶子模块。文档给出的 BERT 风格示例def _init_weights(self, module): Initialize the weights if isinstance(module, nn.Linear): module.weight.normal_(mean0.0, stdself.config.initializer_range) if module.bias is not None: module.bias.zero_() elif isinstance(module, nn.Embedding): module.weight.normal_(mean0.0, stdself.config.initializer_range) if module.padding_idx is not None: module.weight.data[module.padding_idx].zero_() elif isinstance(module, nn.LayerNorm): module.bias.zero_() module.weight.fill_(1.0)需要说明的是当前仓库中 BERT 的实现已演进出更完整的形态——src/transformers/models/bert/modeling_bert.py#L547-L553 中的_init_weights会先super()._init_weights(module)委托通用初始化再对BertLMPredictionHead、BertEmbeddings等做特化处理。对于需要“部分模块保留 PyTorch 原生初始化”的场景文档以Wav2Vec2ForPreTraining的project_hid/project_q为例可给这些子模块打上_is_hf_initialized标志位防止自定义初始化被通用_init_weights覆盖def _init_weights(self, module): Initialize the weights if isinstance(module, Wav2Vec2ForPreTraining): module.project_hid.reset_parameters() module.project_q.reset_parameters() module.project_hid._is_hf_initialized True module.project_q._is_hf_initialized True elif isinstance(module, nn.Linear): module.weight.normal_(mean0.0, stdself.config.initializer_range) if module.bias is not None: module.bias.zero_()_is_hf_initialized标志在库内部的初始化机制src/transformers/initialization.py中被广泛使用用于确保每个子模块只被初始化一次。3.4 第六步编写 Checkpoint 转换脚本接下来写一个转换脚本把你在原仓库用于调试的 Checkpoint 转换成可被 Transformers 实现加载的格式。不要从零开始——先在 Transformers 里搜索处理“同框架、相似模型”的既有转换脚本复制后微调即可TensorFlow → PyTorch可参考 BERT 建模文件中的 TF 转换脚本文档引用了modeling_bert.py中的对应部分PyTorch → PyTorch参考 BART 的转换脚本 src/transformers/models/bart/convert_bart_original_pytorch_checkpoint_to_pytorch.py该文件在当前仓库中真实存在可直接打开研读其“加载原 Checkpoint → 按名对齐 → 断言形状 → 写入”的完整写法。转换脚本的核心是理解PyTorch 如何按“类属性名”定义层名。用一个 dummy 模型SimpleModel说明from torch import nn class SimpleModel(nn.Module): def __init__(self): super().__init__() self.dense nn.Linear(10, 10) self.intermediate nn.Linear(10, 10) self.layer_norm nn.LayerNorm(10)print(model)会输出层结构可以确认层名就是类属性名SimpleModel( (dense): Linear(in_features10, out_features10, biasTrue) (intermediate): Linear(in_features10, out_features10, biasTrue) (layer_norm): LayerNorm((10,), eps1e-05, elementwise_affineTrue) )print(model.dense.weight.data)则显示随机初始化的权重张量。转换脚本要做的是把这些随机权重逐一替换为 Checkpoint 中对应层的精确权重例如# retrieve matching layer weights, e.g. by # recursive algorithm layer_name dense pretrained_weight array_of_dense_layer model_pointer getattr(model, dense) model_pointer.weight.data torch.from_numpy(pretrained_weight)关键在于每个随机初始化权重与对应 Checkpoint 权重必须在形状与命名上精确匹配因此必须加形状断言并打印权重名assert ( model_pointer.weight.shape pretrained_weight.shape ), fPointer shape of random weight {model_pointer.shape} and array shape of checkpoint weight {pretrained_weight.shape} mismatchedlogger.info(fInitialize PyTorch weight {layer_name} from {pretrained_weight.name})若形状或名字不匹配说明你把错误的 Checkpoint 权重赋给了某层。形状错误多半源于BrandNewBertConfig()参数与原 Checkpoint 训练配置不一致也可能是该层权重需要先转置才能被 PyTorch 实现接受。最后务必核对所有必需权重都已初始化并打印出未被使用的 Checkpoint 权重。转换失败形状断言/命名错误是完全正常的通常源于Config 参数错误、架构实现有误、组件init()缺陷或某权重需要转置。反复迭代直到全部权重正确加载然后model.save_pretrained(/path/to/converted/checkpoint/folder)该目录将同时包含pytorch_model.bin与config.json。3.5 第七步实现并验证前向传播权重加载正确后验证 forward pass。你在第三~四步已用原仓库写过前向脚本现在写一个使用 Transformers 实现的对应版本model BrandNewBertModel.from_pretrained(/path/to/converted/checkpoint/folder) input_ids [0, 4, 4, 3, 2, 4, 1, 7, 19] output model(input_ids).last_hidden_states首次运行与原始实现输出不一致、甚至直接报错都是预期内的。先确保不报错——常见错误是用错维度Dimensionality mismatch或用错数据类型如该用torch.float32却传了torch.long。验证目标是输出在1e-3精度内一致分两步形状一致两个脚本的outputs.shape相同数值一致。这是添加新模型最难的部分之一。官方列出的高频错误漏加层——比如漏了激活层或忘了残差连接词嵌入矩阵没有绑定tied weights使用了错误的位置嵌入原实现可能有 offset前向中误启用了 Dropout——确保model.training为False且把self.training正确传给torch.nn.functional.dropout。修复方法是把两个实现的前向并排对照在两边相同位置插打印/取中间结果定位第一个出现偏差的网络位置先确认两边硬编码input_ids一致再依次检查词嵌入、逐层往下直到找到差异点。文档推荐的笨办法往往高效在同名位置两边都加打印逐个删除输出相同的打印。确认一致后用torch.allclose(original_output, output, atol1e-3)收尾——通过它最难的阶段就完成了。3.6 第八步补齐模型测试模型虽然能跑但未必符合库的设计规范必须通过全部共性测试。脚手架已在tests/models/brand_new_bert/test_modeling_brand_new_bert.py生成测试文件对应仓库中如 tests/models/bert/test_modeling_bert.py 这样的既有模型测试布局先运行通用测试pytest tests/models/brand_new_bert/test_modeling_brand_new_bert.py通用测试通过后还要补两类测试价值在于a) 让社区通过测试理解brand_new_bert的专有行为b) 防止未来改动破坏关键功能。集成测试本质上是把你移植时写的调试脚本沉淀为测试。脚手架已生成名为BrandNewBertModelIntegrationTests的模板类填好后用慢速模式运行RUN_SLOW1 pytest -sv tests/models/brand_new_bert/test_modeling_brand_new_bert.py::BrandNewBertModelIntegrationTestsWindows 用户请把RUN_SLOW1换成SET RUN_SLOW1。专有功能测试brand_new_bert独有的功能在BrandNewBertModelTester/BrandNewBertModelTest中单独测试。这部分最容易被遗忘但对知识传递与回归保护都极重要。3.7 第九步实现 Tokenizer通常新模型的 Tokenizer 与已有某个 Tokenizer 相同或非常相似。关键前置条件找到/提取原始 Tokenizer 文件并能在 Transformers 实现中成功加载它。验证方法同样是“双脚本对照”。先在原仓库写一个“输入字符串 → 输出 input_ids”的脚本input_str This is a long example input string containing special characters .$?-, numbers 2872 234 12 and words. model BrandNewBertModel.load_pretrained_checkpoint(/path/to/checkpoint/) input_ids model.tokenize(input_str)可能需要再查一次原仓库找对分词函数甚至修改原代码使其只输出input_ids。然后写 Transformers 侧的对应脚本from transformers import BrandNewBertTokenizer input_str This is a long example input string containing special characters .$?-, numbers 2872 234 12 and words. tokenizer BrandNewBertTokenizer.from_pretrained(/path/to/tokenizer/folder/) input_ids tokenizer(input_str).input_ids两边input_ids一致后加入 Tokenizer 测试文件并像建模测试一样写死若干集成测试用例。3.8 第十步端到端集成测试与 GPU 验证添加能同时覆盖模型与 Tokenizer 的端到端集成测试到tests/models/brand_new_bert/test_modeling_brand_new_bert.py用一个有代表性的文本到文本样例源-目标翻译对、文章-摘要对、问题-答案对等证明实现符合预期。若所移植的 Checkpoint 没有在任何下游任务上微调过只靠模型测试也够。最后一步完整性检查在 GPU 上跑全部测试。你可能漏了给内部张量加.to(self.device)这类错误只在 GPU 测试中暴露。若没有 GPU 资源可以请维护团队代为执行。3.9 第十一步Docstring 与文档页至此功能齐全只差文档。脚手架生成的docs/source/model_doc/brand_new_bert.md模板需要你来填——从 src/transformers/cli/add_new_model_like.py 中create_doc_file函数可以看到模板结构Overview论文名/链接/作者/摘要占位符、Tips、贡献者与原始代码链接、Usage examples以及每个公共类的[[autodoc]]段落。用户通常先读这个页面再用你的模型所以文档必须清晰简洁加几条Tips展示模型该怎么用会很有价值。同时确保modeling_brand_new_bert.py中的 docstring 正确、覆盖所有必要输入输出库有专门的书写文档格式说明docstring 质检器也会检查。记住文档至少应与代码同等精心因为文档通常是社区与模型的第一接触点。3.10 代码重构与质量检查全部功能就绪后先跑格式化工具修正代码风格make style再确认代码风格能通过质量检查make check-repo对照 Makefile 可以看到这两条命令背后的真实质检器集合make style执行 ruff check/format、init_isort与sort_auto_mappingsMakefile#L42-L43make check-repo则以--keep-going方式跑全部检查器Makefile#L58-L59其中包括两组 CI 作业维护的规范清单——代码质量组types、modeling_structure加风格项与仓库一致性组auto_mappings、imports、import_complexity、copies、modular_conversion、inits、doc_toc、reviewers、docstrings、dummies、repo、pipeline_typing、config_docstrings、config_attributes、doctest_list等见 Makefile#L13-L38。此外还有几项严格的“设计测试”可能让 PR 失败常见原因是 docstring 信息缺失或命名不规范——卡住时维护团队会帮忙。最后在确认一切正确后再回头重构一遍新增代码是官方推荐的良好习惯。3.11 第十二步上传模型到 Model Hub把所有 Checkpoint 转换并上传到 Hub为每个 Checkpoint 撰写模型卡。官方建议与团队一起确定合适的命名并获取在原作者组织下上传所需的访问权限模型共享与上传的完整说明见 docs/source/de/model_sharing.md。push_to_hub是快速高效的推送方式brand_new_bert.push_to_hub(brand_new_bert) # Uncomment the following line to push to an organization. # brand_new_bert.push_to_hub(organization/brand_new_bert)值得花时间写好每张模型卡突出该 Checkpoint 的特性——在什么数据集上预训练/微调适合哪些下游任务并附上正确的使用示例代码。3.12 第十三~十四步可选Notebook 与提交最终 PR添加一个详细展示brand_new_bert如何做推理和/或下游微调的 Notebook 不是 PR 合并的必要条件但对社区非常有用。收尾阶段给完工的 PR 写一份漂亮的描述必要时在代码上补注释把 Reviewer 的注意力引到关键设计决策上然后等待合并。完成一次模型添加是对整个生态的重要贡献——你的代码与移植的预训练模型会被大量开发者使用也值得在社区中分享这份成果。四、关键路径速查内容仓库相对路径本文档对应文档德语/英语docs/source/de/add_new_model.md / docs/source/en/add_new_model.md新模型脚手架 CLI 实现依赖 libcstsrc/transformers/cli/add_new_model_like.pyCLI 命令注册src/transformers/cli/transformers.pyBART PyTorch 权重转换脚本范例src/transformers/models/bart/convert_bart_original_pytorch_checkpoint_to_pytorch.pyBERT 当前_init_weights实现src/transformers/models/bert/modeling_bert.py初始化机制与_is_hf_initialized标志src/transformers/initialization.py既有模型测试布局参考tests/models/bert/test_modeling_bert.pymake style/make check-repo质检器清单Makefile.[quality]/.[dev]依赖定义setup.pyPR 检查含 Copied from 规则docs/source/de/pr_checks.md模型上传与共享指南docs/source/de/model_sharing.md最后提醒两点适用前提本文所有命令pip install -e、make、pytest、transformers add-new-model-like均以在Transformers 仓库源码根目录下执行、且已按上文装好.[dev]或.[quality]环境为前提其中add-new-model-like额外要求安装libcst。CPU 即可完成全部移植与调试工作GPU 仅在最终验证阶段需要。【免费下载链接】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），仅供参考