ControlNet是Stable Diffusion生态中最重要的可控生成组件之一，但配置稍有差错就可能出现输出全灰的情况——整张图像蒙上一层均匀的灰度，原本应有的边缘、姿态或深度信息完全失效。造成灰图的常见原因中，预处理器输出值域与模型期望值域不匹配是相当隐蔽的一个。本文围绕0到1与0到255两种值域的差异展开，帮你定位并修复这一问题。
一、为什么值域不匹配会导致全灰
ControlNet模型在训练时，控制图（control map）会被归一化为0到1之间的浮点数，再输入到网络中。以PyTorch为例，模型内部期望接收的张量形状是(B, C, H, W)，数值类型为float32，取值范围在0到1之间。如果你直接把一张PIL图像或者numpy数组传进去，而这张图像的像素值是0到255的uint8类型，数值就会超出模型预期的范围整整255倍。
数值超出范围后，模型的内部卷积层会被异常大的激活值淹没，BN层或GroupNorm的统计量被彻底打乱，最终体现在输出上就是一张均匀的灰色图。这种灰图有一个典型特征：无论你换什么提示词、什么采样器、什么模型，输出永远是一模一样的灰度，说明控制信号已经完全主导并破坏了生成过程。
反过来也存在另一种情况：预处理器输出的是0到1的浮点图，但在保存为图片或送入管道前又被错误地当作0到255处理，比如直接用Image.fromarray处理float数组，会导致图像几乎全黑或者全灰。两种方向的错误本质相同：数据的生产者和消费者对值域的约定不一致。
二、不同预处理器的输出值域差异
不同的预处理器输出格式并不统一，这是问题的根源之一。Canny边缘检测（基于OpenCV）返回的是uint8数组，取值0或255，只有黑白两色；Midas深度估计返回的是归一化后的float数组，取值0到1，保存时需要乘以255再转uint8；OpenPose输出的是直接画在画布上的RGB图像，值域0到255；而MLSD、HED、Scribble等边缘类预处理器大多输出uint8灰度图。
在Stable Diffusion WebUI或ComfyUI中，这些差异通常被内部管道自动处理了，所以多数用户感知不到。但一旦你脱离这些工具，直接调用diffusers库的StableDiffusionControlNetPipeline，或者自己写预处理脚本生成控制图再加载，值域问题就会暴露出来。diffusers管道期望的control_image是PIL Image对象或者0到1的float张量，内部会做归一化，但如果你传入的是裸的0到255 numpy数组，就可能出问题。
排查方法是打印中间数据的类型与统计值。一段实用的检查代码如下：
import numpy as np
def check_value_range(data, name="control_map"):
print(f"--- {name} ---")
print(f"dtype: {data.dtype}")
print(f"shape: {data.shape}")
print(f"min: {data.min()}, max: {data.max()}, mean: {data.mean():.4f}")
if data.dtype == np.uint8:
print("判定: 0-255 整数域")
elif data.max() <= 1.0 and data.min() >= 0.0:
print("判定: 0-1 浮点域")
else:
print("警告: 值域异常，可能溢出！")
# 对预处理器的输出进行检查
check_value_range(canny_result, "canny")
check_value_range(depth_result, "depth")
如果打印结果显示dtype是uint8且max是255，而下游需要0到1的浮点张量，就必须做转换；如果显示float且max远大于1，说明归一化步骤被遗漏了。
三、正确的归一化与反归一化写法
归一化的标准写法是先转为float32，再除以255，切勿直接对uint8做除法后赋值回原数组，那样会因为类型截断导致结果全部变成0：
import numpy as np
import torch
from PIL import Image
# 错误写法：uint8 除法结果被截断为 0
# wrong = control_uint8 / 255 # 若强制转回uint8会全为0
# 正确写法：先转float32再归一化
control_float = control_uint8.astype(np.float32) / 255.0
# 转为模型所需的张量 (1, H, W, C) -> (1, C, H, W)
tensor = torch.from_numpy(control_float).permute(2, 0, 1).unsqueeze(0)
# 反向操作：从模型输出恢复为可显示的图片
output = tensor.squeeze(0).permute(1, 2, 0).cpu().numpy()
image = Image.fromarray((output * 255).clip(0, 255).astype(np.uint8))
image.save("control_map.png")
在diffusers管道中传图时还有几个细节要注意。第一，prepare_control_image方法要求输入图像的尺寸与生成分辨率一致，尺寸不一致时管道默认不自动缩放，需要手动用image.resize((w, h))处理。第二，部分预处理器（如Depth Anything）输出的float数组在保存为PNG时会自动量化，重新读取后值域变回0到255，如果你的流程中有保存再加载的环节，务必确认每次读取时的值域状态。第三，canny这类二值图虽然只有0和255两个值，归一化后就是0和1，这正是模型训练时见到的分布，不要试图再对它做额外的均值标准化。
另外一个常见坑是批次维度和通道维度的混淆。OpenCV读取的图像是HWC格式（高、宽、通道），而PyTorch模型期望CHW格式，忘掉permute会导致张量被错误解读，产生的症状有时也是灰图或形状报错。建议在每次转换后都打印一次shape做确认。
四、系统化排查清单
总结成一个排查流程，遇到ControlNet输出全灰时按顺序检查：
- 打印控制图的dtype、min、max、mean，确认值域落在哪个范围；
- 确认模型输入前的最后一步转换：是否执行了
astype(np.float32) / 255.0； - 检查张量维度顺序是否为
(B, C, H, W)，必要时用permute调整； - 确认控制图分辨率与生成分辨率一致，宽高不要颠倒；
- 如果用了自定义预处理器，查看其文档或源码中返回值是图像还是张量；
- 将控制权重（control strength）临时降到0.5以下测试，如果灰图程度随之变化，说明控制信号本身有问题；
- 用一张已知正确的控制图（如官方示例图）替换你的输入，验证管道本身是否正常。
最后一步的对照实验非常关键：官方示例能正常出图而你的控制图不行，问题百分之百出在你的数据预处理上；如果官方示例也灰图，则要检查模型版本、显存溢出或权重文件损坏等其他方向。值域问题看似细节，却是脱离WebUI走向自定义管线时必经的一道坎，掌握检查数据统计量的习惯后，这类问题通常几分钟就能定位。
ControlNet预处理器值域归一化修改时间：2026-09-15 03:32:33