Qwen-Image-Edit localmente: ComfyUI e VRAM necessário

#Por que Qwen-Image-Edit e o que a família contém

A família Qwen-Image reúne dois usos. O Qwen-Image gera uma imagem a partir de um texto, com um ponto forte reconhecido em seu relatório técnico: a renderização de texto na imagem, incluindo frases inteiras e alfabetos não latinos. O Qwen-Image-Edit parte desse mesmo modelo para modificar uma imagem existente. O repositório GitHub QwenLM/Qwen-Image e a página do Hugging Face Qwen/Qwen-Image-Edit distinguem dois tipos de edição: a edição semântica, que altera o conteúdo ou o estilo mantendo a identidade do assunto, e a edição de aparência, que adiciona, remove ou substitui um elemento sem mexer no restante. O modelo também sabe corrigir ou substituir um texto em uma imagem preservando a fonte e o layout.

Arquitetura e licença são os dois fatos a considerar antes de baixar qualquer coisa. O modelo de difusão é um transformador multimodal (MMDiT) com cerca de 20 bilhões de parâmetros. O codificador de texto não é um CLIP pequeno: é o Qwen2.5-VL 7B, um modelo completo de visão e linguagem, que lê tanto sua instrução quanto a imagem de entrada. Ambos são publicados sob a licença Apache 2.0, que autoriza o uso comercial dos pesos. Cada componente é baixado separadamente, e é essa dispersão em três arquivos que causa a maioria dos erros de nodes descritos mais abaixo.

A linhagem evolui rapidamente. A primeira versão de Qwen-Image-Edit foi publicada em agosto de 2025. Uma versão datada de 2509 veio em setembro de 2025: ela aceita várias imagens de entrada e inclui nativamente condições do tipo ControlNet, como um mapa de profundidade, contornos ou uma pose. Uma versão 2511 chegou no fim de 2025 com melhor coerência do sujeito, e o modelo de geração recebeu, por sua vez, uma revisão 2512. Versões 2.x foram anunciadas em 2026. Este guia se baseia na linhagem documentada passo a passo pelo ComfyUI, da versão de agosto de 2025 à 2511: os nodes e a organização dos arquivos são os mesmos. Antes de escolher, leia o início do README do GitHub, que lista as versões com suas datas de publicação.

#Nativo, FP8 ou GGUF: qual versão do Qwen-Image-Edit baixar

Três formas do mesmo modelo estão circulando, e elas não são usadas da mesma maneira.

Nativo (bf16, formato Diffusers)

O repositório Qwen/Qwen-Image-Edit no Hugging Face, dividido em vários arquivos safetensors, destinado à biblioteca Diffusers em Python. Em bf16, 20 bilhões de parâmetros representam aproximadamente 40 GB apenas para o transformador, além do codificador de texto. Esse é o caminho dos scripts Python e das placas de 48 GB ou mais, ou de um deslocamento parcial para a RAM. Não é o caminho do ComfyUI.

FP8 reempacotado pela Comfy Org

O repositório Comfy-Org/Qwen-Image-Edit_ComfyUI no Hugging Face reúne os pesos em um único arquivo FP8 (formato e4m3fn), com o codificador de texto e o VAE separados em subpastas. É a versão usada pelos workflows oficiais do ComfyUI. O arquivo do modelo de difusão pesa um pouco mais de 20 GB. Uma variante bf16 de cerca de 41 GB existe no mesmo repositório para placas que têm espaço suficiente.

GGUF da comunidade

Conversões para o formato GGUF, o formato dos LLMs quantizados, publicadas por contribuidores como city96, QuantStack ou Unsloth. Elas chegam a Q8_0, Q6_K, Q5_K_M, Q4_K_M, Q3_K_M ou Q2_K, e exigem a extensão ComfyUI-GGUF. É a opção mais realista com menos de 16 GB de VRAM, e a mais confortável no Mac.

A regra de escolha é simples. Placa de 24 GB: FP8 oficial, sem pensar duas vezes. Placa de 16 GB: FP8 funciona graças ao deslocamento de memória do ComfyUI, mas um GGUF Q6_K ou Q5_K_M evita lentidão. Placa de 12 GB: GGUF Q4_K_M ou inferior. Mac Apple Silicon: GGUF, porque o ComfyUI não calcula em FP8 no Metal e desquantiza esses pesos durante o carregamento, dobrando a memória ocupada.

#VRAM necessária: onde ler os números e como interpretá-los

Nem o README do GitHub nem a página do Qwen no Hugging Face fornecem uma tabela do tipo «tanta VRAM para tal placa». A documentação do ComfyUI também não, para este modelo: seus tutoriais listam os arquivos a baixar, a pasta de destino e o workflow, e às vezes informam o hardware e o tempo de seus próprios testes, que devem ser considerados uma referência, não uma promessa. O dado confiável, datado e verificável é o tamanho de cada arquivo exibido em sua página no Hugging Face. Todo o resto é deduzido disso.

O modelo de difusão

Cerca de 20 GB em FP8 (arquivo qwen_image_edit_fp8_e4m3fn.safetensors do repositório Comfy-Org, publicado em agosto de 2025), cerca de 41 GB em bf16. Em GGUF, o peso é calculado assim: 20 bilhões de parâmetros multiplicados pelo número de bits por parâmetro, divididos por oito. Um Q8_0 de 8,5 bits dá cerca de 21 GB, um Q4_K_M de 4,5 a 5 bits dá cerca de 12 GB, um Q3_K_M dá cerca de 9 a 10 GB e um Q2_K dá cerca de 7 GB. A página de cada repositório GGUF exibe o valor exato de cada arquivo.

O codificador de texto

O arquivo qwen_2.5_vl_7b_fp8_scaled.safetensors do repositório Comfy-Org pesa cerca de 9,4 GB. Ele não precisa permanecer na VRAM durante a remoção de ruído: o ComfyUI o carrega para codificar o prompt e a imagem e depois o descarrega se faltar espaço. É por isso que um modelo de 20 GB e um codificador de 9 GB podem rodar em uma placa de 24 GB.

O VAE

O arquivo qwen_image_vae.safetensors tem cerca de 250 MB. É insignificante em termos de memória, mas indispensável e específico para essa família: um VAE de Flux ou de SDXL produz ruído colorido.

As ativações

O cálculo em si exige espaço além dos pesos, e mais ainda em alta resolução. O workflow oficial reduz a imagem de entrada para cerca de um megapixel, o que limita essa parcela. Duplique a resolução de saída e essa margem aumenta.

O ComfyUI ativa por padrão um gerenciamento dinâmico da VRAM, descrito em nosso guia de instalação: quando os pesos excedem a placa, parte deles permanece na RAM e é transferida sob demanda. O modelo então roda em uma placa de 12 ou 16 GB, mas cada passagem de um para o outro custa tempo, e a RAM do sistema se torna o verdadeiro limite: com um modelo de 20 GB e um encoder de 9 GB, 32 GB de RAM são o mínimo e 64 GB oferecem conforto. A tabela de referência abaixo resume a lógica, sem pretender ser uma medição.

24 GB ou mais (RTX 3090, 4090, 5090)

FP8 oficial completo, codificador FP8, imagem de saída de um megapixel sem transferência para outro dispositivo. O bf16 de 41 GB continua reservado às placas profissionais de 48 GB.

16 GB (RTX 4080, 5080, 4060 Ti 16 GB)

FP8 com offload, ou GGUF Q6_K a Q5_K_M que cabem na placa com o encoder descarregado entre as etapas.

12 GB (RTX 3060 12 GB, 4070, 5070, 5070 Ti)

GGUF Q4_K_M ou Q3_K_M, encoder FP8 carregado e depois descarregado, 32 GB de RAM. Espere gerações consideravelmente mais longas do que com SDXL.

8 GB

Possível em Q2_K ou Q3 com um grande volume de transferência, ao custo de menor velocidade e qualidade degradada. Apenas para edições ocasionais.

Mac Apple Silicon

A memória unificada serve como VRAM. Um GGUF Q4_K_M de 12 GB mais o encoder de 9 GB exigem um Mac de 32 GB; 48 GB ou mais para trabalhar sem aperto.

#Pré-requisitos

ComfyUI atualizado

Os nodes próprios do Qwen-Image, como TextEncodeQwenImageEdit, chegaram ao ComfyUI em agosto de 2025, e os da versão 2509 em setembro de 2025. Uma instalação mais antiga os ignora e exibe nodes vermelhos. Atualize antes de tudo: o Desktop é atualizado sozinho, o arquivo portátil pelo script update e a instalação manual com git pull.

Uma placa NVIDIA de no mínimo 12 GB ou um Mac de 32 GB

Abaixo disso, a edição continua possível, mas se torna um exercício de paciência. A AMD funciona no Linux com ROCm e, desde janeiro de 2026, no Windows com o aplicativo Desktop.

Espaço no disco

FP8: pouco mais de 30 GB para o trio modelo, codificador e VAE. Adicione de 10 a 21 GB por variante GGUF que você testar.

Uma instalação do ComfyUI que já funciona

Primeira imagem produzida com SDXL ou Flux. Se não for o caso, comece pelo guia de instalação: este guia começa quando o ComfyUI é aberto em http://127.0.0.1:8188.

#Etapas 1 e 2: baixar os arquivos corretos e organizá-los

O caminho mais curto é a biblioteca de modelos de workflows integrada ao ComfyUI: menu Workflow, Procurar modelos, categoria Image, depois o modelo Qwen-Image-Edit, ou sua variante 2509 ou 2511, dependendo da versão de seu interesse. O ComfyUI detecta os arquivos ausentes e oferece baixá-los diretamente para a pasta correta. Se preferir baixar manualmente, por exemplo para manter o controle sobre a variante escolhida, esta é a organização esperada, conforme documentada pelo tutorial Qwen-Image-Edit de docs.comfy.org.

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
   Baixar o modelo de difusão

   No Hugging Face, repositório Comfy-Org/Qwen-Image-Edit_ComfyUI, pasta split_files/diffusion_models. Pegue o arquivo FP8 correspondente à versão desejada. Verifique o tamanho exibido na página antes de clicar e depois compare-o com o arquivo recebido: um download interrompido gera um arquivo truncado e um erro ilegível ao carregar.
2. 02
   Baixar o codificador de texto e o VAE

   Mesmo repositório, pastas split_files/text_encoders e split_files/vae. O encoder é compartilhado pelo Qwen-Image e por todas as versões do Qwen-Image-Edit: basta uma única cópia, mesmo que você instale várias versões do modelo. O mesmo vale para o VAE.
3. 03
   Organizar cada arquivo em sua subpasta

   Modelo em diffusion_models, codificador em text_encoders, VAE em vae. Com o ComfyUI Desktop, a pasta models fica no local escolhido durante a instalação, visível nas configurações do aplicativo. Um arquivo colocado em checkpoints em vez de diffusion_models não aparece no node de carregamento.
4. 04
   Opcional: o LoRA Lightning

   O repositório lightx2v/Qwen-Image-Lightning publica LoRAs que reduzem a geração para 4 ou 8 passos, em vez de 20, tanto para Qwen-Image quanto para Qwen-Image-Edit. Arquivo em models/loras. As versões posteriores do modelo de edição têm seus próprios LoRAs Lightning: escolha aquele que traz o nome da sua versão.
5. 05
   Atualizar o ComfyUI

   Depois de copiar os arquivos, clique no botão de atualização da interface ou recarregue a página. Os nodes de carregamento relêem as pastas nesse momento, não continuamente.

#Etapa 3: carregar o workflow de edição e entender seus nodes

Abra o modelo de workflow Qwen-Image-Edit pela biblioteca. Se você baixou os arquivos manualmente, o ComfyUI pode oferecer baixá-los novamente: recuse e selecione seus arquivos nos nodes de carregamento. O grafo contém cerca de dez nodes, e cada um tem uma função específica.

Load Diffusion Model

Carrega o arquivo de models/diffusion_models. O menu suspenso deve exibir seu arquivo Qwen-Image-Edit; se estiver vazio, o arquivo foi colocado no lugar errado ou a interface não foi atualizada.

Load CLIP, type qwen_image

Carrega o encoder Qwen2.5-VL de models/text_encoders. O campo type deve ser qwen_image. Com outro tipo, o encoder é carregado sem erro, mas o prompt é interpretado incorretamente e você obtém qualquer coisa.

Load VAE

O VAE Qwen-Image. Nada mais.

Load Image, depois Scale Image to Total Pixels

Sua imagem para edição, redimensionada para cerca de um megapixel. Esse redimensionamento não é opcional: o modelo foi treinado nessa escala, e uma entrada muito maior prejudica a coerência e aumenta o uso de VRAM.

TextEncodeQwenImageEdit

O node próprio desta família. Ele recebe o codificador, o VAE, a imagem e sua instrução, e produz o condicionamento. Existem dois: um para a instrução positiva e outro para a negativa. A partir da versão 2509, o node se chama TextEncodeQwenImageEditPlus e aceita até três imagens.

ModelSamplingAuraFlow e CFGNorm

Dois nodes de ajuste do denoising, pré-configurados no workflow oficial, um deles com um deslocamento (shift) em torno de 3. Não os remova: sem eles, as imagens ficam desbotadas ou saturadas.

KSampler, VAE Decode, Save Image

A redução de ruído, a decodificação e o salvamento, como em qualquer workflow do ComfyUI. A imagem sai na pasta output com o workflow completo gravado no PNG.

Escreva a instrução como uma instrução, não como uma descrição da imagem final: “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”. O modelo entende chinês e inglês prioritariamente; o francês costuma funcionar, mas o inglês continua sendo mais confiável para instruções precisas. Deixe a instrução negativa vazia ou bem curta.

#Etapa 4: as configurações e o LoRA Lightning para ganhar velocidade

O workflow oficial começa com 20 passos, CFG de 2,5, o sampler euler e o scheduler simple. Esses valores são um bom ponto de partida: o CFG deste modelo é baixo por construção, e aumentá-lo para 7, como no SDXL, produz imagens saturadas e distorcidas. Primeiro mude a seed para obter variações e, depois, o número de passos se o resultado não tiver fineza.

1. 01
   Primeira edição sem LoRA

   Execute o workflow como está em uma imagem simples, com uma instrução curta. Observe o terminal: a primeira execução carrega 30 GB de pesos do disco, o que pode levar vários minutos. As execuções seguintes reutilizam o que está na memória.
2. 02
   Adicionar o LoRA Lightning

   Insira um node LoraLoaderModelOnly entre Load Diffusion Model e ModelSamplingAuraFlow, selecione o LoRA Lightning de 4 passos, defina a força como 1. Ajuste o KSampler para 4 passos e o CFG para 1,0: esses LoRA são treinados para funcionar sem orientação. O número de passos é dividido por cinco, portanto o tempo de remoção de ruído diminui na mesma proporção, ao custo de uma possível perda de fidelidade nos detalhes finos e no texto, que o repositório do LoRA não quantifica.
3. 03
   Fixar a semente para comparar

   Defina uma semente fixa no KSampler antes de comparar duas instruções ou duas variantes de modelo. Caso contrário, você atribuirá ao ajuste diferenças que vêm do acaso.
4. 04
   Encadear várias edições

   Para corrigir em várias etapas, recarregue a imagem de saída como uma nova entrada. Cada etapa passa novamente pelo VAE e perde um pouco de detalhe: limite-se a duas ou três e mantenha o original.

#Etapa 5: a variante GGUF para placas de 12 a 16 GB e Macs

O ComfyUI não lê GGUF nativamente: é necessária a extensão ComfyUI-GGUF, de city96, disponível no ComfyUI-Manager ou por meio de um clone Git na pasta custom_nodes. Ela adiciona nodes de carregamento dedicados, e a lógica de organização continua a mesma.

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
   Escolher a quantização

   No repositório GGUF escolhido, por exemplo city96/Qwen-Image-Edit-gguf ou QuantStack/Qwen-Image-Edit-2509-GGUF, a página lista cada arquivo com seu tamanho. Escolha o maior que deixe cerca de 2 GB de margem na sua VRAM após descontar a resolução desejada: Q6_K ou Q5_K_M para 16 GB, Q4_K_M para 12 GB. Assim como nos LLMs, Q4_K_M é o compromisso habitual; abaixo de Q3, os textos e os pequenos detalhes sofrem.
2. 02
   Organizar o arquivo

   O GGUF do modelo de difusão vai para models/diffusion_models, ou para models/unet, que a extensão também lê. O codificador de texto e o VAE continuam sendo os da etapa 1, em safetensors.
3. 03
   Substituir o node de carregamento

   No workflow oficial, exclua Load Diffusion Model e coloque Unet Loader (GGUF) em seu lugar. Conecte a saída model onde estava a antiga. O restante do grafo não muda: TextEncodeQwenImageEdit, VAE, KSampler, tudo funciona de forma idêntica.
4. 04
   Manter o codificador em safetensors

   Existem GGUF do Qwen2.5-VL 7B, mas os produzidos para o llama.cpp são pensados para diálogo e não incluem necessariamente a parte de visão de que a edição precisa para ler a imagem de entrada. Com o arquivo oficial qwen_2.5_vl_7b_fp8_scaled.safetensors, você elimina uma causa de erro. Só passe para um codificador GGUF se o repositório indicar explicitamente a compatibilidade com Qwen-Image-Edit no ComfyUI-GGUF.

No Mac, aplica-se o mesmo procedimento, com uma única diferença: monitore a pressão da memória no Monitor de Atividade. Quando a memória unificada transborda, o macOS grava no SSD e cada imagem leva várias vezes mais tempo, sem exibir mensagem de erro.

#Erros frequentes de nodes com Qwen-Image-Edit

Nodes vermelhos: TextEncodeQwenImageEdit ou TextEncodeQwenImageEditPlus não encontrado

O ComfyUI é antigo demais. Esses nodes fazem parte do núcleo do ComfyUI, não de uma extensão: nenhum gerenciador os encontrará. Atualize o ComfyUI e reinicie.

As saídas do prompt falharam na validação; valor não está na lista

O arquivo selecionado em um nó de carregamento não existe na pasta esperada. Isso acontece quando abrimos um workflow baixado cujos nomes de arquivo diferem dos seus. Reabra o menu suspenso de cada nó de carregamento e escolha seu arquivo.

O tipo qwen_image não aparece em Load CLIP

Mesma causa: versão do ComfyUI anterior a agosto de 2025. Atualize.

CUDA out of memory no início da remoção de ruído

Os pesos ultrapassam a VRAM e o deslocamento não foi suficiente. Na ordem: reduza a resolução de saída, passe para uma quantização GGUF menor, feche os outros aplicativos que ocupam a GPU e depois tente as opções de memória do ComfyUI descritas em nosso guia de instalação, como reservar VRAM ou desativar a VRAM dinâmica.

Imagem de saída feita de ruído colorido ou preta

VAE ou encoder de outra família. Verifique se Load VAE aponta para qwen_image_vae.safetensors e Load CLIP para o encoder Qwen2.5-VL com o tipo qwen_image.

A imagem não é modificada, ou quase não é

Instrução vaga demais ou CFG reduzido a 1 sem o LoRA Lightning. Aumente o CFG para 2,5 sem LoRA, reformule a instrução como um comando direto e verifique se a imagem está realmente conectada ao node TextEncodeQwenImageEdit, e não apenas ao VAE Encode.

O texto reescrito está errado ou ilegível

Coloque o texto desejado entre aspas na instrução, especificando que a fonte deve ser preservada. As quantizações mais agressivas, Q2 e Q3, prejudicam primeiro essa capacidade: volte para Q4 ou FP8 nas edições de texto.

O workflow da versão 2509 aceita apenas uma imagem

Você carregou o node antigo TextEncodeQwenImageEdit. Substitua-o por TextEncodeQwenImageEditPlus, que expõe as entradas image1, image2 e image3.

Unet Loader (GGUF) ausente após a instalação da extensão

Dependências Python não instaladas ou ComfyUI não reiniciado. Execute novamente o pip install no arquivo requirements.txt da extensão, dentro do ambiente do ComfyUI, e depois reinicie. O terminal exibe, na inicialização, a lista de extensões carregadas e seus possíveis erros de importação.

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")

#Para se aprofundar

Instalar o ComfyUI e entender suas opções de memória

Desktop, portátil ou manual, pastas de modelos, VRAM dinâmica e opções de linha de comando. https://quelllm.fr/guide/comfyui-installation-guide-debutant

Gerar imagens localmente: o panorama

Stable Diffusion, Flux, ComfyUI, Draw Things no Mac: qual opção para qual hardware. https://quelllm.fr/guide/generer-images-en-local-guide

ControlNet: dominar a composição

Pose, contornos, profundidade: o que a versão 2509 de Qwen-Image-Edit integra nativamente, explicado no Stable Diffusion. https://quelllm.fr/guide/controlnet-guide-stable-diffusion

VRAM: o que é e de quanta você precisa

Leia a memória da sua placa, entenda o uso da RAM como extensão, escolha uma placa. https://quelllm.fr/guide/vram-c-est-quoi-combien-pour-ia

Fontes oficiais

Repositório GitHub QwenLM/Qwen-Image (lista de versões e datas), página do Hugging Face Qwen/Qwen-Image-Edit (licença Apache 2.0, exemplo Diffusers), repositórios Comfy-Org/Qwen-Image-Edit_ComfyUI e Comfy-Org/Qwen-Image_ComfyUI (arquivos FP8, tamanhos), tutoriais Qwen-Image e Qwen-Image-Edit em docs.comfy.org (estrutura de diretórios, workflows), extensão github.com/city96/ComfyUI-GGUF.