diffusers/main/ru/api/pipelines/flux2.md

Flux2

Flux.2 — это недавняя серия моделей генерации изображений от Black Forest Labs, предшественником которой была серия Flux.1. Это совершенно новая модель с новой архитектурой, обученная с нуля!

Оригинальные контрольные точки модели Flux можно найти здесь. Исходный код для инференса доступен здесь.

Запуск Flux2 на потребительском оборудовании может быть довольно затратным. Однако вы можете применить набор оптимизаций, чтобы ускорить работу и снизить требования к памяти. Подробности изложены в этом разделе. Кроме того, Flux может выиграть от квантования с точки зрения эффективности использования памяти, что, однако, приводит к увеличению задержки вывода. Подробнее см. в этой статье.

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

Увеличение разрешения подписей

Flux.2 потенциально способен генерировать более качественные результаты при использовании улучшенных промптов. Мы можем «апсэмплировать» входной промпт, задав аргумент caption_upsample_temperature в параметрах вызова пайплайна. Официальная реализация рекомендует использовать значение 0.15.

Flux2Pipeline[[diffusers.Flux2Pipeline]]

diffusers.Flux2Pipeline[[diffusers.Flux2Pipeline]]

diffusers.Flux2Pipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLFlux2, text_encoder: Mistral3ForConditionalGeneration, tokenizer: AutoProcessor, transformer: Flux2Transformer2DModel)

Источник

Параметры:

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

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

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

text_encoder (Mistral3ForConditionalGeneration) : Mistral3ForConditionalGeneration

tokenizer (AutoProcessor) : Токенизатор класса PixtralProcessor.

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

Справочная информация: https://bfl.ai/blog/flux-2

call[[diffusers.Flux2Pipeline.call]]

__call__(image: PIL.Image.Image | list[PIL.Image.Image] | None = None, prompt: str | list[str] = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, sigmas: list[float] | None = None, guidance_scale: float | None = 4.0, 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, 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, text_encoder_out_layers: tuple[int] = (10, 20, 30), caption_upsample_temperature: float = None)

Источник

Параметры:

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 вместо него.

guidance_scale (float, optional, по умолчанию 1.0) : Встроенный масштаб руководства (embedded guidance scale) включается при установке guidance_scale > 1. Более высокое значение guidance_scale побуждает модель генерировать изображения, более точно соответствующие prompt, за счёт снижения качества изображения. Модели, дистиллированные по руководству (guidance-distilled), аппроксимируют истинное классификаторно-свободное руководство (classifier-free guidance) для guidance_scale > 1. Подробнее см. в статье.

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.

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

generator (torch.Generator или list[torch.Generator], необязательный) : Один или список генераторов torch для обеспечения детерминированности генерации.

latents (torch.Tensor, необязательный) : Предварительно сгенерированные зашумленные латенты, выбранные из гауссова распределения, которые используются в качестве входных данных для генерации изображений. Можно использовать, чтобы скорректировать одну и ту же генерацию с разными промптами. Если не предоставлены, тензор латентов будет сгенерирован путём выборки с использованием переданного случайного generator.

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

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, необязательный) : Список тензорных входных данных для функции callback_on_step_end. Тензоры, указанные в списке, будут переданы в качестве аргумента callback_kwargs. Вы сможете включать только переменные, перечисленные в атрибуте ._callback_tensor_inputs вашего класса конвейера.

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

text_encoder_out_layers (tuple[int]) : Индексы слоёв, используемые в text_encoder для получения финальных эмбеддингов промпта.

caption_upsample_temperature (float) : Если указано, мы будем пытаться выполнять апсемплинг подписей для потенциального улучшения результатов. Мы рекомендуем установить значение 0.15, если планируется выполнение апсемплинга подписей.

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

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

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

Примеры:

>>> import torch
>>> from diffusers import Flux2Pipeline

>>> pipe = Flux2Pipeline.from_pretrained("black-forest-labs/FLUX.2-dev", 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, guidance_scale=2.5).images[0]
>>> image.save("flux.png")

Flux2KleinPipeline[[diffusers.Flux2KleinPipeline]]

diffusers.Flux2KleinPipeline[[diffusers.Flux2KleinPipeline]]

diffusers.Flux2KleinPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLFlux2, text_encoder: Qwen3ForCausalLM, tokenizer: Qwen2Tokenizer, transformer: Flux2Transformer2DModel, is_distilled: bool = False)

Источник

Параметры:

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

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

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

text_encoder (Qwen3ForCausalLM) : Qwen3ForCausalLM

tokenizer (Qwen2TokenizerFast) : Токенизатор класса Qwen2TokenizerFast.

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

Ссылка: https://bfl.ai/blog/flux2-klein-towards-interactive-visual-intelligence

call[[diffusers.Flux2KleinPipeline.call]]

__call__(image: list[PIL.Image.Image] | PIL.Image.Image | None = None, prompt: str | list[str] = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, sigmas: list[float] | None = None, guidance_scale: float = 4.0, 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, negative_prompt_embeds: str | list[str] | None = None, output_type: str = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], max_sequence_length: int = 512, text_encoder_out_layers: tuple[int] = (9, 18, 27))

Источник

Параметры:

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 вместо него.

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

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], необязательный) : Пользовательские сигмы для процесса денуазинга в планировщиках, поддерживающих аргумент sigmas в методе set_timesteps. Если не задано, будет использоваться поведение по умолчанию при передаче num_inference_steps.

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

generator (torch.Generator или List[torch.Generator], необязательный) : Один или список генераторов torch для обеспечения детерминированности генерации.

latents (torch.Tensor, необязательный) : Предварительно сгенерированные зашумленные латенты, выбранные из гауссова распределения, которые используются в качестве входных данных для генерации изображений. Можно использовать, чтобы скорректировать одну и ту же генерацию с разными промптами. Если не предоставлены, тензор латентов будет сгенерирован путём выборки с использованием переданного случайного generator.

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

negative_prompt_embeds (torch.Tensor, необязательный) : Предварительно сгенерированные отрицательные текстовые эмбеддинги. Обратите внимание, что в этом конвейере в качестве отрицательного промпта используется "". Если значение не указано, оно будет сгенерировано из "".

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, необязательный) : Список тензорных входных данных для функции callback_on_step_end. Тензоры, указанные в списке, будут переданы в качестве аргумента callback_kwargs. Вы сможете включать только переменные, перечисленные в атрибуте ._callback_tensor_inputs вашего класса конвейера.

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

text_encoder_out_layers (tuple[int]) : Индексы слоёв, используемые в text_encoder для получения финальных эмбеддингов промпта.

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

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

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

Примеры:

>>> import torch
>>> from diffusers import Flux2KleinPipeline

>>> pipe = Flux2KleinPipeline.from_pretrained(
...     "black-forest-labs/FLUX.2-klein-base-9B", 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, guidance_scale=4.0).images[0]
>>> image.save("flux2_output.png")

Flux2KleinKVPipeline[[diffusers.Flux2KleinKVPipeline]]

diffusers.Flux2KleinKVPipeline[[diffusers.Flux2KleinKVPipeline]]

diffusers.Flux2KleinKVPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLFlux2, text_encoder: Qwen3ForCausalLM, tokenizer: Qwen2Tokenizer, transformer: Flux2Transformer2DModel, is_distilled: bool = True)

Источник

Параметры:

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

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

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

text_encoder (Qwen3ForCausalLM) : Qwen3ForCausalLM

tokenizer (Qwen2TokenizerFast) : Токенизатор класса Qwen2TokenizerFast.

Пайплайн Flux2 Klein KV для генерации изображений по тексту с использованием KV-кэшированного условия на основе референсного изображения.

На первом шаге удаления шума токены опорного изображения включаются в прямой проход, а их проекции K/V внимания кэшируются. На последующих шагах кэшированные K/V переиспользуются без повторного вычисления, что обеспечивает более быстрый вывод при использовании опорных изображений.

Ссылка: https://bfl.ai/blog/flux2-klein-towards-interactive-visual-intelligence

call[[diffusers.Flux2KleinKVPipeline.call]]

__call__(image: list[PIL.Image.Image] | PIL.Image.Image | None = None, prompt: str | list[str] = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 4, sigmas: list[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, output_type: str = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], max_sequence_length: int = 512, text_encoder_out_layers: tuple[int] = (9, 18, 27))

Источник

Параметры:

image (PIL.Image.Image или List[PIL.Image.Image], необязательный) : Справочное изображение(я) для условного формирования. На первом шаге денойзинга токены справочных изображений включаются в прямой проход, а их значения внимания K/V кэшируются. На последующих шагах кэшированные K/V переиспользуются без повторного вычисления.

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

height (int, необязательный) : Высота генерируемого изображения в пикселях.

width (int, необязательный) : Ширина сгенерированного изображения в пикселях.

num_inference_steps (int, optional, по умолчанию 4) : Количество шагов денойзинга.

sigmas (List[float], необязательный) : Пользовательские сигмы для расписания денойзинга.

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

generator (torch.Generator или List[torch.Generator], необязательный) : Генератор(ы) для детерминированной генерации.

latents (torch.Tensor, необязательный) : Предварительно сгенерированные зашумленные латенты.

prompt_embeds (torch.Tensor, необязательный) : Предварительно сгенерированные текстовые эмбеддинги.

output_type (str, необязательный, по умолчанию "pil") : Формат вывода: "pil" или "np".

return_dict (bool, необязательный, по умолчанию True) : Возвращать ли Flux2PipelineOutput или обычный кортеж.

attention_kwargs (dict, необязательный) : Дополнительные аргументы, передаваемые в обработчики внимания.

callback_on_step_end (Callable, необязательный) : Функция обратного вызова, вызываемая в конце каждого шага удаления шума.

callback_on_step_end_tensor_inputs (List, необязательный) : тензорные входные данные для функции обратного вызова.

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

text_encoder_out_layers (tuple[int]) : Индексы слоёв для извлечения скрытых состояний текстового кодировщика.

Возвращает:

~pipelines.flux2.Flux2PipelineOutput или tuple.

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

Примеры:

>>> import torch
>>> from PIL import Image
>>> from diffusers import Flux2KleinKVPipeline

>>> pipe = Flux2KleinKVPipeline.from_pretrained(
...     "black-forest-labs/FLUX.2-klein-9b-kv", torch_dtype=torch.bfloat16
... )
>>> pipe.to("cuda")
>>> ref_image = Image.open("reference.png")
>>> image = pipe("A cat dressed like a wizard", image=ref_image, num_inference_steps=4).images[0]
>>> image.save("flux2_kv_output.png")