vLLM com Docker: Execute um servidor de inferência acelerado por GPU em minutos

vLLM publica uma imagem Docker oficial, vllm/vllm-openai, que traz um servidor de inferência compatível com OpenAI pronto para usar. O caminho mais rápido: instale o NVIDIA Container Toolkit no host, depois execute a imagem com --gpus all e um ID de modelo do Hugging Face. Após o modelo ser baixado, o servidor fica ativo na porta 8000 e aceita as mesmas requisições da API OpenAI.

Pré-requisitos

• Docker Engine 20.10+ — O Docker Desktop no Windows e macOS funciona através do backend WSL2.
• GPU NVIDIA com um driver que suporte CUDA 12.x. Execute nvidia-smi para confirmar; a «CUDA Version» exibida é a máxima que seu driver suporta.
• NVIDIA Container Toolkit — a ponte que permite ao Docker ver a GPU. Veja a próxima seção.
• VRAM suficiente para seu modelo alvo. Use calculadora de VRAM para verificar antes de se comprometer com um download de modelo.

Instalando o NVIDIA Container Toolkit

Pule esta seção se docker run --gpus all nvidia/cuda:12.0-base nvidia-smi já funciona em sua máquina.

Linux (Ubuntu/Debian):

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | 
  sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | 
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | 
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

RHEL/CentOS: Substitua o deb URL do repositório pela rpm equivalente da documentação NVIDIA e use dnf no lugar de apt-get.

Windows (WSL2): Instale o driver NVIDIA para Windows no host — nenhuma instalação separada de container toolkit é necessária dentro do WSL2. O Docker Desktop cuida do passthrough automaticamente.

macOS: GPUs NVIDIA não são suportadas no macOS. vLLM não é executado no Apple Silicon via Docker com aceleração por GPU. Para inferência local em hardware Apple, considere uma compilação somente para CPU ou um runtime diferente.

O Comando de Execução Mínimo

docker run --runtime nvidia --gpus all 
  --ipc=host 
  -v ~/.cache/huggingface:/root/.cache/huggingface 
  -p 8000:8000 
  vllm/vllm-openai:latest 
  --model meta-llama/Meta-Llama-3-8B-Instruct

Sinalizar	Por que isso importa
--runtime nvidia	Roteia chamadas de GPU através do runtime container NVIDIA.
--gpus all	Expõe todas as GPUs do host. Use "device=0,1" para segmentar GPUs específicas.
--ipc=host	Compartilha o namespace IPC do host. Necessário para memória compartilhada do PyTorch; omiti-lo causa Bus error ou falha de memória compartilhada.
-v ~/.cache/huggingface:…	Monta o cache HF do host para que os pesos persistam após reinicializações do container.
-p 8000:8000	Expõe o servidor compatível com OpenAI no host.
--model	Qualquer ID de modelo do Hugging Face ou um caminho local montado no contêiner.

Para fazer pull de um modelo gated (Llama 3, Mistral, etc.), também passe -e HUGGING_FACE_HUB_TOKEN=hf_yourtoken. Armazene o token em um .env arquivo e passe-o com --env-file .env em vez de inseri-lo no histórico do shell.

Montando o Cache do Hugging Face

vLLM baixa os pesos do modelo para /root/.cache/huggingface dentro do contêiner. Sem uma montagem de volume, cada docker run faz o download completo do modelo — frequentemente 5–80 GB. A linha de montagem é:

-v ~/.cache/huggingface:/root/.cache/huggingface

Se seus modelos residem em um local não padrão, defina -e HF_HOME=/your/path e monte esse caminho em vez disso. Para ambientes isolados, baixe o modelo com huggingface-cli download primeiro, depois passe --model /path/in/container juntamente com uma montagem de volume do diretório de pesos.

Flags Importantes do Servidor vLLM

Essas flags são passadas após o nome da imagem — são argumentos para o processo do servidor vLLM, não para o Docker.

Sinalizar	Padrão	Quando alterar
--tensor-parallel-size N	1	Defina como o número de GPUs para serving multi-GPU. Os cabeçalhos de atenção do modelo devem ser divisíveis por N. Combine com --gpus "device=0,1,..." listando exatamente N dispositivos.
--gpu-memory-utilization 0.X	0.90	Reduza para 0.75–0.80 se observar erros de OOM ou compartilhar a GPU com outros processos.
--max-model-len N	Configuração do modelo	Limita o tamanho do cache KV. Útil quando o contexto padrão de um modelo (por ex. 128 k) esgotaria a VRAM. Tente --max-model-len 8192 como uma primeira redução.
--dtype auto	automático	Substitua por bfloat16 ou float16 se a detecção automática escolher uma precisão inesperada.
--quantization awq / gptq	none	Ative para variantes de modelo pré-quantizados. Reduz aproximadamente pela metade a VRAM com alguma perda de qualidade.
--port	8000	Mude se 8000 já estiver ocupada no host.

Não tem certeza se sua GPU tem VRAM suficiente para um modelo específico? O guia de requisitos de VRAM lista modelos comuns, e o calculadora de VRAM permite que você insira quantização e tamanho de lote. Para decisões de compra de hardware, consulte o guia de recomendações de GPU.

Expondo e Testando o Endpoint Compatível com OpenAI

Quando o contêiner exibe INFO: Application startup complete, a API está ativa.

# Listar modelos carregados
curl http://localhost:8000/v1/models

# Conclusão de texto
curl http://localhost:8000/v1/completions 
  -H "Content-Type: application/json" 
  -d '{"model": "meta-llama/Meta-Llama-3-8B-Instruct", "prompt": "A capital da França é", "max_tokens": 20}'

# Conclusão de chat
curl http://localhost:8000/v1/chat/completions 
  -H "Content-Type: application/json" 
  -d '{"model": "meta-llama/Meta-Llama-3-8B-Instruct", "messages": [{"role": "user", "content": "Olá"}]}'

Qualquer cliente compatível com OpenAI — o openai SDK Python, LangChain, LlamaIndex — funciona configurando base_url="http://localhost:8000/v1" e fornecendo qualquer string não vazia como api_key.

Exemplo com Docker Compose

Para implantações persistentes, um arquivo Compose é mais fácil de gerenciar do que um longo docker run comando:

services:
  vllm:
    image: vllm/vllm-openai:latest
    runtime: nvidia
    environment:
      - HUGGING_FACE_HUB_TOKEN=${HF_TOKEN}
    volumes:
      - ~/.cache/huggingface:/root/.cache/huggingface
    ports:
      - "8000:8000"
    ipc: host
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    command: >
      --model meta-llama/Meta-Llama-3-8B-Instruct
      --gpu-memory-utilization 0.90
      --max-model-len 8192

Comece com docker compose up -d. O bloco deploy.resources é o equivalente do Docker Compose v3 para --gpus all.

Falhas Comuns e Correções

Erro	Causa	Corrigir
Bus error ou /dev/shm muito pequeno	O valor padrão do Docker para /dev/shm é 64 MB — insuficiente para o PyTorch.	Adicione --ipc=host --ipc=host --shm-size=8g se você não puder compartilhar o namespace IPC do host.
Erro CUDA: nenhuma imagem de kernel disponível	A versão do CUDA compilada na imagem vLLM excede a suportada pelo seu driver.	Executar nvidia-smi para descobrir sua versão máxima suportada do CUDA e, em seguida, use uma tag de imagem versionada correspondente (por exemplo, vllm/vllm-openai:v0.5.5).
torch.cuda.OutOfMemoryError	Os pesos do modelo mais o cache KV excedem a VRAM disponível.	Tente --max-model-len 4096 primeiro. Em seguida, reduza --gpu-memory-utilization para 0,80. Se ainda ocorrer erro de memória insuficiente (OOM), use uma variante quantizada ou uma GPU maior.
permissão negada no diretório de cache	O contêiner é executado como root; o diretório no host pertence a outro usuário.	Executar chmod -R a+rw ~/.cache/huggingface no host ou use um volume nomeado do Docker em vez de um bind mount.
O contêiner inicia, mas curl retorna 'connection refused'	O modelo ainda está sendo carregado ou -p 8000:8000 está ausente.	Aguarde a linha de log Application startup complete . Verifique se o mapeamento de porta está presente no seu comando de execução.

Perguntas frequentes

Qual tag da imagem Docker vLLM devo usar?

vllm/vllm-openai:latest a tag 'latest' acompanha a versão mais recente e é adequada para experimentação. Para produção, fixe uma tag de versão específica (por exemplo, v0.6.0) para garantir a reprodutibilidade das compilações. Cada tag de lançamento no Docker Hub indica a versão do CUDA contra a qual foi compilada, que deve ser menor ou igual à versão suportada pelo seu driver.

Posso executar o vLLM em Docker sem GPU?

A imagem padrão exige uma GPU NVIDIA. A inferência somente em CPU é possível compilando o vLLM a partir do código-fonte com VLLM_TARGET_DEVICE=cpu, but throughput is orders of magnitude slower and not practical for serving. For CPU-only local inference, llama.cpp or Ollama are more suitable alternatives — see the Guia do Ollama para comparação.

Como executar um modelo restrito que exige um token do Hugging Face?

Passe o token como uma variável de ambiente: -e HUGGING_FACE_HUB_TOKEN=hf_yourtoken. Armazene-o em um arquivo .env e faça referência a ele com --env-file .env para evitar vazamentos no histórico do shell. O servidor usa esse token durante o download inicial do modelo; ele não é necessário após os pesos serem armazenados em cache localmente.

O que faz a opção –tensor-parallel-size e quando devo usá-la?

A paralelização tensorial fragmenta as matrizes de pesos do modelo entre múltiplas GPUs, permitindo executar modelos maiores do que cabem em uma única placa. Defina-a como o número de GPUs que deseja utilizar (2 ou 4 são valores comuns). Esse número deve corresponder à quantidade de GPUs especificada na opção --gpus, e o número de cabeças de atenção do modelo deve ser divisível por esse valor.

Executar o vLLM em Docker é economicamente vantajoso comparado a uma API gerenciada?

Isso depende inteiramente do volume de solicitações. Hospedar você mesmo envolve custos fixos elevados (instância ou hardware com GPU), mas custo marginal quase nulo por solicitação. APIs gerenciadas não têm custo fixo, mas cobram por token. Use a calculadora de self-hosting vs API para identificar seu ponto de equilíbrio antes de investir em infraestrutura.

Como servir vários modelos simultaneamente?

Execute um contêiner por modelo, cada um mapeado para uma porta diferente no host (por exemplo, 8000, 8001). Atualmente, o vLLM não suporta o atendimento simultâneo de múltiplos modelos a partir de um único processo. Posicione um proxy reverso, como nginx ou Caddy, na frente dos contêineres para rotear as solicitações conforme o nome do modelo para a porta correta.