FLUX.3 Image Klein 开源图像模型：提示词里写框就能控制布局

原文要点

Black Forest Labs 的 FLUX.3 Image Klein 已在 Diffusers 中可用：一个模型同时支持文生图、多参考图的图生图和布局控制——在提示词正文后附一段 JSON 区域列表，用 id、bbox（0–1000 归一化坐标、[y_min, x_min, y_max, x_max]，y 在前）和 desc 描述区域，正文里用 <id> 引用即可指定元素位置；编辑时用 src_bbox/tgt_bbox 指出来源与去向。参考图在提示词中以 <ref_image_0> 等标记引用。提供蒸馏版（默认 16 步、无 CFG）与 base 版（50 步、带 CFG）两个 checkpoint，另有 fp8r 与 nvfp4 量化单文件权重及 DreamBooth LoRA 训练脚本；文中称蒸馏版在单张 H100 上约 1.93 秒生成 1024×1024 图（作者基准），峰值显存约 23.8 GiB，量化可降到约 13–16 GiB。

这次做成什么

照着本页在本机或云 GPU 上装好 Diffusers 版 FLUX.3 Klein，先跑通一张文生图，再用「提示词里写 JSON 框」的方式做出一张布局受控的图，完成一次可复现的小练习。

准备什么

• Python 3.10+ 环境，可运行 pip 安装
• 一张 NVIDIA GPU：bf16 推理建议约 24 GiB 显存，显存不足时用文中 fp8r/nvfp4 量化权重（fp8r 快速内核要求 Compute Capability 8.9+，否则只省显存不提速）
• 已注册 Hugging Face 并能访问 black-forest-labs/flux-3-image-klein 模型页（注意其许可条款）
• 文中命令为 Linux 风格，Windows 建议用 WSL2

具体怎么做

1. 安装依赖

   在虚拟环境中执行：pip install -U diffusers transformers。transformers 是必须的，因为文本编码器用的是 Qwen3-VL。

2. 加载蒸馏模型并生成第一张图

   新建脚本，用 ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein")，再 pipe.load_components(dtype=torch.bfloat16)、pipe.to("cuda")；调用 pipe(prompt="a red fox", output="images")[0].save("fox.png") 验证管线能跑通。完整代码见下方材料。

3. 写一条带 JSON 框的布局提示词

   按三段式构造：先写一段完整画面描述，正文中用 <id> 点名各元素；再附 JSON 数组，每个区域含 id、bbox（y 在前、0–1000 归一化）、desc。坐标与最终分辨率无关，同一组框可用于任意输出尺寸。直接用下方材料里的完整示例替换你自己的元素即可。

4. 生成并检查布局

   用固定 seed（如 manual_seed(0)）生成，保存 PNG。对照你写的 bbox 检查各元素是否落在指定区域：背景应铺满 [0,0,1000,1000]，主体应位于你给的框内。若元素跑偏，先调大区域面积或把 desc 写得更具体再重试。

5. （可选）显存不足时换量化权重

   用 Flux3Transformer2DModel.from_single_file 加载 fp8r 或 nvfp4 单文件 transformer（配 BFLQuantizationConfig），再用 update_components 替换进管线，避免重复下载 bf16 transformer。具体 URL 模板以原文为准。

可直接复制的材料

import torch
from diffusers import ModularPipeline

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

image = pipe(prompt="a red fox", output="images")[0]
image.save("fox.png")

Warm flat-style illustration of a cozy reading corner: a wooden bookshelf <bookshelf_1> on the left, a round orange cat <cat_1> sleeping on a small rug <rug_1> at the bottom right, soft evening light filling the whole background <background_1>.
[{"id": "background_1", "bbox": [0, 0, 1000, 1000], "desc": "A warm cream wall with a large window showing a dusky blue evening sky and a few early stars."}, {"id": "bookshelf_1", "bbox": [80, 40, 900, 380], "desc": "A tall wooden bookshelf with five shelves filled with colorful books and one small potted plant on top."}, {"id": "rug_1", "bbox": [680, 520, 980, 980], "desc": "A small round braided rug in muted red and beige stripes."}, {"id": "cat_1", "bbox": [700, 560, 940, 940], "desc": "A chubby orange tabby cat curled up asleep, tail wrapped around its body."}]

输入与输出示例

本站虚构演示与排错建议，非原作者运行结果；实际生成效果受版本与硬件影响。

输入

使用上面布局提示词材料，调用 pipe(prompt=layout_prompt, generator=torch.Generator().manual_seed(0), output="images")[0].save("reading_corner.png")，默认 1024×1024、16 步。

对应输出

得到 reading_corner.png：书架位于画面左侧（约占 y 80–900、x 40–380 对应的左中竖条区域），橘猫蜷在右下角圆形地毯上（约 y 700–940、x 560–940 区域），窗外为暮色天空，整体为暖色扁平插画风格。若猫偏出右下角，可把 cat_1 的 bbox 放宽为 [660, 500, 980, 980] 并重跑同一 seed 对比。

做完检查这些

• pip 安装后 from diffusers import ModularPipeline 不报错，且能下载 flux-3-image-klein 权重
• 无布局提示词能生成并保存 fox.png，确认基础管线跑通
• 用布局提示词生成后，主体元素（书架、猫、地毯）肉眼可见地落在所给 bbox 对应的大致区域内
• 同一 prompt 同一 seed 重跑两次，画面布局基本一致，便于对照调框效果

容易卡住的地方

• bbox 是 y 在前 [y_min, x_min, y_max, x_max]，写成 x 在前会导致元素全部错位，这是最常见的失败原因
• 坐标是 0–1000 归一化值，不要写像素值；改分辨率不需要改框
• 蒸馏版 16 步且无 CFG，不要照搬 base 版的 guidance_scale 用法；微调要选 base checkpoint
• 参考图标记 <ref_image_0> 的序号必须与 image 参数传入顺序一致，顺序错了会引用错图
• 文中 1.93 秒等耗时是作者在单张 H100 上的基准，不等于你的硬件能达到；消费级显卡请优先考虑量化权重并预留加载时间
• nvfp4 需要 Blackwell 显卡并搭配同版本 flashinfer-python 与 flashinfer-cubin，不满足条件时不要硬装