AB
AB
AiBoss站

全部分类

教程

Qwen Image 2.1 GGUF 本地部署教程：量化选择、文件组成与 sd-cli 出图

教程

Qwen Image 2.1 GGUF 本地部署教程：量化选择、文件组成与 sd-cli 出图

Qwen Image 2.1 的 GGUF 版本是社区把原始权重做量化转换后的文件，只能配合支持它的本地推理工具使用。本文说明量化档位怎么挑、扩散权重／文本编码器／VAE 三类文件各自的作用、sd-cli 的完整命令写法，以及文件大小与显存需求之间的区别等常见误区。

Qwen Image 2.1 的 GGUF 版本，是社区把原始权重做量化转换后得到的一组文件，用来在本地推理工具里加载并出图。它解决的是「显存和硬盘都不宽裕，但又想在本机跑图像生成」这个问题：量化把权重用更少的比特存下来，文件体积随之下降，代价是数值上出现误差。它适合已经有一台能跑本地扩散模型的机器、愿意自己管理模型文件的人；如果你只想点一下按钮就出图，托管服务会更省事。需要先明确一点：GGUF 仓库里放的不是 Qwen 重新训练的新模型，而是对原有权重的转换产物，因此它的能力边界仍然由原模型和运行时的支持情况共同决定。

准备工作

在下载任何文件之前，先把下面几件事确认清楚，能省掉大量返工。

硬件与存储

你需要一块支持本地扩散模型推理的 GPU，以及足够的硬盘空间来存放三类模型文件。文本编码器本身也是数 GB 级别的文件，加上扩散权重和 VAE，整体占用会明显超过单个量化文件的体积。此外还要预留出输出图片和临时文件的目录。

运行时

GGUF 权重不能凭空运行，必须有一个支持 Qwen Image 2.1 架构的推理运行时。命令行方式常用的是 stable-diffusion.cpp 提供的 sd-cli；图形界面方式则可以在 ComfyUI 里配合 GGUF 自定义节点使用。无论走哪条路，都要先确认运行时的版本已经支持这个模型架构，否则加载阶段就会失败。

三类必需文件

这是最容易踩坑的地方：只下载一个扩散模型 GGUF 是跑不起来的。完整的推理链路需要三部分协同工作。

  • 扩散模型权重：例如 qwen_image_2.1-Q4_K.gguf，负责把提示词对应的图像表示逐步去噪生成出来。
  • 文本编码器：把提示词转换成模型能接受的输入。维护者给出的示例使用 Qwen3VL-8B-Instruct-Q4_K_M.gguf。
  • VAE：把图像表示还原成像素。对应文件是 qwen_image_2.1_vae_bf16.safetensors。

如果打算用 GGUF 文本编码器做图像编辑，还需要额外准备视觉投影文件，例如 mmproj-Qwen3VL-8B-Instruct-F16.gguf。另外要特别注意 VAE 的版本：早期 Qwen Image 或 Wan 2.2 的 VAE 与 Qwen Image 2.1 不兼容，不能互相替换。

许可证

量化不会改变授权条款。转换后的文件仍然遵循原模型的许可证。Qwen Research License 限定为非商用用途，商用需要另行取得授权。具体条款请以官方当前公布的信息为准，不要凭「反正是社区版」就默认可以商用。

操作步骤

第一步：选择量化档位

仓库里通常提供多个量化文件，下载体积可以作为存储占用的参考，但它不等于所需的显存大小。常见的档位大致如下：

量化文件大小选择参考
Q2_K2.56 GB存储非常紧张时
Q3_K3.27 GB想保持小体积，同时多保留一些细节
Q4_0 / Q4_K4.20 GB多数本地环境比较好上手的平衡点
Q5_05.07 GB愿意多花内存换取细节
Q6_K6.00 GB资源宽裕、更看重画质
Q8_07.69 GB体积最大，精度更高的选项

一般来说，比特数越高的权重越能保留数值细节，占用的存储也越多。但最终画面受到提示词、分辨率、运行时实现和硬件等多重因素影响，不存在对任何图片都成立的「最佳档位」。务实的做法是：先按存储空间挑一个能放下的档位，再在目标分辨率下实测速度和内存占用，不合适就换档。

第二步：下载并整理文件

把扩散权重、文本编码器、VAE 分别放到不同的目录，例如 models/diffusion_models/、models/text_encoders/、models/vae/。分开存放的好处是命令行参数清晰，后续换量化档位时只需要替换其中一个路径。文件名请保持原样，不要为了好看而重命名，否则排查问题时很难对照仓库说明。

第三步：用 sd-cli 生成第一张图

下面这条命令把扩散模型、文本编码器和 VAE 一起交给 sd-cli。路径需要按你自己的存放位置调整。

sd-cli \
  --diffusion-model ../models/diffusion_models/qwen_image_2.1-Q4_K.gguf \
  --vae ../models/vae/qwen_image_2.1_vae_bf16.safetensors \
  --llm ../models/text_encoders/Qwen3VL-8B-Instruct-Q4_K_M.gguf \
  -p "A small mountain observatory after fresh snowfall, warm window light, quiet winter dusk" \
  --cfg-scale 6.0 \
  --sampling-method euler \
  --offload-to-cpu \
  -o qwen-image-2.1.png

参数的含义可以这样理解：--diffusion-model 指向扩散模型 GGUF，--llm 指向文本编码器，--vae 指向 VAE。-p 是提示词，--cfg-scale 控制提示词约束强度，--sampling-method 指定采样器，-o 是输出文件名。

如果显存不够，--offload-to-cpu 往往能救场，它把一部分计算挪到 CPU 上，代价是生成速度变慢。是否开启、开启后慢多少，取决于你的硬件组合，需要自己试。

第四步：调整分辨率

维护者的指南要求把图片的宽和高都设为 32 的倍数。这一点在写参数时容易被忽略，但不符合要求时可能直接报错或产出异常结果。分辨率提高会同时增加显存占用和生成时间，建议先用较小尺寸确认整条链路通畅，再逐步往上加。

第五步：在 ComfyUI 中使用（可选）

如果更习惯图形界面，GGUF 仓库里通常附带了文生图的工作流文件，配合 leejet/ComfyUI-GGUF 自定义节点使用。安装节点前请先阅读节点自身的说明文档，确认它与当前使用的 ComfyUI 版本兼容。节点与主程序版本不匹配是这类工作流报错的常见原因。

一个完整示例

把上面的步骤串起来，从零到出图的流程大致是这样：

  1. 确认运行时已经支持 Qwen Image 2.1 架构，并准备好存放模型的目录结构。
  2. 根据可用存储空间选定量化档位。若硬盘和显存都一般，从 Q4_K 这类中间档位起步比较稳妥。
  3. 下载三个文件：扩散权重 qwen_image_2.1-Q4_K.gguf、文本编码器 Qwen3VL-8B-Instruct-Q4_K_M.gguf、VAE qwen_image_2.1_vae_bf16.safetensors。若要做图像编辑，再补一个 mmproj-Qwen3VL-8B-Instruct-F16.gguf。
  4. 按前面的目录规划放好文件，核对 VAE 确实是 Qwen Image 2.1 对应的版本。
  5. 用一条 sd-cli 命令把三者串起来，提示词先用一句简单的描述，宽高设为 32 的倍数。
  6. 观察是否正常出图。若显存不足，加上 --offload-to-cpu 重试。
  7. 出图成功后，再逐步调整分辨率、采样器和 cfg 值，观察画质与耗时的变化。
  8. 如果打算商用，回到许可证条款确认授权范围，必要时联系权利方取得许可。

这个流程的价值在于每一步都可单独验证：文件是否齐全、路径是否正确、运行时是否支持、显存是否够用。出问题时按这个顺序排查，比盲目换参数有效得多。

注意事项

只下载扩散 GGUF 是不够的。 文本编码器、VAE 和对应的运行时缺一不可。这是新手最常见的误解，表现为加载时报缺少组件或直接崩溃。

不要混用相似名字的 VAE。 必须使用指南中列出的 Qwen Image 2.1 专用 VAE。早期 Qwen Image 或 Wan 2.2 的 VAE 无法替代，名字相近不代表可以互换。

文件大小不等于显存需求。 下载体积反映的是存储占用。推理过程中，文本编码器、VAE、中间图像以及运行时的工作区都会占用内存，分辨率越高占用越大。用「4.20 GB 的文件所以只要 4.20 GB 显存」来估算，几乎一定会失望。

量化不改变许可证。 转换文件依旧遵循原模型授权。Qwen Research License 仅限非商用，商用需要单独授权。相关条款可能更新，请以官方当前信息为准。

转换后的功能取决于运行时。 原模型支持文生图、图像编辑和透明 RGBA 输出，但转换后的权重在具体运行时里能用哪些功能，要看该运行时的实现进度，不能默认全部可用。

文件名与兼容性会变动。 仓库中的文件命名和运行时支持情况都可能更新，动手前先核对最新的仓库说明与运行指南，避免照着过期的文件名下载。价格、配额、版本号等易变信息同样以官方页面为准。

返回