Implantar o vLLM em production

#O que faz o vLLM e o que exige

vLLM é um motor de inferência open source criado no laboratório Sky Computing da UC Berkeley. Sua ideia central, PagedAttention, gerencia o cache chave-valor da atenção por páginas, como a memória virtual de um sistema operacional. Segundo o anúncio inicial do projeto em 2023, os sistemas existentes desperdiçavam uma grande parte de sua memória, e o vLLM atingia até 24 vezes a taxa de processamento do Hugging Face Transformers e até 3,5 vezes a do TGI em testes da época. Esses números são antigos e específicos daquele ambiente de testes: indicam uma direção, não o que você obterá com seu modelo e sua placa.

Quanto aos pré-requisitos, a documentação atual exige Linux e Python de 3.10 a 3.13; no Mac, existe uma opção separada, vLLM-Metal, que se baseia em MLX. O servidor expõe uma API compatível com a API da OpenAI, escuta por padrão na porta 8000 e serve apenas um modelo de cada vez: para vários modelos, são necessárias várias instâncias.

#Quando escolher vLLM em vez de Ollama

A diferença não está na capacidade de processar requisições em paralelo, que também é oferecida por Ollama, mas na forma como a memória é compartilhada. De acordo com a FAQ de Ollama, o processamento paralelo de um modelo multiplica o tamanho do contexto pelo número de requisições: um contexto de 2.000 tokens com 4 requisições em paralelo torna-se um contexto de 8.000 tokens na memória, reservado antecipadamente. O vLLM aloca seu cache em blocos, conforme demanda, e agrupa as requisições em andamento nos mesmos cálculos.

Regra prática: se menos de três pessoas usam o modelo ao mesmo tempo, ou se você quer trocar de modelo com frequência, Ollama é suficiente. Acima disso, ou com um único modelo servido continuamente, vLLM justifica sua complexidade. O guia comparativo detalha a escolha.

#Quando vLLM é uma má escolha

O vLLM não traz nenhum benefício para um único usuário em uma GPU de 8 a 12 GB: falta memória para um cache compartilhado, e é mais simples iniciar o Ollama ou o llama.cpp. Ele não é muito adequado se você alterna entre cinco modelos ao longo do dia, pois é necessário reiniciar uma instância para cada modelo. Em um Mac, o caminho é diferente e se baseia no MLX. Por fim, se você precisa de uma interface de chat para a equipe em vez de uma API sob alta carga, uma pilha com Ollama e Open WebUI atende melhor e exige menos trabalho operacional.

• Ollama ou vLLM em produção: o comparativo
• vLLM: o que é, para quem, quando usá-lo

#Dimensionar a memória: o cálculo a ser feito antes de tudo

Um servidor vLLM é dimensionado com base no cache de chave-valor, não nos pesos. Após carregar o modelo, o vLLM reserva uma fração da memória do GPU, 92% por padrão de acordo com o código de configuração atual, e dedica o restante ao cache. Esse restante determina quantos tokens de conversa podem coexistir, ou seja, quantos usuários simultâneos você pode atender.

Vamos tomar o Qwen2.5-7B-Instruct, cuja ficha indica 7,61 bilhões de parâmetros, 28 camadas e 4 cabeças chave-valor (atenção agrupada). O peso em 16 bits é de aproximadamente 15,2 GB. O cache de um token equivale a 2 (chaves e valores) × 28 camadas × 4 cabeças × 128 dimensões × 2 bytes, ou seja, 57.344 bytes, cerca de 56 KiB.

Esses limites são altos: os buffers de cálculo e os grafos CUDA consomem parte da memória restante, e o modelo pode ter outro perfil. O método continua válido para qualquer modelo: consulte o número de camadas e de cabeças de chave-valor na ficha do modelo, calcule o custo por token e divida a memória restante por esse custo. Se os logs indicarem preempções, a documentação recomenda aumentar gpu_memory_utilization ou reduzir max_num_seqs.

Duas medidas ampliam o cache sem trocar de placa: carregar uma versão quantizada do modelo, que libera parte do espaço ocupado pelos pesos, ou limitar --max-model-len, o que evita reservar espaço para contextos que ninguém utiliza. A primeira medida pode custar um pouco de qualidade; a segunda não custa nada desde que suas requisições permaneçam curtas.

#1. Instalação

uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto

A documentação recomenda uv, que escolhe automaticamente a versão certa do PyTorch de acordo com seu driver CUDA. Para GPUs AMD, a instalação passa por um índice dedicado; para Intel, TPU ou Ascend, existem plugins. Em produção, a imagem Docker evita conflitos de versões CUDA e é atualizada com uma simples troca de tag.

#2. Iniciar o servidor

vllm serve Qwen/Qwen2.5-7B-Instruct \
  --host 0.0.0.0 \
  --port 8000 \
  --gpu-memory-utilization 0.90 \
  --max-model-len 8192 \
  --api-key "$VLLM_API_KEY"

O comando vllm serve substitui a antiga invocação python -m vllm.entrypoints.openai.api_server, que a documentação atual já não utiliza. Na primeira execução, os pesos são baixados do Hugging Face: reserve espaço em disco (cerca de 15 GB para um modelo 7B em 16 bits). O servidor aplica por padrão o arquivo generation_config.json do repositório do modelo e, portanto, os parâmetros de amostragem recomendados por quem o publica; --generation-config vllm restaura os valores padrão do vLLM.

curl http://localhost:8000/v1/models \
  -H "Authorization: Bearer $VLLM_API_KEY"

#3. Docker e systemd

A imagem oficial vllm/vllm-openai é a maneira mais segura. Monte o cache do Hugging Face para não baixar os pesos novamente e um volume para o cache de compilação: caso contrário, cada novo contêiner inicia com um cache vazio e recompila os artefatos do seu modelo. Observe que a imagem é executada como root por padrão; a documentação descreve uma execução com um usuário não privilegiado (--user 2000:0).

docker run --rm --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -v vllm-cache:/root/.cache/vllm \
  -p 8000:8000 \
  --ipc=host \
  -e VLLM_API_KEY=$VLLM_API_KEY \
  vllm/vllm-openai:latest \
  Qwen/Qwen2.5-7B-Instruct

[Unit]
Description=vLLM OpenAI API
After=network.target

[Service]
Type=simple
User=vllm
EnvironmentFile=/etc/vllm/env
ExecStart=/opt/vllm/bin/vllm serve Qwen/Qwen2.5-7B-Instruct --port 8000
Restart=always

[Install]
WantedBy=multi-user.target

#4. Os parâmetros que importam

Um princípio da documentação: se o modelo cabe em uma única GPU, a distribuição provavelmente é inútil; se não cabe, mas cabe em um nó, utiliza-se o paralelismo tensorial com --tensor-parallel-size. Os modelos já quantizados são carregados diretamente do Hub, sem nenhuma opção específica: a opção --quantization serve apenas para a quantização dinâmica.

• Quantizar o cache KV: economizar VRAM
• Flash Attention: ativar no llama.cpp, Ollama, vLLM

#5. Medir a taxa de processamento corretamente

O comando vllm bench serve envia requisições ao servidor e informa a taxa de processamento, o tempo até o primeiro token (TTFT) e a latência entre tokens. A documentação esclarece que esses benchmarks servem principalmente para avaliar funcionalidades e detectar regressões, e recomenda o GuideLLM para testar um servidor de produção.

vllm bench serve \
  --backend vllm \
  --model Qwen/Qwen2.5-7B-Instruct \
  --endpoint /v1/completions \
  --dataset-name sharegpt \
  --dataset-path CHEMIN/ShareGPT_V3_unfiltered_cleaned_split.json \
  --num-prompts 200

#Implantação e operação

Após o dimensionamento, a implantação segue sempre a mesma sequência. Ela se aplica a uma equipe de cerca de vinte pessoas consultando o mesmo modelo de 7 a 8 bilhões de parâmetros em uma placa de 24 ou 48 GB.

1. 01
   Escolher o modelo e o formato

   Um único modelo por instância. Prefira um repositório já quantizado ou em 16 bits, de acordo com a memória disponível.
2. 02
   Calcular o cache

   Aplique o cálculo por token da seção de dimensionamento para definir --max-model-len e --max-num-seqs.
3. 03
   Iniciar no Docker

   Use a imagem oficial com o cache do Hugging Face montado e uma tag de versão fixa em vez de latest, para evitar que uma atualização mude o comportamento.
4. 04
   Adicionar o proxy

   Reverse proxy com lista branca de rotas, TLS e limitação de taxa, seguido pela chave da API como complemento.
5. 05
   Medir

   Inicie um teste de carga com vllm bench serve variando a semente e anote o TTFT e a taxa de transferência total.
6. 06
   Monitorar

   Integre a coleta de métricas do endpoint /metrics à sua ferramenta de monitoramento.

Os sinais a monitorar são os que indicam falta de cache: preempções nos logs, TTFT que aumenta, filas que se alongam. A documentação indica que a preempção, cujo modo padrão é o recálculo, protege o serviço, mas degrada a latência de ponta a ponta. Se ela se tornar frequente, aumente gpu_memory_utilization, reduza o contexto ou limite o número de requisições simultâneas. Como último recurso, adicione um GPU e distribua o modelo com paralelismo tensorial.

#6. Segurança e exposição: --api-key não é suficiente

Ao contrário do que muitas vezes se lê, o vLLM sabe verificar uma chave de API, com --api-key ou a variável VLLM_API_KEY. Mas a documentação de segurança reforça: a chave protege apenas as rotas sob /v1, /v2, /inference e /cohere. Outras rotas permanecem sem autenticação, como rotas de inferência fora de /v1, rotas de controle como /pause ou /abort_requests, e /health. Portanto, nunca conte apenas com --api-key.

Reverse proxy

Coloque nginx, Envoy ou um gateway Kubernetes à frente do vLLM, com uma lista de permissões contendo apenas as rotas a serem expostas, e bloqueie todas as outras.

Rede

Uma VPN ou uma rede isolada: a comunicação entre os nós de uma implantação distribuída não é protegida por padrão.

Modo de desenvolvimento

Nunca ative VLLM_SERVER_DEV_MODE=1 em produção: ele expõe rotas perigosas.

Limites

Aplique a limitação de taxa e a validação das requisições no nível do proxy, conforme recomendado na documentação.

Registros

Registre quem envia o quê, para depuração e auditoria.

• Proteger um servidor de IA local: autenticação, proxy reverso, exposição

• Fonte: início rápido com vLLM
• Fonte: segurança do vLLM
• Fonte: vLLM com Docker
• Fonte: anúncio do vLLM e PagedAttention