Diffusers documentation

Kandinsky 5.0 图像

Diffusers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Kandinsky 5.0 图像

Kandinsky 5.0 是一个用于视频和图像生成的扩散模型系列。

Kandinsky 5.0 Image Lite 是一个轻量级图像生成模型（6B 参数）。

该模型引入了几项关键创新：

采用 Flow Matching 的 Latent diffusion pipeline，以提升训练稳定性
以 Diffusion Transformer (DiT) 作为主要生成骨干网络，并通过交叉注意力机制与文本嵌入进行交互
使用 Qwen2.5-VL 和 CLIP 进行双重文本编码，以实现全面的文本理解
用于高效图像编码和解码的 Flux VAE

原始代码库可在 kandinskylab/Kandinsky-5 中找到。

在 Hub 上查看 Kandinsky Lab 组织，以获取用于文本到视频生成的官方模型检查点，包括预训练、SFT、无 CFG 和蒸馏变体。

可用模型

Kandinsky 5.0 Image Lite：

model_id	描述	用例
kandinskylab/Kandinsky-5.0-T2I-Lite-sft-Diffusers	6B 图像监督微调模型	最高的生成质量
kandinskylab/Kandinsky-5.0-I2I-Lite-sft-Diffusers	6B 图像编辑监督微调模型	最高的生成质量
kandinskylab/Kandinsky-5.0-T2I-Lite-pretrain-Diffusers	6B 图像基础预训练模型	研究与微调
kandinskylab/Kandinsky-5.0-I2I-Lite-pretrain-Diffusers	6B 图像编辑基础预训练模型	研究与微调

使用示例

基础文本到图像生成

import torch
from diffusers import Kandinsky5T2IPipeline

# Load the pipeline
model_id = "kandinskylab/Kandinsky-5.0-T2I-Lite-sft-Diffusers"
pipe = Kandinsky5T2IPipeline.from_pretrained(model_id)
_ = pipe.to(device='cuda',dtype=torch.bfloat16)  # or "mps", "xpu", "cpu"

# Generate image
prompt = "A fluffy, expressive cat wearing a bright red hat with a soft, slightly textured fabric. The hat should look cozy and well-fitted on the cat’s head. On the front of the hat, add clean, bold white text that reads “SWEET”, clearly visible and neatly centered. Ensure the overall lighting highlights the hat’s color and the cat’s fur details."

output = pipe(
    prompt=prompt,
    negative_prompt="",
    height=1024,
    width=1024,
    num_inference_steps=50,
    guidance_scale=3.5,
).image[0]

基础图像到图像生成

import torch
from diffusers import Kandinsky5I2IPipeline
from diffusers.utils import load_image 
# Load the pipeline
model_id = "kandinskylab/Kandinsky-5.0-I2I-Lite-sft-Diffusers"
pipe = Kandinsky5I2IPipeline.from_pretrained(model_id)

_ = pipe.to(device='cuda',dtype=torch.bfloat16)  # or "mps", "xpu", "cpu"
pipe.enable_model_cpu_offload()                                               # <--- Enable CPU offloading for single GPU inference

# Edit the input image
image = load_image(
    "https://huggingface.co/kandinsky-community/kandinsky-3/resolve/main/assets/title.jpg?download=true"
)

prompt = "Change the background from a winter night scene to a bright summer day. Place the character on a sandy beach with clear blue sky, soft sunlight, and gentle waves in the distance. Replace the winter clothing with a light short-sleeved T-shirt (in soft pastel colors) and casual shorts. Ensure the character’s fur reflects warm daylight instead of cold winter tones. Add small beach details such as seashells, footprints in the sand, and a few scattered beach toys nearby. Keep the oranges in the scene, but place them naturally on the sand."
negative_prompt = ""

output = pipe(
    image=image,
    prompt=prompt,
    negative_prompt=negative_prompt,
    guidance_scale=3.5,
).image[0]

Kandinsky5T2IPipeline

class diffusers.Kandinsky5T2IPipeline

< source >

( transformer: Kandinsky5Transformer3DModelvae: AutoencoderKLtext_encoder: Qwen2_5_VLForConditionalGenerationtokenizer: Qwen2VLProcessortext_encoder_2: CLIPTextModeltokenizer_2: CLIPTokenizerscheduler: FlowMatchEulerDiscreteScheduler )

参数

transformer (Kandinsky5Transformer3DModel) — 用于对编码后的图像潜在变量进行去噪的条件 Transformer。
vae (AutoencoderKL) — 变分自编码器模型 black-forest-labs/FLUX.1-dev (vae)，用于将视频编码和解码为潜在表示。
text_encoder (Qwen2_5_VLForConditionalGeneration) — 冻结的文本编码器 Qwen2.5-VL。
tokenizer（AutoProcessor）—— Qwen2.5-VL 的分词器。
text_encoder_2 (CLIPTextModel) — 冻结的 CLIP，具体为 clip-vit-large-patch14 变体。
tokenizer_2 (CLIPTokenizer) — CLIP 的分词器。
scheduler (FlowMatchEulerDiscreteScheduler) — 用于与 transformer 配合，对编码后的图像潜变量进行去噪的调度器。

使用 Kandinsky 5.0 进行文本到图像生成的 Pipeline。

该模型继承自 DiffusionPipeline。有关为所有 pipeline 实现的通用方法（下载、保存、在特定设备上运行等），请参阅父类文档。

call

< source >

( prompt: str | list[str] = Nonenegative_prompt: str | list[str] | None = Noneheight: int = 1024width: int = 1024num_inference_steps: int = 50guidance_scale: float = 3.5num_images_per_prompt: int | None = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds_qwen: typing.Optional[torch.Tensor] = Noneprompt_embeds_clip: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_qwen: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_clip: typing.Optional[torch.Tensor] = Noneprompt_cu_seqlens: typing.Optional[torch.Tensor] = Nonenegative_prompt_cu_seqlens: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Truecallback_on_step_end: typing.Optional[typing.Callable[[int, int, NoneType], diffusers.callbacks.PipelineCallback | diffusers.callbacks.MultiPipelineCallbacks]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 512 ) → ~KandinskyImagePipelineOutput or tuple

参数

prompt (str 或 list[str]，可选) — 用于引导图像生成的提示词或提示词列表。如果未定义，请改为传入 prompt_embeds。
negative_prompt (str 或 list[str]，可选) — 图像生成过程中需要避免的提示词。如果未定义，请改为传入 negative_prompt_embeds。在未使用引导（guidance_scale < 1）时将被忽略。
height (int，默认为 1024) — 生成图像的高度（以像素为单位）。
width (int，默认为 1024) — 生成图像的宽度（以像素为单位）。
num_inference_steps (int，默认为 50) — 去噪步数。
guidance_scale (float，默认为 5.0) — 无分类器引导中定义的引导尺度。
num_images_per_prompt (int，可选，默认为 1) — 每个提示词生成的图像数量。
generator (torch.Generator 或 list[torch.Generator]，可选) — 用于使生成过程确定性的 torch 生成器。
latents (torch.Tensor, 可选) — 预生成的含噪潜变量。
prompt_embeds_qwen (torch.Tensor, 可选) — 预生成的 Qwen 文本嵌入。
prompt_embeds_clip (torch.Tensor, 可选) — 预生成的 CLIP 文本嵌入。
negative_prompt_embeds_qwen (torch.Tensor, 可选) — 预生成的 Qwen 负向文本嵌入。
negative_prompt_embeds_clip (torch.Tensor, 可选) — 预生成的 CLIP 负向文本嵌入。
prompt_cu_seqlens (torch.Tensor，可选) — 为 Qwen 正向提示词预生成的累积序列长度。
negative_prompt_cu_seqlens (torch.Tensor, 可选) — 为 Qwen 负面提示词预生成的累积序列长度。
output_type (str，可选，默认为 "pil") — 生成图像的输出格式。
return_dict (bool，可选，默认为 True) — 是否返回 KandinskyImagePipelineOutput。
callback_on_step_end (Callable, PipelineCallback, MultiPipelineCallbacks, 可选) — 在每个去噪步骤结束时调用的函数。
callback_on_step_end_tensor_inputs (List, 可选) — callback_on_step_end 函数的张量输入列表。
max_sequence_length (int，默认为 512) — 文本编码的最大序列长度。

返回值

~KandinskyImagePipelineOutput 或 tuple

如果 return_dict 为 True，则返回 KandinskyImagePipelineOutput；否则返回一个 tuple，其中第一个元素是包含生成图像的列表。

用于文本到图像生成的 pipeline 的调用函数。

示例：

>>> import torch
>>> from diffusers import Kandinsky5T2IPipeline

>>> # Available models:
>>> # kandinskylab/Kandinsky-5.0-T2I-Lite-sft-Diffusers
>>> # kandinskylab/Kandinsky-5.0-T2I-Lite-pretrain-Diffusers

>>> model_id = "kandinskylab/Kandinsky-5.0-T2I-Lite-sft-Diffusers"
>>> pipe = Kandinsky5T2IPipeline.from_pretrained(model_id, torch_dtype=torch.bfloat16)
>>> pipe = pipe.to("cuda")

>>> prompt = "A cat and a dog baking a cake together in a kitchen."

>>> output = pipe(
...     prompt=prompt,
...     negative_prompt="",
...     height=1024,
...     width=1024,
...     num_inference_steps=50,
...     guidance_scale=3.5,
... ).frames[0]

check_inputs

< source >

( promptnegative_promptheightwidthprompt_embeds_qwen = Noneprompt_embeds_clip = Nonenegative_prompt_embeds_qwen = Nonenegative_prompt_embeds_clip = Noneprompt_cu_seqlens = Nonenegative_prompt_cu_seqlens = Nonecallback_on_step_end_tensor_inputs = Nonemax_sequence_length = None )

参数

prompt — 输入提示
negative_prompt — 用于引导的负面提示
height — 图像高度
width — 图像宽度
prompt_embeds_qwen — 预计算的 Qwen 提示嵌入
prompt_embeds_clip — 预计算的 CLIP 提示嵌入
negative_prompt_embeds_qwen — 预计算的 Qwen 负提示嵌入
negative_prompt_embeds_clip — 预计算的 CLIP 负提示嵌入
prompt_cu_seqlens — Qwen 正向提示的预计算累积序列长度
negative_prompt_cu_seqlens — Qwen 负面提示的预计算累积序列长度
callback_on_step_end_tensor_inputs — 回调张量输入

引发

ValueError

ValueError — 如果输入无效

验证 pipeline 的输入参数。

encode_prompt

< source >

( prompt: str | list[str]num_images_per_prompt: int = 1max_sequence_length: int = 512device: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = None ) → tuple[torch.Tensor, torch.Tensor, torch.Tensor]

参数

prompt (str 或 list[str]) — 要编码的提示。
num_images_per_prompt (int，可选，默认为 1) — 每个提示词生成的图像数量。
max_sequence_length (int，可选，默认值为 512) — 文本编码的最大序列长度。必须小于 1024
device (torch.device，可选) — Torch 设备。
dtype (torch.dtype，可选) — Torch 数据类型。

返回值

tuple[torch.Tensor, torch.Tensor, torch.Tensor]

形状为 (batch_size * num_images_per_prompt, sequence_length, embedding_dim) 的 Qwen 文本嵌入
形状为 (batch_size * num_images_per_prompt, clip_embedding_dim) 的 CLIP 池化嵌入
Qwen 嵌入的累积序列长度（cu_seqlens），形状为 (batch_size * num_images_per_prompt + 1,)

将单个提示（正向或负向）编码为文本编码器的隐藏状态。

该方法结合了 Qwen2.5-VL 和 CLIP 文本编码器的嵌入，以创建用于图像生成的全面文本表示。

prepare_latents

< source >

( batch_size: intnum_channels_latents: int = 16height: int = 1024width: int = 1024dtype: typing.Optional[torch.dtype] = Nonedevice: typing.Optional[torch.device] = Nonegenerator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = None ) → torch.Tensor

参数

batch_size (int) — 要生成的图像数量
num_channels_latents (int) — 潜在空间中的通道数
height (int) — 生成图像的高度
width (int) — 生成图像的宽度
dtype (torch.dtype) — 潜变量的数据类型
device (torch.device) — 用于创建潜变量的设备
generator (torch.Generator) — 随机数生成器
latents (torch.Tensor) — 要使用的现有潜在变量

返回值

torch.Tensor

准备好的潜在张量

为文本到图像生成准备初始潜在变量。

此方法创建随机噪声潜变量

Kandinsky5I2IPipeline

class diffusers.Kandinsky5I2IPipeline

< source >

参数

transformer (Kandinsky5Transformer3DModel) — 用于对编码后的图像潜在变量进行去噪的条件 Transformer。
vae (AutoencoderKL) — 变分自编码器模型 black-forest-labs/FLUX.1-dev (vae)，用于将视频编码和解码为潜在表示。
text_encoder (Qwen2_5_VLForConditionalGeneration) — 冻结的文本编码器 Qwen2.5-VL。
tokenizer（AutoProcessor）—— Qwen2.5-VL 的分词器。
text_encoder_2 (CLIPTextModel) — 冻结的 CLIP，具体为 clip-vit-large-patch14 变体。
tokenizer_2 (CLIPTokenizer) — CLIP 的分词器。
scheduler (FlowMatchEulerDiscreteScheduler) — 用于与 transformer 配合，对编码后的图像潜变量进行去噪的调度器。

使用 Kandinsky 5.0 进行图像到图像生成的 Pipeline。

该模型继承自 DiffusionPipeline。有关为所有 pipeline 实现的通用方法（下载、保存、在特定设备上运行等），请参阅父类文档。

call

< source >

( image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]prompt: str | list[str] = Nonenegative_prompt: str | list[str] | None = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 50guidance_scale: float = 3.5num_images_per_prompt: int | None = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds_qwen: typing.Optional[torch.Tensor] = Noneprompt_embeds_clip: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_qwen: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_clip: typing.Optional[torch.Tensor] = Noneprompt_cu_seqlens: typing.Optional[torch.Tensor] = Nonenegative_prompt_cu_seqlens: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Truecallback_on_step_end: typing.Optional[typing.Callable[[int, int, NoneType], diffusers.callbacks.PipelineCallback | diffusers.callbacks.MultiPipelineCallbacks]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 1024 ) → ~KandinskyImagePipelineOutput or tuple

参数

image (PipelineImageInput) — 用于条件生成的输入图像。必须为图像、图像列表或 torch.Tensor。
prompt (str 或 list[str]，可选) — 用于引导图像生成的提示词或提示词列表。如果未定义，请改为传入 prompt_embeds。
negative_prompt (str 或 list[str]，可选) — 图像生成过程中需要避免的提示词。如果未定义，请改为传入 negative_prompt_embeds。在未使用引导（guidance_scale < 1）时将被忽略。
height (int) — 生成图像的高度（以像素为单位）。
width (int) — 生成图像的宽度（以像素为单位）。
num_inference_steps (int，默认为 50) — 去噪步数。
guidance_scale (float，默认为 5.0) — 无分类器引导中定义的引导尺度。
num_images_per_prompt (int，可选，默认为 1) — 每个提示词生成的图像数量。
generator (torch.Generator 或 list[torch.Generator]，可选) — 用于使生成过程确定性的 torch 生成器。
latents (torch.Tensor, 可选) — 预生成的含噪潜变量。
prompt_embeds_qwen (torch.Tensor, 可选) — 预生成的 Qwen 文本嵌入。
prompt_embeds_clip (torch.Tensor, 可选) — 预生成的 CLIP 文本嵌入。
negative_prompt_embeds_qwen (torch.Tensor, 可选) — 预生成的 Qwen 负向文本嵌入。
negative_prompt_embeds_clip (torch.Tensor, 可选) — 预生成的 CLIP 负向文本嵌入。
prompt_cu_seqlens (torch.Tensor，可选) — 为 Qwen 正向提示词预生成的累积序列长度。
negative_prompt_cu_seqlens (torch.Tensor, 可选) — 为 Qwen 负面提示词预生成的累积序列长度。
output_type (str，可选，默认为 "pil") — 生成图像的输出格式。
return_dict (bool，可选，默认为 True) — 是否返回 KandinskyImagePipelineOutput。
callback_on_step_end (Callable, PipelineCallback, MultiPipelineCallbacks, 可选) — 在每个去噪步骤结束时调用的函数。
callback_on_step_end_tensor_inputs (List, 可选) — callback_on_step_end 函数的张量输入列表。
max_sequence_length (int，默认为 1024) — 用于文本和图像 qwen 编码的最大序列长度。必须小于 1024

返回值

~KandinskyImagePipelineOutput 或 tuple

如果 return_dict 为 True，则返回 KandinskyImagePipelineOutput；否则返回一个 tuple，其中第一个元素是包含生成图像的列表。

用于图像到图像生成的 pipeline 的调用函数。

示例：

>>> import torch
>>> from diffusers import Kandinsky5I2IPipeline

>>> # Available models:
>>> # kandinskylab/Kandinsky-5.0-I2I-Lite-sft-Diffusers
>>> # kandinskylab/Kandinsky-5.0-I2I-Lite-pretrain-Diffusers

>>> model_id = "kandinskylab/Kandinsky-5.0-I2I-Lite-sft-Diffusers"
>>> pipe = Kandinsky5I2IPipeline.from_pretrained(model_id, torch_dtype=torch.bfloat16)
>>> pipe = pipe.to("cuda")

>>> prompt = "A cat and a dog baking a cake together in a kitchen."

>>> output = pipe(
...     prompt=prompt,
...     negative_prompt="",
...     height=1024,
...     width=1024,
...     num_inference_steps=50,
...     guidance_scale=3.5,
... ).frames[0]

check_inputs

< source >

( promptnegative_promptimageheightwidthprompt_embeds_qwen = Noneprompt_embeds_clip = Nonenegative_prompt_embeds_qwen = Nonenegative_prompt_embeds_clip = Noneprompt_cu_seqlens = Nonenegative_prompt_cu_seqlens = Nonecallback_on_step_end_tensor_inputs = Nonemax_sequence_length = None )

参数

prompt — 输入提示
negative_prompt — 用于引导的负面提示
image — 用于条件控制的输入图像
height — 图像高度
width — 图像宽度
prompt_embeds_qwen — 预计算的 Qwen 提示嵌入
prompt_embeds_clip — 预计算的 CLIP 提示嵌入
negative_prompt_embeds_qwen — 预计算的 Qwen 负提示嵌入
negative_prompt_embeds_clip — 预计算的 CLIP 负提示嵌入
prompt_cu_seqlens — Qwen 正向提示的预计算累积序列长度
negative_prompt_cu_seqlens — Qwen 负面提示的预计算累积序列长度
callback_on_step_end_tensor_inputs — 回调张量输入

引发

ValueError

ValueError — 如果输入无效

验证 pipeline 的输入参数。

encode_prompt

< source >

( prompt: str | list[str]image: Tensornum_images_per_prompt: int = 1max_sequence_length: int = 1024device: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = None ) → tuple[torch.Tensor, torch.Tensor, torch.Tensor]

参数

prompt (str 或 list[str]) — 要编码的提示。
num_images_per_prompt (int，可选，默认为 1) — 每个提示词生成的图像数量。
max_sequence_length (int，可选，默认值为 1024) — 文本编码的最大序列长度。必须小于 1024
device (torch.device，可选) — Torch 设备。
dtype (torch.dtype，可选) — Torch 数据类型。

返回值

tuple[torch.Tensor, torch.Tensor, torch.Tensor]

形状为 (batch_size * num_images_per_prompt, sequence_length, embedding_dim) 的 Qwen 文本嵌入
形状为 (batch_size * num_images_per_prompt, clip_embedding_dim) 的 CLIP 池化嵌入
Qwen 嵌入的累积序列长度（cu_seqlens），形状为 (batch_size * num_images_per_prompt + 1,)

将单个提示（正向或负向）编码为文本编码器的隐藏状态。

该方法结合了 Qwen2.5-VL 和 CLIP 文本编码器的嵌入，以创建用于图像生成的全面文本表示。

prepare_latents

< source >

( image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]batch_size: intnum_channels_latents: int = 16height: int = 1024width: int = 1024dtype: typing.Optional[torch.dtype] = Nonedevice: typing.Optional[torch.device] = Nonegenerator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = None ) → torch.Tensor

参数

image (PipelineImageInput) — 用于条件生成的输入图像
batch_size (int) — 要生成的图像数量
num_channels_latents (int) — 潜在空间中的通道数
height (int) — 生成图像的高度
width (int) — 生成图像的宽度
dtype (torch.dtype) — 潜变量的数据类型
device (torch.device) — 用于创建潜变量的设备
generator (torch.Generator) — 随机数生成器
latents (torch.Tensor) — 要使用的现有潜在变量

返回值

torch.Tensor

包含编码图像的预准备潜在张量

为图像到图像生成准备初始潜在变量。

此方法会创建带有编码图像的随机噪声潜在变量，

引用

@misc{kandinsky2025,
    author = {Alexander Belykh and Alexander Varlamov and Alexey Letunovskiy and Anastasia Aliaskina and Anastasia Maltseva and Anastasiia Kargapoltseva and Andrey Shutkin and Anna Averchenkova and Anna Dmitrienko and Bulat Akhmatov and Denis Dimitrov and Denis Koposov and Denis Parkhomenko and Dmitrii and Ilya Vasiliev and Ivan Kirillov and Julia Agafonova and Kirill Chernyshev and Kormilitsyn Semen and Lev Novitskiy and Maria Kovaleva and Mikhail Mamaev and Mikhailov and Nikita Kiselev and Nikita Osterov and Nikolai Gerasimenko and Nikolai Vaulin and Olga Kim and Olga Vdovchenko and Polina Gavrilova and Polina Mikhailova and Tatiana Nikulina and Viacheslav Vasilev and Vladimir Arkhipkin and Vladimir Korviakov and Vladimir Polovnikov and Yury Kolabushin},
    title = {Kandinsky 5.0: A family of diffusion models for Video & Image generation},
    howpublished = {\url{https://github.com/kandinskylab/Kandinsky-5}},
    year = 2025
}

Update on GitHub

←Kandinsky 3 Kolors→

Diffusers

Kandinsky 5.0 图像

可用模型

使用示例

基础文本到图像生成

基础图像到图像生成

Kandinsky5T2IPipeline

class diffusers.Kandinsky5T2IPipeline

__call__

check_inputs

encode_prompt

prepare_latents

Kandinsky5I2IPipeline

class diffusers.Kandinsky5I2IPipeline

__call__

check_inputs

encode_prompt

prepare_latents

引用

call

call