Diffusers 自定义管道custom_pipeline加载完全指南从 Hub 与 GitHub 加载社区管道与自定义组件【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers本指南围绕 Diffusers 中的社区管道Community Pipelines机制展开讲解如何通过DiffusionPipeline.from_pretrained的custom_pipeline参数从 Hugging Face Hub、官方社区仓库或本地目录加载非官方管道实现并进一步介绍custom_revision版本锁定、from_pipe组件复用、社区组件组合以及trust_remote_code安全加载。读完本文你将掌握在本项目 Diffusers中安全加载、复用与分发自定义管道的完整实战方案。什么是社区管道社区管道Community Pipelines是指与原论文实现形式不同的DiffusionPipeline类。它们通常在原管道基础上提供附加功能或扩展现有实现。例如Speech to Image将语音输入转换为图像生成条件Composable Stable Diffusion将多个提示词拆分为独立区域分别生成再组合实现合成式构图CLIP Guided Stable Diffusion利用 CLIP 模型引导扩散采样过程增强生成图像与提示词的语义对齐。官方维护的社区管道脚本全部集中在仓库的 examples/community 目录下该目录下的 README_community_scripts.md 对每个脚本的用途、输入输出和参数做了逐一说明例如stable_diffusion_mega.py中定义的StableDiffusionMegaPipeline就是通过继承DiffusionPipeline与StableDiffusionMixin组合多个基础管道能力的典型社区实现。社区管道有两种存放位置二者在使用方式上一致但在审核流程与可见性上有明显差异维度GitHub 官方仓库Hugging Face Hub使用方式相同相同审核流程需在 GitHub 上提交 Pull Request经 Diffusers 团队评审后合入流程较慢直接上传到 Hub 仓库无需评审最快可见性收录于官方 Diffusers 仓库与官方文档曝光度高展示在你的 Hub 个人主页依赖自身推广custom_pipeline 参数加载社区管道的统一入口无论管道托管在 Hub 还是 GitHub加载方式都是向~DiffusionPipeline.from_pretrained传入custom_pipeline参数。从源码看该参数在 pipeline_utils.py 中定义了三种合法取值Hub 上的仓库 ID例如hf-internal-testing/diffusers-dummy-pipeline该仓库必须包含一个定义管道的pipeline.py文件GitHub 官方社区管道的文件名例如clip_guided_stable_diffusion注意是文件名而非带.py的脚本名不能写成clip_guided_stable_diffusion.py社区管道始终从 GitHub 当前main分支加载本地目录路径例如./my_pipeline_directory/该目录同样必须包含定义管道的pipeline.py文件。场景一从 Hub 加载社区管道加载 Hub 上的社区管道时需要同时传入管道代码仓库 ID与模型权重/组件仓库 ID。下面的示例从hf-internal-testing/diffusers-dummy-pipeline加载管道代码并从google/ddpm-cifar10-32加载管道权重与组件from diffusers import DiffusionPipeline pipeline DiffusionPipeline.from_pretrained( google/ddpm-cifar10-32, custom_pipelinehf-internal-testing/diffusers-dummy-pipeline )[!WARNING] 从 Hugging Face Hub 加载社区管道等同于信任该代码是安全的。代码会在本地被自动下载并执行因此在运行之前务必到线上检查该代码仓库的可信度与内容场景二从 GitHub 加载官方社区管道并覆盖组件加载 GitHub 上的官方社区管道方式类似但有一个额外能力在加载官方仓库权重的同时可以直接指定管道内部的组件。下面的示例加载社区版 CLIP Guided Stable Diffusion 管道并直接为其注入自定义的clip_model与feature_extractor组件from diffusers import DiffusionPipeline from transformers import CLIPImageProcessor, CLIPModel clip_model_id laion/CLIP-ViT-B-32-laion2B-s34B-b79K feature_extractor CLIPImageProcessor.from_pretrained(clip_model_id) clip_model CLIPModel.from_pretrained(clip_model_id) pipeline DiffusionPipeline.from_pretrained( stable-diffusion-v1-5/stable-diffusion-v1-5, custom_pipelineclip_guided_stable_diffusion, clip_modelclip_model, feature_extractorfeature_extractor, )这种组件覆盖机制在源码中有明确支撑from_pretrained的kwargs用于覆盖可加载/可保存的变量即特定管道类的组件覆盖后的组件会直接传给管道类的__init__方法见 pipeline_utils.py。也就是说社区管道所需的任何额外组件都可以像普通参数一样通过关键字传入无需修改模型仓库。场景三用 custom_revision 锁定管道代码版本社区管道默认从 Diffusers 最新稳定版加载。如果希望从特定版本例如v0.30.0或main加载可以在from_pretrained中追加custom_revision参数其用法与revision类似支持分支名、标签名或提交哈希import torch from diffusers import DiffusionPipeline pipeline DiffusionPipeline.from_pretrained( stabilityai/stable-diffusion-3-medium-diffusers, custom_pipelinepipeline_stable_diffusion_3_instruct_pix2pix, custom_revisionmain, dtypetorch.float16, device_mapcuda, # 或 mps、xpu、cpu )源码中custom_revision的默认语义为加载自定义管道时使用的具体版本默认对应 Diffusers 最新稳定版见 pipeline_utils.py并在 pipeline_utils.py 处传入_get_custom_pipeline_class参与管道类解析。场景四从本地目录加载管道代码将custom_pipeline指向一个本地目录即可离线加载。目录中必须存在包含管道类的pipeline.py文件import torch from diffusers import DiffusionPipeline pipeline DiffusionPipeline.from_pretrained( stabilityai/stable-diffusion-3-medium-diffusers, custom_pipelinepath/to/pipeline_directory, dtypetorch.float16, device_mapcuda, # 或 mps、xpu、cpu )from_pipe零额外显存复用社区管道custom_pipeline参数同样被~DiffusionPipeline.from_pipe支持这对于在多个管道间复用模型组件参见 loading.md 中关于管道复用模型的章节非常实用from_pipe会让多个管道共享组件内存占用只相当于其中最大的那个管道。import torch from diffusers import DiffusionPipeline pipeline_sd DiffusionPipeline.from_pretrained( emilianJR/CyberRealistic_V3, dtypetorch.float16, device_mapcuda # 或 mps、xpu、cpu ) pipeline_lpw DiffusionPipeline.from_pipe( pipeline_sd, custom_pipelinelpw_stable_diffusion, device_mapcuda )from_pipe对社区管道尤其有价值——因为绝大多数社区管道没有自己的预训练权重它们一般是在某个现有管道之上叠加一项功能例如 lpw_stable_diffusion.py 的 Long Prompt Weighting让标准 Stable Diffusion 支持超长提示词与权重语法。社区组件用自定义模块组装完整管道社区组件Community Components允许用户使用 Diffusers 尚未内置支持的自定义 Transformer、UNet、VAE 与 Scheduler 来搭建管道这些组件以 Python 模块的形式提供。下面以 show-1文本生成视频管道为例展示完整的组装流程。第 1 步加载基础组件。文本编码器与分词器通常直接来自 Transformers 库调度器与图像处理器来自 Diffusersfrom transformers import T5Tokenizer, T5EncoderModel, CLIPImageProcessor from diffusers import DPMSolverMultistepScheduler pipeline_id showlab/show-1-base tokenizer T5Tokenizer.from_pretrained(pipeline_id, subfoldertokenizer) text_encoder T5EncoderModel.from_pretrained(pipeline_id, subfoldertext_encoder) scheduler DPMSolverMultistepScheduler.from_pretrained(pipeline_id, subfolderscheduler) feature_extractor CLIPImageProcessor.from_pretrained(pipeline_id, subfolderfeature_extractor)第 2 步加载自定义 UNet。由于UNet3DConditionModel在 Diffusers 中已存在show-1 的自定义实现被重命名为ShowOneUNet3DConditionModel并放在独立的showone_unet_3d_condition.py模块中该类的所有依赖组件也必须放在同一文件内from showone_unet_3d_condition import ShowOneUNet3DConditionModel unet ShowOneUNet3DConditionModel.from_pretrained(pipeline_id, subfolderunet)[!WARNING] 在第 2、3 步中自定义 UNet 与管道脚本的实现格式必须与原始示例文件保持一致否则无法正常工作。第 3 步加载自定义管道代码。pipeline_t2v_base_pixel.py中定义了用于文本生成视频的自定义TextToVideoIFPipeline类其所需的全部代码都应放置在该文件中然后用上一步的ShowOneUNet3DConditionModel初始化import torch from pipeline_t2v_base_pixel import TextToVideoIFPipeline pipeline TextToVideoIFPipeline( unetunet, text_encodertext_encoder, tokenizertokenizer, schedulerscheduler, feature_extractorfeature_extractor, device_mapcuda, # 或 mps、xpu、cpu dtypetorch.float16, )第 4 步推送到 Hub 分享。使用push_to_hub将管道上传pipeline.push_to_hub(custom-t2v-pipeline)推送成功后还需要完成三处结构调整才能让DiffusionPipeline.from_pretrained通过trust_remote_code自动识别将model_index.json中的_class_name属性改为pipeline_t2v_base_pixel与TextToVideoIFPipeline将showone_unet_3d_condition.py上传到unet子目录将pipeline_t2v_base_pixel.py上传到管道仓库根目录。之后其他用户只需在初始化时追加trust_remote_codeTrue即可让 Diffusers 在幕后自动处理自定义代码的拉取与执行import torch from diffusers import DiffusionPipeline pipeline DiffusionPipeline.from_pretrained( change-username/change-id, trust_remote_codeTrue, dtypetorch.float16 )从源码看trust_remote_code在 pipeline_utils.py 处从kwargs中弹出随后贯穿整个加载流程第 885、1068 行并最终参与自定义管道类的解析第 2133 行是远程自定义代码能否被执行的关键开关。安全注意事项与最佳实践社区管道机制的本质是从远程拉取并执行任意 Python 代码因此安全边界至关重要默认不信任Hugging Face Hub 虽然会对上传文件进行恶意软件扫描但用户在加载 Hub 管道前仍应人工检查管道代码确认其行为安全见 pipeline_utils.py 对custom_pipeline的说明。锁定 commit使用trust_remote_codeTrue时强烈建议同时向revision参数传入具体的提交哈希确保代码不会被后续更新替换为新的恶意内容除非你完全信任模型所有者。优先官方渠道如果功能目标与官方社区管道重合优先从 examples/community 中挑选经 Diffusers 团队评审过的实现降低供应链风险。底层加载流程从参数到管道类当传入custom_pipeline后加载流程在 pipeline_utils.py 中分两步完成解析先由_resolve_custom_pipeline_and_cls第 922 行根据缓存目录中的model_index.json配置与custom_pipeline取值解析出管道代码来源Hub 仓库、GitHub 文件名或本地目录与自定义类名再由_get_custom_pipeline_class第 2133 行结合custom_revision与trust_remote_code完成管道类的实际加载。从源码结构可以推断无论采用哪种来源最终都会要求自定义代码模块暴露一个兼容DiffusionPipeline子类的类且 Hub/本地来源必须遵守仓库或目录内存在pipeline.py的约定。此外加载时若检测到 Hub 仓库文件中存在{custom_pipeline}.py也会将其纳入下载白名单见 pipeline_utils.py保证管道脚本随权重一起就位。延伸阅读官方社区管道脚本全集与说明examples/community/README_community_scripts.md社区管道加载的英文权威文档custom_pipeline_overview.md编写自有管道不依赖社区机制纯本地构建参考write_own_pipeline.md管道组件复用与from_pipe详细说明loading.md社区管道贡献与评审流程contribution.md【免费下载链接】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），仅供参考