Módulo 3.4: vLLM — Alternativa Avançada

🚀 O que é vLLM

vLLM é um framework de serving de modelos LLM desenvolvido na UC Berkeley. Usa uma técnica chamada PagedAttention que gerencia o KV-cache de forma muito mais eficiente que implementações tradicionais, resultando em throughput até 10x superior.

🚀 PagedAttention: O Diferencial do vLLM

O KV-cache (armazenamento de atenção) é o gargalo principal em serving de LLMs. PagedAttention resolve isso usando memória virtual paginada, similar ao que o sistema operacional faz com memória RAM.

• Sem fragmentação — memória é alocada em páginas fixas, sem desperdício
• Continuous batching — processa múltiplas requisições simultaneamente sem latência extra
• Utilização de VRAM — usa 80-95% da VRAM disponível eficientemente

📊 Benchmarks de Throughput

Cenário	Ollama	vLLM	Ganho
1 usuário, Llama 7B, A100	~80 tok/s	~120 tok/s	1.5x
10 usuários, Llama 7B, A100	~15 tok/s	~800 tok/s	50x
1 usuário, 30B, RTX 4090	~25 tok/s	~45 tok/s	1.8x

* Valores aproximados, variam por hardware e configuração

⚖️ vLLM vs Ollama

Cada ferramenta tem seu nicho ideal. A regra geral: Ollama para uso pessoal sem GPU, vLLM para servidores com GPU ou uso multi-usuário.

🦙 Ollama

✓ Instalação em 1 comando, sem dependências
✓ Funciona sem GPU (CPU apenas)
✓ Interface web embutida (localhost:11434)
✓ Gerenciamento fácil de modelos (pull/rm)
✗ Menor throughput com múltiplos usuários
✗ Menos configurável para otimizações avançadas

Ideal para: uso pessoal, desenvolvimento, hardware sem GPU

🚀 vLLM

✓ Throughput muito superior com GPU dedicada
✓ Continuous batching (múltiplos usuários)
✓ Suporta tensor parallelism (multi-GPU)
✓ Muitas opções de quantização (AWQ, GPTQ, FP8)
✗ Instalação complexa (CUDA, Python, PyTorch)
✗ Requer GPU NVIDIA (CUDA) para máxima performance

Ideal para: servidores GPU, VPS GPU, times com múltiplos devs

🐍 Instalando vLLM

vLLM é instalado via pip e requer um ambiente Python configurado corretamente. Versões específicas de CUDA e PyTorch são críticas — use o guia abaixo para evitar conflitos de dependência.

Verificar Requisitos

Checar versão do CUDA e Python antes de instalar

nvidia-smi          # ver versão CUDA e GPU
python3 --version   # precisa 3.9+
# CUDA mínimo: 11.8 (recomendado: 12.x)

Criar Ambiente Virtual

Isolar dependências do vLLM do sistema

python3 -m venv vllm-env
source vllm-env/bin/activate  # Linux/Mac
# vllm-env\Scripts\activate  # Windows

Instalar vLLM

Instalação padrão via pip (demora 5-15 min)

pip install vllm

# Para máxima performance com Flash Attention:
pip install vllm[flash-attn]  # GPUs Ampere+ (RTX 30xx/40xx, A100)

Verificar Instalação

Confirmar que vLLM foi instalado corretamente

python -c "import vllm; print(vllm.__version__)"
# Deve mostrar a versão instalada, ex: 0.6.x

⚠️ Erros Comuns na Instalação

CUDA version mismatch: use pip install vllm --extra-index-url https://download.pytorch.org/whl/cu121 para CUDA 12.1
torch not found: instale PyTorch antes: pip install torch torchvision
Out of memory durante import: verifique VRAM disponível com nvidia-smi

▶️ Rodando um Modelo com vLLM

O servidor vLLM é iniciado via Python com o módulo api_server. Os modelos são baixados automaticamente do HuggingFace na primeira execução.

▶️ Comando de Inicialização

python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-Coder-32B-Instruct \
  --port 8000 \
  --gpu-memory-utilization 0.9

Na primeira execução, o modelo (~20GB) será baixado do HuggingFace. Execuções subsequentes carregam do cache local.

Parâmetros Essenciais

--model — ID do modelo no HuggingFace
--port — porta HTTP (padrão: 8000)
--gpu-memory-utilization — % da VRAM a usar (0.0-1.0)
--max-model-len — limitar contexto máximo
--served-model-name — alias para o modelo

Modelos Recomendados (HF IDs)

Qwen/Qwen2.5-Coder-32B-Instruct
mistralai/Devstral-Small-2505
ibm-granite/granite-3.3-8b-instruct
THUDM/glm-4-flash

🔐 Token HuggingFace (se necessário)

Alguns modelos exigem token de acesso ao HuggingFace:

export HF_TOKEN="hf_xxxxxxxxxxxxxxxxxxxx"
# Ou passe diretamente:
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --hf-token $HF_TOKEN ...

🔌 Conectando Claude Code ao vLLM

O processo é idêntico ao Ollama — basta mudar a URL e porta. vLLM usa porta 8000 por padrão. O mesmo mecanismo ANTHROPIC_BASE_URL funciona para qualquer servidor OpenAI-compatível.

🔌 Configuração Completa

# Passo 1: Iniciar o servidor vLLM (mantê-lo rodando)
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-Coder-32B-Instruct \
  --port 8000 \
  --gpu-memory-utilization 0.9 &

# Passo 2: Configurar variáveis para Claude Code
export ANTHROPIC_BASE_URL="http://localhost:8000"
export ANTHROPIC_AUTH_TOKEN="vllm-token"
export ANTHROPIC_API_KEY=""

# Passo 3: Iniciar Claude Code
claude --model Qwen/Qwen2.5-Coder-32B-Instruct

💡 Usar --served-model-name para Simplificar

Ao invés de usar o ID completo do HuggingFace no --model do Claude Code, defina um alias ao iniciar o servidor:

# Iniciar vLLM com alias
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-Coder-32B-Instruct \
  --served-model-name qwen-coder \
  --port 8000 ...

# Então no Claude Code usar o alias:
claude --model qwen-coder

Testar Conexão antes do Claude Code

curl http://localhost:8000/v1/models
# Deve retornar lista de modelos disponíveis

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer vllm-token" \
  -d '{"model": "qwen-coder", "messages": [{"role": "user", "content": "ping"}]}'

⚡ Performance e Otimizações

vLLM oferece diversas opções para maximizar performance no seu hardware específico. A principal alavanca é a quantização — permite rodar modelos maiores com mínima perda de qualidade.

🗜️ Quantização: AWQ e GPTQ

Quantização reduz o tamanho do modelo comprimindo os pesos. AWQ e GPTQ são os métodos mais populares para vLLM:

AWQ (Recommended)

Melhor qualidade por tamanho
Mais rápido que GPTQ em inferência
Requer modelo AWQ pré-quantizado do HF

GPTQ

Mais flexível, mais modelos disponíveis
Levemente mais lento que AWQ
Boa compatibilidade com hardware antigo

# Usar modelo AWQ
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-Coder-32B-Instruct-AWQ \
  --quantization awq \
  --port 8000

# Usar modelo GPTQ
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-Coder-7B-Instruct-GPTQ-Int4 \
  --quantization gptq \
  --port 8000

Parâmetros de Otimização Completos

python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-Coder-32B-Instruct-AWQ \
  --quantization awq \
  --port 8000 \
  --gpu-memory-utilization 0.90 \    # % da VRAM (0.85-0.95)
  --max-model-len 65536 \            # limitar contexto = menos RAM
  --max-num-seqs 32 \                # requisições simultâneas
  --enable-chunked-prefill \         # melhor latência de TTFT
  --tensor-parallel-size 2           # usar 2 GPUs (se disponível)

GPU Única (24GB)

--gpu-memory-utilization 0.90
--max-model-len 65536
--quantization awq

2x GPU (2x 24GB)

--tensor-parallel-size 2
--gpu-memory-utilization 0.85
--max-model-len 131072

A100/H100 (80GB)

--gpu-memory-utilization 0.90
--max-model-len 131072
--enable-prefix-caching

💡 Flash Attention 2 (Ganho Significativo)

Para GPUs NVIDIA Ampere ou mais recentes (RTX 30xx, 40xx, A100, H100), habilite Flash Attention 2 para ganho de 20-40% de velocidade:

pip install flash-attn --no-build-isolation
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-Coder-32B-Instruct-AWQ \
  --enable-chunked-prefill \
  --port 8000

vLLM detecta e usa Flash Attention automaticamente se instalado.

📋 Resumo do Módulo

✓

vLLM usa PagedAttention — até 50x mais throughput que Ollama em cenários multi-usuário

✓

Requer GPU NVIDIA + CUDA — para máxima performance; instalação mais complexa que Ollama

✓

Mesmo mecanismo de conexão — ANTHROPIC_BASE_URL="http://localhost:8000" (porta diferente do Ollama)

✓

AWQ é a melhor quantização — melhor qualidade/tamanho, mais rápido que GPTQ

✓

Flash Attention 2 dá ganho extra — 20-40% em GPUs Ampere+ com pip install flash-attn

Conclusão da Trilha 3:

Você domina as duas principais opções de LLM local: Ollama para uso pessoal fácil e vLLM para servidores com GPU de alta performance. Próxima trilha: OpenRouter para acessar dezenas de modelos via API unificada.

← Módulo Anterior Voltar à Trilha 3 T4: OpenRouter →