Diffusers ControlNet 条件图尺寸匹配的处理

我在做 ControlNet 推理时，最容易忽略的不是提示词，而是条件图的实际像素尺寸。边缘图、深度图、姿态图看起来都能正常传入，但只要它们和最终生成画布的宽高不一致，就可能出现三个典型问题：条件结构被非等比拉伸、关键轮廓与输出位置错开，或者多路条件图在组批时直接报尺寸不一致。

后来我把处理方式固定成一条规则：先确定唯一的目标尺寸，再在调用管线之前显式归一所有条件图，同时把相同的 width 和 height 传给 Diffusers 管线。这样既方便定位问题，也不会把尺寸决策悄悄交给不同版本的预处理逻辑。

一、先把目标画布定下来

目标尺寸应该由实际任务决定，而不是由某一张临时条件图决定。例如准备生成 1024×1024 的图片，就先固定：

target_width = 1024
target_height = 1024
target_size = (target_width, target_height)  # Pillow 使用（宽，高）顺序

这里有一个很常见的顺序陷阱：Pillow 的 Image.size 和 resize() 使用 (width, height)，Diffusers 管线参数却通常分别写成 height=...、width=...。我会始终保留两个具名变量，避免在竖图上把宽高写反。

图1：ControlNet 条件图尺寸归一流程，先确定目标宽高，再选择补边或裁切，最后同步给生成画布。

在经典的 Stable Diffusion ControlNet 管线中，条件图预处理会接收 height 和 width。如果调用时显式传入这两个值，预处理器会据此处理图像；如果没有传入，输出尺寸往往会从条件图推导。为了让行为清晰可控，我更建议显式设置，而不是依赖默认推导。

二、不要把“尺寸一致”简单理解成强制拉伸

直接执行 image.resize((1024, 1024)) 虽然能让数组形状一致，却可能破坏 ControlNet 真正依赖的结构。人物会被压扁，圆形会变成椭圆，边缘图中的直线角度也可能改变。条件图不是普通装饰图，它提供的是空间约束，所以比例变形往往比轻微补边更糟。

1. 等比缩放后补边

当完整结构不能丢失时，我优先使用等比缩放加补边。它适合姿态骨架、完整商品轮廓、建筑外观等需要保留全部内容的场景：

from PIL import Image, ImageOps

def fit_control_image(image: Image.Image, size: tuple[int, int]) -> Image.Image:
    # 统一为 RGB，避免灰度图或带透明通道的图像在后续出现模式差异
    image = image.convert("RGB")

    # 保持原始比例并补到精确目标尺寸；黑色通常表示无额外结构信号
    return ImageOps.pad(
        image,
        size,
        method=Image.Resampling.LANCZOS,
        color=(0, 0, 0),
        centering=(0.5, 0.5),
    )

control_image = fit_control_image(raw_control_image, target_size)
assert control_image.size == target_size  # 调用前做一次轻量尺寸断言

补边颜色要结合条件类型理解。对 Canny 这类黑底白线图，黑色补边通常自然；对深度图或语义分割图，补边值可能具有含义，就要使用与预处理器约定一致的背景值，不能机械套用黑色。

2. 等比缩放后居中裁切

当画面中心主体最重要，而且允许舍弃四周内容时，居中裁切更合适：

from PIL import ImageOps

def crop_control_image(image, size):
    # ImageOps.fit 会保持比例，放大后裁掉超出目标比例的边缘区域
    return ImageOps.fit(
        image.convert("RGB"),
        size,
        method=Image.Resampling.LANCZOS,
        centering=(0.5, 0.5),
    )

control_image = crop_control_image(raw_control_image, target_size)

我通常把选择标准写得很简单：结构必须完整就补边，中心主体优先就裁切；只有在原图与目标比例完全一致时，才直接 resize。这样比“所有图片都拉成同一宽高”可靠得多。

三、调用管线时同步传入宽高

条件图处理完成后，调用参数也必须使用同一组目标值：

result = pipe(
    prompt="a clean architectural sketch, soft daylight",
    image=control_image,
    width=target_width,
    height=target_height,
    num_inference_steps=30,
).images[0]

# 生成后只核对尺寸，不把它当作条件结构质量的唯一判断
assert result.size == target_size

这里的关键不是多写两个参数，而是让三个对象共享同一基准：预处理后的条件图、管线的生成宽高、最终输出画布。如果其中任意一个使用了另一套尺寸，问题就会变得难以复现。

实际项目还应选择模型与管线适合的尺寸。经典 VAE 潜空间通常要求宽高能被缩放因子整除，常见做法是至少保证为 8 的倍数；使用 SDXL 或特定 ControlNet 时，还要遵循对应模型卡建议的训练分辨率与长宽比。本文的 1024×1024 只是演示值，不是所有模型的固定答案。

四、多 ControlNet 与批量输入怎么检查

多 ControlNet 最容易出现“每张图单独看都正确，放进列表就报错”的情况。原因通常不是 ControlNet 模型本身，而是某一路条件图仍保留原尺寸，或者批量维度和模型列表没有对应好。

图2：多 ControlNet 输入一致性检查，所有条件图、列表成员和批次样本都围绕同一 target_size 组织。

我会先对每一路条件图使用同一个函数，再组装列表：

raw_controls = [canny_image, depth_image]

# 每一路条件图都归一到同一个目标尺寸，再按 ControlNet 顺序组装
control_images = [
    fit_control_image(image, target_size)
    for image in raw_controls
]

# 列表中任何一张尺寸不同都立即停止，避免错误进入推理阶段
assert all(image.size == target_size for image in control_images)

result = pipe(
    prompt="a modern living room, precise geometry",
    image=control_images,
    width=target_width,
    height=target_height,
).images[0]

如果是批量生成，还要再检查一层：每个样本对应的条件图数量是否相同、每一路的 batch size 是否一致、提示词批次是否与条件图批次对齐。不同 Diffusers 管线对 PIL 列表、嵌套列表和 Tensor 的接受方式可能不同，最好以正在使用的具体管线签名为准，不要把单 ControlNet 的输入形状直接套到多 ControlNet。

五、Tensor 输入为什么也建议显式归一

有些管线允许直接传 NumPy 数组或 PyTorch Tensor。它们可能已经带有批次维度，也可能跳过一部分 PIL 预处理。此时更不能只看 height、width 参数，而要在传入前确认 Tensor 的空间维度。

# 常见图像 Tensor 形状为 [B, C, H, W]，具体仍以当前管线文档为准
batch, channels, image_height, image_width = control_tensor.shape

assert image_width == target_width
assert image_height == target_height
assert channels in (1, 3)  # 根据条件图类型确认通道数

如果需要缩放 Tensor，应使用适合图像的插值方式。连续值深度图可以考虑双线性插值；离散标签图通常需要最近邻插值，避免生成不存在的类别值；二值边缘图在缩放后可能还要重新阈值化。也就是说，尺寸匹配不仅是“改形状”，还要保护条件数据的语义。

六、我的调用前检查清单

• 目标 width 与 height 已明确，并满足所用模型的分辨率要求。
• Pillow 尺寸元组按 (width, height) 编写，没有和管线参数顺序混淆。
• 条件图按内容选择了补边或裁切，没有无条件强制拉伸。
• 条件图的实际 image.size 与目标尺寸完全相同。
• 管线调用显式传入相同的 width 和 height。
• 多 ControlNet 的每一路条件图、模型顺序和批次结构一一对应。
• Tensor 输入已确认空间维度、通道数、数值范围与插值方式。

Diffusers 官方文档入口为 https://huggingface.co/docs/diffusers/。具体版本的参数签名可能变化，尤其是 Union、多 ControlNet 和 Tensor 输入形式，最终应以当前所用管线的官方 API 页面为准。

把尺寸归一放在管线调用之前，最大的收益不是代码更长，而是所有空间约束都有一个可检查的来源。只要目标尺寸、条件图和输出画布保持同一基准，大多数“控制不准”和“批量输入报错”都会更容易定位。