Hugging Face's logo

Diffusers documentation

Flux2

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Flux2

LoRA MPS

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

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

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

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

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

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

Flux2Pipeline

класс diffusers.Flux2Pipeline

< >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLFlux2text_encoder: Mistral3ForConditionalGenerationtokenizer: AutoProcessortransformer: 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__

< >

( image: PIL.Image.Image | list[PIL.Image.Image] | None = Noneprompt: str | list[str] = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 50sigmas: list[float] | None = Noneguidance_scale: float | None = 4.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] = 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 = 512text_encoder_out_layers: tuple[int] = (10, 20, 30)caption_upsample_temperature: float = None ) → ~pipelines.flux2.Flux2PipelineOutput 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 вместо него.
  • guidance_scale (float, необязательный, по умолчанию 1.0) — Встроенный масштаб guidance включается при установке guidance_scale > 1. Более высокое значение guidance_scale поощряет модель генерировать изображения, более точно соответствующие prompt , в ущерб качеству изображения.

    Модели, полученные с помощью дистилляции guidance, аппроксимируют истинный classifer-free guidance для guidance_scale > 1. Подробнее см. в статье.

  • 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. Если не задано, будет использоваться поведение по умолчанию при передаче 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

< >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLFlux2text_encoder: Qwen3ForCausalLMtokenizer: Qwen2Tokenizertransformer: Flux2Transformer2DModelis_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__

< >

( image: list[PIL.Image.Image] | PIL.Image.Image | None = Noneprompt: str | list[str] = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 50sigmas: list[float] | None = Noneguidance_scale: float = 4.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] = Nonenegative_prompt_embeds: str | list[str] | None = Noneoutput_type: str = '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']max_sequence_length: int = 512text_encoder_out_layers: tuple[int] = (9, 18, 27) ) → ~pipelines.flux2.Flux2PipelineOutput 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 вместо него.
  • guidance_scale (float, необязательный, по умолчанию 4.0) — Масштаб руководства, определенный в Classifier-Free Diffusion Guidance. guidance_scale определяется как w из уравнения 2 статьи Imagen Paper. Масштаб руководства включается при установке guidance_scale > 1. Более высокий масштаб руководства способствует генерации изображений, тесно связанных с текстом prompt, обычно за счет снижения качества изображения. Для пошагово дистиллированных моделей guidance_scale игнорируется.
  • 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. Если не задано, будет использовано поведение по умолчанию при передаче 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

< >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLFlux2text_encoder: Qwen3ForCausalLMtokenizer: Qwen2Tokenizertransformer: Flux2Transformer2DModelis_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__

< >

( image: list[PIL.Image.Image] | PIL.Image.Image | None = Noneprompt: str | list[str] = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 4sigmas: 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] = Noneoutput_type: str = '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']max_sequence_length: int = 512text_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, необязательный, по умолчанию 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]) — Индексы слоёв для извлечения скрытых состояний текстового кодировщика.

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

Примеры:

>>> 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")
Update on GitHub

←Flux Flux3→