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) adalah model teks-ke-gambar berbasis flow-matching yang dibangun di sekitar MMDiT single-stream dengan grouped-query attention. Encoder teks Qwen3-VL menyediakan kondisioning: alih-alih menggunakan hidden state terakhir, hidden state dari dua belas lapisan decoder diambil per token dan digabungkan di dalam transformer melalui tahap fusi teks kecil. Gambar didekodekan dengan VAE Qwen-Image.

Dua checkpoint dirilis, berbagi arsitektur yang sama tetapi dengan pengaturan sampler yang direkomendasikan berbeda:

  • Base (midtrain) — gunakan sampler penuh dengan classifier-free guidance: num_inference_steps=28, guidance_scale=4.5.
  • TDM (distilled) — di-distil untuk sampling beberapa langkah, dijalankan dengan num_inference_steps=8 dan guidance dinonaktifkan (guidance_scale=0.0).

guidance_scale mengikuti konvensi Krea 2: kecepatan dihitung sebagai cond + guidance_scale * (cond - uncond) dan panduan diaktifkan setiap kali guidance_scale > 0 (ini setara dengan formulasi CFG biasa dengan skala 1 + guidance_scale).

Teks-ke-gambar

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

Kami juga menyediakan contoh untuk menggunakan 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")

Memuat checkpoint file tunggal

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

kelas diffusers.Krea2Pipeline

< >

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

Parameter

  • scheduler (FlowMatchEulerDiscreteScheduler) — Scheduler flow-matching Euler. Jadwal sigma Krea 2 adalah pergeseran waktu eksponensial yang sadar resolusi, sehingga konfigurasi scheduler diharapkan mengatur use_dynamic_shifting=True bersama dengan parameter pergeseran Krea 2 (base_shift=0.5, max_shift=1.15, base_image_seq_len=256, max_image_seq_len=6400).
  • vae (AutoencoderKLQwenImage) — Variational auto-encoder Qwen-Image (f8, 16 kanal laten) yang digunakan untuk mendekode laten menjadi gambar.
  • text_encoder (PreTrainedModel) — Model Qwen3-VL (misalnya Qwen3VLModel dari Qwen/Qwen3-VL-4B-Instruct). Pipeline ini mengonsumsi tumpukan hidden states yang diambil dari beberapa lapisan decoder, bukan hidden state terakhir.
  • tokenizer (AutoTokenizer) — Tokenizer yang berpasangan dengan text encoder.
  • transformer (Krea2Transformer2DModel) — Krea 2 single-stream MMDiT yang memprediksi kecepatan flow-matching.
  • text_encoder_select_layers (tuple[int, ...], opsional) — Indeks ke dalam tuple hidden_states dari text encoder (0 adalah output embedding) yang state-nya ditumpuk per token sebagai kondisi teks transformer. Harus memiliki transformer.config.num_text_layers entri.
  • is_distilled (bool, opsional, default False) — Apakah transformer tersebut adalah checkpoint few-step distilled (TDM/turbo). Jika True, shift timestep tetap mu=1.15 digunakan; selain itu, mu dihitung dari resolusi gambar.
  • patch_size (int, opsional, default 2) — Panjang sisi dari patch persegi tempat latents dikemas sebelum masuk ke transformer. Faktor downsampling efektif dari piksel ke token adalah vae_scale_factor * patch_size.

Pipeline Krea 2 untuk generasi teks-ke-gambar.

__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

Parameter

  • prompt (str atau list[str], opsional) — Prompt atau prompt-prompt untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus meneruskan prompt_embeds.
  • negative_prompt (str atau list[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk mengarahkan generasi gambar. Diabaikan ketika guidance_scale <= 0; secara default menggunakan prompt kosong ketika guidance diaktifkan.
  • height (int, defaultnya 1024) — Tinggi gambar yang dihasilkan dalam piksel. Dibulatkan ke atas menjadi kelipatan 16 jika diperlukan.
  • width (int, defaultnya 1024) — Lebar gambar yang dihasilkan dalam piksel. Dibulatkan ke atas menjadi kelipatan 16 jika diperlukan.
  • num_inference_steps (int, default 28) — Jumlah langkah denoising. Gunakan 28 untuk checkpoint dasar (midtrain) dan 8 untuk checkpoint distilled few-step (TDM).
  • sigmas (list[float], opsional) — Sigmas kustom untuk scheduler. Jika tidak didefinisikan, grid default linspace(1.0, 1/num_inference_steps, num_inference_steps) digunakan (pergeseran yang sadar resolusi diterapkan di dalam scheduler).
  • guidance_scale (float, default 4.5) — Skala panduan bebas klasifikator, mengikuti konvensi Krea 2: kecepatan dihitung sebagai cond + guidance_scale * (cond - uncond) dan panduan diaktifkan setiap kali guidance_scale > 0 (ini sama dengan formulasi CFG biasa dengan skala 1 + guidance_scale). Atur ke 0.0 untuk menonaktifkan (misalnya untuk checkpoint TDM).
  • num_images_per_prompt (int, defaultnya 1) — Jumlah gambar yang akan dihasilkan per prompt.
  • generator (torch.Generator atau list[torch.Generator], opsional) — Satu atau lebih generator torch untuk membuat proses generasi menjadi deterministik.
  • latents (torch.Tensor, opsional) — Latents berisik yang telah dibuat sebelumnya dalam bentuk terpadat (batch_size, image_seq_len, in_channels), yang diambil dari distribusi Gaussian, untuk digunakan sebagai input untuk generasi gambar.
  • prompt_embeds (torch.Tensor, opsional) — Embedding teks yang telah dibuat sebelumnya dengan bentuk (batch_size, text_seq_len, num_text_layers, text_hidden_dim). Jika tidak disediakan, embedding akan dibuat dari prompt.
  • prompt_embeds_mask (torch.Tensor, opsional) — Mask boolean untuk prompt_embeds; wajib diisi ketika prompt_embeds diberikan.
  • negative_prompt_embeds (torch.Tensor, opsional) — Embedding teks negatif yang telah dibuat sebelumnya; tata letak yang sama dengan prompt_embeds.
  • negative_prompt_embeds_mask (torch.Tensor, opsional) — Mask boolean untuk negative_prompt_embeds; wajib diisi ketika negative_prompt_embeds diberikan.
  • output_type (str, opsional, defaultnya "pil") — Format output dari gambar yang dihasilkan. Pilih antara "pil", "np", "pt" atau "latent".
  • return_dict (bool, opsional, default True) — Apakah akan mengembalikan Krea2PipelineOutput alih-alih tuple biasa.
  • callback_on_step_end (Callable, opsional) — Fungsi yang dipanggil di akhir setiap langkah denoising dengan callback_on_step_end(self, step, timestep, callback_kwargs).
  • callback_on_step_end_tensor_inputs (list[str], opsional, defaultnya ["latents"]) — Daftar input tensor untuk fungsi callback_on_step_end. Harus berupa subset dari ._callback_tensor_inputs.
  • attention_kwargs (dict, opsional) — Kamus kwargs yang jika ditentukan akan diteruskan ke AttentionProcessor seperti yang didefinisikan di bawah self.processor dalam diffusers.models.attention_processor.
  • max_sequence_length (int, defaultnya 512) — Panjang sekuens teks tetap yang dikonsumsi oleh transformer; prompt akan di-*pad* atau dipangkas hingga panjang tersebut.

Mengembalikan

Krea2PipelineOutput atau tuple

Krea2PipelineOutput jika return_dict bernilai True, selain itu berupa tuple, di mana elemen pertamanya adalah daftar berisi gambar yang dihasilkan.

Fungsi yang dipanggil saat memanggil pipeline untuk generasi.

Contoh:

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

Parameter

  • prompt (str atau list[str], opsional) — prompt yang akan dienkod
  • device — (torch.device): perangkat torch
  • num_images_per_prompt (int) — jumlah gambar yang harus dihasilkan per prompt
  • prompt_embeds (torch.Tensor, opsional) — Embedding teks yang telah dibuat sebelumnya dengan bentuk (batch_size, text_seq_len, num_text_layers, text_hidden_dim). Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya pembobotan prompt. Jika tidak disediakan, embedding teks akan dibuat dari argumen input prompt.
  • prompt_embeds_mask (torch.Tensor, opsional) — Mask boolean yang telah dibuat sebelumnya untuk menandai token teks yang valid, dengan bentuk (batch_size, text_seq_len). Wajib disediakan ketika prompt_embeds diteruskan.
  • max_sequence_length (int, defaultnya 512) — Panjang sekuens teks tetap yang dikonsumsi oleh transformer; prompt akan di-*pad* atau dipangkas hingga panjang tersebut.

get_text_hidden_states

< >

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

Tokenisasi prompt menjadi tata letak Krea 2 dengan panjang tetap dan ambil hidden states encoder yang dipilih.

Mengembalikan tuple (hidden_states, attention_mask) dengan bentuk (batch_size, text_seq_len, num_text_layers, text_hidden_dim) dan (batch_size, text_seq_len) (bool).

prepare_position_ids

< >

( text_seq_len: intgrid_height: intgrid_width: intdevice: device )

Bangun koordinat rotasi (text_seq_len + grid_height * grid_width, 3) untuk urutan gabungan: token teks berada di titik asal, token gambar membawa koordinat grid laten (0, h, w) mereka.

Krea2PipelineOutput

kelas diffusers.pipelines.krea2.Krea2PipelineOutput

< >

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

Parameter

  • images (list[PIL.Image.Image] atau np.ndarray) — Daftar gambar PIL yang telah didenoise dengan panjang batch_size atau array numpy dengan bentuk (batch_size, height, width, num_channels).

Kelas output untuk pipeline Krea 2.

Modular

Krea 2 juga tersedia sebagai pipeline modular. Classifier-free guidance dikonfigurasi melalui komponen guider alih-alih argumen pemanggilan guidance_scale. Krea 2 menggunakan CFG yang dijangkar pada cond, yaitu ClassifierFreeGuidance dengan 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")

Kami juga menyediakan contoh penggunaan Krea2 Turbo. Checkpoint yang telah didistilasi dipetakan ke set blok miliknya sendiri (Krea2TurboAutoBlocks): berjalan tanpa panduan (tanpa guider), tidak menerima negative prompt, dan melakukan sampling dalam beberapa langkah. ModularPipeline.from_pretrained memilih blok turbo secara otomatis dari konfigurasi is_distilled checkpoint, sehingga tidak diperlukan konfigurasi panduan:

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

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

A ModularPipeline untuk Krea 2.

Krea2AutoBlocks

kelas diffusers.Krea2AutoBlocks

< >

( )

Auto Modular pipeline untuk generasi teks-ke-gambar menggunakan Krea 2: encode teks -> core denoise (CFG simetris) -> decode.

Alur kerja yang didukung:

  • text2image: membutuhkan prompt

Komponen: text_encoder (Qwen3VLModel): Encoder teks Qwen3-VL. tokenizer (AutoTokenizer): Tokenizer yang berpasangan dengan encoder teks. guider (ClassifierFreeGuidance) transformer (Krea2Transformer2DModel) scheduler (FlowMatchEulerDiscreteScheduler) vae (AutoencoderKLQwenImage) image_processor (VaeImageProcessor)

Inputs: prompt (str): The prompt or prompts to guide image generation. negative_prompt (str, optional): The negative prompt(s) for CFG. max_sequence_length (int, optional, defaults to 512): Maximum sequence length for prompt encoding. num_images_per_prompt (int, optional, defaults to 1): The number of images to generate per prompt. latents (Tensor, optional): Pre-generated noisy latents for image generation. height (int, optional, defaults to 1024): The height in pixels of the generated image. width (int, optional, defaults to 1024): The width in pixels of the generated image. generator (Generator, optional): Torch generator for deterministic generation. num_inference_steps (int, optional, defaults to 28): The number of denoising steps. sigmas (list, optional): Custom sigma schedule (defaults to a linear ramp). attention_kwargs (dict, optional): Additional kwargs for attention processors. output_type (str, optional, defaults to pil): Output format: ‘pil’, ‘np’, ‘pt’.

Output: images (list): Gambar yang dihasilkan.

Krea2TurboModularPipeline

kelas 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 untuk checkpoint Krea 2 turbo (TDM) yang telah di-distil. Pipeline ini berjalan tanpa classifier-free guidance, sehingga tidak memerlukan negative prompt dan tidak memiliki guider.

Krea2TurboAutoBlocks

kelas diffusers.Krea2TurboAutoBlocks

< >

( )

Auto Modular pipeline untuk generasi teks-ke-gambar menggunakan checkpoint Krea 2 turbo yang telah di-distil: encode teks -> core denoise (tanpa guidance) -> decode.

Alur kerja yang didukung:

  • text2image: membutuhkan prompt

Komponen: text_encoder (Qwen3VLModel): Encoder teks Qwen3-VL. tokenizer (AutoTokenizer): Tokenizer yang berpasangan dengan encoder teks. transformer (Krea2Transformer2DModel) scheduler (FlowMatchEulerDiscreteScheduler) vae (AutoencoderKLQwenImage) image_processor (VaeImageProcessor)

Inputs: prompt (str): The prompt or prompts to guide image generation. max_sequence_length (int, optional, defaults to 512): Maximum sequence length for prompt encoding. num_images_per_prompt (int, optional, defaults to 1): The number of images to generate per prompt. latents (Tensor, optional): Pre-generated noisy latents for image generation. height (int, optional, defaults to 1024): The height in pixels of the generated image. width (int, optional, defaults to 1024): The width in pixels of the generated image. generator (Generator, optional): Torch generator for deterministic generation. num_inference_steps (int, optional, defaults to 8): The number of denoising steps. sigmas (list, optional): Custom sigma schedule (defaults to a linear ramp). attention_kwargs (dict, optional): Additional kwargs for attention processors. output_type (str, optional, defaults to pil): Output format: ‘pil’, ‘np’, ‘pt’.

Output: images (list): Gambar yang dihasilkan.

Update on GitHub

←Kolors Model Konsistensi Laten→