Transformers 模板指南：使用 Cookiecutter 与 `add-new-model-like` 向 Transformers 添加新模型

推理引擎大模型【免费下载链接】FlexGenRunning large language models on a single GPU for throughput-oriented scenarios.项目地址https://gitcode.com/gh_mirrors/fl/FlexGen点击查看免费下载本篇技术指南完整讲解 HuggingFace Transformers 仓库内置的「新模型脚手架」能力如何借助transformers-cli add-new-modelCookiecutter 模板和transformers-cli add-new-model-like克隆式生成两条 CLI 命令自动生成模型配置、PyTorch/TensorFlow/Flax 建模代码、Tokenizer、文档与测试文件并将其注册进 Auto 类映射与主__init__.py。读完本文你将掌握两条生成路径的完整交互流程、生成文件的目录结构、# Copied from同步机制的约束以及提交合入前必须通过的make fixup/make fix-copies等质量关卡并了解 FlexGen 仓库中作为第三方依赖内置的该模板的源码级实现。模板目录与两条生成路径概览本仓库的benchmark/third_party/transformers/目录下内置了一份完整的 Transformers 源码树其中新模型脚手架位于 templates/adding_a_new_model/其核心内容包括README.md—— 本文所依据的官方使用指南即本篇讲解对象cookiecutter.json—— Cookiecutter 模板的配置项与默认值含 BERT / BART / Standalone 三种 tokenizer_type 与多框架组合选项cookiecutter-template-{{cookiecutter.modelname}}/—— 渲染产物模板目录内含configuration_*.py、modeling_*.py、modeling_tf_*.py、modeling_flax_*.py、tokenization_*.py、三个框架的测试文件、*.mdx文档与to_replace_*.py注册脚本ADD_NEW_MODEL_PROPOSAL_TEMPLATE.md与open_model_proposals/—— 面向社区贡献者的模型移植提案模板tests/—— 供 CLI 自动化测试使用的多组 JSON 配置pt-encoder-bert-tokenizer.json、standalone.json等。官方提供两条生成路径二者有明确的定位差异命令原理适用场景transformers-cli add-new-model基于 Cookiecutter 模板从零生成以 BERTencoder-only或 BARTencoder-decoder为底座的模型代码新模型与 BERT/BART 结构相近希望获得完整的七件套模板transformers-cli add-new-model-like克隆一个已存在模型的整套文件做命名模式替换并自动补齐# Copied from声明新模型与某个既有模型高度相似只需局部 tweak注意从本仓库内置的 add_new_model.py 源码看add-new-model命令已标记为 deprecated计划在 Transformers v5 移除官方建议优先使用add-new-model-like但 Cookiecutter 模板本身仍被保留并作为add-new-model-like生成思路的参考。使用 Cookiecutter 模板生成新模型环境准备与命令启动add-new-model依赖cookiecutter包需要先安装 Transformers 的全部 dev 依赖。在仓库根目录执行git clone https://github.com/huggingface/transformers cd transformers pip install -e .[dev]随后启动交互式生成transformers-cli add-new-model从源码 add_new_model.py 可以看到若环境中缺少cookiecutter命令会抛出ImportError并提示先执行pip install -e .[modelcreation]README 中写的是[dev]两者均会引入模板生成所需依赖。启动后CLI 内部会定位到templates/adding_a_new_model目录并调用cookiecutter(str(path_to_cookiecutter))渲染模板。回答交互式问卷cookiecutter会依据 cookiecutter.json 逐个向你提问。核心问题如下1. 模型名及其四种大小写变体modelname应按论文中的普通文本大小写填写如 BERT、RoBERTa、DeBERTa其余三种大小写变体用于不同代码场景modelname [ModelNAME]: uppercase_modelname [MODEL_NAME]: lowercase_modelname [model_name]: camelcase_modelname [ModelName]:各变体的用途可以对照模板源码印证uppercase_modelname用于XX_PRETRAINED_MODEL_ARCHIVE_LIST常量名camelcase_modelname用于类名如BrandNewBertModellowercase_modelname用于模块目录与文件名如brand_new_bert/。默认值即modelname的相应大小写转换例如在 cookiecutter.json 中以BrandNewBERT/BRAND_NEW_BERT/brand_new_bert/BrandNewBert为示例。2. 作者信息authors [The HuggingFace Team]:填写你的团队/个人署名该值会写入生成文件顶部的版权头如Copyright 2022 {{cookiecutter.authors}} The HuggingFace Inc. team见 modeling 模板。3. 检查点标识符checkpoint_identifier [organisation/model_name-base-cased]:这是后续所有示例与集成测试中引用的检查点名称会作为_CHECKPOINT_FOR_DOC、PRETRAINED_MODEL_ARCHIVE_LIST的首项写入建模文件。务必包含组织前缀如organisation/brand-new-bert-base-cased且该名字将出现在 Model Hub 上。4. Tokenizer 类型Select tokenizer_type: 1 - Based on BERT 2 - Standalone Choose from 1, 2 [1]:Based on BERT复用 BERT 分词逻辑仅需替换词表等资源Standalone生成完全独立的 Tokenizer 实现。在 cookiecutter.json 中实际还保留了第三项Based on BART对应 encoder-decoder 场景。5. 架构类型与框架组合模板中注释掉的is_encoder_decoder_model问题提示了底层规则encoder-only 架构基于 BERT 生成encoder-decoder 架构基于 BART 生成。实际生效的框架组合选项来自 cookiecutter.json 的generate_tensorflow_pytorch_and_flax支持以下组合PyTorch, TensorFlow and Flax全框架PyTorch TensorFlow/PyTorch Flax/TensorFlow Flax双框架PyTorch/TensorFlow/Flax单框架生成器会根据你的选择只产出对应框架的 modeling 与测试文件未选择的框架文件会在 add_new_model.py 中被os.remove清理。生成产物7 个新文件命令执行完成后仓库中会新增 7 个文件目录结构以仓库内模板渲染后的实际落点为参照README 中给出的路径即模板产物的标准去向docs/source/model_doc/model_name.mdx src/transformers/models/model_name/configuration_model_name.py src/transformers/models/model_name/modeling_model_name.py src/transformers/models/model_name/modeling_tf_model_name.py src/transformers/models/model_name/tokenization_model_name.py tests/test_modeling_model_name.py tests/test_modeling_tf_model_name.py结合 add_new_model.py 的落盘逻辑实际行为还包括在src/transformers/models/model_name/创建模型模块目录并在tests/models/model_name/创建测试目录含空的__init__.py因为测试文件存在父级相对导入modeling_*.py、modeling_tf_*.py、modeling_flax_*.py分别移动到模型模块目录测试文件移动到测试目录文档*.mdx移动到docs/source/en/model_doc/tokenization_model_name.py与tokenization_model_name_fast.py由模板中的两个 tokenization 文件分别落位模板自带一个to_replace_model_name.py注册脚本内含# To replace in:/# Below:/# Replace with:/# End.标记块CLI 据此把 import 语句、Auto 映射等代码片段插入到src/transformers/__init__.py、src/transformers/models/__init__.py以及各auto/映射文件中见 add_new_model.py 的replace_in_files实现。运行测试验证生成完成后运行以下命令验证全部测试通过python -m pytest ./tests/test_*model_name*.py然后按需修改每个文件使其符合你自己的模型行为。理解# Copied from代码同步机制生成文件中会出现大量以如下注释开头的类或函数# Copied from transformers.[...]这是 Transformers 库内部的代码一致性保证机制带该注释的代码块被视为从源位置「复制」而来make fix-copies会自动将源位置的代码同步覆盖到所有复制位置。因此如果新模型的实现与源不同必须删除这行注释否则运行make fix-copies时你的修改会被源代码覆盖如果只是局部 tweak保留注释即可持续享受自动同步。从 add_new_model_like.py 的duplicate_module实现可以进一步看到该机制的生成侧细节克隆建模文件时工具会对每个类/函数做命名模式替换Bert-BertNew、BertConfig-BertNewConfig等并自动插入# Copied from 源模块.旧类名 with 替换列表注释替换列表会被simplify_replacements精简如Bert-BertNew已隐含BertConfig-BertNewConfig时后者会被剔除。使用add-new-model-like克隆式生成新模型安装与启动同样需要 dev 依赖git clone https://github.com/huggingface/transformers cd transformers pip install -e .[dev]启动命令transformers-cli add-new-model-like回答问卷关键问答逐项说明命令会启动一个交互式问卷。对照源码 get_user_input()各问题的含义如下。第一步指定被克隆的旧模型What is the model you would like to duplicate? Please provide the lowercase model_type (e.g. roberta):model_type是模型在库内的标识符可在两处找到该模型任意检查点的config.json中该模型文档页面的名字例如BigBirdPegasus的文档页为https://huggingface.co/docs/transformers/model_doc/bigbird_pegasus其model_type即为bigbird_pegasus。如果拼写有误命令会借助difflib.get_close_matches提示最接近的候选 model_type见 add_new_model_like.py。第二步新模型的命名与各大小写变体What is the name (with no special casing) for your new model in the paper (e.g. RoBERTa)? What identifier would you like to use for the model_type of this model? What lowercase name would you like to use for the module (folder) of this model? What prefix (camel-cased) would you like to use for the model classes of this model (e.g. Roberta)? What prefix (upper-cased) would you like to use for the constants relative to this model?第一个问题论文名无特殊大小写如RoBERTa会作为基准其余问题自动给出默认值model_type默认取名字小写并把空格换成-模块名默认小写并把空格/连字符换成_类名前缀默认 CamelCase常量前缀默认全大写。命名规则在 ModelPatterns.post_init中完整定义可自行确认或覆盖。第三步配置类名What will be the name of the config class for this model?默认值为{CamelCase}Config。第四步检查点标识符Please give a checkpoint identifier (on the model Hub) for this new model (e.g. facebook/roberta-base):将写入所有示例与集成测试务必包含组织前缀。第五步是否复用旧模型的预处理类Will your new model use the same processing class as xxx (XxxTokenizer/XxxFeatureExtractor)回答yes直接复用旧模型的 Tokenizer / Feature Extractor / Processor允许换用新词表文件回答no会继续询问新类名默认{CamelCase}Tokenizer、{CamelCase}FeatureExtractor、{CamelCase}Processor仅询问旧模型确实拥有的预处理类型。第六步是否生成# Copied from声明Should we add # Copied from statements when creating the new modeling file?计划完全重写 modeling 文件 → 回答no只想 tweak 其中一小部分 → 回答yes此时生成的类/函数会带# Copied from注释便于make fix-copies追踪源位置。第七步框架范围Should we add a version of your new model in all the frameworks implemented by Old Model (xxx)?回答yes为旧模型实现过的所有框架各生成一份PyTorch / TensorFlow / Flax回答no继续追问让你输入所需的框架列表pt、tf、flax用空格分隔。生成逻辑与产物命令结束后会在src/transformers/models/下新建模型子目录。结合 create_new_model_like 的实现生成过程分六步克隆模型模块复制旧模型的 configuration / modeling 文件按所选框架过滤做命名替换并可选插入# Copied from注释__init__.py中未选框架的 import 会被clean_frameworks_in_init清理注册到 init在src/transformers/models/__init__.py与主src/transformers/__init__.py中追加新模型的 import 条目克隆测试文件复制tests/models/model_type/下的测试同样做命名替换若新模型暂不支持torch.fx符号跟踪测试中的fx_compatible True会被自动改为False并打印提示注册 Auto 类通过add_model_to_auto_classes把新模型写入configuration_auto.py、modeling_auto.py、modeling_tf_auto.py、modeling_flax_auto.py、feature_extraction_auto.py、processing_auto.py的映射表Tokenizer 则由insert_tokenizer_in_auto_module特殊处理进TOKENIZER_MAPPING_NAMES生成文档基于旧模型文档生成docs/source/en/model_doc/model_type.mdx自动替换标题、Overview 占位模板与类文档块并按所选框架裁剪 TF/Flax 章节打印警示信息若旧模型的model_type、checkpoint、lowercase 名存在同名情况会提示你手动检查新文件中可能被错误替换为 checkpoint/model_type 的位置。之后需要先运行make style make fix-copies再开始 tweak 你的模型填充docs/source/model_doc/model_name.mdx的文档内容调整 configuration 与 modeling 文件。完成后运行测试验证python -m pytest ./tests/test_*model_name*.py对# Copied from的处理与 Cookiecutter 路径完全相同实现有差异就删掉注释行否则make fix-copies会覆盖你的改动。提交流程与合入前检查清单两条路径都建议在生成并修改完毕后执行以下质量关卡运行make fixup或make style以统一代码风格保证符合库的代码质量规范完善文档文件docs/source/model_doc/model_name.mdx确保模型可被文档化使用add-new-model-like路径额外要求把新模型加入主 README 模型列表然后运行make fix-copies同步各处拷贝重新运行测试并修改失败用例确保全部通过后再提交 Pull Request。仓库内置模板的扩展阅读路径FlexGen 仓库把整套 Transformers 作为 benchmark 第三方依赖内置你可以在以下位置继续深挖模板与配置templates/adding_a_new_model/cookiecutter.json、模板渲染产物目录命令实现add_new_model.pyCookiecutter 路径、add_new_model_like.py克隆式路径注册脚本语法to_replace_{{cookiecutter.lowercase_modelname}}.py 头部的注释块说明了# To replace in:/# Below:/# Replace with:/# End.标记的书写规则社区移植提案模板ADD_NEW_MODEL_PROPOSAL_TEMPLATE.md 与 open_model_proposals/其中保留了 BigBird 的完整提案示例可作为「从论文移植到 Transformers」全流程的参考蓝图。值得强调的是本模板位于 FlexGen 的 benchmark/third_party/ 依赖目录下属于 benchmark 环境的一部分读者如需在 FlexGen 工作区内查阅上述路径即可实际使用脚手架时应在独立的 Transformers 源码 clone 中执行add-new-model命令会默认基于可编辑安装的源码根目录定位模板见 add_new_model.py。赞分享推理引擎大模型【免费下载链接】FlexGenRunning large language models on a single GPU for throughput-oriented scenarios.项目地址https://gitcode.com/gh_mirrors/fl/FlexGen点击查看免费下载相关推荐Transformers 新模型贡献完全指南Legacy 工作流、add-new-model-like 脚手架与源码级原理剖析Transformers 新模型贡献完全指南Legacy 工作流、add new model like 脚手架与源码级原理剖析 本文以 Transformer人工智能深度学习机器学习预训练微调NLP计算机视觉语音多模态如何用 modular transformers 以继承方式给 Transformers 添加新模型如何用 modular transformers 以继承方式给 Transformers 添加新模型 如果你在 HuggingFace Transformer人工智能深度学习机器学习预训练微调NLP计算机视觉语音多模态为什么Seed by Snaplet是开发者的最佳选择TypeScript类型安全详解为什么Seed by Snaplet是开发者的最佳选择TypeScript类型安全详解 Seed by Snaplet是一款为开发者打造的终极数据库填充工具推理引擎大模型上一篇OpenCore Legacy Patcher实战指南突破Mac系统限制的完整解决方案下一篇Kibi快捷键大全掌握这些技巧让你的编辑速度翻倍创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考