使用 PushToHubMixin 将 Diffusers 模型、Scheduler 与 Pipeline 一键上传到 Hugging Face Hub【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers导读本指南讲解 Diffusers 中统一的上传接口 ——PushToHubMixin它能够一次完成在 Hub 创建仓库 → 本地保存模型/调度器/流水线文件 → 上传到远程仓库三个步骤让模型、Scheduler 和 Pipeline 的分享与二次加载都只需一行push_to_hub调用。读完本文你将掌握三类对象的上传姿势、私有仓库设置、组织仓库命名规则以及save_pretrained(push_to_hubTrue)这条在训练脚本中高频出现的进阶用法。前置准备登录 Hugging Face 账号上传到 Hub 需要先完成身份认证。Diffusers 复用huggingface_hub的登录机制两种方式任选其一Notebook / 交互式环境调用notebook_login()会弹出链接引导你在浏览器中完成授权并把 token 写入本地缓存from huggingface_hub import notebook_login notebook_login()命令行HF CLIhf auth login命令执行后会要求输入你的访问令牌Access Token登录凭证默认保存在本地~/.huggingface目录。push_to_hub的token参数正是读取该凭证若你通过环境变量或代码显式传入 token则会优先使用传入值。PushToHubMixin上传的三步合一底座模型、Scheduler、Pipeline 之所以能共享同一种上传体验是因为它们都混入了PushToHubMixin这个工具类。从 hub_utils.py 的源码 可以看到push_to_hub内部实际做了三件事调用create_repo(...)在 Hub 上创建或复用目标仓库并返回规范化后的repo_id在临时目录中调用save_pretrained(...)把所有文件落盘同时生成或更新模型卡片README.md调用_upload_folder(...)底层是huggingface_hub.upload_folder把整个目录推送到远程。其中提交信息commit message是自动生成的类名含Model时默认Upload model含Scheduler时默认Upload scheduler其余如 Pipeline默认Upload {ClassName}。push_to_hub 完整参数说明源码中的函数签名 定义了以下参数掌握它们可以覆盖绝大多数上传场景参数类型 / 默认值作用repo_idstr必填目标仓库名可含组织前缀如your-org/my-model也可传本地目录路径commit_messagestr | None自定义提交信息默认按对象类型自动生成privatebool | None是否创建私有仓库None时遵循组织默认策略且仅对新建仓库生效tokenstr | None远程认证令牌默认使用hf auth login保存的凭证create_prbool默认False为True时以 Pull Request 形式提交文件而非直接 commitsafe_serializationbool默认True权重是否以safetensors格式保存variantstr | None指定时权重按pytorch_model.variant.bin的命名保存Scheduler 不支持该参数源码中会跳过subfolderstr | None将文件上传到仓库的指定子目录从源码看variant参数会被条件过滤只有当类名中不包含Scheduler时才会传入save_pretrained见 hub_utils.py 第 582-584 行因为调度器只有一份scheduler_config.json无需多版本权重。上传模型Model任何继承自ModelMixin的模型组件UNet、VAE、ControlNet、Transformer 等都能直接调用push_to_hub。下面以 ControlNet 为例from diffusers import ControlNetModel controlnet ControlNetModel( block_out_channels(32, 64), layers_per_block2, in_channels4, down_block_types(DownBlock2D, CrossAttnDownBlock2D), cross_attention_dim32, conditioning_embedding_out_channels(16, 32), ) controlnet.push_to_hub(my-controlnet-model)执行后仓库里会包含该模型的config.json配置文件权重则因safe_serializationTrue默认以.safetensors文件保存比pickle更安全、加载更快。重新加载时用对应的from_pretrained类方法即可model ControlNetModel.from_pretrained(your-namespace/my-controlnet-model)注意repo_id只写my-controlnet-model时仓库会创建在你自己的命名空间下想推送到组织请使用your-org/my-controlnet-model这种组织名/仓库名的完整格式源码示例见 hub_utils.py 第 560-572 行。上传调度器SchedulerScheduler 同样继承了PushToHubMixin见SchedulerMixin。以 DDIM 为例from diffusers import DDIMScheduler scheduler DDIMScheduler( beta_start0.00085, beta_end0.012, beta_schedulescaled_linear, clip_sampleFalse, set_alpha_to_oneFalse, ) scheduler.push_to_hub(my-controlnet-scheduler)与模型不同Scheduler 本质上只是一组噪声调度配置因此仓库中只保存一份scheduler_config.json文件不含任何权重。这也解释了上面提到的variant参数对 Scheduler 无效的原因。加载时使用SchedulerMixin.from_pretrainedscheduler DDIMScheduler.from_pretrained(your-namespace/my-controlnet-scheduler)上传完整 PipelinePipeline 是多个组件的集合上传时push_to_hub会把每个可保存的组件分别存入仓库的一个子目录再在根目录写入model_index.json作为组件清单保证日后能用DiffusionPipeline.from_pretrained一键还原整条流水线。先初始化各组件以 Stable Diffusion 为例使用小尺寸配置便于演示from diffusers import ( UNet2DConditionModel, AutoencoderKL, DDIMScheduler, StableDiffusionPipeline, ) from transformers import CLIPTextModel, CLIPTextConfig, CLIPTokenizer unet UNet2DConditionModel( block_out_channels(32, 64), layers_per_block2, sample_size32, in_channels4, out_channels4, down_block_types(DownBlock2D, CrossAttnDownBlock2D), up_block_types(CrossAttnUpBlock2D, UpBlock2D), cross_attention_dim32, ) scheduler DDIMScheduler( beta_start0.00085, beta_end0.012, beta_schedulescaled_linear, clip_sampleFalse, set_alpha_to_oneFalse, ) vae AutoencoderKL( block_out_channels[32, 64], in_channels3, out_channels3, down_block_types[DownEncoderBlock2D, DownEncoderBlock2D], up_block_types[UpDecoderBlock2D, UpDecoderBlock2D], latent_channels4, ) text_encoder_config CLIPTextConfig( bos_token_id0, eos_token_id2, hidden_size32, intermediate_size37, layer_norm_eps1e-05, num_attention_heads4, num_hidden_layers5, pad_token_id1, vocab_size1000, ) text_encoder CLIPTextModel(text_encoder_config) tokenizer CLIPTokenizer.from_pretrained(hf-internal-testing/tiny-random-clip)然后组装成 Pipeline 并上传components { unet: unet, scheduler: scheduler, vae: vae, text_encoder: text_encoder, tokenizer: tokenizer, safety_checker: None, feature_extractor: None, } pipeline StableDiffusionPipeline(**components) pipeline.push_to_hub(my-pipeline)这里把safety_checker和feature_extractor显式置为None意味着这两类组件不会被保存。在 pipeline_utils.py 的保存逻辑 中is_saveable_module会跳过值为None的可选组件避免生成无法加载的空目录。加载时一条命令即可恢复整条流水线pipeline StableDiffusionPipeline.from_pretrained(your-namespace/my-pipeline)上传 Pipeline 的另一种姿势save_pretrained(push_to_hubTrue)除了直接调用push_to_hubDiffusionPipeline.save_pretrained也内置了push_to_hub开关。当它为True时方法会在本地保存完毕后自动完成创建仓库 → 生成模型卡片 → 上传目录的全流程repo_id可通过关键字参数传入缺省时取save_directory的末级目录名见 pipeline_utils.py 第 297-303 行。这在分布式训练脚本中尤其常见——训练完成后只需pipeline.save_pretrained( ./my-pipeline, push_to_hubTrue, repo_idyour-namespace/my-pipeline, )即可同时完成本地留存与远程分享。SchedulerMixin.save_pretrained同样支持该参数见 scheduling_utils.py 第 164 行。隐私控制私有仓库默认情况下上传的仓库对所有人公开。如果只想自己可见在push_to_hub中设置privateTruecontrolnet.push_to_hub(my-controlnet-model-private, privateTrue)私有仓库的可见性规则需要特别注意只有仓库所有者及组织内有权限的成员能看到和克隆不会出现在 Hub 搜索结果中即使其他用户拿到了仓库 URL访问时也会收到404 - Sorry, we cant find the page you are looking for从私有仓库加载模型前必须保证当前环境已登录否则同样无法下载。从源码看private仅在仓库不存在时生效——如果同名仓库已存在该参数会被忽略见 hub_utils.py 第 547-549 行因此需要调整可见性时应先确认目标仓库的状态。进阶技巧小结组织仓库repo_id使用your-org/repo-name格式即可推送到组织命名空间适用于团队协作与项目统一管理。PR 式提交设置create_prTrue文件会以 Pull Request 形式提交方便在合并前进行 review适合有严格协作流程的团队。权重格式默认safe_serializationTrue输出safetensors如需传统pytorch_model.binpickle格式可显式传safe_serializationFalse。验证加载上传完成后务必在干净环境中用对应的from_pretrained重新加载一次确认仓库内文件完整、组件路径正确。参考实现路径PushToHubMixin与push_to_hub完整实现模型上传基类ModelMixin调度器上传基类SchedulerMixinPipeline 保存与上传逻辑DiffusionPipeline.save_pretrained【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考