Transformers 模型共享指南将训练完成的模型发布到 Hugging Face 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在完成模型的微调训练之后下一个关键步骤就是将成果分享给社区。本文基于 Hugging Face Transformers 仓库中的官方共享指南docs/source/it/model_sharing.md英文原版见 docs/source/en/model_sharing.md系统讲解把训练好或微调好的模型上传到 Model Hub 的两种主流方式——编程式共享通过Trainer或push_to_hub方法与网页拖拽上传并结合仓库源码剖析底层实现。读完本文你将掌握从登录认证、跨框架转换、训练中自动推送到撰写 Model Card 的完整发布链路。一、为什么要把模型分享到 HubHugging Face 的核心理念是共享知识与资源让 AI 对所有人民主化。将训练好的模型发布到 Model Hub能帮助其他开发者省去重复训练的时间与算力成本。在 Transformers 生态中模型分享有两个关键途径编程式共享通过 Python 代码把文件推送到 Hub适合与训练流程深度集成界面拖拽共享通过 Hub 的网页图形界面无代码上传适合快速发布。无论哪种方式最终模型都能被全世界任何开发者通过一行from_pretrained加载使用。二、发布前的环境配置1. 注册账号与获取凭据要与社区共享模型首先需要一个 huggingface.co 账号。你也可以加入现有组织或创建新组织以便以组织名义发布模型。接下来需要生成一个**用户访问令牌User Access Token**用于身份认证。2. 命令行登录hf auth login如果你有终端环境在安装了 Transformers 的虚拟环境中执行以下命令登录。该命令会把访问令牌保存在 Hugging Face 的缓存目录中默认是~/.cache/hf auth login登录后令牌默认存放在缓存目录中后续所有需要认证的推送操作都会自动读取它。这一机制在源码中也有体现PushToHubMixin.push_to_hub的token参数文档明确指出默认会使用执行hf auth login时生成并存储在~/.huggingface中的令牌见 hub.py。3. 笔记本环境登录notebook_login如果使用 Jupyter 或 Colaboratory 这类笔记本环境需要先安装huggingface_hub库——它是与 Hub 进行编程式交互的基础依赖pip install huggingface_hub然后通过notebook_login登录它会生成一个链接引导你在浏览器中完成令牌授权 from huggingface_hub import notebook_login notebook_login()三、Model Hub 仓库的核心特性1. 基于 Git 与 Git LFS 的版本管理Model Hub 上的每个模型仓库都像一个典型的 GitHub 仓库提供**版本管理、提交历史commit history与差异可视化diff**功能。版本管理的底层基于 Git 和 Git Large File Storage (Git LFS)因此可以把模型当作一个真正的代码仓库来对待获得更精细的访问控制与更强的可扩展性——这正是大模型权重这类超大文件得以高效托管的关键。2. 用revision固定模型版本版本管理衍生出 **revisions修订版本**机制你可以用提交哈希commit hash、标签tag或分支branch来固定模型的某个特定版本实现可复现的加载。在from_pretrained中传入revision参数即可 model AutoModel.from_pretrained( ... julien-c/EsperBERTo-small, revision4c77982 # 标签名、分支名或提交哈希 ... )这一参数背后对应仓库源码中的下载逻辑get_checkpoint_shard_files等函数会把revision透传给 Hub API用于拉取对应版本的权重文件见 hub.py。同理在推送时你也可以通过revision指定推送到的目标分支。3. 仓库的访问控制与交互能力除了版本管理模型仓库还支持门控gating机制来控制谁能访问模型——这在研究模型公开发布前只允许特定群体预览时非常实用。仓库还内嵌推理 Widget让访问者在网页上直接与模型交互试玩。四、跨框架转换让模型适配所有生态为了让使用不同深度学习框架的开发者都能直接使用你的模型官方强烈建议同时上传 PyTorch 和 TensorFlow 两种格式的 checkpoint。虽然 Transformers 也能从异构框架加载模型但如果跳过转换步骤加载时会因为需要现场转换 checkpoint 而明显变慢。转换过程非常简单确保本地同时安装了 PyTorch 和 TensorFlow安装说明见 安装指南然后在目标框架中找到对应任务的模型类。例如要把 TensorFlow checkpoint 转换为 PyTorch指定from_tfTrue pt_model DistilBertForSequenceClassification.from_pretrained( ... path/to/the/name-you-picked, from_tfTrue ... ) pt_model.save_pretrained(path/to/the/name-you-picked)执行完save_pretrained后本地目录就同时拥有了两份权重随后便可将它们一起推送到 Hub见后文push_to_hub小节。五、训练期间自动共享Trainer 的一键推送把模型分享到 Hub 简单到只需要添加一个额外参数或一个回调。还记得微调教程docs/source/en/training.md中的TrainingArguments吗它就是指定超参数和训练选项的地方其中就包含直接向 Hub 推送模型的开关。1. 开启push_to_hub并训练在TrainingArguments中设置push_to_hubTrue from transformers import TrainingArguments, Trainer training_args TrainingArguments(output_dirmy-awesome-model, push_to_hubTrue)然后像往常一样把参数传给Trainer trainer Trainer( ... modelmodel, ... argstraining_args, ... train_datasetsmall_train_dataset, ... eval_datasetsmall_eval_dataset, ... compute_metricscompute_metrics, ... )从源码看push_to_hub的完整语义是每次保存模型时都推送到 Hub见 training_args.py。开启后output_dir会成为一个与 Hub 仓库同步的 git 目录每次触发保存由save_strategy决定都会执行推送调用Trainer.save_model也会触发推送。2. 训练结束后手动推送微调完成后调用Trainer.push_to_hub上传训练好的模型 trainer.push_to_hub()Trainer.push_to_hub默认的提交消息是End of training并支持blocking是否等待 git push 完成、token、revision等参数。Transformers 还会自动把训练超参数、训练结果和框架版本写入你的 Model Card无需手动整理。从实现细节看见 trainer.pypush_to_hub会依次执行初始化 Hub 仓库如果尚未创建、调用save_model保存模型、调用create_model_card生成模型卡片、最后通过hf_api().upload_folder把output_dir整体上传并自动忽略_*临时文件与checkpoint-*检查点目录。3. 训练过程中的推送策略hub_strategy如果希望训练过程中就持续推送中间结果而不仅是训练结束可以配置hub_strategy参数见 training_args.py。它有四种取值取值行为end仅在训练结束时推送every_save每次保存时推送默认异步执行不阻塞训练checkpoint同every_save另外把最新 checkpoint 推送到last-checkpoint子目录方便断点续训all_checkpoints推送出现的全部 checkpoint与之配合的参数还包括hub_model_id指定要同步的仓库名。可以是简单的模型 ID推送到你的命名空间下也可以是user_name/model或organization_name/model形式的完整仓库名默认值为user_name/output_dir 名称hub_token推送使用的令牌默认取hf auth login缓存的令牌hub_private_repo是否创建私有仓库。为None默认时仓库公开除非组织默认私有仓库已存在时该参数被忽略hub_always_push为True时即使上一次推送尚未完成也会继续推送否则会跳过本次推送hub_revision推送目标分支可以是分支名、标签或提交哈希。Trainer内部的_push_from_checkpoint见 trainer.py会从 checkpoint 目录中挑选配置文件、权重文件、分片索引与分片文件连同 tokenizer 和训练参数一起上传并以Training in progress, step N / epoch N作为提交消息。整个上传过程是异步的避免阻塞训练循环。六、直接调用push_to_hub函数上传模型除了Trainer你还可以直接在模型对象上调用push_to_hub上传。它的底层是PushToHubMixin——一个为模型、tokenizer 等对象提供 Hub 推送能力的混入类Mixin。1. 基础用法指定模型名称即可创建仓库并上传 pt_model.push_to_hub(my-awesome-model)这会在你的用户名下创建一个名为my-awesome-model的仓库。现在任何人都可以用from_pretrained加载你的模型 from transformers import AutoModel model AutoModel.from_pretrained(your-username/my-awesome-model)2. 推送到组织如果你属于某个组织想以组织名义发布模型push_to_hub接受organization参数这是文档中的经典写法 pt_model.push_to_hub(my-awesome-model, organizationmy-awesome-org)注从当前仓库源码看新版PushToHubMixin.push_to_hub已不再单列organization参数推荐直接使用组织名/模型名形式的repo_id——例如pt_model.push_to_hub(my-awesome-org/my-awesome-model)见 hub.py 中的 docstring 示例。旧式organization写法在早期版本仍可工作。3. 向同一仓库追加其他文件push_to_hub不仅能上传模型权重还能把 tokenizer、TensorFlow 版本权重等文件追加到同一个仓库。例如把 tokenizer 加入模型仓库 tokenizer.push_to_hub(my-awesome-model)或者把你 PyTorch 模型的 TensorFlow 版本也推上去 tf_model.push_to_hub(my-awesome-model)现在浏览你的 Hugging Face 个人主页就能看到新建的模型仓库点击Files标签页可以看到全部已上传文件。4.push_to_hub的完整参数结合 hub.py 的实现PushToHubMixin.push_to_hub支持的参数非常丰富参数类型默认值说明repo_idstr必填仓库名推送到组织时需包含组织名如org/modelcommit_messagestr按对象类型自动生成如Upload model提交消息commit_descriptionstrNone提交的描述信息privateboolNone是否创建私有仓库None时公开除非组织默认私有仓库已存在时忽略tokenbool/strNone认证令牌True时使用hf auth login生成的令牌revisionstrNone推送到的目标分支create_prboolFalse是直接提交还是创建一个 Pull Requestmax_shard_sizeint/str50GB仅对模型生效checkpoint 分片的最大尺寸超过则分片支持5MB这类带单位的写法tagslist[str]None推送到 Hub 的标签列表从执行流程看hub.pypush_to_hub的完整调用链是先用hf_api().create_repo创建仓库已存在则复用→ 生成/更新 Model Card 并打标签 → 在临时目录中调用save_pretrained保存全部文件 → 把 Model Card 写入README.md→ 最后通过_upload_modified_files把临时目录中的文件以一次 commit 推送到远端。其中_upload_modified_fileshub.py会基于文件的修改时间戳智能识别需要上传的文件并在指定revision时自动创建对应分支。5. 使用save_pretrained的注意点需要特别说明PushToHubMixin依赖对象自身实现save_pretrained方法。mixin 中的save_pretrained只是显式抛出不实现的约定见 hub.py模型、tokenizer 等具体类必须自己实现序列化逻辑push_to_hub才能正常工作。这也解释了为什么它能统一适用于模型、tokenizer、feature extractor 和 processor 等各种对象。七、无代码方案使用网页界面上传偏好零代码工作流的开发者可以直接通过 Hub 网页界面上传模型。1. 创建仓库访问 huggingface.co/new 创建新仓库然后填写模型信息Owner选择仓库所有者可以是你自己也可以是所属的任意组织Name为模型命名该名称同时也是仓库名可见性选择模型是公开public还是私有privateLicense指定模型使用的许可证。2. 上传文件点击Files标签页再点击Add file按钮把文件拖拽进上传区域填写提交消息commit message后提交文件即进入仓库。3. 网页方式与代码方式的取舍网页方式适合快速发布、非技术成员协作等场景代码方式Trainer/push_to_hub则能融入自动化训练流水线实现训练完即发布并自动生成带训练元数据的 Model Card。实际项目中常两者结合用代码推送权重再用网页补充说明文档。八、添加 Model Card让模型可被理解与信任为了确保任何使用你模型的人都能了解它的能力、局限性、潜在偏见与伦理考量官方强烈建议为仓库添加一张Model Card模型卡。Model Card 就是仓库根目录下的README.md文件可以通过两种方式添加手动创建README.md文件并上传到仓库在模型仓库页面点击Edit model card按钮在线编辑。1. Trainer 自动生成 Model Card使用Trainer.push_to_hub时Transformers 会自动生成 Model Card。Trainer.create_model_card见 trainer.py会把TrainingSummary汇总的训练信息写入output_dir/README.md。它还支持通过参数补充卡片元数据language模型适用的语言license模型许可证默认继承原始预训练模型仓库的许可证tags卡片元数据标签model_name模型名称finetuned_from微调所基于的基座模型默认取传入Trainer的原始模型仓库名tasks任务标识符dataset_tags/dataset/dataset_args训练数据集信息。如果输出目录中已有README.mdcreate_model_card还会自动合并已有标签避免覆盖手工维护的卡片内容。2. 手动补充更多元数据除了上述字段Model Card 的README.md还可以通过 YAML front-matter 声明碳足迹carbon emissions、论文链接、许可证、示例 Widget 等更多元数据让模型信息更完整。一个好的 Model Card 应涵盖模型用途与能力、训练数据与过程、评估指标与结果、已知限制与偏见、伦理考量以及使用示例。九、发布后的验证与最佳实践1. 验证模型可被加载发布后建议在一个全新的环境中用from_pretrained验证加载是否成功 from transformers import AutoModel model AutoModel.from_pretrained(your-username/my-awesome-model)2. 组合技巧速查需求推荐做法训练完自动发布TrainingArguments(output_dir..., push_to_hubTrue)trainer.push_to_hub()仅发布模型不训练model.push_to_hub(my-awesome-model)发布到组织model.push_to_hub(org-name/my-awesome-model)或旧式organization参数附带 tokenizer / TF 权重分别调用tokenizer.push_to_hub(...)、tf_model.push_to_hub(...)追加文件训练过程实时同步配置hub_strategyevery_save默认或checkpoint固定可复现版本加载时传revisioncommit-hash私有发布push_to_hub(..., privateTrue)或hub_private_repoTrue3. 几点提醒上传大模型时会自动分片max_shard_size默认50GB无需手动处理若仓库已存在private参数会被忽略可见性以仓库当前状态为准分布式训练时Trainer会保证只在主进程执行推送is_world_process_zero判断避免重复上传见 trainer.py。至此从登录认证、跨框架转换、训练中一键推送、手动push_to_hub、网页上传到 Model Card 撰写你已经掌握了完整的模型发布链路。把模型共享出去让开源 AI 的成果惠及更多人。【免费下载链接】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），仅供参考