Diffusers 模型/调度器/管道上传指南使用 PushToHubMixin 将文件推送到 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工具类让开发者可以一条命令把训练好的模型Model、调度器Scheduler或完整管道Pipeline直接上传到 Hugging Face Hub实现成果共享与版本托管。本指南以 docs/source/ko/using-diffusers/push_to_hub.md 为主线完整演示从登录认证、推送单一模型/调度器、推送完整管道到私有仓库设置的端到端流程并结合仓库源码剖析push_to_hub背后的自动建仓、权重序列化与模型卡片生成机制读完即可独立完成你的第一个 Hub 上传任务。PushToHubMixin三步完成文件上传PushToHubMixin是挂载在模型、调度器和管道基类上的混入类其工作流程可以归纳为三个步骤在 Hub 上创建或复用一个仓库将模型、调度器或管道的文件保存到本地临时目录确保后续可以重新加载把包含这些文件的目录上传到 Hub。调用入口是统一的PushToHubMixin.push_to_hub它负责串联建仓 → 保存 → 上传三件事你只需要传入目标repo_id即可。第一步登录 Hub 账号上传前必须先登录 Hugging Face 账号。最简单的方式是在 Notebook 或交互式环境中使用huggingface_hub提供的notebook_login它会引导你输入访问令牌Access Token可在 Hugging Face 设置页面的 Tokens 中创建from huggingface_hub import notebook_login notebook_login()在非 Notebook 的终端环境下也可以改用命令行工具登录hf auth login登录后令牌会保存在本地~/.huggingface目录后续push_to_hub调用会自动复用该凭据无需在每次调用中显式传入token参数。推送模型以 ControlNetModel 为例要推送一个模型实例化模型后调用push_to_hub并指定仓库 id 即可。下面以 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)push_to_hub会自动完成两件事保存模型的config.json配置文件将权重以safetensors格式保存因为safe_serialization默认开启可避免pickle反序列化带来的安全风险。按变体variant推送权重针对模型你还可以指定要推送的权重变体checkpoint variant。例如只上传fp16半精度权重controlnet.push_to_hub(my-controlnet-model, variantfp16)variant参数会传给底层的save_pretrained权重文件将以pytorch_model.fp16.safetensors之类的带后缀文件名存储参见 ModelMixin.save_pretrained 的variant参数说明。加载时通过from_pretrained(..., variantfp16)即可对应读取。需要注意的是调度器Scheduler类并不接受variant参数——在 push_to_hub 源码 中可以看到variant只会加入非 Scheduler 类的保存参数。从 Hub 重新加载模型上传完成后任何人都可以通过仓库 id 重新加载model ControlNetModel.from_pretrained(your-namespace/my-controlnet-model)这里的your-namespace是你的用户名或组织名my-controlnet-model是push_to_hub中指定的仓库名如果只写仓库名默认推到当前登录账号名下。推送调度器以 DDIMScheduler 为例调度器的推送方式与模型一致。例如将一套 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)调度器本质上只有一份配置因此push_to_hub只向仓库写入一个scheduler_config.json文件对应 SchedulerMixin.save_pretrained 内部调用save_config保存配置对象的实现不会像模型那样附带权重文件。重新加载调度器scheduler DDIMScheduler.from_pretrained(your-namepsace/my-controlnet-scheduler)注意加载时仓库 id 中的命名空间namespace要与上传时保持一致否则无法找到目标仓库。推送完整管道以 StableDiffusionPipeline 为例除了单独推送某个组件push_to_hub也支持把包含全部组件的完整管道一次性上传。首先按需求初始化各组件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)将全部组件组装成字典并传给StableDiffusionPipeline然后推送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)推送管道时push_to_hub会把每个组件分别保存到仓库的对应子文件夹中例如unet/、vae/、text_encoder/并额外生成一份管道级model_index.json描述组件布局。加载时它会自动按子文件夹结构重建所有组件pipeline StableDiffusionPipeline.from_pretrained(your-namespace/my-pipeline)私有仓库设置 privateTrue如果你不希望工作成果被公开只需在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的提示要从私有仓库加载模型必须先登录保持已认证状态。源码视角push_to_hub 的内部机制与完整参数从PushToHubMixin.push_to_hub的源码实现可以看到一次调用背后做了这些事情建仓调用create_repo(repo_id, privateprivate, tokentoken, exist_okTrue)仓库已存在时不会报错exist_okTrue返回规范化的repo_id生成模型卡片调用load_or_create_model_card与populate_model_card创建并填充README.md模型卡片保存文件在tempfile.TemporaryDirectory()临时目录中调用save_pretrained模型写入config.json与safetensors权重调度器写入scheduler_config.json管道按子文件夹组织各组件上传通过_upload_folder调用huggingface_hub的upload_folder把整个目录推送到 Hub默认提交信息按对象类型自动生成——模型类为Upload model、调度器类为Upload scheduler其余为Upload {类名}见 hub_utils.py#L508-L514。push_to_hub的完整签名与参数含义如下参数默认值作用repo_id必填目标仓库 id可包含组织名如your-org/my-model也可以是本地目录路径commit_messageNone提交信息默认按对象类型自动生成privateNone是否创建私有仓库None时默认公开除非组织默认私有对已存在的仓库不生效tokenNoneHTTP 鉴权令牌默认读取hf auth login保存在~/.huggingface的令牌create_prFalse是否以 Pull Request 形式提交文件而不是直接 commitsafe_serializationTrue是否将权重转为safetensors格式variantNone权重变体后缀如fp16仅对模型类生效subfolderNone将文件上传到仓库中的指定子目录另一条推送路径save_pretrained(push_to_hubTrue)除了直接调用push_to_hub模型、调度器和管道的save_pretrained方法也都支持push_to_hubTrue的快捷方式保存到本地目录的同时推送到 Hubrepo_id不指定时默认取save_directory的名字。仓库测试 tests/models/test_modeling_common.py#L312-L379 中的TestModelPushToHub即验证了这两条路径# 路径一直接推送 model.push_to_hub(self.repo_id, tokenTOKEN) # 路径二save_pretrained push_to_hubTrue with tempfile.TemporaryDirectory() as tmp_dir: model.save_pretrained(tmp_dir, repo_idsave_repo_id, push_to_hubTrue, tokenTOKEN)该测试在推送后立即用from_pretrained重新加载并逐参数断言torch.equal(p1, p2)验证权重完全一致同时覆盖了组织仓库valid_org/{repo_id}-org的推送场景说明模型、调度器、管道三大类对象均遵循可推送即可重载的对称设计。小结借助PushToHubMixin从本地对象到 Hub 上的可复用资产只需一次方法调用模型与调度器通过push_to_hub(repo_id)直接上传模型自动附带config.json与safetensors权重调度器仅上传scheduler_config.json完整管道则自动按子文件夹组织全部组件并生成model_index.jsonvariant支持权重变体、privateTrue保护私有成果、save_pretrained(push_to_hubTrue)提供等价替代路径。掌握这套流程后你便可以在训练脚本的收尾阶段一键发布成果并通过from_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），仅供参考 
长河君 · 2026/9/10 8:37:36 · 阅读 1.2k Diffusers 模型/调度器/管道上传指南：使用 PushToHubMixin 将文件推送到 Hugging Face Hub
Diffusers 模型/调度器/管道上传指南使用 PushToHubMixin 将文件推送到 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工具类让开发者可以一条命令把训练好的模型Model、调度器Scheduler或完整管道Pipeline直接上传到 Hugging Face Hub实现成果共享与版本托管。本指南以 docs/source/ko/using-diffusers/push_to_hub.md 为主线完整演示从登录认证、推送单一模型/调度器、推送完整管道到私有仓库设置的端到端流程并结合仓库源码剖析push_to_hub背后的自动建仓、权重序列化与模型卡片生成机制读完即可独立完成你的第一个 Hub 上传任务。PushToHubMixin三步完成文件上传PushToHubMixin是挂载在模型、调度器和管道基类上的混入类其工作流程可以归纳为三个步骤在 Hub 上创建或复用一个仓库将模型、调度器或管道的文件保存到本地临时目录确保后续可以重新加载把包含这些文件的目录上传到 Hub。调用入口是统一的PushToHubMixin.push_to_hub它负责串联建仓 → 保存 → 上传三件事你只需要传入目标repo_id即可。第一步登录 Hub 账号上传前必须先登录 Hugging Face 账号。最简单的方式是在 Notebook 或交互式环境中使用huggingface_hub提供的notebook_login它会引导你输入访问令牌Access Token可在 Hugging Face 设置页面的 Tokens 中创建from huggingface_hub import notebook_login notebook_login()在非 Notebook 的终端环境下也可以改用命令行工具登录hf auth login登录后令牌会保存在本地~/.huggingface目录后续push_to_hub调用会自动复用该凭据无需在每次调用中显式传入token参数。推送模型以 ControlNetModel 为例要推送一个模型实例化模型后调用push_to_hub并指定仓库 id 即可。下面以 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)push_to_hub会自动完成两件事保存模型的config.json配置文件将权重以safetensors格式保存因为safe_serialization默认开启可避免pickle反序列化带来的安全风险。按变体variant推送权重针对模型你还可以指定要推送的权重变体checkpoint variant。例如只上传fp16半精度权重controlnet.push_to_hub(my-controlnet-model, variantfp16)variant参数会传给底层的save_pretrained权重文件将以pytorch_model.fp16.safetensors之类的带后缀文件名存储参见 ModelMixin.save_pretrained 的variant参数说明。加载时通过from_pretrained(..., variantfp16)即可对应读取。需要注意的是调度器Scheduler类并不接受variant参数——在 push_to_hub 源码 中可以看到variant只会加入非 Scheduler 类的保存参数。从 Hub 重新加载模型上传完成后任何人都可以通过仓库 id 重新加载model ControlNetModel.from_pretrained(your-namespace/my-controlnet-model)这里的your-namespace是你的用户名或组织名my-controlnet-model是push_to_hub中指定的仓库名如果只写仓库名默认推到当前登录账号名下。推送调度器以 DDIMScheduler 为例调度器的推送方式与模型一致。例如将一套 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)调度器本质上只有一份配置因此push_to_hub只向仓库写入一个scheduler_config.json文件对应 SchedulerMixin.save_pretrained 内部调用save_config保存配置对象的实现不会像模型那样附带权重文件。重新加载调度器scheduler DDIMScheduler.from_pretrained(your-namepsace/my-controlnet-scheduler)注意加载时仓库 id 中的命名空间namespace要与上传时保持一致否则无法找到目标仓库。推送完整管道以 StableDiffusionPipeline 为例除了单独推送某个组件push_to_hub也支持把包含全部组件的完整管道一次性上传。首先按需求初始化各组件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)将全部组件组装成字典并传给StableDiffusionPipeline然后推送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)推送管道时push_to_hub会把每个组件分别保存到仓库的对应子文件夹中例如unet/、vae/、text_encoder/并额外生成一份管道级model_index.json描述组件布局。加载时它会自动按子文件夹结构重建所有组件pipeline StableDiffusionPipeline.from_pretrained(your-namespace/my-pipeline)私有仓库设置 privateTrue如果你不希望工作成果被公开只需在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的提示要从私有仓库加载模型必须先登录保持已认证状态。源码视角push_to_hub 的内部机制与完整参数从PushToHubMixin.push_to_hub的源码实现可以看到一次调用背后做了这些事情建仓调用create_repo(repo_id, privateprivate, tokentoken, exist_okTrue)仓库已存在时不会报错exist_okTrue返回规范化的repo_id生成模型卡片调用load_or_create_model_card与populate_model_card创建并填充README.md模型卡片保存文件在tempfile.TemporaryDirectory()临时目录中调用save_pretrained模型写入config.json与safetensors权重调度器写入scheduler_config.json管道按子文件夹组织各组件上传通过_upload_folder调用huggingface_hub的upload_folder把整个目录推送到 Hub默认提交信息按对象类型自动生成——模型类为Upload model、调度器类为Upload scheduler其余为Upload {类名}见 hub_utils.py#L508-L514。push_to_hub的完整签名与参数含义如下参数默认值作用repo_id必填目标仓库 id可包含组织名如your-org/my-model也可以是本地目录路径commit_messageNone提交信息默认按对象类型自动生成privateNone是否创建私有仓库None时默认公开除非组织默认私有对已存在的仓库不生效tokenNoneHTTP 鉴权令牌默认读取hf auth login保存在~/.huggingface的令牌create_prFalse是否以 Pull Request 形式提交文件而不是直接 commitsafe_serializationTrue是否将权重转为safetensors格式variantNone权重变体后缀如fp16仅对模型类生效subfolderNone将文件上传到仓库中的指定子目录另一条推送路径save_pretrained(push_to_hubTrue)除了直接调用push_to_hub模型、调度器和管道的save_pretrained方法也都支持push_to_hubTrue的快捷方式保存到本地目录的同时推送到 Hubrepo_id不指定时默认取save_directory的名字。仓库测试 tests/models/test_modeling_common.py#L312-L379 中的TestModelPushToHub即验证了这两条路径# 路径一直接推送 model.push_to_hub(self.repo_id, tokenTOKEN) # 路径二save_pretrained push_to_hubTrue with tempfile.TemporaryDirectory() as tmp_dir: model.save_pretrained(tmp_dir, repo_idsave_repo_id, push_to_hubTrue, tokenTOKEN)该测试在推送后立即用from_pretrained重新加载并逐参数断言torch.equal(p1, p2)验证权重完全一致同时覆盖了组织仓库valid_org/{repo_id}-org的推送场景说明模型、调度器、管道三大类对象均遵循可推送即可重载的对称设计。小结借助PushToHubMixin从本地对象到 Hub 上的可复用资产只需一次方法调用模型与调度器通过push_to_hub(repo_id)直接上传模型自动附带config.json与safetensors权重调度器仅上传scheduler_config.json完整管道则自动按子文件夹组织全部组件并生成model_index.jsonvariant支持权重变体、privateTrue保护私有成果、save_pretrained(push_to_hubTrue)提供等价替代路径。掌握这套流程后你便可以在训练脚本的收尾阶段一键发布成果并通过from_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），仅供参考