hf-doc-build/doc / diffusers /main /ru /api /pipelines /qwenimage.md

|

raw

151 kB

Лицензия Apache License, Version 2.0 («Лицензия»);

вы можете использовать этот файл только в соответствии с Лицензией.

Вы можете получить копию Лицензии по адресу

http://www.apache.org/licenses/LICENSE-2.0

Если это не требуется применимым законодательством или не оговорено письменно, программное

распространяется по Лицензии на условиях «КАК ЕСТЬ»,

БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ ИЛИ УСЛОВИЙ, прямо указанных или подразумеваемых.

См. Лицензию для получения конкретных условий, регулирующих разрешения и

ограничениями Лицензии. -->

QwenImage

Qwen-Image от команды Qwen — это базовая модель генерации изображений в серии Qwen, демонстрирующая значительный прогресс в сложном рендеринге текста и точном редактировании изображений. Эксперименты подтверждают высокие общие возможности как в генерации, так и в редактировании изображений, с выдающимися результатами в рендеринге текста, особенно для китайского языка.

Qwen-Image доступен в следующих вариантах:

тип модели	идентификатор модели
Qwen-Image	`Qwen/Qwen-Image`
Qwen-Image-Edit	`Qwen/Qwen-Image-Edit`
Qwen-Image-Edit Plus	Qwen/Qwen-Image-Edit-2509

См. руководство Кэширование, чтобы ускорить инференс за счёт сохранения и повторного использования промежуточных результатов.

LoRA для более быстрого вывода

Используйте LoRA из lightx2v/Qwen-Image-Lightning, чтобы ускорить инференс за счёт уменьшения числа шагов. См. фрагмент кода ниже:

Код

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, когда они появятся. Обратите внимание, что передача guidance_scale в пайплайн не имеет эффекта. Чтобы включить classifier-free guidance, передайте true_cfg_scale и 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

Использование 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]

Пакетный вывод с промптами переменной длины

При использовании classifier-free guidance (CFG) с промптами разной длины пайплайн корректно обрабатывает заполнение (padding) с помощью маскирования внимания. Это гарантирует, что токены заполнения не влияют на сгенерированный вывод.

# 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]]

diffusers.QwenImagePipeline[[diffusers.QwenImagePipeline]]

diffusers.QwenImagePipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLQwenImage, text_encoder: Qwen2_5_VLForConditionalGeneration, tokenizer: Qwen2Tokenizer, transformer: QwenImageTransformer2DModel)

Источник

Параметры:

transformer (QwenImageTransformer2DModel) : архитектура условного трансформера (MMDiT) для удаления шума из закодированных латентов изображения.

scheduler (FlowMatchEulerDiscreteScheduler) : планировщик, используемый в связке с transformer для удаления шума из закодированных латентов изображения.

vae (AutoencoderKL) : Модель вариационного автоэнкодера (VAE) для кодирования изображений в латентные представления и декодирования из них.

text_encoder (Qwen2.5-VL-7B-Instruct) : Qwen2.5-VL-7B-Instruct, а именно вариант Qwen2.5-VL-7B-Instruct.

tokenizer (Qwen2Tokenizer) : Токенизатор класса https://huggingface.co/docs/transformers/en/model_doc/qwen2#transformers.Qwen2Tokenizer

Пайплайн QwenImage для генерации изображений по тексту.

call[[diffusers.QwenImagePipeline.call]]

__call__(prompt: str | list[str] = None, negative_prompt: str | list[str] = None, true_cfg_scale: float = 4.0, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, sigmas: list[float] | None = None, guidance_scale: float | None = None, num_images_per_prompt: int = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds_mask: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], max_sequence_length: int = 512)

Источник

Параметры:

prompt (str или list[str], необязательный) : Промпт или промпты для управления генерацией изображения. Если не задан, необходимо передать prompt_embeds вместо него.

negative_prompt (str или list[str], необязательный) : Промпт или промпты, которые не должны направлять генерацию изображения. Если не задан, необходимо передать negative_prompt_embeds. Игнорируется, если не используется направляющая (то есть игнорируется, если true_cfg_scale не больше 1).

true_cfg_scale (float, optional, по умолчанию 1.0) : Масштаб направленного генерирования, как определено в Classifier-Free Diffusion Guidance. true_cfg_scale определяется как w из уравнения 2. в Imagen Paper. Classifier-free guidance включается при установке true_cfg_scale > 1 и предоставлении negative_prompt. Более высокий масштаб направленного генерирования способствует созданию изображений, тесно связанных с текстовым prompt, обычно за счёт снижения качества изображения.

height (int, optional, по умолчанию self.unet.config.sample_size * self.vae_scale_factor) : Высота генерируемого изображения в пикселях. По умолчанию установлено значение 1024 для достижения наилучших результатов.

width (int, optional, по умолчанию self.unet.config.sample_size * self.vae_scale_factor) : Ширина генерируемого изображения в пикселях. По умолчанию установлено значение 1024 для достижения наилучших результатов.

num_inference_steps (int, optional, по умолчанию 50) : Количество шагов денойзинга. Как правило, большее число шагов денойзинга приводит к изображению более высокого качества, но за счёт более медленного вывода.

sigmas (list[float], optional) : Пользовательские сигмы для процесса денойзинга в планировщиках, поддерживающих аргумент sigmas в методе set_timesteps. Если не задано, будет использовано поведение по умолчанию при передаче num_inference_steps.

guidance_scale (float, optional, по умолчанию None) : Значение масштаба руководства (guidance scale) для моделей с дистиллированным руководством. В отличие от традиционного classifier-free guidance, где масштаб руководства применяется во время вывода через масштабирование предсказания шума, модели с дистиллированным руководством принимают масштаб руководства непосредственно как входной параметр во время прямого прохода. Масштаб руководства активируется при установке guidance_scale > 1. Более высокое значение масштаба руководства способствует генерации изображений, тесно связанных с текстовым prompt, обычно за счёт снижения качества изображения. Этот параметр в пайплайне предназначен для поддержки будущих моделей с дистиллированным руководством. Он игнорируется, если не используются модели с дистиллированным руководством. Для включения традиционного classifier-free guidance передайте true_cfg_scale > 1.0 и 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, который при указании передается в AttentionProcessor, определенный в self.processor в diffusers.models.attention_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, optional) : Список тензорных входных данных для функции callback_on_step_end. Тензоры, указанные в списке, будут переданы в качестве аргумента callback_kwargs. Вы сможете включать только переменные, перечисленные в атрибуте ._callback_tensor_inputs вашего класса pipeline.

max_sequence_length (int по умолчанию 512) : Максимальная длина последовательности, используемая с prompt.

Возвращает: ~pipelines.qwenimage.QwenImagePipelineOutput или tuple

~pipelines.qwenimage.QwenImagePipelineOutput, если return_dict равно True, иначе tuple. При возврате кортежа первым элементом является список с сгенерированными изображениями.

Функция, вызываемая при обращении к конвейеру для генерации.

Примеры:

>>> 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[[diffusers.QwenImagePipeline.encode_prompt]]

encode_prompt(prompt: str | list[str], device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 1024)

Источник

Параметры:

prompt (str или list[str], необязательный) : промпт для кодирования

device : (torch.device): устройство torch

num_images_per_prompt (int) : количество изображений, которые должны быть сгенерированы для каждого промпта

prompt_embeds (torch.Tensor, необязательный) : Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, например для взвешивания промпта. Если не предоставлены, текстовые эмбеддинги будут сгенерированы из входного аргумента prompt.

QwenImageImg2ImgPipeline[[diffusers.QwenImageImg2ImgPipeline]]

diffusers.QwenImageImg2ImgPipeline[[diffusers.QwenImageImg2ImgPipeline]]

diffusers.QwenImageImg2ImgPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLQwenImage, text_encoder: Qwen2_5_VLForConditionalGeneration, tokenizer: Qwen2Tokenizer, transformer: QwenImageTransformer2DModel)

Источник

Параметры:

transformer (QwenImageTransformer2DModel) : архитектура условного трансформера (MMDiT) для удаления шума из закодированных латентов изображения.

scheduler (FlowMatchEulerDiscreteScheduler) : планировщик, используемый в связке с transformer для удаления шума из закодированных латентов изображения.

vae (AutoencoderKL) : Модель вариационного автоэнкодера (VAE) для кодирования изображений в латентные представления и декодирования из них.

text_encoder (Qwen2.5-VL-7B-Instruct) : Qwen2.5-VL-7B-Instruct, а именно вариант Qwen2.5-VL-7B-Instruct.

tokenizer (Qwen2Tokenizer) : Токенизатор класса https://huggingface.co/docs/transformers/en/model_doc/qwen2#transformers.Qwen2Tokenizer

Пайплайн QwenImage для генерации изображений по тексту.

call[[diffusers.QwenImageImg2ImgPipeline.call]]

__call__(prompt: str | list[str] = None, negative_prompt: str | list[str] = None, true_cfg_scale: float = 4.0, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, height: int | None = None, width: int | None = None, strength: float = 0.6, num_inference_steps: int = 50, sigmas: list[float] | None = None, guidance_scale: float | None = None, num_images_per_prompt: int = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds_mask: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], max_sequence_length: int = 512)

Источник

Параметры:

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, optional, по умолчанию 1.0) : Масштаб направленного генерирования, как определено в Classifier-Free Diffusion Guidance. true_cfg_scale определяется как w из уравнения 2. в Imagen Paper. Classifier-free guidance включается при установке true_cfg_scale > 1 и предоставлении negative_prompt. Более высокий масштаб направленного генерирования способствует созданию изображений, тесно связанных с текстовым prompt, обычно за счёт снижения качества изображения.

height (int, optional, по умолчанию self.unet.config.sample_size * self.vae_scale_factor) : Высота генерируемого изображения в пикселях. По умолчанию установлено значение 1024 для достижения наилучших результатов.

width (int, optional, по умолчанию self.unet.config.sample_size * self.vae_scale_factor) : Ширина генерируемого изображения в пикселях. По умолчанию установлено значение 1024 для достижения наилучших результатов.

strength (float, optional, по умолчанию 1.0) : Определяет степень трансформации исходного image. Значение должно быть в диапазоне от 0 до 1. image используется как отправная точка, и чем выше strength, тем больше шума добавляется. Количество шагов денойзинга зависит от количества шума, добавленного изначально. Когда strength равно 1, добавляется максимальное количество шума, и процесс денойзинга выполняется в течение полного числа итераций, указанного в num_inference_steps. Значение 1 фактически игнорирует image.