vLLM Docker: Arquitetura, Desempenho e Guia de Implementação na Nuvem

vLLM Docker: Arquitetura, Desempenho e Guia de Implementação na Nuvem

O Docker é a forma mais direta de colocar o vLLM atrás de um endpoint compatível com OpenAI em GPUs que você controla. No entanto, uma boa implementação de vLLM Docker não é apenas um comando docker run: ela exige um runtime de GPU compatível, um plano delimitado de memória e concorrência, autenticação na borda e uma maneira reproduzível de testar o desempenho antes da chegada do tráfego.

Este guia aborda a arquitetura, uma primeira implementação segura, os controles que realmente alteram a capacidade e o caminho de uma GPU para uma frota de GPUs na nuvem.

Use o vLLM Docker quando precisar de controle sobre os pesos do modelo, o local de implementação, as configurações de runtime ou uma carga de trabalho auto-hospedada constante. Se o custo operacional superar esse controle, uma API de modelo gerenciada ou um gateway unificado geralmente será o limite mais adequado.

O que o vLLM Docker oferece

O vLLM publica uma imagem Docker oficial vllm/vllm-openai que inicia um servidor compatível com OpenAI. Isso torna o vLLM Docker uma ponte útil entre um repositório de modelos e aplicações que já usam o formato de cliente da OpenAI: listagem de modelos, conclusões de chat, conclusões, embeddings e endpoints compatíveis relacionados dependem do modelo e da versão do servidor que você implementa. A documentação do Docker do vLLM contém os exemplos atuais de imagem e runtime.

A implicação prática é simples: sua aplicação não deve precisar de um cliente de servidor de modelo personalizado apenas porque você move uma carga de trabalho para sua própria GPU. Ela ainda precisa de um nome de modelo explícito, uma chave de API, um tempo limite e um comportamento de repetição que corresponda à sua própria meta de disponibilidade.

Como funciona a arquitetura do vLLM Docker

Em alto nível, o vLLM Docker tem cinco camadas:

1. Seu cliente envia uma solicitação autenticada para um endpoint compatível com OpenAI.
2. O servidor de API valida e tokeniza a solicitação e, em seguida, a encaminha ao mecanismo vLLM.
3. O agendador agrupa trabalhos compatíveis em lotes e os envia para um ou mais workers de GPU.
4. Os workers de GPU mantêm os pesos do modelo e o cache de chave-valor (KV) enquanto geram tokens.
5. A resposta é transmitida de volta pelo servidor de API ao cliente.

A ideia central de desempenho é o PagedAttention. Em vez de reservar uma grande região contígua de cache KV para o comprimento máximo possível de uma solicitação, o vLLM gerencia o estado KV em blocos. Isso facilita acomodar cargas de trabalho de comprimento variável na memória disponível e permite que solicitações concluídas liberem blocos para trabalhos posteriores. O artigo original sobre PagedAttention descreve o agendador, os workers de GPU, os blocos KV lógicos para físicos e a relação entre utilização de cache e processamento em lote.

Essa arquitetura tem uma consequência operacional importante: a VRAM não é apenas o “tamanho do modelo”. Ela é compartilhada entre os pesos do modelo, a sobrecarga de runtime, as ativações e um cache KV cuja demanda cresce com o comprimento do contexto e as solicitações simultâneas. Trate contexto, concorrência e utilização de memória como uma única decisão — não como três tarefas de ajuste separadas.

Antes de executar o vLLM Docker em uma GPU na nuvem

Comece com quatro verificações:

1. Escolha uma tag de imagem testada. Em produção, fixe uma tag de versão do vLLM em vez de seguir cegamente o latest. Leia a documentação correspondente a essa tag antes de depender de uma flag ou padrão.
2. Use um modelo que você tenha permissão para baixar e servir. Alguns repositórios exigem um token do Hugging Face ou a aceitação de uma licença de modelo. Fixe a revisão do modelo após validá-la.
3. Verifique o acesso à GPU fora do contêiner do modelo. Instale o driver NVIDIA no host e o NVIDIA Container Toolkit e, em seguida, valide um contêiner habilitado para GPU com nvidia-smi. O guia de instalação da NVIDIA aborda os pré-requisitos no host e a configuração do runtime.
4. Mantenha a porta privada inicialmente. Vincule ao loopback para uma prova de conceito em um único host ou mantenha o serviço em uma sub-rede privada, atrás de TLS, autenticação e um proxy reverso/balanceador de carga. Não trate o servidor de modelo sem proteção como um limite de segurança voltado para a internet.

Use o comando de exemplo da NVIDIA antes de depurar o próprio vLLM:

docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

Se esse comando não conseguir ver a GPU esperada, pare por aí. Um log do servidor de modelo não corrigirá um driver ausente, um runtime de contêiner não configurado ou uma GPU que nunca foi atribuída à VM na nuvem.

Execute um servidor vLLM Docker de GPU única

O seguinte é um ponto de partida deliberadamente pequeno. Ele espelha o padrão da imagem oficial, mas adiciona uma chave de API e vincula a porta publicada ao loopback. Substitua os marcadores de posição por um modelo e uma tag de imagem que você tenha testado.

export HF_TOKEN="your_hugging_face_token"
export VLLM_API_KEY="replace-with-a-long-random-secret"
export VLLM_IMAGE="vllm/vllm-openai:<tested-version>"
export MODEL="Qwen/Qwen3-0.6B"

docker run -d \
  --name vllm-api \
  --restart unless-stopped \
  --runtime=nvidia \
  --gpus all \
  --ipc=host \
  -p 127.0.0.1:8000:8000 \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -e HF_TOKEN \
  -e VLLM_API_KEY \
  "$VLLM_IMAGE" \
  --model "$MODEL" \
  --dtype auto \
  --api-key "$VLLM_API_KEY"

A configuração de memória compartilhada e a montagem do cache do Hugging Face seguem o exemplo oficial do vLLM Docker. A montagem do cache evita baixar novamente os mesmos pesos do modelo quando o contêiner é recriado. A chave de API é um controle da aplicação, não um substituto para isolamento de rede, TLS, limites de taxa ou um gerenciador de segredos.

Verifique se o servidor está servindo o modelo esperado antes de conectar uma aplicação:

curl --fail --silent --show-error \
  http://127.0.0.1:8000/v1/models \
  -H "Authorization: Bearer $VLLM_API_KEY"

Em seguida, envie uma pequena solicitação com o mesmo identificador de modelo retornado por /v1/models:

curl --fail --silent --show-error \
  http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer $VLLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-0.6B",
    "messages": [{"role": "user", "content": "Reply with the word ready."}],
    "max_tokens": 16
  }'

Se o seu modelo não incluir um modelo de chat utilizável, as solicitações de conclusão de chat poderão falhar mesmo que o contêiner tenha sido iniciado. O vLLM documenta como fornecer --chat-template para modelos cuja configuração de tokenizador não tenha um; teste isso antes da implantação de uma aplicação. Consulte as orientações sobre modelos de chat.

Defina o envelope de desempenho antes de alterar as flags

Não existe um comando vLLM Docker universalmente correto. A configuração adequada depende da arquitetura do modelo, do tipo e da memória da GPU, da distribuição dos comprimentos de entrada/saída, da simultaneidade e do objetivo de latência. Estabeleça uma linha de base com uma carga de trabalho representativa e, em seguida, altere uma variável por vez.

Registre pelo menos estas medições:

• Taxa de sucesso/erro das solicitações e eventos de reinicialização/OOM.
• Tempo até o primeiro token (TTFT) e tempo por token de saída (TPOT), segmentados pelo comprimento do prompt.
• Latência de ponta a ponta em p50 e p95/p99 sob a simultaneidade esperada.
• Tokens de entrada, tokens de saída, tempo na fila, solicitações ativas e uso de memória da GPU.
• Vazão somente junto à meta de latência e qualidade que ela atendeu.

As flags do vLLM Docker que alteram materialmente a capacidade

Os padrões e o comportamento exatos das opções são sensíveis à versão. A atual referência de argumentos do mecanismo do vLLM define os controles de agendador, cache, paralelismo e fila; sua referência de configuração de cache explica as configurações de utilização de memória e cache de prefixos.

Uma ordem prática de ajuste

1. Defina um --max-model-len realista com base nos limites da aplicação.
2. Comece de forma conservadora com a utilização de memória e deixe margem para a sobrecarga do driver/runtime.
3. Faça testes de carga de --max-num-seqs e --max-num-batched-tokens com comprimentos reais de prompts e conclusões.
4. Adicione paralelismo de tensor somente quando uma GPU não conseguir acomodar o modelo ou atender ao objetivo para ele.
5. Adicione réplicas atrás de um balanceador de carga quando as necessidades de disponibilidade ou de tráfego agregado exigirem domínios de falha independentes.

Essa sequência evita um erro comum: adicionar GPUs ou aumentar a concorrência antes de saber se a carga de trabalho é realmente limitada por contexto, fila, memória ou computação.

Escale o vLLM Docker em várias GPUs

Para um modelo que precisa de várias GPUs, o vLLM oferece suporte à disponibilização com paralelismo de tensor e de pipeline. Em um único host, exponha as GPUs ao contêiner e defina o tamanho do paralelismo de tensor como o número de GPUs que você atribui deliberadamente a esse servidor de modelo:

docker run -d \
  --name vllm-tp \
  --restart unless-stopped \
  --runtime=nvidia \
  --gpus all \
  --ipc=host \
  -p 127.0.0.1:8000:8000 \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -e HF_TOKEN \
  -e VLLM_API_KEY \
  "$VLLM_IMAGE" \
  --model "$MODEL" \
  --tensor-parallel-size 4 \
  --api-key "$VLLM_API_KEY"

O guia de paralelismo e escalabilidade do vLLM documenta paralelismo de tensor, paralelismo de pipeline e as opções de execução em nó único versus vários nós. Não copie 4 do exemplo para um nó com duas GPUs: ajuste o sinalizador às GPUs alocadas a este servidor e valide a topologia de comunicação, o equilíbrio de memória e o comportamento em caso de falha.

Para detalhes de implementação, verificações de topologia e uma decisão entre paralelismo de tensor e de pipeline, consulte o guia de inferência vLLM com várias GPUs da Flatkey. Para uma decisão sobre o runtime de serving, e não sobre a implementação com Docker, consulte vLLM vs. SGLang.

Uma arquitetura de implementação em nuvem para produção

Uma implementação de produção do vLLM Docker normalmente separa a borda pública da execução em GPU:

Coloque o cache do Hugging Face em armazenamento durável ou intencionalmente pré-aquecido, para que uma reinicialização comum não resulte em um download inesperado do modelo. Mantenha a licença e os controles de acesso do modelo no registro da sua implementação. Fixar apenas a tag da imagem não é suficiente se o repositório do modelo apontar para uma ramificação em constante mudança.

Para contexto sobre seleção de GPU, planejamento de memória orientado por contexto e quando a infraestrutura em nuvem é a escolha certa, vincule este runbook ao guia de requisitos de memória de GPU para LLMs, ao guia de nuvem de GPU e ao framework de nuvem de GPU vs. API de modelo da Flatkey.

Solução de problemas do vLLM Docker sem suposições

Quando o servidor está em execução, mas o comportamento da aplicação ainda difere de uma API hospedada, confirme explicitamente a compatibilidade de endpoints e parâmetros. O guia de servidor de inferência compatível com OpenAI da Flatkey aborda a migração do lado do cliente e a superfície de testes de compatibilidade.

Quando não operar o vLLM Docker por conta própria

Hospedar por conta própria é um compromisso de infraestrutura. Você é responsável pelas atualizações de imagem, procedência do modelo, capacidade de GPU, falhas de nós, controle de acesso, validação de latência e pelo processo de plantão. Essa pode ser a escolha certa quando o controle do tempo de execução é um requisito.

Para cargas de trabalho em que a escolha do modelo, a disponibilidade do provedor ou a simplicidade operacional importam mais do que o controle direto da GPU, mantenha um caminho de API gerenciada na arquitetura. A Flatkey foi projetada para o fluxo de trabalho complementar: uma única integração compatível com OpenAI para acessar modelos entre provedores com faturamento centralizado, enquanto um endpoint vLLM hospedado por conta própria continua sendo uma opção para as cargas de trabalho que realmente precisam dele.

O próximo passo certo não é maximizar um benchmark isoladamente. Antes de colocar o vLLM Docker atrás do tráfego de produção, fixe a imagem e o modelo, comprove o runtime de GPU, defina uma política explícita de contexto e fila, teste com solicitações semelhantes às de produção e documente o caminho de falha.

Perguntas frequentes

O vLLM Docker é o mesmo que uma API de LLM gerenciada?

Não. O vLLM Docker fornece um runtime de serviço de modelos em GPUs que você opera. Uma API gerenciada abstrai a hospedagem de modelos e as operações de GPU. Ambos podem expor uma interface de cliente compatível com OpenAI, mas a responsabilidade operacional é diferente.

O vLLM Docker precisa do NVIDIA Container Toolkit?

Para contêineres com GPU NVIDIA, o host precisa de um driver NVIDIA compatível e de um runtime de contêiner de GPU configurado. O NVIDIA Container Toolkit é o caminho padrão documentado pela NVIDIA para disponibilizar GPUs aos contêineres Docker.

Qual flag do vLLM Docker devo ajustar primeiro?

Defina primeiro um comprimento máximo de contexto realista e, em seguida, teste a utilização de memória, a concorrência e os limites de tokens por lote com uma combinação representativa de solicitações. Alterar flags sem uma linha de base da carga de trabalho geralmente produz resultados não reproduzíveis.

O vLLM Docker pode executar um modelo em várias GPUs?

Sim. O vLLM oferece suporte a serviço com paralelismo de tensor e paralelismo de pipeline. Comece com um único host e valide a contagem exata de GPUs, a topologia e o comportamento de comunicação antes de expandir o projeto.

Fontes e leituras adicionais

• vLLM: Usando Docker
• vLLM: Paralelismo e escalabilidade
• vLLM: Argumentos do mecanismo
• Guia de instalação do NVIDIA Container Toolkit
• Gerenciamento eficiente de memória para servir grandes modelos de linguagem com PagedAttention