ComfyUI GGUF: execute grandes modelos de difusão em GPUs com pouca VRAM

GGUF é um formato binário desenvolvido pelo projeto llama.cpp para armazenar pesos de redes neurais quantizados. Originalmente criado para LLMs, foi adaptado para UNets de modelos de difusão, e o nó personalizado ComfyUI-GGUF nó personalizado de city96 traz esse suporte para o ComfyUI. O resultado prático: o FLUX.1-dev, que exige cerca de 24 GB de VRAM em precisão total BF16, torna-se executável em uma GPU de 6–8 GB com quantização Q4 — com qualidade de imagem muitas vezes indistinguível, a olho nu, da versão em precisão total.

Por que o GGUF é importante para geração de imagens

Os checkpoints de difusão padrão são distribuídos como .safetensors arquivos em FP16 ou BF16. Para modelos de gerações anteriores (SD1.5, com cerca de 2 GB, e SDXL, com cerca de 7 GB), isso é viável em hardware de faixa intermediária. Já para os modelos FLUX.1 e SD3, os arquivos em precisão total têm 24 GB e 16 GB, respectivamente — ultrapassando o limite de VRAM de qualquer GPU voltada ao consumidor.

A quantização GGUF mapeia cada peso para uma representação inteira menor. Um peso Q8_0 usa 8 bits em vez de 16, reduzindo aproximadamente à metade o tamanho do modelo com perda de qualidade praticamente imperceptível. As variantes Q4 usam 4 bits por peso, cortando o tamanho para cerca de um quarto do valor em fp16. Essas economias se tornam extremamente significativas em modelos com bilhões de parâmetros. Use o Calculadora de VRAM para estimar quanto de memória de GPU será necessária para um determinado nível de quantização antes mesmo de baixar qualquer arquivo.

O FLUX.1 também possui um grande codificador de texto T5-XXL (~9,3 GB em fp16). Ao combinar um UNet em formato GGUF com um codificador T5-XXL também em GGUF, todo o pipeline completo do FLUX.1 passa a caber em placas de vídeo que, de outra forma, seriam incapazes de executá-lo. Ambos os componentes podem ser carregados independentemente no formato GGUF.

Instalando o nó personalizado ComfyUI-GGUF

Via ComfyUI Manager (recomendado)

1. Abra o ComfyUI e clique em Manager na barra lateral.
2. Ir para Instalar Nós Personalizados.
3. Pesquise por nó personalizado ComfyUI-GGUF.
4. Clique Instalar ao lado da entrada de city96 e reinicie o ComfyUI.

Instalação Manual

Clone o repositório no seu diretório custom_nodes e instale sua dependência em Python:

cd ComfyUI/custom_nodes
git clone https://github.com/city96/ComfyUI-GGUF

Linux / macOS (venv):

source ComfyUI/venv/bin/activate
pip install -r ComfyUI/custom_nodes/ComfyUI-GGUF/requirements.txt

Windows (versão portátil do ComfyUI):

ComfyUIpython_embedspython.exe -m pip install -r ComfyUIcustom_nodesComfyUI-GGUFrequirements.txt

Windows (venv):

ComfyUIvenvScriptsactivate.bat
pip install -r ComfyUIcustom_nodesComfyUI-GGUFrequirements.txt

A principal dependência é o pacote Python gguf . Reinicie o ComfyUI após a instalação.

Obtendo arquivos de modelo GGUF

city96 faz o upload de versões GGUF dos modelos FLUX.1-dev e FLUX.1-schnell no Hugging Face, sob o nome de usuário city96. Pesquise por city96 FLUX.1-dev-gguf no Hugging Face para encontrar o repositório. Cada repositório contém vários .gguf arquivos, um para cada nível de quantização. Baixe apenas o arquivo correspondente ao nível de quantização desejado — não é necessário baixar todos eles.

Versões GGUF do codificador de texto T5-XXL também estão disponíveis no Hugging Face (pesquise por t5-v1_1-xxl-encoder-gguf). O codificador CLIP-L é pequeno o suficiente (~240 MB) para que sua quantização raramente valha o esforço.

Membros da comunidade também fazem o upload de variantes GGUF de modelos FLUX ajustados (fine-tuned) no CivitAI. A mesma estrutura de nós e diretórios se aplica, independentemente da origem do arquivo baixado.

Onde colocar os arquivos de modelo

O VAE do FLUX não é quantizado e permanece em seu local padrão. Apenas o UNet e o codificador de texto se beneficiam do carregamento em formato GGUF.

Usando os nós carregadores GGUF

Após instalar o ComfyUI-GGUF e reiniciar, novos nós aparecem no navegador de nós. Esses nós substituem suas versões padrão no seu fluxo de trabalho — você não pode carregar um .gguf arquivo com o nó padrão UNETLoader.

Para um fluxo de trabalho FLUX padrão: substitua UNETLoader para UnetLoaderGGUF, e substitua DualCLIPLoader para DualCLIPLoaderGGUF se você também estiver usando um T5-XXL no formato GGUF. Conecte as saídas aos mesmos nós downstream de antes — as formas dos tensores são compatíveis.

Escolhendo um nível de quantização

A tabela abaixo mostra valores aproximados apenas para os pesos do UNet do FLUX.1. Seu orçamento total de VRAM deve também cobrir o VAE (~350 MB), os codificadores de texto (240 MB para o CLIP-L, além do que você alocar para o T5-XXL) e os tensores intermediários durante a geração. Use o Referência de requisitos de VRAM juntamente com esta tabela e consulte o guia de GPUs se estiver decidindo qual placa comprar.

Pontos práticos de partida: Q5_K_S ou Q4_K_S para placas com 8–12 GB de VRAM (melhor relação qualidade/VRAM). Q3_K_S ou Q2_K para placas com 6 GB de VRAM, caso você também esteja usando um T5-XXL quantizado. Q8_0 para placas com 16 GB de VRAM, quando deseja fidelidade máxima mantendo todo o modelo na VRAM.

Checkpoints de difusão padrão são distribuídos como

No nível Q8_0, as diferenças em relação ao BF16 são virtualmente indetectáveis em comparações lado a lado. No nível Q4_K_S, texturas finas e renderização de texto podem apresentar uma degradação muito sutil sob inspeção minuciosa, mas as saídas têm qualidade adequada para produção na maioria dos casos de uso. O Q2_K introduz suavização visível e artefatos ocasionais, especialmente em rostos e detalhes finos — trata-se de uma solução de último recurso para hardware extremamente limitado em memória.

A velocidade de geração com GGUF pode ser comparável ou até superior à de carregar um modelo BF16 com descarga para CPU, pois os pesos quantizados reduzem a pressão sobre a largura de banda de memória. Contudo, se sua GPU puder manter o modelo BF16 completo inteiramente na VRAM sem descarga, isso geralmente será mais rápido do que a inferência com GGUF. A vantagem de desempenho do GGUF é mais pronunciada quando a alternativa envolve troca (swapping) de camadas entre VRAM e memória do sistema.

Em Apple Silicon (macOS), o backend MPS suporta inferência GGUF por meio do ComfyUI-GGUF, mas as características de desempenho diferem das da CUDA da NVIDIA. Os resultados são funcionais, porém a velocidade de geração pode ser inferior à de uma GPU NVIDIA equivalente. A arquitetura de memória unificada do Apple Silicon implica que o limite prático de VRAM é maior do que o de GPUs discretas com a mesma capacidade nominal; portanto, você talvez consiga executar níveis de quantização mais altos do que os sugeridos na tabela acima.

Em GPUs AMD (Linux, ROCm), a inferência GGUF funciona por meio do backend ROCm do PyTorch. Instale primeiro uma versão do PyTorch compatível com ROCm para o ComfyUI antes de instalar o ComfyUI-GGUF. Desempenho e compatibilidade variam conforme a geração da GPU; as placas RDNA 3 (série RX 7000) possuem o suporte mais confiável.

Perguntas frequentes

Posso carregar um arquivo .gguf com o nó padrão UNETLoader?

Não. O nó padrão UNETLoader aceita apenas arquivos .safetensors . Você deve instalar o nó personalizado ComfyUI-GGUF e usar o nó UnetLoaderGGUF para carregar .gguf modelos de difusão.

Preciso quantizar meus próprios modelos ou posso baixar arquivos pré-quantizados?

Para o FLUX.1-dev e o FLUX.1-schnell, o usuário city96 fornece arquivos GGUF pré-quantizados no Hugging Face, abrangendo todos os principais níveis de quantização. Baixe o arquivo .gguf específico para o nível desejado — não há necessidade de executar ferramentas de quantização por conta própria.

O GGUF funciona para modelos SD1.5 e SDXL?

Tecnicamente sim, mas o benefício é pequeno. O SD1.5 tem cerca de 2 GB e o SDXL cerca de 7 GB em fp16 — ambos já cabem confortavelmente em GPUs consumidoras de faixa média. A quantização GGUF é mais valiosa para modelos muito grandes (FLUX.1, SD3), cujos pesos em precisão total excedem a capacidade de VRAM da maioria das placas.

Um T5-XXL em GGUF é sensivelmente pior do que a versão completa em fp16?

Nos níveis Q8_0 ou Q5_K_S, a fidelidade ao prompt e a qualidade da codificação textual são efetivamente idênticas às da versão em fp16. Níveis mais baixos de quantização (Q2_K, Q3_K_S) podem ocasionalmente produzir uma aderência ligeiramente reduzida ao prompt em entradas complexas, mas essa degradação é sutil em comparação com o impacto sobre a qualidade do UNet no mesmo nível de quantização.

Meu fluxo de trabalho foi criado para um modelo FLUX em precisão total. Preciso reconstruí-lo?

Não. Substitua UNETLoader com UnetLoaderGGUF e (opcionalmente) DualCLIPLoader com DualCLIPLoaderGGUF. Todas as conexões downstream — KSampler, decodificação pelo VAE, condicionamento — permanecem inalteradas. As saídas desses nós são compatíveis em formato tensorial com o restante de um fluxo de trabalho FLUX padrão.

Por que o ComfyUI ainda esgota a VRAM mesmo com um modelo quantizado?

O UNet em GGUF representa apenas uma parte do consumo total de VRAM. Um pipeline FLUX completo também carrega o CLIP-L (~240 MB), o T5-XXL (até ~9,3 GB em fp16) e o VAE (~350 MB), além dos buffers de trabalho durante a geração. Se você ainda estiver esgotando a VRAM, carregue também o T5-XXL como GGUF por meio de DualCLIPLoaderGGUFe considere ativar o mosaico (tiling) interno do VAE do ComfyUI para a etapa de decodificação.