Diffusers 中的 SD3ControlNetModel为 Stable Diffusion 3 添加空间条件控制的完整指南【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers导读本文围绕 Diffusers 仓库中 docs/source/en/api/models/controlnet_sd3.md 文档系统讲解SD3ControlNetModel的架构原理、模型加载、推理调用与多 ControlNet 组合使用。你将掌握如何将 Canny 边缘、深度图、分割图、姿态关键点等空间条件注入 Stable Diffusion 3 的 MMDiT 主干网络实现精细可控的文生图并获得可直接运行的完整代码示例。一、SD3ControlNetModel 是什么SD3ControlNetModel是 ControlNet 架构在 Stable Diffusion 3SD3上的具体实现。ControlNet 这一概念最初由论文Adding Conditional Control to Text-to-Image Diffusion ModelsLvmin Zhang, Anyi Rao, Maneesh Agrawala提出核心思想是在不破坏预训练大模型的前提下通过可学习的条件分支为扩散模型注入额外空间控制信号例如边缘图edge maps、深度图depth maps、分割图segmentation maps以及用于姿态检测的关键点keypoints。论文摘要阐述了其设计动机ControlNet 锁定生产级的大型扩散模型复用其经数十亿图像预训练而得的深层、稳健的编码层作为骨干网络去学习多样化的条件控制。新加入的网络结构通过零卷积zero convolutions即零初始化卷积层与主干相连——这些参数从零开始渐进增长从而保证微调过程中不会引入有害噪声。实验表明 ControlNet 的训练在小型50k与大型1m数据集上都表现稳健支持单条件、多条件、有提示词与无提示词等多种组合。在 Diffusers 中SD3ControlNetModel位于 src/diffusers/models/controlnets/controlnet_sd3.py配套的推理管线为StableDiffusion3ControlNetPipeline见 src/diffusers/pipelines/controlnet_sd3/pipeline_stable_diffusion_3_controlnet.py。二、加载模型从官方权重与从 Transformer 初始化2.1 从预训练权重加载默认方式按官方文档说明SD3ControlNetModel默认应通过ModelMixin.from_pretrained加载。以下代码同时加载了 SD3 基础模型与 Canny 条件的 ControlNetfrom diffusers import StableDiffusion3ControlNetPipeline from diffusers.models import SD3ControlNetModel, SD3MultiControlNetModel controlnet SD3ControlNetModel.from_pretrained(InstantX/SD3-Controlnet-Canny) pipe StableDiffusion3ControlNetPipeline.from_pretrained( stabilityai/stable-diffusion-3-medium-diffusers, controlnetcontrolnet )SD3ControlNetModel继承自ModelMixin、AttentionMixin、ConfigMixin、PeftAdapterMixin与FromOriginalModelMixin因此它不仅支持 Diffusers 原生格式加载也支持从原始非 Diffusers权重格式转换加载——这正是FromOriginalModelMixin提供的from_single_file类方法家族的能力。2.2 从 Transformer 初始化from_transformer源码中提供了一个值得关注的类方法from_transformersrc/diffusers/models/controlnets/controlnet_sd3.py#L253-L270它可以从一个已加载的SD3Transformer2DModel实例构建 ControlNetclassmethod def from_transformer( cls, transformer, num_layers12, num_extra_conditioning_channels1, load_weights_from_transformerTrue ):其工作方式是读取 transformer 的 config改写num_layers与extra_conditioning_channels后from_config构建 ControlNet若load_weights_from_transformerTrue则把 transformer 的pos_embed、time_text_embed、context_embedder、transformer_blocks权重拷贝进 ControlNet并把pos_embed_input做零初始化。这为用现有 SD3 权重初始化 ControlNet 微调提供了快捷路径。三、模型架构零卷积、Patch 嵌入与联合注意力块3.1 网络构成从 src/diffusers/models/controlnets/controlnet_sd3.py#L87-L175 的__init__可以看到SD3ControlNetModel主要由以下模块组成pos_embedPatchEmbed把 4 维潜变量sample_size × sample_size切成 patch 并加入可学习的正弦余弦位置编码pos_embed_typesincos。time_text_embedCombinedTimestepTextProjEmbeddings融合时间步与池化文本投影。context_embedder一个nn.Linear(joint_attention_dim, caption_projection_dim)线性层负责把文本编码器输出的高维嵌入投影到控制网络内部维度。transformer_blocks由JointTransformerBlock联合图文注意力块组成的列表。attention_head_dim会翻倍以容纳文本与图像流的混合use_dual_attention决定某层是否为双流注意力层。controlnet_blocks与transformer_blocks一一对应的nn.Linear(inner_dim, inner_dim)层且每个都用zero_module做零初始化——这是 ControlNet 架构零卷积思想在线性层上的体现保证训练开始时新增分支输出为零不破坏主干。pos_embed_input第二个PatchEmbed输入通道为in_channels extra_conditioning_channels同样经zero_module零初始化用于把条件输入如 Canny 边缘图的潜变量嵌入并与主干特征相加。3.2 前向传播流程forwardsrc/diffusers/models/controlnets/controlnet_sd3.py#L273-L374的核心步骤可以概括为对hidden_states做 patch 嵌入含位置编码由time_text_embed(timestep, pooled_projections)计算时间步与文本投影融合张量temb文本嵌入经context_embedder投影将条件输入嵌入加到主干特征上hidden_states hidden_states self.pos_embed_input(controlnet_cond)逐层经过JointTransformerBlock支持梯度检查点gradient_checkpointing收集每层输出为block_res_samples用controlnet_blocks对每层输出做线性映射得到controlnet_block_res_samples乘以conditioning_scale缩放后返回SD3ControlNetOutput(controlnet_block_samples...)。3.3 返回结果SD3ControlNetOutputSD3ControlNetOutput是一个 dataclasssrc/diffusers/models/controlnets/controlnet_sd3.py#L37-L39dataclass class SD3ControlNetOutput(BaseOutput): controlnet_block_samples: tuple[torch.Tensor]它仅包含一个字段controlnet_block_samples即每个 transformer 块对应的条件残差张量元组。这些样本会被注入到 SD3 Transformer 主干中——在 transformer_sd3.py#L323-L326 中主干的每个非context_pre_only块会将block_controlnet_hidden_states按层数比例对齐后加到隐藏状态上# controlnet residual if block_controlnet_hidden_states is not None and block.context_pre_only is False: interval_control len(self.transformer_blocks) / len(block_controlnet_hidden_states) hidden_states hidden_states block_controlnet_hidden_states[int(index_block / interval_control)]这就是条件控制生效的关键机制ControlNet 分支的输出以残差形式逐层修改主干的去噪过程。四、构造参数详解SD3ControlNetModel.__init__的全部参数及其默认值如下均注册进 config可通过from_pretrained加载参数默认值含义sample_size128潜变量宽/高训练时固定用于学习位置嵌入数量patch_size2把输入数据切成小块patch的尺寸in_channels16输入潜变量通道数num_layers18使用的 transformer 块层数attention_head_dim64每个注意力头的通道数num_attention_heads18多头注意力的头数joint_attention_dim4096联合图文注意力的嵌入维度caption_projection_dim1152文本嵌入caption embedding的投影维度pooled_projection_dim2048池化文本投影的嵌入维度out_channels16输出潜变量通道数若为None则取in_channelspos_embed_max_size96位置嵌入允许的最大潜变量高/宽extra_conditioning_channels0patch 嵌入时额外增加的条件通道数dual_attention_layers()使用双流注意力dual-stream的 transformer 块序号元组qk_normNone注意力层 query/key 的归一化方式如rms_normpos_embed_typesincos位置嵌入类型可选sincos或Noneuse_pos_embedTrue是否使用位置嵌入force_zeros_for_pooled_projectionTrue是否强制池化投影为零由管线读取 config 处理两个值得展开的细节force_zeros_for_pooled_projectionTrue这是为了兼容 InstantX 的 SD3 ControlNet 权重——该系列权重在训练时使用零池化投影。管线在 pipeline_stable_diffusion_3_controlnet.py#L1058-L1141 中据此决定若为True则controlnet_pooled_projections用torch.zeros_like(pooled_prompt_embeds)填充且 VAE 编码控制图时 shift factor 取 0。joint_attention_dim为None时context_embedder置为Nonetransformer_blocks改用SD3SingleTransformerBlock。这是为 SD3.5 8B 官方 ControlNet 预留的路径——这类权重不消费encoder_hidden_states且共享主干的pos_embed见_get_pos_embed_from_transformer与管线__init__中的自动接管逻辑 pipeline_stable_diffusion_3_controlnet.py#L210-L224。五、端到端推理用 StableDiffusion3ControlNetPipeline 生成受控图像管线自带的标准示例见源码中的EXAMPLE_DOC_STRING展示了完整的 fp16 推理流程import torch from diffusers import StableDiffusion3ControlNetPipeline from diffusers.models import SD3ControlNetModel, SD3MultiControlNetModel from diffusers.utils import load_image controlnet SD3ControlNetModel.from_pretrained(InstantX/SD3-Controlnet-Canny, torch_dtypetorch.float16) pipe StableDiffusion3ControlNetPipeline.from_pretrained( stabilityai/stable-diffusion-3-medium-diffusers, controlnetcontrolnet, torch_dtypetorch.float16 ) pipe.to(cuda) control_image load_image( https://huggingface.co/datasets/hf-internal-testing/diffusers-images/resolve/main/sd_controlnet/bird_canny.png ) prompt A bird in space image pipe( prompt, control_imagecontrol_image, height1024, width768, controlnet_conditioning_scale0.7 ).images[0] image.save(sd3.png)5.1 关键推理参数__call__方法pipeline_stable_diffusion_3_controlnet.py#L819-L973中与 ControlNet 强相关的参数control_imageControlNet 的条件输入支持torch.Tensor、PIL.Image.Image、np.ndarray及其列表使用多个 ControlNet 时必须传列表。若不指定height/width输出图尺寸默认跟随条件图尺寸。controlnet_conditioning_scale默认1.0ControlNet 输出在注入主干前乘上的缩放系数。示例中取0.7以弱化条件约束、保留更多文生图自由度。多 ControlNet 时可传列表分别设置。control_guidance_start/control_guidance_end默认0.0/1.0以总步数百分比表示的 ControlNet 生效区间。例如control_guidance_start0.0, control_guidance_end0.5表示仅前 50% 去噪步骤施加条件控制。多 ControlNet 场景可传列表实现差异化调度。controlnet_pooled_projections预计算的池化投影不传时由管线根据force_zeros_for_pooled_projection决定取零或复用pooled_prompt_embeds。guidance_scale默认7.0无分类器引导CFG强度大于 1 时启用引导越强图像越贴合文本提示。num_inference_steps默认28去噪步数也可通过sigmas传入自定义 sigma 调度。height/width默认取default_sample_size * vae_scale_factor即 1024×1024示例中设为 1024×768。注意check_inputs要求二者都能被 8 整除。5.2 管线内部如何消费条件图在去噪循环前管线会把条件图编码进潜空间pipeline_stable_diffusion_3_controlnet.py#L1057-L1102先经VaeImageProcessor.preprocess预处理并按 batch 复制再用vae.encode(...).latent_dist.sample()采样最后按(latent - vae_shift_factor) * scaling_factor缩放。随后在每一步去噪中管线先调用self.controlnet(...)得到control_block_samples再将其作为block_controlnet_hidden_states传入self.transformer(...)完成残差注入见 pipeline_stable_diffusion_3_controlnet.py#L1183-L1203。六、多条件控制SD3MultiControlNetModel当需要同时使用多个条件例如边缘 深度或边缘 姿态时可以使用SD3MultiControlNetModel它是对多个SD3ControlNetModel实例的包装src/diffusers/models/controlnets/controlnet_sd3.py#L377-L452from diffusers import StableDiffusion3ControlNetPipeline from diffusers.models import SD3ControlNetModel, SD3MultiControlNetModel controlnet [ SD3ControlNetModel.from_pretrained(InstantX/SD3-Controlnet-Canny, torch_dtypetorch.float16), SD3ControlNetModel.from_pretrained(InstantX/SD3-Controlnet-Depth, torch_dtypetorch.float16), ] controlnet SD3MultiControlNetModel(controlnet) pipe StableDiffusion3ControlNetPipeline.from_pretrained( stabilityai/stable-diffusion-3-medium-diffusers, controlnetcontrolnet, torch_dtypetorch.float16 )SD3MultiControlNetModel.forward会逐个运行每个子 ControlNet并把所有control_block_samples按元素相加合并后再注入主干每个子网络可配置独立的conditioning_scale与生效区间control_guidance_start/end传列表。此外StableDiffusion3ControlNetPipeline.__init__会自动把传入的list/tuple包装成SD3MultiControlNetModel因此直接传列表也可。七、配套测试与工程化细节仓库中 tests/pipelines/controlnet_sd3/test_controlnet_sd3.py 提供了完整的验证用例可帮助你理解各参数的合法组合与模型装配方式。从测试的get_dummy_components可以看出测试用小模型的关键配置为in_channels8、num_layers4、attention_head_dim8、num_attention_heads4、joint_attention_dim32、pooled_projection_dim64、qk_normrms_norm并支持dual_attention_layers的开关。另有 test_controlnet_inpaint_sd3.py 覆盖 SD3 ControlNet 的修复inpainting场景对应管线为StableDiffusion3ControlNetInpaintingPipeline见 src/diffusers/pipelines/controlnet_sd3/pipeline_stable_diffusion_3_controlnet_inpainting.py适合局部重绘类任务。其他值得留意的工程细节梯度检查点_supports_gradient_checkpointing True训练时可启用enable_gradient_checkpointing以省显存。注意力优化fuse_qkv_projections()/unfuse_qkv_projections()可将 QKV 投影融合以加速推理实验性 APIenable_forward_chunking()可对前馈层做分块以减少峰值内存。LoRA 与 IP-Adapter 兼容模型继承PeftAdapterMixin管线继承SD3LoraLoaderMixin与SD3IPAdapterMixin因此可在 ControlNet 条件控制的基础上叠加 LoRA 微调与图像提示适配器ip_adapter_image参数。CPU offloadenable_sequential_cpu_offload()会按text_encoder → text_encoder_2 → text_encoder_3 → image_encoder → transformer → vae的顺序卸载模块适配大模型推理。结语SD3ControlNetModel把 ControlNet 的零卷积条件分支思想完整地带入了 Stable Diffusion 3 的 MMDiT 架构通过pos_embed_input注入条件潜变量、以逐层controlnet_blocks生成残差样本再经block_controlnet_hidden_states注入主干。配合StableDiffusion3ControlNetPipeline与SD3MultiControlNetModel你可以组合边缘、深度、分割、姿态等任意可编码的空间条件实现从提示词驱动到提示词 结构约束的精细控制。需要深入研读时建议优先查看 controlnet_sd3.py、pipeline_stable_diffusion_3_controlnet.py 及对应测试用例。【免费下载链接】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 中的 SD3ControlNetModel：为 Stable Diffusion 3 添加空间条件控制的完整指南
Diffusers 中的 SD3ControlNetModel为 Stable Diffusion 3 添加空间条件控制的完整指南【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers导读本文围绕 Diffusers 仓库中 docs/source/en/api/models/controlnet_sd3.md 文档系统讲解SD3ControlNetModel的架构原理、模型加载、推理调用与多 ControlNet 组合使用。你将掌握如何将 Canny 边缘、深度图、分割图、姿态关键点等空间条件注入 Stable Diffusion 3 的 MMDiT 主干网络实现精细可控的文生图并获得可直接运行的完整代码示例。一、SD3ControlNetModel 是什么SD3ControlNetModel是 ControlNet 架构在 Stable Diffusion 3SD3上的具体实现。ControlNet 这一概念最初由论文Adding Conditional Control to Text-to-Image Diffusion ModelsLvmin Zhang, Anyi Rao, Maneesh Agrawala提出核心思想是在不破坏预训练大模型的前提下通过可学习的条件分支为扩散模型注入额外空间控制信号例如边缘图edge maps、深度图depth maps、分割图segmentation maps以及用于姿态检测的关键点keypoints。论文摘要阐述了其设计动机ControlNet 锁定生产级的大型扩散模型复用其经数十亿图像预训练而得的深层、稳健的编码层作为骨干网络去学习多样化的条件控制。新加入的网络结构通过零卷积zero convolutions即零初始化卷积层与主干相连——这些参数从零开始渐进增长从而保证微调过程中不会引入有害噪声。实验表明 ControlNet 的训练在小型50k与大型1m数据集上都表现稳健支持单条件、多条件、有提示词与无提示词等多种组合。在 Diffusers 中SD3ControlNetModel位于 src/diffusers/models/controlnets/controlnet_sd3.py配套的推理管线为StableDiffusion3ControlNetPipeline见 src/diffusers/pipelines/controlnet_sd3/pipeline_stable_diffusion_3_controlnet.py。二、加载模型从官方权重与从 Transformer 初始化2.1 从预训练权重加载默认方式按官方文档说明SD3ControlNetModel默认应通过ModelMixin.from_pretrained加载。以下代码同时加载了 SD3 基础模型与 Canny 条件的 ControlNetfrom diffusers import StableDiffusion3ControlNetPipeline from diffusers.models import SD3ControlNetModel, SD3MultiControlNetModel controlnet SD3ControlNetModel.from_pretrained(InstantX/SD3-Controlnet-Canny) pipe StableDiffusion3ControlNetPipeline.from_pretrained( stabilityai/stable-diffusion-3-medium-diffusers, controlnetcontrolnet )SD3ControlNetModel继承自ModelMixin、AttentionMixin、ConfigMixin、PeftAdapterMixin与FromOriginalModelMixin因此它不仅支持 Diffusers 原生格式加载也支持从原始非 Diffusers权重格式转换加载——这正是FromOriginalModelMixin提供的from_single_file类方法家族的能力。2.2 从 Transformer 初始化from_transformer源码中提供了一个值得关注的类方法from_transformersrc/diffusers/models/controlnets/controlnet_sd3.py#L253-L270它可以从一个已加载的SD3Transformer2DModel实例构建 ControlNetclassmethod def from_transformer( cls, transformer, num_layers12, num_extra_conditioning_channels1, load_weights_from_transformerTrue ):其工作方式是读取 transformer 的 config改写num_layers与extra_conditioning_channels后from_config构建 ControlNet若load_weights_from_transformerTrue则把 transformer 的pos_embed、time_text_embed、context_embedder、transformer_blocks权重拷贝进 ControlNet并把pos_embed_input做零初始化。这为用现有 SD3 权重初始化 ControlNet 微调提供了快捷路径。三、模型架构零卷积、Patch 嵌入与联合注意力块3.1 网络构成从 src/diffusers/models/controlnets/controlnet_sd3.py#L87-L175 的__init__可以看到SD3ControlNetModel主要由以下模块组成pos_embedPatchEmbed把 4 维潜变量sample_size × sample_size切成 patch 并加入可学习的正弦余弦位置编码pos_embed_typesincos。time_text_embedCombinedTimestepTextProjEmbeddings融合时间步与池化文本投影。context_embedder一个nn.Linear(joint_attention_dim, caption_projection_dim)线性层负责把文本编码器输出的高维嵌入投影到控制网络内部维度。transformer_blocks由JointTransformerBlock联合图文注意力块组成的列表。attention_head_dim会翻倍以容纳文本与图像流的混合use_dual_attention决定某层是否为双流注意力层。controlnet_blocks与transformer_blocks一一对应的nn.Linear(inner_dim, inner_dim)层且每个都用zero_module做零初始化——这是 ControlNet 架构零卷积思想在线性层上的体现保证训练开始时新增分支输出为零不破坏主干。pos_embed_input第二个PatchEmbed输入通道为in_channels extra_conditioning_channels同样经zero_module零初始化用于把条件输入如 Canny 边缘图的潜变量嵌入并与主干特征相加。3.2 前向传播流程forwardsrc/diffusers/models/controlnets/controlnet_sd3.py#L273-L374的核心步骤可以概括为对hidden_states做 patch 嵌入含位置编码由time_text_embed(timestep, pooled_projections)计算时间步与文本投影融合张量temb文本嵌入经context_embedder投影将条件输入嵌入加到主干特征上hidden_states hidden_states self.pos_embed_input(controlnet_cond)逐层经过JointTransformerBlock支持梯度检查点gradient_checkpointing收集每层输出为block_res_samples用controlnet_blocks对每层输出做线性映射得到controlnet_block_res_samples乘以conditioning_scale缩放后返回SD3ControlNetOutput(controlnet_block_samples...)。3.3 返回结果SD3ControlNetOutputSD3ControlNetOutput是一个 dataclasssrc/diffusers/models/controlnets/controlnet_sd3.py#L37-L39dataclass class SD3ControlNetOutput(BaseOutput): controlnet_block_samples: tuple[torch.Tensor]它仅包含一个字段controlnet_block_samples即每个 transformer 块对应的条件残差张量元组。这些样本会被注入到 SD3 Transformer 主干中——在 transformer_sd3.py#L323-L326 中主干的每个非context_pre_only块会将block_controlnet_hidden_states按层数比例对齐后加到隐藏状态上# controlnet residual if block_controlnet_hidden_states is not None and block.context_pre_only is False: interval_control len(self.transformer_blocks) / len(block_controlnet_hidden_states) hidden_states hidden_states block_controlnet_hidden_states[int(index_block / interval_control)]这就是条件控制生效的关键机制ControlNet 分支的输出以残差形式逐层修改主干的去噪过程。四、构造参数详解SD3ControlNetModel.__init__的全部参数及其默认值如下均注册进 config可通过from_pretrained加载参数默认值含义sample_size128潜变量宽/高训练时固定用于学习位置嵌入数量patch_size2把输入数据切成小块patch的尺寸in_channels16输入潜变量通道数num_layers18使用的 transformer 块层数attention_head_dim64每个注意力头的通道数num_attention_heads18多头注意力的头数joint_attention_dim4096联合图文注意力的嵌入维度caption_projection_dim1152文本嵌入caption embedding的投影维度pooled_projection_dim2048池化文本投影的嵌入维度out_channels16输出潜变量通道数若为None则取in_channelspos_embed_max_size96位置嵌入允许的最大潜变量高/宽extra_conditioning_channels0patch 嵌入时额外增加的条件通道数dual_attention_layers()使用双流注意力dual-stream的 transformer 块序号元组qk_normNone注意力层 query/key 的归一化方式如rms_normpos_embed_typesincos位置嵌入类型可选sincos或Noneuse_pos_embedTrue是否使用位置嵌入force_zeros_for_pooled_projectionTrue是否强制池化投影为零由管线读取 config 处理两个值得展开的细节force_zeros_for_pooled_projectionTrue这是为了兼容 InstantX 的 SD3 ControlNet 权重——该系列权重在训练时使用零池化投影。管线在 pipeline_stable_diffusion_3_controlnet.py#L1058-L1141 中据此决定若为True则controlnet_pooled_projections用torch.zeros_like(pooled_prompt_embeds)填充且 VAE 编码控制图时 shift factor 取 0。joint_attention_dim为None时context_embedder置为Nonetransformer_blocks改用SD3SingleTransformerBlock。这是为 SD3.5 8B 官方 ControlNet 预留的路径——这类权重不消费encoder_hidden_states且共享主干的pos_embed见_get_pos_embed_from_transformer与管线__init__中的自动接管逻辑 pipeline_stable_diffusion_3_controlnet.py#L210-L224。五、端到端推理用 StableDiffusion3ControlNetPipeline 生成受控图像管线自带的标准示例见源码中的EXAMPLE_DOC_STRING展示了完整的 fp16 推理流程import torch from diffusers import StableDiffusion3ControlNetPipeline from diffusers.models import SD3ControlNetModel, SD3MultiControlNetModel from diffusers.utils import load_image controlnet SD3ControlNetModel.from_pretrained(InstantX/SD3-Controlnet-Canny, torch_dtypetorch.float16) pipe StableDiffusion3ControlNetPipeline.from_pretrained( stabilityai/stable-diffusion-3-medium-diffusers, controlnetcontrolnet, torch_dtypetorch.float16 ) pipe.to(cuda) control_image load_image( https://huggingface.co/datasets/hf-internal-testing/diffusers-images/resolve/main/sd_controlnet/bird_canny.png ) prompt A bird in space image pipe( prompt, control_imagecontrol_image, height1024, width768, controlnet_conditioning_scale0.7 ).images[0] image.save(sd3.png)5.1 关键推理参数__call__方法pipeline_stable_diffusion_3_controlnet.py#L819-L973中与 ControlNet 强相关的参数control_imageControlNet 的条件输入支持torch.Tensor、PIL.Image.Image、np.ndarray及其列表使用多个 ControlNet 时必须传列表。若不指定height/width输出图尺寸默认跟随条件图尺寸。controlnet_conditioning_scale默认1.0ControlNet 输出在注入主干前乘上的缩放系数。示例中取0.7以弱化条件约束、保留更多文生图自由度。多 ControlNet 时可传列表分别设置。control_guidance_start/control_guidance_end默认0.0/1.0以总步数百分比表示的 ControlNet 生效区间。例如control_guidance_start0.0, control_guidance_end0.5表示仅前 50% 去噪步骤施加条件控制。多 ControlNet 场景可传列表实现差异化调度。controlnet_pooled_projections预计算的池化投影不传时由管线根据force_zeros_for_pooled_projection决定取零或复用pooled_prompt_embeds。guidance_scale默认7.0无分类器引导CFG强度大于 1 时启用引导越强图像越贴合文本提示。num_inference_steps默认28去噪步数也可通过sigmas传入自定义 sigma 调度。height/width默认取default_sample_size * vae_scale_factor即 1024×1024示例中设为 1024×768。注意check_inputs要求二者都能被 8 整除。5.2 管线内部如何消费条件图在去噪循环前管线会把条件图编码进潜空间pipeline_stable_diffusion_3_controlnet.py#L1057-L1102先经VaeImageProcessor.preprocess预处理并按 batch 复制再用vae.encode(...).latent_dist.sample()采样最后按(latent - vae_shift_factor) * scaling_factor缩放。随后在每一步去噪中管线先调用self.controlnet(...)得到control_block_samples再将其作为block_controlnet_hidden_states传入self.transformer(...)完成残差注入见 pipeline_stable_diffusion_3_controlnet.py#L1183-L1203。六、多条件控制SD3MultiControlNetModel当需要同时使用多个条件例如边缘 深度或边缘 姿态时可以使用SD3MultiControlNetModel它是对多个SD3ControlNetModel实例的包装src/diffusers/models/controlnets/controlnet_sd3.py#L377-L452from diffusers import StableDiffusion3ControlNetPipeline from diffusers.models import SD3ControlNetModel, SD3MultiControlNetModel controlnet [ SD3ControlNetModel.from_pretrained(InstantX/SD3-Controlnet-Canny, torch_dtypetorch.float16), SD3ControlNetModel.from_pretrained(InstantX/SD3-Controlnet-Depth, torch_dtypetorch.float16), ] controlnet SD3MultiControlNetModel(controlnet) pipe StableDiffusion3ControlNetPipeline.from_pretrained( stabilityai/stable-diffusion-3-medium-diffusers, controlnetcontrolnet, torch_dtypetorch.float16 )SD3MultiControlNetModel.forward会逐个运行每个子 ControlNet并把所有control_block_samples按元素相加合并后再注入主干每个子网络可配置独立的conditioning_scale与生效区间control_guidance_start/end传列表。此外StableDiffusion3ControlNetPipeline.__init__会自动把传入的list/tuple包装成SD3MultiControlNetModel因此直接传列表也可。七、配套测试与工程化细节仓库中 tests/pipelines/controlnet_sd3/test_controlnet_sd3.py 提供了完整的验证用例可帮助你理解各参数的合法组合与模型装配方式。从测试的get_dummy_components可以看出测试用小模型的关键配置为in_channels8、num_layers4、attention_head_dim8、num_attention_heads4、joint_attention_dim32、pooled_projection_dim64、qk_normrms_norm并支持dual_attention_layers的开关。另有 test_controlnet_inpaint_sd3.py 覆盖 SD3 ControlNet 的修复inpainting场景对应管线为StableDiffusion3ControlNetInpaintingPipeline见 src/diffusers/pipelines/controlnet_sd3/pipeline_stable_diffusion_3_controlnet_inpainting.py适合局部重绘类任务。其他值得留意的工程细节梯度检查点_supports_gradient_checkpointing True训练时可启用enable_gradient_checkpointing以省显存。注意力优化fuse_qkv_projections()/unfuse_qkv_projections()可将 QKV 投影融合以加速推理实验性 APIenable_forward_chunking()可对前馈层做分块以减少峰值内存。LoRA 与 IP-Adapter 兼容模型继承PeftAdapterMixin管线继承SD3LoraLoaderMixin与SD3IPAdapterMixin因此可在 ControlNet 条件控制的基础上叠加 LoRA 微调与图像提示适配器ip_adapter_image参数。CPU offloadenable_sequential_cpu_offload()会按text_encoder → text_encoder_2 → text_encoder_3 → image_encoder → transformer → vae的顺序卸载模块适配大模型推理。结语SD3ControlNetModel把 ControlNet 的零卷积条件分支思想完整地带入了 Stable Diffusion 3 的 MMDiT 架构通过pos_embed_input注入条件潜变量、以逐层controlnet_blocks生成残差样本再经block_controlnet_hidden_states注入主干。配合StableDiffusion3ControlNetPipeline与SD3MultiControlNetModel你可以组合边缘、深度、分割、姿态等任意可编码的空间条件实现从提示词驱动到提示词 结构约束的精细控制。需要深入研读时建议优先查看 controlnet_sd3.py、pipeline_stable_diffusion_3_controlnet.py 及对应测试用例。【免费下载链接】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），仅供参考