Swift开发者必看:2行代码调用flux-3-image-klein-pup-8bit提示词增强器的Flux3PromptUpsampler速查

原创2026-10-19 10:50:481,441 阅读
文章标签:人工智能大模型多模态媒体生成提示工程

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 常驻,适合低配机器。

新手常见问题与避坑指南

  1. presence penalty 为什么关键? mlx-lm 的 presence penalty 会把 prompt 也计入,而正确行为(与 vLLM 一致)只统计生成 token。直接使用 Flux3PromptUpsampler 封装即可避开这个坑。
  2. 贪心解码每次结果一样吗? 不完全一样。分数接近并列时贪心解码具有混沌性,上游官方两次运行同一请求的结果相似度也在 0.25–1.0 之间波动,所以"逐字一致"不是验收标准。
  3. 协议与许可? 本仓库为 Apache-2.0(与上游一致,源自 Qwen3.5-9B),可免费商用;但 FLUX 3 Klein 出图模型本身是 FLUX Kommunity License,两者协议不同,商用时请分别确认。
  4. 没有 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% 的使用场景。🚀

登录后查看全文
flux-3-image-klein-pup-8bit