使用 diffusers 实现 Image-to-Image 生成StableDiffusionImg2ImgPipeline 完整实战指南【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers图像到图像Image-to-Image简称 img2img生成是扩散模型最实用的能力之一它不再像文生图那样从纯噪声开始而是以一张已有图片作为扩散过程的起点结合文本提示词对其内容、风格与细节进行重绘与改造。本文以 Diffusers 仓库中StableDiffusionImg2ImgPipeline为核心对应文档见 docs/source/en/using-diffusers/img2img.md韩文版见 docs/source/ko/using-diffusers/img2img.md从原理、最小可运行示例、关键参数strength、guidance_scale、负向提示词到多管线串联、ControlNet 可控生成与推理优化循序渐进展开同时结合仓库源码与测试用例解释底层机制。读完本文你将能够独立搭建一条可复现的图生图工作流并理解每个参数对输出的实际影响。一、Image-to-Image 的核心原理从噪声到新图的完整链路Image-to-Image 与文生图Text-to-Image最大的区别在于扩散过程并非从随机高斯噪声起步而是从一张真实图片出发。整个流程可以拆解为以下四步依据 StableDiffusionImg2ImgPipeline 实现编码到潜空间初始图片经 VAE 编码器压缩为 latent 表示prepare_latents中调用self.vae.encode(image)再乘以self.vae.config.scaling_factor进行缩放加噪根据strength决定向 latent 中加入多少噪声self.scheduler.add_noise(init_latents, noise, timestep)加噪越多模型后续的创作自由度越大条件去噪潜空间扩散模型UNet同时接收文本提示词编码与带噪 latent预测被添加的噪声并逐步将其去除解码还原去噪完成的新 latent 经 VAE 解码器重新映射回像素空间得到最终图像。这一链路正是 pipeline_stable_diffusion_img2img.py 的__call__方法 所执行的完整流程。理解加噪-去噪的本质是后面理解strength参数的前提。二、环境准备与最小可运行示例2.1 安装依赖使用StableDiffusionImg2ImgPipeline需要安装以下库原文安装命令pip install diffusers transformers ftfy acceleratediffusers提供管线与模型组件transformers提供文本编码器如 CLIPftfy文本修复工具用于规范提示词文本accelerate支持enable_model_cpu_offload等显存优化能力。如需在 CUDA 环境以半精度运行还需确认已安装对应版本的torch。2.2 加载预训练模型并构建管线直接实例化StableDiffusionImg2ImgPipeline是最直观的用法。以吉卜力风格Ghibli-style微调检查点为例该示例来自 韩文版 img2img 指南import torch from diffusers import StableDiffusionImg2ImgPipeline device cuda pipe StableDiffusionImg2ImgPipeline.from_pretrained( nitrosocke/Ghibli-Diffusion, torch_dtypetorch.float16, ).to(device)注意仓库源码中from_pretrained加载精度的参数名为torch_dtype参见 pipeline_stable_diffusion_img2img.py 的示例 docstring传入torch.float16可以显著降低显存占用并提升推理速度。2.3 准备初始图片初始图片既可以是本地文件也可以通过 HTTP 下载。原文档使用requests与PIL完成下载、解码与预处理from PIL import Image import requests from io import BytesIO # 替换为你的初始图片 URL 或本地路径 url your_image_url_or_local_path response requests.get(url) init_image Image.open(BytesIO(response.content)).convert(RGB) init_image.thumbnail((768, 768)) init_image这里做了两件关键预处理.convert(RGB)统一通道数为 3避免 RGBA 或灰度图引发的形状错误.thumbnail((768, 768))将图片缩放到 768px 以内。潜空间 VAE 要求输入宽高为 8 的整数倍源码preprocess中有w, h (x - x % 8 for x in (w, h))的处理逻辑过大图片会显著增加显存与耗时。2.4 定义提示词并执行生成对于吉卜力风格检查点需要在提示词前附加ghibli style触发词这类风格 token由该检查点训练时定义使用前需查看模型卡说明prompt ghibli style, a fantasy landscape with castles generator torch.Generator(devicedevice).manual_seed(1024) image pipe( promptprompt, imageinit_image, strength0.75, guidance_scale7.5, generatorgenerator, ).images[0] imagestrength0.75保留部分原图结构同时允许较大幅度的风格变换guidance_scale7.5提示词引导强度是 Stable Diffusion 系列的常用默认值generator固定随机种子1024保证结果可复现。2.5 切换调度器Scheduler观察输出差异调度器决定去噪步进的数学策略。原文档演示了如何把默认调度器替换为LMSDiscreteSchedulerfrom diffusers import LMSDiscreteScheduler lms LMSDiscreteScheduler.from_config(pipe.scheduler.config) pipe.scheduler lms generator torch.Generator(devicedevice).manual_seed(1024) image pipe( promptprompt, imageinit_image, strength0.75, guidance_scale7.5, generatorgenerator, ).images[0] image要点是LMSDiscreteScheduler.from_config(pipe.scheduler.config)——它复用当前调度器的配置如beta_start、beta_end、prediction_type等保证切换后扩散过程语义一致。LMSDiscreteScheduler的完整实现见 src/diffusers/schedulers/scheduling_lms_discrete.py。仓库测试也专门覆盖了 K-LMS 场景见 tests/pipelines/stable_diffusion/test_stable_diffusion_img2img.py 中test_stable_diffusion_img2img_k_lms说明切换调度器是官方支持的常规操作。三、更省心的入口AutoPipelineForImage2Image手写StableDiffusionImg2ImgPipeline需要明确知道检查点对应的管线类型而 AutoPipelineForImage2Image 会根据model_index.json中记录的_class_name自动匹配正确的图生图管线类import torch from diffusers import AutoPipelineForImage2Image from diffusers.utils import load_image, make_image_grid pipeline AutoPipelineForImage2Image.from_pretrained( kandinsky-community/kandinsky-2-2-decoder, torch_dtypetorch.float16, use_safetensorsTrue, ) pipeline.enable_model_cpu_offload() # 若未安装 xFormers 或已使用 PyTorch 2.0可删除下一行 pipeline.enable_xformers_memory_efficient_attention() init_image load_image(your_image_url_or_local_path) prompt cat wizard, gandalf, lord of the rings, detailed, fantasy, cute, adorable, Pixar, Disney, 8k image pipeline(prompt, imageinit_image).images[0] make_image_grid([init_image, image], rows1, cols2)从源码看AutoPipelineForImage2Image.from_pretrained会根据配置对象的_class_name检测管线类并通过类名模式匹配找到对应的图生图管线见 auto_pipeline.py 中的类 docstring。此外若传入controlnet参数它会自动实例化为StableDiffusionControlNetImg2ImgPipeline这为后面的 ControlNet 章节埋下伏笔。enable_model_cpu_offload()与enable_xformers_memory_efficient_attention()两个方法贯穿整个指南前者把管线组件按需在 CPU/GPU 间搬移以节省显存后者启用内存高效的注意力实现若使用 PyTorch 2.0其原生 scaled-dot product attention 已默认生效无需再调用 xFormers详见 docs/source/en/optimization/fp16.md。四、主流图生图模型横向对比不同检查点的架构与训练方式差异会直接影响输出质量原文档对比了三种流行模型。4.1 Stable Diffusion v1.5由早期检查点初始化并额外微调 59.5 万步512×512 分辨率的潜扩散模型pipeline AutoPipelineForImage2Image.from_pretrained( stable-diffusion-v1-5/stable-diffusion-v1-5, torch_dtypetorch.float16, variantfp16, use_safetensorsTrue, ) pipeline.enable_model_cpu_offload() pipeline.enable_xformers_memory_efficient_attention() init_image load_image(your_image_url_or_local_path) prompt Astronaut in a jungle, cold color palette, muted colors, detailed, 8k image pipeline(prompt, imageinit_image).images[0] make_image_grid([init_image, image], rows1, cols2)4.2 Stable Diffusion XLSDXLSDXL 采用更大的基础模型并附带一个 refiner 模型用于提升基础模型输出质量。完整用法可参考 docs/source/en/api/pipelines/stable_diffusion/stable_diffusion_xl.md。加载 refiner 作为图生图管线pipeline AutoPipelineForImage2Image.from_pretrained( stabilityai/stable-diffusion-xl-refiner-1.0, torch_dtypetorch.float16, variantfp16, use_safetensorsTrue, ) pipeline.enable_model_cpu_offload() pipeline.enable_xformers_memory_efficient_attention() init_image load_image(your_image_url_or_local_path) image pipeline(prompt, imageinit_image, strength0.5).images[0]4.3 Kandinsky 2.2Kandinsky 与 Stable Diffusion 架构不同它先用一个 image prior 模型把文本映射为图像嵌入image embeddings从而让文本与图像对齐更充分再交由潜扩散模型生成。其使用方式与前述一致仅更换模型 ID 为kandinsky-community/kandinsky-2-2-decoder。从使用角度可总结SDXL 通常在画质与细节上优于 SD v1.5Kandinsky 在文本-图像对齐上有独特优势。三者共享同一套AutoPipelineForImage2Image调用接口因此切换成本极低。五、核心参数深度解析5.1 strength控制像原图还是有创意strength是图生图中影响最大的参数取值范围[0.0, 1.0]语义如下值越高模型越自由生成结果与原图差异越大strength1.0时原图几乎被忽略等价于从纯噪声起步值越低生成结果越接近原图。strength与num_inference_steps是耦合的因为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 :]也就是说当num_inference_steps50、strength0.8时实际只执行50 × 0.8 40步去噪而check_inputs会对越界值直接抛错The value of strength should in [0.0, 1.0]见 check_inputs 方法。prepare_latents则负责把加噪后的 latent 作为去噪起点源码位置。实操建议想要轻度重绘/风格微调用0.3 ~ 0.5想要大幅改版用0.6 ~ 0.81.0几乎等于重新生成。5.2 guidance_scale提示词服从度guidance_scale默认 7.5控制生成图与提示词的对齐程度。值越高图像越贴合文本描述值越低模型越有偏离空间。在源码中它通过 classifier-free guidance 生效当guidance_scale 1时UNet 同时推理无条件与有条件两组噪声预测再按公式融合noise_pred_uncond, noise_pred_text noise_pred.chunk(2) noise_pred noise_pred_uncond self.guidance_scale * (noise_pred_text - noise_pred_uncond)见 denoising 循环中的实现。guidance_scale可与strength组合实现更精细的表达控制高strength 高guidance_scale最大化创意且紧扣提示词低strength 低guidance_scale输出贴近原图同时不被提示词严格束缚。5.3 negative_prompt负向提示词负向提示词告诉模型不要生成什么可用于提升画质如排除 poor details、blurry或做内容排除。示例negative_prompt ugly, deformed, disfigured, poor details, bad anatomy image pipeline( prompt, negative_promptnegative_prompt, imageinit_image, ).images[0]从源码看负向提示词仅在开启 classifier-free guidanceguidance_scale 1时生效对应 docstring 说明。六、链式管线让图生图能力叠加单次图生图之外原文档还展示了把多条管线串联起来的进阶玩法。6.1 Text-to-Image-to-Image文生图 → 图生图先用文生图管线从零生成一张图再把它作为图生图管线的初始图from diffusers import AutoPipelineForText2Image, AutoPipelineForImage2Image import torch from diffusers.utils import make_image_grid pipeline AutoPipelineForText2Image.from_pretrained( stable-diffusion-v1-5/stable-diffusion-v1-5, torch_dtypetorch.float16, variantfp16, use_safetensorsTrue, ) pipeline.enable_model_cpu_offload() text2image pipeline(Astronaut in a jungle, cold color palette, muted colors, detailed, 8k).images[0] pipeline AutoPipelineForImage2Image.from_pretrained( kandinsky-community/kandinsky-2-2-decoder, torch_dtypetorch.float16, use_safetensorsTrue, ) pipeline.enable_model_cpu_offload() image2image pipeline(Astronaut in a jungle, cold color palette, muted colors, detailed, 8k, imagetext2image).images[0] make_image_grid([text2image, image2image], rows1, cols2)这种组合适合完全从零开始又要二次风格化/精修的流程。6.2 Image-to-Image-to-Image潜空间接力把多个图生图管线首尾相接可以迭代式风格迁移、生成短 GIF、修复色彩或补全区域。关键技巧是第一段输出使用output_typelatent让结果停留在潜空间直接交给下一段省去一次解码-再编码image pipeline(prompt, imageinit_image, output_typelatent).images[0] # 换用风格模型需在提示词中包含其风格 token如 charliebo artstyle image pipeline(Astronaut in a jungle, charliebo artstyle, imageimage, output_typelatent).images[0] # 再换像素风模型提示词加 pixelartstyle image pipeline(Astronaut in a jungle, pixelartstyle, imageimage).images[0]注意潜空间直传仅在两段管线使用相同 VAE 时成立。6.3 放大与超分链图生图 → 潜空间放大 → 超分辨率逐级提升细节from diffusers import StableDiffusionLatentUpscalePipeline, StableDiffusionUpscalePipeline image_1 pipeline(prompt, imageinit_image, output_typelatent).images[0] upscaler StableDiffusionLatentUpscalePipeline.from_pretrained( stabilityai/sd-x2-latent-upscaler, torch_dtypetorch.float16, use_safetensorsTrue ) image_2 upscaler(prompt, imageimage_1).images[0] super_res StableDiffusionUpscalePipeline.from_pretrained( stabilityai/stable-diffusion-x4-upscaler, torch_dtypetorch.float16, variantfp16, use_safetensorsTrue, ) image_3 super_res(prompt, imageimage_2).images[0]七、可控生成提示词加权与 ControlNet7.1 提示词加权Prompt Weighting提示词加权允许按权重缩放提示词中各概念的嵌入强度。AutoPipelineForImage2Image支持prompt_embeds以及配合负向提示词的negative_prompt_embeds参数直接接收预生成的嵌入替代prompt字符串image pipeline( prompt_embedsprompt_embeds, # 由 Compel 等库生成 negative_prompt_embedsnegative_prompt_embeds, imageinit_image, ).images[0]从源码 docstring 可见prompt_embeds的设计目的正是方便微调文本输入prompt weighting参数说明。嵌入的生成方法参见 docs/source/en/using-diffusers/weighted_prompts.md。7.2 ControlNet用条件图精确控制结构ControlNet 通过额外条件图canny 边缘、深度图、分割图甚至涂鸦约束生成结构比负向提示词更精确。以深度图条件为例from diffusers import ControlNetModel, AutoPipelineForImage2Image from diffusers.utils import load_image import torch init_image load_image(your_image_url_or_local_path) depth_image load_image(your_depth_map_path) # 深度图 controlnet ControlNetModel.from_pretrained( lllyasviel/control_v11f1p_sd15_depth, torch_dtypetorch.float16, variantfp16, use_safetensorsTrue, ) pipeline AutoPipelineForImage2Image.from_pretrained( stable-diffusion-v1-5/stable-diffusion-v1-5, controlnetcontrolnet, torch_dtypetorch.float16, variantfp16, use_safetensorsTrue, ) pipeline.enable_model_cpu_offload() pipeline.enable_xformers_memory_efficient_attention() image_control_net pipeline( Astronaut in a jungle, cold color palette, muted colors, detailed, 8k, imageinit_image, control_imagedepth_image, ).images[0]深度图保留了空间位置信息因此输出会在保持构图的前提下重绘细节。若需在 ControlNet 输出上进一步套用风格可再接一段AutoPipelineForImage2Image如 elden-ring 风格模型提示词加elden ring styletoken并用较低strength0.45保留结构。八、推理优化让图生图跑在消费级显卡上扩散模型推理开销大但通过以下手段足以在消费级/免费 tier GPU 上运行pipeline.enable_model_cpu_offload() # 组件按需搬移降低显存峰值 pipeline.enable_xformers_memory_efficient_attention() # 高效注意力PyTorch 2.0 可省略进一步用torch.compile加速 UNetpipeline.unet torch.compile(pipeline.unet, modereduce-overhead, fullgraphTrue)更多方案参见 docs/source/en/optimization/memory.md降低显存与 docs/source/en/optimization/fp16.md加速推理后者还介绍了 PyTorch 2.0 原生 scaled-dot product attention 的原理。九、测试与验证仓库如何保证图生图管线可用仓库为图生图管线提供了系统化测试是验证上述用法的可靠参照见 tests/pipelines/stable_diffusion/test_stable_diffusion_img2img.pytest_stable_diffusion_img2img_default_case默认参数下的小规模冒烟测试test_stable_diffusion_img2img_negative_prompt验证负向提示词路径test_stable_diffusion_img2img_multiple_init_images验证多张初始图输入test_stable_diffusion_img2img_k_lms验证切换 K-LMS 调度器test_stable_diffusion_img2img_pipeline_multiple_of_8验证输入尺寸必须为 8 的整数倍这一约束。如果你想基于当前仓库自行复现可在安装依赖后运行该测试文件以确认本地环境与管线行为一致。小结围绕StableDiffusionImg2ImgPipeline与AutoPipelineForImage2Image本文完整覆盖了从原理、环境搭建、基础调用、参数调优strength/guidance_scale/negative_prompt、调度器切换、链式管线、ControlNet 可控生成到推理优化的全链路实践。其核心心智模型是加噪比例strength决定改写幅度引导系数guidance_scale决定对文本的服从度而管线串联与 ControlNet 则把单次生成扩展为可组合、可控制的完整工作流。建议读者在实际项目中以本仓库源码与测试为对照逐步实验各参数组合找到最适合自己场景的配置。【免费下载链接】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），仅供参考