Skip to content

artubss/SKILLS-CLAUDE-CODE / skills/skills/ai-research/optimization-gguf

gguf-quantization

Verified

Formato GGUF e quantização llama.cpp para inferência eficiente em CPU/GPU. Use ao implantar modelos em hardware de consumidor, Apple Silicon, ou quando precisar de quantização flexível de 2-8 bits sem requisitos de GPU.

GGUF - Formato de Quantização para llama.cpp

GGUF (GPT-Generated Unified Format) é o formato de arquivo padrão para llama.cpp, permitindo inferência eficiente em CPUs, Apple Silicon e GPUs com opções de quantização flexível.

Quando usar GGUF

Use GGUF quando:

  • Implantando em hardware de consumidor (laptops, desktops)
  • Executando em Apple Silicon (M1/M2/M3) com aceleração Metal
  • Precisar de inferência em CPU sem requisitos de GPU
  • Quiser quantização flexível (Q2_K a Q8_0)
  • Usando ferramentas locais de IA (LM Studio, Ollama, text-generation-webui)

Principais vantagens:

  • Hardware universal: Suporte para CPU, Apple Silicon, NVIDIA, AMD
  • Sem runtime Python: Inferência pura em C/C++
  • Quantização flexível: 2-8 bits com vários métodos (K-quants)
  • Suporte do ecossistema: LM Studio, Ollama, koboldcpp e outros
  • imatrix: Matriz de importância para melhor qualidade em bits baixos

Use alternativas em vez disso:

  • AWQ/GPTQ: Máxima precisão com calibração em GPUs NVIDIA
  • HQQ: Quantização rápida sem calibração para HuggingFace
  • bitsandbytes: Integração simples com a biblioteca transformers
  • TensorRT-LLM: Implantação NVIDIA em produção com máxima velocidade

Início rápido

Instalação

# Clone llama.cpp
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp

# Build (CPU)
make

# Build com CUDA (NVIDIA)
make GGML_CUDA=1

# Build com Metal (Apple Silicon)
make GGML_METAL=1

# Instalar bindings Python (opcional)
pip install llama-cpp-python

Converter modelo para GGUF

# Instalar requisitos
pip install -r requirements.txt

# Converter modelo HuggingFace para GGUF (FP16)
python convert_hf_to_gguf.py ./path/to/model --outfile model-f16.gguf

# Ou especificar tipo de saída
python convert_hf_to_gguf.py ./path/to/model \
    --outfile model-f16.gguf \
    --outtype f16

Quantizar modelo

# Quantização básica para Q4_K_M
./llama-quantize model-f16.gguf model-q4_k_m.gguf Q4_K_M

# Quantizar com matriz de importância (melhor qualidade)
./llama-imatrix -m model-f16.gguf -f calibration.txt -o model.imatrix
./llama-quantize --imatrix model.imatrix model-f16.gguf model-q4_k_m.gguf Q4_K_M

Executar inferência

# Inferência CLI
./llama-cli -m model-q4_k_m.gguf -p "Hello, how are you?"

# Modo interativo
./llama-cli -m model-q4_k_m.gguf --interactive

# Com offload de GPU
./llama-cli -m model-q4_k_m.gguf -ngl 35 -p "Hello!"

Tipos de quantização

Métodos K-quant (recomendados)

TipoBitsTamanho (7B)QualidadeCaso de Uso
Q2_K2.5~2.8 GBBaixaCompressão extrema
Q3_K_S3.0~3.0 GBBaixa-MedMemória limitada
Q3_K_M3.3~3.3 GBMédiaEquilíbrio
Q4_K_S4.0~3.8 GBMed-AltaBom equilíbrio
Q4_K_M4.5~4.1 GBAltaPadrão recomendado
Q5_K_S5.0~4.6 GBAltaFocado em qualidade
Q5_K_M5.5~4.8 GBMuito AltaAlta qualidade
Q6_K6.0~5.5 GBExcelentePróximo ao original
Q8_08.0~7.2 GBMelhorMáxima qualidade

Métodos herdados

TipoDescrição
Q4_04-bit, básico
Q4_14-bit com delta
Q5_05-bit, básico
Q5_15-bit com delta

Recomendação: Use métodos K-quant (Q4_K_M, Q5_K_M) para melhor proporção qualidade/tamanho.

Fluxos de conversão

Fluxo 1: HuggingFace para GGUF

# 1. Baixar modelo
huggingface-cli download meta-llama/Llama-3.1-8B --local-dir ./llama-3.1-8b

# 2. Converter para GGUF (FP16)
python convert_hf_to_gguf.py ./llama-3.1-8b \
    --outfile llama-3.1-8b-f16.gguf \
    --outtype f16

# 3. Quantizar
./llama-quantize llama-3.1-8b-f16.gguf llama-3.1-8b-q4_k_m.gguf Q4_K_M

# 4. Testar
./llama-cli -m llama-3.1-8b-q4_k_m.gguf -p "Hello!" -n 50

Fluxo 2: Com matriz de importância (melhor qualidade)

# 1. Converter para GGUF
python convert_hf_to_gguf.py ./model --outfile model-f16.gguf

# 2. Criar texto de calibração (amostras diversas)
cat > calibration.txt << 'EOF'
The quick brown fox jumps over the lazy dog.
Machine learning is a subset of artificial intelligence.
Python is a popular programming language.
# Adicionar mais amostras de texto diversas...
EOF

# 3. Gerar matriz de importância
./llama-imatrix -m model-f16.gguf \
    -f calibration.txt \
    --chunk 512 \
    -o model.imatrix \
    -ngl 35  # Camadas GPU se disponível

# 4. Quantizar com imatrix
./llama-quantize --imatrix model.imatrix \
    model-f16.gguf \
    model-q4_k_m.gguf \
    Q4_K_M

Fluxo 3: Múltiplas quantizações

#!/bin/bash
MODEL="llama-3.1-8b-f16.gguf"
IMATRIX="llama-3.1-8b.imatrix"

# Gerar imatrix uma vez
./llama-imatrix -m $MODEL -f wiki.txt -o $IMATRIX -ngl 35

# Criar múltiplas quantizações
for QUANT in Q4_K_M Q5_K_M Q6_K Q8_0; do
    OUTPUT="llama-3.1-8b-${QUANT,,}.gguf"
    ./llama-quantize --imatrix $IMATRIX $MODEL $OUTPUT $QUANT
    echo "Created: $OUTPUT ($(du -h $OUTPUT | cut -f1))"
done

Uso em Python

llama-cpp-python

from llama_cpp import Llama

# Carregar modelo
llm = Llama(
    model_path="./model-q4_k_m.gguf",
    n_ctx=4096,          # Janela de contexto
    n_gpu_layers=35,     # Offload de GPU (0 apenas CPU)
    n_threads=8          # Threads de CPU
)

# Gerar
output = llm(
    "What is machine learning?",
    max_tokens=256,
    temperature=0.7,
    stop=["</s>", "\n\n"]
)
print(output["choices"][0]["text"])

Conclusão de chat

from llama_cpp import Llama

llm = Llama(
    model_path="./model-q4_k_m.gguf",
    n_ctx=4096,
    n_gpu_layers=35,
    chat_format="llama-3"  # Ou "chatml", "mistral", etc.
)

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is Python?"}
]

response = llm.create_chat_completion(
    messages=messages,
    max_tokens=256,
    temperature=0.7
)
print(response["choices"][0]["message"]["content"])

Streaming

from llama_cpp import Llama

llm = Llama(model_path="./model-q4_k_m.gguf", n_gpu_layers=35)

# Transmitir tokens
for chunk in llm(
    "Explain quantum computing:",
    max_tokens=256,
    stream=True
):
    print(chunk["choices"][0]["text"], end="", flush=True)

Modo servidor

Iniciar servidor compatível com OpenAI

# Iniciar servidor
./llama-server -m model-q4_k_m.gguf \
    --host 0.0.0.0 \
    --port 8080 \
    -ngl 35 \
    -c 4096

# Ou com bindings Python
python -m llama_cpp.server \
    --model model-q4_k_m.gguf \
    --n_gpu_layers 35 \
    --host 0.0.0.0 \
    --port 8080

Usar com cliente OpenAI

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"
)

response = client.chat.completions.create(
    model="local-model",
    messages=[{"role": "user", "content": "Hello!"}],
    max_tokens=256
)
print(response.choices[0].message.content)

Otimização de hardware

Apple Silicon (Metal)

# Build com Metal
make clean && make GGML_METAL=1

# Executar com aceleração Metal
./llama-cli -m model.gguf -ngl 99 -p "Hello"

# Python com Metal
llm = Llama(
    model_path="model.gguf",
    n_gpu_layers=99,     # Offload de todas as camadas
    n_threads=1          # Metal gerencia o paralelismo
)

NVIDIA CUDA

# Build com CUDA
make clean && make GGML_CUDA=1

# Executar com CUDA
./llama-cli -m model.gguf -ngl 35 -p "Hello"

# Especificar GPU
CUDA_VISIBLE_DEVICES=0 ./llama-cli -m model.gguf -ngl 35

Otimização de CPU

# Build com AVX2/AVX512
make clean && make

# Executar com threads otimizados
./llama-cli -m model.gguf -t 8 -p "Hello"

# Configuração Python apenas CPU
llm = Llama(
    model_path="model.gguf",
    n_gpu_layers=0,      # Apenas CPU
    n_threads=8,         # Corresponder aos núcleos físicos
    n_batch=512          # Tamanho do lote para processamento de prompt
)

Integração com ferramentas

Ollama

# Criar Modelfile
cat > Modelfile << 'EOF'
FROM ./model-q4_k_m.gguf
TEMPLATE """{{ .System }}
{{ .Prompt }}"""
PARAMETER temperature 0.7
PARAMETER num_ctx 4096
EOF

# Criar modelo Ollama
ollama create mymodel -f Modelfile

# Executar
ollama run mymodel "Hello!"

LM Studio

  1. Colocar arquivo GGUF em ~/.cache/lm-studio/models/
  2. Abrir LM Studio e selecionar o modelo
  3. Configurar comprimento de contexto e offload de GPU
  4. Iniciar inferência

text-generation-webui

# Colocar na pasta de modelos
cp model-q4_k_m.gguf text-generation-webui/models/

# Iniciar com loader llama.cpp
python server.py --model model-q4_k_m.gguf --loader llama.cpp --n-gpu-layers 35

Melhores práticas

  1. Use K-quants: Q4_K_M oferece melhor equilíbrio qualidade/tamanho
  2. Use imatrix: Sempre use matriz de importância para Q4 e abaixo
  3. Offload de GPU: Descarregue o máximo de camadas permitido pela VRAM
  4. Comprimento de contexto: Comece com 4096, aumente se necessário
  5. Contagem de threads: Corresponda aos núcleos físicos da CPU, não lógicos
  6. Tamanho do lote: Aumente n_batch para processamento mais rápido de prompt

Problemas comuns

Modelo carrega lentamente:

# Use mmap para carregamento mais rápido
./llama-cli -m model.gguf --mmap

Memória insuficiente:

# Reduzir camadas de GPU
./llama-cli -m model.gguf -ngl 20  # Reduzir de 35

# Ou usar quantização menor
./llama-quantize model-f16.gguf model-q3_k_m.gguf Q3_K_M

Qualidade fraca em bits baixos:

# Sempre use imatrix para Q4 e abaixo
./llama-imatrix -m model-f16.gguf -f calibration.txt -o model.imatrix
./llama-quantize --imatrix model.imatrix model-f16.gguf model-q4_k_m.gguf Q4_K_M

Referências

Recursos

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 192kUpdated Claude CodeCodexVerifiedInstall