Diffusers 中的 Flux.1 ControlNet 管线用 Canny / Depth / Union 条件精确控制图像生成【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers导读本文围绕 Flux.1 ControlNet 官方文档系统讲解 Diffusers 中FluxControlNetPipeline的完整用法从 InstantX 与 XLabs 两套预训练 ControlNet 的选型到文本到图像、图像到图像、局部重绘三种调用方式再到多 ControlNet 组合、ControlNet-Union 模式与 LoRA 融合等进阶能力。读完本文你将掌握如何加载 Flux.1-dev 基座模型与 ControlNet 权重、如何调优controlnet_conditioning_scale、control_guidance_start/end等核心参数并理解其底层实现原理对应源码 pipeline_flux_controlnet.py 与模型定义 controlnet_flux.py。一、背景ControlNet 为 Flux.1 带来的条件控制ControlNet 最初由 Lvmin Zhang、Anyi Rao 与 Maneesh Agrawala 在论文Adding Conditional Control to Text-to-Image Diffusion Models中提出。其核心思想是在冻结已训练好的大规模文生图扩散模型如 Flux.1权重的前提下额外训练一套可插拔的条件控制网络用“零卷积”zero-initialized convolution layers从零逐步增长参数从而在不破坏基座模型的前提下注入边缘、深度、分割、人体姿态等空间条件。本文涉及的是 Flux.1 架构上的 ControlNet 实现与 Stable Diffusion 的 ControlNet 在使用 API 上相似但底层架构MMDiT、2×2 打包等完全不同。在 Diffusers 中这条管线即为FluxControlNetPipeline位于 src/diffusers/pipelines/flux/pipeline_flux_controlnet.py。官方文档明确指出该代码由The InstantX Team实现同时XLabs Team贡献的另一套 ControlNet 权重同样受支持。二、选择预训练 ControlNet 权重2.1 InstantX 系列官方文档推荐ControlNet 类型开发者权重仓库Canny边缘The InstantX TeamInstantX/FLUX.1-dev-Controlnet-CannyDepth深度The InstantX TeamShakker-Labs/FLUX.1-dev-ControlNet-DepthUnion多条件统一The InstantX TeamInstantX/FLUX.1-dev-Controlnet-Union2.2 XLabs 系列同样受支持ControlNet 类型开发者权重仓库CannyThe XLabs TeamXLabs-AI/flux-controlnet-canny-diffusersDepthThe XLabs TeamXLabs-AI/flux-controlnet-depth-diffusersHED软边缘The XLabs TeamXLabs-AI/flux-controlnet-hed-diffusers使用提示两套权重的结构存在差异详见下文两种架构分支一节——InstantX 的模型没有input_hint_block需要先把条件图编码进 VAE 潜在空间XLabs 的模型自带input_hint_block直接消费像素级提示图。因此在加载管线时务必保证 ControlNet 权重与基座模型black-forest-labs/FLUX.1-dev配套使用并统一使用torch_dtypetorch.bfloat16以匹配 Flux.1 的训练精度。三、快速上手文本到图像Text-to-Image官方文档同时被写入 pipeline_flux_controlnet.py 的 docstring 作为示例给出的最小可用代码如下import torch from diffusers.utils import load_image from diffusers import FluxControlNetPipeline from diffusers import FluxControlNetModel base_model black-forest-labs/FLUX.1-dev controlnet_model InstantX/FLUX.1-dev-controlnet-canny controlnet FluxControlNetModel.from_pretrained(controlnet_model, torch_dtypetorch.bfloat16) pipe FluxControlNetPipeline.from_pretrained( base_model, controlnetcontrolnet, torch_dtypetorch.bfloat16 ) pipe.to(cuda) control_image load_image(https://huggingface.co/InstantX/SD3-Controlnet-Canny/resolve/main/canny.jpg) prompt A girl in city, 25 years old, cool, futuristic image pipe( prompt, control_imagecontrol_image, control_guidance_start0.2, control_guidance_end0.8, controlnet_conditioning_scale1.0, num_inference_steps28, guidance_scale3.5, ).images[0] image.save(flux.png)关键参数解析依据__call__签名见 pipeline_flux_controlnet.py参数默认值说明control_image必填条件控制图支持PIL.Image.Image、np.ndarray、torch.Tensor及对应 list多 ControlNet 时必须按序传入 listcontrolnet_conditioning_scale1.0ControlNet 输出注入主网络残差前的乘性权重多 ControlNet 时可传 list 分别指定control_guidance_start0.0ControlNet 开始生效的步数百分比0~1control_guidance_end1.0ControlNet 停止生效的步数百分比0~1control_modeNone仅 ControlNet-Union 使用指定条件类型见下文 Union 小节guidance_scale7.0无分类器引导强度越高越贴近 prompt但过高会降低图像质量true_cfg_scale1.0大于 1 且传入negative_prompt时启用真正的无分类器引导Flux.1 默认不适用传统 CFGnum_inference_steps28去噪步数越多质量越高但更慢height/width1024由default_sample_size128与 VAE 缩放因子推导生成尺寸须能被vae_scale_factor * 2即 16整除max_sequence_length512T5 文本编码器最大序列长度上限 512超限会在check_inputs中报错generatorNone随机数生成器传入后可复现结果latentsNone预先生成的噪声潜在向量用于固定构图/种子joint_attention_kwargsNone透传给注意力处理器的 kwargs可用于 LoRA scale 等control_guidance_start/end的范围语义以0.2 ~ 0.8为例表示前 20% 与后 20% 的采样步中 ControlNet 不参与只在中间 60% 的步数施加条件——这在先用 prompt 自由构图、再让条件约束细节的工作流中非常实用。若传入多 ControlNet这两个参数会自动扩展为与 ControlNet 数量等长的 list见 pipeline_flux_controlnet.py 的归一化逻辑。四、底层原理ControlNet 是如何接入 Flux 的4.1 模型定义与两种架构分支FluxControlNetModel定义于 src/diffusers/models/controlnets/controlnet_flux.py。其__init__中有一个关键开关当构造时传入conditioning_embedding_channels时会创建ControlNetConditioningEmbeddingblock_out_channels(16, 16, 16, 16)作为input_hint_block——这是XLabs 架构条件图直接走提示编码块进入网络当该值为None时input_hint_block None——这是InstantX 架构条件图必须先经 VAE 编码并完成 2×2 打包。对应地管线在 pipeline_flux_controlnet.py 中用self.controlnet.input_hint_block is None判断分支# xlab controlnet has a input_hint_block and instantx controlnet does not controlnet_blocks_repeat False if self.controlnet.input_hint_block is None else True if self.controlnet.input_hint_block is None: # vae encode control_image retrieve_latents(self.vae.encode(control_image), generatorgenerator) control_image (control_image - self.vae.config.shift_factor) * self.vae.config.scaling_factor # pack将 latent 切分为 2×2 patch control_image self._pack_latents(...)4.2 Flux 特有的 latent 打包packingFlux 的 MMDiT 架构不直接处理B, C, H, W的潜在张量而是将其拆成 2×2 的 patch 并展平为序列。因此管线中的_pack_latentspipeline_flux_controlnet.py会把(batch, channels, H, W)重排为(batch, (H/2)*(W/2), channels*4)_unpack_latents则在解码前反向还原。这也是为什么height/width必须能被 16 整除VAE 8 倍压缩 × 2×2 打包check_inputs会对不满足的尺寸发出告警。4.3 前向推理流程__call__主循环__call__的执行顺序可归纳为输入校验check_inputs检查prompt与prompt_embeds二选一、negative_prompt配对、尺寸可整除等文本编码encode_prompt分别调用 CLIP得到 pooled 输出与 T5序列最长 512两套编码器得到prompt_embeds、pooled_prompt_embeds与text_ids条件图准备prepare_image完成预处理、resize 到目标尺寸并按num_images_per_prompt重复随后按上节所述进入 VAE 编码 打包分支步进去噪每步用FlowMatchEulerDiscreteScheduler计算时间步将control_image、text_ids、latent_image_ids一并送入transformerControlNet 输出乘以controlnet_conditioning_scale后叠加进主网络解码输出_unpack_latents还原潜在张量VAE 解码为图像默认返回FluxPipelineOutputreturn_dictTrue或 tuple。4.4 多 ControlNetFluxMultiControlNetModel传入 list/tuple 形式的 ControlNet 时__init__会自动包装为FluxMultiControlNetModelcontrolnet_flux.py并在前向中逐条读取controlnet_cond、controlnet_mode与conditioning_scale把多个条件网络的结果累加进主网络controlnet_flux.py。此时control_image、controlnet_conditioning_scale、control_guidance_start/end、control_mode都应传等长 list实现Canny 边缘 Depth 深度之类的组合控制。五、进阶用法一图像到图像Image-to-Image仓库还提供FluxControlNetImg2ImgPipelinepipeline_flux_controlnet_image_to_image.py支持在条件控制的同时以一张源图初始化 latent实现参考原图结构 受 ControlNet 约束的重绘。import torch from diffusers import FluxControlNetImg2ImgPipeline, FluxControlNetModel from diffusers.utils import load_image controlnet FluxControlNetModel.from_pretrained( InstantX/FLUX.1-dev-controlnet-canny, torch_dtypetorch.bfloat16 ) pipe FluxControlNetImg2ImgPipeline.from_pretrained( black-forest-labs/FLUX.1-dev, controlnetcontrolnet, torch_dtypetorch.bfloat16, ) pipe.to(cuda) init_image load_image(https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/img2img-init.jpg) control_image load_image(https://huggingface.co/InstantX/SD3-Controlnet-Canny/resolve/main/canny.jpg) image pipe( a cat wearing sunglasses, imageinit_image, control_imagecontrol_image, strength0.6, # 保留原图结构的程度 controlnet_conditioning_scale0.8, num_inference_steps28, guidance_scale3.5, ).images[0]strength控制重绘程度值越大越偏离原图。该参数与control_image的 VAE 编码逻辑共同作用实际效果建议在 0.4~0.8 之间调试。六、进阶用法二局部重绘InpaintingFluxControlNetInpaintPipelinepipeline_flux_controlnet_inpainting.py把 ControlNet 条件与掩码重绘结合起来掩码区域被重新生成而 ControlNet 约束确保生成结果贴合指定的空间结构如边缘、深度。import torch from diffusers import FluxControlNetInpaintPipeline, FluxControlNetModel from diffusers.utils import load_image controlnet FluxControlNetModel.from_pretrained( InstantX/FLUX.1-dev-controlnet-canny, torch_dtypetorch.bfloat16 ) pipe FluxControlNetInpaintPipeline.from_pretrained( black-forest-labs/FLUX.1-dev, controlnetcontrolnet, torch_dtypetorch.bfloat16, ) pipe.to(cuda) init_image load_image(.../dog.png) mask_image load_image(.../dog_mask.png) control_image load_image(.../canny.png) image pipe( a majestic lion, imageinit_image, mask_imagemask_image, control_imagecontrol_image, strength0.8, guidance_scale3.5, controlnet_conditioning_scale1.0, num_inference_steps28, ).images[0]掩码白色区域为待重绘会通过 VAE 编码进 latent 空间并与控制条件一起在去噪循环中发挥作用两种进阶管线共享本文第一节的所有 ControlNet 参数语义可平滑迁移。七、进阶用法三ControlNet-Union 与多条件组合7.1 Union 模式InstantX/FLUX.1-dev-Controlnet-Union允许单个 ControlNet 处理多种条件类型。通过control_mode指定条件类型管线要求其为int或None多 ControlNet 时传等长 list见 pipeline_flux_controlnet.pyimage pipe( prompt, control_imagecontrol_image, control_mode0, # 具体取值映射见 InstantX 权重仓库说明如 Canny/Depth/… controlnet_conditioning_scale1.0, num_inference_steps28, guidance_scale3.5, ).images[0]control_mode会在进入多 ControlNet 前向时被展开为与条件图等长的张量FluxMultiControlNetModel.forward中逐一对应未指定时以-1兜底见 controlnet_flux.py。7.2 多 ControlNet 组合以 Canny Depth 为例controlnet_canny FluxControlNetModel.from_pretrained( InstantX/FLUX.1-dev-controlnet-canny, torch_dtypetorch.bfloat16 ) controlnet_depth FluxControlNetModel.from_pretrained( Shakker-Labs/FLUX.1-dev-ControlNet-Depth, torch_dtypetorch.bfloat16 ) pipe FluxControlNetPipeline.from_pretrained( black-forest-labs/FLUX.1-dev, controlnet[controlnet_canny, controlnet_depth], # list 自动包装为 FluxMultiControlNetModel torch_dtypetorch.bfloat16, ) pipe.to(cuda) image pipe( prompt, control_image[canny_image, depth_image], controlnet_conditioning_scale[0.8, 0.7], # 逐 ControlNet 权重 control_guidance_start[0.0, 0.1], control_guidance_end[1.0, 0.9], num_inference_steps28, guidance_scale3.5, ).images[0]八、进阶用法四与 LoRA 协同使用FluxControlNetPipeline同时继承FluxLoraLoaderMixin、FromSingleFileMixin与FluxIPAdapterMixinpipeline_flux_controlnet.py因此可通过pipe.load_lora_weights(...)加载风格/概念 LoRA并通过joint_attention_kwargs{scale: 0.8}调节 LoRA 强度源码中encode_prompt会根据lora_scale动态scale_lora_layers/unscale_lora_layers通过pipe.load_ip_adapter(...)与ip_adapter_image参数叠加 IP-Adapter 图像语义引导实现文本 条件图 参考图三重控制通过FromSingleFileMixin从单文件权重加载整条管线。提示_callback_tensor_inputs [latents, prompt_embeds, control_image]这意味着步进回调callback_on_step_end可拿到这三个张量用于中间过程可视化或提前中断pipe.interrupt。九、参考实现与自测仓库为上述能力提供了完整的单测覆盖可作为行为基准torch_dtype建议按 CI 环境使用torch.bfloat16文本到图像 tests/pipelines/controlnet_flux/test_controlnet_flux.py图像到图像 tests/pipelines/controlnet_flux/test_controlnet_flux_img2img.py局部重绘 tests/pipelines/controlnet_flux/test_controlnet_flux_inpaint.py测试中覆盖了control_guidance_start/end边界、多 ControlNet 传参、FluxPipelineOutput结构等关键行为阅读这些用例可帮助你校准自己的调用参数。若需要为 Flux.1 训练自定义 ControlNet仓库还提供了官方训练脚本 examples/flux-control/train_control_flux.py支持--dataset_name/--jsonl_for_train数据源、--image_column/--conditioning_image_column列名配置、--resolution需能被 8 整除以保证 VAE 与 Transformer 尺寸一致、--validation_prompt/--validation_image周期验证等参数以及 LoRA 版 train_control_lora_flux.py。十、常见问题与调参建议生成尺寸异常height/width必须能被 16 整除否则check_inputs会告警并自动调整尺寸pipeline_flux_controlnet.py。条件约束过强/过弱优先调节controlnet_conditioning_scale0.5~1.0 常见区间当希望先自由生成、后受约束时使用control_guidance_start0.2, control_guidance_end0.8这类区间化设置。InstantX 与 XLabs 权重混用两者架构分支不同input_hint_block有无混用可能导致维度不匹配请保持同一团队权重。内存占用过高可启用 CPU offloadpipe.enable_model_cpu_offload()类属性model_cpu_offload_seq text_encoder-text_encoder_2-image_encoder-transformer-vae已按依赖顺序定义或enable_sequential_cpu_offload()。关于调度器管线默认使用FlowMatchEulerDiscreteScheduler可参考 Schedulers 指南 在速度与质量之间权衡若需在多条管线间复用 VAE/文本编码器等组件参见 Reusing models across pipelines。小结FluxControlNetPipeline及其衍生管线Img2Img、Inpaint把 ControlNet 的空间条件控制能力完整地带到了 Flux.1 生态通过 controlnet_flux.py 中的FluxControlNetModel/FluxMultiControlNetModel与管线侧 pipeline_flux_controlnet.py 的打包-去噪-解包流程配合 InstantX / XLabs 的预训练权重即可用 Canny 边缘、深度图、Union 多模式乃至多个 ControlNet 的组合精确约束 Flux.1 的图像生成结果同时保留 LoRA、IP-Adapter 等生态能力的叠加空间。【免费下载链接】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），仅供参考 Diffusers 中的 Flux.1 ControlNet 管线：用 Canny / Depth / Union 条件精确控制图像生成
Diffusers 中的 Flux.1 ControlNet 管线用 Canny / Depth / Union 条件精确控制图像生成【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers导读本文围绕 Flux.1 ControlNet 官方文档系统讲解 Diffusers 中FluxControlNetPipeline的完整用法从 InstantX 与 XLabs 两套预训练 ControlNet 的选型到文本到图像、图像到图像、局部重绘三种调用方式再到多 ControlNet 组合、ControlNet-Union 模式与 LoRA 融合等进阶能力。读完本文你将掌握如何加载 Flux.1-dev 基座模型与 ControlNet 权重、如何调优controlnet_conditioning_scale、control_guidance_start/end等核心参数并理解其底层实现原理对应源码 pipeline_flux_controlnet.py 与模型定义 controlnet_flux.py。一、背景ControlNet 为 Flux.1 带来的条件控制ControlNet 最初由 Lvmin Zhang、Anyi Rao 与 Maneesh Agrawala 在论文Adding Conditional Control to Text-to-Image Diffusion Models中提出。其核心思想是在冻结已训练好的大规模文生图扩散模型如 Flux.1权重的前提下额外训练一套可插拔的条件控制网络用“零卷积”zero-initialized convolution layers从零逐步增长参数从而在不破坏基座模型的前提下注入边缘、深度、分割、人体姿态等空间条件。本文涉及的是 Flux.1 架构上的 ControlNet 实现与 Stable Diffusion 的 ControlNet 在使用 API 上相似但底层架构MMDiT、2×2 打包等完全不同。在 Diffusers 中这条管线即为FluxControlNetPipeline位于 src/diffusers/pipelines/flux/pipeline_flux_controlnet.py。官方文档明确指出该代码由The InstantX Team实现同时XLabs Team贡献的另一套 ControlNet 权重同样受支持。二、选择预训练 ControlNet 权重2.1 InstantX 系列官方文档推荐ControlNet 类型开发者权重仓库Canny边缘The InstantX TeamInstantX/FLUX.1-dev-Controlnet-CannyDepth深度The InstantX TeamShakker-Labs/FLUX.1-dev-ControlNet-DepthUnion多条件统一The InstantX TeamInstantX/FLUX.1-dev-Controlnet-Union2.2 XLabs 系列同样受支持ControlNet 类型开发者权重仓库CannyThe XLabs TeamXLabs-AI/flux-controlnet-canny-diffusersDepthThe XLabs TeamXLabs-AI/flux-controlnet-depth-diffusersHED软边缘The XLabs TeamXLabs-AI/flux-controlnet-hed-diffusers使用提示两套权重的结构存在差异详见下文两种架构分支一节——InstantX 的模型没有input_hint_block需要先把条件图编码进 VAE 潜在空间XLabs 的模型自带input_hint_block直接消费像素级提示图。因此在加载管线时务必保证 ControlNet 权重与基座模型black-forest-labs/FLUX.1-dev配套使用并统一使用torch_dtypetorch.bfloat16以匹配 Flux.1 的训练精度。三、快速上手文本到图像Text-to-Image官方文档同时被写入 pipeline_flux_controlnet.py 的 docstring 作为示例给出的最小可用代码如下import torch from diffusers.utils import load_image from diffusers import FluxControlNetPipeline from diffusers import FluxControlNetModel base_model black-forest-labs/FLUX.1-dev controlnet_model InstantX/FLUX.1-dev-controlnet-canny controlnet FluxControlNetModel.from_pretrained(controlnet_model, torch_dtypetorch.bfloat16) pipe FluxControlNetPipeline.from_pretrained( base_model, controlnetcontrolnet, torch_dtypetorch.bfloat16 ) pipe.to(cuda) control_image load_image(https://huggingface.co/InstantX/SD3-Controlnet-Canny/resolve/main/canny.jpg) prompt A girl in city, 25 years old, cool, futuristic image pipe( prompt, control_imagecontrol_image, control_guidance_start0.2, control_guidance_end0.8, controlnet_conditioning_scale1.0, num_inference_steps28, guidance_scale3.5, ).images[0] image.save(flux.png)关键参数解析依据__call__签名见 pipeline_flux_controlnet.py参数默认值说明control_image必填条件控制图支持PIL.Image.Image、np.ndarray、torch.Tensor及对应 list多 ControlNet 时必须按序传入 listcontrolnet_conditioning_scale1.0ControlNet 输出注入主网络残差前的乘性权重多 ControlNet 时可传 list 分别指定control_guidance_start0.0ControlNet 开始生效的步数百分比0~1control_guidance_end1.0ControlNet 停止生效的步数百分比0~1control_modeNone仅 ControlNet-Union 使用指定条件类型见下文 Union 小节guidance_scale7.0无分类器引导强度越高越贴近 prompt但过高会降低图像质量true_cfg_scale1.0大于 1 且传入negative_prompt时启用真正的无分类器引导Flux.1 默认不适用传统 CFGnum_inference_steps28去噪步数越多质量越高但更慢height/width1024由default_sample_size128与 VAE 缩放因子推导生成尺寸须能被vae_scale_factor * 2即 16整除max_sequence_length512T5 文本编码器最大序列长度上限 512超限会在check_inputs中报错generatorNone随机数生成器传入后可复现结果latentsNone预先生成的噪声潜在向量用于固定构图/种子joint_attention_kwargsNone透传给注意力处理器的 kwargs可用于 LoRA scale 等control_guidance_start/end的范围语义以0.2 ~ 0.8为例表示前 20% 与后 20% 的采样步中 ControlNet 不参与只在中间 60% 的步数施加条件——这在先用 prompt 自由构图、再让条件约束细节的工作流中非常实用。若传入多 ControlNet这两个参数会自动扩展为与 ControlNet 数量等长的 list见 pipeline_flux_controlnet.py 的归一化逻辑。四、底层原理ControlNet 是如何接入 Flux 的4.1 模型定义与两种架构分支FluxControlNetModel定义于 src/diffusers/models/controlnets/controlnet_flux.py。其__init__中有一个关键开关当构造时传入conditioning_embedding_channels时会创建ControlNetConditioningEmbeddingblock_out_channels(16, 16, 16, 16)作为input_hint_block——这是XLabs 架构条件图直接走提示编码块进入网络当该值为None时input_hint_block None——这是InstantX 架构条件图必须先经 VAE 编码并完成 2×2 打包。对应地管线在 pipeline_flux_controlnet.py 中用self.controlnet.input_hint_block is None判断分支# xlab controlnet has a input_hint_block and instantx controlnet does not controlnet_blocks_repeat False if self.controlnet.input_hint_block is None else True if self.controlnet.input_hint_block is None: # vae encode control_image retrieve_latents(self.vae.encode(control_image), generatorgenerator) control_image (control_image - self.vae.config.shift_factor) * self.vae.config.scaling_factor # pack将 latent 切分为 2×2 patch control_image self._pack_latents(...)4.2 Flux 特有的 latent 打包packingFlux 的 MMDiT 架构不直接处理B, C, H, W的潜在张量而是将其拆成 2×2 的 patch 并展平为序列。因此管线中的_pack_latentspipeline_flux_controlnet.py会把(batch, channels, H, W)重排为(batch, (H/2)*(W/2), channels*4)_unpack_latents则在解码前反向还原。这也是为什么height/width必须能被 16 整除VAE 8 倍压缩 × 2×2 打包check_inputs会对不满足的尺寸发出告警。4.3 前向推理流程__call__主循环__call__的执行顺序可归纳为输入校验check_inputs检查prompt与prompt_embeds二选一、negative_prompt配对、尺寸可整除等文本编码encode_prompt分别调用 CLIP得到 pooled 输出与 T5序列最长 512两套编码器得到prompt_embeds、pooled_prompt_embeds与text_ids条件图准备prepare_image完成预处理、resize 到目标尺寸并按num_images_per_prompt重复随后按上节所述进入 VAE 编码 打包分支步进去噪每步用FlowMatchEulerDiscreteScheduler计算时间步将control_image、text_ids、latent_image_ids一并送入transformerControlNet 输出乘以controlnet_conditioning_scale后叠加进主网络解码输出_unpack_latents还原潜在张量VAE 解码为图像默认返回FluxPipelineOutputreturn_dictTrue或 tuple。4.4 多 ControlNetFluxMultiControlNetModel传入 list/tuple 形式的 ControlNet 时__init__会自动包装为FluxMultiControlNetModelcontrolnet_flux.py并在前向中逐条读取controlnet_cond、controlnet_mode与conditioning_scale把多个条件网络的结果累加进主网络controlnet_flux.py。此时control_image、controlnet_conditioning_scale、control_guidance_start/end、control_mode都应传等长 list实现Canny 边缘 Depth 深度之类的组合控制。五、进阶用法一图像到图像Image-to-Image仓库还提供FluxControlNetImg2ImgPipelinepipeline_flux_controlnet_image_to_image.py支持在条件控制的同时以一张源图初始化 latent实现参考原图结构 受 ControlNet 约束的重绘。import torch from diffusers import FluxControlNetImg2ImgPipeline, FluxControlNetModel from diffusers.utils import load_image controlnet FluxControlNetModel.from_pretrained( InstantX/FLUX.1-dev-controlnet-canny, torch_dtypetorch.bfloat16 ) pipe FluxControlNetImg2ImgPipeline.from_pretrained( black-forest-labs/FLUX.1-dev, controlnetcontrolnet, torch_dtypetorch.bfloat16, ) pipe.to(cuda) init_image load_image(https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/img2img-init.jpg) control_image load_image(https://huggingface.co/InstantX/SD3-Controlnet-Canny/resolve/main/canny.jpg) image pipe( a cat wearing sunglasses, imageinit_image, control_imagecontrol_image, strength0.6, # 保留原图结构的程度 controlnet_conditioning_scale0.8, num_inference_steps28, guidance_scale3.5, ).images[0]strength控制重绘程度值越大越偏离原图。该参数与control_image的 VAE 编码逻辑共同作用实际效果建议在 0.4~0.8 之间调试。六、进阶用法二局部重绘InpaintingFluxControlNetInpaintPipelinepipeline_flux_controlnet_inpainting.py把 ControlNet 条件与掩码重绘结合起来掩码区域被重新生成而 ControlNet 约束确保生成结果贴合指定的空间结构如边缘、深度。import torch from diffusers import FluxControlNetInpaintPipeline, FluxControlNetModel from diffusers.utils import load_image controlnet FluxControlNetModel.from_pretrained( InstantX/FLUX.1-dev-controlnet-canny, torch_dtypetorch.bfloat16 ) pipe FluxControlNetInpaintPipeline.from_pretrained( black-forest-labs/FLUX.1-dev, controlnetcontrolnet, torch_dtypetorch.bfloat16, ) pipe.to(cuda) init_image load_image(.../dog.png) mask_image load_image(.../dog_mask.png) control_image load_image(.../canny.png) image pipe( a majestic lion, imageinit_image, mask_imagemask_image, control_imagecontrol_image, strength0.8, guidance_scale3.5, controlnet_conditioning_scale1.0, num_inference_steps28, ).images[0]掩码白色区域为待重绘会通过 VAE 编码进 latent 空间并与控制条件一起在去噪循环中发挥作用两种进阶管线共享本文第一节的所有 ControlNet 参数语义可平滑迁移。七、进阶用法三ControlNet-Union 与多条件组合7.1 Union 模式InstantX/FLUX.1-dev-Controlnet-Union允许单个 ControlNet 处理多种条件类型。通过control_mode指定条件类型管线要求其为int或None多 ControlNet 时传等长 list见 pipeline_flux_controlnet.pyimage pipe( prompt, control_imagecontrol_image, control_mode0, # 具体取值映射见 InstantX 权重仓库说明如 Canny/Depth/… controlnet_conditioning_scale1.0, num_inference_steps28, guidance_scale3.5, ).images[0]control_mode会在进入多 ControlNet 前向时被展开为与条件图等长的张量FluxMultiControlNetModel.forward中逐一对应未指定时以-1兜底见 controlnet_flux.py。7.2 多 ControlNet 组合以 Canny Depth 为例controlnet_canny FluxControlNetModel.from_pretrained( InstantX/FLUX.1-dev-controlnet-canny, torch_dtypetorch.bfloat16 ) controlnet_depth FluxControlNetModel.from_pretrained( Shakker-Labs/FLUX.1-dev-ControlNet-Depth, torch_dtypetorch.bfloat16 ) pipe FluxControlNetPipeline.from_pretrained( black-forest-labs/FLUX.1-dev, controlnet[controlnet_canny, controlnet_depth], # list 自动包装为 FluxMultiControlNetModel torch_dtypetorch.bfloat16, ) pipe.to(cuda) image pipe( prompt, control_image[canny_image, depth_image], controlnet_conditioning_scale[0.8, 0.7], # 逐 ControlNet 权重 control_guidance_start[0.0, 0.1], control_guidance_end[1.0, 0.9], num_inference_steps28, guidance_scale3.5, ).images[0]八、进阶用法四与 LoRA 协同使用FluxControlNetPipeline同时继承FluxLoraLoaderMixin、FromSingleFileMixin与FluxIPAdapterMixinpipeline_flux_controlnet.py因此可通过pipe.load_lora_weights(...)加载风格/概念 LoRA并通过joint_attention_kwargs{scale: 0.8}调节 LoRA 强度源码中encode_prompt会根据lora_scale动态scale_lora_layers/unscale_lora_layers通过pipe.load_ip_adapter(...)与ip_adapter_image参数叠加 IP-Adapter 图像语义引导实现文本 条件图 参考图三重控制通过FromSingleFileMixin从单文件权重加载整条管线。提示_callback_tensor_inputs [latents, prompt_embeds, control_image]这意味着步进回调callback_on_step_end可拿到这三个张量用于中间过程可视化或提前中断pipe.interrupt。九、参考实现与自测仓库为上述能力提供了完整的单测覆盖可作为行为基准torch_dtype建议按 CI 环境使用torch.bfloat16文本到图像 tests/pipelines/controlnet_flux/test_controlnet_flux.py图像到图像 tests/pipelines/controlnet_flux/test_controlnet_flux_img2img.py局部重绘 tests/pipelines/controlnet_flux/test_controlnet_flux_inpaint.py测试中覆盖了control_guidance_start/end边界、多 ControlNet 传参、FluxPipelineOutput结构等关键行为阅读这些用例可帮助你校准自己的调用参数。若需要为 Flux.1 训练自定义 ControlNet仓库还提供了官方训练脚本 examples/flux-control/train_control_flux.py支持--dataset_name/--jsonl_for_train数据源、--image_column/--conditioning_image_column列名配置、--resolution需能被 8 整除以保证 VAE 与 Transformer 尺寸一致、--validation_prompt/--validation_image周期验证等参数以及 LoRA 版 train_control_lora_flux.py。十、常见问题与调参建议生成尺寸异常height/width必须能被 16 整除否则check_inputs会告警并自动调整尺寸pipeline_flux_controlnet.py。条件约束过强/过弱优先调节controlnet_conditioning_scale0.5~1.0 常见区间当希望先自由生成、后受约束时使用control_guidance_start0.2, control_guidance_end0.8这类区间化设置。InstantX 与 XLabs 权重混用两者架构分支不同input_hint_block有无混用可能导致维度不匹配请保持同一团队权重。内存占用过高可启用 CPU offloadpipe.enable_model_cpu_offload()类属性model_cpu_offload_seq text_encoder-text_encoder_2-image_encoder-transformer-vae已按依赖顺序定义或enable_sequential_cpu_offload()。关于调度器管线默认使用FlowMatchEulerDiscreteScheduler可参考 Schedulers 指南 在速度与质量之间权衡若需在多条管线间复用 VAE/文本编码器等组件参见 Reusing models across pipelines。小结FluxControlNetPipeline及其衍生管线Img2Img、Inpaint把 ControlNet 的空间条件控制能力完整地带到了 Flux.1 生态通过 controlnet_flux.py 中的FluxControlNetModel/FluxMultiControlNetModel与管线侧 pipeline_flux_controlnet.py 的打包-去噪-解包流程配合 InstantX / XLabs 的预训练权重即可用 Canny 边缘、深度图、Union 多模式乃至多个 ControlNet 的组合精确约束 Flux.1 的图像生成结果同时保留 LoRA、IP-Adapter 等生态能力的叠加空间。【免费下载链接】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），仅供参考