教程 ↗

FLUX 3 Image Klein 接入:蒸馏权重与提示词扩写

在本地或服务端接入 FLUX 3 Image Klein 时,正确选定 16 步 distilled 权重并保留默认开启的提示词扩写组件。

接入 FLUX 3 Image Klein 蒸馏推理与必选提示词扩写

接入 FLUX 3 Image Klein 时,先选面向生成与编辑的 distilled 权重,并保留提示词扩写器 pup。它会把用户的短句扩成完整场景描述,参考 CLI、Demo 和 Python generate 都默认开启这个步骤。本文对照 BFL 官方仓库,说明组件加载、参考图和布局框输入;未执行安装、模型推理或付费 API 调用。

模型组件边界与权重分工

在规划硬件与进程初始化逻辑前,需要先对齐官方模型卡中的结构定义。根据 FLUX 3 Image Klein 模型卡说明,官方标注的 5.6B 参数量仅指代图像 Transformer 主干(image transformer),文本编码器(text encoder)作为独立组件存在,提示词扩写模块同样独立加载。因此,任何显存预算、权重缓存目录与进程预热脚本都不能按单一 5.6B 裸权重体积来推算。

FLUX 3 Image Klein 官方模型卡中的组件与提示词扩写说明。

FLUX 3 Image Klein 官方模型卡中的组件与提示词扩写说明。

官方将 distilled 用于生成与图像编辑,默认采样 16 步、不使用 CFG,单次最多接受 10 张参考图。Base 则供微调与研究使用。以下示例沿用 distilled 的默认配置。

为什么必须保留提示词扩写(Prompt Upsampler)

在 black-forest-labs/flux-3-image-klein 官方 GitHub 仓库中,维护者针对提示词扩写组件给出了直接警告:切勿在没有该组件的情况下使用模型(“do not use the model without it”)。参考实现中的 CLI 脚本、交互式 Demo 以及 Python generate 接口全部默认启用 pup。

扩写器在图像采样前,将简短输入整理成更完整的场景描述。官方提醒,直接输入未经扩写的短句会得到较弱的结果。若显存不足,可先单独运行扩写器,再把得到的长描述传给图像模型。只有已经提供完整场景描述时,才使用 --no-pup 跳过内置扩写。

参考安装前提与官方调用示例

在准备运行环境时,官方文档列出的前提条件包括:使用已同意门控权重协议(gated weight terms)的 Hugging Face 账号获取权重、配备兼容的 CUDA GPU,以及按照参考安装说明准备 Python 3.12 环境。以下命令行与 Python 代码均为官方仓库 README 提供的文档示例,本文未执行本地安装、模型推理或付费 API 调用。

对于快速验证或脚本批处理,官方 README 给出的标准 CLI 文档示例如下:

python scripts/cli.py "A man walking with his dog, afternoon sun" --model distilled --out out.png --seed 7

这条命令显式指定了 --model distilled 并固定随机种子 --seed 7,同时没有附加 --no-pup,从而保证内置的提示词扩写正常介入。

在构建常驻 Python 服务或工作流节点时,应直接复用 flux3.generate 与 flux3.pipeline 中的组件加载方式。以下是官方 README 中的 Python 文档示例,展示了如何同时加载 distilled 主干与 pup 扩写器,并分别执行纯文本生成与带参考图的指令编辑:

from PIL import Image

from flux3.generate import Models, generate
from flux3.pipeline import WEIGHTS, dit_path

models = Models({"distilled": str(dit_path("distilled"))}, pup=str(WEIGHTS / "pup"), pup_memory=0.35)

image, record = generate(models, "distilled", "a red bicycle leaning on a white wall", images=[], seed=1)
image.save("bicycle.png")

image, record = generate(models, "distilled", "put a red bandana around the dog's neck",
                         images=[Image.open("examples/inputs/3.png")], seed=22)
image.save("bandana.png")

在初始化 Models 实例时,pup=str(WEIGHTS / “pup”) 明确挂载了扩写器权重路径,并通过 pup_memory=0.35 控制其内存分配比例。第一次调用 generate 时传入空列表 images=[] 执行文生图;第二次调用则在 images 列表中传入单张 PIL.Image 对象执行图像编辑(架构上限支持最多 10 张参考图),同时返回生成图像 image 与包含执行上下文的 record 对象。

坐标归一化约定与显存数据核对

如果业务管线涉及区域引导或空间框输入,需要严格核对坐标系的数学定义。FLUX 3 Image Klein 参考代码使用的边界框格式为归一化数组 [y_min, x_min, y_max, x_max],取值范围为 0..1,坐标原点位于图像左上角(top-left origin)。注意这里的维度顺序是 y 在前、x 在后。在维护多模型图像路由或将其他视觉管线的标注数据转换过来时,切勿将其与中心原点像素坐标,或者部分模型内部使用的 0..1000 整数提示词框混用。坐标表示的相关问题可参照多尺度 WebGL 坐标精度。同时需要向产品与设计方对齐的是,官方模型卡明确指出这些边界框仅用于引导布局(guide layout),并不会施加硬性的像素级遮罩(hard pixel masks),因此在封装接口时不应向调用方承诺像素级精确抠图或硬边界局部重绘。

在硬件资源规划方面,官方 README 报告了在 NVIDIA B200 GPU 上生成 1024×1024 图像时的峰值显存厂商测量值:在不开启扩写器(without upsampler)的条件下,distilled 模型在 BF16 精度下为 31GB,FP8 精度下为 26GB,NVFP4 精度下为 25GB。阅读这组官方数据时必须注意两个技术边界:首先,这是特定硬件(B200)上的厂商报告数据,并非所有 CUDA 显卡的通用最低显存门槛;其次,该表格记录的是不含 pup 扩写器的参考调用峰值占用。由于实际业务接入必须保留 pup(除非外部已提供完整扩写长文本),工程团队在设置容器显存上限或 GPU 调度配额时,还需为 pup 预留余量。这组数值不表示只有图像 Transformer 的占用,也不能直接当成其他显卡的最低显存要求。

许可证合规与集成自检步骤

在将代码合并到主干分支前,还需要确认开源许可边界。该项目的参考代码采用 Apache-2.0 许可证,但模型权重受 FLUX Kommunity License 约束。这意味着商业使用是附带条件的(conditional),不能在内部合规清单中将其简单标记为无限制商用许可,上线前需对照权重协议核实具体的商业授权条款。

完成代码对接后,建议按以下具体检查项逐一核验集成代码:

  • 检查模型初始化参数:确认 Models(…) 实例化代码中包含 pup=str(WEIGHTS / “pup”) 且未被注释,CLI 封装脚本中未在未经扩写的原始用户输入路径上硬编码 --no-pup。
  • 核对生成记录与输入列表:在测试环境中检查 generate 返回的 record 内容,确认实际送入主干网络的提示词已经过扩写展开;同时在接口层添加校验,限制 images 列表长度不超过 10 张,并确认封装使用的是 distilled 的默认采样配置。
  • 验证坐标转换单元测试:若接入了布局框引导,编写独立断言测试,验证所有传入框均满足 0 <= y_min < y_max <= 1 且 0 <= x_min < x_max <= 1,确保没有混入 [x, y, w, h] 或 0..1000 范围的旧版坐标数据。
← 返回列表