FLUX 3 Image Klein

FLUX 3 Image Klein — это модель генерации изображений с 5,6 млрд параметров от Black Forest Labs: единый трансформер (Flux3Transformer2DModel) генерирует изображения по текстовому запросу, как самостоятельно, так и в сочетании с одним или несколькими референсными изображениями. Текстовое условие формируется с помощью Qwen3-VL, а для изображений используется упакованный автоэнкодер FLUX.2 (AutoencoderKLFlux2).

FLUX 3 Image Klein поставляется в виде модульного конвейера. Начните с генерации изображения по тексту:

import torch
from diffusers import ModularPipeline

pipe = ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein-base")
pipe.load_components(dtype={"vae": torch.float32, "default": torch.bfloat16})
pipe.to("cuda")

image = pipe(
    prompt="A red fox in a snow-covered forest clearing at golden hour",
    generator=torch.Generator().manual_seed(0),
    output="images",
)[0]
image.save("fox.png")

prompt — единственный обязательный входной параметр: конвейер использует рекомендуемые настройки выборки (50 шагов, guidance scale 3.5, scheduler shift 6.93) и по умолчанию генерирует изображения размером 1024 x 1024. За один вызов принимается один промпт; для получения нескольких изображений по одному промпту используйте num_images_per_prompt.

As you can see in the example above, loading and running differ a little from a DiffusionPipeline. Loading is lazy: from_pretrained() only builds the pipeline, and you call load_components() to load the weights. A call returns the pipeline state, and you ask for what you need with output: output="images" here, or output=["images", "prompt"] to also get the caption the prompt upsampler wrote.

Если вы впервые работаете с ModularPipeline, прочитайте быстрый старт, а если вы знакомы со стандартными пайплайнами — Переход из DiffusionPipeline. Помимо загрузки и вывода, есть несколько других отличий: guidance, callbacks и offloading.

Увеличение размера промпта

Промпт имеет значение: FLUX 3 Image Klein принимает полные описания сцены, в которых указаны объект, композиция, освещение и атмосфера, а не короткие запросы; запрос, отправленный в исходном виде, приводит к общему результату. Именно поэтому конвейер сначала запускает апгрейдер промпта для каждого запроса, будь то генерация изображения по тексту или редактирование. Это отдельная 9B-модель от Black Forest Labs (black-forest-labs/flux-3-image-klein-pup), которая расширяет prompt до такого описания перед текстовым энкодером, поэтому достаточно короткого промпта.

Модель-апгрейдер промпта превращает короткий запрос, а при редактировании — вместе с референсными изображениями, в полное описание сцены, которое получает модель: средний план и стиль, сцена, освещение и камера, каждый объект с его цветами, материалами и позицией в кадре. Одна модель покрывает генерацию изображений по тексту, редактирование с референсными изображениями и компоновку с использованием рамок. Написанное ею описание возвращается как вывод prompt. В примере выше запросите его вместе с изображениями, чтобы увидеть, что получила модель изображений:

out = pipe(
    prompt="A red fox in a snow-covered forest clearing at golden hour",
    generator=torch.Generator().manual_seed(0),
    output=["images", "prompt"],
)
print(out["prompt"])

Full-color outdoor wildlife photograph taken from a low eye-level perspective in a snow-covered forest clearing at golden hour. In the center foreground, a red fox stands in profile facing left, its body turned toward the viewer and its head raised as it looks across the clearing. The fox has dense rust-red winter fur, a white throat and chest, black lower legs, pointed ears with dark tips, and a long bushy tail ending in white. ...

Полное описание занимает около 240 слов; max_new_tokens ограничивает его длину (по умолчанию 3584).

Вы можете вывести doc шага, чтобы увидеть, что он принимает и что записывает:

print(pipe.blocks.sub_blocks["prompt_upsampler"].doc)

  Inputs:
      prompt (`str`):
          The edit instruction to expand into the full caption (one per call).
      image (`Image | list`, *optional*):
          The reference image(s) of the edit, at most 10; the same ones the pipeline receives.
      boxes (`list`, *optional*):
          Layout boxes, each {'id', 'desc', 'from', 'src_bbox', 'tgt_bbox'} with the boxes as [y_min, x_min, y_max, x_max] in
          0-1: ...
      max_new_tokens (`int`, *optional*, defaults to 3584):
          The most tokens the upsampler may generate for the caption.

  Outputs:
      prompt (`str`):
          The full caption, replacing the request.

Как и другие блоки в конвейере, блок prompt_upsampler также выполняется самостоятельно. Рекомендуемый способ — вынуть его из блоков: вынутый блок становится автономным апсемплером, а оставшиеся блоки образуют конвейер, который принимает расширенный описатель как prompt:

blocks = ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein-base").blocks
pup_block = blocks.sub_blocks.pop("prompt_upsampler")

pup = pup_block.init_pipeline("black-forest-labs/flux-3-image-klein-base")
pup.load_components(dtype=torch.bfloat16)
pup.to("cuda")
caption = pup(prompt="A red fox in a snow-covered forest clearing at golden hour", output="prompt")

pipe = blocks.init_pipeline("black-forest-labs/flux-3-image-klein-base")
pipe.load_components(dtype={"vae": torch.float32, "default": torch.bfloat16})
pipe.to("cuda")
image = pipe(prompt=caption, generator=torch.Generator().manual_seed(0), output="images")[0]

Таким образом, его можно использовать как отдельный этап, на собственном GPU или за собственным endpoint, а UI может отображать сгенерированное описание и позволять пользователю отредактировать его перед генерацией. На место upsampler можно поставить любую другую LLM, используя те же системные промпты: передайте ей system_prompts["t2i"] из репозитория upsampler (или "i2i", при этом ссылки должны идти в начале пользовательского сообщения) в качестве системного промпта, а запрос — в качестве пользовательского сообщения, и передайте возвращённое описание как prompt в pipe.

Изображение в изображение

Передайте одно или несколько эталонных изображений с помощью image. Одно эталонное изображение сохраняется целиком: оно уменьшается только при размере более 4 мегапикселей, дополняется до сетки 16 пикселей, а по умолчанию генерация выполняется в его размере, поэтому результат редактирования имеет размер исходного изображения. Несколько эталонных изображений приводятся к размеру менее 1 мегапикселя каждое и обрезаются по сетке, а по умолчанию генерация выполняется в размере первого из них. Указанные height/width переопределяют значения по умолчанию. Опишите целевое изображение как полную подпись к эталонному с включённым в неё редактированием, а не как однострочную инструкцию, либо позвольте prompt upsampler составить её на основе инструкции и эталонных изображений:

night = pipe(
    prompt="the same scene at night under a full moon",
    image=image,
    generator=torch.Generator().manual_seed(0),
    output=["images", "prompt"],
)

При наличии нескольких ссылок обращайтесь к ним как к первому изображению, второму изображению, … в том порядке, в котором они передаются в image; в подписи для модели изображений они обозначаются как <ref_image_0>, <ref_image_1>, …:

combined = pipe(
    prompt="the fox from the first image sitting on the wooden bench from the second image",
    image=[image, bench],
    height=768,
    width=1360,
    output="images",
)[0]

Передайте height и/или width, чтобы переопределить вычисленный размер.

Управление макетом

Чтобы явно разместить контент, передайте boxes: для каждого элемента укажите id, краткое desc и bbox в формате [y_min, x_min, y_max, x_max] в диапазоне 0–1 (начало координат — левый верхний угол), чтобы результат не зависел от размера вывода. Апсемплер размещает подпись вокруг них, ссылаясь на каждый элемент как <id>, и добавляет таблицу с координатами, сохраняя ваши значения без изменений:

boxes = [
    {"id": "balloon_1", "desc": "a red and yellow striped hot-air balloon", "bbox": [0.08, 0.06, 0.48, 0.38]},
    {"id": "balloon_2", "desc": "a small blue hot-air balloon", "bbox": [0.20, 0.62, 0.42, 0.80]},
]
out = pipe(prompt="hot-air balloons over a green valley at sunrise", boxes=boxes, output=["images", "prompt"])

При редактировании поле указывает источник с помощью from: "target" с tgt_bbox добавляет новый элемент в это место, "ref_image_0" с src_bbox и tgt_bbox перемещает элемент из этого эталонного изображения (равные поля оставляют его на месте):

boxes = [{"id": "cactus", "desc": "a small potted cactus", "from": "target", "src_bbox": None, "tgt_bbox": [0.55, 0.62, 0.85, 0.85]}]
out = pipe(prompt="add a small potted cactus in the marked spot", image=mug, boxes=boxes, output=["images", "prompt"])

boxes = [{"id": "knight", "desc": "the knight figure", "from": "ref_image_0", "src_bbox": [0.50, 0.15, 0.85, 0.35], "tgt_bbox": [0.19, 0.06, 0.54, 0.26]}]
out = pipe(prompt="move the knight up and to the left, keep the rest unchanged", image=knight, boxes=boxes, output=["images", "prompt"])

Подпись, которую читает модель изображения, содержит элементы, помеченные в тексте как <id>, а также таблицу, добавленную в формате JSON, где координаты ячеек указаны в системе координат 0–1000; для просмотра содержимого выведите результат prompt. Подпись, написанная вручную в таком формате, передаётся в конвейер без этого шага, как описано в разделе Улучшение промпта.

Масштаб направляющего сигнала

Пайплайн применяет классификаторно-свободное управление (classifier-free guidance) через свой компонент guider и не принимает аргумент guidance_scale во время вызова. По умолчанию используется ClassifierFreeGuidance с guidance_scale=3.5, что является рекомендуемым значением для обоих рабочих процессов. Чтобы изменить его, создайте обновлённую копию guider:

pipe.guider = pipe.guider.new(guidance_scale=5.0)

См. руководство по guider, чтобы переключиться на другой метод guidance.

Модель с дистилляцией по шагам

Чекпоинт, полученный с помощью дистилляции шагов, генерирует результат за 16 шагов без классификаторного свободного руководства. Его трансформер представляет собой flow map: на каждом шаге ему сообщаются текущий временной шаг и тот, к которому шаг перескакивает. Он загружается так же, как базовая модель (файл modular_model_index.json в репозитории указывает на Flux3DistilledModularPipeline и Flux3DistilledAutoBlocks); в пайплайне нет guider, и он не принимает negative_prompt:

pipe = ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein")
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")

image = pipe(prompt=prompt, generator=torch.Generator().manual_seed(0), output="images")[0]

Он поддерживает те же два сценария использования, что и базовая модель. num_inference_steps по умолчанию равно 16; модель обучена для 4–16 шагов.

Воспроизводимая генерация

Генератор generator фиксирует шум, который извлекает конвейер (см. Воспроизводимость). Чтобы переиспользовать шум, извлеченный в другом месте, передайте его как latents с формой (batch_size, 128, height // 16, width // 16). Например, реализация BFL извлекает шум в виде токенов изображения на CPU и преобразует его в bf16; это позволяет воспроизвести ее образец для заданного seed:

height, width = 1024, 1024
h, w = height // 16, width // 16

noise = torch.randn((h * w, 128), generator=torch.Generator().manual_seed(0)).to(torch.bfloat16)
latents = noise.T.reshape(1, 128, h, w)

image = pipe(prompt=prompt, latents=latents, height=height, width=width, output="images")[0]

Рабочие процессы

Пайплайн поддерживает два рабочих процесса: text2image и image_conditioned; тот, который будет выполнен, определяется входными данными (image выбирает image-to-image). Метод from_pretrained() также может создать пайплайн для одного рабочего процесса с помощью аргумента workflow, при этом он ожидает и загружает только те компоненты, которые нужны этому рабочему процессу:

from diffusers.modular_pipelines import Flux3AutoBlocks

print(Flux3AutoBlocks().available_workflows)
# ["text2image", "image_conditioned"]

t2i = ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein-base", workflow="text2image")
print(t2i.blocks.doc)

Обработчики на каждом шаге

Чтобы использовать существующую функцию обратного вызова, вставьте блок в цикл денойзинга. В руководстве по callback-функциям приведён простой пример с блоком CallbackOnStepEnd и вспомогательной функцией walk_denoise_loops:

blocks = Flux3AutoBlocks()  # or Flux3DistilledAutoBlocks
for loop in walk_denoise_loops(blocks):
    loop.sub_blocks["callback"] = CallbackOnStepEnd()
pipe = blocks.init_pipeline("black-forest-labs/flux-3-image-klein-base")

image = pipe(prompt=caption, callback_on_step_end=my_callback, output="images")[0]

Чтобы остановить процесс досрочно, вызовите исключение из колбэка; флаг interrupt отсутствует.

Память

Загрузка всего в bf16 занимает около 39 ГБ весов: трансформер содержит 5,5 млрд параметров, текстовый энкодер Qwen3-VL-4B — 4 млрд, а prompt upsampler — 9 млрд (около 19 ГБ отдельно), при этом image VAE находится в fp32. Пайплайн, собранный без шага upsampler (см. там), загружает около 20 ГБ. Для GPU с меньшим объемом памяти включите offloading компонентов; менеджер перемещает компоненты между CPU и GPU по мере необходимости на каждом шаге, включая upsampler:

from diffusers import ComponentsManager, ModularPipeline

manager = ComponentsManager()
pipe = ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein-base", components_manager=manager)
pipe.load_components(dtype={"vae": torch.float32, "default": torch.bfloat16})
manager.enable_auto_cpu_offload(device="cuda")

Загрузка из одного файла

Flux3Transformer2DModel загружает трансформер напрямую из пакета модели Black Forest Labs с помощью from_single_file(). Файл config.json не читается; передайте конфигурацию diffusers через параметры config и subfolder.

import torch
from diffusers import Flux3Transformer2DModel, ModularPipeline

transformer = Flux3Transformer2DModel.from_single_file(
    "https://huggingface.co/black-forest-labs/flux-3-image-klein-base/blob/main/model.safetensors",
    config="black-forest-labs/flux-3-image-klein-base",
    subfolder="transformer",
    dtype=torch.bfloat16,
)

pipe = ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein-base")
pipe.load_components(dtype={"vae": torch.float32, "default": torch.bfloat16})
pipe.update_components(transformer=transformer)
pipe.to("cuda")

Сначала загрузите остальные компоненты по имени: load_components() без names также загрузил бы трансформер из репозитория пайплайна.

Также поддерживается загрузка контрольных точек FP8r и NVFP4 в формате одного файла. Оба варианта загружаются через один и тот же вызов с BFLQuantizationConfig. Требования к ядрам для каждой схемы описаны в руководстве по квантованию BFL.

from diffusers import BFLQuantizationConfig

transformer = Flux3Transformer2DModel.from_single_file(
    "https://huggingface.co/black-forest-labs/flux-3-image-klein-base/blob/main/variants/nvfp4/model.safetensors",
    config="black-forest-labs/flux-3-image-klein-base",
    subfolder="transformer",
    quantization_config=BFLQuantizationConfig(compute_dtype=torch.bfloat16),
    dtype=torch.bfloat16,
)

При загрузке чекпоинтов, полученных с помощью дистилляции по шагам, нам необходимы их конфигурации (flow_map=True):

transformer = Flux3Transformer2DModel.from_single_file(
    "https://huggingface.co/black-forest-labs/flux-3-image-klein/blob/main/variants/nvfp4/model.safetensors",
    config="black-forest-labs/flux-3-image-klein",
    subfolder="transformer",
    quantization_config=BFLQuantizationConfig(compute_dtype=torch.bfloat16),
    dtype=torch.bfloat16,
)

Flux3ModularPipeline

Flux3AutoBlocks

Flux3DistilledAutoBlocks

Flux3DistilledModularPipeline