Hugging Face's logo

Diffusers documentation

Krea 2

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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).

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

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:

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")

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

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

< >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLQwenImagetext_encoder: Qwen3VLModeltokenizer: AutoTokenizertransformer: Krea2Transformer2DModeltext_encoder_select_layers: tuple[int, ...] | list[int] | None = Noneis_distilled: bool = Falsepatch_size: int = 2 )

Параметры

  • scheduler (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) — вариационный автоэнкодер Qwen-Image (f8, 16 латентных каналов), используемый для декодирования латентов в изображения.
  • text_encoder (PreTrainedModel) — Модель Qwen3-VL (например, Qwen3VLModel из Qwen/Qwen3-VL-4B-Instruct). Пайплайн использует стек скрытых состояний, полученных из нескольких слоев декодера, а не последнее скрытое состояние.
  • tokenizer (AutoTokenizer) — токенизатор, используемый вместе с текстовым энкодером.
  • transformer (Krea2Transformer2DModel) — Однопоточный MMDiT Krea 2, предсказывающий скорость flow-matching.
  • text_encoder_select_layers (tuple[int, ...], необязательный) — Индексы в кортеже hidden_states текстового кодировщика (0 — выход эмбеддинга), состояния которых складываются по токенам в качестве текстового условия для трансформера. Должно содержать transformer.config.num_text_layers элементов.
  • is_distilled (bool, необязательный, по умолчанию False) — Указывает, является ли трансформер дистиллированной контрольной точкой с малым числом шагов (TDM/turbo). Если True, используется фиксированный сдвиг временного шага mu=1.15; в противном случае mu вычисляется на основе разрешения изображения.
  • patch_size (int, необязательный, по умолчанию 2) — Длина стороны квадратных патчей, в которые упаковываются латенты перед передачей в трансформер. Эффективный коэффициент понижения разрешения пикселей до токенов составляет vae_scale_factor * patch_size.

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

__call__

< >

( prompt: str | list[str] | None = Nonenegative_prompt: str | list[str] | None = Noneheight: int = 1024width: int = 1024num_inference_steps: int = 28sigmas: list[float] | None = Noneguidance_scale: float = 4.5num_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 = Truecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']attention_kwargs: dict[str, typing.Any] | None = Nonemax_sequence_length: int = 512 ) → Krea2PipelineOutput or tuple

Параметры

  • 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], необязательный) — Пользовательские сигмы для планировщика. Если не заданы, используется сетка по умолчанию 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_scale > 0 (это эквивалентно стандартной формулировке CFG с масштабом 1 + guidance_scale). Установите 0.0, чтобы отключить (например, для чекпоинта TDM).
  • num_images_per_prompt (int, по умолчанию 1) — Количество изображений, генерируемых на один промпт.
  • generator (torch.Generator или list[torch.Generator], необязательный) — Один или несколько генераторов torch для обеспечения детерминированности генерации.
  • 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 вместо обычного кортежа.
  • 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.
  • max_sequence_length (int, по умолчанию 512) — фиксированная длина текстовой последовательности, потребляемой трансформером; промпты дополняются или обрезаются до этой длины.

Возвращает

Krea2PipelineOutput или tuple

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

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

Примеры:

>>> 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

< >

( prompt: str | list[str]device: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 512 )

Параметры

  • 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

< >

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

Токенизируйте 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

< >

( text_seq_len: intgrid_height: intgrid_width: intdevice: device )

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

Krea2PipelineOutput

класс diffusers.pipelines.krea2.Krea2PipelineOutput

< >

( images: list[PIL.Image.Image] | numpy.ndarray )

Параметры

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

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

Модульность

Krea 2 также доступна в виде модульного конвейера. Настройка classifier-free guidance выполняется через компонент guider, а не через аргумент вызова guidance_scale. Krea 2 использует cond-anchored CFG, то есть ClassifierFreeGuidance с параметром use_original_formulation=True.

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): она работает без гайданса (без guider), не принимает отрицательный промпт и выполняет сэмплирование за несколько шагов. ModularPipeline.from_pretrained автоматически выбирает турбо-блоки из конфигурации is_distilled контрольной точки, поэтому настройка гайданса не требуется:

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

< >

( 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 для Krea 2.

Krea2AutoBlocks

класс diffusers.Krea2AutoBlocks

< >

( )

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’.

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

Krea2TurboModularPipeline

класс diffusers.Krea2TurboModularPipeline

< >

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

Krea2TurboAutoBlocks

класс diffusers.Krea2TurboAutoBlocks

< >

( )

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’.

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

Update on GitHub

←Kolors Модели латентной консистентности→