Hugging Face's logo

Diffusers documentation

Krea 2

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
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 = ['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 Модели латентной консистентности→