Hugging Face's logo

Diffusers documentation

Qwen-Image 2.1

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Qwen-Image 2.1

Qwen-Image 2.1 кодирует промпт и любые условные изображения вместе с моделью Qwen3-VL, а затем выполняет денуазинг целевого изображения с помощью однопоточного блочно-каузального трансформера. См. QwenImage21Transformer2DModel для блочно-каузального внимания, процессоров внимания и causal_condition.

Значения по умолчанию соответствуют рекомендациям Qwen: 40 шагов и отсутствие guidance. Чтобы включить classifier-free guidance, передайте negative_prompt вместе с true_cfg_scale > 1; это удвоит объём вычислений на каждом шаге.

import torch
from diffusers import QwenImage21Pipeline

pipe = QwenImage21Pipeline.from_pretrained("Qwen/Qwen-Image-2.1", dtype=torch.bfloat16).to("cuda")

# Text-to-image
image = pipe("A capybara wearing a wizard hat, oil painting").images[0]
image.save("t2i.png")

# Image-conditioned editing
edited = pipe("Move it to a snowy mountain top", image=image).images[0]
edited.save("edit.png")

Несколько изображений условий

Передайте список в image, и каждый элемент станет отдельным блоком в объединённой последовательности: энкодер Qwen3-VL воспринимает их как визуальный контекст, а VAE добавляет их латентные токены. Блочное причинное внимание сохраняет двунаправленность внутри каждого блока, позволяя последующим блокам и целевому изображению обращать внимание на предыдущие, поэтому порядок, в котором вы их передаёте, определяет порядок, в котором модель их читает.

edited = pipe("Put the flowers from the first image into the second scene", image=[flowers, scene]).images[0]

Более быстрое внимание с flex_attention

По умолчанию QwenImage21AttnProcessor выполняет блок-каузальный prefill в виде одного вызова внимания на каждый сегмент префикса. Он не требует компиляции и работает в любой сборке PyTorch. QwenImage21FlexAttnProcessor выражает ту же маску в виде одного вызова flex_attention, что быстрее, когда модель скомпилирована.

Скомпилируйте модель при переключении на flex-процессор. Нескомпилированный flex_attention материализует полную матрицу оценок внимания в fp32, что значительно медленнее и приводит к исчерпанию памяти при высоком разрешении.

from diffusers.models.transformers.transformer_qwenimage21 import QwenImage21FlexAttnProcessor

pipe.transformer.set_attn_processor(QwenImage21FlexAttnProcessor())
pipe.transformer.compile()

Загрузка контрольных точек в одном файле

import torch
from diffusers import QwenImage21Pipeline, QwenImage21Transformer2DModel

transformer = QwenImage21Transformer2DModel.from_single_file(
    "https://huggingface.co/Comfy-Org/Qwen-Image-2.1/blob/main/diffusion_models/qwen_image_2.1_bf16.safetensors",
    dtype=torch.bfloat16,
)
pipe = QwenImage21Pipeline.from_pretrained("Qwen/Qwen-Image-2.1", transformer=transformer, dtype=torch.bfloat16).to(
    "cuda"
)

Сигмы выборки

Авторы моделей могут настроить сетку выборки по умолчанию с помощью sample_sigmas в конфигурации пайплайна. При загрузке опубликованного чекпоинта его сетка и настройки планировщика по умолчанию восстанавливаются автоматически.

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

# Use the checkpoint's default sampling grid.
image = pipe(prompt).images[0]

# Override the default grid for this call.
image = pipe(prompt, sigmas=[1.0, 0.8, 0.5, 0.2]).images[0]

Приведённая выше пользовательская сетка иллюстрирует API; качество генерации зависит от контрольной точки и сетки. Списки сигм не включают конечную сигму, которую планировщик добавляет в конец. Явно заданные sigmas переопределяют настроенные sample_sigmas, и любой из этих списков определяет количество шагов вместо num_inference_steps. Если ни один из них не указан, конвейер использует num_inference_steps для генерации расписания. Планировщик применяет свою настроенную обработку к любой из сеток.

Модульность

Qwen-Image 2.1 также доступен в виде модульного конвейера. Те же блоки выполняют генерацию изображений по тексту и условную генерацию по изображению: передайте image, чтобы задать условие по одному или нескольким изображениям. Настройка classifier-free guidance выполняется через компонент guider, а не через аргумент вызова true_cfg_scale, а префиксный KV-кэш включен по умолчанию (use_kv_cache=False отключает его).

import torch
from diffusers import ClassifierFreeGuidance, ModularPipeline

pipe = ModularPipeline.from_pretrained("Qwen/Qwen-Image-2.1")
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")

image = pipe(prompt="A capybara wearing a wizard hat, oil painting").images[0]

# Turn classifier-free guidance on for an edit.
pipe.update_components(guider=ClassifierFreeGuidance(guidance_scale=4.0))
edited = pipe(prompt="Move it to a snowy mountain top", negative_prompt="blurry", image=image).images[0]

Турбо-чекпоинт соответствует собственным блокам (QwenImage21TurboAutoBlocks): он работает без guider, не принимает negative_prompt и использует сетку сигм, поставляемую вместе с ним. ModularPipeline.from_pretrained выбирает турбо-блоки по записи sample_sigmas в конфигурации чекпоинта, поэтому ничего настраивать не нужно:

import torch
from diffusers import ModularPipeline

pipe = ModularPipeline.from_pretrained("Qwen/Qwen-Image-2.1-Turbo")
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")

image = pipe(prompt="A capybara wearing a wizard hat, oil painting").images[0]

QwenImage21Pipeline

класс diffusers.QwenImage21Pipeline

< >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLQwenImage21text_encoder: Qwen3VLForConditionalGenerationprocessor: Qwen3VLProcessortransformer: QwenImage21Transformer2DModelsample_sigmas: list[float] | None = None )

Параметры

  • scheduler (FlowMatchEulerDiscreteScheduler) — Планировщик, используемый для удаления шума из закодированных латентов изображения.
  • vae (AutoencoderKLQwenImage21) — Вариационный автоэнкодер, отображающий изображения в 64-канальное латентное пространство и обратно.
  • text_encoder (Qwen3VLForConditionalGeneration) — модель Qwen3-VL, формирующая совместные текстовые и изображенческие эмбеддинги.
  • processor (Qwen3VLProcessor) — Процессор, который формирует шаблон чата и токенизирует промпт и условные изображения.
  • transformer (QwenImage21Transformer2DModel) — однопоточный блок-каузальный трансформер, выполняющий денойзинг латентов.
  • sample_sigmas (list[float], необязательный) — Сигмы выборки по умолчанию, настроенные автором модели, за исключением конечной сигмы. Их длина определяет количество шагов денойзинга. Чтобы экспериментировать с другой сеткой во время выполнения, передайте sigmas в __call__.

Генерация изображений по тексту и с условием на изображение с помощью Qwen-Image 2.1.

Изображения промпта и условия кодируются совместно моделью Qwen3-VL, поэтому изображение условия занимает слоты зрения, зарезервированные для него кодировщиком, а трансформер видит одну чередующуюся последовательность текста и изображений.

__call__

< >

( prompt: str | list[str] = Noneimage: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = Nonenegative_prompt: str | list[str] = Nonetrue_cfg_scale: float = 1.0height: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 40sigmas: list[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, dict], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']output_resolution: int = 1024use_kv_cache: bool = True ) → ~pipelines.qwenimage.QwenImagePipelineOutput or tuple

Параметры

  • prompt (str или list[str], необязательный) — Промпт для управления генерацией изображения. Вместо него можно передать prompt_embeds, чтобы напрямую указать эмбеддинги.
  • image (PipelineImageInput, необязательный) — Одно или несколько условных изображений в формате PIL или массива numpy. Они кодируются текстовым энкодером как визуальный контекст и VAE в латентные токены, добавляемые перед шумом. Список представляет собой один набор изображений, общий для всех промптов в батче, а не один элемент на каждый промпт.
  • negative_prompt (str или list[str], необязательный) — Промпт, который не следует использовать для управления генерацией изображения. Игнорируется, если true_cfg_scale не больше 1.
  • true_cfg_scale (float, необязательный, по умолчанию 1.0) — Масштаб классификаторно-свободного управления. Включается при true_cfg_scale > 1 в сочетании с отрицательным промптом. Qwen-Image 2.1 предназначен для выборки без управления, поэтому значение по умолчанию равно 1.0.
  • height (int, необязательный) — Высота генерируемого изображения в пикселях. Если не указано, вычисляется на основе соотношения сторон исходного изображения.
  • width (int, необязательный) — Ширина генерируемого изображения в пикселях. Если не указано, вычисляется на основе соотношения сторон исходного изображения.
  • num_inference_steps (int, необязательный, по умолчанию 40) — Количество шагов денойзинга. Игнорируется, если используется sigmas или настроенный для пайплайна sample_sigmas; длина этого расписания определяет количество шагов.
  • sigmas (list[float], необязательный) — Сигмы для выборки, которые следует использовать в этом вызове, за исключением конечной сигмы. Переопределяет настроенные для пайплайна sample_sigmas и определяет количество шагов денойзинга. Планировщик применяет к этим значениям свою настроенную обработку.
  • num_images_per_prompt (int, необязательный, по умолчанию 1) — Количество изображений, генерируемых для каждого промпта.
  • generator (torch.Generator или list[torch.Generator], необязательный) — Генератор(ы) для обеспечения детерминированности генерации.
  • latents (torch.Tensor, необязательный) — Предварительно сгенерированные зашумленные латенты.
  • prompt_embeds (torch.Tensor, необязательный) — Предварительно сгенерированные текстовые эмбеддинги, позволяющие пропустить кодирование промпта. Передавайте вместе с ними prompt_embeds_mask.
  • prompt_embeds_mask (torch.Tensor, необязательный) — Маска типа Bool, отмечающая валидные позиции в prompt_embeds.
  • negative_prompt_embeds (torch.Tensor, необязательный) — Предварительно сгенерированные отрицательные текстовые эмбеддинги, используемые вместо negative_prompt. Передавайте вместе с ними negative_prompt_embeds_mask.
  • negative_prompt_embeds_mask (torch.Tensor, необязательный) — Bool-маска, отмечающая валидные позиции в negative_prompt_embeds.
  • output_type (str, необязательный, по умолчанию "pil") — Формат вывода: "pil", "np", "pt" или "latent".
  • return_dict (bool, необязательный, по умолчанию True) — Определяет, следует ли возвращать ~pipelines.qwenimage.QwenImagePipelineOutput вместо обычного кортежа.
  • attention_kwargs (dict, необязательный) — Передаётся в процессор внимания.
  • callback_on_step_end (Callable, необязательный) — Вызывается в конце каждого шага денойзинга.
  • callback_on_step_end_tensor_inputs (list[str], необязательный, по умолчанию ["latents"]) — Тензоры из цикла денойзинга, передаваемые в callback_on_step_end. Они должны быть перечислены в _callback_tensor_inputs пайплайна.
  • output_resolution (int, необязательный, по умолчанию 1024) — Целевая длина стороны, используемая для определения height/width и изменения размера условных изображений.
  • use_kv_cache (bool, необязательный, по умолчанию True) — Кэшировать ключи и значения для текста и условного изображения после первого шага. Это допустимо, так как causal_condition модулирует эти токены начиная с t = 0, что делает их активации независимыми от шага. Изменение этого параметра не воспроизводит то же самое изображение побитово в пониженной точности. Кэширование приводит к тому, что шаг декодирования обращается к последовательности с другой структурой, чем шаг префилла, из-за чего они по-разному разбиваются на тайлы и попадают под разные округления; оба варианта совпадают с эталоном fp32 с одинаковой точностью. Разница в один ULP на первом блоке затем усиливается 32 блоками и каждым шагом сэмплера, поэтому оба режима дают равнозначные, но визуально различимые выборки. Чтобы зафиксировать выборку, зафиксируйте этот флаг.

    Переключение этого параметра не воспроизводит изображение побитово в пониженной точности. Кэширование заставляет этап декодирования обращать внимание с другой раскладкой последовательности, чем этап префилла, поэтому тайлы формируются по-разному и попадают на разные значения округления; оба варианта совпадают с эталоном fp32 в пределах той же допустимой погрешности. Различие в один ULP на первом блоке затем усиливается 32 блоками и каждым шагом сэмплера, в результате чего два режима дают одинаково валидные, но визуально различимые сэмплы. Чтобы зафиксировать сэмпл, зафиксируйте этот флаг.

Возвращает

~pipelines.qwenimage.QwenImagePipelineOutput или tuple

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

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

Примеры:

>>> import torch
>>> from diffusers import QwenImage21Pipeline

>>> pipe = QwenImage21Pipeline.from_pretrained("Qwen/Qwen-Image-2.1", dtype=torch.bfloat16)
>>> pipe.to("cuda")
>>> prompt = "A capybara wearing a wizard hat, reading a book by candlelight, oil painting"
>>> image = pipe(prompt).images[0]
>>> image.save("qwenimage21.png")

encode_prompt

< >

( prompt: str | list[str]image: list[typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]] | None = Nonedevice: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Noneimage_pad_mask: typing.Optional[torch.Tensor] = None )

Параметры

  • prompt (str или list[str], необязательный) — Промпт для кодирования.
  • image (list[PipelineImageInput], необязательный) — Условные изображения для кодирования вместе с промптом.
  • device (torch.device) — Устройство Torch.
  • num_images_per_prompt (int) — Количество изображений, генерируемых на один промпт.
  • prompt_embeds (torch.Tensor, необязательный) — Предварительно сгенерированные текстовые эмбеддинги. Если переданы, кодирование пропускается.

QwenImagePipelineOutput

класс diffusers.pipelines.qwenimage.pipeline_output.QwenImagePipelineOutput

< >

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

Параметры

  • images (list[PIL.Image.Image] или np.ndarray) — список денойзированных изображений PIL длиной batch_size или массив numpy с формой (batch_size, height, width, num_channels). Изображения PIL или массив numpy представляют денойзированные изображения диффузионного конвейера.

Класс вывода для пайплайнов Stable Diffusion.

QwenImage21ModularPipeline

класс diffusers.QwenImage21ModularPipeline

< >

( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )

Модульный ModularPipeline для Qwen-Image 2.1.

QwenImage21AutoBlocks

класс diffusers.QwenImage21AutoBlocks

< >

( )

Auto Модульный конвейер для генерации изображений по тексту и условной генерации на основе изображений с использованием Qwen-Image 2.1.

  • для генерации изображений по тексту достаточно указать prompt
  • для генерации с условием по изображению необходимо указать prompt и image (одно изображение или список)

Поддерживаемые рабочие процессы:

  • text2image: требуется prompt
  • image_conditioned: требуется prompt, image

Компоненты: image_processor (VaeImageProcessor) text_encoder (Qwen3VLForConditionalGeneration) processor (Qwen3VLProcessor) vae (AutoencoderKLQwenImage21) scheduler (FlowMatchEulerDiscreteScheduler) guider (ClassifierFreeGuidance) transformer (QwenImage21Transformer2DModel)

Входные данные: image (Image | list, необязательный): Справочное изображение или список изображений для процесса денойзинга. Может быть одним изображением или списком изображений. output_resolution (int, необязательный, по умолчанию 1024): Целевая длина стороны, используемая для определения размера выходного изображения и изменения размера условных изображений. prompt (str): Промпт или промпты для управления генерацией изображения. negative_prompt (str, необязательный): Промпт или промпты, которые не должны направлять генерацию изображения. generator (Generator, необязательный): Генератор Torch для детерминированной генерации. num_images_per_prompt (int, необязательный, по умолчанию 1): Количество изображений для генерации на каждый промпт. height (int, необязательный): Высота сгенерированного изображения в пикселях. width (int, необязательный): Ширина сгенерированного изображения в пикселях. image_latents (list, необязательный): Нормализованные латенты каждого условного изображения. Могут быть сгенерированы на шаге vae_encoder. latents (Tensor): Предварительно сгенерированные шумовые латенты для генерации изображения. num_inference_steps (int): Количество шагов денойзинга. sigmas (list, необязательный): Пользовательские сигмы для процесса денойзинга. use_kv_cache (bool, необязательный, по умолчанию True): Кэшировать ключи и значения текста и условных изображений после первого шага. Это допустимо, так как causal_condition модулирует эти токены начиная с t = 0, что делает их активации независимыми от шага. Переключение этого параметра не воспроизводит то же самое изображение побитово в режиме пониженной точности. attention_kwargs (dict, необязательный): Дополнительные аргументы для процессоров внимания. *denoiser_input_fields (None,необязательный): входные данные условной модели для денойзера: например, prompt_embeds, negative_prompt_embeds и т. д. output_type (str,необязательный*, по умолчанию pil): Формат вывода: ‘pil’, ‘np’, ‘pt’.

Вывод: images (list): Сгенерированные изображения.

QwenImage21TurboModularPipeline

класс diffusers.QwenImage21TurboModularPipeline

< >

( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )

ModularPipeline для Qwen-Image 2.1 Turbo — ускоренная контрольная точка, которая генерирует образы за несколько шагов без направляющего сигнала.

QwenImage21TurboAutoBlocks

класс diffusers.QwenImage21TurboAutoBlocks

< >

( )

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

  • для генерации изображений по тексту достаточно указать prompt
  • для генерации с условием по изображению необходимо указать prompt и image (одно изображение или список)

Поддерживаемые рабочие процессы:

  • text2image: требуется prompt
  • image_conditioned: требуется prompt, image

Компоненты: image_processor (VaeImageProcessor) text_encoder (Qwen3VLForConditionalGeneration) processor (Qwen3VLProcessor) vae (AutoencoderKLQwenImage21) scheduler (FlowMatchEulerDiscreteScheduler) transformer (QwenImage21Transformer2DModel)

Конфигурации: sample_sigmas (по умолчанию: None): сетка дискретизации, поставляемая с контрольной точкой, используется, если sigmas не передан.

Входные данные: image (Image | list, необязательный): Справочное изображение или список изображений для процесса денойзинга. Может быть одним изображением или списком изображений. output_resolution (int, необязательный, по умолчанию 1024): Целевая длина стороны, используемая для определения размера выходного изображения и изменения размера условных изображений. prompt (str): Промпт или промпты для управления генерацией изображений. generator (Generator, необязательный): Генератор Torch для детерминированной генерации. num_images_per_prompt (int, необязательный, по умолчанию 1): Количество изображений, генерируемых на каждый промпт. height (int, необязательный): Высота генерируемого изображения в пикселях. width (int, необязательный): Ширина генерируемого изображения в пикселях. image_latents (list, необязательный): Нормализованные латенты каждого условного изображения. Могут быть получены на шаге vae_encoder. latents (Tensor): Предварительно сгенерированные шумовые латенты для генерации изображений. num_inference_steps (int): Количество шагов денойзинга. sigmas (list, необязательный): Пользовательские сигмы для процесса денойзинга. use_kv_cache (bool, необязательный, по умолчанию True): Кэшировать ключи и значения текста и условных изображений после первого шага. Это допустимо, так как causal_condition модулирует эти токены начиная с t = 0, что делает их активации независимыми от шага. Переключение этого параметра не воспроизводит то же самое изображение побитово в режиме пониженной точности. attention_kwargs (dict, необязательный): Дополнительные аргументы для процессоров внимания. *denoiser_input_fields (None,необязательный): входные данные условной модели для денойзера: например, prompt_embeds, negative_prompt_embeds и т. д. output_type (str,необязательный*, по умолчанию pil): Формат вывода: ‘pil’, ‘np’, ‘pt’.

Вывод: images (list): Сгенерированные изображения.

Update on GitHub

←PRX Pixel QwenImage→