Executando FLUX.1-dev GGUF Q8 em Python

FLUX.1-dev é um modelo poderoso de geração de imagem a partir de texto que produz resultados impressionantes, mas seu requisito de memória de 24GB+ torna difícil executá-lo em muitos sistemas. Quantização GGUF de FLUX.1-dev oferece uma solução, reduzindo o uso de memória em aproximadamente 50% enquanto mantém a excelente qualidade das imagens.

Esta imagem foi gerada usando o modelo FLUX.1-dev quantizado Q8 no formato GGUF, demonstrando que a qualidade é preservada mesmo com um menor footprint de memória.

O que é a Quantização GGUF?

GGUF (GPT-Generated Unified Format) é um formato de quantização originalmente desenvolvido para modelos de linguagem, mas agora suportado para modelos de difusão como FLUX. A quantização reduz o tamanho do modelo armazenando os pesos em formatos de precisão mais baixa (8-bit, 6-bit ou 4-bit) em vez de precisão completa de 16-bit ou 32-bit.

Para FLUX.1-dev, o componente transformer (a parte maior do modelo) pode ser quantizado, reduzindo seu footprint de memória de aproximadamente 24GB para 12GB com a quantização Q8_0, ou ainda mais baixo com níveis de quantização mais agressivos.

Benefícios da Quantização GGUF

As principais vantagens de usar modelos FLUX quantizados GGUF incluem:

• Redução do Uso de Memória: Corte pela metade as exigências de VRAM, tornando FLUX.1-dev acessível em mais hardware
• Qualidade Mantida: A quantização Q8_0 preserva a qualidade da imagem com mínimas diferenças visíveis
• Carregamento Mais Rápido: Modelos quantizados carregam mais rápido devido aos tamanhos de arquivo menores
• Consumo de Energia Mais Baixo: O uso reduzido de memória se traduz em menor consumo de energia durante a inferência

Em nossos testes, o modelo quantizado usa aproximadamente 12-15GB de VRAM em comparação com 24GB+ para o modelo completo, enquanto o tempo de geração permanece semelhante.

Instalação e Configuração

Para usar o FLUX.1-dev quantizado GGUF, você precisará do pacote gguf além das dependências padrão de diffusers. Se você já está usando FLUX para geração de imagem a partir de texto, você já está familiarizado com a configuração básica.

Se você está usando uv como seu gerenciador de pacotes Python, você pode instalar os pacotes necessários com:

uv pip install -U diffusers torch transformers gguf

Ou com o pip padrão:

pip install -U diffusers torch transformers gguf

Implementação

A diferença principal ao usar modelos GGUF quantizados é que você carrega o transformer separadamente usando FluxTransformer2DModel.from_single_file() com GGUFQuantizationConfig, depois passa-o para o pipeline. Se você precisa de uma referência rápida para a sintaxe Python, consulte a Folha de Dicas do Python. Aqui está um exemplo completo e funcional:

import os
import torch
from diffusers import FluxPipeline, FluxTransformer2DModel, GGUFQuantizationConfig

# Caminhos
gguf_model_path = "/caminho/para/flux1-dev-Q8_0.gguf"
base_model_path = "/caminho/para/FLUX.1-dev-config"  # Apenas arquivos de configuração

# Carregar transformer quantizado GGUF
print(f"Carregando transformer quantizado GGUF de: {gguf_model_path}")
transformer = FluxTransformer2DModel.from_single_file(
    gguf_model_path,
    quantization_config=GGUFQuantizationConfig(compute_dtype=torch.bfloat16),
    config=base_model_path,
    subfolder="transformer",
    torch_dtype=torch.bfloat16,
)

# Criar pipeline com transformer quantizado
print(f"Criando pipeline com modelo base: {base_model_path}")
pipe = FluxPipeline.from_pretrained(
    base_model_path,
    transformer=transformer,
    torch_dtype=torch.bfloat16,
)

# Habilitar offloading para CPU (requerido para GGUF)
pipe.enable_model_cpu_offload()
# Nota: enable_sequential_cpu_offload() NÃO é compatível com GGUF

# Gerar imagem
prompt = "Uma paisagem urbana futurista ao entardecer com luzes neon"
image = pipe(
    prompt,
    height=496,
    width=680,
    guidance_scale=3.5,
    num_inference_steps=60,
    max_sequence_length=512,
    generator=torch.Generator("cpu").manual_seed(42)
).images[0]

image.save("output.jpg")

Considerações Importantes

Arquivos de Configuração do Modelo

Ao usar a quantização GGUF, você ainda precisa dos arquivos de configuração do modelo original FLUX.1-dev. Eles incluem:

• model_index.json - Estrutura do pipeline
• Configurações dos componentes (transformer, text_encoder, text_encoder_2, vae, scheduler)
• Arquivos do tokenizer
• Pesos do text encoder e VAE (esses não são quantizados)

Os pesos do transformer vêm do arquivo GGUF, mas todos os outros componentes exigem os arquivos do modelo original.

Compatibilidade com Offloading para CPU

Importante: enable_sequential_cpu_offload() não é compatível com modelos quantizados GGUF e causará um erro KeyError: None. Estou usando apenas enable_model_cpu_offload() ao trabalhar com transformers quantizados.

Níveis de Quantização

Níveis de quantização disponíveis para FLUX.1-dev incluem:

• Q8_0: Melhor qualidade, ~14-15GB de memória (recomendado)
• Q6_K: Bom equilíbrio, ~12GB de memória
• Q4_K: Máxima compressão, ~8GB de memória (assumo que afeta a qualidade de forma negativa)

Para a maioria dos casos de uso, a Q8_0 oferece o melhor equilíbrio entre economia de memória e qualidade da imagem.

Comparação de Desempenho

Em nossos testes com prompts e configurações idênticas:

O modelo quantizado, porque agora requer menos offloading para CPU, tem mais de três vezes a velocidade de geração enquanto usa significativamente menos memória, tornando-o prático para sistemas com VRAM limitada.

Testei ambos os modelos com o prompt

Um close-up futurista de um chip ASIC de inferência de transformer com circuitos intricados, luz azul brilhante emitindo de unidades de multiplicação densa e ALUs de baixa precisão, cercado por buffers de SRAM no chip e pipelines de quantização, renderizado em estilo fotorealístico hiper-detalhado com um esquema de iluminação frio e clínico.

A saída de exemplo do FLUX.1-dev Q8 é a imagem de capa deste post - veja acima.

A saída de exemplo do FLUX.1-dev não quantizado está abaixo:

Não vejo muita diferença na qualidade.

Conclusão

A quantização GGUF torna o FLUX.1-dev acessível a uma gama mais ampla de hardware, mantendo a alta qualidade de geração de imagem pela qual o modelo é conhecido. Ao reduzir as exigências de memória em aproximadamente 50%, você pode executar a geração de imagem de texto de ponta em hardware mais acessível sem perda significativa de qualidade.

A implementação é direta com a biblioteca diffusers, exigindo apenas pequenas alterações na configuração padrão do pipeline FLUX. Para a maioria dos usuários, a quantização Q8_0 oferece o equilíbrio ideal entre eficiência de memória e qualidade da imagem.

Se você está trabalhando com FLUX.1-Kontext-dev para aumento de imagem, técnicas de quantização semelhantes podem tornar-se disponíveis no futuro.

Artigos Relacionados

• Flux texto para imagem - guia para usar FLUX.1-dev para geração de imagem a partir de texto
• FLUX.1-Kontext-dev: Modelo de IA para Aumento de Imagem
• uv - Novo Gerenciador de Pacotes, Projetos e Ambientes Python
• Folha de Dicas do Python

Referências

• Documentação GGUF do HuggingFace Diffusers - Documentação oficial sobre o uso de GGUF com diffusers
• Unsloth FLUX.1-dev-GGUF - Modelos GGUF pré-quantizados para FLUX.1-dev
• Black Forest Labs FLUX.1-dev - Repositório do modelo original FLUX.1-dev
• Especificação do Formato GGUF - Detalhes técnicos sobre o formato GGUF