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/transformersHugging Face Hub 是面向开发者共享、发现与消费各类模型与数据集的平台而transformers为把本地训练/微调产物上传到 Hub 提供了完整的开箱即用能力。本文以 model_sharing.md 为骨架结合当前仓库源码系统讲解从账号登录、模型仓库能力到 Trainer、push_to_hub直接推送与 Web 界面上传三条完整路径的实操方法并剖析底层实现读完后你将掌握如何把训练好的模型一键发布到 Hub 并被他人用一行代码加载。一、准备工作账号、访问令牌与登录要将模型分享到 Hub前提是拥有一个 Hugging Face 账号并创建一个User Access Token带写权限。Token 默认会被持久化存储在本地缓存目录中关于该目录的完整机制可参考 缓存目录说明 一节。登录方式有命令行与 Notebook 两种二选一即可方式一huggingface CLIhf auth login方式二Notebook 环境from huggingface_hub import notebook_login notebook_login()从源码角度登录产物Token会作为后续所有上传请求的 HTTP Bearer 鉴权凭据。在transformers中几乎所有 Hub 操作都会把token透传给 huggingface_hub 的HfApi见 utils/hub.py 中hf_api()工具函数当调用处未显式传入token时底层默认复用hf auth login写入的本地 Token这也是登录一次、随处推送的原理。二、理解模型仓库版本化、revision、gating 与 Widget每次通过push_to_hub或 Web 界面创建的模型仓库本身就是一个完整的 Git 仓库天然具备以下能力版本化Versioning底层基于 Git 与 Git Large File StorageGit LFS权重等大文件由 LFS 托管。每个仓库都拥有提交历史commit history与文件差异可视化diff visualization。修订版本Revisions由于版本化基于提交实现你可以用提交哈希、标签tag或分支branch来锁定某个确定的模型版本。在加载侧from_pretrained家族方法都支持revision参数来拉取指定版本。例如文档中的示例model AutoModel.from_pretrained( julien-c/EsperBERTo-small, revision4c77982 )Gating门控访问仓库支持门控设置用于控制谁能访问模型。这在研究模型正式公开前、仅允许特定群体预览时非常常用。Inference Widget每个模型仓库都内置推理 Widget访问者无需写任何代码即可在页面上直接与模型交互体验。关于模型仓库的完整特性说明可进一步查阅 Hub 官方 Models 文档hf.co/docs/hub/models。三、方式一训练结束后用 Trainer 一键上传对于使用Trainer做微调/训练的用户Hub 集成是最省事的一条路训练完成后只需一行trainer.push_to_hub()即可完成上传。最小示例from transformers import TrainingArguments, Trainer training_args TrainingArguments(output_dirmy-awesome-model, push_to_hubTrue) trainer Trainer( modelmodel, argstraining_args, train_datasetsmall_train_dataset, eval_datasetsmall_eval_dataset, compute_metricscompute_metrics, ) trainer.push_to_hub()TrainingArguments中push_to_hubTrue会让仓库保持与output_dir的同步中状态每次 save 触发推送而trainer.push_to_hub()在训练结束后显式上传模型并自动在模型卡中补充训练超参数与评测结果等有价值信息。Hub 集成的核心参数push_to_hubTrue之外还有一组hub_*参数共同控制推送行为它们定义于 training_args.py 的 Hub Integration 代码块中关键参数如下参数默认值作用push_to_hubFalse是否每次保存模型时都推送到 Huboutput_dir会与远端仓库保持同步hub_tokenNone推送使用的 Token缺省时使用hf auth login写入的 Tokenhub_model_idNone与本地output_dir保持同步的远端仓库名如me/awesome-modelhub_private_repoNone是否创建私有仓库None时默认公开除非所属组织的默认策略是私有hub_strategyevery_save定义推什么、何时推end/every_save/checkpoint/all_checkpointshub_always_pushFalse若为False前一次推送未完成时 Trainer 会跳过本次推送hub_revisionNone推送目标 revision可以是分支名、tag 或提交哈希其中hub_strategy的四个取值对应 trainer_utils.py 中的枚举HubStrategyEND仅训练结束时推送、EVERY_SAVE每次保存都推送、CHECKPOINT额外把最新 checkpoint 推送到远端last-checkpoint路径、ALL_CHECKPOINTS推送所有 checkpoint。编程式配置set_push_to_hub除逐个给TrainingArguments传参外也可以调用args.set_push_to_hub(model_id, strategy..., token..., private_repo..., always_push..., revision...)。该方法会自动将push_to_hub置为True并统一配置上述字段见 training_args.py。源码侧实现要点Trainer.push_to_hub 的内部流程清晰地展示了训练产物如何变成远端提交触发on_push_begin回调用save_model把模型权重、config、tokenizer/processor 写入output_dir调用create_model_card生成/更新模型卡含model_name、tags 等信息调用hf_api().upload_folder(...)把整个output_dir以一次 commit 上传到hub_model_id默认忽略_*开头的临时文件与checkpoint-*目录。另外在多进程/多卡场景下Trainer 只在is_world_process_zero()的主进程执行实际上传避免多个进程重复推送同一份内容。值得一提的是参数blocking与返回的Futuretrainer.push_to_hub(blockingFalse)时函数会立即返回一个追踪进度的Future对象便于在超长训练中做后台异步上传。四、方式二直接调用 PushToHubMixin.push_to_hub不经过Trainer时模型与 tokenizer 等对象本身也可以直接推送——其能力来自PushToHubMixinmixin定义于 utils/hub.pyPreTrainedModel、tokenizer、feature extractor、processor 等对象都继承自它。基本用法model.push_to_hub(my-awesome-model)mixin 会以你当前命名空间下名为my-awesome-model的仓库 ID 创建远端仓库。其他对象如 tokenizer的推送方式完全一致tokenizer.push_to_hub(my-awesome-model)推送完成后你的 Hugging Face 个人主页即可看到新建的模型仓库进入仓库的Files标签页可以查看上传的全部文件config、权重、vocab、README 等。完整参数签名PushToHubMixin.push_to_hub的参数相比 Trainer 版本更贴近底层可直接控制提交与序列化细节参数默认值作用repo_id必填远端仓库名推送到组织时需包含组织名如huggingface/my-finetuned-bertcommit_messageNone提交信息缺省时按对象类型自动生成见下文commit_descriptionNone提交的详细描述privateNone是否创建私有仓库仓库已存在时该值被忽略tokenNoneHTTP Bearer 鉴权 Token缺省使用hf auth login生成的 Token存储在~/.huggingfacerevisionNone推送目标分支传入非refs/pr开头的值时若分支不存在会自动创建create_prFalse是直接提交还是以 Pull Request 形式提交无写权限的仓库也可走 PR 流程max_shard_size50GB模型权重分片阈值权重超过该值会被拆分为多个 shard 文件可传整数或如5MB的带单位字符串tagsNone需要写入模型卡 YAML 的标签列表底层执行流程从 push_to_hub 实现 看一次推送实际是三步走建仓调用hf_api().create_repo(repo_id, privateprivate, tokentoken, exist_okTrue)仓库不存在则创建、已存在则复用组装模型卡调用create_and_tag_model_card(repo_id, tags, tokentoken)——若远端已存在README.md则加载并补充 tags否则基于内置模板生成一张标记了library_name: transformers的模型卡实现见同文件create_and_tag_model_card保存并上传在临时目录中调用save_pretrained(tmp_dir, max_shard_size...)完成本地序列化含权重分片把模型卡写入README.md再交由_upload_modified_files构造CommitOperationAdd操作列表并调用hf_api().create_commit(...)一次性提交。自动提交信息规则不传commit_message时mixin 会根据对象类名自动生成例如Upload model、Upload tokenizer、Upload config、Upload processor、Upload feature extractor等避免每次手动填写。tokenizer 的注意点因为该 mixin 要求实现save_pretrained未实现时会显式抛出NotImplementedError见 hub.py 中save_pretrained的说明tokenizer 需要先通过save_pretrained产出tokenizer_config.json、vocab/merges 等文件后才能被整体推送——这正是调用tokenizer.push_to_hub(...)背后发生的事情。关于向 Hub 上传文件的更多细节如目录上传、版本冲突处理可参考 Hub 官方的 Upload files to the Hub 指南。五、方式三无需代码——用 Hub Web 界面上传若不想写代码也可以全程在 Web 界面完成上传点击页面上的New Model创建新仓库完善模型信息要点如下Owner仓库归属者可选择自己或你所属的任何组织模型名称即仓库名需全局唯一可见性选择公开public或私有privateLicense设置模型的开源许可证点击Create model完成建仓进入Files标签页点击Add file按钮把文件拖拽进仓库填写提交信息commit message后点击Commit changes to main即完成提交。该路径适合一次性/低频分享高频训练同步场景仍建议优先使用Trainer或push_to_hub以便将版本历史与训练过程自动关联。六、模型卡让模型可被发现、可被信任Model Card模型卡是仓库根目录下的README.md文件用于向使用者说明模型的表现、局限性、潜在偏差与伦理考量等信息。一份详实的模型卡能显著提升模型的可信度与可复现性官方强烈建议发布时附带。添加模型卡有两种方式手动编写一个README.md并上传到仓库在仓库页面点击Edit model card按钮在线编辑。除自由格式正文外模型卡还支持结构化 YAML 元数据前文所述的tags最终就是写进这一节。这些元数据覆盖范围很广例如碳排放carbon emissions、许可证、论文链接、评估指标等均通过huggingface_hub的 ModelCard 工具链读写对应源码见 hub.py 中create_and_tag_model_card其利用ModelCardData与ModelCard.from_template在仓库没有模型卡时自动生成标准模板并将传入的 tags 与已有 tags 去重合并。如果你使用Trainer训练也可以参考Trainer.create_model_card自动生成包含训练超参数的模型卡再按需手动补充细节——这也是保证模型 文档一起发布的推荐工作流。七、验证与复盘发布后如何被消费无论用哪种方式上传发布的最终效果都应是任何人或任何下游脚本都能通过模型 ID 直接加载你的成果from transformers import AutoModel, AutoTokenizer model AutoModel.from_pretrained(你的用户名/my-awesome-model) tokenizer AutoTokenizer.from_pretrained(你的用户名/my-awesome-model)若要固定到某个确定版本例如复现实验则传入revisionmodel AutoModel.from_pretrained(你的用户名/my-awesome-model, revisioncommit-hash 或 tag 或 branch)结合本文对三种上传路径Trainer、PushToHubMixin.push_to_hub、Web 界面及背后create_repo → save_pretrained/upload_folder → create_commit调用链的了解你可以把训练 → 发布 → 被消费整条链路顺畅地打通日常迭代交给hub_strategyevery_save自动同步正式版本用带revision与commit_message的显式推送打 tag再辅以内容完整的模型卡即可让研究成果以最高质量对外呈现。【免费下载链接】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），仅供参考