如何离线部署qwen-image-2-1-mflux-q4:hf download本地权重与--model参数实战

原创2026-11-09 21:15:181,714 阅读

如何离线部署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 只需两步:

  1. hf download mflux-community/qwen-image-2-1-mflux-q4 --local-dir ./qwen-image-2-1-mflux-q4 下载完整权重;
  2. 生成图片时用 --model ./qwen-image-2-1-mflux-q4 指向本地目录。

10.6GB 的体积 + 两步配置,就能让 Qwen-Image-2.1 文生图模型在你的 Mac 上稳定离线运行。更多细节可参考仓库内的 README.md。

登录后查看全文
qwen-image-2-1-mflux-q4