Swift开发者必看:2行代码调用flux-3-image-klein-pup-8bit提示词增强器的Flux3PromptUpsampler速查
Swift开发者必看:2行代码调用flux-3-image-klein-pup-8bit提示词增强器的Flux3PromptUpsampler速查
flux-3-image-klein-pup-8bit 是 FLUX 3 Image Klein 官方提示词增强器(Prompt Upsampler)的 MLX 8-bit 量化版,专为 Apple Silicon 优化。Swift 开发者通过 Flux3PromptUpsampler 只需 2 行核心代码,就能把一句简短提示词自动扩展成细节丰富的场景描述,再交给 FLUX 3 出图模型,出图质量立刻上一个台阶。本文是它的速查手册:文件清单、下载方式、两行核心代码、四种模式与解码参数,一页读完。
什么是 flux-3-image-klein-pup-8bit?
一句话:它是 FLUX 3 出图模型的"提示词扩写器"。
- 底座是 Qwen3.5-9B 视觉-语言微调模型,能"看图 + 写字"
- 输入:一句短提示词(+ 最多 10 张参考图 + 可选边界框)
- 输出:一段 100–350 词的完整场景 caption,即出图模型真正接收的提示词
⚠️ 把短提示词直接丢给出图模型,画面往往很泛化;先经过它扩写一遍,主体、材质、光线、构图都会被具体化。
量化与体积速览(详见 config.json):
| 项目 | 说明 |
|---|---|
| 量化方式 | 8-bit affine,group size 64 |
| 模型体积 | 约 9.8 GB(2 个分片) |
| 运行平台 | Apple Silicon(MLX 框架) |
| 许可协议 | Apache-2.0(可免费商用) |
模型文件清单:仓库结构一览
| 文件 | 作用 |
|---|---|
| model-00001-of-00002.safetensors、model-00002-of-00002.safetensors | 模型权重(8-bit 量化,两个分片) |
| model.safetensors.index.json | 权重分片索引 |
| config.json | 模型架构与量化配置(Qwen3_5ForConditionalGeneration) |
| system_prompts.json | 四种模式的系统提示词(t2i / i2i / t2i_bbox / i2i_bbox) |
| chat_template.jinja | 对话模板 |
| tokenizer.json、tokenizer_config.json | 分词器(最长 262,144 token 上下文) |
| processor_config.json | 图像处理器配置(Qwen3VLProcessor) |
| generation_config.json | 生成配置(结束符等) |
| README.md | 官方说明:用法、一致性测试、各档位内存实测 |
如何下载 flux-3-image-klein-pup-8bit 模型?
最简单的方式是 clone 整个仓库,把目录当作模型目录传给 Swift 代码:
git clone https://gitcode.com/hf_mirrors/mlx-community/flux-3-image-klein-pup-8bit
📥 完整体积约 9.8 GB,建议放在 SSD 上;clone 后的仓库目录即可作为下文
snapshotURL指向的本地模型目录。
Flux3PromptUpsampler 两行代码速查:加载与调用
以下是最小调用方式(官方 README.md 示例):
import Flux3KleinUpsampler
let up = try await Flux3PromptUpsampler.load(directory: snapshotURL)
let caption = try await up.upsample("A man walking with his dog, afternoon sun")
- 第 1 行
load(directory:):从本地模型目录加载权重,snapshotURL指向 clone 下来的仓库目录 - 第 2 行
upsample(_:):传入短提示词,返回扩写后的完整 caption
caption 直接作为 FLUX 3 Image Klein 的提示词使用。无需手写 tokenizer、图像预处理或采样参数,封装已内置上游全部约定。
四种工作模式怎么选?
system_prompts.json 内置 4 套系统提示词,对应 4 种任务形态:
| 模式 | 场景 | 输出 |
|---|---|---|
t2i |
文生图 | 单段连续场景描述(100–350 词) |
i2i |
图像编辑(1–10 张参考图) | 单段编辑指令(50–150 词) |
t2i_bbox |
文生图 + 布局规划 | 场景描述 + 元素边界框 JSON 表格 |
i2i_bbox |
图像编辑 + 布局规划 | 编辑指令 + 源图/目标图边界框记录 |
选型建议:
- 只做文生图 →
t2i - 对一张图做局部修改 →
i2i - 需要精确控制元素位置(海报、表格、键盘等结构化排版)→
t2i_bbox或i2i_bbox,边界框采用 0–1000 归一化网格
关键解码参数速查表
| 参数 | 取值 | 说明 |
|---|---|---|
| 解码策略 | greedy | 贪心解码,输出稳定 |
| presence penalty | 文生图 1.5 / 编辑 0 | 只统计生成 token(与 vLLM 一致,不把 prompt 计入) |
| enable_thinking | False |
关闭思考模式,直接输出 caption |
| 最大新 token | 3,584 | 上限保护 |
| 参考图预处理 | 1 张→1MP;2 张→724²;3–10 张→512² | LANCZOS 缩放、边长为 32 的倍数、白底去透明、JPEG q92 往返 |
⚡️ 性能参考:M5 Max 上生成一条 caption 约需 9–15 秒。
量化档位与内存占用对比:8bit 值不值?
同一模型的三个档位实测(M5 Max,19 组官方样例,全部完整保留引号内原文与边界框表格):
| 档位 | 常驻内存 | 峰值内存 | 与 bf16 输出相似度 |
|---|---|---|---|
| bf16 | 18.8 GB | 20.2 GB | 1.00 |
| 8bit(本仓库) | 10.4 GB | 11.1 GB | 0.68 |
| 4bit | 6.0 GB | 6.8 GB | 0.45 |
8bit 是内存与质量的平衡点:比 bf16 省近一半显存,输出的结构、主体和引文保持一致,仅措辞上"改写"得更多一些;4bit 则进一步压缩到 6 GB 常驻,适合低配机器。
新手常见问题与避坑指南
- presence penalty 为什么关键? mlx-lm 的 presence penalty 会把 prompt 也计入,而正确行为(与 vLLM 一致)只统计生成 token。直接使用
Flux3PromptUpsampler封装即可避开这个坑。 - 贪心解码每次结果一样吗? 不完全一样。分数接近并列时贪心解码具有混沌性,上游官方两次运行同一请求的结果相似度也在 0.25–1.0 之间波动,所以"逐字一致"不是验收标准。
- 协议与许可? 本仓库为 Apache-2.0(与上游一致,源自 Qwen3.5-9B),可免费商用;但 FLUX 3 Klein 出图模型本身是 FLUX Kommunity License,两者协议不同,商用时请分别确认。
- 没有 Swift 环境怎么办? Python 侧可用 mlx-vlm 直接加载本仓库权重;
Flux3PromptUpsampler来自 Swift 封装项目 flux3-klein-swift,将其Flux3KleinUpsampler模块加入 SwiftPM 依赖即可使用。
小结
flux-3-image-klein-pup-8bit 用约 9.8 GB 的 8-bit 量化权重,把"短提示词 → 专业场景描述"压缩成 2 行 Swift 代码:Flux3PromptUpsampler.load 加载、upsample 出稿。记住三个关键数字——presence penalty 1.5、3,584 token 上限、参考图最多 10 张,再认准 t2i / i2i / t2i_bbox / i2i_bbox 四种模式,就能覆盖 90% 的使用场景。🚀