Kandinsky 2.2 系列 Pipeline 完全指南Diffusers 中的文生图、图生图、图像修复与 ControlNet 实战【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusersKandinsky 2.2 是 Diffusers 中内置的一套多阶段扩散模型家族本文基于 API 参考文档 与 kandinsky2_2 源码目录 编写系统讲解其 Prior Decoder 两阶段架构、9 个 Pipeline 类、统一自动加载AutoPipeline用法以及基于 CLIP-ViT-G 图像编码器和 ControlNet 机制的文生图、图生图、修复、深度控制等完整实战方案。读完本文你将掌握如何用几行代码搭建可复现的 Kandinsky 2.2 生成工作流并理解底层调用链与关键参数的作用。一、Kandinsky 2.2 是什么Kandinsky 2.2 由 Arseniy Shakhmatov、Anton Razzhigaev、Aleksandr Nikolich、Vladimir Arkhipkin、Igor Pavlov、Andrey Kuznetsov 与 Denis Dimitrov 等作者创建是其前身 Kandinsky 2.1 的显著升级版。官方描述的两大核心改进是更强大的图像编码器 CLIP-ViT-G替换旧版图像编码器后模型生成图像的美感与对文本的理解能力都明显提升ControlNet 支持通过 ControlNet 机制有效控制图像生成过程实现更精确、更具视觉吸引力的输出并开辟了文本引导图像编辑的新可能。在 Diffusers 仓库中Kandinsky 2.2 的完整实现位于 src/diffusers/pipelines/kandinsky2_2由 9 个模块文件组成对应 9 个 Pipeline 类全部继承自DiffusionPipeline基类享有统一的模型下载/保存、设备迁移、CPU offload 等通用能力。二、两阶段架构Prior 与 Decoder理解 Kandinsky 2.2 的关键是它的两阶段Prior Decoder架构Prior 阶段图像先验KandinskyV22PriorPipeline使用PriorTransformer与UnCLIPScheduler把 CLIP 文本嵌入CLIPTextModelWithProjection翻译成 CLIP 图像嵌入。这个阶段输出的是嵌入向量而非图像Decoder 阶段解码生成KandinskyV22Pipeline使用UNet2DConditionModelDDPMScheduler在嵌入条件引导下去噪最后由MoVQ 解码器VQModel把潜变量解码为真实图像。从源码可见Decoder 管线的组件构成非常精简pipeline_kandinsky2_2.pydef __init__(self, unet: UNet2DConditionModel, scheduler: DDPMScheduler, movq: VQModel):而 Prior 管线则聚合了 6 个组件pipeline_kandinsky2_2_prior.pydef __init__( self, prior: PriorTransformer, image_encoder: CLIPVisionModelWithProjection, text_encoder: CLIPTextModelWithProjection, tokenizer: CLIPTokenizer, scheduler: UnCLIPScheduler, image_processor: CLIPImageProcessor, ):Prior 阶段默认走 25 步去噪Decoder 阶段默认 100 步UnCLIPScheduler负责先验扩散DDPMScheduler负责解码器去噪。两阶段各自独立可复用——这正是本文后面组件跨管线复用技巧的基础。文生图完整示例两管线串联Prior 管线 docstring 给出了标准的串联调用方式from diffusers import KandinskyV22Pipeline, KandinskyV22PriorPipeline import torch pipe_prior KandinskyV22PriorPipeline.from_pretrained(kandinsky-community/kandinsky-2-2-prior) pipe_prior.to(cuda) prompt red cat, 4k photo image_emb, negative_image_emb pipe_prior(prompt).to_tuple() pipe KandinskyV22Pipeline.from_pretrained(kandinsky-community/kandinsky-2-2-decoder) pipe.to(cuda) image pipe( image_embedsimage_emb, negative_image_embedsnegative_image_emb, height768, width768, num_inference_steps50, ).images image[0].save(cat.png)Prior 管线的输出是KandinskyPriorPipelineOutput数据类包含image_embeds正向图像嵌入与negative_image_embeds负向图像嵌入两个字段当return_dictFalse时可退化为普通二元组。Prior 阶段的内部调用链从源码看KandinskyV22PriorPipeline.__call__的完整流程是Prompt 编码_encode_prompttokenizer 以max_length填充并截断text_encoder输出text_embeds与last_hidden_state当启用无分类器引导guidance_scale 1时会把无条件嵌入与条件嵌入拼接成一批一次前向完成两次推理初始化潜变量prepare_latents形状为(batch_size, embedding_dim)用randn_tensor采样并乘以scheduler.init_noise_sigma迭代去噪prior模型接收proj_embedding、encoder_hidden_states、attention_mask输出predicted_image_embeddingCFG 公式为uncond guidance_scale * (text - uncond)后处理prior.post_process_latents得到最终嵌入若未提供 negative prompt则通过get_zero_embed用全零图像经image_encoder生成零嵌入输出output_type仅支持pt与np默认pt。值得注意的是KandinskyV22PriorPipeline设置了model_cpu_offload_seq text_encoder-image_encoder-prior且把prior排除在 offload 之外_exclude_from_cpu_offload [prior]说明 PriorTransformer 是计算热点适合常驻 GPU。三、9 个 Pipeline 类总览文档共罗列 9 个 Pipeline 类对应 9 个源码文件构成完整的功能矩阵Pipeline 类源码文件功能KandinskyV22PriorPipelinepipeline_kandinsky2_2_prior.py文生图 Prior文本 → 图像嵌入含interpolateKandinskyV22Pipelinepipeline_kandinsky2_2.py文生图 Decoder嵌入 → 图像KandinskyV22CombinedPipelinepipeline_kandinsky2_2_combined.py文生图一体化Prior Decoder 合并KandinskyV22ControlnetPipelinepipeline_kandinsky2_2_controlnet.pyControlNet 文生图如深度控制KandinskyV22PriorEmb2EmbPipelinepipeline_kandinsky2_2_prior_emb2emb.py图像引导 Prior图生图的嵌入重编含interpolateKandinskyV22Img2ImgPipelinepipeline_kandinsky2_2_img2img.py图生图 DecoderKandinskyV22Img2ImgCombinedPipelinepipeline_kandinsky2_2_combined.py图生图一体化KandinskyV22ControlnetImg2ImgPipelinepipeline_kandinsky2_2_controlnet_img2img.pyControlNet 图生图KandinskyV22InpaintPipelinepipeline_kandinsky2_2_inpainting.py图像修复 DecoderKandinskyV22InpaintCombinedPipelinepipeline_kandinsky2_2_combined.py图像修复一体化统一自动加载AutoPipeline不想手动串联 Prior 与 Decoder 时可以依赖 AutoPipeline 的自动路由。从 auto_pipeline.py 的注册表可以看出文生图自动路由到KandinskyV22CombinedPipeline或 decoder 版KandinskyV22Pipeline图生图自动路由到KandinskyV22Img2ImgCombinedPipeline或KandinskyV22Img2ImgPipeline修复自动路由到KandinskyV22InpaintCombinedPipeline或KandinskyV22InpaintPipeline。源码注释还指出connected pipelines一体化管线只能从 decoder 型 checkpoint 加载例如kandinsky-community/kandinsky-2-2-decoder——它会自动把 Prior 组件一并装配进来。文生图的一体化用法如下出自 Combined 管线 docstringfrom diffusers import AutoPipelineForText2Image import torch pipe AutoPipelineForText2Image.from_pretrained( kandinsky-community/kandinsky-2-2-decoder, torch_dtypetorch.float16 ) pipe.enable_model_cpu_offload() prompt A lion in galaxies, spirals, nebulae, stars, smoke, iridescent, intricate detail, octane render, 8k image pipe(promptprompt, num_inference_steps25).images[0]一体化管线在__init__内部自动构建prior_pipe与decoder_pipe两个子管线见 pipeline_kandinsky2_2_combined.py并额外暴露prior_guidance_scale默认 4.0与prior_num_inference_steps默认 25两个参数分别控制 Prior 阶段的引导强度与步数。其model_cpu_offload_seq prior_text_encoder-prior_image_encoder-unet-movq表明整套管线按顺序卸载到 CPU 以节省显存。组件跨管线复用与调度器调优官方文档特别提醒两点原文档 TIP阅读 调度器指南 学习如何权衡调度器的速度与质量阅读 跨管线复用模型 章节学习如何把相同组件高效加载到多个管线中。由于 Prior 与 Decoder 是解耦的两套组件你可以把同一个KandinskyV22PriorPipeline的结果喂给普通 Decoder、ControlNet Decoder 或修复 Decoder复用一次嵌入计算。四、图生图strength 与时间步截断KandinskyV22Img2ImgPipeline在 Decoder 组件之外还内置了VaeImageProcessorvae_scale_factor取自movq_scale_factorresamplebicubic。其核心参数是strength默认0.3数值越大注入的初始噪声越多输出与输入图的差异越大strength1时等价于完全重绘。底层的时间步截断逻辑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:]即只从第init_timestep步开始去噪实际执行的去噪步数为num_inference_steps - t_start。初始潜变量由movq.encode(image).latent_dist.sample(generator)编码后乘movq.config.scaling_factor得到再叠加噪声。图生图 docstring 示例image pipe( imageinit_image, image_embedsimage_emb, negative_image_embedszero_image_emb, height768, width768, num_inference_steps100, strength0.2, ).images image[0].save(red_frog.png)使用AutoPipelineForImage2Image时同样可以自动装配见 Combined 管线 docstringfrom diffusers import AutoPipelineForImage2Image import torch pipe AutoPipelineForImage2Image.from_pretrained( kandinsky-community/kandinsky-2-2-decoder, torch_dtypetorch.float16 ) pipe.enable_model_cpu_offload() prompt A fantasy landscape, Cinematic lighting negative_prompt low quality, bad quality image pipe(promptprompt, imageoriginal_image, num_inference_steps25).images[0]图像引导的 PriorPriorEmb2EmbKandinskyV22PriorEmb2EmbPipeline是图生图流程中 Prior 阶段的图像嵌入重编版本它同样接受image与strength用输入图的图像嵌入作为先验扩散的起点同样的get_timesteps截断逻辑见 pipeline_kandinsky2_2_prior_emb2emb.py从而让最终生成的图像嵌入既贴近文本又保留输入图的语义。它同样实现了interpolate方法详见第七节。该管线的模块组成与KandinskyV22PriorPipeline完全一致仅在去噪初始点与图像输入上不同。五、图像修复mask 语义与 8 通道拼接KandinskyV22InpaintPipeline支持 PIL 图像或np.ndarray形式的mask_image。mask 语义为黑色像素0保留、白色像素1重绘PIL 图像会被自动转换为单通道灰度。底层流程见 pipeline_kandinsky2_2_inpainting.pyprepare_mask_and_masked_image预处理图像与 maskmask 经F.interpolate缩放到潜空间尺寸masked_image image * mask_image得到掩码图像U-Net 输入为[latent_model_input, masked_image, mask_image]的8 通道拼接每一步用latents mask_image * image (1 - mask_image) * latents保持掩码区域锁定。修复示例mask 为 768×768 的float32数组把猫头上方区域置 1from diffusers import AutoPipelineForInpainting from diffusers.utils import load_image import torch import numpy as np pipe AutoPipelineForInpainting.from_pretrained( kandinsky-community/kandinsky-2-2-decoder-inpaint, torch_dtypetorch.float16 ) pipe.enable_model_cpu_offload() prompt A fantasy landscape, Cinematic lighting negative_prompt low quality, bad quality original_image load_image(path/to/cat.png) mask np.zeros((768, 768), dtypenp.float32) # 把猫头上方的区域掩码掉 mask[:250, 250:-250] 1 image pipe(promptprompt, imageoriginal_image, mask_imagemask, num_inference_steps25).images[0]注意修复管线的_callback_tensor_inputs比 Decoder 管线多了masked_image与mask_image因此步末回调可以观测掩码状态。六、ControlNet深度图控制的文生图KandinskyV22ControlnetPipeline的核心在于新增的hint参数——一个经过预处理的控制条件张量如深度图。官方示例用 transformers 的depth-estimation管线生成深度提示再加载kandinsky-community/kandinsky-2-2-controlnet-depthcheckpoint见 ControlNet docstringimport torch import numpy as np from diffusers import KandinskyV22PriorPipeline, KandinskyV22ControlnetPipeline from transformers import pipeline from diffusers.utils import load_image def make_hint(image, depth_estimator): image depth_estimator(image)[depth] image np.array(image) image image[:, :, None] image np.concatenate([image, image, image], axis2) detected_map torch.from_numpy(image).float() / 255.0 hint detected_map.permute(2, 0, 1) return hint depth_estimator pipeline(depth-estimation) pipe_prior KandinskyV22PriorPipeline.from_pretrained( kandinsky-community/kandinsky-2-2-prior, torch_dtypetorch.float16 ).to(cuda) pipe KandinskyV22ControlnetPipeline.from_pretrained( kandinsky-community/kandinsky-2-2-controlnet-depth, torch_dtypetorch.float16 ).to(cuda) img load_image(path/to/cat.png).resize((768, 768)) hint make_hint(img, depth_estimator).unsqueeze(0).half().to(cuda) prompt A robot, 4k photo negative_prior_prompt lowres, text, error, cropped, worst quality, low quality, jpeg artifacts, ugly, duplicate, morbid, mutilated, out of frame, extra fingers, mutated hands, poorly drawn hands, poorly drawn face, mutation, deformed, blurry, dehydrated, bad anatomy, bad proportions, extra limbs, cloned face, disfigured, gross proportions, malformed limbs, missing arms, missing legs, extra arms, extra legs, fused fingers, too many fingers, long neck, username, watermark, signature generator torch.Generator(devicecuda).manual_seed(43) image_emb, zero_image_emb pipe_prior( promptprompt, negative_promptnegative_prior_prompt, generatorgenerator ).to_tuple() images pipe( image_embedsimage_emb, negative_image_embedszero_image_emb, hinthint, num_inference_steps50, generatorgenerator, height768, width768, ).images images[0].save(robot_cat.png)KandinskyV22ControlnetImg2ImgPipeline则同时接受image、hint与strength可以在既有图像上施加结构控制如保持原图构图并重绘内容其get_timesteps与图生图管线一致。七、嵌入插值interpolate 方法Prior 管线KandinskyV22PriorPipeline与KandinskyV22PriorEmb2EmbPipeline都实现了interpolate方法用于在多个文本提示与参考图像之间做嵌入插值实现风格混合。其签名与要点如下pipe_prior.interpolate( images_and_prompts, # list[str | PIL.Image.Image | torch.Tensor]条件列表 weights, # list[float]与条件一一对应的权重 num_images_per_prompt1, num_inference_steps25, generatorNone, latentsNone, negative_prior_promptNone, negative_prompt, guidance_scale4.0, )底层实现逻辑pipeline_kandinsky2_2_prior.pyimages_and_prompts与weights长度必须相等否则抛出ValueError字符串条件调用self(...)走完整 Prior 扩散得到image_embeds图像条件经image_processor预处理后直接过image_encoder得到图像嵌入每个嵌入乘以其权重后求和torch.cat(image_embeddings).sum(dim0)负向嵌入取自negative_prompt对应的零/负向嵌入。官方插值示例interpolate docstringfrom diffusers import KandinskyV22PriorPipeline, KandinskyV22Pipeline from diffusers.utils import load_image import torch pipe_prior KandinskyV22PriorPipeline.from_pretrained( kandinsky-community/kandinsky-2-2-prior, torch_dtypetorch.float16 ).to(cuda) img1 load_image(path/to/cat.png) img2 load_image(path/to/starry_night.jpeg) images_texts [a cat, img1, img2] weights [0.3, 0.3, 0.4] out pipe_prior.interpolate(images_texts, weights) pipe KandinskyV22Pipeline.from_pretrained( kandinsky-community/kandinsky-2-2-decoder, torch_dtypetorch.float16 ).to(cuda) image pipe( image_embedsout.image_embeds, negative_image_embedsout.negative_image_embeds, height768, width768, num_inference_steps50, ).images[0] image.save(starry_cat.png)调整weights即可连续控制猫 星空的混合比例这是 Kandinsky 2.2 做风格迁移与多条件融合的独特能力。八、关键参数速查以下是各管线__call__的核心参数以当前仓库源码签名为准参数默认值适用管线说明prompt/negative_prompt—Prior / Combined文本提示与负提示支持str或list[str]image_embeds/negative_image_embeds—所有 Decoder 类Prior 输出的图像嵌入num_inference_steps25Prior/ 100Decoder全部去噪步数越多质量越高、速度越慢guidance_scale4.0全部CFG 引导强度 1时启用引导越高越贴合提示prior_guidance_scale/prior_num_inference_steps4.0 / 25Combined 类单独控制 Prior 阶段num_images_per_prompt1全部每个提示生成的图像数generatorNone全部torch.Generator传入后结果可复现latentsNone全部预先生成的噪声潜变量可复用做同种子变体height/width512 / 512Decoder 类输出尺寸会被规整到scale_factor²的整数倍strength0.3图生图 / 修复 / Emb2Emb初始噪声注入比例越大改动越大hint—ControlNet 类控制条件张量如深度图mask_image—修复类掩码黑色保留、白色重绘output_typeptPrior/pilDecoder全部pil/np/ptDecoder 另有latentreturn_dictTrue全部True返回数据类False返回元组关于分辨率还有一个易忽略的细节Decoder 管线会调用downscale_height_and_widthpipeline_kandinsky2_2.py把height/width向上取整到movq_scale_factor²默认 8²64的整数倍避免潜空间尺寸非整数。另外 Decoder 的output_typelatent会直接返回未解码的潜变量适合做二次编辑或调试。九、工程实践建议显存管理Prior 与 Decoder 组件较多优先使用enable_model_cpu_offload()逐模块卸载而非.to(cuda)一体化管线已内置卸载顺序enable_sequential_cpu_offload可进一步降低峰值显存但速度更慢半精度与可复现性官方示例普遍使用torch_dtypetorch.float16配合enable_model_cpu_offload需要复现时固定torch.Generator种子如torch.Generator(devicecuda).manual_seed(43)步末回调Decoder 类管线支持callback_on_step_end与callback_on_step_end_tensor_inputs可观测/修改latents、image_embeds、negative_image_embeds修复管线另有masked_image、mask_image旧式callback/callback_steps参数已被标记弃用deprecate至 1.0.0训练与进阶若需要训练或微调 Kandinsky 2.2 相关模型可参考 examples/kandinsky2_2/text_to_image 下的训练脚本与说明以及 kandinsky2_2 测试目录 中的端到端测试用例它们验证了各管线在真实 checkpoint 上的可用性Checkpoint 组织官方模型权重按任务分布在kandinsky-community系列仓库中如kandinsky-2-2-prior、kandinsky-2-2-decoder、kandinsky-2-2-decoder-inpaint、kandinsky-2-2-controlnet-depth等文生图、图生图、修复均有对应官方 checkpoint。十、小结Kandinsky 2.2 在 Diffusers 中是一套结构清晰、覆盖完整的多阶段扩散模型家族Prior负责把文本/图像语义映射到嵌入空间Decoder含 MoVQ负责生成像素ControlNet组件提供结构化条件控制Combined管线把流程封装为一行调用interpolate提供嵌入级的多条件融合能力。掌握 API 参考文档 与 源码目录 中展示的参数语义与调用链你就能在文生图、图生图、修复与结构控制等场景中自由组合这套管线。【免费下载链接】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），仅供参考
Kandinsky 2.2 系列 Pipeline 完全指南Diffusers 中的文生图、图生图、图像修复与 ControlNet 实战【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusersKandinsky 2.2 是 Diffusers 中内置的一套多阶段扩散模型家族本文基于 API 参考文档 与 kandinsky2_2 源码目录 编写系统讲解其 Prior Decoder 两阶段架构、9 个 Pipeline 类、统一自动加载AutoPipeline用法以及基于 CLIP-ViT-G 图像编码器和 ControlNet 机制的文生图、图生图、修复、深度控制等完整实战方案。读完本文你将掌握如何用几行代码搭建可复现的 Kandinsky 2.2 生成工作流并理解底层调用链与关键参数的作用。一、Kandinsky 2.2 是什么Kandinsky 2.2 由 Arseniy Shakhmatov、Anton Razzhigaev、Aleksandr Nikolich、Vladimir Arkhipkin、Igor Pavlov、Andrey Kuznetsov 与 Denis Dimitrov 等作者创建是其前身 Kandinsky 2.1 的显著升级版。官方描述的两大核心改进是更强大的图像编码器 CLIP-ViT-G替换旧版图像编码器后模型生成图像的美感与对文本的理解能力都明显提升ControlNet 支持通过 ControlNet 机制有效控制图像生成过程实现更精确、更具视觉吸引力的输出并开辟了文本引导图像编辑的新可能。在 Diffusers 仓库中Kandinsky 2.2 的完整实现位于 src/diffusers/pipelines/kandinsky2_2由 9 个模块文件组成对应 9 个 Pipeline 类全部继承自DiffusionPipeline基类享有统一的模型下载/保存、设备迁移、CPU offload 等通用能力。二、两阶段架构Prior 与 Decoder理解 Kandinsky 2.2 的关键是它的两阶段Prior Decoder架构Prior 阶段图像先验KandinskyV22PriorPipeline使用PriorTransformer与UnCLIPScheduler把 CLIP 文本嵌入CLIPTextModelWithProjection翻译成 CLIP 图像嵌入。这个阶段输出的是嵌入向量而非图像Decoder 阶段解码生成KandinskyV22Pipeline使用UNet2DConditionModelDDPMScheduler在嵌入条件引导下去噪最后由MoVQ 解码器VQModel把潜变量解码为真实图像。从源码可见Decoder 管线的组件构成非常精简pipeline_kandinsky2_2.pydef __init__(self, unet: UNet2DConditionModel, scheduler: DDPMScheduler, movq: VQModel):而 Prior 管线则聚合了 6 个组件pipeline_kandinsky2_2_prior.pydef __init__( self, prior: PriorTransformer, image_encoder: CLIPVisionModelWithProjection, text_encoder: CLIPTextModelWithProjection, tokenizer: CLIPTokenizer, scheduler: UnCLIPScheduler, image_processor: CLIPImageProcessor, ):Prior 阶段默认走 25 步去噪Decoder 阶段默认 100 步UnCLIPScheduler负责先验扩散DDPMScheduler负责解码器去噪。两阶段各自独立可复用——这正是本文后面组件跨管线复用技巧的基础。文生图完整示例两管线串联Prior 管线 docstring 给出了标准的串联调用方式from diffusers import KandinskyV22Pipeline, KandinskyV22PriorPipeline import torch pipe_prior KandinskyV22PriorPipeline.from_pretrained(kandinsky-community/kandinsky-2-2-prior) pipe_prior.to(cuda) prompt red cat, 4k photo image_emb, negative_image_emb pipe_prior(prompt).to_tuple() pipe KandinskyV22Pipeline.from_pretrained(kandinsky-community/kandinsky-2-2-decoder) pipe.to(cuda) image pipe( image_embedsimage_emb, negative_image_embedsnegative_image_emb, height768, width768, num_inference_steps50, ).images image[0].save(cat.png)Prior 管线的输出是KandinskyPriorPipelineOutput数据类包含image_embeds正向图像嵌入与negative_image_embeds负向图像嵌入两个字段当return_dictFalse时可退化为普通二元组。Prior 阶段的内部调用链从源码看KandinskyV22PriorPipeline.__call__的完整流程是Prompt 编码_encode_prompttokenizer 以max_length填充并截断text_encoder输出text_embeds与last_hidden_state当启用无分类器引导guidance_scale 1时会把无条件嵌入与条件嵌入拼接成一批一次前向完成两次推理初始化潜变量prepare_latents形状为(batch_size, embedding_dim)用randn_tensor采样并乘以scheduler.init_noise_sigma迭代去噪prior模型接收proj_embedding、encoder_hidden_states、attention_mask输出predicted_image_embeddingCFG 公式为uncond guidance_scale * (text - uncond)后处理prior.post_process_latents得到最终嵌入若未提供 negative prompt则通过get_zero_embed用全零图像经image_encoder生成零嵌入输出output_type仅支持pt与np默认pt。值得注意的是KandinskyV22PriorPipeline设置了model_cpu_offload_seq text_encoder-image_encoder-prior且把prior排除在 offload 之外_exclude_from_cpu_offload [prior]说明 PriorTransformer 是计算热点适合常驻 GPU。三、9 个 Pipeline 类总览文档共罗列 9 个 Pipeline 类对应 9 个源码文件构成完整的功能矩阵Pipeline 类源码文件功能KandinskyV22PriorPipelinepipeline_kandinsky2_2_prior.py文生图 Prior文本 → 图像嵌入含interpolateKandinskyV22Pipelinepipeline_kandinsky2_2.py文生图 Decoder嵌入 → 图像KandinskyV22CombinedPipelinepipeline_kandinsky2_2_combined.py文生图一体化Prior Decoder 合并KandinskyV22ControlnetPipelinepipeline_kandinsky2_2_controlnet.pyControlNet 文生图如深度控制KandinskyV22PriorEmb2EmbPipelinepipeline_kandinsky2_2_prior_emb2emb.py图像引导 Prior图生图的嵌入重编含interpolateKandinskyV22Img2ImgPipelinepipeline_kandinsky2_2_img2img.py图生图 DecoderKandinskyV22Img2ImgCombinedPipelinepipeline_kandinsky2_2_combined.py图生图一体化KandinskyV22ControlnetImg2ImgPipelinepipeline_kandinsky2_2_controlnet_img2img.pyControlNet 图生图KandinskyV22InpaintPipelinepipeline_kandinsky2_2_inpainting.py图像修复 DecoderKandinskyV22InpaintCombinedPipelinepipeline_kandinsky2_2_combined.py图像修复一体化统一自动加载AutoPipeline不想手动串联 Prior 与 Decoder 时可以依赖 AutoPipeline 的自动路由。从 auto_pipeline.py 的注册表可以看出文生图自动路由到KandinskyV22CombinedPipeline或 decoder 版KandinskyV22Pipeline图生图自动路由到KandinskyV22Img2ImgCombinedPipeline或KandinskyV22Img2ImgPipeline修复自动路由到KandinskyV22InpaintCombinedPipeline或KandinskyV22InpaintPipeline。源码注释还指出connected pipelines一体化管线只能从 decoder 型 checkpoint 加载例如kandinsky-community/kandinsky-2-2-decoder——它会自动把 Prior 组件一并装配进来。文生图的一体化用法如下出自 Combined 管线 docstringfrom diffusers import AutoPipelineForText2Image import torch pipe AutoPipelineForText2Image.from_pretrained( kandinsky-community/kandinsky-2-2-decoder, torch_dtypetorch.float16 ) pipe.enable_model_cpu_offload() prompt A lion in galaxies, spirals, nebulae, stars, smoke, iridescent, intricate detail, octane render, 8k image pipe(promptprompt, num_inference_steps25).images[0]一体化管线在__init__内部自动构建prior_pipe与decoder_pipe两个子管线见 pipeline_kandinsky2_2_combined.py并额外暴露prior_guidance_scale默认 4.0与prior_num_inference_steps默认 25两个参数分别控制 Prior 阶段的引导强度与步数。其model_cpu_offload_seq prior_text_encoder-prior_image_encoder-unet-movq表明整套管线按顺序卸载到 CPU 以节省显存。组件跨管线复用与调度器调优官方文档特别提醒两点原文档 TIP阅读 调度器指南 学习如何权衡调度器的速度与质量阅读 跨管线复用模型 章节学习如何把相同组件高效加载到多个管线中。由于 Prior 与 Decoder 是解耦的两套组件你可以把同一个KandinskyV22PriorPipeline的结果喂给普通 Decoder、ControlNet Decoder 或修复 Decoder复用一次嵌入计算。四、图生图strength 与时间步截断KandinskyV22Img2ImgPipeline在 Decoder 组件之外还内置了VaeImageProcessorvae_scale_factor取自movq_scale_factorresamplebicubic。其核心参数是strength默认0.3数值越大注入的初始噪声越多输出与输入图的差异越大strength1时等价于完全重绘。底层的时间步截断逻辑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:]即只从第init_timestep步开始去噪实际执行的去噪步数为num_inference_steps - t_start。初始潜变量由movq.encode(image).latent_dist.sample(generator)编码后乘movq.config.scaling_factor得到再叠加噪声。图生图 docstring 示例image pipe( imageinit_image, image_embedsimage_emb, negative_image_embedszero_image_emb, height768, width768, num_inference_steps100, strength0.2, ).images image[0].save(red_frog.png)使用AutoPipelineForImage2Image时同样可以自动装配见 Combined 管线 docstringfrom diffusers import AutoPipelineForImage2Image import torch pipe AutoPipelineForImage2Image.from_pretrained( kandinsky-community/kandinsky-2-2-decoder, torch_dtypetorch.float16 ) pipe.enable_model_cpu_offload() prompt A fantasy landscape, Cinematic lighting negative_prompt low quality, bad quality image pipe(promptprompt, imageoriginal_image, num_inference_steps25).images[0]图像引导的 PriorPriorEmb2EmbKandinskyV22PriorEmb2EmbPipeline是图生图流程中 Prior 阶段的图像嵌入重编版本它同样接受image与strength用输入图的图像嵌入作为先验扩散的起点同样的get_timesteps截断逻辑见 pipeline_kandinsky2_2_prior_emb2emb.py从而让最终生成的图像嵌入既贴近文本又保留输入图的语义。它同样实现了interpolate方法详见第七节。该管线的模块组成与KandinskyV22PriorPipeline完全一致仅在去噪初始点与图像输入上不同。五、图像修复mask 语义与 8 通道拼接KandinskyV22InpaintPipeline支持 PIL 图像或np.ndarray形式的mask_image。mask 语义为黑色像素0保留、白色像素1重绘PIL 图像会被自动转换为单通道灰度。底层流程见 pipeline_kandinsky2_2_inpainting.pyprepare_mask_and_masked_image预处理图像与 maskmask 经F.interpolate缩放到潜空间尺寸masked_image image * mask_image得到掩码图像U-Net 输入为[latent_model_input, masked_image, mask_image]的8 通道拼接每一步用latents mask_image * image (1 - mask_image) * latents保持掩码区域锁定。修复示例mask 为 768×768 的float32数组把猫头上方区域置 1from diffusers import AutoPipelineForInpainting from diffusers.utils import load_image import torch import numpy as np pipe AutoPipelineForInpainting.from_pretrained( kandinsky-community/kandinsky-2-2-decoder-inpaint, torch_dtypetorch.float16 ) pipe.enable_model_cpu_offload() prompt A fantasy landscape, Cinematic lighting negative_prompt low quality, bad quality original_image load_image(path/to/cat.png) mask np.zeros((768, 768), dtypenp.float32) # 把猫头上方的区域掩码掉 mask[:250, 250:-250] 1 image pipe(promptprompt, imageoriginal_image, mask_imagemask, num_inference_steps25).images[0]注意修复管线的_callback_tensor_inputs比 Decoder 管线多了masked_image与mask_image因此步末回调可以观测掩码状态。六、ControlNet深度图控制的文生图KandinskyV22ControlnetPipeline的核心在于新增的hint参数——一个经过预处理的控制条件张量如深度图。官方示例用 transformers 的depth-estimation管线生成深度提示再加载kandinsky-community/kandinsky-2-2-controlnet-depthcheckpoint见 ControlNet docstringimport torch import numpy as np from diffusers import KandinskyV22PriorPipeline, KandinskyV22ControlnetPipeline from transformers import pipeline from diffusers.utils import load_image def make_hint(image, depth_estimator): image depth_estimator(image)[depth] image np.array(image) image image[:, :, None] image np.concatenate([image, image, image], axis2) detected_map torch.from_numpy(image).float() / 255.0 hint detected_map.permute(2, 0, 1) return hint depth_estimator pipeline(depth-estimation) pipe_prior KandinskyV22PriorPipeline.from_pretrained( kandinsky-community/kandinsky-2-2-prior, torch_dtypetorch.float16 ).to(cuda) pipe KandinskyV22ControlnetPipeline.from_pretrained( kandinsky-community/kandinsky-2-2-controlnet-depth, torch_dtypetorch.float16 ).to(cuda) img load_image(path/to/cat.png).resize((768, 768)) hint make_hint(img, depth_estimator).unsqueeze(0).half().to(cuda) prompt A robot, 4k photo negative_prior_prompt lowres, text, error, cropped, worst quality, low quality, jpeg artifacts, ugly, duplicate, morbid, mutilated, out of frame, extra fingers, mutated hands, poorly drawn hands, poorly drawn face, mutation, deformed, blurry, dehydrated, bad anatomy, bad proportions, extra limbs, cloned face, disfigured, gross proportions, malformed limbs, missing arms, missing legs, extra arms, extra legs, fused fingers, too many fingers, long neck, username, watermark, signature generator torch.Generator(devicecuda).manual_seed(43) image_emb, zero_image_emb pipe_prior( promptprompt, negative_promptnegative_prior_prompt, generatorgenerator ).to_tuple() images pipe( image_embedsimage_emb, negative_image_embedszero_image_emb, hinthint, num_inference_steps50, generatorgenerator, height768, width768, ).images images[0].save(robot_cat.png)KandinskyV22ControlnetImg2ImgPipeline则同时接受image、hint与strength可以在既有图像上施加结构控制如保持原图构图并重绘内容其get_timesteps与图生图管线一致。七、嵌入插值interpolate 方法Prior 管线KandinskyV22PriorPipeline与KandinskyV22PriorEmb2EmbPipeline都实现了interpolate方法用于在多个文本提示与参考图像之间做嵌入插值实现风格混合。其签名与要点如下pipe_prior.interpolate( images_and_prompts, # list[str | PIL.Image.Image | torch.Tensor]条件列表 weights, # list[float]与条件一一对应的权重 num_images_per_prompt1, num_inference_steps25, generatorNone, latentsNone, negative_prior_promptNone, negative_prompt, guidance_scale4.0, )底层实现逻辑pipeline_kandinsky2_2_prior.pyimages_and_prompts与weights长度必须相等否则抛出ValueError字符串条件调用self(...)走完整 Prior 扩散得到image_embeds图像条件经image_processor预处理后直接过image_encoder得到图像嵌入每个嵌入乘以其权重后求和torch.cat(image_embeddings).sum(dim0)负向嵌入取自negative_prompt对应的零/负向嵌入。官方插值示例interpolate docstringfrom diffusers import KandinskyV22PriorPipeline, KandinskyV22Pipeline from diffusers.utils import load_image import torch pipe_prior KandinskyV22PriorPipeline.from_pretrained( kandinsky-community/kandinsky-2-2-prior, torch_dtypetorch.float16 ).to(cuda) img1 load_image(path/to/cat.png) img2 load_image(path/to/starry_night.jpeg) images_texts [a cat, img1, img2] weights [0.3, 0.3, 0.4] out pipe_prior.interpolate(images_texts, weights) pipe KandinskyV22Pipeline.from_pretrained( kandinsky-community/kandinsky-2-2-decoder, torch_dtypetorch.float16 ).to(cuda) image pipe( image_embedsout.image_embeds, negative_image_embedsout.negative_image_embeds, height768, width768, num_inference_steps50, ).images[0] image.save(starry_cat.png)调整weights即可连续控制猫 星空的混合比例这是 Kandinsky 2.2 做风格迁移与多条件融合的独特能力。八、关键参数速查以下是各管线__call__的核心参数以当前仓库源码签名为准参数默认值适用管线说明prompt/negative_prompt—Prior / Combined文本提示与负提示支持str或list[str]image_embeds/negative_image_embeds—所有 Decoder 类Prior 输出的图像嵌入num_inference_steps25Prior/ 100Decoder全部去噪步数越多质量越高、速度越慢guidance_scale4.0全部CFG 引导强度 1时启用引导越高越贴合提示prior_guidance_scale/prior_num_inference_steps4.0 / 25Combined 类单独控制 Prior 阶段num_images_per_prompt1全部每个提示生成的图像数generatorNone全部torch.Generator传入后结果可复现latentsNone全部预先生成的噪声潜变量可复用做同种子变体height/width512 / 512Decoder 类输出尺寸会被规整到scale_factor²的整数倍strength0.3图生图 / 修复 / Emb2Emb初始噪声注入比例越大改动越大hint—ControlNet 类控制条件张量如深度图mask_image—修复类掩码黑色保留、白色重绘output_typeptPrior/pilDecoder全部pil/np/ptDecoder 另有latentreturn_dictTrue全部True返回数据类False返回元组关于分辨率还有一个易忽略的细节Decoder 管线会调用downscale_height_and_widthpipeline_kandinsky2_2.py把height/width向上取整到movq_scale_factor²默认 8²64的整数倍避免潜空间尺寸非整数。另外 Decoder 的output_typelatent会直接返回未解码的潜变量适合做二次编辑或调试。九、工程实践建议显存管理Prior 与 Decoder 组件较多优先使用enable_model_cpu_offload()逐模块卸载而非.to(cuda)一体化管线已内置卸载顺序enable_sequential_cpu_offload可进一步降低峰值显存但速度更慢半精度与可复现性官方示例普遍使用torch_dtypetorch.float16配合enable_model_cpu_offload需要复现时固定torch.Generator种子如torch.Generator(devicecuda).manual_seed(43)步末回调Decoder 类管线支持callback_on_step_end与callback_on_step_end_tensor_inputs可观测/修改latents、image_embeds、negative_image_embeds修复管线另有masked_image、mask_image旧式callback/callback_steps参数已被标记弃用deprecate至 1.0.0训练与进阶若需要训练或微调 Kandinsky 2.2 相关模型可参考 examples/kandinsky2_2/text_to_image 下的训练脚本与说明以及 kandinsky2_2 测试目录 中的端到端测试用例它们验证了各管线在真实 checkpoint 上的可用性Checkpoint 组织官方模型权重按任务分布在kandinsky-community系列仓库中如kandinsky-2-2-prior、kandinsky-2-2-decoder、kandinsky-2-2-decoder-inpaint、kandinsky-2-2-controlnet-depth等文生图、图生图、修复均有对应官方 checkpoint。十、小结Kandinsky 2.2 在 Diffusers 中是一套结构清晰、覆盖完整的多阶段扩散模型家族Prior负责把文本/图像语义映射到嵌入空间Decoder含 MoVQ负责生成像素ControlNet组件提供结构化条件控制Combined管线把流程封装为一行调用interpolate提供嵌入级的多条件融合能力。掌握 API 参考文档 与 源码目录 中展示的参数语义与调用链你就能在文生图、图生图、修复与结构控制等场景中自由组合这套管线。【免费下载链接】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），仅供参考
![[特殊字符] Diffusers 官方训练脚本全景指南：从零训练你自己的扩散模型](http://pic.xiahunao.cn/yaotu/[特殊字符] Diffusers 官方训练脚本全景指南：从零训练你自己的扩散模型)
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
