告别慢速下载:用 hf download 离线部署 qwen-image-edit-2511-mflux-q4 的完整教程
告别慢速下载:用 hf download 离线部署 qwen-image-edit-2511-mflux-q4 的完整教程
qwen-image-edit-2511-mflux-q4 是 Qwen-Image-Edit-2511 的 MFlux Q4 量化版本,专为 Apple Silicon 原生 MLX 运行而生。本教程教你用 hf download 命令一次性把约 29.0 GB 的模型权重拉取到本地,实现离线部署,彻底告别首次使用时反复慢速下载的烦恼。🚀
一、为什么选择 Q4 量化版?
MFlux-Community 把 Qwen-Image-Edit-2511 转换成了多个量化档位,覆盖从 BF16 到 Q3 的完整区间。各版本体积对比如下(详见 README.md):
| 量化档位 | 体积(GB) |
|---|---|
| BF16 | 56.6 |
| Q8 | 37.5 |
| Q6 | 32.4 |
| Q5 | 29.8 |
| Q4(本仓库) | 29.0 |
| Q3 | 24.7 |
Q4 是"质量与体积的黄金平衡点":
- ✅ 体积小:比 BF16 版省下近 28 GB 下载量,慢速网络也能从容拉取
- ✅ 质量高:4-bit MLX 仿射量化(affine quantization)覆盖 text encoder、transformer 和 VAE 三大组件
- ✅ 零配置:量化级别已写入权重元数据(见 transformer/model.safetensors.index.json 中的
quantization_level: "4"),运行时无需再传--quantize参数
💡 提示:本仓库由 MFlux-Community 于 2026-10-10 使用 MFlux 0.22.0 转换完成,继承原模型 apache-2.0 许可证。
二、本地模型仓库结构详解
用 hf download 拉取完成后,你会得到下面这套标准的 MFlux 模型目录。各子目录分工明确:
- 📁 text_encoder/:文本编码器权重,8 个
.safetensors分片 + 索引文件,负责把你的提示词编码为语义向量 - 📁 transformer/:核心扩散 Transformer 权重,7 个分片,是图像编辑的主力
- 📁 vae/:VAE 解码器,负责把潜空间噪声还原为像素
- 📁 tokenizer/:tokenizer.json 与 tokenizer_config.json,处理文本分词
- 📄 manifest.json:记录整个仓库内容的 SHA-256 校验值,可用于完整性验证
- 📄 README.md:模型卡,含量化对比表与用法说明
每个分片旁的 model.safetensors.index.json(如 vae/model.safetensors.index.json)记录了"权重名 → 分片文件"的映射关系,MFlux 正是靠它精准定位每一个张量。
三、最快配置方法:安装 MFlux 工具链
MFlux 是开源且免费的本地生成式图像运行框架,推荐用 uv 一行装好(README.md 官方用法):
uv tool install --upgrade mflux
装完后你会获得 mflux-generate-qwen-edit 等命令行工具。若没有 uv,可先执行 pip install uv 快速获得。
四、用 hf download 一键离线下载(核心步骤)
默认情况下,MFlux 会在首次使用时从远端仓库按需拉取权重——网络不稳时,这一步最容易卡住。正确的姿势是提前全量下载到本地:
hf download mflux-community/qwen-image-edit-2511-mflux-q4 --local-dir ./qwen-image-edit-2511-mflux-q4
命令要点速查:
| 参数 | 作用 |
|---|---|
mflux-community/qwen-image-edit-2511-mflux-q4 |
仓库完整路径 |
--local-dir |
指定本地落地目录,离线部署的关键 |
下载完成后,后续所有生成任务都指向本地目录,断网也能照常出图。建议下载结束后核对 manifest.json 中的 sha256,确认仓库完整性。
五、离线生成图片:一条命令出效果
下载完成后,把 --model 指向本地目录即可离线编辑图片:
mflux-generate-qwen-edit \
--model ./qwen-image-edit-2511-mflux-q4 \
--base-model qwen-image-edit \
--image-paths input.png \
--prompt "A puffin standing on a cliff" \
--width 1024 \
--height 1024 \
--seed 42 \
--output image.png
参数小贴士:
--image-paths:输入待编辑的图片,可传多张--prompt:描述期望的编辑效果(英文提示词效果更佳)--seed:固定随机种子,保证结果可复现--width/--height:输出分辨率,1024×1024 是推荐起点
六、常见问题速查
Q:离线运行时还需要联网吗?
不需要。只要 hf download 全量完成并指定 --model ./qwen-image-edit-2511-mflux-q4,整个编辑流程完全在本地完成。
Q:磁盘空间要预留多少? Q4 仓库约 29.0 GB,建议预留 35 GB 以上空间,给下载缓存和输出图片留出余量。
Q:可以换更小的 Q3 吗?
可以。Q3 版仅 24.7 GB,适合内存紧张的 Mac,思路完全相同,只需换成对应仓库路径执行 hf download。
写在最后
从"每次首次生成都要等半天下载"到"断网照常出图",核心只差一条 hf download 命令。现在就把 qwen-image-edit-2511-mflux-q4 拉到本地,让你的 Mac 变身一台随开随用的离线 AI 图像编辑工作站吧。✨