参数调优指南:flux-3-image-klein-pup-GGUF 官方采样参数(temperature、presence_penalty)逐一解析
参数调优指南:flux-3-image-klein-pup-GGUF 官方采样参数(temperature、presence_penalty)逐一解析
项目速览:它是什么,为什么值得调参
flux-3-image-klein-pup-GGUF 是 FLUX 3 Image Klein 的提示词增强器(Prompt Upsampler,简称 PUP)的 GGUF 量化版本。它基于 Qwen3.5-9B 微调而来,作用是把你输入的简短图像请求(例如"一个体操运动员做后空翻")扩写成一段 100~350 词的详尽英文描述,再交给 FLUX 3 Image Klein 出图——官方验证过,这样能显著减少姿势崩坏、手臂缠绕等解剖学问题。
这个项目由 Unsloth 量化打包,仓库内包含 5 个不同精度档位的模型文件、2 个视觉投影器(mmproj)以及官方的 system_prompts.json,配合 llama.cpp 即可在本地跑起来。🔧
核心结论先说:官方推荐值就是一组"贪心解码 + 高 presence_penalty"的组合,绝大多数场景直接照抄即可,不需要自己摸索。下文逐项解释每个参数为什么这么设。
官方采样参数一览:来自 ComfyUI 官方模板
README 中明确说明,以下参数取自官方 ComfyUI FLUX 3 Image Klein 模板(详见 README.md 的 "Usage with llama.cpp" 一节):
| 参数 | 官方值 | 作用一句话 |
|---|---|---|
temperature |
1.0 | 配合 top_k 生效的温度系数 |
top_k |
1 | 只取概率最高的 1 个 token,即贪心解码 |
top_p |
0.95 | 核采样阈值(贪心下基本不生效) |
min_p |
0.0 | 最小概率过滤,关闭 |
presence_penalty |
1.5(t2i)/ 0(i2i) | 惩罚已出现过的词,控制"啰嗦程度" |
repeat_penalty |
1.0 | 重复惩罚,1.0 即关闭 |
max_tokens |
3584 | 单次生成最多 3584 个 token |
enable_thinking |
false | 关闭 Qwen3.5 的思考模式 |
启动服务的最小命令
用 llama.cpp 拉起服务(文生图场景):
llama-server -m flux-3-image-klein-pup-UD-Q4_K_XL.gguf --mmproj mmproj-F16.gguf \
-ngl 99 -c 16384 --jinja
然后把 system_prompts.json 中对应的 system prompt 作为系统消息、你的短请求作为用户消息发送,并按上表设置采样参数。
temperature 解析:为什么"看起来随机"其实完全确定性
很多新手的第一反应是:temperature 是 1.0,那岂不是"最大随机"?
不是。 关键点在于 top_k: 1:每一步只允许概率排名第一的 token 被选中,temperature 在 top_k=1 下完全不起作用,整个过程就是贪心解码(greedy decoding)——同一段输入永远得到同一段描述,方便复现和排错。
- 如果你想要每次出图描述略有不同(配合不同构图探索),可以把
top_k调到 20~40 并保留temperature: 1.0,再视情况微调top_p。 - 但官方强调这套参数是"official"配置,不建议为了求稳而把 temperature 调低——低温度 + 高 top_k 的组合反而容易让扩写卡在套话上。
一句话:temperature 1.0 在这里只是占位,真正控制随机性的是 top_k。🎯
presence_penalty 解析:全篇最值得懂的参数
presence_penalty 会对"已经出现过的词"施加额外惩罚,数值越大,模型越倾向于换新词,避免反复说同一件事。
t2i(文生图):presence_penalty = 1.5
这是官方刻意设置的较高惩罚。原因很直观:提示词扩写器要产出一整段不重复的场景描述,如果它开始循环(例如反复写 "the background is blurry"),生成的图就会失衡。1.5 的强度能:
- 压制长描述中的词句复读;
- 让镜头语言、光影、人物细节逐句推进,而不是原地打转;
- 官方量化评测也验证过:各精度档位"循环频率不超过 BF16",说明这套解码参数本身就很抗复读。
i2i(图编辑):presence_penalty = 0
做图像编辑时必须归零。编辑任务的描述通常只有 50~150 词,且大量内容是对参考图中已有元素的指代("把那个杯子换成蓝色"),强行推新词会让模型偏离图里实际可见的内容。
| 场景 | system prompt | presence_penalty |
|---|---|---|
| 文生图 | t2i |
1.5 |
| 图像编辑 | i2i |
0 |
| 文生图 + 定位框 | t2i_bbox |
参照 t2i |
| 编辑 + 定位框 | i2i_bbox |
参照 i2i |
四种 system prompt 原文都在 system_prompts.json 中,来自 Black Forest Labs,未做改动。
其他参数与"思考模式":容易被忽略的两处
max_tokens: 3584
官方描述长度典型在 100~350 词,3584 是足够的安全上限。除非你用 t2i_bbox 输出"描述 + JSON 元素表"这类超长结构,否则没必要改小——改小会截断 JSON,导致 FLUX 3 Image Klein 解析失败。
enable_thinking: false
这是通过 chat_template_kwargs 传入的聊天模板参数,关闭 Qwen3.5 的"思考"输出。PUP 只该输出描述本身,思考内容会混进最终 caption,务必保持 false。启动命令里的 --jinja 参数就是为了让 llama.cpp 正确应用聊天模板,两者要搭配使用。
调参实操建议:从默认值出发的三条经验
- 先跑通官方值。UD-Q4_K_XL 档位约 7.5 GB 显存(含 mmproj),是官方默认档,也是 4-bit 文件中与 BF16 最接近的(KL 散度 0.0119)。
- 图编辑必须带 mmproj:编辑场景要传
--mmproj mmproj-F16.gguf(或 BF16 版)并把参考图放在用户消息文本之前,否则模型"看不见"图。 - 遇到问题再动一个参数:描述出现循环 → 确认 presence_penalty 是否为 1.5(t2i);编辑描述偏离原图 → 确认是否误用了 1.5 而非 0;输出混入思考文本 → 确认
enable_thinking与--jinja都设置正确。一次只改一个变量,否则很难归因。
文件清单与精度选择
| 文件 | 大小 | 说明 |
|---|---|---|
| flux-3-image-klein-pup-UD-Q4_K_XL.gguf | 6.0 GB | Unsloth Dynamic 4-bit + imatrix,4-bit 中最接近 BF16,默认推荐 |
| flux-3-image-klein-pup-Q4_K_M.gguf | 5.6 GB | 标准 4-bit,显存紧张时的选择 |
| flux-3-image-klein-pup-Q6_K.gguf | 7.4 GB | 6-bit,质量/体积折中 |
| flux-3-image-klein-pup-Q8_0.gguf | 9.5 GB | 8-bit,最接近 BF16 |
| flux-3-image-klein-pup-BF16.gguf | 17.9 GB | 未量化原版 |
| mmproj-F16.gguf / mmproj-BF16.gguf | 0.9 GB | 视觉投影器,图编辑必需 |
官方对比实验显示,用 Q4_K_M、Q8_0 与 BF16 生成的描述渲染后,在"后空翻、倒立、拉小提琴"等困难姿势上看不出解剖学差异——所以显存不够时放心选低档位,参数不用重调。
常见问题速查
问:改温度就能让描述更多样吗?
不能。先调 top_k(例如 30),temperature 保持 1.0 即可。
问:图编辑时描述总是重复画面内容? 检查两点:presence_penalty 是否为 0,mmproj 是否已加载。
问:需要联网下载吗? 本项目为 GGUF 权重仓库,若需完整模型文件可通过 git clone 获取仓库(LFS 权重随仓库拉取),配合 llama.cpp 本地运行,全程离线可用。
总结:temperature 1.0 + top_k 1 保证可复现,presence_penalty 1.5/0 的"双模式"是官方解码策略的灵魂所在。记住这张参数表,你的 FLUX 3 Image Klein 出图姿势崩坏率就会肉眼可见地下降。✅