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

O vLLM publica uma imagem oficial do Docker, vllm/vllm-openai, que inclui um servidor de inferência compatível com OpenAI pronto para uso. O caminho mais rápido: instale o NVIDIA Container Toolkit no host e execute a imagem com --gpus all e um ID de modelo do Hugging Face. Assim que o modelo for baixado, o servidor ficará ativo na porta 8000 e aceitará as mesmas solicitações da API OpenAI.

Pré-requisitos

• Docker Engine 20.10 ou superior — O Docker Desktop no Windows e no macOS funciona por meio do backend WSL2.
• GPU NVIDIA com um driver que suporte CUDA 12.x. Execute nvidia-smi para confirmar; a versão de CUDA exibida é a versão máxima suportada pelo seu driver.
• NVIDIA Container Toolkit — a ponte que permite ao Docker acessar a GPU. Consulte a próxima seção.
• Memória VRAM suficiente para o seu modelo-alvo. Use o Calculadora de VRAM para verificar antes de baixar o modelo.

Instalando o NVIDIA Container Toolkit

Pule esta seção se docker run --gpus all nvidia/cuda:12.0-base nvidia-smi já funcionar 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 a URL do repositório deb pela equivalente rpm da documentação da NVIDIA e use dnf no lugar de apt-get.

Windows (WSL2): Instale o driver NVIDIA para Windows no host — nenhuma instalação adicional do toolkit de contêineres é necessária dentro do WSL2. O Docker Desktop gerencia automaticamente a passagem (passthrough) da GPU.

macOS: GPUs NVIDIA não são suportadas no macOS. O vLLM não executa em hardware Apple Silicon via Docker com aceleração por GPU. Para inferência local em dispositivos Apple, considere uma compilação somente para CPU ou outro ambiente de execução.

Comando mínimo de execução

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

Para baixar um modelo protegido por acesso restrito (como Llama 3, Mistral etc.), também passe -e HUGGING_FACE_HUB_TOKEN=hf_seutoken. Armazene o token em um arquivo .env e passe-o com --env-file .env em vez de inseri-lo diretamente no histórico do seu shell.

Montando o cache do Hugging Face

O vLLM baixa os pesos dos modelos para /root/.cache/huggingface dentro do contêiner. Sem uma montagem de volume, cada comando docker run rebaixa integralmente o modelo — frequentemente entre 5 e 80 GB. A linha de montagem é:

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

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

Principais flags 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.

Não tem certeza se sua GPU possui VRAM suficiente para um determinado modelo? A Guia de requisitos de VRAM lista modelos comuns 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

Assim que o contêiner exibir INFO: Application startup complete, a API estará 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 SDK em Python, LangChain, LlamaIndex — funciona definindo-se openai base_url="http://localhost:8000/v1" e fornecendo qualquer string não vazia como a Para implantações persistentes, um arquivo Compose é mais fácil de gerenciar do que um comando longo api_key.

Exemplo com Docker Compose

docker run docker run completo:

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 soluções

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, mas o throughput é várias ordens de grandeza menor e não é viável para serviços. Para inferência local somente em CPU, alternativas mais adequadas são o llama.cpp ou o Ollama — consulte a 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_seutoken. 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 autohospedagem versus 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.