参考图预处理藏着哪些细节?flux-3-image-klein-pup-8bit的Alpha合白、LANCZOS缩放与JPEG q92完整流程
参考图预处理藏着哪些细节?flux-3-image-klein-pup-8bit的Alpha合白、LANCZOS缩放与JPEG q92完整流程
flux-3-image-klein-pup-8bit 是 FLUX 3 Image Klein 的"提示词增强器"(prompt upsampler)的 MLX 8-bit 量化版:它读取你的短提示 + 最多 10 张参考图,输出一段完整的场景描述,再交给图像生成模型。很多人只关心模型本身,却忽略了参考图预处理这一步——Alpha 合白、LANCZOS 缩放、JPEG q92 往返,每个细节都直接影响编辑结果的一致性。
🧩 先搞懂:这个项目是做什么的
这个项目并不是出图的扩散模型,而是出图前的"文案策划"。README.md 中的说明很直白:
- 它是 Qwen3.5-9B 视觉-语言基座的微调版,架构为
Qwen3_5ForConditionalGeneration(见 config.json) - 作用:把短请求 + 参考图(+ 可选 bounding box)扩写成 FLUX 3 Klein 需要的完整 scene caption
- 8-bit 量化(affine、group size 64),体积约 9.8 GB,比 bf16 版省一半以上显存
没有它,直接把短提示丢给图像模型,出图会很"泛";有了它,提示词会被规划成具体、自洽的画面描述。
📥 为什么参考图预处理这么关键
在 i2i(图像编辑)场景下,upsampler 会"看到"你按顺序附上的所有参考图,再写出一段与这些图配套的编辑指令。也就是说:模型看到的不是你的原图,而是经过预处理流水线加工后的图。
如果你本地预处理的方式和训练时不一致——比如透明 PNG 直接黑底填充、用双线性缩放、或者喂了无损 PNG——描述质量和编辑指令的准确度都会悄悄下降。README 中专门用一句话总结了这条流水线:
alpha over white, LANCZOS to 1 MP for one reference, 724² for two, 512² for 3–10, sides multiples of 32, then a JPEG q92 round trip.
下面逐步拆解。
🎨 步骤一:Alpha 合白(Alpha over White)
处理带透明通道的图片时,先把 alpha 通道"混合"到纯白背景上。
- 常见错误做法:透明区域直接填黑,或者丢弃 alpha 通道留下杂色——透明 PNG 的预览底和实际像素值并不一样
- 正确做法:
color = alpha × pixel + (1 - alpha) × white,得到一张不透明的 RGB 图
为什么要合"白"而不是别的颜色?这大概率对应训练数据的制备方式:素材里的透明图统一压在白底上,推理时保持一致,视觉编码器看到的分布才和训练时相同。
📐 步骤二:LANCZOS 缩放到目标尺寸
缩放不是"随便压小",README 给出了精确的尺寸规则:
| 参考图数量 | 目标尺寸 |
|---|---|
| 1 张 | 缩放到约 1 MP |
| 2 张 | 每张 724 × 724 |
| 3–10 张 | 每张 512 × 512 |
| 通用约束 | 边长必须是 32 的倍数 |
两个细节值得注意:
- 图越多,单张分辨率越低。1 张图时给到 1 MP 保留最多细节,10 张图时每张只给 512²,保证总 token 数可控。
- 32 的倍数不是玄学。对照 preprocessor_config.json:视觉编码器
patch_size为 16,merge_size为 2,即每 16×2=32 像素合并成一个视觉 token。边长对齐到 32,才能完整铺满 patch,不产生裁切或填充。
缩放算法指定为 LANCZOS——在 preprocessor_config.json 和 processor_config.json 中对应 "resample": 3(PIL 枚举里 3 即 Resampling.LANCZOS)。相比双线性,LANCZOS 在缩小图片时能保留更锐利的边缘和文字细节,对"图内文字逐字转写"这类任务很重要。
🖼️ 步骤三:JPEG q92 往返
缩放完成后,把图存成 quality=92 的 JPEG,再读回来当输入。
这一步乍看多余——q92 已经很高了,损失肉眼几乎不可见。但它的作用是对齐训练时的数据管道:训练用的参考图几乎可以肯定都是 JPEG 压缩过的(这也是网络图片的常态)。做同样的压缩往返,就是在模拟"模型训练时看到过的图像质感",包括轻微的色带、边缘柔化等压缩特征。
三步连起来就是一条完整的流水线:
原图(PNG/JPEG/WebP)
→ Alpha over White 合成到白底
→ LANCZOS 缩放(1MP / 724² / 512²,边长对齐 32)
→ JPEG q92 压缩往返
→ 送入视觉编码器
⚙️ 与视觉编码器的参数对应
预处理之后的图,交给 Qwen 系视觉编码器处理。几个关键参数可以对照 preprocessor_config.json:
"image_processor_type": "Qwen2VLImageProcessor",并做do_convert_rgb、do_rescale、do_normalize"image_mean": [0.5, 0.5, 0.5]、"image_std": [0.5, 0.5, 0.5]:归一化到 [-1, 1] 区间"patch_size": 16+"merge_size": 2:32 像素对齐的根源(见 config.json 的vision_config,spatial_merge_size同为 2)"shortest_edge": 65536、"longest_edge": 16777216:像素总数上下限,保证参考图缩放后仍满足范围
🔤 系统提示词与解码设置
upsampler 的行为由 system_prompts.json 中四套系统提示词驱动,覆盖全部任务形态:
| 键 | 场景 |
|---|---|
t2i |
纯文生图,扩写为 100–350 词的场景描述 |
i2i |
图像编辑,输出 50–150 词的编辑指令 |
t2i_bbox |
文生图 + 元素 bbox 表格 |
i2i_bbox |
图像编辑 + bbox 标注记录 |
解码侧同样有讲究(README "Two details matter" 部分):
- 贪心解码;
t2i使用 presence penalty 1.5,编辑类任务为 0 enable_thinking=False,最多生成 3,584 个新 token- presence penalty 只统计新生成的 token(与 vLLM 行为一致),这是移植时特意对齐的细节
对话侧的消息组装规则见 chat_template.jinja,分词配置见 tokenizer_config.json 与 tokenizer.json。
📊 8-bit 量化下效果损失有多大?
README 的 Tiers 表格(19 条 BFL 官方样例测试,M5 Max 实测):
| 档位 | 引文保留 | bbox 表 | 与 bf16 相似度 | 常驻显存 |
|---|---|---|---|---|
| bf16 | 20/20 | 2/2 | 1.00 | 18.8 GB |
| 8bit | 20/20 | 2/2 | 0.68 | 10.4 GB |
| 4bit | 20/20 | 2/2 | 0.45 | 6.0 GB |
8-bit 版是甜点档:引号和 bbox 表格 100% 保留,措辞比 bf16 更"意译"一些,但结构、主体、关键文本完整;每条 caption 在 M5 Max 上约 9–15 秒。权重分片为 model-00001-of-00002.safetensors 和 model-00002-of-00002.safetensors,索引见 model.safetensors.index.json。
✅ 实操清单
给参考图喂进 flux-3-image-klein-pup-8bit 之前,逐条检查:
- ☑️ 透明 PNG?→ 先 Alpha 合成到白底
- ☑️ 尺寸?→ 1 张约 1 MP / 2 张 724² / 3–10 张 512²
- ☑️ 边长?→ 必须是 32 的倍数
- ☑️ 缩放算法?→ LANCZOS(
resample=3) - ☑️ 最后一步?→ JPEG quality=92 压缩往返
- ☑️ 参考图顺序有意义:
i2i提示词按"第一张、第二张……"引用图片,附件顺序要稳定
预处理这一环不显眼,却决定了 upsampler "看到"的世界和训练时是否一致。把这三步做对,8-bit 模型就能稳定产出 20/20 引文保留的高质量 caption。