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) es un modelo de texto a imagen basado en flow-matching, construido en torno a un MMDiT de un solo flujo con atención de consulta agrupada. Un codificador de texto Qwen3-VL proporciona la condición: en lugar del último estado oculto, se extraen los estados ocultos de doce capas del decodificador por token y se fusionan dentro del transformer mediante una pequeña etapa de fusión de texto. Las imágenes se decodifican con el VAE de Qwen-Image.

Se publican dos puntos de control que comparten la misma arquitectura pero con diferentes configuraciones de muestreador recomendadas:

  • Base (midtrain) — usa el muestreador completo con guía libre de clasificador: num_inference_steps=28, guidance_scale=4.5.
  • TDM (destilado) — destilado para muestreo en pocos pasos, se ejecuta con num_inference_steps=8 y la guía desactivada (guidance_scale=0.0).

guidance_scale sigue la convención de Krea 2: la velocidad se calcula como cond + guidance_scale * (cond - uncond) y la guía se habilita siempre que guidance_scale > 0 (esto equivale a la formulación habitual de CFG con escala 1 + guidance_scale).

Texto a imagen

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

Además, proporcionamos un ejemplo para usar 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")

Carga de puntos de control de un solo archivo

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

clase diffusers.Krea2Pipeline

< >

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

Parámetros

  • scheduler (FlowMatchEulerDiscreteScheduler) — Programador de flujo de Euler. El programa de sigma de Krea 2 es el desplazamiento exponencial de tiempo consciente de la resolución, por lo que se espera que la configuración del programador establezca use_dynamic_shifting=True junto con los parámetros de desplazamiento de Krea 2 (base_shift=0.5, max_shift=1.15, base_image_seq_len=256, max_image_seq_len=6400).
  • vae (AutoencoderKLQwenImage) — El autoencoder variacional de Qwen-Image (f8, 16 canales latentes) utilizado para decodificar latentes en imágenes.
  • text_encoder (PreTrainedModel) — Un modelo Qwen3-VL (p. ej. Qwen3VLModel de Qwen/Qwen3-VL-4B-Instruct). El pipeline consume una pila de estados ocultos extraídos de varias capas decodificadoras en lugar del último estado oculto.
  • tokenizer (AutoTokenizer) — El tokenizador asociado con el codificador de texto.
  • transformer (Krea2Transformer2DModel) — El MMDiT de un solo flujo de Krea 2 que predice la velocidad de flow-matching.
  • text_encoder_select_layers (tuple[int, ...], opcional) — Índices dentro de la tupla hidden_states del codificador de texto (0 es la salida de la incrustación) cuyos estados se apilan por token como la condición de texto del transformador. Debe tener transformer.config.num_text_layers entradas.
  • is_distilled (bool, opcional, valor predeterminado False) — Indica si el transformer es un checkpoint destilado de pocos pasos (TDM/turbo). Cuando True, se utiliza un desplazamiento de paso fijo mu=1.15; de lo contrario, mu se calcula a partir de la resolución de la imagen.
  • patch_size (int, opcional, valor predeterminado 2) — Lado de los parches cuadrados en los que se empaquetan los latentes antes de entrar al transformer. El factor de reducción de píxeles a tokens efectivo es vae_scale_factor * patch_size.

El pipeline Krea 2 para la generación de imágenes a partir de texto.

__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

Parámetros

  • prompt (str o list[str], opcional) — El prompt o los prompts para guiar la generación de la imagen. Si no se define, hay que pasar prompt_embeds.
  • negative_prompt (str o list[str], opcional) — El prompt o prompts que no deben guiar la generación de la imagen. Se ignora cuando guidance_scale <= 0; por defecto, se utiliza un prompt vacío cuando la guía está habilitada.
  • height (int, por defecto 1024) — La altura en píxeles de la imagen generada. Se redondea hacia arriba a un múltiplo de 16 si es necesario.
  • width (int, por defecto 1024) — El ancho en píxeles de la imagen generada. Se redondea hacia arriba a un múltiplo de 16 si es necesario.
  • num_inference_steps (int, por defecto 28) — El número de pasos de desruido. Use 28 para el punto de control base (midtrain) y 8 para el punto de control destilado de pocos pasos (TDM).
  • sigmas (list[float], opcional) — Sigmas personalizados para el programador. Si no se definen, se utiliza la cuadrícula predeterminada linspace(1.0, 1/num_inference_steps, num_inference_steps) (el desplazamiento consciente de la resolución se aplica dentro del programador).
  • guidance_scale (float, valor predeterminado 4.5) — Escala de guía libre de clasificador, siguiendo la convención de Krea 2: la velocidad se calcula como cond + guidance_scale * (cond - uncond) y la guía se habilita siempre que guidance_scale > 0 (esto equivale a la formulación habitual de CFG con escala 1 + guidance_scale). Establecer en 0.0 para deshabilitarla (p. ej., para el punto de control TDM).
  • num_images_per_prompt (int, por defecto 1) — El número de imágenes a generar por prompt.
  • generator (torch.Generator o list[torch.Generator], opcional) — Uno o más generadores de torch para hacer la generación determinista.
  • latents (torch.Tensor, opcional) — Latentes ruidosos pregenerados en formato empaquetado (batch_size, image_seq_len, in_channels), muestreados de una distribución gaussiana, para usarse como entradas para la generación de imágenes.
  • prompt_embeds (torch.Tensor, opcional) — Incrustaciones de texto pregeneradas de forma (batch_size, text_seq_len, num_text_layers, text_hidden_dim). Si no se proporcionan, las incrustaciones se generan a partir de prompt.
  • prompt_embeds_mask (torch.Tensor, opcional) — Máscara booleana para prompt_embeds; obligatoria cuando se pasa prompt_embeds.
  • negative_prompt_embeds (torch.Tensor, opcional) — Incrustaciones de texto negativo pregeneradas; mismo diseño que prompt_embeds.
  • negative_prompt_embeds_mask (torch.Tensor, opcional) — Máscara booleana para negative_prompt_embeds; obligatoria cuando se pasa negative_prompt_embeds.
  • output_type (str, opcional, valor predeterminado "pil") — El formato de salida de la imagen generada. Elija entre "pil", "np", "pt" o "latent".
  • return_dict (bool, opcional, valor predeterminado True) — Indica si se debe devolver un Krea2PipelineOutput en lugar de una tupla simple.
  • callback_on_step_end (Callable, opcional) — Una función que se llama al final de cada paso de desruido con callback_on_step_end(self, step, timestep, callback_kwargs).
  • callback_on_step_end_tensor_inputs (list[str], opcional, valor predeterminado ["latents"]) — La lista de entradas de tensor para la función callback_on_step_end. Debe ser un subconjunto de ._callback_tensor_inputs.
  • attention_kwargs (dict, opcional) — Un diccionario de kwargs que, si se especifica, se pasa al AttentionProcessor definido en self.processor dentro de diffusers.models.attention_processor.
  • max_sequence_length (int, por defecto 512) — Longitud fija de la secuencia de texto consumida por el transformer; los prompts se rellenan o se truncan hasta alcanzarla.

Devuelve

Krea2PipelineOutput o tuple

Krea2PipelineOutput si return_dict es True, de lo contrario una tuple, cuyo primer elemento es una lista con las imágenes generadas.

Función invocada al llamar a la pipeline para la generación.

Ejemplos:

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

Parámetros

  • prompt (str o list[str], opcional) — prompt a codificar
  • device — (torch.device): dispositivo de torch
  • num_images_per_prompt (int) — número de imágenes que deben generarse por prompt
  • prompt_embeds (torch.Tensor, opcional) — Incrustaciones de texto pregeneradas de forma (batch_size, text_seq_len, num_text_layers, text_hidden_dim). Se pueden usar para ajustar fácilmente las entradas de texto, p. ej. el ponderado del prompt. Si no se proporciona, las incrustaciones de texto se generarán a partir del argumento de entrada prompt.
  • prompt_embeds_mask (torch.Tensor, opcional) — Máscara booleana pregenerada que marca los tokens de texto válidos, de forma (batch_size, text_seq_len). Es obligatoria cuando se pasa prompt_embeds.
  • max_sequence_length (int, por defecto 512) — Longitud fija de la secuencia de texto consumida por el transformer; los prompts se rellenan o se truncan hasta alcanzarla.

get_text_hidden_states

< >

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

Tokeniza prompt en el diseño de longitud fija de Krea 2 y toma los estados ocultos del codificador seleccionado.

Devuelve una tupla (hidden_states, attention_mask) de formas (batch_size, text_seq_len, num_text_layers, text_hidden_dim) y (batch_size, text_seq_len) (bool).

prepare_position_ids

< >

( text_seq_len: intgrid_height: intgrid_width: intdevice: device )

Construya las coordenadas rotatorias (text_seq_len + grid_height * grid_width, 3) para la secuencia combinada: los tokens de texto se ubican en el origen, mientras que los tokens de imagen llevan sus coordenadas de la cuadrícula latente (0, h, w).

Krea2PipelineOutput

clase diffusers.pipelines.krea2.Krea2PipelineOutput

< >

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

Parámetros

  • images (list[PIL.Image.Image] o np.ndarray) — Lista de imágenes PIL desruidas de longitud batch_size o array de numpy de forma (batch_size, height, width, num_channels).

Clase de salida para el pipeline Krea 2.

Modular

Krea 2 también está disponible como pipeline modular. La guía sin clasificador se configura a través del componente guider en lugar de un argumento de llamada guidance_scale. Krea 2 utiliza CFG anclado a la condición, que es ClassifierFreeGuidance con 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")

Además, proporcionamos un ejemplo para usar Krea2 Turbo. El checkpoint destilado se corresponde con su propio conjunto de bloques (Krea2TurboAutoBlocks): se ejecuta sin guía (sin guider), no toma un prompt negativo y muestrea en pocos pasos. ModularPipeline.from_pretrained selecciona los bloques turbo automáticamente a partir de la configuración is_distilled del checkpoint, por lo que no se necesita ninguna configuración de guía:

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

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

Un ModularPipeline para Krea 2.

Krea2AutoBlocks

clase diffusers.Krea2AutoBlocks

< >

( )

Auto Modular pipeline para la generación de imágenes a partir de texto usando Krea 2: codificar texto -> desruido principal (CFG simétrico) -> decodificar.

Flujos de trabajo admitidos:

  • text2image: requiere prompt

Componentes: text_encoder (Qwen3VLModel): El codificador de texto de Qwen3-VL. tokenizer (AutoTokenizer): El tokenizador emparejado con el codificador de texto. guider (ClassifierFreeGuidance) transformer (Krea2Transformer2DModel) scheduler (FlowMatchEulerDiscreteScheduler) vae (AutoencoderKLQwenImage) image_processor (VaeImageProcessor)

Entradas: prompt (str): El prompt o prompts para guiar la generación de imágenes. negative_prompt (str, opcional): El o los negative prompts para CFG. max_sequence_length (int, opcional, valor predeterminado 512): Longitud máxima de secuencia para la codificación del prompt. num_images_per_prompt (int, opcional, valor predeterminado 1): El número de imágenes a generar por prompt. latents (Tensor, opcional): Latentes ruidosos pregenerados para la generación de imágenes. height (int, opcional, valor predeterminado 1024): La altura en píxeles de la imagen generada. width (int, opcional, valor predeterminado 1024): El ancho en píxeles de la imagen generada. generator (Generator, opcional): Generador de Torch para una generación determinista. num_inference_steps (int, opcional, valor predeterminado 28): El número de pasos de desruido. sigmas (list, opcional): Programa de sigmas personalizado (el valor predeterminado es una rampa lineal). attention_kwargs (dict, opcional): Kwargs adicionales para los procesadores de atención. output_type (str, opcional, valor predeterminado pil): Formato de salida: ‘pil’, ‘np’, ‘pt’.

Salidas: images (list): Imágenes generadas.

Krea2TurboModularPipeline

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

Un ModularPipeline para el punto de control destilado de Krea 2 turbo (TDM). Se ejecuta sin guía libre de clasificador, por lo que no acepta un prompt negativo y no tiene un guionista.

Krea2TurboAutoBlocks

clase diffusers.Krea2TurboAutoBlocks

< >

( )

Auto Modular pipeline para la generación de imágenes a partir de texto usando el checkpoint destilado Krea 2 turbo: codificar texto -> desruido principal (sin guía) -> decodificar.

Flujos de trabajo admitidos:

  • text2image: requiere prompt

Componentes: text_encoder (Qwen3VLModel): El codificador de texto de Qwen3-VL. tokenizer (AutoTokenizer): El tokenizador emparejado con el codificador de texto. transformer (Krea2Transformer2DModel) scheduler (FlowMatchEulerDiscreteScheduler) vae (AutoencoderKLQwenImage) image_processor (VaeImageProcessor)

Entradas: prompt (str): El prompt o prompts para guiar la generación de imágenes. max_sequence_length (int, opcional, valor predeterminado 512): Longitud máxima de secuencia para la codificación del prompt. num_images_per_prompt (int, opcional, valor predeterminado 1): El número de imágenes a generar por prompt. latents (Tensor, opcional): Latentes ruidosos pregenerados para la generación de imágenes. height (int, opcional, valor predeterminado 1024): La altura en píxeles de la imagen generada. width (int, opcional, valor predeterminado 1024): El ancho en píxeles de la imagen generada. generator (Generator, opcional): Generador de Torch para una generación determinista. num_inference_steps (int, opcional, valor predeterminado 8): El número de pasos de desruido. sigmas (list, opcional): Programa de sigma personalizado (el valor predeterminado es una rampa lineal). attention_kwargs (dict, opcional): Kwargs adicionales para los procesadores de atención. output_type (str, opcional, valor predeterminado pil): Formato de salida: ‘pil’, ‘np’, ‘pt’.

Salidas: images (list): Imágenes generadas.

Update on GitHub

←Kolors Modelos de consistencia latente→