FLUX 3 Image Klein

FLUX 3 Image Klein là mô hình tạo ảnh 5.6B từ Black Forest Labs: một transformer duy nhất (Flux3Transformer2DModel) tạo ảnh từ một prompt văn bản, hoạt động độc lập hoặc cùng với một hoặc nhiều ảnh tham chiếu. Điều kiện văn bản đến từ Qwen3-VL, và ảnh sử dụng autoencoder đóng gói FLUX.2 (AutoencoderKLFlux2).

FLUX 3 Image Klein được phát hành dưới dạng pipeline module hóa. Bắt đầu với việc tạo ảnh từ văn bả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 là đầu vào bắt buộc duy nhất: pipeline mang theo các cài đặt lấy mẫu được khuyến nghị (50 bước, guidance scale 3.5, scheduler shift 6.93) và mặc định tạo ảnh kích thước 1024 x 1024. Mỗi lần gọi chỉ nhận một prompt; dùng num_images_per_prompt để tạo nhiều ảnh từ cùng một prompt.

Như bạn có thể thấy trong ví dụ ở trên, việc tải và chạy hơi khác so với DiffusionPipeline. Việc tải là theo kiểu lười (lazy): from_pretrained() chỉ xây dựng pipeline, và bạn gọi load_components() để tải trọng số. Một lời gọi sẽ trả về trạng thái của pipeline, và bạn yêu cầu những gì cần thiết bằng output: ở đây là output="images", hoặc output=["images", "prompt"] để cũng nhận được chú thích mà prompt upsampler đã viết.

Nếu bạn làm việc với ModularPipeline lần đầu tiên, hãy đọc quickstart, và Coming from DiffusionPipeline nếu bạn đã quen thuộc với các pipeline chuẩn. Ngoài việc tải và đầu ra, một số điểm khác biệt khác là: guidance, callbacks và offloading.

Mẫu hóa lại prompt

Việc tạo prompt rất quan trọng: FLUX 3 Image Klein nhận các mô tả cảnh hoàn chỉnh, trong đó nêu rõ chủ thể, bố cục, ánh sáng và bầu không khí, chứ không phải các prompt ngắn; một yêu cầu được gửi đúng như cách gõ sẽ cho ra kết quả chung chung. Đó là lý do pipeline chạy bộ mở rộng prompt trước tiên cho mọi yêu cầu, dù là tạo ảnh từ văn bản hay chỉnh sửa. Đây là một mô hình 9B riêng biệt từ Black Forest Labs (black-forest-labs/flux-3-image-klein-pup) có nhiệm vụ mở rộng prompt thành một mô tả như vậy trước khi đưa vào bộ mã hóa văn bản, và chỉ cần một prompt ngắn là đủ.

Upsampler prompt biến một yêu cầu ngắn, cùng với các hình ảnh tham chiếu khi chỉnh sửa, thành mô tả cảnh hoàn chỉnh mà mô hình sử dụng: medium và style, cảnh, ánh sáng và camera, mỗi chủ thể cùng màu sắc, vật liệu và vị trí của nó trong khung hình. Một mô hình bao phủ text-to-image, chỉnh sửa với hình ảnh tham chiếu và layout với các hộp. Mô tả mà nó viết được trả về dưới dạng đầu ra prompt. Trong ví dụ trên, hãy yêu cầu nó cùng với các hình ảnh để xem mô hình hình ảnh đã nhận được gì:

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

Đoạn chú thích đầy đủ dài khoảng 240 từ; max_new_tokens giới hạn độ dài của nó (mặc định là 3584).

Bạn có thể in doc của bước để xem nó nhận những gì và ghi ra những gì:

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.

Tương tự như các khối khác trong pipeline, khối prompt_upsampler cũng chạy độc lập. Cách được khuyến nghị là tách nó ra khỏi các khối: khối bị tách ra sẽ trở thành một upsampler độc lập, và các khối còn lại sẽ tạo thành một pipeline nhận caption đã mở rộng dưới dạng prompt:

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]

Nhờ đó, nó có thể được triển khai như một giai đoạn riêng biệt, trên GPU riêng hoặc sau endpoint riêng, và giao diện người dùng có thể hiển thị chú thích mà nó đã viết, cho phép người dùng chỉnh sửa trước khi tạo ảnh. Bất kỳ LLM nào khác cũng có thể thay thế upsampler, với cùng các system prompt: hãy cung cấp system_prompts["t2i"] từ kho upsampler (hoặc "i2i", với các tham chiếu đặt trước trong user message) làm system prompt và yêu cầu làm user message, sau đó truyền chú thích mà nó trả về dưới dạng prompt cho pipe.

Ảnh sang ảnh

Truyền một hoặc nhiều hình ảnh tham chiếu bằng image. Một tham chiếu đơn được giữ nguyên vẹn: nó chỉ bị giảm kích thước khi vượt quá 4 megapixel, được đệm lên lưới 16 pixel, và kích thước mặc định của quá trình tạo sẽ khớp với kích thước của nó, do đó kết quả chỉnh sửa sẽ có cùng kích thước với đầu vào. Nhiều tham chiếu sẽ mỗi cái được điều chỉnh dưới 1 megapixel và cắt theo lưới, và kích thước mặc định của quá trình tạo sẽ lấy theo kích thước của tham chiếu đầu tiên. Giá trị height/width cụ thể sẽ ghi đè lên mặc định. Hãy mô tả hình ảnh mục tiêu như một chú thích hoàn chỉnh của hình tham chiếu với phần chỉnh sửa của bạn được tích hợp vào, thay vì một dòng hướng dẫn ngắn, hoặc để prompt upsampler viết ra từ hướng dẫn và các hình tham chiếu:

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

Với một số tham chiếu, hãy gọi chúng là hình ảnh đầu tiên, hình ảnh thứ hai, … theo thứ tự chúng được truyền vào image; chú thích gọi chúng là <ref_image_0>, <ref_image_1>, … đối với mô hình hình ảnh:

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]

Truyền height và/hoặc width để ghi đè kích thước đã suy ra.

Kiểm soát bố cục

Để đặt nội dung một cách rõ ràng, hãy truyền boxes: cho mỗi phần tử một id, một desc ngắn, và một bbox dạng [y_min, x_min, y_max, x_max] trong khoảng 0-1 (gốc ở góc trên bên trái), để nó độc lập với kích thước đầu ra. Bộ tăng độ phân giải sẽ viết chú thích xung quanh chúng, trích dẫn mỗi phần tử dưới dạng <id>, và thêm bảng các hộp, giữ nguyên chính xác hộp của bạn:

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

Khi chỉnh sửa, một hộp chỉ định nguồn của nó bằng from: "target" kèm tgt_bbox sẽ thêm một phần tử mới tại đó, "ref_image_0" kèm src_bbox và tgt_bbox sẽ di chuyển một phần tử của ảnh tham chiếu đó (các hộp bằng nhau sẽ giữ nguyên vị trí):

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

Caption mà mô hình ảnh đọc có các phần tử được gắn thẻ <id> trong văn bản và bảng được nối thêm dưới dạng JSON, với các hộp trên canvas 0-1000; in ra kết quả prompt để xem. Một caption được viết theo dạng đó bằng tay sẽ được đưa vào pipeline mà không cần bước này, như trong Prompt upsampling.

Thang độ dẫn

Pipeline áp dụng classifier-free guidance thông qua thành phần guider và không nhận đối số guidance_scale tại thời điểm gọi. Guider mặc định là ClassifierFreeGuidance với guidance_scale=3.5, cài đặt được khuyến nghị cho cả hai workflow. Để thay đổi, hãy tạo một bản sao cập nhật của guider:

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

Xem hướng dẫn cho guider để chuyển sang phương pháp guidance khác.

Mô hình được chưng cất theo bước

Checkpoint được chưng cất theo bước tạo ra kết quả trong 16 bước mà không cần classifier-free guidance. Transformer của nó là một flow map: ở mỗi bước, nó được cung cấp timestep hiện tại và timestep mà bước đó nhảy tới. Nó được nạp giống như mô hình cơ sở (tệp modular_model_index.json trong kho chỉ đến Flux3DistilledModularPipeline và Flux3DistilledAutoBlocks); pipeline không có guider và không nhận negative_prompt:

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]

Nó phục vụ cùng hai luồng công việc như mô hình cơ sở. num_inference_steps mặc định là 16; mô hình được huấn luyện trong 4 đến 16 bước.

Tạo ra có thể tái lập

Một generator cố định nhiễu mà pipeline lấy (xem Tính tái lập). Để tái sử dụng nhiễu đã lấy ở nơi khác, hãy truyền nó dưới dạng latents với hình dạng (batch_size, 128, height // 16, width // 16). Ví dụ, cách triển khai của BFL lấy nhiễu dưới dạng các token ảnh trên CPU và chuyển đổi nó sang bf16; điều này tái lập mẫu của nó cho một seed nhất định:

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]

Quy trình làm việc

Pipeline phục vụ hai luồng công việc, text2image và image_conditioned; luồng được thực thi sẽ được chọn dựa trên các đầu vào (image chọn image-to-image). from_pretrained() cũng có thể xây dựng pipeline cho một luồng công việc bằng tham số workflow, khi đó pipeline chỉ kỳ vọng và tải các thành phần mà luồng công việc đó cần:

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)

Callback theo từng bước

Để sử dụng một hàm callback có sẵn, hãy chèn một khối vào vòng lặp khử nhiễu. hướng dẫn về callback có một ví dụ đơn giản với khối CallbackOnStepEnd và hàm trợ giúp walk_denoise_loops:

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]

Để dừng sớm, hãy raise từ callback; không có cờ interrupt.

Bộ nhớ

Việc nạp toàn bộ ở bf16 tiêu tốn khoảng 39 GB trọng số: transformer có 5,5B tham số, text encoder Qwen3-VL-4B có 4B và prompt upsampler có 9B (khoảng 19 GB riêng), với image VAE ở fp32. Một pipeline được xây dựng không có bước upsampler (xem ở đó) nạp khoảng 20 GB. Đối với GPU có bộ nhớ ít hơn, hãy bật component offloading; trình quản lý sẽ di chuyển các component giữa CPU và GPU khi mỗi bước cần đến, bao gồm cả upsampler:

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

Tải tệp đơn

Flux3Transformer2DModel nạp transformer trực tiếp từ gói mô hình của Black Forest Labs bằng from_single_file(). Gói config.json không được đọc; hãy truyền cấu hình diffusers bằng config và subfolder.

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

Tải các thành phần khác theo tên trước: load_components() không có names cũng sẽ tải transformer từ kho pipeline.

Việc nạp các checkpoint đơn tệp FP8r và NVFP4 cũng được hỗ trợ. Cả hai đều được nạp thông qua cùng một lệnh gọi với BFLQuantizationConfig. Xem hướng dẫn lượng tử hóa BFL để biết yêu cầu về kernel của từng phương á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,
)

Khi nạp các checkpoint đã chưng cất theo bước, chúng ta cần cấu hình của chúng (flow_map=True):

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