FLUX 3 Image Klein

FLUX 3 Image Klein, Black Forest Labs tarafından geliştirilen 5,6B parametreli bir görüntü üretim modelidir: tek bir transformer (Flux3Transformer2DModel), bir metin komutundan, yalnızca kendisi veya bir veya daha fazla referans görüntüyle birlikte görüntüler üretir. Metin koşullandırması Qwen3-VL'den gelir ve görüntüler FLUX.2 paketlenmiş otoenkoderını (AutoencoderKLFlux2) kullanır.

FLUX 3 Image Klein, modüler bir pipeline olarak sunulur. Metinden görüntüye üretimle başlayın:

import torch
from diffusers import ModularPipeline

pipe = ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein-base")
pipe.load_components(dtype={"vae": torch.float32, "default": torch.bfloat16})
pipe.to("cuda")

image = pipe(
    prompt="A red fox in a snow-covered forest clearing at golden hour",
    generator=torch.Generator().manual_seed(0),
    output="images",
)[0]
image.save("fox.png")

prompt tek zorunlu girdidir: pipeline, önerilen örneklem ayarlarını (50 adım, yönlendirme ölçeği 3.5, zamanlayıcı kayması 6.93) taşır ve varsayılan olarak 1024 x 1024 boyutunda görüntüler üretir. Her çağrıda bir prompt alır; aynı prompt için birden fazla görüntü üretmek için num_images_per_prompt parametresini kullanın.

Yukarıdaki örnekte de görebileceğiniz gibi, yükleme ve çalıştırma DiffusionPipeline'den biraz farklıdır. Yükleme tembel (lazy)dir: from_pretrained() yalnızca hattı (pipeline) oluşturur ve ağırlıkları yüklemek için load_components() çağrısını yaparsınız. Bir çağrı hattın durumunu döndürür ve ihtiyacınız olanı output ile istersiniz: burada output="images" veya prompt upsampler'ın yazdığı başlığı da almak için output=["images", "prompt"].

If you’re working with ModularPipeline for the first time, read the quickstart, and Coming from DiffusionPipeline if you know the standard pipelines. Besides loading and outputs, a few other things differ: guidance, callbacks and offloading.

Prompt örnekleme

Prompting önemlidir: FLUX 3 Image Klein, kısa promptlar yerine konuyu, kompozisyonu, aydınlatmayı ve atmosferi açıklayan tam sahne betimlemeleri alır; olduğu gibi gönderilen bir istek genel bir çıktı verir. Bu nedenle pipeline, her istekte, metinden görüntüye ve düzenleme olsun, önce prompt upsampler'ı çalıştırır. Black Forest Labs'e ait ayrı bir 9B modeldir (black-forest-labs/flux-3-image-klein-pup) ve metin kodlayıcıdan önce prompt'u böyle bir betimlemeye genişletir; bunun için kısa bir prompt yeterlidir.

Prompt upsampler, kısa bir isteği (düzenleme sırasında referans görsellerle birlikte) modelin kullandığı tam sahne açıklamasına dönüştürür: orta ve stil, sahne, aydınlatma ve kamera, her bir konunun renkleri, malzemeleri ve karedeki konumu. Tek bir model, metinden görsel oluşturma, referans görsellerle düzenleme ve kutularla yerleşim düzenini kapsar. Yazdığı açıklama, prompt çıktısı olarak geri döner. Yukarıdaki örnekte, görsel modelinin ne aldığını görmek için görsellerle birlikte isten:

out = pipe(
    prompt="A red fox in a snow-covered forest clearing at golden hour",
    generator=torch.Generator().manual_seed(0),
    output=["images", "prompt"],
)
print(out["prompt"])

Full-color outdoor wildlife photograph taken from a low eye-level perspective in a snow-covered forest clearing at golden hour. In the center foreground, a red fox stands in profile facing left, its body turned toward the viewer and its head raised as it looks across the clearing. The fox has dense rust-red winter fur, a white throat and chest, black lower legs, pointed ears with dark tips, and a long bushy tail ending in white. ...

Tam açıklama yaklaşık 240 kelime uzunluğundadır; max_new_tokens uzunluğunu sınırlar (varsayılan olarak 3584).

Adımın doc değerini yazdırarak ne aldığını ve ne yazdığını görebilirsiniz:

print(pipe.blocks.sub_blocks["prompt_upsampler"].doc)

  Inputs:
      prompt (`str`):
          The edit instruction to expand into the full caption (one per call).
      image (`Image | list`, *optional*):
          The reference image(s) of the edit, at most 10; the same ones the pipeline receives.
      boxes (`list`, *optional*):
          Layout boxes, each {'id', 'desc', 'from', 'src_bbox', 'tgt_bbox'} with the boxes as [y_min, x_min, y_max, x_max] in
          0-1: ...
      max_new_tokens (`int`, *optional*, defaults to 3584):
          The most tokens the upsampler may generate for the caption.

  Outputs:
      prompt (`str`):
          The full caption, replacing the request.

Hattın diğer blokları gibi prompt_upsampler bloğu da kendi başına çalışır. Önerilen yöntem, bloklardan çıkarılmasıdır: çıkarılan blok bağımsız bir upsampler olur, kalan bloklar ise genişletilmiş başlığı prompt olarak alan bir hat oluşturur:

blocks = ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein-base").blocks
pup_block = blocks.sub_blocks.pop("prompt_upsampler")

pup = pup_block.init_pipeline("black-forest-labs/flux-3-image-klein-base")
pup.load_components(dtype=torch.bfloat16)
pup.to("cuda")
caption = pup(prompt="A red fox in a snow-covered forest clearing at golden hour", output="prompt")

pipe = blocks.init_pipeline("black-forest-labs/flux-3-image-klein-base")
pipe.load_components(dtype={"vae": torch.float32, "default": torch.bfloat16})
pipe.to("cuda")
image = pipe(prompt=caption, generator=torch.Generator().manual_seed(0), output="images")[0]

Bu sayede ayrı bir aşama olarak, kendi GPU’sunda veya kendi endpoint’i arkasında sunulabilir ve bir arayüz, yazdığı başlığı gösterebilir ve üretmeden önce kullanıcının düzenlemesine izin verebilir. Upsampler’ın yerini aynı sistem istemleriyle herhangi bir başka LLM alabilir: upsampler deposundan system_prompts["t2i"]’yi (veya referanslar kullanıcı mesajında önce gelecek şekilde "i2i") sistem istemi olarak ve isteği kullanıcı mesajı olarak verin, ardından döndürdüğü başlığı pipe’e prompt olarak iletin.

Görselden görseli

image ile bir veya daha fazla referans görüntü geçin. Tek bir referans bütünüyle korunur: yalnızca 4 megapikselin üzerinde olduğunda küçültülür, 16 piksel ızgarasına tamamlanır ve üretim varsayılan olarak bu boyutu kullanır; bu nedenle düzenleme, girdinin boyutunda geri döner. Birden fazla referansın her biri 1 megapikselin altına sığdırılır ve ızgaraya kırpılır; üretim varsayılan olarak ilkinin boyutunu kullanır. Belirtilen height/width değeri varsayılanı geçersiz kılar. Hedef görüntüyü, tek satırlık bir talimat yerine, düzenlemenizi referansın tam bir açıklamasına entegre ederek tanımlayın ya da prompt upsampler'ın bunu talimattan ve referanslardan yazmasına izin verin:

night = pipe(
    prompt="the same scene at night under a full moon",
    image=image,
    generator=torch.Generator().manual_seed(0),
    output=["images", "prompt"],
)

Birden fazla referans varsa, bunlara image parametresine geçiş sırasına göre ilk görsel, ikinci görsel, … şeklinde atıfta bulunulur; görsel modeli için başlık bunları <ref_image_0>, <ref_image_1>, … olarak adlandırır:

combined = pipe(
    prompt="the fox from the first image sitting on the wooden bench from the second image",
    image=[image, bench],
    height=768,
    width=1360,
    output="images",
)[0]

Türetilen boyutu geçersiz kılmak için height ve/veya width parametrelerini iletin.

Düzen kontrolü

İçeriği açıkça konumlandırmak için boxes parametresini iletin: her öğe için bir id, kısa bir desc ve 0-1 aralığında (orijin sol üst köşe) [y_min, x_min, y_max, x_max] biçiminde bir bbox verin; böylece çıktı boyutundan bağımsız olur. Upsampler, başlığı bu öğelerin etrafına yazar, her öğeyi <id> olarak atıf gösterir ve kutuların tablosunu ekler; sizinkiler aynen korunur:

boxes = [
    {"id": "balloon_1", "desc": "a red and yellow striped hot-air balloon", "bbox": [0.08, 0.06, 0.48, 0.38]},
    {"id": "balloon_2", "desc": "a small blue hot-air balloon", "bbox": [0.20, 0.62, 0.42, 0.80]},
]
out = pipe(prompt="hot-air balloons over a green valley at sunrise", boxes=boxes, output=["images", "prompt"])

Düzenleme sırasında bir kutu, kaynağını from ile adlandırır: tgt_bbox içeren "target", oraya yeni bir öğe ekler; src_bbox ve tgt_bbox içeren "ref_image_0", o referansın bir öğesini taşır (eşit kutular öğeyi yerinde tutar):

boxes = [{"id": "cactus", "desc": "a small potted cactus", "from": "target", "src_bbox": None, "tgt_bbox": [0.55, 0.62, 0.85, 0.85]}]
out = pipe(prompt="add a small potted cactus in the marked spot", image=mug, boxes=boxes, output=["images", "prompt"])

boxes = [{"id": "knight", "desc": "the knight figure", "from": "ref_image_0", "src_bbox": [0.50, 0.15, 0.85, 0.35], "tgt_bbox": [0.19, 0.06, 0.54, 0.26]}]
out = pipe(prompt="move the knight up and to the left, keep the rest unchanged", image=knight, boxes=boxes, output=["images", "prompt"])

Görsel modelin okuduğu başlık, metindeki <id> etiketli öğeleri ve 0-1000 tuvalinde kutularla JSON olarak eklenen tabloyu içerir; görmek için prompt çıktısını yazdırın. Bu formda elle yazılan bir başlık, Prompt upsampling örneğinde olduğu gibi, bu adım olmadan doğrudan pipeline'a gönderilir.

Yönlendirme ölçeği

Pipeline, guider bileşeni aracılığıyla classifier-free guidance uygular ve çağrı sırasında guidance_scale argümanı almaz. Varsayılan guider, her iki iş akışı için önerilen ayar olan guidance_scale=3.5 değerine sahip ClassifierFreeGuidance'dir. Değiştirmek için guider'ın güncellenmiş bir kopyasını oluşturun:

pipe.guider = pipe.guider.new(guidance_scale=5.0)

Farklı bir yönlendirme yöntemine geçmek için yönlendiriciler kılavuzuna bakın.

Adım-distilled model

Step-distilled checkpoint, classifier-free guidance olmadan 16 adımda üretim yapar. Transformer'ı bir akış haritasıdır: her adımda hem mevcut timestep hem de adımın atlayacağı timestep kendisine bildirilir. Temel model gibi yüklenir (deponun modular_model_index.json dosyası Flux3DistilledModularPipeline ve Flux3DistilledAutoBlocks olarak çözümlenir); pipeline'da guider yoktur ve negative_prompt parametresini kabul etmez:

pipe = ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein")
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")

image = pipe(prompt=prompt, generator=torch.Generator().manual_seed(0), output="images")[0]

Temel modelle aynı iki iş akışını sunar. num_inference_steps varsayılan olarak 16'dır; model 4 ila 16 adım için eğitilmiştir.

Tekrarlanabilir üretim

generator, hattın çektiği gürültüyü sabitler (bkz. Tekrarlanabilirlik). Başka bir yerde çekilen gürültüyü yeniden kullanmak için, (batch_size, 128, height // 16, width // 16) biçiminde latents olarak iletin. Örneğin, BFL uygulaması gürültüsünü CPU üzerinde görüntü jetonları olarak çeker ve bf16'ya dönüştürür; bu, belirli bir tohum için örneğini yeniden üretir:

height, width = 1024, 1024
h, w = height // 16, width // 16

noise = torch.randn((h * w, 128), generator=torch.Generator().manual_seed(0)).to(torch.bfloat16)
latents = noise.T.reshape(1, 128, h, w)

image = pipe(prompt=prompt, latents=latents, height=height, width=width, output="images")[0]

İş Akışları

Pipeline iki iş akışına hizmet eder: text2image ve image_conditioned; çalıştırılacak olanı girdiler belirler (image, image-to-image iş akışını seçer). from_pretrained(), workflow argümanı ile tek bir iş akışı için de pipeline oluşturabilir; bu durumda yalnızca ilgili iş akışının gerektirdiği bileşenler beklenir ve yüklenir:

from diffusers.modular_pipelines import Flux3AutoBlocks

print(Flux3AutoBlocks().available_workflows)
# ["text2image", "image_conditioned"]

t2i = ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein-base", workflow="text2image")
print(t2i.blocks.doc)

Adım başına geri çağrılar

Mevcut bir geri çağırma işlevini kullanmak için, gürültü azaltma döngüsüne bir blok ekleyin. geri çağırma kılavuzu, CallbackOnStepEnd bloğu ve walk_denoise_loops yardımcısıyla basit bir örnek içerir:

blocks = Flux3AutoBlocks()  # or Flux3DistilledAutoBlocks
for loop in walk_denoise_loops(blocks):
    loop.sub_blocks["callback"] = CallbackOnStepEnd()
pipe = blocks.init_pipeline("black-forest-labs/flux-3-image-klein-base")

image = pipe(prompt=caption, callback_on_step_end=my_callback, output="images")[0]

Erken durdurmak için geri çağrıdan (callback) raise kullanın; interrupt bayrağı yoktur.

Bellek

bf16'da her şeyin yüklenmesi yaklaşık 39 GB ağırlık gerektirir: transformer 5,5B parametreye, Qwen3-VL-4B metin kodlayıcısı 4B'ye ve prompt upsampler 9B'ye (tek başına yaklaşık 19 GB) sahipken, görüntü VAE'si fp32'dedir. Upsampler adımı olmadan oluşturulan bir pipeline (oraya bakın) yaklaşık 20 GB yükler. Daha az belleğe sahip GPU'lar için bileşen offloading'i etkinleştirin; yönetici, her adımın ihtiyaç duyduğu bileşenleri (upsampler dahil) CPU ile GPU arasında taşır:

from diffusers import ComponentsManager, ModularPipeline

manager = ComponentsManager()
pipe = ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein-base", components_manager=manager)
pipe.load_components(dtype={"vae": torch.float32, "default": torch.bfloat16})
manager.enable_auto_cpu_offload(device="cuda")

Tek dosya yükleme

Flux3Transformer2DModel, transformer'ı doğrudan bir Black Forest Labs model paketinden from_single_file() ile yükler. Paketin config.json dosyası okunmaz; diffusers yapılandırmasını config ve subfolder ile iletin.

import torch
from diffusers import Flux3Transformer2DModel, ModularPipeline

transformer = Flux3Transformer2DModel.from_single_file(
    "https://huggingface.co/black-forest-labs/flux-3-image-klein-base/blob/main/model.safetensors",
    config="black-forest-labs/flux-3-image-klein-base",
    subfolder="transformer",
    dtype=torch.bfloat16,
)

pipe = ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein-base")
pipe.load_components(dtype={"vae": torch.float32, "default": torch.bfloat16})
pipe.update_components(transformer=transformer)
pipe.to("cuda")

Önce diğer bileşenleri adlarıyla yükleyin: names parametresi olmadan load_components() çağrısı, pipeline deposundan dönüştürücüyü de yükleyecektir.

FP8r ve NVFP4 tek dosyalık checkpoint'lerin yüklenmesi de desteklenir. İkisi de BFLQuantizationConfig ile aynı çağrı üzerinden yüklenir. Her şema için çekirdek gereksinimlerini görmek için BFL kuantizasyon kılavuzu'na bakın.

from diffusers import BFLQuantizationConfig

transformer = Flux3Transformer2DModel.from_single_file(
    "https://huggingface.co/black-forest-labs/flux-3-image-klein-base/blob/main/variants/nvfp4/model.safetensors",
    config="black-forest-labs/flux-3-image-klein-base",
    subfolder="transformer",
    quantization_config=BFLQuantizationConfig(compute_dtype=torch.bfloat16),
    dtype=torch.bfloat16,
)

Adım damıtılmış denetim noktalarını yüklerken yapılandırmalarına (flow_map=True) ihtiyaç duyarız:

transformer = Flux3Transformer2DModel.from_single_file(
    "https://huggingface.co/black-forest-labs/flux-3-image-klein/blob/main/variants/nvfp4/model.safetensors",
    config="black-forest-labs/flux-3-image-klein",
    subfolder="transformer",
    quantization_config=BFLQuantizationConfig(compute_dtype=torch.bfloat16),
    dtype=torch.bfloat16,
)

Flux3ModularPipeline

Flux3AutoBlocks

Flux3DistilledAutoBlocks

Flux3DistilledModularPipeline