controlnet微调需满足五点：①diffusers≥0.25.0；②conditioning_image与pixel_values预处理严格对齐；③unet和controlnet须同时启用gradient_checkpointing；④lora target_modules应覆盖conv_in及下采样路径关键卷积层；⑤condition图质量与prompt语义必须一致。
ControlNet 微调前必须确认 diffusers 版本是否支持训练接口
新版 diffusers（≥0.25.0）才把 ControlNetModel 的训练逻辑和 UNet2DConditionModel 对齐，旧版本调用 model.train() 后反向传播会卡在 torch.nn.functional.interpolate 的梯度计算上，报错信息通常是 RuntimeError: derivative for aten::upsample_bilinear2d_backward is not implemented。
- 运行
pip show diffusers确认版本，低于 0.25.0 必须升级：pip install --upgrade diffusers - 不要用 Hugging Face 官方 example scripts 里带
train_controlnet.py的旧分支（比如v0.24.0tag），直接拉main分支或指定0.27.2+ - 即使版本够新，也要检查你加载的
ControlNetModel是否启用了use_linear_projection=False（SD 1.5 默认是False），否则AttnProcessor2_0在训练时可能跳过某些权重更新
训练时 conditioning_image 和 pixel_values 的预处理必须严格对齐
ControlNet 不是“额外加个图”，而是把条件图和原图在像素级做通道拼接再送进 UNet。如果两者 resize 方式不一致（比如一个双线性、一个最近邻），模型根本学不到空间对应关系，loss 降不下去，生成结果完全错位。
-
conditioning_image（如 Canny 图、depth 图）必须和pixel_values（原图）使用**同一套transforms.Resize+transforms.CenterCrop流程**，且尺寸完全相同（如都 resize 到 512×512 再 crop） - 别用 OpenCV/PIL 单独读 condition 图再 resize —— 容易和
image_processor的归一化范围（[0,1]还是[-1,1]）不一致；统一走dataset里的transform函数 - 如果是边缘/深度图，确保输入是单通道但被 expand 到 3 通道（
img = img.expand(3, -1, -1)），否则和 RGB 图 concat 时维度报错：torch.cat([cond_img, rgb_img], dim=0)要求 channel 数一致
gradient_checkpointing 开关不当会导致 RuntimeError: Trying to backward through the graph a second time
ControlNet 训练显存压力大，很多人直接开 unet.enable_gradient_checkpointing()，但忘了 controlnet 本身也要单独启用——而且顺序不能错。如果只开 UNet 的 checkpoint，ControlNet 的 forward 输出会被缓存两次，反向时重复释放导致图破坏。
- 必须同时启用：
unet.enable_gradient_checkpointing()和controlnet.enable_gradient_checkpointing() - 启用位置要在
model.train()之后、optimizer.step()之前，且不能在accelerator.prepare()包裹范围内调用（否则 DDP 下各进程状态不同步） - 如果仍报错，临时关掉 ControlNet 的 checkpoint（它参数量小，影响有限），优先保 UNet 的显存节省
LoRA 微调 ControlNet 时，target_modules 不能只写 "conv_in"
ControlNet 的结构比 UNet 简单，但关键控制信号是从 conv_in → down_blocks → mid_block 逐层注入的。只在 conv_in 加 LoRA，等于只调了最表层的输入映射，后面所有下采样块都还是冻结的原始权重，根本无法引导生成结构。
立即学习“Python免费学习笔记（深入）”；
- 推荐 target 列表：
["conv_in", "down_blocks.0.resnets.0.conv1", "down_blocks.1.resnets.0.conv1", "mid_block.resnets.0.conv1"]（覆盖主要下采样路径） - 别碰
controlnet_cond_embedding里的模块（如conv_out），那是把 condition 图编码成 latent 的部分，微调它容易让 ControlNet “看不懂”输入图语义 - LoRA rank 设为 8 或 16 足够，rank > 32 时 loss 下降变慢，且 inference 时
merge_and_unload()容易出 shape mismatch
ControlNet 微调最耗神的地方不在代码，而在 condition 图的质量和与 prompt 的语义一致性。哪怕训练脚本全对，一张模糊的 Canny 图配一句“高清细节”，模型也只会学会在模糊区域硬凑纹理——这时候该修数据，不是调 learning rate。
