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) 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 = ['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→