在 Diffusers 中欢迎 FLUX.3 Image Klein

来源: https://huggingface.co/blog/flux-3

Black Forest Labs (https://huggingface.co/black-forest-labs)

FLUX.3 Image Klein 来了，首发即支持 Diffusers。一个模型同时支持文本生图和多参考图的图生图，还带来了新功能——布局控制。你可以在提示词中写入边界框，指定图像中每个部分应放置的位置，或移动参考图中的某个区域。两个开放权重检查点都收录在 FLUX.3 Image Klein 合集中：一张雪林中的红狐（文本生图）、同一只狐狸从该图重新渲染的版本（图生图）、黄绿色背景上黑色点画风格的奔跑剪影（在标注的边界框内绘制）、以及一只编织骑士从“来源“框移动到编织巨龙旁的“目标“框（布局编辑）。

你可以直接前往 Hugging Face Space 立即开始生成图像！

TL;DR

• 一个模型同时支持文本生图、多参考图图生图和边界框布局控制。
• 蒸馏检查点在 H100 上约 2 秒内生成一张 1024 × 1024 图像。
• NVFP4 和 FP8 权重可通过 from_single_file 加载，适配显存较小的 GPU。
• 提供文本生图和图像编辑的 LoRA 训练脚本。
• 以 Modular Diffusers 管线形式发布，你可以随意拆卸或添加模块。

目录

• 快速开始
• FLUX.3 能做什么
• 基础模型与量化变体
• LoRA 微调
• 运行成本
• 架构
• Modular Diffusers
• 开始使用

快速开始

安装最新版 diffusers 和 transformers（用于 Qwen3-VL 文本编码器）：

pip install -U diffusers transformers

加载蒸馏检查点并生成图像：

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")
pipe(prompt="a red fox", output="images")[0].save("fox.png")

FLUX.3 能做什么

文本生图

FLUX.3 对完整的场景描述响应最佳，包括主体、环境、光线、构图和风格。Black Forest Labs 的官方提示词指南中有更多技巧。

蒸馏检查点默认通过 16 步生成一张 1024 × 1024 图像。传入 height、width 或 num_inference_steps 可以更改这些参数。

prompt = (
    "A wide-angle wildlife photograph of a red fox standing alert in a snow-covered forest clearing at golden hour. "
    "The fox is centered in the frame, its thick orange winter coat contrasting with the fresh white snow, breath "
    "visible in the cold air. Snow-laden pine trees fill the softly blurred background, and low warm sunlight rakes "
    "across the scene from the left, casting long blue shadows."
)
fox = pipe(
    prompt=prompt,
    generator=torch.Generator().manual_seed(0),
    output="images"
)[0]
fox.save("fox.png")

一只红狐站在雪林空地上，被左侧低角度金色阳光照亮

文本生图

图生图

通过 image 参数传入参考图（可以多张）。将提示词写成你期望得到的图像描述，并包含变化内容。

prompt = (
    "The same red fox in the same snow-covered forest clearing, now at night under a full moon: cool blue "
    "moonlight, deep shadows, stars visible through the pine branches, the fox's eyes catching the light."
)
night = pipe(
    prompt=prompt,
    image=fox,  # 来自前一个文本生图示例
    generator=torch.Generator().manual_seed(0),
    output="images",
)[0]
night.save("night.png")

上一张图中的狐狸，在冷蓝色月光下重新渲染

图生图

当使用多张参考图时，在提示词中按照传入 image 的顺序依次提及 <ref_image_0>、<ref_image_1> …：

red_fox = pipe(prompt="a red fox", generator=torch.Generator().manual_seed(0), output="images")[0]
bench = pipe(prompt="a wooden bench", generator=torch.Generator().manual_seed(0), output="images")[0]
combined = pipe(
    prompt="The fox from <ref_image_0> sitting on the wooden bench from <ref_image_1> in a snowy setting.",
    image=[red_fox, bench],
    output="images",
)[0]
combined.save("combined.png")

布局控制

在描述文字后面添加一个 JSON 区域列表。每个区域包含 id、bbox 和 desc，描述文字中通过 <region_id> 引用它。

边界框格式为 [y_min, x_min, y_max, x_max]，y 在前，取值范围为 0–1000 的标准化尺度。由于尺度已归一化，同一边界框适用于任何图像尺寸。

在新图像中放置区域

layout_prompt = (
    "Minimalist graphic illustration featuring a black silhouette of a person centered against a "
    "solid, vibrant chartreuse background <background_1>. The figure is captured in a dynamic, mid-stride running "
    "pose, facing toward the left side of the frame. "
    '[{"id": "background_1", "bbox": [0, 0, 1000, 1000], "desc": "A flat field of neon yellow-green with a subtle '
    'paper texture and fine, organic grain."}, {"id": "silhouette_1", "bbox": [150, 150, 850, 850], "desc": "A '
    'black silhouette of a person in motion, made of dense stippled ink. The leading edges are solid; the trailing '
    'arm and leg dissolve into coarse square pixels and scattered dots."}]'
)
runner = pipe(prompt=layout_prompt, generator=torch.Generator().manual_seed(0), output="images")[0]

示意图：左侧为描述文字和两个区域描述，中间为 0–1000 网格上的两个边界框，右侧为生成的图像——一个黑色点画风格的奔跑者填满剪影框，背景为黄绿色

每个区域的 desc 绘制在其 bbox 内

在参考图中移动区域

对于编辑操作，每个区域指定其内容来自参考图中的哪个位置（src_bbox）以及要移动到输出图像中的哪个位置（tgt_bbox）。如果两个边界框相同，该区域保持原位不动。

此示例将编织骑士向上向左移动，并固定背景、悬崖、缝合针、巨龙和火焰：

from diffusers.utils import load_image

knight_image = load_image("knight_orig.png")

edit_prompt = (
    "In <ref_image_0>, move the miniature grey amigurumi knight figure <knight_1> upwards and to the left along the "
    "yarn cliff <cliff_1>. Keep the rest of the image completely unchanged, preserving the blurred yarn backdrop "
    "<backdrop_1>, the large knitted dragon <dragon_1>, and the fiery orange thread <fire_1>. "
    '[{"id": "knight_1", "from": "ref_image_0", "src_bbox": [500, 150, 850, 350], "tgt_bbox": [194, 55, 544, 255], '
    '"desc": "A miniature amigurumi knight crocheted from thick grey woolen yarn."}, '
    '{"id": "backdrop_1", "from": "ref_image_0", "src_bbox": [0, 0, 1000, 1000], "tgt_bbox": [0, 0, 1000, 1000], '
    '"desc": "A soft, out-of-focus backdrop of cream and indigo knitted yarn."}, '
    '{"id": "cliff_1", "from": "ref_image_0", "src_bbox": [300, 0, 1000, 450], "tgt_bbox": [300, 0, 1000, 450], '
    '"desc": "A steep cliff of stacked yarn skeins in mustard, terracotta, and indigo."}, '
    '{"id": "needle_1", "from": "ref_image_0", "src_bbox": [420, 250, 550, 450], "tgt_bbox": [420, 250, 550, 450], '
    '"desc": "An oversized polished steel tapestry needle."}, '
    '{"id": "dragon_1", "from": "ref_image_0", "src_bbox": [100, 600, 950, 1000], "tgt_bbox": [100, 600, 950, 1000], '
    '"desc": "A large, fluffy knitted dragon in terracotta and mustard yarn."}, '
    '{"id": "fire_1", "from": "ref_image_0", "src_bbox": [350, 400, 650, 650], "tgt_bbox": [350, 400, 650, 650], '
    '"desc": "Curled puffs of fiery orange angora thread suspended in mid-air."}]'
)
moved = pipe(prompt=edit_prompt, image=knight_image, generator=torch.Generator().manual_seed(0), output="images")[0]

左侧：参考图及骑士的来源框。右侧：输出图像，箭头从来源框指向目标框；被固定的区域以白色描边标出

骑士从其 src_bbox 移动到 tgt_bbox，场景其余部分保持不变

基础模型与量化变体

基础模型

以上示例均使用蒸馏检查点。基础检查点运行 50 步并使用无分类器引导，是微调所用的版本（参见 LoRA 微调）。

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")
pipe.guider = pipe.guider.new(guidance_scale=5.0)  # 可选
image = pipe(prompt=prompt, output="images")[0]

单文件格式检查点

Black Forest Labs 还以单文件形式发布 transformer，包括 bf16 和两种量化格式：fp8r（行级 FP8）和 nvfp4。使用 from_single_file 加载任意格式，然后按名称加载其他组件，以避免同时下载 bf16 transformer。

from diffusers import BFLQuantizationConfig, Flux3Transformer2DModel, ModularPipeline

model_id = "black-forest-labs/flux-3-image-klein-base"
variant = "fp8r"  # 或 "nvfp4"

transformer = Flux3Transformer2DModel.from_single_file(
    f"https://huggingface.co/{model_id}/blob/main/variants/{variant}/model.safetensors",
    config=model_id,
    subfolder="transformer",
    quantization_config=BFLQuantizationConfig(compute_dtype=torch.bfloat16),
    dtype=torch.bfloat16,
)

pipe = ModularPipeline.from_pretrained(model_id)
pipe.load_components(dtype=torch.bfloat16)
pipe.update_components(transformer=transformer)
pipe.to("cuda")

对于未量化的单文件，使用 https://huggingface.co/{model_id}/blob/main/model.safetensors 并省略 quantization_config。

LoRA 微调

FLUX.3 同时支持文本生图和图生图，是自定义 LoRA 的理想基础模型。diffusers 为两种任务都提供了 DreamBooth LoRA 训练脚本（你也可以使用 Ostris 的 AI Toolkit 进行训练）。

以下是文本生图示例，从 multimodalart/1920-raider-waite-tarot-public-domain 数据集学习塔罗牌风格，通过 trtcrd 触发词激活：

accelerate launch train_dreambooth_lora_flux3_klein.py \
  --pretrained_model_name_or_path="black-forest-labs/flux-3-image-klein-base" \
  --dataset_name="multimodalart/1920-raider-waite-tarot-public-domain" \
  --caption_column="caption" \
  --instance_prompt="trtcrd" \
  --output_dir="trained-flux3-tarot-lora" \
  --mixed_precision="bf16" \
  --resolution=1024 \
  --use_aspect_ratio_buckets \
  --train_batch_size=1 \
  --rank=16 \
  --lora_alpha=16 \
  --learning_rate=1e-4 \
  --lr_scheduler="constant" \
  --max_train_steps=1500 \
  --validation_prompt="a trtcrd of a cat, tarot style" \
  --validation_epochs=25 \
  --seed=0 \
  --push_to_hub

为降低显存使用，添加以下优化标志：

--gradient_checkpointing
--cache_latents
--use_8bit_adam

--gradient_checkpointing 在反向传播中重新计算激活值（降低显存，稍慢），--cache_latents 预编码图像并释放 VAE，--use_8bit_adam 将优化器状态保持在 8 位精度。

有几个参数值得实验。下方网格使用不同的 LoRA rank 和优化器训练相同的塔罗牌风格；适配器已发布在 Hub 上的 diffusers-modular/flux3-tarot-lora。更多训练功能和配置详见 DreamBooth FLUX.3 README。

不同 rank 和优化器下的 FLUX.3 塔罗风格 LoRA：基础模型（无 LoRA）、rank 16、rank 8、rank 32（AdamW，lr 1e-4）和 Prodigy，在两个保留提示词上的效果

对于基于指令的编辑，图生图脚本（train_dreambooth_lora_flux3_klein_img2img.py）在（参考图、目标图、指令）三元组上训练，其中参考图在提示词中以 <ref_image_0> 引用。所有选项和完整的图生图示例详见 DreamBooth FLUX.3 README。

运行成本

本节介绍模型的显存消耗和生成速度。

显存

如果显存不足：

• 加载量化后的 transformer。
• 单独运行文本编码器并及时释放。它每张图只在去噪前运行一次（参见一次编码，多次生成）。
• 开启自动 CPU 卸载，仅在各组件运行时将其移至 GPU（我们未对此进行基准测试）：

from diffusers import ComponentsManager, ModularPipeline

manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")

pipe = ModularPipeline.from_pretrained(
    "black-forest-labs/flux-3-image-klein", components_manager=manager
)
pipe.load_components(dtype={"vae": torch.float32, "default": torch.bfloat16})
# 不要调用 pipe.to("cuda")：由 manager 负责设备放置

速度

蒸馏检查点（16 步）的端到端计时，预热后三次运行取平均：

单张 NVIDIA H100 80GB，无卸载，默认注意力后端。

参考图大致会使耗时翻倍。参考图的 token 会加入与文本和待生成图像相同的序列中，因此一张 1024 × 1024 的参考图会在每个前向传播中额外增加 4,096 个 token。