Hugging Face's logo

Diffusers documentation

Qwen-Image 2.1

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
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 = ['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→