跳转至

ControlNet Pipeline 算子节点

为已构建的主干扩散管线包装一层 ControlNet 接口，使其在生成推理阶段能够实时接收多模态空间引导约束。

算子所属分类：ModularDiffusion/Pipeline

核心速查 (TL;DR)

  • 位于管线装配与去噪生成之间：串联在 Pipeline Builder 与 Generate Media Latents 之间——它将底层缓存的基础管线动态重连转换为兼容 ControlNet 的衍生变体；
  • 接收 control_net 配置列表：支持连入一个或多个来自 Configure ControlNet 的配置实体。在底层模型机制支持的前提下（如 Flux Union 等架构），原生支持多个 ControlNet 空间控制网络多重堆叠；
  • 输出端口与原管线平替兼容：输出的 controlnet_pipeline 端口类型依然为标准的 Pipeline Config——可直接无缝替换原基础管线输入至下游所有计算节点。

典型工作流编排拓扑

Pipeline Builder ─────→ [ControlNet Pipeline] ──→ Generate Media Latents ──→ Decode Media Latent
Configure ControlNet ─↗
Configure ControlNet ─↗

节点外观预览

ControlNet Pipeline 算子节点外观

输入端口规范 (Inputs)

端口名称 数据类型 是否必填 详细功能与业务规范说明
pipeline Pipeline Config 是 来自上游基础 Pipeline Builder 节点。输入的基础管线严禁为已经被其他 ControlNet 节点包装过的变体。
control_nets list[control_net] 是 接收一个或多个来自 Configure ControlNet 的控制网定义。所有控制网项的架构体系必须与输入的基础管线完全吻合。

输出端口矩阵 (Outputs)

端口名称 数据类型 详细功能与业务规范说明
controlnet_pipeline Pipeline Config 已成功挂载并重组好 ControlNet 调度的管线凭据对象。
control_parameters control_parameters 透传上游已连接的所有 ControlNet 运行期动态超参（如权重起止步长等）。直接连入 Generate Media Latents 的 controlnet_parameters 输入端口。
logs str 记录 ControlNet 挂载、权重装配与解析出的配置 Hash 指纹的详细日志。

避坑技巧与最佳实践 (Tips & pitfalls)

  • 架构提供方必须严格一致 (Provider match)：每个连接的 ControlNet 的 provider 属性必须与基础主干管线的 provider 严格相等（例如 SDXL 的 ControlNet 严禁与 Flux 管线混用）——节点在执行前会发起严格的静态校验。
  • 管线类兼容性校验：并非所有基础管线原生支持多重 ControlNet 堆叠；该算子在执行装配前会校验底层 Driver，若当前模型组合无法共存会主动弹出报错并明确指出不兼容项。
  • 在单节点内聚合多个 ControlNet，严禁串联两个本节点：若需要同时叠加姿态 (OpenPose) 与边缘 (Canny) 双重控制，请在同一个 ControlNet Pipeline 节点的 control_nets 列表中传入两个配置，绝对不要将一个 ControlNet Pipeline 节点的输出插槽再插给第二个 ControlNet Pipeline 节点（输入端遇到已有 ControlNet 资产时会直接抛错阻断）。
  • 底模复用与权重增量加载机制：节点仅按需加载选定 ControlNet 的空间特征增量网络；上游庞大的基础扩散主干模型直接从显存缓存池中原地复用，绝不重复拉取。

推荐延伸阅读