Hugging Face's logo

Diffusers documentation

QwenImage

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

QwenImage

LoRA

来自 Qwen 团队的 Qwen-Image 是 Qwen 系列中的图像生成基础模型，在复杂文本渲染和精确图像编辑方面取得了显著进展。实验表明，该模型在图像生成和编辑方面均展现出强大的通用能力，在文本渲染方面表现尤为出色，尤其是在中文场景下。

Qwen-Image 提供以下变体：

模型类型模型 ID
Qwen-ImageQwen/Qwen-Image
Qwen-Image-EditQwen/Qwen-Image-Edit
Qwen-Image-Edit PlusQwen/Qwen-Image-Edit-2509

请参阅 缓存 指南，通过存储和复用中间输出来加速推理。

使用 LoRA 实现更快的推理

使用来自 lightx2v/Qwen-Image-Lightning 的 LoRA 来减少步数，从而加速推理。请参考以下代码片段：

Code 
from diffusers import DiffusionPipeline, FlowMatchEulerDiscreteScheduler
import torch 
import math

ckpt_id = "Qwen/Qwen-Image"

# From
# https://github.com/ModelTC/Qwen-Image-Lightning/blob/342260e8f5468d2f24d084ce04f55e101007118b/generate_with_diffusers.py#L82C9-L97C10
scheduler_config = {
    "base_image_seq_len": 256,
    "base_shift": math.log(3),  # We use shift=3 in distillation
    "invert_sigmas": False,
    "max_image_seq_len": 8192,
    "max_shift": math.log(3),  # We use shift=3 in distillation
    "num_train_timesteps": 1000,
    "shift": 1.0,
    "shift_terminal": None,  # set shift_terminal to None
    "stochastic_sampling": False,
    "time_shift_type": "exponential",
    "use_beta_sigmas": False,
    "use_dynamic_shifting": True,
    "use_exponential_sigmas": False,
    "use_karras_sigmas": False,
}
scheduler = FlowMatchEulerDiscreteScheduler.from_config(scheduler_config)
pipe = DiffusionPipeline.from_pretrained(
    ckpt_id, scheduler=scheduler, dtype=torch.bfloat16
).to("cuda")  # or "mps", "xpu", "cpu"
pipe.load_lora_weights(
    "lightx2v/Qwen-Image-Lightning", weight_name="Qwen-Image-Lightning-8steps-V1.0.safetensors"
)

prompt = "a tiny astronaut hatching from an egg on the moon, Ultra HD, 4K, cinematic composition."
negative_prompt = " "
image = pipe(
    prompt=prompt,
    negative_prompt=negative_prompt,
    width=1024,
    height=1024,
    num_inference_steps=8,
    true_cfg_scale=1.0,
    generator=torch.manual_seed(0),
).images[0]
image.save("qwen_fewsteps.png")

管道中的 guidance_scale 参数旨在为未来可能出现的 guidance-distilled 模型提供支持。请注意，向管道传入 guidance_scale 是无效的。若要启用 classifier-free guidance，请传入 true_cfg_scale 和 negative_prompt（即使是像 ” ” 这样的空 negative prompt 也应能启用 classifier-free guidance 计算）。

使用 QwenImageEditPlusPipeline 进行多图像参考

使用 QwenImageEditPlusPipeline 时，可以提供多张图片作为输入参考。

import torch
from PIL import Image
from diffusers import QwenImageEditPlusPipeline
from diffusers.utils import load_image

pipe = QwenImageEditPlusPipeline.from_pretrained(
    "Qwen/Qwen-Image-Edit-2509", dtype=torch.bfloat16
).to("cuda")  # or "mps", "xpu", "cpu"

image_1 = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/grumpy.jpg")
image_2 = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/peng.png")
image = pipe(
    image=[image_1, image_2],
    prompt='''put the penguin and the cat at a game show called "Qwen Edit Plus Games"''',
    num_inference_steps=50
).images[0]

性能

torch.compile

在 transformer 上使用 torch.compile 可提供约 2.4 倍的加速（A100 80GB：4.70s → 1.93s）：

import torch
from diffusers import QwenImagePipeline

pipe = QwenImagePipeline.from_pretrained("Qwen/Qwen-Image", dtype=torch.bfloat16).to("cuda")  # or "mps", "xpu", "cpu"
pipe.transformer = torch.compile(pipe.transformer)

# First call triggers compilation (~7s overhead)
# Subsequent calls run at ~2.4x faster
image = pipe("a cat", num_inference_steps=50).images[0]

使用变长提示词进行批量推理

在使用无分类器引导（CFG）处理不同长度的提示时，流水线通过注意力掩码正确地进行填充处理。这确保了填充标记不会影响生成的输出。

# CFG with different prompt lengths works correctly
image = pipe(
    prompt="A cat",
    negative_prompt="blurry, low quality, distorted",
    true_cfg_scale=3.5,
    num_inference_steps=50,
).images[0]

有关详细的基准测试脚本和结果，请参阅 此 gist。

QwenImagePipeline

类 diffusers.QwenImagePipeline

< >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLQwenImagetext_encoder: Qwen2_5_VLForConditionalGenerationtokenizer: Qwen2Tokenizertransformer: QwenImageTransformer2DModel )

参数

用于文本到图像生成的 QwenImage 流水线。

__call__

< >

( prompt: str | list[str] = Nonenegative_prompt: str | list[str] = Nonetrue_cfg_scale: float = 4.0height: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 50sigmas: list[float] | None = Noneguidance_scale: float | None = Nonenum_images_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_mask: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']max_sequence_length: int = 512 ) → ~pipelines.qwenimage.QwenImagePipelineOutput or tuple

参数

  • prompt (str 或 list[str]，可选) — 用于引导图像生成的提示词或提示词列表。如果未定义，则必须改为传入 prompt_embeds。
  • negative_prompt (str 或 list[str]，可选) — 用于不引导图像生成的提示词。如果未定义，则必须传入 negative_prompt_embeds。当不使用引导时会被忽略（即当 true_cfg_scale 不大于 1 时会被忽略）。
  • true_cfg_scale (float，可选，默认值为 1.0) — Classifier-Free Diffusion Guidance 中定义的引导尺度。true_cfg_scale 定义为 Imagen Paper 中公式 2 的 w。通过设置 true_cfg_scale > 1 并提供 negative_prompt 来启用无分类器引导。较高的引导尺度会促使生成与文本 prompt 紧密关联的图像，通常以牺牲图像质量为代价。
  • height (int，可选，默认为 self.unet.config.sample_size * self.vae_scale_factor) — 生成图像的高度（以像素为单位）。默认设置为 1024，以获得最佳效果。
  • width (int，可选，默认为 self.unet.config.sample_size * self.vae_scale_factor) — 生成图像的宽度（以像素为单位）。默认设置为 1024，以获得最佳效果。
  • num_inference_steps (int，可选，默认为 50) — 去噪步数。更多的去噪步数通常能生成更高质量的图像，但代价是推理速度变慢。
  • sigmas (list[float]，可选) — 用于在支持 sigmas 参数的调度器的 set_timesteps 方法中，为去噪过程指定自定义的 sigmas。如果未定义，则使用传入 num_inference_steps 时的默认行为。
  • guidance_scale (float, 可选，默认为 None) — 用于 guidance 蒸馏模型的 guidance scale 值。与传统的 classifier-free guidance 不同，后者在推理阶段通过噪声预测重缩放来应用 guidance scale，而 guidance 蒸馏模型在 forward pass 期间直接将 guidance scale 作为输入参数。通过设置 guidance_scale > 1 来启用 guidance scale。较高的 guidance scale 会促使生成与文本 prompt 紧密关联的图像，通常以牺牲图像质量为代价。流水线中的此参数旨在支持未来出现的 guidance 蒸馏模型。在未使用 guidance 蒸馏模型时，该参数将被忽略。若要启用传统的 classifier-free guidance，请传入 true_cfg_scale > 1.0 和 negative_prompt（即使是像 ” ” 这样的空 negative prompt 也应能启用 classifier-free guidance 计算）。
  • num_images_per_prompt (int，可选，默认为 1) — 每个提示词生成的图像数量。
  • generator (torch.Generator 或 list[torch.Generator]，可选) — 一个或一组 torch 生成器，用于使生成过程具有确定性。
  • latents (torch.Tensor, 可选) — 预先生成的噪声潜变量，从高斯分布中采样得到，用作图像生成的输入。可用于使用不同的提示词对同一生成过程进行微调。如果未提供，将通过使用提供的随机generator进行采样来生成一个潜变量张量。
  • prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如 提示词加权。如果未提供，文本嵌入将从 prompt 输入参数生成。
  • prompt_embeds_mask (torch.Tensor, 可选) — prompt_embeds 的注意力掩码。
  • negative_prompt_embeds (torch.Tensor, 可选) — 预生成的负向文本嵌入。可用于轻松调整文本输入，例如提示词加权。如果未提供，negative_prompt_embeds 将从 negative_prompt 输入参数生成。
  • negative_prompt_embeds_mask (torch.Tensor, 可选) — negative_prompt_embeds 的注意力掩码。
  • output_type (str，可选，默认为 "pil") — 生成图像的输出格式。可选值为 PIL：PIL.Image.Image 或 np.array。
  • return_dict (bool，可选，默认为 True) — 是否返回 ~pipelines.qwenimage.QwenImagePipelineOutput 而不是普通元组。
  • attention_kwargs (dict, 可选) — 一个 kwargs 字典，如果指定，将传递给 diffusers.models.attention_processor 中定义的 AttentionProcessor，该处理器在 self.processor 下定义。
  • callback_on_step_end (Callable, 可选) — 一个在推理过程中每个去噪步骤结束时调用的函数。该函数以以下参数被调用：callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)。callback_kwargs 将包含由 callback_on_step_end_tensor_inputs 指定的所有张量列表。
  • callback_on_step_end_tensor_inputs (list，可选) — callback_on_step_end 函数的张量输入列表。列表中指定的张量将作为 callback_kwargs 参数传递。您只能包含流水线类 ._callback_tensor_inputs 属性中列出的变量。
  • max_sequence_length（int，默认为 512）— 与 prompt 配合使用的最大序列长度。

返回值

~pipelines.qwenimage.QwenImagePipelineOutput 或 tuple

如果 return_dict 为 True，则返回 ~pipelines.qwenimage.QwenImagePipelineOutput，否则返回 tuple。当返回元组时，第一个元素是一个包含生成图像的列表。

调用生成 pipeline 时调用的函数。

示例：

>>> import torch
>>> from diffusers import QwenImagePipeline

>>> pipe = QwenImagePipeline.from_pretrained("Qwen/Qwen-Image", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")
>>> prompt = "A cat holding a sign that says hello world"
>>> # Depending on the variant being used, the pipeline call will slightly vary.
>>> # Refer to the pipeline documentation for more details.
>>> image = pipe(prompt, num_inference_steps=50).images[0]
>>> image.save("qwenimage.png")

encode_prompt

< >

( prompt: str | list[str]device: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024 )

参数

  • prompt (str 或 list[str]，可选) — 要编码的提示
  • device — (torch.device)： torch 设备
  • num_images_per_prompt (int) — 每个提示词应生成的图像数量
  • prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如 提示词加权。如果未提供，文本嵌入将从 prompt 输入参数生成。

QwenImageImg2ImgPipeline

class diffusers.QwenImageImg2ImgPipeline

< >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLQwenImagetext_encoder: Qwen2_5_VLForConditionalGenerationtokenizer: Qwen2Tokenizertransformer: QwenImageTransformer2DModel )

参数

用于文本到图像生成的 QwenImage 流水线。

__call__

< >

( prompt: str | list[str] = Nonenegative_prompt: str | list[str] = Nonetrue_cfg_scale: float = 4.0image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Noneheight: int | None = Nonewidth: int | None = Nonestrength: float = 0.6num_inference_steps: int = 50sigmas: list[float] | None = Noneguidance_scale: float | None = Nonenum_images_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_mask: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']max_sequence_length: int = 512 ) → ~pipelines.qwenimage.QwenImagePipelineOutput or tuple

参数

  • prompt (str 或 list[str]，可选) — 用于引导图像生成的提示词或提示词列表。如果未定义，则必须改为传入 prompt_embeds。
  • negative_prompt (str 或 list[str]，可选) — 用于不引导图像生成的提示词。如果未定义，则必须传入 negative_prompt_embeds。当不使用引导时会被忽略（即当 true_cfg_scale 不大于 1 时会被忽略）。
  • image (torch.Tensor、PIL.Image.Image、np.ndarray、list[torch.Tensor]、list[PIL.Image.Image] 或 list[np.ndarray]) — Image、numpy 数组或张量，表示用作起点的图像批次。对于 numpy 数组和 PyTorch 张量，预期的取值范围为 [0, 1]。如果是张量或张量列表，预期的形状应为 (B, C, H, W) 或 (C, H, W)。如果是 numpy 数组或数组列表，预期的形状应为 (B, H, W, C) 或 (H, W, C)。它也可以接受图像潜变量作为 image，但如果直接传入潜变量，则不会再次进行编码。
  • true_cfg_scale (float，可选，默认值为 1.0) — Classifier-Free Diffusion Guidance 中定义的引导尺度。true_cfg_scale 定义为 Imagen Paper 中公式 2 的 w。通过设置 true_cfg_scale > 1 并提供 negative_prompt 来启用无分类器引导。较高的引导尺度会促使生成与文本 prompt 紧密关联的图像，通常以牺牲图像质量为代价。
  • height (int，可选，默认为 self.unet.config.sample_size * self.vae_scale_factor) — 生成图像的高度（以像素为单位）。默认设置为 1024，以获得最佳效果。
  • width (int，可选，默认为 self.unet.config.sample_size * self.vae_scale_factor) — 生成图像的宽度（以像素为单位）。默认设置为 1024，以获得最佳效果。
  • strength (float, 可选，默认为 1.0) — 指示对参考 image 进行变换的程度。取值必须在 0 到 1 之间。image 用作起始点，strength 越高，添加的噪声越多。去噪步数取决于初始添加的噪声量。当 strength 为 1 时，添加的噪声达到最大值，去噪过程将运行 num_inference_steps 中指定的完整迭代次数。值为 1 时，基本上会忽略 image。
  • num_inference_steps (int，可选，默认为 50) — 去噪步数。更多的去噪步数通常能生成更高质量的图像，但代价是推理速度变慢。
  • sigmas (list[float]，可选) — 用于在支持 sigmas 参数的调度器的 set_timesteps 方法中，为去噪过程指定自定义的 sigmas。如果未定义，则使用传入 num_inference_steps 时的默认行为。
  • guidance_scale (float, 可选，默认为 None) — 用于 guidance 蒸馏模型的 guidance scale 值。与传统的 classifier-free guidance 不同，后者在推理阶段通过噪声预测重缩放来应用 guidance scale，而 guidance 蒸馏模型在 forward pass 期间直接将 guidance scale 作为输入参数。通过设置 guidance_scale > 1 来启用 guidance scale。较高的 guidance scale 会促使生成与文本 prompt 紧密关联的图像，通常以牺牲图像质量为代价。流水线中的此参数旨在支持未来出现的 guidance 蒸馏模型。在未使用 guidance 蒸馏模型时，该参数将被忽略。若要启用传统的 classifier-free guidance，请传入 true_cfg_scale > 1.0 和 negative_prompt（即使是像 ” ” 这样的空 negative prompt 也应能启用 classifier-free guidance 计算）。
  • num_images_per_prompt (int，可选，默认为 1) — 每个提示词生成的图像数量。
  • generator (torch.Generator 或 list[torch.Generator]，可选) — 一个或一组 torch 生成器，用于使生成过程具有确定性。
  • latents (torch.Tensor, 可选) — 预先生成的噪声潜变量，从高斯分布中采样得到，用作图像生成的输入。可用于使用不同的提示词对同一生成过程进行微调。如果未提供，将通过使用提供的随机generator进行采样来生成一个潜变量张量。
  • prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如 提示词加权。如果未提供，文本嵌入将从 prompt 输入参数生成。
  • prompt_embeds_mask (torch.Tensor, 可选) — prompt_embeds 的注意力掩码。
  • negative_prompt_embeds (torch.Tensor, 可选) — 预生成的负向文本嵌入。可用于轻松调整文本输入，例如提示词加权。如果未提供，negative_prompt_embeds 将从 negative_prompt 输入参数生成。
  • negative_prompt_embeds_mask (torch.Tensor, 可选) — negative_prompt_embeds 的注意力掩码。
  • output_type (str，可选，默认为 "pil") — 生成图像的输出格式。可选值为 PIL：PIL.Image.Image 或 np.array。
  • return_dict (bool，可选，默认为 True) — 是否返回 ~pipelines.qwenimage.QwenImagePipelineOutput 而不是普通元组。
  • attention_kwargs (dict, 可选) — 一个 kwargs 字典，如果指定，将传递给 diffusers.models.attention_processor 中定义的 AttentionProcessor，该处理器在 self.processor 下定义。
  • callback_on_step_end (Callable, 可选) — 一个在推理过程中每个去噪步骤结束时调用的函数。该函数以以下参数被调用：callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)。callback_kwargs 将包含由 callback_on_step_end_tensor_inputs 指定的所有张量列表。
  • callback_on_step_end_tensor_inputs (list，可选) — callback_on_step_end 函数的张量输入列表。列表中指定的张量将作为 callback_kwargs 参数传递。您只能包含流水线类 ._callback_tensor_inputs 属性中列出的变量。
  • max_sequence_length（int，默认为 512）— 与 prompt 配合使用的最大序列长度。

返回值

~pipelines.qwenimage.QwenImagePipelineOutput 或 tuple

如果 return_dict 为 True，则返回 ~pipelines.qwenimage.QwenImagePipelineOutput，否则返回 tuple。当返回元组时，第一个元素是一个包含生成图像的列表。

调用生成 pipeline 时调用的函数。

示例：

>>> import torch
>>> from diffusers import QwenImageImg2ImgPipeline
>>> from diffusers.utils import load_image

>>> pipe = QwenImageImg2ImgPipeline.from_pretrained("Qwen/Qwen-Image", torch_dtype=torch.bfloat16)
>>> pipe = pipe.to("cuda")
>>> url = "https://raw.githubusercontent.com/CompVis/stable-diffusion/main/assets/stable-samples/img2img/sketch-mountains-input.jpg"
>>> init_image = load_image(url).resize((1024, 1024))
>>> prompt = "cat wizard, gandalf, lord of the rings, detailed, fantasy, cute, adorable, Pixar, Disney"
>>> images = pipe(prompt=prompt, negative_prompt=" ", image=init_image, strength=0.95).images[0]
>>> images.save("qwenimage_img2img.png")

encode_prompt

< >

( prompt: str | list[str]device: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024 )

参数

  • prompt (str 或 list[str]，可选) — 要编码的提示
  • device — (torch.device)： torch 设备
  • num_images_per_prompt (int) — 每个提示词应生成的图像数量
  • prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如 提示词加权。如果未提供，文本嵌入将从 prompt 输入参数生成。

QwenImageInpaintPipeline

类 diffusers.QwenImageInpaintPipeline

< >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLQwenImagetext_encoder: Qwen2_5_VLForConditionalGenerationtokenizer: Qwen2Tokenizertransformer: QwenImageTransformer2DModel )

参数

用于文本到图像生成的 QwenImage 流水线。

__call__

< >

( prompt: str | list[str] = Nonenegative_prompt: str | list[str] = Nonetrue_cfg_scale: float = 4.0image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Nonemask_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Nonemasked_image_latents: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Noneheight: int | None = Nonewidth: int | None = Nonepadding_mask_crop: int | None = Nonestrength: float = 0.6num_inference_steps: int = 50sigmas: list[float] | None = Noneguidance_scale: float | None = Nonenum_images_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_mask: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']max_sequence_length: int = 512 ) → ~pipelines.qwenimage.QwenImagePipelineOutput or tuple

参数

  • prompt (str 或 list[str]，可选) — 用于引导图像生成的提示词或提示词列表。如果未定义，则必须改为传入 prompt_embeds。
  • negative_prompt (str 或 list[str]，可选) — 用于不引导图像生成的提示词。如果未定义，则必须传入 negative_prompt_embeds。当不使用引导时会被忽略（即当 true_cfg_scale 不大于 1 时会被忽略）。
  • image (torch.Tensor、PIL.Image.Image、np.ndarray、list[torch.Tensor]、list[PIL.Image.Image] 或 list[np.ndarray]) — Image、numpy 数组或张量，表示用作起点的图像批次。对于 numpy 数组和 PyTorch 张量，预期的取值范围为 [0, 1]。如果是张量或张量列表，预期的形状应为 (B, C, H, W) 或 (C, H, W)。如果是 numpy 数组或数组列表，预期的形状应为 (B, H, W, C) 或 (H, W, C)。它也可以接受图像潜变量作为 image，但如果直接传入潜变量，则不会再次进行编码。
  • true_cfg_scale (float，可选，默认值为 1.0) — Classifier-Free Diffusion Guidance 中定义的引导尺度。true_cfg_scale 定义为 Imagen Paper 中公式 2 的 w。通过设置 true_cfg_scale > 1 并提供 negative_prompt 来启用无分类器引导。较高的引导尺度会促使生成与文本 prompt 紧密关联的图像，通常以牺牲图像质量为代价。
  • mask_image (torch.Tensor、PIL.Image.Image、np.ndarray、list[torch.Tensor]、list[PIL.Image.Image] 或 list[np.ndarray]) — Image、numpy 数组或张量，表示要用于遮罩 image 的图像批次。遮罩中的白色像素将被重绘，而黑色像素将保留。如果 mask_image 是 PIL 图像，则在使用前会将其转换为单通道（亮度）。如果它是 numpy 数组或 PyTorch 张量，则应包含一个颜色通道（L）而不是三个，因此 PyTorch 张量的预期形状为 (B, 1, H, W)、(B, H, W)、(1, H, W) 或 (H, W)。而 numpy 数组的预期形状为 (B, H, W, 1)、(B, H, W)、(H, W, 1) 或 (H, W)。
  • masked_image_latents (torch.Tensor, list[torch.Tensor]) — Tensor，表示用于对 VAE 生成的 image 进行掩码处理的图像批次。如果未提供，掩码潜变量张量将由 mask_image 生成。
  • height (int，可选，默认为 self.unet.config.sample_size * self.vae_scale_factor) — 生成图像的高度（以像素为单位）。默认设置为 1024，以获得最佳效果。
  • width (int，可选，默认为 self.unet.config.sample_size * self.vae_scale_factor) — 生成图像的宽度（以像素为单位）。默认设置为 1024，以获得最佳效果。
  • padding_mask_crop (int, 可选，默认为 None) — 应用于图像和掩码的裁剪边距大小。如果为 None，则不对 image 和 mask_image 进行裁剪。如果 padding_mask_crop 不为 None，则会先找到一个与图像具有相同宽高比且包含所有掩码区域的矩形区域，然后基于 padding_mask_crop 扩展该区域。随后，在调整大小以匹配原始图像尺寸用于修复之前，会根据扩展后的区域对图像和 mask_image 进行裁剪。当掩码区域较小而图像较大，且包含与修复无关的信息（例如背景）时，此功能非常有用。
  • strength (float, 可选，默认为 1.0) — 指示对参考 image 进行变换的程度。取值必须在 0 到 1 之间。image 用作起始点，strength 越高，添加的噪声越多。去噪步数取决于初始添加的噪声量。当 strength 为 1 时，添加的噪声达到最大值，去噪过程将运行 num_inference_steps 中指定的完整迭代次数。值为 1 时，基本上会忽略 image。
  • num_inference_steps (int，可选，默认为 50) — 去噪步数。更多的去噪步数通常能生成更高质量的图像，但代价是推理速度变慢。
  • sigmas (list[float]，可选) — 用于在支持 sigmas 参数的调度器的 set_timesteps 方法中，为去噪过程指定自定义的 sigmas。如果未定义，则使用传入 num_inference_steps 时的默认行为。
  • guidance_scale (float, 可选，默认为 None) — 用于 guidance 蒸馏模型的 guidance scale 值。与传统的 classifier-free guidance 不同，后者在推理阶段通过噪声预测重缩放来应用 guidance scale，而 guidance 蒸馏模型在 forward pass 期间直接将 guidance scale 作为输入参数。通过设置 guidance_scale > 1 来启用 guidance scale。较高的 guidance scale 会促使生成与文本 prompt 紧密关联的图像，通常以牺牲图像质量为代价。流水线中的此参数旨在支持未来出现的 guidance 蒸馏模型。在未使用 guidance 蒸馏模型时，该参数将被忽略。若要启用传统的 classifier-free guidance，请传入 true_cfg_scale > 1.0 和 negative_prompt（即使是像 ” ” 这样的空 negative prompt 也应能启用 classifier-free guidance 计算）。
  • num_images_per_prompt (int，可选，默认为 1) — 每个提示词生成的图像数量。
  • generator (torch.Generator 或 list[torch.Generator]，可选) — 一个或一组 torch 生成器，用于使生成过程具有确定性。
  • latents (torch.Tensor, 可选) — 预先生成的噪声潜变量，从高斯分布中采样得到，用作图像生成的输入。可用于使用不同的提示词对同一生成过程进行微调。如果未提供，将通过使用提供的随机generator进行采样来生成一个潜变量张量。
  • prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如 提示词加权。如果未提供，文本嵌入将从 prompt 输入参数生成。
  • prompt_embeds_mask (torch.Tensor, 可选) — prompt_embeds 的注意力掩码。
  • negative_prompt_embeds (torch.Tensor, 可选) — 预生成的负向文本嵌入。可用于轻松调整文本输入，例如提示词加权。如果未提供，negative_prompt_embeds 将从 negative_prompt 输入参数生成。
  • negative_prompt_embeds_mask (torch.Tensor, 可选) — negative_prompt_embeds 的注意力掩码。
  • output_type (str，可选，默认为 "pil") — 生成图像的输出格式。可选值为 PIL：PIL.Image.Image 或 np.array。
  • return_dict (bool，可选，默认为 True) — 是否返回 ~pipelines.qwenimage.QwenImagePipelineOutput 而不是普通元组。
  • attention_kwargs (dict, 可选) — 一个 kwargs 字典，如果指定，将传递给 diffusers.models.attention_processor 中定义的 AttentionProcessor，该处理器在 self.processor 下定义。
  • callback_on_step_end (Callable, 可选) — 一个在推理过程中每个去噪步骤结束时调用的函数。该函数以以下参数被调用：callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)。callback_kwargs 将包含由 callback_on_step_end_tensor_inputs 指定的所有张量列表。
  • callback_on_step_end_tensor_inputs (list，可选) — callback_on_step_end 函数的张量输入列表。列表中指定的张量将作为 callback_kwargs 参数传递。您只能包含流水线类 ._callback_tensor_inputs 属性中列出的变量。
  • max_sequence_length（int，默认为 512）— 与 prompt 配合使用的最大序列长度。

返回值

~pipelines.qwenimage.QwenImagePipelineOutput 或 tuple

如果 return_dict 为 True，则返回 ~pipelines.qwenimage.QwenImagePipelineOutput，否则返回 tuple。当返回元组时，第一个元素是一个包含生成图像的列表。

调用生成 pipeline 时调用的函数。

示例：

>>> import torch
>>> from diffusers import QwenImageInpaintPipeline
>>> from diffusers.utils import load_image

>>> pipe = QwenImageInpaintPipeline.from_pretrained("Qwen/Qwen-Image", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")
>>> prompt = "Face of a yellow cat, high resolution, sitting on a park bench"
>>> img_url = "https://raw.githubusercontent.com/CompVis/latent-diffusion/main/data/inpainting_examples/overture-creations-5sI6fQgYIuo.png"
>>> mask_url = "https://raw.githubusercontent.com/CompVis/latent-diffusion/main/data/inpainting_examples/overture-creations-5sI6fQgYIuo_mask.png"
>>> source = load_image(img_url)
>>> mask = load_image(mask_url)
>>> image = pipe(prompt=prompt, negative_prompt=" ", image=source, mask_image=mask, strength=0.85).images[0]
>>> image.save("qwenimage_inpainting.png")

encode_prompt

< >

( prompt: str | list[str]device: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024 )

参数

  • prompt (str 或 list[str]，可选) — 要编码的提示
  • device — (torch.device)： torch 设备
  • num_images_per_prompt (int) — 每个提示词应生成的图像数量
  • prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如 提示词加权。如果未提供，文本嵌入将从 prompt 输入参数生成。

QwenImageEditPipeline

class diffusers.QwenImageEditPipeline

< >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLQwenImagetext_encoder: Qwen2_5_VLForConditionalGenerationtokenizer: Qwen2Tokenizerprocessor: Qwen2VLProcessortransformer: QwenImageTransformer2DModel )

参数

用于图像编辑的 Qwen-Image-Edit 流水线。

__call__

< >

( image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = Noneprompt: str | list[str] = Nonenegative_prompt: str | list[str] = Nonetrue_cfg_scale: float = 4.0height: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 50sigmas: list[float] | None = Noneguidance_scale: float | None = Nonenum_images_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_mask: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']max_sequence_length: int = 512 ) → ~pipelines.qwenimage.QwenImagePipelineOutput or tuple

参数

  • image (torch.Tensor、PIL.Image.Image、np.ndarray、list[torch.Tensor]、list[PIL.Image.Image] 或 list[np.ndarray]) — Image、numpy 数组或张量，表示用作起点的图像批次。对于 numpy 数组和 PyTorch 张量，预期的取值范围为 [0, 1]。如果是张量或张量列表，预期的形状应为 (B, C, H, W) 或 (C, H, W)。如果是 numpy 数组或数组列表，预期的形状应为 (B, H, W, C) 或 (H, W, C)。它也可以接受图像潜变量作为 image，但如果直接传入潜变量，则不会再次进行编码。
  • prompt (str 或 list[str]，可选) — 用于引导图像生成的提示词或提示词列表。如果未定义，则必须改为传入 prompt_embeds。
  • negative_prompt (str 或 list[str]，可选) — 用于不引导图像生成的提示词。如果未定义，则必须传入 negative_prompt_embeds。当不使用引导时会被忽略（即当 true_cfg_scale 不大于 1 时会被忽略）。
  • true_cfg_scale (float，可选，默认值为 1.0) — true_cfg_scale (float，可选，默认值为 1.0)：如 Classifier-Free Diffusion Guidance 中定义的引导尺度。true_cfg_scale 定义为 Imagen Paper 中公式 2 的 w。通过设置 true_cfg_scale > 1 并提供 negative_prompt 来启用无分类器引导。较高的引导尺度会促使生成与文本 prompt 紧密关联的图像，通常以牺牲图像质量为代价。
  • height (int，可选，默认为 self.unet.config.sample_size * self.vae_scale_factor) — 生成图像的高度（以像素为单位）。默认设置为 1024，以获得最佳效果。
  • width (int，可选，默认为 self.unet.config.sample_size * self.vae_scale_factor) — 生成图像的宽度（以像素为单位）。默认设置为 1024，以获得最佳效果。
  • num_inference_steps (int，可选，默认为 50) — 去噪步数。更多的去噪步数通常能生成更高质量的图像，但代价是推理速度变慢。
  • sigmas (list[float]，可选) — 用于在支持 sigmas 参数的调度器的 set_timesteps 方法中，为去噪过程指定自定义的 sigmas。如果未定义，则使用传入 num_inference_steps 时的默认行为。
  • guidance_scale (float, 可选，默认为 None) — 用于 guidance 蒸馏模型的 guidance scale 值。与传统的 classifier-free guidance 不同，后者在推理阶段通过噪声预测重缩放来应用 guidance scale，而 guidance 蒸馏模型在 forward pass 期间直接将 guidance scale 作为输入参数。通过设置 guidance_scale > 1 来启用 guidance scale。较高的 guidance scale 会促使生成与文本 prompt 紧密关联的图像，通常以牺牲图像质量为代价。流水线中的此参数旨在支持未来出现的 guidance 蒸馏模型。在未使用 guidance 蒸馏模型时，该参数将被忽略。若要启用传统的 classifier-free guidance，请传入 true_cfg_scale > 1.0 和 negative_prompt（即使是像 ” ” 这样的空 negative prompt 也应能启用 classifier-free guidance 计算）。
  • num_images_per_prompt (int，可选，默认为 1) — 每个提示词生成的图像数量。
  • generator (torch.Generator 或 list[torch.Generator]，可选) — 一个或一组 torch 生成器，用于使生成过程具有确定性。
  • latents (torch.Tensor, 可选) — 预先生成的噪声潜变量，从高斯分布中采样得到，用作图像生成的输入。可用于使用不同的提示词对同一生成过程进行微调。如果未提供，将通过使用提供的随机generator进行采样来生成一个潜变量张量。
  • prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如 提示词加权。如果未提供，文本嵌入将从 prompt 输入参数生成。
  • prompt_embeds_mask (torch.Tensor, 可选) — prompt_embeds 的注意力掩码。
  • negative_prompt_embeds (torch.Tensor, 可选) — 预生成的负向文本嵌入。可用于轻松调整文本输入，例如提示词加权。如果未提供，negative_prompt_embeds 将从 negative_prompt 输入参数生成。
  • negative_prompt_embeds_mask (torch.Tensor, 可选) — negative_prompt_embeds 的注意力掩码。
  • output_type (str，可选，默认为 "pil") — 生成图像的输出格式。可选值为 PIL：PIL.Image.Image 或 np.array。
  • return_dict (bool，可选，默认为 True) — 是否返回 ~pipelines.qwenimage.QwenImagePipelineOutput 而不是普通元组。
  • attention_kwargs (dict, 可选) — 一个 kwargs 字典，如果指定，将传递给 diffusers.models.attention_processor 中定义的 AttentionProcessor，该处理器在 self.processor 下定义。
  • callback_on_step_end (Callable, 可选) — 一个在推理过程中每个去噪步骤结束时调用的函数。该函数以以下参数被调用：callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)。callback_kwargs 将包含由 callback_on_step_end_tensor_inputs 指定的所有张量列表。
  • callback_on_step_end_tensor_inputs (list，可选) — callback_on_step_end 函数的张量输入列表。列表中指定的张量将作为 callback_kwargs 参数传递。您只能包含流水线类 ._callback_tensor_inputs 属性中列出的变量。
  • max_sequence_length（int，默认为 512）— 与 prompt 配合使用的最大序列长度。

返回值

~pipelines.qwenimage.QwenImagePipelineOutput 或 tuple

如果 return_dict 为 True，则返回 ~pipelines.qwenimage.QwenImagePipelineOutput，否则返回 tuple。当返回元组时，第一个元素是一个包含生成图像的列表。

调用生成 pipeline 时调用的函数。

示例：

>>> import torch
>>> from PIL import Image
>>> from diffusers import QwenImageEditPipeline
>>> from diffusers.utils import load_image

>>> pipe = QwenImageEditPipeline.from_pretrained("Qwen/Qwen-Image-Edit", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")
>>> image = load_image(
...     "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/yarn-art-pikachu.png"
... ).convert("RGB")
>>> prompt = (
...     "Make Pikachu hold a sign that says 'Qwen Edit is awesome', yarn art style, detailed, vibrant colors"
... )
>>> # Depending on the variant being used, the pipeline call will slightly vary.
>>> # Refer to the pipeline documentation for more details.
>>> image = pipe(image, prompt, num_inference_steps=50).images[0]
>>> image.save("qwenimage_edit.png")

encode_prompt

< >

( prompt: str | list[str]image: typing.Optional[torch.Tensor] = Nonedevice: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024 )

参数

  • prompt (str 或 list[str]，可选) — 要编码的提示
  • image (torch.Tensor, 可选) — 要编码的图像
  • device — (torch.device)： torch 设备
  • num_images_per_prompt (int) — 每个提示词应生成的图像数量
  • prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如 提示词加权。如果未提供，文本嵌入将从 prompt 输入参数生成。

QwenImageEditInpaintPipeline

class diffusers.QwenImageEditInpaintPipeline

< >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLQwenImagetext_encoder: Qwen2_5_VLForConditionalGenerationtokenizer: Qwen2Tokenizerprocessor: Qwen2VLProcessortransformer: QwenImageTransformer2DModel )

参数

用于图像编辑的 Qwen-Image-Edit 流水线。

__call__

< >

( image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = Noneprompt: str | list[str] = Nonenegative_prompt: str | list[str] = Nonemask_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Nonemasked_image_latents: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Nonetrue_cfg_scale: float = 4.0height: int | None = Nonewidth: int | None = Nonepadding_mask_crop: int | None = Nonestrength: float = 0.6num_inference_steps: int = 50sigmas: list[float] | None = Noneguidance_scale: float | None = Nonenum_images_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_mask: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']max_sequence_length: int = 512 ) → ~pipelines.qwenimage.QwenImagePipelineOutput or tuple

参数

  • image (torch.Tensor、PIL.Image.Image、np.ndarray、list[torch.Tensor]、list[PIL.Image.Image] 或 list[np.ndarray]) — Image、numpy 数组或张量，表示用作起点的图像批次。对于 numpy 数组和 PyTorch 张量，预期的取值范围为 [0, 1]。如果是张量或张量列表，预期的形状应为 (B, C, H, W) 或 (C, H, W)。如果是 numpy 数组或数组列表，预期的形状应为 (B, H, W, C) 或 (H, W, C)。它也可以接受图像潜变量作为 image，但如果直接传入潜变量，则不会再次进行编码。
  • prompt (str 或 list[str]，可选) — 用于引导图像生成的提示词或提示词列表。如果未定义，则必须改为传入 prompt_embeds。
  • negative_prompt (str 或 list[str]，可选) — 用于不引导图像生成的提示词。如果未定义，则必须传入 negative_prompt_embeds。当不使用引导时会被忽略（即当 true_cfg_scale 不大于 1 时会被忽略）。
  • true_cfg_scale (float，可选，默认值为 1.0) — true_cfg_scale (float，可选，默认值为 1.0)：如 Classifier-Free Diffusion Guidance 中定义的引导尺度。true_cfg_scale 定义为 Imagen Paper 中公式 2 的 w。通过设置 true_cfg_scale > 1 并提供 negative_prompt 来启用无分类器引导。较高的引导尺度会促使生成与文本 prompt 紧密关联的图像，通常以牺牲图像质量为代价。
  • mask_image (torch.Tensor、PIL.Image.Image、np.ndarray、list[torch.Tensor]、list[PIL.Image.Image] 或 list[np.ndarray]) — Image、numpy 数组或张量，表示要用于遮罩 image 的图像批次。遮罩中的白色像素将被重绘，而黑色像素将保留。如果 mask_image 是 PIL 图像，则在使用前会将其转换为单通道（亮度）。如果它是 numpy 数组或 PyTorch 张量，则应包含一个颜色通道（L）而不是三个，因此 PyTorch 张量的预期形状为 (B, 1, H, W)、(B, H, W)、(1, H, W) 或 (H, W)。而 numpy 数组的预期形状为 (B, H, W, 1)、(B, H, W)、(H, W, 1) 或 (H, W)。
  • masked_image_latents (torch.Tensor, list[torch.Tensor]) — Tensor，表示用于对 VAE 生成的 image 进行掩码处理的图像批次。如果未提供，掩码潜变量张量将由 mask_image 生成。
  • height (int，可选，默认为 self.unet.config.sample_size * self.vae_scale_factor) — 生成图像的高度（以像素为单位）。默认设置为 1024，以获得最佳效果。
  • width (int，可选，默认为 self.unet.config.sample_size * self.vae_scale_factor) — 生成图像的宽度（以像素为单位）。默认设置为 1024，以获得最佳效果。
  • padding_mask_crop (int, 可选，默认为 None) — 应用于图像和掩码的裁剪边距大小。如果为 None，则不对 image 和 mask_image 进行裁剪。如果 padding_mask_crop 不为 None，则会先找到一个与图像具有相同宽高比且包含所有掩码区域的矩形区域，然后基于 padding_mask_crop 扩展该区域。随后，在调整大小以匹配原始图像尺寸用于修复之前，会根据扩展后的区域对图像和 mask_image 进行裁剪。当掩码区域较小而图像较大，且包含与修复无关的信息（例如背景）时，此功能非常有用。
  • strength (float, 可选，默认为 1.0) — 指示对参考 image 进行变换的程度。取值必须在 0 到 1 之间。image 用作起始点，strength 越高，添加的噪声越多。去噪步数取决于初始添加的噪声量。当 strength 为 1 时，添加的噪声达到最大值，去噪过程将运行 num_inference_steps 中指定的完整迭代次数。值为 1 时，基本上会忽略 image。
  • num_inference_steps (int，可选，默认为 50) — 去噪步数。更多的去噪步数通常能生成更高质量的图像，但代价是推理速度变慢。
  • sigmas (list[float]，可选) — 用于在支持 sigmas 参数的调度器的 set_timesteps 方法中，为去噪过程指定自定义的 sigmas。如果未定义，则使用传入 num_inference_steps 时的默认行为。
  • guidance_scale (float, 可选，默认为 None) — 用于 guidance 蒸馏模型的 guidance scale 值。与传统的 classifier-free guidance 不同，后者在推理阶段通过噪声预测重缩放来应用 guidance scale，而 guidance 蒸馏模型在 forward pass 期间直接将 guidance scale 作为输入参数。通过设置 guidance_scale > 1 来启用 guidance scale。较高的 guidance scale 会促使生成与文本 prompt 紧密关联的图像，通常以牺牲图像质量为代价。流水线中的此参数旨在支持未来出现的 guidance 蒸馏模型。在未使用 guidance 蒸馏模型时，该参数将被忽略。若要启用传统的 classifier-free guidance，请传入 true_cfg_scale > 1.0 和 negative_prompt（即使是像 ” ” 这样的空 negative prompt 也应能启用 classifier-free guidance 计算）。
  • num_images_per_prompt (int，可选，默认为 1) — 每个提示词生成的图像数量。
  • generator (torch.Generator 或 list[torch.Generator]，可选) — 一个或一组 torch 生成器，用于使生成过程具有确定性。
  • latents (torch.Tensor, 可选) — 预先生成的噪声潜变量，从高斯分布中采样得到，用作图像生成的输入。可用于使用不同的提示词对同一生成过程进行微调。如果未提供，将通过使用提供的随机generator进行采样来生成一个潜变量张量。
  • prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如 提示词加权。如果未提供，文本嵌入将从 prompt 输入参数生成。
  • prompt_embeds_mask (torch.Tensor, 可选) — prompt_embeds 的注意力掩码。
  • negative_prompt_embeds (torch.Tensor, 可选) — 预生成的负向文本嵌入。可用于轻松调整文本输入，例如提示词加权。如果未提供，negative_prompt_embeds 将从 negative_prompt 输入参数生成。
  • negative_prompt_embeds_mask (torch.Tensor, 可选) — negative_prompt_embeds 的注意力掩码。
  • output_type (str，可选，默认为 "pil") — 生成图像的输出格式。可选值为 PIL：PIL.Image.Image 或 np.array。
  • return_dict (bool，可选，默认为 True) — 是否返回 ~pipelines.qwenimage.QwenImagePipelineOutput 而不是普通元组。
  • attention_kwargs (dict, 可选) — 一个 kwargs 字典，如果指定，将传递给 diffusers.models.attention_processor 中定义的 AttentionProcessor，该处理器在 self.processor 下定义。
  • callback_on_step_end (Callable, 可选) — 一个在推理过程中每个去噪步骤结束时调用的函数。该函数以以下参数被调用：callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)。callback_kwargs 将包含由 callback_on_step_end_tensor_inputs 指定的所有张量列表。
  • callback_on_step_end_tensor_inputs (list，可选) — callback_on_step_end 函数的张量输入列表。列表中指定的张量将作为 callback_kwargs 参数传递。您只能包含流水线类 ._callback_tensor_inputs 属性中列出的变量。
  • max_sequence_length（int，默认为 512）— 与 prompt 配合使用的最大序列长度。

返回值

~pipelines.qwenimage.QwenImagePipelineOutput 或 tuple

如果 return_dict 为 True，则返回 ~pipelines.qwenimage.QwenImagePipelineOutput，否则返回 tuple。当返回元组时，第一个元素是一个包含生成图像的列表。

调用生成 pipeline 时调用的函数。

示例：

>>> import torch
>>> from PIL import Image
>>> from diffusers import QwenImageEditInpaintPipeline
>>> from diffusers.utils import load_image

>>> pipe = QwenImageEditInpaintPipeline.from_pretrained("Qwen/Qwen-Image-Edit", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")
>>> prompt = "Face of a yellow cat, high resolution, sitting on a park bench"

>>> img_url = "https://raw.githubusercontent.com/CompVis/latent-diffusion/main/data/inpainting_examples/overture-creations-5sI6fQgYIuo.png"
>>> mask_url = "https://raw.githubusercontent.com/CompVis/latent-diffusion/main/data/inpainting_examples/overture-creations-5sI6fQgYIuo_mask.png"
>>> source = load_image(img_url)
>>> mask = load_image(mask_url)
>>> image = pipe(
...     prompt=prompt, negative_prompt=" ", image=source, mask_image=mask, strength=1.0, num_inference_steps=50
... ).images[0]
>>> image.save("qwenimage_inpainting.png")

encode_prompt

< >

( prompt: str | list[str]image: typing.Optional[torch.Tensor] = Nonedevice: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024 )

参数

  • prompt (str 或 list[str]，可选) — 要编码的提示
  • image (torch.Tensor, 可选) — 要编码的图像
  • device — (torch.device)： torch 设备
  • num_images_per_prompt (int) — 每个提示词应生成的图像数量
  • prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如 提示词加权。如果未提供，文本嵌入将从 prompt 输入参数生成。

QwenImageControlNetPipeline

类 diffusers.QwenImageControlNetPipeline

< >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLQwenImagetext_encoder: Qwen2_5_VLForConditionalGenerationtokenizer: Qwen2Tokenizertransformer: QwenImageTransformer2DModelcontrolnet: diffusers.models.controlnets.controlnet_qwenimage.QwenImageControlNetModel | diffusers.models.controlnets.controlnet_qwenimage.QwenImageMultiControlNetModel )

参数

用于文本到图像生成的 QwenImage 流水线。

__call__

< >

( prompt: str | list[str] = Nonenegative_prompt: str | list[str] = Nonetrue_cfg_scale: float = 4.0height: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 50sigmas: list[float] | None = Noneguidance_scale: float | None = Nonecontrol_guidance_start: float | list[float] = 0.0control_guidance_end: float | list[float] = 1.0control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Nonecontrolnet_conditioning_scale: float | list[float] = 1.0num_images_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_mask: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']max_sequence_length: int = 512 ) → ~pipelines.qwenimage.QwenImagePipelineOutput or tuple

参数

  • prompt (str 或 list[str]，可选) — 用于引导图像生成的提示词或提示词列表。如果未定义，则必须改为传入 prompt_embeds。
  • negative_prompt (str 或 list[str]，可选) — 用于不引导图像生成的提示词。如果未定义，则必须传入 negative_prompt_embeds。当不使用引导时会被忽略（即当 true_cfg_scale 不大于 1 时会被忽略）。
  • true_cfg_scale (float，可选，默认值为 1.0) — Classifier-Free Diffusion Guidance 中定义的引导尺度。true_cfg_scale 定义为 Imagen Paper 中公式 2 的 w。通过设置 true_cfg_scale > 1 并提供 negative_prompt 来启用无分类器引导。较高的引导尺度会促使生成与文本 prompt 紧密关联的图像，通常以牺牲图像质量为代价。
  • height (int，可选，默认为 self.unet.config.sample_size * self.vae_scale_factor) — 生成图像的高度（以像素为单位）。默认设置为 1024，以获得最佳效果。
  • width (int，可选，默认为 self.unet.config.sample_size * self.vae_scale_factor) — 生成图像的宽度（以像素为单位）。默认设置为 1024，以获得最佳效果。
  • num_inference_steps (int，可选，默认为 50) — 去噪步数。更多的去噪步数通常能生成更高质量的图像，但代价是推理速度变慢。
  • sigmas (list[float]，可选) — 用于在支持 sigmas 参数的调度器的 set_timesteps 方法中，为去噪过程指定自定义的 sigmas。如果未定义，则使用传入 num_inference_steps 时的默认行为。
  • guidance_scale (float, 可选，默认为 None) — 用于 guidance 蒸馏模型的 guidance scale 值。与传统的 classifier-free guidance 不同，后者在推理阶段通过噪声预测重缩放来应用 guidance scale，而 guidance 蒸馏模型在 forward pass 期间直接将 guidance scale 作为输入参数。通过设置 guidance_scale > 1 来启用 guidance scale。较高的 guidance scale 会促使生成与文本 prompt 紧密关联的图像，通常以牺牲图像质量为代价。流水线中的此参数旨在支持未来出现的 guidance 蒸馏模型。在未使用 guidance 蒸馏模型时，该参数将被忽略。若要启用传统的 classifier-free guidance，请传入 true_cfg_scale > 1.0 和 negative_prompt（即使是像 ” ” 这样的空 negative prompt 也应能启用 classifier-free guidance 计算）。
  • control_guidance_start（float 或 list[float]，可选，默认值为 0.0）—— ControlNet 开始施加影响的总步数百分比。
  • control_guidance_end (float 或 list[float]，可选，默认值为 1.0) — ControlNet 停止应用时占总步数的百分比。
  • control_image (PipelineImageInput，可选) — 用于为生成过程提供引导的 ControlNet 输入条件。
  • controlnet_conditioning_scale（float 或 list[float]，可选，默认值为 1.0）— ControlNet 的输出在加到原始 transformer 的残差之前，会先乘以 controlnet_conditioning_scale。
  • num_images_per_prompt (int，可选，默认为 1) — 每个提示词生成的图像数量。
  • generator (torch.Generator 或 list[torch.Generator]，可选) — 一个或一组 torch 生成器，用于使生成过程具有确定性。
  • latents (torch.Tensor, 可选) — 预先生成的噪声潜变量，从高斯分布中采样得到，用作图像生成的输入。可用于使用不同的提示词对同一生成过程进行微调。如果未提供，将通过使用提供的随机generator进行采样来生成一个潜变量张量。
  • prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如 提示词加权。如果未提供，文本嵌入将从 prompt 输入参数生成。
  • prompt_embeds_mask (torch.Tensor, 可选) — prompt_embeds 的注意力掩码。
  • negative_prompt_embeds (torch.Tensor, 可选) — 预生成的负向文本嵌入。可用于轻松调整文本输入，例如提示词加权。如果未提供，negative_prompt_embeds 将从 negative_prompt 输入参数生成。
  • negative_prompt_embeds_mask (torch.Tensor, 可选) — negative_prompt_embeds 的注意力掩码。
  • output_type (str，可选，默认为 "pil") — 生成图像的输出格式。可选值为 PIL：PIL.Image.Image 或 np.array。
  • return_dict (bool，可选，默认为 True) — 是否返回 ~pipelines.qwenimage.QwenImagePipelineOutput 而不是普通元组。
  • attention_kwargs (dict, 可选) — 一个 kwargs 字典，如果指定，将传递给 diffusers.models.attention_processor 中定义的 AttentionProcessor，该处理器在 self.processor 下定义。
  • callback_on_step_end (Callable, 可选) — 一个在推理过程中每个去噪步骤结束时调用的函数。该函数以以下参数被调用：callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)。callback_kwargs 将包含由 callback_on_step_end_tensor_inputs 指定的所有张量列表。
  • callback_on_step_end_tensor_inputs (list，可选) — callback_on_step_end 函数的张量输入列表。列表中指定的张量将作为 callback_kwargs 参数传递。您只能包含流水线类 ._callback_tensor_inputs 属性中列出的变量。
  • max_sequence_length（int，默认为 512）— 与 prompt 配合使用的最大序列长度。

返回值

~pipelines.qwenimage.QwenImagePipelineOutput 或 tuple

如果 return_dict 为 True，则返回 ~pipelines.qwenimage.QwenImagePipelineOutput，否则返回 tuple。当返回元组时，第一个元素是一个包含生成图像的列表。

调用生成 pipeline 时调用的函数。

示例：

>>> import torch
>>> from diffusers.utils import load_image
>>> from diffusers import QwenImageControlNetModel, QwenImageMultiControlNetModel, QwenImageControlNetPipeline

>>> # QwenImageControlNetModel
>>> controlnet = QwenImageControlNetModel.from_pretrained(
...     "InstantX/Qwen-Image-ControlNet-Union", torch_dtype=torch.bfloat16
... )
>>> pipe = QwenImageControlNetPipeline.from_pretrained(
...     "Qwen/Qwen-Image", controlnet=controlnet, torch_dtype=torch.bfloat16
... )
>>> pipe.to("cuda")
>>> prompt = "Aesthetics art, traditional asian pagoda, elaborate golden accents, sky blue and white color palette, swirling cloud pattern, digital illustration, east asian architecture, ornamental rooftop, intricate detailing on building, cultural representation."
>>> negative_prompt = " "
>>> control_image = load_image(
...     "https://huggingface.co/InstantX/Qwen-Image-ControlNet-Union/resolve/main/conds/canny.png"
... )
>>> # Depending on the variant being used, the pipeline call will slightly vary.
>>> # Refer to the pipeline documentation for more details.
>>> image = pipe(
...     prompt,
...     negative_prompt=negative_prompt,
...     control_image=control_image,
...     controlnet_conditioning_scale=1.0,
...     num_inference_steps=30,
...     true_cfg_scale=4.0,
... ).images[0]
>>> image.save("qwenimage_cn_union.png")

>>> # QwenImageMultiControlNetModel
>>> controlnet = QwenImageControlNetModel.from_pretrained(
...     "InstantX/Qwen-Image-ControlNet-Union", torch_dtype=torch.bfloat16
... )
>>> controlnet = QwenImageMultiControlNetModel([controlnet])
>>> pipe = QwenImageControlNetPipeline.from_pretrained(
...     "Qwen/Qwen-Image", controlnet=controlnet, torch_dtype=torch.bfloat16
... )
>>> pipe.to("cuda")
>>> prompt = "Aesthetics art, traditional asian pagoda, elaborate golden accents, sky blue and white color palette, swirling cloud pattern, digital illustration, east asian architecture, ornamental rooftop, intricate detailing on building, cultural representation."
>>> negative_prompt = " "
>>> control_image = load_image(
...     "https://huggingface.co/InstantX/Qwen-Image-ControlNet-Union/resolve/main/conds/canny.png"
... )
>>> # Depending on the variant being used, the pipeline call will slightly vary.
>>> # Refer to the pipeline documentation for more details.
>>> image = pipe(
...     prompt,
...     negative_prompt=negative_prompt,
...     control_image=[control_image, control_image],
...     controlnet_conditioning_scale=[0.5, 0.5],
...     num_inference_steps=30,
...     true_cfg_scale=4.0,
... ).images[0]
>>> image.save("qwenimage_cn_union_multi.png")

encode_prompt

< >

( prompt: str | list[str]device: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024 )

参数

  • prompt (str 或 list[str]，可选) — 要编码的提示
  • device — (torch.device)： torch 设备
  • num_images_per_prompt (int) — 每个提示词应生成的图像数量
  • prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如 提示词加权。如果未提供，文本嵌入将从 prompt 输入参数生成。

QwenImageEditPlusPipeline

类 diffusers.QwenImageEditPlusPipeline

< >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLQwenImagetext_encoder: Qwen2_5_VLForConditionalGenerationtokenizer: Qwen2Tokenizerprocessor: Qwen2VLProcessortransformer: QwenImageTransformer2DModel )

参数

用于图像编辑的 Qwen-Image-Edit 流水线。

__call__

< >

( image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = Noneprompt: str | list[str] = Nonenegative_prompt: str | list[str] = Nonetrue_cfg_scale: float = 4.0height: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 50sigmas: list[float] | None = Noneguidance_scale: float | None = Nonenum_images_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_mask: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']max_sequence_length: int = 512 ) → ~pipelines.qwenimage.QwenImagePipelineOutput or tuple

参数

  • image (torch.Tensor、PIL.Image.Image、np.ndarray、list[torch.Tensor]、list[PIL.Image.Image] 或 list[np.ndarray]) — Image、numpy 数组或张量，表示用作起点的图像批次。对于 numpy 数组和 PyTorch 张量，预期的取值范围为 [0, 1]。如果是张量或张量列表，预期的形状应为 (B, C, H, W) 或 (C, H, W)。如果是 numpy 数组或数组列表，预期的形状应为 (B, H, W, C) 或 (H, W, C)。它也可以接受图像潜变量作为 image，但如果直接传入潜变量，则不会再次进行编码。
  • prompt (str 或 list[str]，可选) — 用于引导图像生成的提示词或提示词列表。如果未定义，则必须改为传入 prompt_embeds。
  • negative_prompt (str 或 list[str]，可选) — 用于不引导图像生成的提示词。如果未定义，则必须传入 negative_prompt_embeds。当不使用引导时会被忽略（即当 true_cfg_scale 不大于 1 时会被忽略）。
  • true_cfg_scale (float，可选，默认值为 1.0) — true_cfg_scale (float，可选，默认值为 1.0)：如 Classifier-Free Diffusion Guidance 中定义的引导尺度。true_cfg_scale 定义为 Imagen Paper 中公式 2 的 w。通过设置 true_cfg_scale > 1 并提供 negative_prompt 来启用无分类器引导。较高的引导尺度会促使生成与文本 prompt 紧密关联的图像，通常以牺牲图像质量为代价。
  • height (int，可选，默认为 self.unet.config.sample_size * self.vae_scale_factor) — 生成图像的高度（以像素为单位）。默认设置为 1024，以获得最佳效果。
  • width (int，可选，默认为 self.unet.config.sample_size * self.vae_scale_factor) — 生成图像的宽度（以像素为单位）。默认设置为 1024，以获得最佳效果。
  • num_inference_steps (int，可选，默认为 50) — 去噪步数。更多的去噪步数通常能生成更高质量的图像，但代价是推理速度变慢。
  • sigmas (list[float]，可选) — 用于在支持 sigmas 参数的调度器的 set_timesteps 方法中，为去噪过程指定自定义的 sigmas。如果未定义，则使用传入 num_inference_steps 时的默认行为。
  • guidance_scale (float, 可选，默认为 None) — 用于 guidance 蒸馏模型的 guidance scale 值。与传统的 classifier-free guidance 不同，后者在推理阶段通过噪声预测重缩放来应用 guidance scale，而 guidance 蒸馏模型在 forward pass 期间直接将 guidance scale 作为输入参数。通过设置 guidance_scale > 1 来启用 guidance scale。较高的 guidance scale 会促使生成与文本 prompt 紧密关联的图像，通常以牺牲图像质量为代价。流水线中的此参数旨在支持未来出现的 guidance 蒸馏模型。在未使用 guidance 蒸馏模型时，该参数将被忽略。若要启用传统的 classifier-free guidance，请传入 true_cfg_scale > 1.0 和 negative_prompt（即使是像 ” ” 这样的空 negative prompt 也应能启用 classifier-free guidance 计算）。
  • num_images_per_prompt (int，可选，默认为 1) — 每个提示词生成的图像数量。
  • generator (torch.Generator 或 list[torch.Generator]，可选) — 一个或一组 torch 生成器，用于使生成过程具有确定性。
  • latents (torch.Tensor, 可选) — 预先生成的噪声潜变量，从高斯分布中采样得到，用作图像生成的输入。可用于使用不同的提示词对同一生成过程进行微调。如果未提供，将通过使用提供的随机generator进行采样来生成一个潜变量张量。
  • prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如 提示词加权。如果未提供，文本嵌入将从 prompt 输入参数生成。
  • prompt_embeds_mask (torch.Tensor, 可选) — prompt_embeds 的注意力掩码。
  • negative_prompt_embeds (torch.Tensor, 可选) — 预生成的负向文本嵌入。可用于轻松调整文本输入，例如提示词加权。如果未提供，negative_prompt_embeds 将从 negative_prompt 输入参数生成。
  • negative_prompt_embeds_mask (torch.Tensor, 可选) — negative_prompt_embeds 的注意力掩码。
  • output_type (str，可选，默认为 "pil") — 生成图像的输出格式。可选值为 PIL：PIL.Image.Image 或 np.array。
  • return_dict (bool，可选，默认为 True) — 是否返回 ~pipelines.qwenimage.QwenImagePipelineOutput 而不是普通元组。
  • attention_kwargs (dict, 可选) — 一个 kwargs 字典，如果指定，将传递给 diffusers.models.attention_processor 中定义的 AttentionProcessor，该处理器在 self.processor 下定义。
  • callback_on_step_end (Callable, 可选) — 一个在推理过程中每个去噪步骤结束时调用的函数。该函数以以下参数被调用：callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)。callback_kwargs 将包含由 callback_on_step_end_tensor_inputs 指定的所有张量列表。
  • callback_on_step_end_tensor_inputs (list，可选) — callback_on_step_end 函数的张量输入列表。列表中指定的张量将作为 callback_kwargs 参数传递。您只能包含流水线类 ._callback_tensor_inputs 属性中列出的变量。
  • max_sequence_length（int，默认为 512）— 与 prompt 配合使用的最大序列长度。

返回值

~pipelines.qwenimage.QwenImagePipelineOutput 或 tuple

如果 return_dict 为 True，则返回 ~pipelines.qwenimage.QwenImagePipelineOutput，否则返回 tuple。当返回元组时，第一个元素是一个包含生成图像的列表。

调用生成 pipeline 时调用的函数。

示例：

>>> import torch
>>> from PIL import Image
>>> from diffusers import QwenImageEditPlusPipeline
>>> from diffusers.utils import load_image

>>> pipe = QwenImageEditPlusPipeline.from_pretrained("Qwen/Qwen-Image-Edit-2509", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")
>>> image = load_image(
...     "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/yarn-art-pikachu.png"
... ).convert("RGB")
>>> prompt = (
...     "Make Pikachu hold a sign that says 'Qwen Edit is awesome', yarn art style, detailed, vibrant colors"
... )
>>> # Depending on the variant being used, the pipeline call will slightly vary.
>>> # Refer to the pipeline documentation for more details.
>>> image = pipe(image, prompt, num_inference_steps=50).images[0]
>>> image.save("qwenimage_edit_plus.png")

encode_prompt

< >

( prompt: str | list[str]image: typing.Optional[torch.Tensor] = Nonedevice: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024 )

参数

  • prompt (str 或 list[str]，可选) — 要编码的提示
  • image (torch.Tensor, 可选) — 要编码的图像
  • device — (torch.device)： torch 设备
  • num_images_per_prompt (int) — 每个提示词应生成的图像数量
  • prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如 提示词加权。如果未提供，文本嵌入将从 prompt 输入参数生成。

QwenImageLayeredPipeline

class diffusers.QwenImageLayeredPipeline

< >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLQwenImagetext_encoder: Qwen2_5_VLForConditionalGenerationtokenizer: Qwen2Tokenizerprocessor: Qwen2VLProcessortransformer: QwenImageTransformer2DModel )

参数

用于图像分解的 Qwen-Image-Layered 流水线。

__call__

< >

( image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = Noneprompt: str | list[str] = Nonenegative_prompt: str | list[str] = Nonetrue_cfg_scale: float = 4.0layers: int | None = 4num_inference_steps: int = 50sigmas: list[float] | None = Noneguidance_scale: float | None = Nonenum_images_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_mask: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']max_sequence_length: int = 512resolution: int = 640cfg_normalize: bool = Falseuse_en_prompt: bool = False ) → ~pipelines.qwenimage.QwenImagePipelineOutput or tuple

参数

  • image (torch.Tensor、PIL.Image.Image、np.ndarray、list[torch.Tensor]、list[PIL.Image.Image] 或 list[np.ndarray]) — Image、numpy 数组或张量，表示用作起点的图像批次。对于 numpy 数组和 PyTorch 张量，预期的取值范围为 [0, 1]。如果是张量或张量列表，预期的形状应为 (B, C, H, W) 或 (C, H, W)。如果是 numpy 数组或数组列表，预期的形状应为 (B, H, W, C) 或 (H, W, C)。它也可以接受图像潜变量作为 image，但如果直接传入潜变量，则不会再次进行编码。
  • prompt (str 或 list[str]，可选) — 用于引导图像生成的提示词或提示词列表。如果未定义，则必须改为传入 prompt_embeds。
  • negative_prompt (str 或 list[str]，可选) — 用于不引导图像生成的提示词。如果未定义，则必须传入 negative_prompt_embeds。当不使用引导时会被忽略（即当 true_cfg_scale 不大于 1 时会被忽略）。
  • true_cfg_scale (float，可选，默认值为 1.0) — true_cfg_scale (float，可选，默认值为 1.0)：如 Classifier-Free Diffusion Guidance 中定义的引导尺度。true_cfg_scale 定义为 Imagen Paper 中公式 2 的 w。通过设置 true_cfg_scale > 1 并提供 negative_prompt 来启用无分类器引导。较高的引导尺度会促使生成与文本 prompt 紧密关联的图像，通常以牺牲图像质量为代价。
  • layers (int，可选，默认为 4) — 用于生成分层输出的潜在层数。
  • num_inference_steps (int，可选，默认为 50) — 去噪步数。更多的去噪步数通常能生成更高质量的图像，但代价是推理速度变慢。
  • sigmas (list[float]，可选) — 用于在支持 sigmas 参数的调度器的 set_timesteps 方法中，为去噪过程指定自定义的 sigmas。如果未定义，则使用传入 num_inference_steps 时的默认行为。
  • guidance_scale (float, 可选，默认为 None) — 用于 guidance 蒸馏模型的 guidance scale 值。与传统的 classifier-free guidance 不同，后者在推理阶段通过噪声预测重缩放来应用 guidance scale，而 guidance 蒸馏模型在 forward pass 期间直接将 guidance scale 作为输入参数。通过设置 guidance_scale > 1 来启用 guidance scale。较高的 guidance scale 会促使生成与文本 prompt 紧密关联的图像，通常以牺牲图像质量为代价。流水线中的此参数旨在支持未来出现的 guidance 蒸馏模型。在未使用 guidance 蒸馏模型时，该参数将被忽略。若要启用传统的 classifier-free guidance，请传入 true_cfg_scale > 1.0 和 negative_prompt（即使是像 ” ” 这样的空 negative prompt 也应能启用 classifier-free guidance 计算）。
  • num_images_per_prompt (int，可选，默认为 1) — 每个提示词生成的图像数量。
  • generator (torch.Generator 或 list[torch.Generator]，可选) — 一个或一组 torch 生成器，用于使生成过程具有确定性。
  • latents (torch.Tensor, 可选) — 预先生成的噪声潜变量，从高斯分布中采样得到，用作图像生成的输入。可用于使用不同的提示词对同一生成过程进行微调。如果未提供，将通过使用提供的随机generator进行采样来生成一个潜变量张量。
  • prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如 提示词加权。如果未提供，文本嵌入将从 prompt 输入参数生成。
  • prompt_embeds_mask (torch.Tensor, 可选) — prompt_embeds 的注意力掩码。
  • negative_prompt_embeds (torch.Tensor, 可选) — 预生成的负向文本嵌入。可用于轻松调整文本输入，例如提示词加权。如果未提供，negative_prompt_embeds 将从 negative_prompt 输入参数生成。
  • negative_prompt_embeds_mask (torch.Tensor, 可选) — negative_prompt_embeds 的注意力掩码。
  • output_type (str，可选，默认为 "pil") — 生成图像的输出格式。可选值为 PIL：PIL.Image.Image 或 np.array。
  • return_dict (bool，可选，默认为 True) — 是否返回 ~pipelines.qwenimage.QwenImagePipelineOutput 而不是普通元组。
  • attention_kwargs (dict, 可选) — 一个 kwargs 字典，如果指定，将传递给 diffusers.models.attention_processor 中定义的 AttentionProcessor，该处理器在 self.processor 下定义。
  • callback_on_step_end (Callable, 可选) — 一个在推理过程中每个去噪步骤结束时调用的函数。该函数以以下参数被调用：callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)。callback_kwargs 将包含由 callback_on_step_end_tensor_inputs 指定的所有张量列表。
  • callback_on_step_end_tensor_inputs (List，可选) — callback_on_step_end 函数的张量输入列表。列表中指定的张量将作为 callback_kwargs 参数传入。您只能包含流水线类的 ._callback_tensor_inputs 属性中列出的变量。
  • max_sequence_length（int，默认为 512）— 与 prompt 配合使用的最大序列长度。
  • resolution (int，可选，默认值为 640) — 使用 (640, 1024) 中的不同分桶来确定条件和输出分辨率
  • cfg_normalize (bool，可选，默认为 False) — 是否启用 cfg 归一化。
  • use_en_prompt (bool，可选，默认为 False) — 如果用户未提供说明，则自动确定说明的语言

返回值

~pipelines.qwenimage.QwenImagePipelineOutput 或 tuple

如果 return_dict 为 True，则返回 ~pipelines.qwenimage.QwenImagePipelineOutput，否则返回 tuple。当返回元组时，第一个元素是一个包含生成图像的列表。

调用生成 pipeline 时调用的函数。

示例：

>>> import torch
>>> from PIL import Image
>>> from diffusers import QwenImageLayeredPipeline
>>> from diffusers.utils import load_image

>>> pipe = QwenImageLayeredPipeline.from_pretrained("Qwen/Qwen-Image-Layered", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")
>>> image = load_image(
...     "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/yarn-art-pikachu.png"
... ).convert("RGBA")
>>> prompt = ""
>>> # Depending on the variant being used, the pipeline call will slightly vary.
>>> # Refer to the pipeline documentation for more details.
>>> images = pipe(
...     image,
...     prompt,
...     num_inference_steps=50,
...     true_cfg_scale=4.0,
...     layers=4,
...     resolution=640,
...     cfg_normalize=False,
...     use_en_prompt=True,
... ).images[0]
>>> for i, image in enumerate(images):
...     image.save(f"{i}.out.png")

encode_prompt

< >

( prompt: str | list[str]device: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024 )

参数

  • prompt (str 或 list[str]，可选) — 要编码的提示
  • device — (torch.device)： torch 设备
  • num_images_per_prompt (int) — 每个提示词应生成的图像数量
  • prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如 提示词加权。如果未提供，文本嵌入将从 prompt 输入参数生成。

QwenImagePipelineOutput

class diffusers.pipelines.qwenimage.pipeline_output.QwenImagePipelineOutput

< >

( images: list[PIL.Image.Image] | numpy.ndarray )

参数

  • images (list[PIL.Image.Image] 或 np.ndarray) — 长度为 batch_size 的去噪 PIL 图像列表，或形状为 (batch_size, height, width, num_channels) 的 numpy 数组。PIL 图像或 numpy 数组表示扩散流水线生成的去噪图像。

Stable Diffusion 管道的输出类。

Update on GitHub

←Qwen-Image 2.1 Sana→