如何离线部署qwen-image-2-1-mflux-q4:hf download本地权重与--model参数实战
如何离线部署qwen-image-2-1-mflux-q4:hf download本地权重与--model参数实战
qwen-image-2-1-mflux-q4 是 Qwen-Image-2.1 文生图模型的 Q4 4-bit 量化版本(约 10.6GB),专为 Apple Silicon Mac 上的 MFlux 框架设计。本文将带你用 hf download 把模型权重完整下载到本地目录,再通过 --model 参数指向本地路径,实现完全离线的 AI 绘图——断网状态下也能稳定生成图片,不再依赖首次运行时的自动下载。
一、先认识 qwen-image-2-1-mflux-q4 🧩
这个仓库是社区对 Qwen-Image-2.1 做的 MLX 格式转换 + 4-bit 量化产物(由 MFlux-Community 转换,非官方发布)。量化等级直接保存在权重文件中,因此运行时不需要额外的 --quantize 参数。
MFlux 提供了同一模型的不同量化档位,可按内存预算选择:
| 量化档位 | 体积 | 特点 |
|---|---|---|
| BF16 | 33.1 GB | 精度最高,内存占用最大 |
| Q8 | 18.5 GB | 质量接近全精度 |
| Q6 | 14.5 GB | 质量/体积平衡 |
| Q5 | 12.6 GB | 较均衡的选择 |
| Q4(本仓库) | 10.6 GB | 体积小巧,适合 16GB 内存 Mac |
| Q3 | 8.7 GB | 最小体积,画质损失略大 |
💡 数字越小体积越小:Q4 比 BF16 全精度版本节省了约 2/3 的空间。
二、模型目录结构速览 📦
整个仓库就是 MFlux 加载所需的全部文件,结构清晰:
| 路径 | 作用 |
|---|---|
| model_index.json | 流水线入口,声明各组件类型(QwenImage21Pipeline) |
| transformer/ | 核心扩散模型(QwenImage21Transformer2DModel),权重分片存于 0.safetensors / 1.safetensors |
| text_encoder/ | Qwen3VL 文本编码器,负责理解 prompt |
| vae/ | VAE 图像编解码器,把潜变量还原成像素 |
| processor/ | 分词器与对话模板(chat_template.jinja、tokenizer.json) |
| scheduler/scheduler_config.json | 采样调度器配置(FlowMatchEulerDiscreteScheduler) |
| manifest.json | 权重完整性校验值(sha256) |
打开 transformer/model.safetensors.index.json 可以看到元数据中标注了 "quantization_level": "4" 和 mflux_version: 0.24.0,这也是运行时无需量化参数的原因。
三、第一步:用 hf download 下载本地权重 ⬇️
MFlux 默认在首次运行时自动从仓库拉取权重;若要离线部署,先用 hf download 命令把权重完整落到本地目录:
hf download mflux-community/qwen-image-2-1-mflux-q4 --local-dir ./qwen-image-2-1-mflux-q4
参数说明:
mflux-community/qwen-image-2-1-mflux-q4:模型仓库名--local-dir:指定本地保存目录,下载完成后该目录下会包含transformer/、text_encoder/、vae/等全部组件
✅ 下载完成后,检查目录下是否存在 model_index.json 和各分片 *.safetensors 文件,即可确认权重完整。
四、第二步:--model 参数指向本地目录 🎯
先安装 MFlux 框架:
uv tool install --upgrade mflux
对比一下两种用法——在线模式直接写仓库名,由框架自动下载:
mflux-generate-qwen-2.1 \
--model mflux-community/qwen-image-2-1-mflux-q4 \
--base-model qwen-image-2.1
离线模式只需把 --model 换成第三步的本地目录路径,其余命令完全不变:
mflux-generate-qwen-2.1 \
--model ./qwen-image-2-1-mflux-q4 \
--base-model qwen-image-2.1 \
--prompt "A puffin standing on a cliff" \
--width 1024 \
--height 1024 \
--seed 42 \
--output image.png
核心参数一览:
| 参数 | 作用 | 离线部署要点 |
|---|---|---|
--model |
模型位置 | 指向本地目录(如 ./qwen-image-2-1-mflux-q4)而非仓库名 |
--base-model |
基础模型类型 | 固定为 qwen-image-2.1 |
--prompt |
绘图提示词 | 支持中英文描述 |
--width / --height |
输出分辨率 | 推荐 1024 × 1024 |
--seed |
随机种子 | 固定种子可复现结果 |
--output |
输出文件路径 | 如 image.png |
运行成功后,当前目录会生成 image.png,此时即使断网也能反复出图。
五、常见问题排查 🛠️
1. 改了 --model 后仍然在线下载?
确认路径是本地目录(带 ./ 前缀的路径),而不是仓库名。框架会把 --model 值当作仓库名或本地路径两种情况处理,写成仓库名就会走在线下载逻辑。
2. 为什么不用加 --quantize 参数? 量化等级(Q4)已写入权重文件本身,框架加载时自动识别,见 transformer/model.safetensors.index.json 中的元数据。
3. 内存不够怎么办? Q4 版本已比全精度小约 2/3;若 16GB 内存 Mac 仍然吃紧,可换用 8.7GB 的 Q3 版本,思路完全相同。
4. 如何校验权重完整性? 仓库提供 manifest.json 记录整体 sha256,可用于核对下载是否完整。
六、总结 ✅
离线部署 qwen-image-2-1-mflux-q4 只需两步:
hf download mflux-community/qwen-image-2-1-mflux-q4 --local-dir ./qwen-image-2-1-mflux-q4下载完整权重;- 生成图片时用
--model ./qwen-image-2-1-mflux-q4指向本地目录。
10.6GB 的体积 + 两步配置,就能让 Qwen-Image-2.1 文生图模型在你的 Mac 上稳定离线运行。更多细节可参考仓库内的 README.md。