Hugging Face's logo

Diffusers documentation

Flux2

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Flux2

LoRA MPS

Flux.2 adalah seri model generasi gambar terbaru dari Black Forest Labs, yang didahului oleh seri Flux.1. Ini adalah model yang sepenuhnya baru dengan arsitektur baru dan pra-pelatihan yang dilakukan dari awal!

Checkpoint model asli untuk Flux dapat ditemukan di sini. Kode inferensi asli dapat ditemukan di sini.

Flux2 dapat cukup mahal untuk dijalankan pada perangkat keras konsumen. Namun, Anda dapat melakukan serangkaian optimasi untuk menjalankannya lebih cepat dan dengan cara yang lebih hemat memori. Lihat bagian ini untuk detail lebih lanjut. Selain itu, Flux dapat diuntungkan dari kuantisasi untuk efisiensi memori dengan trade-off pada latensi inferensi. Rujuk artikel blog ini untuk mempelajari lebih lanjut.

Caching juga dapat mempercepat inferensi dengan menyimpan dan menggunakan kembali output antara.

Upsampling caption

Flux.2 berpotensi menghasilkan output yang lebih baik dengan prompt yang lebih baik. Kita dapat “upsample” prompt input dengan mengatur argumen caption_upsample_temperature dalam argumen panggilan pipeline. Implementasi resmi merekomendasikan nilai ini menjadi 0.15.

Flux2Pipeline

kelas diffusers.Flux2Pipeline

< >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLFlux2text_encoder: Mistral3ForConditionalGenerationtokenizer: AutoProcessortransformer: Flux2Transformer2DModel )

Parameter

  • transformer (Flux2Transformer2DModel) — Arsitektur Conditional Transformer (MMDiT) untuk mendenois latens gambar yang telah dikodekan.
  • scheduler (FlowMatchEulerDiscreteScheduler) — Scheduler yang digunakan bersama transformer untuk menghilangkan noise pada latens gambar yang telah dikodekan.
  • vae (AutoencoderKLFlux2) — Model Variational Auto-Encoder (VAE) untuk mengodekan dan mendekodekan gambar ke dan dari representasi laten.
  • text_encoder (Mistral3ForConditionalGeneration) — Mistral3ForConditionalGeneration
  • tokenizer (AutoProcessor) — Tokenizer dari kelas PixtralProcessor.

Pipeline Flux2 untuk generasi teks-ke-gambar.

Referensi: https://bfl.ai/blog/flux-2

__call__

< >

( image: PIL.Image.Image | list[PIL.Image.Image] | None = Noneprompt: str | list[str] = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 50sigmas: list[float] | None = Noneguidance_scale: float | None = 4.0num_images_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']max_sequence_length: int = 512text_encoder_out_layers: tuple[int] = (10, 20, 30)caption_upsample_temperature: float = None ) → ~pipelines.flux2.Flux2PipelineOutput or tuple

Parameter

  • image (torch.Tensor, PIL.Image.Image, np.ndarray, list[torch.Tensor], list[PIL.Image.Image], atau list[np.ndarray]) — Image, array numpy, atau tensor yang merepresentasikan batch gambar untuk digunakan sebagai titik awal. Untuk array numpy dan tensor pytorch, rentang nilai yang diharapkan adalah antara [0, 1] Jika berupa tensor atau daftar tensor, bentuk (shape) yang diharapkan adalah (B, C, H, W) atau (C, H, W). Jika berupa array numpy atau daftar array, bentuk yang diharapkan adalah (B, H, W, C) atau (H, W, C) Parameter ini juga dapat menerima latens gambar sebagai image, namun jika latens diberikan secara langsung, latens tersebut tidak akan di-encode ulang.
  • prompt (str atau list[str], opsional) — Prompt atau prompt-prompt untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus meneruskan prompt_embeds sebagai gantinya.
  • guidance_scale (float, opsional, defaultnya 1.0) — Skala panduan tertanam diaktifkan dengan mengatur guidance_scale > 1. Nilai guidance_scale yang lebih tinggi mendorong model untuk menghasilkan gambar yang lebih selaras dengan prompt dengan mengorbankan kualitas gambar yang lebih rendah.

    Model yang telah melalui distilasi panduan (guidance-distilled) mengaproksimasi true classifer-free guidance untuk guidance_scale > 1. Lihat makalah untuk mempelajari lebih lanjut.

  • height (int, opsional, defaultnya self.unet.config.sample_size * self.vae_scale_factor) — Tinggi gambar yang dihasilkan dalam piksel. Nilai ini secara default diatur ke 1024 untuk hasil terbaik.
  • width (int, opsional, defaultnya self.unet.config.sample_size * self.vae_scale_factor) — Lebar gambar yang dihasilkan dalam piksel. Ini diatur ke 1024 secara default untuk hasil terbaik.
  • num_inference_steps (int, opsional, default 50) — Jumlah langkah denoising. Semakin banyak langkah denoising, biasanya menghasilkan gambar dengan kualitas lebih tinggi, namun dengan biaya inferensi yang lebih lambat.
  • sigmas (list[float], opsional) — Sigmas kustom untuk digunakan dalam proses denoising dengan scheduler yang mendukung argumen sigmas dalam metode set_timesteps mereka. Jika tidak didefinisikan, perilaku default saat num_inference_steps diteruskan akan digunakan.
  • num_images_per_prompt (int, opsional, default 1) — Jumlah gambar yang akan dihasilkan per prompt.
  • generator (torch.Generator atau list[torch.Generator], opsional) — Satu atau daftar generator torch untuk membuat proses generasi menjadi deterministik.
  • latents (torch.Tensor, opsional) — Latents berisik yang telah dibuat sebelumnya, diambil dari distribusi Gaussian, untuk digunakan sebagai input untuk generasi gambar. Dapat digunakan untuk menyesuaikan generasi yang sama dengan prompt yang berbeda. Jika tidak disediakan, tensor latents akan dibuat dengan pengambilan sampel menggunakan generator acak yang diberikan.
  • prompt_embeds (torch.Tensor, opsional) — Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya pembobotan prompt. Jika tidak disediakan, embedding teks akan dihasilkan dari argumen input prompt.
  • output_type (str, opsional, defaultnya "pil") — Format output dari generate image. Pilih antara PIL: PIL.Image.Image atau np.array.
  • return_dict (bool, opsional, default True) — Apakah akan mengembalikan ~pipelines.qwenimage.QwenImagePipelineOutput alih-alih tuple biasa.
  • 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.
  • callback_on_step_end (Callable, opsional) — Fungsi yang dipanggil di akhir setiap langkah denoising selama inferensi. Fungsi ini dipanggil dengan argumen berikut: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs akan berisi daftar semua tensor sesuai yang ditentukan oleh callback_on_step_end_tensor_inputs.
  • callback_on_step_end_tensor_inputs (List, opsional) — Daftar input tensor untuk fungsi callback_on_step_end. Tensor yang ditentukan dalam daftar akan diteruskan sebagai argumen callback_kwargs. Anda hanya dapat menyertakan variabel yang tercantum dalam atribut ._callback_tensor_inputs dari kelas pipeline Anda.
  • max_sequence_length (int defaultnya 512) — Panjang maksimum urutan yang digunakan dengan prompt.
  • text_encoder_out_layers (tuple[int]) — Indeks layer yang digunakan pada text_encoder untuk menurunkan embedding prompt akhir.
  • caption_upsample_temperature (float) — Jika ditentukan, kami akan mencoba melakukan caption upsampling untuk hasil yang mungkin lebih baik. Kami merekomendasikan untuk mengaturnya ke 0.15 jika caption upsampling akan dilakukan.

Mengembalikan

~pipelines.flux2.Flux2PipelineOutput atau tuple

~pipelines.flux2.Flux2PipelineOutput jika return_dict bernilai True, selain itu berupa tuple. Saat mengembalikan tuple, elemen pertama adalah daftar berisi gambar yang dihasilkan.

Fungsi yang dipanggil saat memanggil pipeline untuk generasi.

Contoh:

>>> import torch
>>> from diffusers import Flux2Pipeline

>>> pipe = Flux2Pipeline.from_pretrained("black-forest-labs/FLUX.2-dev", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")
>>> prompt = "A cat holding a sign that says hello world"
>>> # Depending on the variant being used, the pipeline call will slightly vary.
>>> # Refer to the pipeline documentation for more details.
>>> image = pipe(prompt, num_inference_steps=50, guidance_scale=2.5).images[0]
>>> image.save("flux.png")

Flux2KleinPipeline

kelas diffusers.Flux2KleinPipeline

< >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLFlux2text_encoder: Qwen3ForCausalLMtokenizer: Qwen2Tokenizertransformer: Flux2Transformer2DModelis_distilled: bool = False )

Parameter

  • transformer (Flux2Transformer2DModel) — Arsitektur Conditional Transformer (MMDiT) untuk mendenois latens gambar yang telah dikodekan.
  • scheduler (FlowMatchEulerDiscreteScheduler) — Scheduler yang digunakan bersama transformer untuk menghilangkan noise pada latens gambar yang telah dikodekan.
  • vae (AutoencoderKLFlux2) — Model Variational Auto-Encoder (VAE) untuk mengodekan dan mendekodekan gambar ke dan dari representasi laten.
  • text_encoder (Qwen3ForCausalLM) — Qwen3ForCausalLM
  • tokenizer (Qwen2TokenizerFast) — Tokenizer dari kelas Qwen2TokenizerFast.

Pipeline Flux2 Klein untuk generasi teks-ke-gambar.

Referensi: https://bfl.ai/blog/flux2-klein-towards-interactive-visual-intelligence

__call__

< >

( image: list[PIL.Image.Image] | PIL.Image.Image | None = Noneprompt: str | list[str] = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 50sigmas: list[float] | None = Noneguidance_scale: float = 4.0num_images_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: str | list[str] | None = Noneoutput_type: str = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']max_sequence_length: int = 512text_encoder_out_layers: tuple[int] = (9, 18, 27) ) → ~pipelines.flux2.Flux2PipelineOutput or tuple

Parameter

  • image (torch.Tensor, PIL.Image.Image, np.ndarray, List[torch.Tensor], List[PIL.Image.Image], atau List[np.ndarray]) — Image, array numpy, atau tensor yang merepresentasikan batch gambar untuk digunakan sebagai titik awal. Untuk array numpy dan tensor pytorch, rentang nilai yang diharapkan adalah antara [0, 1]. Jika berupa tensor atau daftar tensor, bentuk (shape) yang diharapkan adalah (B, C, H, W) atau (C, H, W). Jika berupa array numpy atau daftar array, bentuk yang diharapkan adalah (B, H, W, C) atau (H, W, C). Parameter ini juga dapat menerima latens gambar sebagai image, namun jika latens diberikan secara langsung, latens tersebut tidak akan di-encode ulang.
  • prompt (str atau List[str], opsional) — Prompt atau prompt-prompt untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus meneruskan prompt_embeds sebagai gantinya.
  • guidance_scale (float, opsional, default 4.0) — Skala panduan seperti yang didefinisikan dalam Classifier-Free Diffusion Guidance. guidance_scale didefinisikan sebagai w dari persamaan 2. dari Imagen Paper. Skala panduan diaktifkan dengan mengatur guidance_scale > 1. Skala panduan yang lebih tinggi mendorong generasi gambar yang sangat terkait dengan teks prompt, biasanya dengan mengorbankan kualitas gambar yang lebih rendah. Untuk model yang disuling per langkah, guidance_scale diabaikan.
  • height (int, opsional, defaultnya self.unet.config.sample_size * self.vae_scale_factor) — Tinggi gambar yang dihasilkan dalam piksel. Nilai ini secara default diatur ke 1024 untuk hasil terbaik.
  • width (int, opsional, defaultnya self.unet.config.sample_size * self.vae_scale_factor) — Lebar gambar yang dihasilkan dalam piksel. Ini diatur ke 1024 secara default untuk hasil terbaik.
  • num_inference_steps (int, opsional, default 50) — Jumlah langkah denoising. Semakin banyak langkah denoising, biasanya menghasilkan gambar dengan kualitas lebih tinggi, namun dengan biaya inferensi yang lebih lambat.
  • sigmas (List[float], opsional) — Sigmas kustom untuk digunakan dalam proses denoising dengan scheduler yang mendukung argumen sigmas di metode set_timesteps mereka. Jika tidak didefinisikan, perilaku default saat num_inference_steps diteruskan akan digunakan.
  • num_images_per_prompt (int, opsional, default 1) — Jumlah gambar yang akan dihasilkan per prompt.
  • generator (torch.Generator atau List[torch.Generator], opsional) — Satu atau daftar generator torch untuk membuat proses generasi menjadi deterministik.
  • latents (torch.Tensor, opsional) — Latents berisik yang telah dibuat sebelumnya, diambil dari distribusi Gaussian, untuk digunakan sebagai input untuk generasi gambar. Dapat digunakan untuk menyesuaikan generasi yang sama dengan prompt yang berbeda. Jika tidak disediakan, tensor latents akan dibuat dengan pengambilan sampel menggunakan generator acak yang diberikan.
  • prompt_embeds (torch.Tensor, opsional) — Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya pembobotan prompt. Jika tidak disediakan, embedding teks akan dihasilkan dari argumen input prompt.
  • negative_prompt_embeds (torch.Tensor, opsional) — Embedding teks negatif yang telah dibuat sebelumnya. Perhatikan bahwa "" digunakan sebagai prompt negatif dalam pipeline ini. Jika tidak disediakan, akan dibuat dari "".
  • output_type (str, opsional, defaultnya "pil") — Format output dari generate image. Pilih antara PIL: PIL.Image.Image atau np.array.
  • return_dict (bool, opsional, default True) — Apakah akan mengembalikan ~pipelines.qwenimage.QwenImagePipelineOutput alih-alih tuple biasa.
  • 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.
  • callback_on_step_end (Callable, opsional) — Fungsi yang dipanggil di akhir setiap langkah denoising selama inferensi. Fungsi ini dipanggil dengan argumen berikut: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs akan berisi daftar semua tensor sesuai yang ditentukan oleh callback_on_step_end_tensor_inputs.
  • callback_on_step_end_tensor_inputs (List, opsional) — Daftar input tensor untuk fungsi callback_on_step_end. Tensor yang ditentukan dalam daftar akan diteruskan sebagai argumen callback_kwargs. Anda hanya dapat menyertakan variabel yang tercantum dalam atribut ._callback_tensor_inputs dari kelas pipeline Anda.
  • max_sequence_length (int defaultnya 512) — Panjang maksimum urutan yang digunakan dengan prompt.
  • text_encoder_out_layers (tuple[int]) — Indeks layer yang digunakan pada text_encoder untuk menurunkan embedding prompt akhir.

Mengembalikan

~pipelines.flux2.Flux2PipelineOutput atau tuple

~pipelines.flux2.Flux2PipelineOutput jika return_dict bernilai True, selain itu berupa tuple. Saat mengembalikan tuple, elemen pertama adalah daftar berisi gambar yang dihasilkan.

Fungsi yang dipanggil saat memanggil pipeline untuk generasi.

Contoh:

>>> import torch
>>> from diffusers import Flux2KleinPipeline

>>> pipe = Flux2KleinPipeline.from_pretrained(
...     "black-forest-labs/FLUX.2-klein-base-9B", torch_dtype=torch.bfloat16
... )
>>> pipe.to("cuda")
>>> prompt = "A cat holding a sign that says hello world"
>>> # Depending on the variant being used, the pipeline call will slightly vary.
>>> # Refer to the pipeline documentation for more details.
>>> image = pipe(prompt, num_inference_steps=50, guidance_scale=4.0).images[0]
>>> image.save("flux2_output.png")

Flux2KleinKVPipeline

kelas diffusers.Flux2KleinKVPipeline

< >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLFlux2text_encoder: Qwen3ForCausalLMtokenizer: Qwen2Tokenizertransformer: Flux2Transformer2DModelis_distilled: bool = True )

Parameter

  • transformer (Flux2Transformer2DModel) — Arsitektur Conditional Transformer (MMDiT) untuk mendenois latens gambar yang telah dikodekan.
  • scheduler (FlowMatchEulerDiscreteScheduler) — Scheduler yang digunakan bersama transformer untuk menghilangkan noise pada latens gambar yang telah dikodekan.
  • vae (AutoencoderKLFlux2) — Model Variational Auto-Encoder (VAE) untuk mengodekan dan mendekodekan gambar ke dan dari representasi laten.
  • text_encoder (Qwen3ForCausalLM) — Qwen3ForCausalLM
  • tokenizer (Qwen2TokenizerFast) — Tokenizer dari kelas Qwen2TokenizerFast.

Pipeline Flux2 Klein KV untuk generasi teks-ke-gambar dengan kondisioning gambar referensi yang menggunakan KV-cached.

Pada langkah denoising pertama, token gambar referensi disertakan dalam forward pass dan proyeksi K/V perhatian mereka di-cache. Pada langkah-langkah berikutnya, K/V yang di-cache digunakan kembali tanpa dihitung ulang, sehingga memberikan inferensi yang lebih cepat saat menggunakan gambar referensi.

Referensi: https://bfl.ai/blog/flux2-klein-towards-interactive-visual-intelligence

__call__

< >

( image: list[PIL.Image.Image] | PIL.Image.Image | None = Noneprompt: str | list[str] = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 4sigmas: list[float] | None = Nonenum_images_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneoutput_type: str = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']max_sequence_length: int = 512text_encoder_out_layers: tuple[int] = (9, 18, 27) )

Parameter

  • image (PIL.Image.Image atau List[PIL.Image.Image], opsional) — Gambar referensi untuk kondisioning. Pada langkah denoising pertama, token referensi disertakan dalam forward pass dan K/V perhatian mereka dikache. Pada langkah-langkah berikutnya, K/V yang dikache digunakan kembali tanpa menghitung ulang.
  • prompt (str atau List[str], opsional) — Prompt atau prompt-prompt untuk mengarahkan generasi gambar.
  • height (int, opsional) — Tinggi gambar yang dihasilkan dalam piksel.
  • width (int, opsional) — Lebar gambar yang dihasilkan dalam piksel.
  • num_inference_steps (int, opsional, default 4) — Jumlah langkah denoising.
  • sigmas (List[float], opsional) — Sigmas kustom untuk jadwal denoising.
  • num_images_per_prompt (int, opsional, default 1) — Jumlah gambar yang akan dihasilkan per prompt.
  • generator (torch.Generator atau List[torch.Generator], opsional) — Generator untuk generasi deterministik.
  • latents (torch.Tensor, opsional) — Latents berisik yang telah dibuat sebelumnya.
  • prompt_embeds (torch.Tensor, opsional) — Embedding teks yang telah dibuat sebelumnya.
  • output_type (str, opsional, default "pil") — Format output: "pil" atau "np".
  • return_dict (bool, opsional, default True) — Apakah akan mengembalikan Flux2PipelineOutput atau tuple biasa.
  • attention_kwargs (dict, opsional) — Kwargs tambahan yang diteruskan ke pemroses perhatian.
  • callback_on_step_end (Callable, opsional) — Fungsi callback yang dipanggil di akhir setiap langkah denoising.
  • callback_on_step_end_tensor_inputs (List, opsional) — Input tensor untuk fungsi callback.
  • max_sequence_length (int, defaultnya 512) — Panjang maksimum urutan untuk prompt.
  • text_encoder_out_layers (tuple[int]) — Indeks layer untuk ekstraksi hidden state dari text encoder.

Fungsi yang dipanggil saat memanggil pipeline untuk generasi.

Contoh:

>>> import torch
>>> from PIL import Image
>>> from diffusers import Flux2KleinKVPipeline

>>> pipe = Flux2KleinKVPipeline.from_pretrained(
...     "black-forest-labs/FLUX.2-klein-9b-kv", torch_dtype=torch.bfloat16
... )
>>> pipe.to("cuda")
>>> ref_image = Image.open("reference.png")
>>> image = pipe("A cat dressed like a wizard", image=ref_image, num_inference_steps=4).images[0]
>>> image.save("flux2_kv_output.png")
Update on GitHub

←Flux Flux3→