mflux-generate-qwen参数全清单:Qwen-Image-2512-4bit出图效果调优完全手册
mflux-generate-qwen参数全清单:Qwen-Image-2512-4bit出图效果调优完全手册
本文是一份面向 Apple Silicon 用户的出图调优完全手册:针对 MLX 量化版模型 Qwen-Image-2512-4bit,逐条梳理 mflux-generate-qwen 的全部参数,并给出 steps、guidance、分辨率、负向提示词等关键参数的调优建议,帮助你快速把出图效果调到满意。
一、Qwen-Image-2512-4bit 是什么?🧊
Qwen-Image-2512-4bit 是通义千问文生图模型 Qwen-Image-2512 的 MLX 框架 4-bit 量化版本,专为 Apple Silicon(M 系列芯片)优化,由 mflux 0.14.0 转换而来。相比原版约 58GB 的完整模型,4-bit 版仅需约 24GB 存储,大幅降低了本地部署门槛。
| 项目 | 说明 |
|---|---|
| 基础模型 | Qwen/Qwen-Image-2512(20B 参数文生图模型) |
| 量化精度 | 4-bit |
| 运行框架 | MLX(Apple Silicon 优化) |
| 模型体积 | 约 24GB |
| 许可证 | Apache 2.0 |
模型仓库由四大组件构成,这也是理解出图流程的关键:
| 目录 | 作用 | 文件示例 |
|---|---|---|
transformer/ |
扩散主干(MMDiT),决定生成质量 | transformer/model.safetensors.index.json |
text_encoder/ |
Qwen2.5-VL 7B 文本编码器,擅长中英文提示词理解 | text_encoder/model.safetensors.index.json |
vae/ |
潜空间解码器,负责把 latent 还原成像素图像 | vae/model.safetensors.index.json |
tokenizer/ |
分词器,把提示词转成 token | tokenizer/tokenizer.json |
💡 一个小知识:mflux 出于精度考虑会故意保留 text_encoder 为 bfloat16(约 14GB 显存占用),
--quantize并不会压缩它。
二、快速上手:三条命令跑出第一张图 🚀
第一步,安装 mflux:
pip install mflux
第二步,运行 mflux-generate-qwen,通过 --model 指向本仓库:
mflux-generate-qwen \
--model mlx-community/Qwen-Image-2512-4bit \
--prompt "A photorealistic cat wearing a tiny top hat" \
--steps 20
这条命令与仓库 README.md 中的 Quick Start 示例完全一致。输出默认为 image.png,可用 --output 改名。
如果希望把整个模型下载到本地,可执行:
git clone https://gitcode.com/hf_mirrors/mlx-community/Qwen-Image-2512-4bit
然后使用 --model <本地路径> --base-model qwen-image 加载(详见下文的 --base-model 说明)。
三、mflux-generate-qwen 参数全清单
以下按功能分组,覆盖该命令支持的全部参数。
1. 模型相关参数
| 参数 | 说明 |
|---|---|
--model / -m |
模型标识:内置名、HuggingFace 仓库 ID(如 mlx-community/Qwen-Image-2512-4bit)或本地路径 |
--base-model |
使用第三方仓库或本地路径时,必须显式声明其基于的内置模型(如 qwen-image) |
--quantize / -q |
运行时量化档位,可选 3 / 4 / 5 / 6 / 8。对已是 4-bit 的预量化仓库无需再传 |
2. 提示词与随机种子参数
| 参数 | 说明 |
|---|---|
--prompt |
正向提示词(与 --prompt-file 二选一) |
--prompt-file |
从文件读取提示词;多 seed 连跑时每个 seed 前会重新读取,方便边跑边改 |
--negative-prompt |
负向提示词,描述不希望出现的内容 |
--seed |
随机种子,可传多个(如 --seed 42 43),不传则用时间随机种子 |
--auto-seeds |
自动生成 N 个随机种子批量出图 |
--scheduler |
采样调度器,目前仅支持 linear |
3. 画质与尺寸参数(调优核心)
| 参数 | 说明 |
|---|---|
--width / --height |
输出宽高(像素),默认约 1024,也支持 2x 这类缩放因子;尺寸需为 16 的倍数 |
--steps |
推理步数。qwen-image 的默认值为 20 |
--guidance |
引导强度(CFG),qwen-image 默认 3.5 |
--image |
参考图(图生图),格式 --image photo.jpg 0.6,第二个数是强度 |
--image-strength |
参考图影响强度,0.0 表示无影响,默认 0.4 |
4. LoRA 参数
| 参数 | 说明 |
|---|---|
--lora |
添加 LoRA:--lora 路径 权重,可重复传多个,权重默认 1.0 |
--lora-paths / --lora-scales |
旧式写法(已标记弃用,推荐改用 --lora) |
--bake-lora |
是否把 LoRA 差值合并进基础权重,默认开启;--no-bake-lora 可关闭 |
--lora-style |
使用内置风格 LoRA(如 storyboard) |
5. 内存与性能参数
| 参数 | 说明 |
|---|---|
--low-ram |
低内存模式,牺牲部分性能换更低占用 |
--mlx-cache-limit-gb |
不启用完整低内存模式,仅限制 MLX 缓存大小(GB),如 8 或 16 |
--vae-tiling |
VAE 解码阶段分块,降低峰值显存 |
--vae-tile-size |
分块边长(默认 512,最小 128,需为 16 的倍数),越小越省内存 |
--battery-percentage-stop-limit / -B |
电池模式下降至该百分比(默认 5%)时停止生成,防止笔记本断电 |
6. 解码与输出参数
| 参数 | 说明 |
|---|---|
--output |
输出文件名,默认 image.png |
--make-conf / --metadata |
把本次全部生成参数写入 JSON 旁挂文件(<输出名>.metadata.json) |
--config-from-conf / -C |
从旁挂 JSON 恢复参数,命令行传入的参数会覆盖它 |
--no-exif / --no-metadata |
不在输出图片中嵌入生成元数据 |
--pid-decode |
改用 NVIDIA PiD 像素扩散超分解码器(首次需下载约 8GB 权重) |
--pid-degrade-sigma |
配合 --pid-decode 使用,故意注入 0.0–0.8 的噪声;出现"过度纹理"时可试 0.2 |
--stepwise-image-output-dir |
实验性功能:输出每一步的中间图,方便观察去噪过程 |
四、出图效果调优手册:6 个关键调参技巧
1. --steps 怎么选?20 起步,30 出细节
- 20 步:
qwen-image的官方默认值,速度与质量平衡点,日常出图够用; - 25~30 步:需要更干净的背景、更丰富的纹理时往上加;
- 超过 35 步:提升有限,速度代价明显,一般没必要。
2. --guidance 的"黄金区间"
- 默认 3.5 更严格地贴合提示词;
- 想要更自然、少"AI 味"的画面,可降到 2.5~3.0;
- 画面元素"不听话"时适当调高,但过高易导致过饱和、细节崩坏。
3. --width / --height:横图 1920×816 是官方推荐组合
mflux 官方示例(文生图、书法、街景)统一采用 --width 1920 --height 816 的横版构图,分辨率高且长宽比接近 21:9,适合风光、街景、产品图等场景;方图则用 1024×1024。
mflux-generate-qwen \
--model mlx-community/Qwen-Image-2512-4bit \
--prompt "Traditional Chinese street scene, red lanterns, bustling street life, photorealistic" \
--negative-prompt "blurry, low quality, distorted, watermark, cartoon, anime" \
--width 1920 --height 816 \
--steps 30 --seed 42
4. --negative-prompt 万能模板
官方示例中反复使用的负向提示词模板,可直接复用:
blurry, low quality, distorted, deformed, ugly, bad anatomy,
bad proportions, extra limbs, duplicate, watermark, signature,
text, letters, cartoon, anime, painting, 3d render, cgi
⚠️ 注意:如果你要生成含文字的画面(招牌、书法),请删掉模板里的
text, letters,否则会互相打架。
5. 种子陷阱:换 seed 不如换 prompt
Qwen 系列模型对 --seed 变化不敏感——不同种子产出的图往往大同小异。想要明显不同的构图或风格,请优先改动 --prompt 的描述;固定种子主要用于复现满意的结果。
6. 用 --make-conf + -C 一键复现完美参数
调参满意后加上 --make-conf,所有参数会保存到 JSON 旁挂文件;下次只需:
mflux-generate-qwen --model mlx-community/Qwen-Image-2512-4bit -C image.metadata.json
即可精确复现,需要微调时再在命令行覆盖个别参数。
五、量化档位怎么选?3bit 到 8bit 一览
mlx-community 提供了全系列量化版本,按显存/存储预算选择即可:
| 量化档位 | 体积 | 建议场景 |
|---|---|---|
| 8-bit | 约 34GB | 显存充足,追求最高还原度 |
| 6-bit | 约 29GB | 画质与体积平衡 |
| 4-bit(本仓库) | 约 24GB | 多数 M 系列机器的甜点档 |
| 5-bit | 约 27GB | 介于两者之间 |
| 3-bit | 约 22GB | 显存吃紧时的保底选择 |
📌 官方提示:Qwen 模型量化到 6-bit 及以下时,画质下滑会比 FLUX 系列更明显,显存允许的话优先选 8-bit;4-bit 是容量与画质的折中,3-bit 需谨慎。
六、常见问题 FAQ
Q1:显存不够,卡在 VAE 解码阶段怎么办?
依次尝试 --mlx-cache-limit-gb 16、--vae-tiling --vae-tile-size 256,最后才是 --low-ram。分块解码对画质基本无损。
Q2:生成的图偏"软"、不够锐利?
这是 Qwen 系列相比 FLUX 的已知特性。可尝试 --steps 30、适度提高 --guidance,或启用 --pid-decode 超分解码(注意首次需下载约 8GB 权重,其中 gemma-2-2b-it 为授权模型需先在 Hugging Face 接受协议)。
Q3:如何确认 4-bit 权重是否完整?
各分片的量化元数据都写在索引文件中,例如 transformer/model.safetensors.index.json 声明了 "quantization_level": "4" 与 mflux_version: 0.14.0,与 README.md 的 Model Details 相互印证。
Q4:--model 用本地路径时报错?
使用本地路径或第三方仓库时,必须同时传 --base-model qwen-image 告诉 mflux 该按哪套内置模型加载,否则会在加载权重前直接报错。
结语
掌握以上参数后,你就可以在 Apple Silicon 上高效玩转 Qwen-Image-2512-4bit 了:20 步起步、guidance 3.5、1920×816 横图、配一份负向提示词模板,再配合 -C 参数复现,基本能覆盖绝大多数出图需求。祝出图顺利!🎨