# Krea 2

Krea 2 (K2) — это модель генерации изображений по текстовому описанию на основе flow-matching, построенная вокруг однопоточного MMDiT с группированным запросным вниманием (grouped-query attention). В качестве источника условий используется текстовый энкодер Qwen3-VL: вместо последнего скрытого состояния для каждого токена извлекаются скрытые состояния из двенадцати декодерных слоев, которые затем объединяются внутри трансформера с помощью небольшого этапа текстового слияния (text-fusion). Изображения декодируются с помощью VAE Qwen-Image.

Опубликованы две контрольные точки, использующие одну и ту же архитектуру, но с различными рекомендуемыми настройками сэмплера:

- **Base (midtrain)** — используйте полный сэмплер с классификаторно-свободным наведением: `num_inference_steps=28`, `guidance_scale=4.5`.
- **TDM (distilled)** — дистиллированная модель для сэмплирования за несколько шагов, запускается с `num_inference_steps=8` и отключённым guidance (`guidance_scale=0.0`).

`guidance_scale` следует конвенции Krea 2: скорость вычисляется как `cond + guidance_scale * (cond - uncond)`, а guidance включается, когда `guidance_scale > 0` (это эквивалентно стандартной формулировке CFG с масштабом `1 + guidance_scale`).

## Текст в изображение

```python
import torch
from diffusers import Krea2Pipeline

# Load from a local directory produced by the Krea 2 conversion (no hub repo yet).
pipe = Krea2Pipeline.from_pretrained("krea/Krea-2-Raw", dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

prompt = "a fox in the snow"
image = pipe(
    prompt,
    height=1024,
    width=1024,
    num_inference_steps=28,
    guidance_scale=4.5,
    generator=torch.Generator("cuda").manual_seed(0),
).images[0]
image.save("krea2.png")
```

Кроме того, мы приводим пример использования Krea2 Turbo:

```python
import torch
from diffusers import Krea2Pipeline

pipe = Krea2Pipeline.from_pretrained("krea/Krea-2-Turbo", dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

image = pipe(
    "a fox in the snow",
    height=1024,
    width=1024,
    num_inference_steps=8,
    guidance_scale=0.0,
    generator=torch.Generator("cuda").manual_seed(0),
).images[0]
image.save("krea2_turbo.png")
```

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

```python
import torch
from diffusers import Krea2Pipeline, Krea2Transformer2DModel

transformer = Krea2Transformer2DModel.from_single_file(
    "https://huggingface.co/krea/Krea-2-Turbo/blob/main/turbo.safetensors", dtype=torch.bfloat16
)
pipe = Krea2Pipeline.from_pretrained("krea/Krea-2-Turbo", transformer=transformer, dtype=torch.bfloat16).to("cuda")
```

## Krea2Pipeline[[diffusers.Krea2Pipeline]]

#### diffusers.Krea2Pipeline[[diffusers.Krea2Pipeline]]

```python
diffusers.Krea2Pipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLQwenImage, text_encoder: Qwen3VLModel, tokenizer: AutoTokenizer, transformer: Krea2Transformer2DModel, text_encoder_select_layers: tuple[int, ...] | list[int] | None = None, is_distilled: bool = False, patch_size: int = 2)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/krea2/pipeline_krea2.py#L134)

**Параметры:**

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ru/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : планировщик Euler flow-matching. Расписание сигма для Krea 2 представляет собой экспоненциальный сдвиг времени с учётом разрешения, поэтому в конфигурации планировщика ожидается установка `use_dynamic_shifting=True` вместе с параметрами сдвига Krea 2 (`base_shift=0.5`, `max_shift=1.15`, `base_image_seq_len=256`, `max_image_seq_len=6400`).

vae ([AutoencoderKLQwenImage](/docs/diffusers/main/ru/api/models/autoencoderkl_qwenimage#diffusers.AutoencoderKLQwenImage)) : вариационный автоэнкодер Qwen-Image (f8, 16 латентных каналов), используемый для декодирования латентов в изображения.

text_encoder ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)) : модель Qwen3-VL (например, `Qwen3VLModel` из `Qwen/Qwen3-VL-4B-Instruct`). Конвейер использует стек скрытых состояний, извлечённых из нескольких декодерных слоёв, а не последнее скрытое состояние.

tokenizer ([AutoTokenizer](https://huggingface.co/docs/transformers/main/en/model_doc/auto#transformers.AutoTokenizer)) : токенизатор, используемый вместе с текстовым энкодером.

transformer ([Krea2Transformer2DModel](/docs/diffusers/main/ru/api/models/krea2_transformer2d#diffusers.Krea2Transformer2DModel)) : Однопоточная MMDiT Krea 2, предсказывающая скорость flow-matching.

text_encoder_select_layers (`tuple[int, ...]`, *optional*) : Индексы в кортеже `hidden_states` текстового энкодера (0 — выход эмбеддингов), состояния которых складываются по токенам в качестве текстового условия для трансформера. Должно содержать `transformer.config.num_text_layers` элементов.

is_distilled (`bool`, *необязательный*, по умолчанию `False`) : Указывает, является ли трансформер контрольной точкой с дистилляцией за несколько шагов (TDM/turbo). Если `True`, используется фиксированный сдвиг временного шага `mu=1.15`; в противном случае `mu` вычисляется на основе разрешения изображения.

patch_size (`int`, *optional*, по умолчанию 2) : Длина стороны квадратных патчей, в которые упаковываются латенты перед передачей в трансформер. Эффективный коэффициент даунсемплинга пикселей в токены составляет `vae_scale_factor * patch_size`.

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

#### __call__[[diffusers.Krea2Pipeline.__call__]]

```python
__call__(prompt: str | list[str] | None = None, negative_prompt: str | list[str] | None = None, height: int = 1024, width: int = 1024, num_inference_steps: int = 28, sigmas: list[float] | None = None, guidance_scale: float = 4.5, 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, prompt_embeds_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds_mask: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, callback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], NoneType]] = None, callback_on_step_end_tensor_inputs: list = ['latents'], attention_kwargs: dict[str, typing.Any] | None = None, max_sequence_length: int = 512)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/krea2/pipeline_krea2.py#L445)

**Параметры:**

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

negative_prompt (`str` или `list[str]`, *необязательный*) : Промпт или промпты, которые не следует использовать для управления генерацией изображения. Игнорируется, если `guidance_scale <= 0`; по умолчанию используется пустой промпт, когда управление включено.

height (`int`, по умолчанию 1024) : Высота генерируемого изображения в пикселях. При необходимости округляется вверх до кратного 16.

width (`int`, по умолчанию 1024) : Ширина генерируемого изображения в пикселях. При необходимости округляется вверх до кратного 16.

num_inference_steps (`int`, по умолчанию 28) : Количество шагов денойзинга. Используйте 28 для базовой (midtrain) контрольной точки и 8 для дистиллированной (TDM) контрольной точки с малым числом шагов.

sigmas (`list[float]`, *optional*) : Пользовательские сигмы для планировщика. Если не заданы, используется сетка по умолчанию `linspace(1.0, 1/num_inference_steps, num_inference_steps)` (сдвиг с учётом разрешения применяется внутри планировщика).

guidance_scale (`float`, по умолчанию 4.5) : Масштаб classifier-free guidance, согласно конвенции Krea 2: скорость вычисляется как `cond + guidance_scale * (cond - uncond)`, а guidance включается, когда `guidance_scale > 0` (это эквивалентно стандартной формулировке CFG с масштабом `1 + guidance_scale`). Установите `0.0`, чтобы отключить (например, для чекпоинта TDM).

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

generator (`torch.Generator` или `list[torch.Generator]`, *необязательно*) : Один или несколько [генераторов torch](https://pytorch.org/docs/stable/generated/torch.Generator.html) для обеспечения детерминированности генерации.

latents (`torch.Tensor`, *необязательный*) : Предварительно сгенерированные шумовые латенты в упакованном виде `(batch_size, image_seq_len, in_channels)`, выбранные из гауссова распределения, для использования в качестве входных данных для генерации изображений.

prompt_embeds (`torch.Tensor`, *необязательный*) : Предварительно сгенерированные текстовые эмбеддинги формы `(batch_size, text_seq_len, num_text_layers, text_hidden_dim)`. Если не указаны, эмбеддинги генерируются из `prompt`.

prompt_embeds_mask (`torch.Tensor`, *необязательный*) : Булева маска для `prompt_embeds`; обязательна, если передан `prompt_embeds`.

negative_prompt_embeds (`torch.Tensor`, *необязательный*) : Предварительно сгенерированные эмбеддинги отрицательного текста; та же структура, что и у `prompt_embeds`.

negative_prompt_embeds_mask (`torch.Tensor`, *необязательный*) : Булева маска для `negative_prompt_embeds`; требуется, если передан `negative_prompt_embeds`.

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

return_dict (`bool`, *необязательный*, по умолчанию `True`) : Возвращать ли [Krea2PipelineOutput](/docs/diffusers/main/ru/api/pipelines/krea2#diffusers.pipelines.krea2.Krea2PipelineOutput) вместо обычного кортежа.

callback_on_step_end (`Callable`, *необязательный*) : функция, вызываемая в конце каждого шага денойзинга с параметрами `callback_on_step_end(self, step, timestep, callback_kwargs)`.

callback_on_step_end_tensor_inputs (`list[str]`, *необязательный*, по умолчанию `["latents"]`) : Список тензорных входных данных для функции `callback_on_step_end`. Должен быть подмножеством `._callback_tensor_inputs`.

attention_kwargs (`dict`, *необязательный*) : Словарь kwargs, который при указании передается в `AttentionProcessor`, определенный в `self.processor` в [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

max_sequence_length (`int`, по умолчанию 512) : фиксированная длина текстовой последовательности, потребляемой трансформером; промпты дополняются или обрезаются до этой длины.

**Возвращает:** [Krea2PipelineOutput](/docs/diffusers/main/ru/api/pipelines/krea2#diffusers.pipelines.krea2.Krea2PipelineOutput) или `tuple`

[Krea2PipelineOutput](/docs/diffusers/main/ru/api/pipelines/krea2#diffusers.pipelines.krea2.Krea2PipelineOutput), если `return_dict` равно True, иначе `tuple`, первым элементом которого является список с сгенерированными изображениями.

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

Примеры:
```py
>>> import torch
>>> from diffusers import Krea2Pipeline

>>> # Load from a local directory produced by the Krea 2 conversion (no hub repo yet).
>>> pipe = Krea2Pipeline.from_pretrained("path/to/krea2-diffusers", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")
>>> prompt = "a fox in the snow"
>>> # Base (midtrain) checkpoint defaults. For the few-step distilled (TDM) checkpoint use
>>> # `num_inference_steps=8, guidance_scale=0.0` instead.
>>> image = pipe(prompt, num_inference_steps=28, guidance_scale=4.5).images[0]
>>> image.save("krea2.png")
```

#### encode_prompt[[diffusers.Krea2Pipeline.encode_prompt]]

```python
encode_prompt(prompt: str | list[str], device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 512)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/krea2/pipeline_krea2.py#L263)

**Параметры:**

prompt (`str` или `list[str]`, *необязательный*) : промпт для кодирования

device : (`torch.device`): устройство torch

num_images_per_prompt (`int`) : количество изображений, которые должны быть сгенерированы для каждого промпта

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

prompt_embeds_mask (`torch.Tensor`, *необязательный*) : Предварительно сгенерированная булева маска, отмечающая валидные токены текста, с формой `(batch_size, text_seq_len)`. Обязательна при передаче `prompt_embeds`.

max_sequence_length (`int`, по умолчанию 512) : фиксированная длина текстовой последовательности, потребляемой трансформером; промпты дополняются или обрезаются до этой длины.

#### get_text_hidden_states[[diffusers.Krea2Pipeline.get_text_hidden_states]]

```python
get_text_hidden_states(prompt: str | list[str], max_sequence_length: int = 512, device: typing.Optional[torch.device] = None)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/krea2/pipeline_krea2.py#L214)

Токенизируйте `prompt` в фиксированную по длине раскладку Krea 2 и извлеките выбранные скрытые состояния энкодера.

Возвращает кортеж `(hidden_states, attention_mask)` форм `(batch_size, text_seq_len, num_text_layers, text_hidden_dim)` и `(batch_size, text_seq_len)` (bool).

#### prepare_position_ids[[diffusers.Krea2Pipeline.prepare_position_ids]]

```python
prepare_position_ids(text_seq_len: int, grid_height: int, grid_width: int, device: device)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/krea2/pipeline_krea2.py#L381)

Постройте вращательные координаты размера `(text_seq_len + grid_height * grid_width, 3)` для объединённой последовательности: токены текста находятся в начале координат, а токены изображения несут свои координаты `(0, h, w)` в латентной сетке.

## Krea2PipelineOutput[[diffusers.pipelines.krea2.Krea2PipelineOutput]]

#### diffusers.pipelines.krea2.Krea2PipelineOutput[[diffusers.pipelines.krea2.Krea2PipelineOutput]]

```python
diffusers.pipelines.krea2.Krea2PipelineOutput(images: list[PIL.Image.Image] | numpy.ndarray)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/krea2/pipeline_output.py#L24)

**Параметры:**

images (`list[PIL.Image.Image]` или `np.ndarray`) : Список денойзированных изображений PIL длиной `batch_size` или массив numpy с формой `(batch_size, height, width, num_channels)`.

Класс вывода для конвейера Krea 2.

## Модульность

Krea 2 также доступна в виде [модульного конвейера](../../modular_diffusers/overview). Настройка classifier-free guidance выполняется через компонент `guider`, а не через аргумент вызова `guidance_scale`. Krea 2 использует cond-anchored CFG, то есть [ClassifierFreeGuidance](/docs/diffusers/main/ru/api/modular_diffusers/guiders#diffusers.ClassifierFreeGuidance) с параметром `use_original_formulation=True`.

```python
import torch
from diffusers import ClassifierFreeGuidance, ModularPipeline

pipe = ModularPipeline.from_pretrained("krea/Krea-2-Raw")
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

image = pipe(
    prompt="a fox in the snow",
    height=1024,
    width=1024,
    num_inference_steps=28,
    generator=torch.Generator("cuda").manual_seed(0),
).images[0]
image.save("krea2.png")
```

Мы также приводим пример использования Krea2 Turbo. Дистиллированная контрольная точка соответствует собственному набору блоков ([Krea2TurboAutoBlocks](/docs/diffusers/main/ru/api/pipelines/krea2#diffusers.Krea2TurboAutoBlocks)): она работает без гайданса (без `guider`), не принимает отрицательный промпт и выполняет сэмплирование за несколько шагов. `ModularPipeline.from_pretrained` автоматически выбирает турбо-блоки из конфигурации `is_distilled` контрольной точки, поэтому настройка гайданса не требуется:

```python
import torch
from diffusers import ModularPipeline

pipe = ModularPipeline.from_pretrained("krea/Krea-2-Turbo")
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

image = pipe(
    prompt="a fox in the snow",
    height=1024,
    width=1024,
    num_inference_steps=8,
    generator=torch.Generator("cuda").manual_seed(0),
).images[0]
image.save("krea2_turbo.png")
```

## Krea2ModularPipeline[[diffusers.Krea2ModularPipeline]]

#### diffusers.Krea2ModularPipeline[[diffusers.Krea2ModularPipeline]]

```python
diffusers.Krea2ModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/krea2/modular_pipeline.py#L19)

Модульный ModularPipeline для Krea 2.

## Krea2AutoBlocks[[diffusers.Krea2AutoBlocks]]

#### diffusers.Krea2AutoBlocks[[diffusers.Krea2AutoBlocks]]

```python
diffusers.Krea2AutoBlocks()
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/krea2/modular_blocks_krea2.py#L106)

Auto Модульный конвейер для генерации изображений по тексту с использованием Krea 2: кодирование текста -> основное шумоподавление (симметричный CFG) -> декодирование.

Поддерживаемые рабочие процессы:
- `text2image`: требуется `prompt`

Компоненты: text_encoder (`Qwen3VLModel`): текстовый энкодер Qwen3-VL. tokenizer (`AutoTokenizer`): токенизатор, используемый вместе с текстовым энкодером. guider (`ClassifierFreeGuidance`) transformer (`Krea2Transformer2DModel`) scheduler (`FlowMatchEulerDiscreteScheduler`) vae (`AutoencoderKLQwenImage`) image_processor (`VaeImageProcessor`)

Входные данные: prompt (`str`): Промпт или промпты для управления генерацией изображения. negative_prompt (`str`, *необязательный*): Отрицательный промпт(ы) для CFG. max_sequence_length (`int`, *необязательный*, по умолчанию 512): Максимальная длина последовательности для кодирования промпта. num_images_per_prompt (`int`, *необязательный*, по умолчанию 1): Количество изображений, генерируемых на один промпт. latents (`Tensor`, *необязательный*): Предварительно сгенерированные зашумленные латенты для генерации изображения. height (`int`, *необязательный*, по умолчанию 1024): Высота сгенерированного изображения в пикселях. width (`int`, *необязательный*, по умолчанию 1024): Ширина сгенерированного изображения в пикселях. generator (`Generator`, *необязательный*): Генератор Torch для детерминированной генерации. num_inference_steps (`int`, *необязательный*, по умолчанию 28): Количество шагов денойзинга. sigmas (`list`, *необязательный*): Пользовательское расписание сигм (по умолчанию линейный спуск). attention_kwargs (`dict`, *необязательный*): Дополнительные аргументы для процессоров внимания. output_type (`str`, *необязательный*, по умолчанию pil): Формат вывода: 'pil', 'np', 'pt'.

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

## Krea2TurboModularPipeline[[diffusers.Krea2TurboModularPipeline]]

#### diffusers.Krea2TurboModularPipeline[[diffusers.Krea2TurboModularPipeline]]

```python
diffusers.Krea2TurboModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/krea2/modular_pipeline.py#L54)

ModularPipeline для дистиллированной контрольной точки Krea 2 turbo (TDM). Работает без классификаторного свободного руководства, поэтому не принимает отрицательный промпт и не имеет направляющего.

## Krea2TurboAutoBlocks[[diffusers.Krea2TurboAutoBlocks]]

#### diffusers.Krea2TurboAutoBlocks[[diffusers.Krea2TurboAutoBlocks]]

```python
diffusers.Krea2TurboAutoBlocks()
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/krea2/modular_blocks_krea2_turbo.py#L102)

Auto Модульный конвейер для генерации изображений по тексту с использованием дистиллированной контрольной точки Krea 2 turbo: кодирование текста -> основное шумоподавление (без направляющего сигнала) -> декодирование.

Поддерживаемые рабочие процессы:
- `text2image`: требуется `prompt`

Компоненты: text_encoder (`Qwen3VLModel`): текстовый энкодер Qwen3-VL. tokenizer (`AutoTokenizer`): токенизатор, используемый вместе с текстовым энкодером. transformer (`Krea2Transformer2DModel`) scheduler (`FlowMatchEulerDiscreteScheduler`) vae (`AutoencoderKLQwenImage`) image_processor (`VaeImageProcessor`)

Входные данные: prompt (`str`): Промпт или промпты для управления генерацией изображения. max_sequence_length (`int`, *необязательный*, по умолчанию 512): Максимальная длина последовательности для кодирования промпта. num_images_per_prompt (`int`, *необязательный*, по умолчанию 1): Количество изображений, генерируемых на каждый промпт. latents (`Tensor`, *необязательный*): Предварительно сгенерированные зашумленные латенты для генерации изображения. height (`int`, *необязательный*, по умолчанию 1024): Высота сгенерированного изображения в пикселях. width (`int`, *необязательный*, по умолчанию 1024): Ширина сгенерированного изображения в пикселях. generator (`Generator`, *необязательный*): Генератор Torch для детерминированной генерации. num_inference_steps (`int`, *необязательный*, по умолчанию 8): Количество шагов денойзинга. sigmas (`list`, *необязательный*): Пользовательское расписание сигм (по умолчанию линейный спуск). attention_kwargs (`dict`, *необязательный*): Дополнительные аргументы для процессоров внимания. output_type (`str`, *необязательный*, по умолчанию pil): Формат вывода: 'pil', 'np', 'pt'.

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