Diffusers 文本引导深度图到图像生成实战StableDiffusionDepth2ImgPipeline 原理与用法解析【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers导读本文基于 Diffusers 官方文档系统讲解StableDiffusionDepth2ImgPipeline这一文本引导的深度图到图像depth-to-image生成管线它允许你同时输入一段文本提示词与一张初始图片在保持原图空间结构的前提下重新生成全新内容若未提供深度图管线还会自动调用内置的深度估计模型预测深度。读完本文你将掌握该管线的加载方式、核心参数调优、深度图手动脉传的完整玩法并能从源码层面理解深度信息是如何参与扩散去噪过程的。什么是深度图到图像生成depth-to-image普通的图生图img2img只依赖文本 初始图片约束生成方向而深度图到图像生成额外引入了一路几何结构约束由深度估计模型MiDaS / DPT从输入图片中提取逐像素的相对深度信息深度值越大代表物体离相机越近。扩散模型在去噪时同时参考这条深度通道因此能在老虎保持猫咪的构图与纵深关系的同时完成主体替换结构保真度远高于纯文本驱动的 img2img。在 Diffusers 中这一能力由StableDiffusionDepth2ImgPipeline提供对应的官方检查点是stabilityai/stable-diffusion-2-depth。该模型属于 Stable Diffusion 2 系列其整体架构与经典 Stable Diffusion 基本一致仅在 UNet 输入端多拼接了一路深度特征见下文源码解析。Stable Diffusion 2 系列在 LAION-5B 的美学子集上训练采用 OpenCLIP 新文本编码器支持 512×512 与 768×768 两种默认分辨率。快速上手加载管线并生成第一张图1. 安装与依赖使用本管线至少需要diffusers、torch、transformers提供 CLIP 文本编码器与 DPT 深度估计模型以及PIL图像读写。DPTForDepthEstimation与DPTImageProcessor均来自 transformers 库是管线内置深度估计环节的必需组件。2. 创建管线实例参照 韩文官方文档 与 英文使用指南加载方式如下import torch from diffusers import StableDiffusionDepth2ImgPipeline pipe StableDiffusionDepth2ImgPipeline.from_pretrained( stabilityai/stable-diffusion-2-depth, torch_dtypetorch.float16, use_safetensorsTrue, # 加载 safetensors 格式权重更安全 ).to(cuda) # 也可换成 mps、xpu 或 cpu几点说明from_pretrained会自动下载管线全部 7 个组件VAE、文本编码器、分词器、UNet、调度器、深度估计器、特征提取器并缓存在本地使用torch.float16可显著降低显存占用并加速推理若显存紧张可改用torch.float32或torch.bfloat16.to(cuda)将整条管线搬到 GPU在 Apple Silicon 上可传mps。3. 传入提示词与初始图片官方文档以一张 COCO 数据集中的猫咪图片为例将其改写成两只老虎from PIL import Image import requests url http://images.cocodataset.org/val2017/000000039769.jpg init_image Image.open(requests.get(url, streamTrue).raw) prompt two tigers n_prompt bad, deformed, ugly, bad anatomy image pipe(promptprompt, imageinit_image, negative_promptn_prompt, strength0.7).images[0] image在英文版文档中加载图片与并排对比推荐使用 Diffusers 自带工具函数更加简洁from diffusers.utils import load_image, make_image_grid init_image load_image(url) image pipe(promptprompt, imageinit_image, negative_promptn_prompt, strength0.7).images[0] make_image_grid([init_image, image], rows1, cols2) # 左右并排对比输入输出prompt希望生成的画面内容如two tigersnegative_prompt负面提示词用于抑制不想出现的内容畸变、低质量、不良解剖结构等在无分类器引导guidance_scale 1时会被忽略strength0.7改写强度取值范围[0, 1]数值越大对原图改动越剧烈详见下文参数解析。核心参数详解与调优StableDiffusionDepth2ImgPipeline的__call__方法签名定义在 pipeline_stable_diffusion_depth2img.py 中核心参数与默认值如下参数默认值作用说明promptNone文本提示词str或str列表不传时须传prompt_embedsimageNone初始图片支持PIL.Image、torch.Tensor、np.ndarray及其列表必填depth_mapNone手动提供的深度图张量不传则由内置 DPT 模型自动预测strength0.8改写强度须在[0, 1]越大加噪越多、改动越大1.0时基本忽略原图num_inference_steps50总去噪步数步数越多质量越高但越慢会被strength按比例削减实际步数guidance_scale7.5无分类器引导强度1时启用 CFG越大越贴近提示词但可能牺牲画质negative_promptNone负面提示词num_images_per_prompt1每个提示词生成的图片数eta0.0DDIM 论文中的 η仅对DDIMScheduler生效generatorNonetorch.Generator传入固定种子可复现结果output_typepil输出格式可选pil、np、latentclip_skipNone跳过 CLIP 末尾若干层计算提示嵌入如1表示使用倒数第二层输出callback_on_step_endNone每个去噪步结束时回调可配合callback_on_step_end_tensor_inputs使用strength 与步数的联动关系strength决定去噪从哪个中间时刻开始。从 get_timesteps 的源码可见init_timestep min(int(num_inference_steps * strength), num_inference_steps) t_start max(num_inference_steps - init_timestep, 0) timesteps self.scheduler.timesteps[t_start * self.scheduler.order :]也就是说strength越大初始噪声时刻越靠后实际执行的去噪步数越接近num_inference_steps全量strength1.0时等效于完全从纯噪声出发近似文生图。check_inputs会校验strength必须落在[0.0, 1.0]越界会直接抛出ValueError。手动传入 depth_map默认情况下管线自动估计深度但官方文档明确指出你也可以主动传入depth_map以显式控制要保留的结构。典型的做法是先独立跑一次深度估计再把结果喂给管线import torch # 用任一 DPT/MiDaS 模型先算出深度图 depth_map ... # torch.Tensor形状 (B, 1, H, W)值域可任意内部会归一化 image pipe( prompttwo tigers, imageinit_image, depth_mapdepth_map, # 显式传入深度跳过自动估计 strength0.7, ).images[0]从 prepare_depth_map 的源码可以看到无论深度来自自动估计还是手动传入后续都会被统一处理双三次插值缩放到(H // vae_scale_factor, W // vae_scale_factor)再按通道做 min-max 归一化到[-1, 1]区间。因此手动传入时无需自己预先归一化。源码级原理深度信息如何参与去噪要真正理解 depth-to-image最直接的方式是通读 pipeline_stable_diffusion_depth2img.py。组件构成构造函数注册了 7 个模块L121-L166vaeAutoencoderKL负责图像与潜空间的双向编解码text_encoder/tokenizerCLIP 文本编码器与分词器unetUNet2DConditionModel去噪主干网络scheduler调度器支持DDIMScheduler、LMSDiscreteScheduler、PNDMScheduler等depth_estimatorDPTForDepthEstimation内置深度估计模型基于 MiDaS 的 DPT-Hybridfeature_extractorDPTImageProcessor深度模型的输入预处理。此外管线还设置了model_cpu_offload_seq text_encoder-unet-vae启用enable_model_cpu_offload时会按此顺序将模型在 CPU/GPU 间搬移是官方推荐的显存优化路径。深度通道与 UNet 的 5 通道输入在去噪循环中L842-L855latent_model_input torch.cat([latents] * 2) if self.do_classifier_free_guidance else latents latent_model_input self.scheduler.scale_model_input(latent_model_input, t) latent_model_input torch.cat([latent_model_input, depth_mask], dim1)深度图在通道维与潜变量拼接后再送入 UNet因此该管线的 UNet 输入通道数为 54 通道潜变量 1 通道深度而普通 Stable Diffusion 的 UNet 是 4 通道输入。这一点在 测试用例 中有直接印证测试构造的 dummy UNet 明确设置了in_channels5、out_channels4。当启用无分类器引导guidance_scale 1时prepare_depth_map会把深度图复制两份与条件/无条件潜变量对齐保证两条分支拿到相同的结构约束。自动深度估计的 fp16 兼容处理当未传depth_map时管线用feature_extractor预处理图像再交给depth_estimator输出predicted_depth。源码特别注明L576-L587DPT-Hybrid 模型含 batch-norm 层不兼容 fp16因此在半精度推理时用torch.autocast自动混合精度包裹深度估计在 MPSApple Silicon上由于不支持 autocast则退化为全精度并打印警告。输出与返回结构去噪结束后潜变量经 VAE 解码除以scaling_factor由VaeImageProcessor.postprocess转成output_type指定格式最终返回ImagePipelineOutput(images...)return_dictTrue时或纯元组。测试中慢速用例test_stable_diffusion_depth.py验证了 480×640 输入图可原分辨率输出说明该管线不强制 512×512输出分辨率跟随输入图片。进阶玩法LoRA、Textual Inversion 与显存优化组件级扩展能力StableDiffusionDepth2ImgPipeline同时继承了TextualInversionLoaderMixin与StableDiffusionLoraLoaderMixin类定义因此天然支持load_textual_inversion(...)加载文本反转嵌入实现自定义概念词load_lora_weights(...)/save_lora_weights(...)加载/保存 LoRA 权重可用于风格迁移或人物一致性微调。官方 API 文档 中亦列出该管线支持enable_attention_slicing、disable_attention_slicing、enable_xformers_memory_efficient_attention等内存优化接口。此外encode_prompt支持传入prompt_embeds/negative_prompt_embeds复用预计算嵌入以及clip_skip跳过 CLIP 末层方便与提示词加权等技巧结合。替换调度器提速Stable Diffusion 2 官方文档建议将默认调度器替换为DPMSolverMultistepScheduler它在速度与质量之间取得良好平衡仅需约 20 步即可得到不错的结果适合在 depth-to-image 流程中显著缩短推理时间from diffusers import DPMSolverMultistepScheduler pipe.scheduler DPMSolverMultistepScheduler.from_config(pipe.scheduler.config) image pipe(promptprompt, imageinit_image, strength0.7, num_inference_steps20).images[0]更进一步的显存优化pipe.enable_model_cpu_offload()按text_encoder-unet-vae顺序逐模块搬移显著降低峰值显存pipe.enable_attention_slicing()切分注意力计算用少量时间换取显存下降在 测试文件 中TestStableDiffusionDepth2ImgPipelineMemory专门覆盖了 CPU offload、group offload 与逐层低精度转换等内存优化场景可作为调优参考。测试与验证仓库为这条管线提供了完整测试覆盖位于 tests/pipelines/stable_diffusion_2/test_stable_diffusion_depth.py默认生成校验输出形状与特定像素切片的期望值确保 CPU 上结果可复现negative_prompt 分支验证负面提示词确实参与 CFG 引导多图输入prompt与image均为长度为 2 的列表时输出批量形状(2, C, H, W)PIL 输入路径验证PIL.Image输入与张量输入结果一致慢速/夜间测试加载真实检查点stabilityai/stable-diffusion-2-depth以strength0.75、guidance_scale7.5推理并对比预存参考数组误差 1e-3。这些测试一方面锁定了管线的行为契约另一方面也为读者提供了最小可复现调用的范例——例如get_dummy_inputs中prompt、image、guidance_scale、num_inference_steps的最小组合。小结深度图到图像生成是在 img2img 基础上叠加几何约束的实用方案StableDiffusionDepth2ImgPipeline将 MiDaS/DPT 深度估计与 Stable Diffusion 2 扩散主干融为一体深度通道作为 UNet 的第 5 路输入贯穿整个去噪过程从而实现结构不变、内容重写。本文从加载、推理、参数调优讲到源码级原理与测试佐证你可以基于此快速搭建自己的 depth-to-image 应用并借助 LoRA、调度器替换与显存优化进一步扩展它的能力边界。若需查阅更多细节可直接研读官方使用指南 docs/source/en/using-diffusers/depth2img.md、管线源码 pipeline_stable_diffusion_depth2img.py 以及对应测试 test_stable_diffusion_depth.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），仅供参考