本地运行的 Qwen-Image-Edit：ComfyUI 与 VRAM 必需

#为什么是 Qwen-Image-Edit，以及该系列包含什么

Qwen-Image 系列涵盖两种用途。Qwen-Image 根据文本生成图像，其技术报告公认的优势之一是图像中的文字渲染，包括完整句子和非拉丁字母。Qwen-Image-Edit 基于同一模型修改现有图像。GitHub 仓库 QwenLM/Qwen-Image 和 Hugging Face 模型卡片 Qwen/Qwen-Image-Edit 区分了两类编辑：语义编辑，即在保持主体身份的同时改变内容或风格；外观编辑，即添加、删除或替换某个元素而不影响其他部分。该模型还可以在保留字体和版式的情况下，校正或替换图像中的文字。

在下载任何内容之前，需要记住的两个事实是架构和许可证。该扩散模型是一种多模态变换器（MMDiT），约有 200 亿个参数。文本编码器并不是小型 CLIP，而是 Qwen2.5-VL 7B，这是一款完整的视觉语言模型，能够同时读取你的指令和输入图像。两者均以 Apache 2.0 许可证发布，允许将这些权重用于商业用途。每个组件都需要单独下载，而正是分散在三个文件中的这种结构，导致了下文所述的大多数节点错误。

这一系列发展很快。Qwen-Image-Edit 的第一个版本于 2025 年 8 月发布。标记为 2509 的版本于 2025 年 9 月推出：它接受多张输入图像，并原生支持 ControlNet 类型的条件，例如深度图、轮廓或姿态。2511 版本于 2025 年底推出，主题一致性更好；生成模型本身则获得了 2512 修订版。2026 年又宣布了 2.x 版本。本指南依据 ComfyUI 逐步记录的这一系列版本，从 2025 年 8 月的版本到 2511 版本：其中的节点和文件组织方式相同。在做出选择前，请阅读 GitHub README 的开头，其中列出了各版本及其发布日期。

#原生、FP8 还是 GGUF：该下载哪个版本的 Qwen-Image-Edit

同一个模型有三种形式在流通，而它们的使用方式并不相同。

原生（bf16，Diffusers 格式）

Hugging Face 上的 Qwen/Qwen-Image-Edit 仓库被拆分为多个 safetensors 文件，供 Python 的 Diffusers 库使用。在 bf16 下，200 亿参数仅变换器就约占 40 GB，此外还要加上文本编码器。这条路线适合 Python 脚本和 48 GB 或更大显存的显卡，或者将部分计算转移到 RAM。不适合 ComfyUI。

由 Comfy Org 重新打包的 FP8

Hugging Face 上的 Comfy-Org/Qwen-Image-Edit 仓库以单个 FP8 文件（e4m3fn 格式）提供权重，文本编码器和 VAE 则拆分在子目录中。这是 ComfyUI 官方工作流使用的版本。扩散模型文件略大于 20 GB。同一仓库中还提供约 41 GB 的 bf16 变体，适用于有足够空间的显卡。

社区 GGUF

由 city96、QuantStack 或 Unsloth 等贡献者发布的 GGUF 格式转换文件；GGUF 是量化 LLM 使用的格式。它们支持降至 Q8_0、Q6_K、Q5_K_M、Q4_K_M、Q3_K_M 或 Q2_K，并要求安装 ComfyUI-GGUF 扩展。在显存低于 16 GB 的情况下，这是最现实的选择；在 Mac 上使用也最舒适。

选择规则很简单。24 GB 显卡：直接使用官方 FP8，无需多想。16 GB 显卡：借助 ComfyUI 的内存转移功能，FP8 可以运行，但 GGUF Q6_K 或 Q5_K_M 可避免速度变慢。12 GB 显卡：使用 GGUF Q4_K_M 或更低量化。Mac Apple Silicon：使用 GGUF，因为 ComfyUI 在 Metal 上不会以 FP8 计算，并会在加载时对这些权重进行反量化，从而使占用的内存翻倍。

#所需 VRAM：在哪里查看数字以及如何解读

无论是 GitHub README 还是 Qwen 的 Hugging Face 页面，都没有提供“某张卡需要多少显存”的对照表。对于这个模型，ComfyUI 文档也没有：其教程会列出要下载的文件、目标文件夹和工作流，有时还会给出其自身测试所使用的硬件和耗时；这些只能作为参考，不能视为承诺。可靠、带日期且可验证的数据，是 Hugging Face 页面上显示的每个文件的大小。其他一切都由此推导。

扩散模型

FP8 约 20 GB（Comfy-Org 仓库中的 qwen_image_edit_fp8_e4m3fn.safetensors 文件，于 2025 年 8 月发布），bf16 约 41 GB。在 GGUF 中，权重大小的计算方式是：200 亿个参数乘以每个参数的比特数，再除以八。8.5 比特的 Q8_0 约为 21 GB，4.5 至 5 比特的 Q4_K_M 约为 12 GB，Q3_K_M 约为 9 至 10 GB，Q2_K 约为 7 GB。每个 GGUF 仓库的页面都会显示每个文件的确切数值。

文本编码器

Comfy-Org 仓库中的 qwen_2.5_vl_7b_fp8_scaled.safetensors 文件约为 9.4 GB。去噪期间它无需一直留在 VRAM 中：ComfyUI 会将其加载到 VRAM 中以编码提示词和图像，空间不足时再将其卸载。因此，20 GB 的模型和 9 GB 的编码器可以在 24 GB 显卡上运行。

VAE

qwen_image_vae.safetensors 文件约为 250 MB。它占用的内存可以忽略不计，但不可或缺，而且专属于这一模型系列：Flux 或 SDXL 的 VAE 会产生彩色噪声。

激活项

计算本身除了权重之外还需要额外空间，而且在高分辨率下需要更多空间。官方工作流会将输入图像缩小到约一百万像素，从而限制这部分开销。将输出分辨率提高一倍，这部分余量也会增大。

ComfyUI 默认启用动态 VRAM 管理，我们的安装指南对此有说明：当权重超过显卡容量时，一部分权重会保留在 RAM 中，并按需传输。这样，模型可以在 12 或 16 GB 的显卡上运行，但两者之间的每次传输都会耗费时间，系统 RAM 也会成为真正的上限：对于 20 GB 的模型和 9 GB 的编码器，32 GB RAM 是最低要求，64 GB 则更舒适。下面的参考表总结了这一逻辑，但不代表实际测量结果。

24 GB 及以上（RTX 3090、4090、5090）

完整的官方 FP8、FP8 编码器，以及无需卸载的单百万像素输出图像。41 GB 的 bf16 仍仅适用于 48 GB 的专业显卡。

16 GB（RTX 4080、5080、4060 Ti 16 GB）

带卸载的 FP8，或采用 GGUF Q6_K 至 Q5_K_M，并在各步骤之间卸载编码器，以便容纳在显卡中。

12 GB（RTX 3060 12 GB、4070、5070、5070 Ti）

GGUF Q4_K_M 或 Q3_K_M，加载后再卸载 FP8 编码器，32 GB RAM。生成时间会明显长于使用 SDXL 时。

8 GB

使用 Q2_K 或 Q3 并进行大量卸载是可行的，但代价是速度和质量下降。仅适合偶尔编辑。

搭载 Apple Silicon 的 Mac

统一内存充当 VRAM。一个 12 GB 的 GGUF Q4_K_M 加上 9 GB 的编码器，需要一台配备 32 GB 内存的 Mac；要想工作时不捉襟见肘，则需要 48 GB 及以上。

#先决条件

ComfyUI 已更新

Qwen-Image 专属的节点（如 TextEncodeQwenImageEdit）于 2025 年 8 月加入 ComfyUI，2509 版本的节点则于 2025 年 9 月加入。较旧的安装会忽略这些节点并显示红色节点。请先完成更新：Desktop 会自动更新，便携版归档通过 update 脚本更新，手动安装则执行 git pull。

至少一张 12 GB 的NVIDIA显卡，或一台 32 GB 的 Mac

低于这一配置时仍然可以进行编辑，但会变成一场耐心考验。AMD 可在 Linux 上通过 ROCm 运行，自 2026 年 1 月起也可在 Windows 上通过 Desktop 应用运行。

磁盘空间

FP8：模型、编码器和 VAE 三者合计占用略多于 30 GB。每尝试一种 GGUF 变体，还要额外增加 10 至 21 GB。

已经可以正常运行的 ComfyUI 安装

使用 SDXL 或 Flux 生成的第一张图像。如果还没有生成，请先按照安装指南操作：本指南从 ComfyUI 在 http://127.0.0.1:8188 上打开时开始。

#步骤 1 和 2：下载正确的文件并将其归位

最短路径是使用 ComfyUI 内置的工作流模型库：打开 Workflow 菜单，选择浏览模型，再选择 Image 类别，然后选择 Qwen-Image-Edit 模型，或根据你感兴趣的版本选择其 2509 或 2511 变体。ComfyUI 会检测缺失的文件，并建议将其直接下载到正确的文件夹。如果你更愿意手动下载，例如为了自行控制所选变体，下面是预期的目录结构，具体记录在 docs.comfy.org 的 Qwen-Image-Edit 教程中。

ComfyUI/
└── models/
    ├── diffusion_models/
    │   └── qwen_image_edit_fp8_e4m3fn.safetensors        # ou qwen_image_edit_2509_fp8_e4m3fn.safetensors
    ├── text_encoders/
    │   └── qwen_2.5_vl_7b_fp8_scaled.safetensors
    ├── vae/
    │   └── qwen_image_vae.safetensors
    └── loras/
        └── Qwen-Image-Lightning-4steps-V1.0.safetensors    # facultatif, accélère

1. 01
   下载扩散模型

   在 Hugging Face 上，打开仓库 Comfy-Org/Qwen-Image-Edit_ComfyUI 的 split_files/diffusion_models 目录。选择与所需版本对应的 FP8 文件。点击前先检查页面显示的大小，然后与收到的文件进行比较：中断的下载会生成截断文件，并在加载时产生难以辨认的错误。
2. 02
   下载文本编码器和 VAE

   同一个仓库，目录为 split_files/text_encoders 和 split_files/vae。该编码器由 Qwen-Image 以及 Qwen-Image-Edit 的所有版本共用：即使安装多个模型版本，也只需一份。VAE 同理。
3. 03
   将每个文件放入其子目录

   模型放入 diffusion_models，编码器放入 text_encoders，VAE 放入 vae。使用 ComfyUI Desktop 时，models 目录位于安装时选择的位置，该位置可在应用设置中查看。将文件放入 checkpoints 而不是 diffusion_models，不会在加载节点中显示。
4. 04
   可选：Lightning LoRA

   仓库 lightx2v/Qwen-Image-Lightning 发布了 LoRA，可将生成步骤从 20 步减少到 4 或 8 步，适用于 Qwen-Image 和 Qwen-Image-Edit。文件放在 models/loras 中。编辑模型的后续版本拥有各自的 Lightning LoRA：请选择名称中包含你所用版本的那个。
5. 05
   刷新 ComfyUI

   复制文件后，点击界面的刷新按钮，或重新加载页面。加载节点会在此时重新读取目录，而不是持续读取。

#步骤 3：加载编辑工作流并理解其中的节点

从库中打开 Qwen-Image-Edit 工作流模板。如果你是手动下载文件的，ComfyUI 可能会建议重新下载它们：请拒绝，然后在加载节点中选择你的文件。该图包含大约十个节点，每个节点都有明确的作用。

加载扩散模型

从 models/diffusion_models 加载文件。下拉菜单应显示您的 Qwen-Image-Edit 文件；如果为空，说明文件放置错误，或界面尚未刷新。

Load CLIP, type qwen_image

从 models/text_encoders 加载 Qwen2.5-VL 编码器。type 字段必须设为 qwen_image。使用其他类型时，编码器虽能无错误加载，但 prompt 会被错误解释，结果也会完全不对。

Load VAE

Qwen-Image VAE。没有其他内容。

Load Image，然后 Scale Image to Total Pixels

要修改的图像，调整至约一百万像素。此调整并非可选项：模型就是在这一尺度上训练的，尺寸大得多的输入会降低一致性，同时增加 VRAM 占用。

TextEncodeQwenImageEdit

该系列专用的节点。它接收编码器、VAE、图像和您的提示词，并生成条件信息。共有两个：一个用于正向提示词，另一个用于负向提示词。2509 版及后续版本中的节点名为 TextEncodeQwenImageEditPlus，最多接受三张图像。

ModelSamplingAuraFlow 和 CFGNorm

两个用于调整去噪的节点已在官方工作流中预先设置，其中一个偏移（shift）约为 3。不要移除它们：没有它们，生成的图像会褪色或过度饱和。

KSampler、VAE Decode、Save Image

去噪、解码和保存，与任何 ComfyUI 工作流一样。图像会输出到 output 文件夹，并将完整工作流写入 PNG。

请将提示词写成指令，而不是最终图像的描述：「replace the text on the sign with OUVERT, keep the same font」、「change the jacket to red leather, keep everything else」、「remove the person on the left」。模型优先理解中文和英语；法语通常也能使用，但对于精确指令，英语仍然更可靠。负面提示词请留空或保持很短。

#步骤 4：设置，以及用于加速的 LoRA Lightning

官方工作流从 20 个步骤、2.5 的 CFG、euler 采样器和 simple 调度器开始。这些数值是很好的起点：该模型的 CFG 从设计上就较低，将其调到像 SDXL 那样的 7 会生成过度饱和且变形的图像。先更改种子（seed）以获得不同变体；如果结果不够精细，再调整步骤数。

1. 01
   没有 LoRA 的首个版本

   在一张简单图像上按原样运行该工作流，并使用简短指令。查看终端：首次执行会从磁盘加载 30 GB 权重，可能需要几分钟。后续执行会复用内存中的内容。
2. 02
   添加 LoRA Lightning

   在 Load Diffusion Model 和 ModelSamplingAuraFlow 之间插入一个 node LoraLoaderModelOnly，选择 4 步 Lightning LoRA，强度设为 1。将 KSampler 的步数设为 4，将 CFG 设为 1,0：这些 LoRA 经过训练，无需引导即可运行。步数减少到五分之一，因此去噪时间也按相同比例缩短，但细节和文字的保真度可能下降；LoRA 仓库没有量化这一点。
3. 03
   固定随机种子以便比较

   在比较两条提示词或两个模型变体之前，将 KSampler 设置为固定种子。否则，您会把由随机性造成的差异归因于设置。
4. 04
   连续进行多次编辑

   要分多轮修正，请将输出图像重新加载为新的输入。每一轮都会再次经过 VAE，并损失少量细节：限制在两到三轮，并保留原图。

#第 5 步：适用于 12 至 16 GB 显卡和 Mac 的 GGUF 变体

ComfyUI 原生无法读取 GGUF：必须安装 city96 的 ComfyUI-GGUF 扩展，该扩展可在 ComfyUI-Manager 中获取，也可以通过 Git 克隆到 custom_nodes 文件夹。它会添加专用的加载节点，而文件整理逻辑保持不变。

cd ComfyUI/custom_nodes
git clone https://github.com/city96/ComfyUI-GGUF
pip install -r ComfyUI-GGUF/requirements.txt
# puis redémarrer ComfyUI

1. 01
   选择量化方式

   以选定的 GGUF 仓库为例，例如 city96/Qwen-Image-Edit-gguf 或 QuantStack/Qwen-Image-Edit-2509-GGUF，其页面会列出每个文件及其大小。扣除目标分辨率所需空间后，选择最大的、还能在 VRAM 中留出约 2 GB 余量的文件：16 GB 选择 Q6_K 或 Q5_K_M，12 GB 选择 Q4_K_M。和 LLM 一样，Q4_K_M 通常是折中方案；低于 Q3 后，文本和细节会受到影响。
2. 02
   整理文件

   扩散模型的 GGUF 文件放入 models/diffusion_models，也可以放入该扩展同样会读取的 models/unet。文本编码器和 VAE 沿用第 1 步中的 safetensors 文件。
3. 03
   替换加载节点

   在官方工作流中，删除 Load Diffusion Model，并将其替换为 Unet Loader (GGUF)。将其 model 输出连接到原节点所在的位置。图的其余部分无需改变：TextEncodeQwenImageEdit、VAE、KSampler，全部保持相同的工作方式。
4. 04
   将编码器保留为 safetensors

   Qwen2.5-VL 7B 有 GGUF 版本，但为 llama.cpp 制作的版本面向对话，并不一定包含该编辑功能读取输入图像所需的视觉部分。使用官方的 qwen_2.5_vl_7b_fp8_scaled.safetensors 文件，可以排除一种错误原因。只有在仓库明确说明其兼容 ComfyUI-GGUF 中的 Qwen-Image-Edit 时，才切换到 GGUF 编码器。

在 Mac 上适用相同的流程，只有一个区别：请在“活动监视器”中监控内存压力。当统一内存溢出时，macOS 会写入 SSD，每张图像所需的时间会增加数倍，且不会显示错误消息。

#使用 Qwen-Image-Edit 时常见的节点错误

红色节点：找不到 TextEncodeQwenImageEdit 或 TextEncodeQwenImageEditPlus

ComfyUI 版本太旧。这些节点属于 ComfyUI 核心，而不是扩展：任何管理器都找不到它们。请更新 ComfyUI 并重启。

提示词输出未通过验证，值不在列表中

加载节点中选定的文件不存在于预期文件夹中。打开下载的工作流时，如果其中的文件名与你的文件名不同，就会出现这种情况。请重新打开每个加载节点的下拉菜单，然后选择你的文件。

Load CLIP 中没有出现 qwen_image 类型

原因相同：ComfyUI 版本早于 2025 年 8 月。请更新。

去噪开始时 CUDA out of memory

权重超出了 VRAM，卸载也不足以解决问题。按以下顺序操作：降低输出分辨率，改用更小的 GGUF 量化，关闭占用 GPU 的其他应用，然后尝试我们安装指南中介绍的 ComfyUI 内存选项，例如预留 VRAM 或禁用动态 VRAM。

输出图像呈彩色噪声或全黑

VAE，或其他系列的编码器。请确认 Load VAE 指向 qwen_image_vae.safetensors，Load CLIP 指向采用 qwen_image 类型的 Qwen2.5-VL 编码器。

图像没有修改，或几乎没有修改

提示词过于模糊，或者未使用 LoRA Lightning 时 CFG 降到了 1。未使用 LoRA 时，将 CFG 调回 2,5；把提示词改写为直接指令，并确认图像确实连接到了 TextEncodeQwenImageEdit 节点，而不仅仅是 VAE Encode。

重写后的文本错误或无法读取

在指令中将所需文本放在引号内，并明确要求保留字体。最激进的量化方式 Q2 和 Q3 会首先损害这一能力：处理文本编辑时，请改用 Q4 或 FP8。

2509 版本的工作流只接受一张图像

你加载的是旧版 TextEncodeQwenImageEdit 节点。请将其替换为 TextEncodeQwenImageEditPlus，它提供 image1、image2 和 image3 输入。

安装扩展后缺少 Unet Loader（GGUF）

未安装 Python 依赖，或 ComfyUI 未重启。请在 ComfyUI 环境中对扩展的 requirements.txt 文件重新运行 pip install，然后重启。终端会在启动时显示已加载扩展的列表及其可能出现的导入错误。

import torch
from PIL import Image
from diffusers import QwenImageEditPipeline

pipeline = QwenImageEditPipeline.from_pretrained("Qwen/Qwen-Image-Edit")
pipeline.to(torch.bfloat16)
pipeline.to("cuda")

image = Image.open("./input.png").convert("RGB")
prompt = "Change the rabbit's color to purple, with a flash light background."
inputs = {
    "image": image,
    "prompt": prompt,
    "generator": torch.manual_seed(0),
    "true_cfg_scale": 4.0,
    "negative_prompt": " ",
    "num_inference_steps": 50,
}
with torch.inference_mode():
    output = pipeline(**inputs)
    output.output_images[0].save("output_image_edit.png")

#深入了解

安装 ComfyUI 并了解其内存选项

台式机、笔记本电脑或手册，模型文件夹、动态 VRAM 和命令行选项。https://quelllm.fr/guide/comfyui-installation-guide-debutant

本地图像生成：全面概览

Mac 上的 Stable Diffusion、Flux、ComfyUI、Draw Things：哪种硬件适合哪种方案。https://quelllm.fr/guide/generer-images-en-local-guide

ControlNet：掌控构图

姿态、轮廓、深度：Qwen-Image-Edit 的 2509 版本原生集成了哪些功能，Stable Diffusion 上的说明。https://quelllm.fr/guide/controlnet-guide-stable-diffusion

什么是 VRAM，需要多少 VRAM

读取显卡内存，理解向 RAM 转移的过程，选择显卡。https://quelllm.fr/guide/vram-c-est-quoi-combien-pour-ia

官方来源

GitHub 仓库 QwenLM/Qwen-Image（版本列表和日期），Hugging Face 模型卡片 Qwen/Qwen-Image-Edit（Apache 2.0 许可证、Diffusers 示例），Comfy-Org/Qwen-Image-Edit_ComfyUI 和 Comfy-Org/Qwen-Image_ComfyUI 仓库（FP8 文件、大小），docs.comfy.org 上的 Qwen-Image 和 Qwen-Image-Edit 教程（目录结构、工作流），以及扩展 github.com/city96/ComfyUI-GGUF。