vLLM Quickstart: Servir LLMs de Alto Desempenho - em 2026

O vLLM é um motor de inferência e entrega (serving) de alta vazão e alta eficiência de memória para Modelos de Linguagem de Grande Escala (LLMs), desenvolvido pelo Sky Computing Lab da UC Berkeley.

Seu algoritmo PagedAttention trata o cache de KV (chaves e valores) como páginas de memória virtual de um sistema operacional e o combina com lotes contínuos (continuous batching) — a combinação que tornou o vLLM o motor padrão para a entrega de LLMs em produção. Para entender como o vLLM se encaixa entre o Ollama, Docker Model Runner, LocalAI e provedores de nuvem — incluindo compensações de custo e infraestrutura —, veja Hospedagem de LLM: Comparação de Infraestrutura Local, Self-Hosted e Nuvem.

Este guia está atualizado até a versão vLLM v0.31.0 (outubro de 2026). Duas coisas mudaram recentemente, caso você esteja chegando a partir de tutoriais mais antigos: o comando python -m vllm.entrypoints.openai.api_server foi descontinuado e exibe um aviso — o vllm serve é agora o CLI padrão — e as rodas pré-construídas (wheels) visam a CUDA 12.9 por padrão, em vez de 11.8.

O que é o vLLM?

O vLLM (LLM virtual) é uma biblioteca de código aberto para inferência e entrega rápida de LLMs que rapidamente se tornou o padrão da indústria para implantações em produção. Lançado em 2023, ele introduziu o PagedAttention, uma técnica inovadora de gerenciamento de memória que melhora drasticamente a eficiência de entrega.

Principais Funcionalidades

Desempenho de Alta Vazão: Os benchmarks da época do lançamento do vLLM relataram uma vazão 14 a 24 vezes maior que o HuggingFace Transformers no mesmo hardware, e o motor manteve essa liderança por meio de lotes contínuos, kernels CUDA otimizados e o algoritmo PagedAttention, que elimina a fragmentação de memória.

Compatibilidade com a API da OpenAI: O vLLM inclui um servidor de API embutido totalmente compatível com o formato da OpenAI. Isso permite uma migração sem emendas da OpenAI para infraestrutura auto-hospedada sem alterar o código da aplicação. Basta apontar seu cliente de API para o endpoint do vLLM e ele funcionará transparentemente.

Algoritmo PagedAttention: A inovação central por trás do desempenho do vLLM é o PagedAttention, que aplica o conceito de paginação de memória virtual aos mecanismos de atenção. Em vez de alocar blocos de memória contíguos para os caches de KV (o que leva à fragmentação), o PagedAttention divide a memória em blocos de tamanho fixo que podem ser alocados sob demanda. Isso reduz o desperdício de memória em até 4x e permite tamanhos de lote (batch) muito maiores.

Lote Contínuo (Continuous Batching): Ao contrário do lote estático, onde você espera que todas as sequências sejam concluídas, o vLLM usa lote contínuo (rolante). Assim que uma sequência termina, uma nova pode ser adicionada ao lote. Isso maximiza a utilização da GPU e minimiza a latência para solicitações de entrada.

Suporte Multi-GPU: O vLLM suporta paralelismo de tensor e paralelismo de pipeline para distribuir modelos grandes em várias GPUs. Ele pode servir eficientemente modelos que não cabem na memória de uma única GPU, suportando configurações de 2 a 8+ GPUs.

Ampla Suporte a Modelos: Compatível com arquiteturas de modelos populares, incluindo LLaMA, Mistral, Mixtral, Qwen, Phi, Gemma e muitos outros. Suporta tanto modelos ajustados por instruções quanto modelos base do HuggingFace Hub.

Quando Usar o vLLM

O vLLM destaca-se em cenários específicos onde suas forças brilham:

Serviços de API de Produção: Quando você precisa entregar um LLM para muitos usuários simultâneos via API, a alta vazão e o lote eficiente do vLLM o tornam a melhor escolha. Empresas que executam chatbots, assistentes de código ou serviços de geração de conteúdo se beneficiam de sua capacidade de lidar com centenas de solicitações por segundo.

Cargas de Trabalho de Alta Concurrencia: Se sua aplicação tem muitos usuários simultâneos fazendo solicitações, o lote contínuo e o PagedAttention do vLLM permitem atender mais usuários com o mesmo hardware em comparação a alternativas.

Otimização de Custos: Quando os custos de GPU são uma preocupação, a superior vazão do vLLM significa que você pode atender o mesmo tráfego com menos GPUs, reduzindo diretamente os custos de infraestrutura. A eficiência de memória de 4x do PagedAttention também permite o uso de instâncias de GPU menores e mais baratas.

Implantações em Kubernetes: O projeto stateless (sem estado) e a arquitetura amigável a contêineres do vLLM o tornam ideal para clusters Kubernetes. Seu desempenho consistente sob carga e o gerenciamento direto de recursos integram-se bem à infraestrutura cloud-native.

Quando NÃO Usar o vLLM: Para desenvolvimento local, experimentação ou cenários de usuário único, ferramentas como Ollama ou llama.cpp oferecem uma melhor experiência de usuário com configuração mais simples. A complexidade do vLLM é justificada quando você precisa de suas vantagens de desempenho para cargas de trabalho de produção.

Como Instalar o vLLM

Pré-requisitos

Antes de instalar o vLLM, certifique-se de que seu sistema atende a estes requisitos:

• Sistema Operacional: Linux com glibc 2.35 ou mais recente (Ubuntu 22.04+, Debian 12+, RHEL 9+)
• GPU: GPU NVIDIA com capacidade computacional 7.5 ou superior (T4, A10, A100, L4, H100, B200, séries RTX 20/30/40/50). Cartões mais antigos da geração 7.0, como o V100, não estão mais na lista de suportados. GPUs AMD são suportadas através de rodas (wheels) separadas do ROCm — veja ROCm vs Vulkan para Hospedagem Local de LLMs em AMD para a imagem específica da AMD, as flags de dispositivo e as ressalvas sobre a cobertura de kernels.
• CUDA: As rodas padrão do pip são compiladas contra a CUDA 12.9; variantes 12.8 e 13.0 são publicadas junto com elas. GPUs Blackwell (B200, GB200) exigem CUDA 12.8+. Seu driver NVIDIA deve ser novo o suficiente para a versão da CUDA que você instalar.
• Python: 3.10 a 3.13 — 3.12 é a versão recomendada (rodas do ROCm são exclusivas para 3.12)
• VRAM: Mínimo de 16GB para modelos 7B, 24GB+ para 13B, 40GB+ para modelos maiores

Instalação via pip

A instalação recomendada usa o uv para criar um ambiente Python 3.12 e selecionar automaticamente o backend CUDA correspondente do PyTorch (--torch-backend=auto inspeciona o driver instalado). Para uma visão mais aprofundada do próprio uv, veja uv: O Novo Gerenciador de Projetos e Ambientes de Pacotes Python:

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

# Verificar instalação
python -c "import vllm; print(vllm.__version__)"

O pip simples também funciona:

python3 -m venv vllm-env
source vllm-env/bin/activate
pip install vllm

As rodas padrão são compiladas contra a CUDA 12.9. Se você precisar de uma versão diferente da CUDA, obtenha o índice de rodas do PyTorch correspondente — por exemplo, CUDA 12.8:

pip install vllm --extra-index-url https://download.pytorch.org/whl/cu128

As rodas fixadas antigas, como vllm==0.4.2+cu121, não existem mais nessa forma. Misturar o vLLM em um ambiente existente com uma build diferente do PyTorch é uma fonte comum de falhas de instalação; o projeto recomenda um ambiente novo e uma build a partir do código-fonte quando você precisar de um alvo CUDA personalizado.

Instalação com Docker

O Docker fornece o método de implantação mais confiável, especialmente para produção. Fixe a imagem em uma versão de release em vez de latest para que as atualizações sejam deliberadas, e note que existem imagens variantes para CUDA 12.9 (sufixo de tag -cu129), AMD ROCm (vllm-openai-rocm), CPU (vllm-openai-cpu) e XPU da Intel (vllm-openai-xpu):

# Baixar a imagem oficial do vLLM
docker pull vllm/vllm-openai:v0.31.0

# Executar o vLLM com suporte a GPU
docker run --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:v0.31.0 \
    --model Qwen/Qwen3-8B

A flag --ipc=host é importante para configurações multi-GPU, pois habilita a comunicação interprocessos adequada.

Compilando a partir do Código-Fonte

Para os recursos mais recentes ou modificações personalizadas, compile a partir do código-fonte:

git clone https://github.com/vllm-project/vllm.git
cd vllm
pip install -e .

Guia Rápido do vLLM

Executando Seu Primeiro Modelo

Inicie o vLLM com um modelo usando a interface de linha de comando:

# Baixar e servir um modelo com a API compatível com a OpenAI
vllm serve Qwen/Qwen3-8B \
    --port 8000

O vllm serve é o CLI atual para o servidor compatível com a OpenAI. A invocação antiga python -m vllm.entrypoints.openai.api_server ainda executa, mas imprime um aviso de depreciação e pode ser removida em uma release futura, portanto atualize qualquer script ou manifesto Kubernetes que ainda o utilize.

O vLLM baixará automaticamente o modelo do HuggingFace Hub (se não estiver em cache) e iniciará o servidor. Você verá uma saída indicando que o servidor está pronto:

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000

Fazendo Requisições de API

Uma vez que o servidor está em execução, você pode fazer requisições usando o cliente Python da OpenAI ou curl:

Usando curl:

curl http://localhost:8000/v1/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "Qwen/Qwen3-8B",
        "prompt": "Explain what vLLM is in one sentence:",
        "max_tokens": 100,
        "temperature": 0.7
    }'

Usando o Cliente Python da OpenAI:

from openai import OpenAI

# Apontar para seu servidor vLLM
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed"  # vLLM ignora isso a menos que você inicie o servidor com --api-key
)

response = client.completions.create(
    model="Qwen/Qwen3-8B",
    prompt="Explain what vLLM is in one sentence:",
    max_tokens=100,
    temperature=0.7
)

print(response.choices[0].text)

API de Chat Completions:

response = client.chat.completions.create(
    model="Qwen/Qwen3-8B",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is PagedAttention?"}
    ],
    max_tokens=200
)

print(response.choices[0].message.content)

Configuração Avançada

O vLLM oferece inúmeros parâmetros para otimizar o desempenho:

vllm serve Qwen/Qwen3-8B \
    --port 8000 \
    --gpu-memory-utilization 0.95 \  # Usar 95% da memória da GPU
    --max-model-len 32k \            # Comprimento máximo da sequência (8192 e 32k funcionam)
    --tensor-parallel-size 2 \       # Usar 2 GPUs com paralelismo de tensor
    --dtype float16 \                # Usar precisão FP16
    --max-num-seqs 256               # Tamanho máximo do lote

Principais Parâmetros Explicados:

• --gpu-memory-utilization: Fração da memória da GPU para o executor do modelo (padrão 0.92). Valores mais altos permitem lotes maiores, mas deixam menos margem para picos de memória.
• --max-model-len: Comprimento máximo do contexto. Aceita contagens de tokens ou valores legíveis como 32k. Reduzir isso economiza memória para lotes maiores.
• --tensor-parallel-size: Número de GPUs para dividir o modelo.
• --dtype: Tipo de dados para os pesos (auto, float16, bfloat16, float32). auto segue o dtype do checkpoint, o que geralmente é o que você quer.
• --max-num-seqs: Número máximo de sequências em um lote.
• --max-num-active-seqs: Limita a admissão de RUNTIME independentemente de max_num_seqs (novo na v0.31.0) — útil para limitar a latência sem reduzir a janela de lote do agendador.

vLLM vs Ollama

O vLLM é projetado para entrega de produção de alta vazão e multiusuário com lote contínuo, PagedAttention e suporte multi-GPU. O Ollama otimiza para configuração local rápida, conveniência de usuário único e gerenciamento simples de modelos.

Para um guia de decisão detalhado cobrindo sinais de migração, etapas de planejamento, configuração do Docker Compose e uma checklist prática, veja Ollama para vLLM: Quando Migrar Seu Servidor Local de LLM.

vLLM vs Docker Model Runner

O Model Runner do Docker é sua solução oficial para implantação local de modelos de IA. Como ele se compara ao vLLM?

Filosofia de Arquitetura

O Docker Model Runner visa ser o “Docker para IA” – uma maneira simples e padronizada de executar modelos de IA localmente com a mesma facilidade de executar contêineres. Ele abstrai a complexidade e fornece uma interface consistente entre diferentes modelos e frameworks.

O vLLM é um motor de inferência especializado focado exclusivamente na entrega de LLMs com desempenho máximo. É uma ferramenta de nível inferior que você contêineriza com o Docker, em vez de uma plataforma completa.

Configuração e Primeiros Passos

A instalação do Docker Model Runner é direta para usuários do Docker:

docker model pull llama3:8b
docker model run llama3:8b

Essa semelhança com o fluxo de trabalho de imagens do Docker o torna instantaneamente familiar para desenvolvedores que já usam contêineres; o conjunto completo de comandos está na folha de dicas do Docker Model Runner.

O vLLM requer mais configuração inicial (Python, CUDA, dependências) ou o uso de imagens Docker pré-construídas:

docker pull vllm/vllm-openai:latest
docker run --runtime nvidia --gpus all vllm/vllm-openai:latest --model <nome-do-modelo>

Características de Desempenho

O vLLM entrega uma vazão superior para cenários multiusuário devido ao PagedAttention e ao lote contínuo. Para serviços de API de produção que lidam com centenas de solicitações por segundo, as otimizações do vLLM proporcionam uma vazão 2 a 5 vezes melhor do que abordagens genéricas de entrega.

O Docker Model Runner foca na facilidade de uso em vez de desempenho máximo. É adequado para desenvolvimento local, testes e cargas de trabalho moderadas, mas não implementa as otimizações avançadas que fazem o vLLM excelir em escala.

Suporte a Modelos

O Docker Model Runner fornece uma biblioteca de modelos curada com acesso em um comando a modelos populares. Ele suporta múltiplos frameworks (não apenas LLMs), incluindo Stable Diffusion, Whisper e outros modelos de IA, tornando-o mais versátil para diferentes cargas de trabalho de IA.

O vLLM se especializa em inferência de LLMs com suporte profundo para modelos de linguagem baseados em transformadores. Ele suporta qualquer LLM compatível com HuggingFace, mas não se estende a outros tipos de modelos de IA, como geração de imagem ou reconhecimento de fala.

Implantação em Produção

O vLLM é testado em batalha em produção em empresas como Anthropic, Replicate e muitas outras que servem bilhões de tokens diariamente. Suas características de desempenho e estabilidade sob carga pesada o tornam o padrão de fato para a entrega de LLMs em produção.

O Docker Model Runner é mais novo e se posiciona mais para cenários de desenvolvimento e testes locais. Embora possa servir tráfego de produção, falta o histórico comprovado e as otimizações de desempenho que as implantações de produção exigem.

Ecossistema de Integração

O vLLM integra-se com ferramentas de infraestrutura de produção: operadores Kubernetes, métricas Prometheus, Ray para entrega distribuída e compatibilidade extensa com a API da OpenAI para aplicações existentes.

O Docker Model Runner integra-se naturalmente ao ecossistema do Docker e ao Docker Desktop. Para equipes já padronizadas no Docker, essa integração fornece uma experiência coesa, mas com menos recursos especializados de entrega de LLM.

Quando Usar Cada Um

Use vLLM para:

• Serviços de API de LLM em produção
• Implantações de alta vazão e multiusuário
• Implantações em nuvem sensíveis a custos que precisam de eficiência máxima
• Ambientes Kubernetes e cloud-native
• Quando você precisa de escalabilidade e desempenho comprovados

Use Docker Model Runner para:

• Desenvolvimento e testes locais
• Executar vários tipos de modelos de IA (não apenas LLMs)
• Equipes fortemente investidas no ecossistema Docker
• Experimentação rápida sem configuração de infraestrutura
• Finalidades de aprendizado e educacionais

Abordagem Híbrida: Muitas equipes desenvolvem localmente com o Docker Model Runner por conveniência, então implantam com o vLLM em produção pelo desempenho. As imagens do Docker Model Runner também podem ser usadas para executar contêineres do vLLM, combinando ambas as abordagens.

Melhores Práticas de Implantação em Produção

Implantação Docker

Crie uma configuração Docker Compose pronta para produção:

version: '3.8'

services:
  vllm:
    image: vllm/vllm-openai:latest
    runtime: nvidia
    environment:
      - CUDA_VISIBLE_DEVICES=0,1
    volumes:
      - ~/.cache/huggingface:/root/.cache/huggingface
      - ./logs:/logs
    ports:
      - "8000:8000"
    command: >
      --model Qwen/Qwen3-8B
      --tensor-parallel-size 2
      --gpu-memory-utilization 0.90
      --max-num-seqs 256
      --max-model-len 8192
    restart: unless-stopped
    shm_size: '16gb'
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 2
              capabilities: [gpu]

Implantação Kubernetes

Implante o vLLM no Kubernetes para escala de produção:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-server
spec:
  replicas: 2
  selector:
    matchLabels:
      app: vllm
  template:
    metadata:
      labels:
        app: vllm
    spec:
      containers:
      - name: vllm
        image: vllm/vllm-openai:latest
        args:
          - --model
          - Qwen/Qwen3-8B
          - --tensor-parallel-size
          - "2"
          - --gpu-memory-utilization
          - "0.90"
        resources:
          limits:
            nvidia.com/gpu: 2
        ports:
        - containerPort: 8000
        volumeMounts:
        - name: cache
          mountPath: /root/.cache/huggingface
      volumes:
      - name: cache
        hostPath:
          path: /mnt/huggingface-cache
---
apiVersion: v1
kind: Service
metadata:
  name: vllm-service
spec:
  selector:
    app: vllm
  ports:
  - port: 80
    targetPort: 8000
  type: LoadBalancer

Monitoramento e Observabilidade

O servidor compatível com a OpenAI expõe métricas Prometheus em /metrics por padrão — sem flags extras necessárias:

curl -s http://localhost:8000/metrics | grep '^vllm:'

Métricas-chave para monitorar:

• vllm:num_requests_running / vllm:num_requests_waiting / vllm:num_requests_swapped — solicitações nos estados do agendador RUNNING, WAITING e SWAPPED
• vllm:kv_cache_usage_perc — fração de blocos de cache de KV usados (0–1)
• vllm:time_to_first_token_seconds — histograma de TTFT (Tempo Até o Primeiro Token)
• vllm:time_per_output_token_seconds — velocidade de geração por token
• vllm:num_preemptions_total — preemptions cumulativas; um contador em aumento significa que o cache de KV está superassinado e as solicitações estão sendo recalculadas

Para dashboards, exemplos de PromQL e limites de alerta em torno da entrega de LLMs, veja Monitorar Inferência de LLM em Produção (2026): Prometheus & Grafana para vLLM, TGI, llama.cpp.

Ajuste de Desempenho

Otimizar a Utilização da Memória da GPU: O padrão é 0.92; ajuste com base no comportamento observado. Valores mais altos permitem lotes maiores, mas correm o risco de erros OOM (Out of Memory) durante picos de tráfego.

Ajustar o Comprimento Máximo da Sequência: Se seu caso de uso não precisa do comprimento total do contexto, reduza --max-model-len. Isso libera memória para lotes maiores. Por exemplo, se você só precisa de contexto 4K, defina --max-model-len 4096 em vez de usar o máximo do modelo (frequentemente 8K-32K).

Escolher a Quantização Apropriada: Para modelos que a suportam, use versões quantizadas (8-bit, 4-bit) para reduzir a memória e aumentar a vazão:

--quantization awq  # Para modelos quantizados AWQ
--quantization gptq # Para modelos quantizados GPTQ

Cache de Prefixo (Prefix Caching): O cache de prefixo é habilitado por padrão no motor atual, de modo que solicitações que compartilham um prefixo de prompt (um prompt de sistema fixo, um modelo de contexto RAG) reutilizam seu cache de KV sem qualquer flag. Desative-o com --no-enable-prefix-caching para cargas de trabalho com muitos prompts longos únicos onde o registro de cache não traz nada.

Solução de Problemas Comuns

Erros de Memória Insuficiente (Out of Memory)

Sintomas: O servidor trava com erros CUDA out of memory.

Soluções:

• Reduza --gpu-memory-utilization para 0.85 ou 0.80
• Diminua --max-model-len se seu caso de uso permitir
• Reduza --max-num-seqs para reduzir o tamanho do lote
• Use uma versão quantizada do modelo
• Habilite o paralelismo de tensor para distribuir em mais GPUs

Duas formas distintas de OOM exigem correções diferentes. Um OOM de inicialização ocorre antes de qualquer solicitação: o vLLM perfila a memória e falha em alocar até o mínimo do cache de KV, então reduzir --max-num-seqs não ajuda — reduza --max-model-len ou aumente --gpu-memory-utilization se você tiver folga. Um OOM em tempo de execução sob carga pode vir da memória de captura de CUDA-graph, que escala com --max-num-seqs mas fica fora da contabilidade do cache de KV; execute uma vez com --enforce-eager para verificar se os gráficos CUDA são a memória em falta, e reteste a mesma configuração exata antes de culpar o cache. Se inicializações em hardware idêntico continuarem tendo sucesso com a mesma alocação, passe de volta o valor --kv-cache-memory-bytes que o vLLM registra na inicialização para pular a etapa de perfilamento em inicializações subsequentes.

Em um cartão de 16 GB único, a maioria desses erros de OOM se origina do orçamento do cache de KV em vez dos pesos sozinhos — Cache de KV em GPUs de 16 GB cobre a fórmula exata, o dtype de cache de KV FP8 e as compensações do cache de prefixo por trás de --max-model-len e --max-num-seqs antes de recorrer a um modelo menor.

Lento na Inicialização

Sintomas: O servidor leva minutos do lançamento até “Application startup complete”.

Soluções:

• O carregamento de pesos, compilação e captura de CUDA-graph dominam a inicialização — --enforce-eager pula ambas a compilação e a captura e informa quanto da inicialização eles custam, ao preço da velocidade de decodificação em estado estacionário
• Reutilize o valor registrado de --kv-cache-memory-bytes para pular as etapas de perfilamento de memória e estimativa de CUDA-graph em inicializações repetidas
• Na v0.30.0+, o comando vllm preload executa um daemon persistente de cache de pesos que mantém pesos pós-quantização residentes na memória da GPU, de modo que reinicializações do motor mapeiam pesos sobre IPC CUDA em vez de recarregar do disco (--load-format ipc_cache)
• Para checkpoints NVFP4 que sofrem OOM durante a compilação de inicialização, limitar as threads de build com MAX_JOBS=4 e NVCC_THREADS=4 é uma correção amplamente usada — ela atrasa a build JIT, mas para o OOM

Baixa Vazão

Sintomas: O servidor lida com menos solicitações do que o esperado.

Soluções:

• Aumente --max-num-seqs para permitir lotes maiores
• Aumente --gpu-memory-utilization se você tiver folga
• Verifique se a CPU não é o gargalo com htop – considere CPUs mais rápidas
• Verifique a utilização da GPU com nvidia-smi – deve ser 95%+
• Habilite FP16 se estiver usando FP32: --dtype float16

Lento no Tempo do Primeiro Token

Sintomas: Latência alta antes de a geração começar.

Soluções:

• Use modelos menores para aplicações críticas em latência
• O cache de prefixo está ligado por padrão — verifique se está ativo, em vez de re-adicionar a flag
• Reduza --max-num-seqs para priorizar latência em vez de vazão
• Considere decodificação especulativa para modelos suportados
• Otimize a configuração de paralelismo de tensor

Falhas no Carregamento de Modelo

Sintomas: O servidor falha ao iniciar, não consegue carregar o modelo.

Soluções:

• Verifique se o nome do modelo corresponde exatamente ao formato do HuggingFace
• Verifique a conectividade de rede ao HuggingFace Hub
• Garanta espaço em disco suficiente em ~/.cache/huggingface
• Para modelos com controle de acesso, defina a variável de ambiente HF_TOKEN
• Tente baixar manualmente com hf download <modelo> (ou huggingface-cli download <modelo> em instalações mais antigas)

Recursos Avançados

Decodificação Especulativa

O vLLM suporta decodificação especulativa, onde um modelo de rascunho menor propõe tokens que um modelo de destino maior verifica. Isso pode acelerar a geração em 1,5 a 2x. Para um guia abrangente sobre métodos de decodificação especulativa — modelos de rascunho, EAGLE-3, P-EAGLE e n-gram — veja Decodificação Especulativa: Inferência Mais Rápida Sem Perda de Qualidade.

vllm serve meta-llama/Llama-3.1-8B-Instruct \
    --speculative-config '{"method": "draft_model", "model": "meta-llama/Llama-3.2-1B-Instruct", "num_speculative_tokens": 4}'

As flags antigas --speculative-model e --num-speculative-tokens foram removidas — a configuração mudou para o único argumento JSON --speculative-config, que também seleciona o método (draft_model, ngram, família EAGLE, ou MTP para modelos com cabeças nativas de previsão multi-token).

Adaptadores LoRA

Sirva múltiplos adaptadores LoRA em cima de um modelo base sem carregar múltiplos modelos completos:

vllm serve meta-llama/Llama-3.1-8B-Instruct \
    --enable-lora \
    --lora-modules sql-lora=/caminho/para/adaptador-sql \
                   code-lora=/caminho/para/adaptador-codigo

Então especifique qual adaptador usar por solicitação colocando seu nome no campo model — o mesmo mecanismo escala para dezenas de adaptadores específicos de tarefa (variantes específicas de cliente ou por domínio) com apenas o modelo base residente na memória:

response = client.completions.create(
    model="sql-lora",  # Usar o adaptador SQL
    prompt="Convert this to SQL: Show me all users created this month"
)

Cache de Prefixo

O cache de prefixo evita recalcular o cache de KV para prefixos de prompt compartilhados e é habilitado por padrão no motor atual.

Ele compensa mais para:

• Chatbots com prompts de sistema fixos
• Aplicações RAG com modelos de contexto consistentes
• Prompts de aprendizado com alguns exemplos (few-shot) repetidos entre solicitações

Para solicitações que compartilham um prefixo, o tempo até o primeiro token cai substancialmente porque o pré-preenchimento (prefill) da parte compartilhada é pulado.

Exemplos de Integração

Integração LangChain

from langchain_community.llms import VLLMOpenAI

llm = VLLMOpenAI(
    openai_api_key="EMPTY",
    openai_api_base="http://localhost:8000/v1",
    model_name="Qwen/Qwen3-8B",
    max_tokens=512,
    temperature=0.7,
)

response = llm("Explain PagedAttention in simple terms")
print(response)

Aplicação FastAPI

from fastapi import FastAPI
from openai import AsyncOpenAI

app = FastAPI()
client = AsyncOpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed"
)

@app.post("/generate")
async def generate(prompt: str):
    response = await client.completions.create(
        model="Qwen/Qwen3-8B",
        prompt=prompt,
        max_tokens=200
    )
    return {"result": response.choices[0].text}

Benchmarks de Desempenho

Dados de desempenho do mundo real ajudam a ilustrar as vantagens do vLLM. As figuras abaixo vêm da documentação da época do lançamento do projeto e medições iniciais da comunidade — trate-as como indicações de ordem de grandeza do efeito da arquitetura, e não como resultados atuais para a geração de modelos de hoje:

Comparação de Vazão (Mistral-7B em GPU A100):

• vLLM: ~3.500 tokens/segundo com 64 usuários simultâneos
• HuggingFace Transformers: ~250 tokens/segundo com a mesma concorrência
• Ollama: ~1.200 tokens/segundo com a mesma concorrência
• Resultado: o vLLM fornece uma melhoria de 14x em comparação com implementações básicas

Eficiência de Memória (LLaMA-2-13B):

• Implementação padrão: 24GB de VRAM, 32 sequências simultâneas
• vLLM com PagedAttention: 24GB de VRAM, 128 sequências simultâneas
• Resultado: 4x mais solicitações simultâneas com a mesma memória

Latência Sob Carga (Mixtral-8x7B em 2xA100):

• vLLM: latência P50 de 180ms, latência P99 de 420ms a 100 req/s
• Entrega padrão: latência P50 de 650ms, latência P99 de 3.200ms a 100 req/s
• Resultado: o vLLM mantém latência consistente sob carga alta

Análise de Custos

Entender as implicações de custo de escolher o vLLM:

Cenário: Servindo 1M de solicitações/dia

Com Entrega Padrão:

• Necessário: 8x GPUs A100 (80GB)
• Custo AWS: ~$32/hora × 24 × 30 = $23.040/mês
• Custo por 1M de tokens: ~$0,75

Com vLLM:

• Necessário: 2x GPUs A100 (80GB)
• Custo AWS: ~$8/hora × 24 × 30 = $5.760/mês
• Custo por 1M de tokens: ~$0,19
• Economia: $17.280/mês (redução de 75%)

Essa vantagem de custo cresce com a escala. Organizações que servem bilhões de tokens mensalmente economizam centenas de milhares de dólares ao usar a entrega otimizada do vLLM em vez de implementações ingênuas.

Considerações de Segurança

Autenticação

O vLLM possui uma flag embutida --api-key, mas, de acordo com a documentação oficial, ela apenas autentica endpoints sob os prefixos de caminho /v1, /v2 e /inference — outros endpoints no mesmo servidor permanecem não autenticados. Trate-o como uma camada, não como a resposta completa; para cobertura total, implemente autenticação no nível do proxy reverso:

# Configuração Nginx
location /v1/ {
    auth_request /auth;
    proxy_pass http://vllm-backend:8000;
}

location /auth {
    proxy_pass http://auth-service:8080/verify;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
}

Ou use gateways de API como Kong, Traefik ou AWS API Gateway para autenticação e limitação de taxa de nível empresarial.

Isolamento de Rede

Execute o vLLM em redes privadas, não diretamente exposto à internet:

# Exemplo de NetworkPolicy Kubernetes
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: vllm-access
spec:
  podSelector:
    matchLabels:
      app: vllm
  policyTypes:
  - Ingress
  ingress:
  - from:
    - podSelector:
        matchLabels:
          role: api-gateway
    ports:
    - protocol: TCP
      port: 8000

Limitação de Taxa (Rate Limiting)

Implemente limitação de taxa para evitar abuso:

# Exemplo usando Redis para limitação de taxa
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
import redis
from datetime import datetime, timedelta

app = FastAPI()
redis_client = redis.Redis(host='localhost', port=6379)

@app.middleware("http")
async def rate_limit_middleware(request, call_next):
    client_ip = request.client.host
    key = f"rate_limit:{client_ip}"
    
    requests = redis_client.incr(key)
    if requests == 1:
        redis_client.expire(key, 60)  # Janela de 60 segundos
    
    if requests > 60:  # 60 solicitações por minuto
        raise HTTPException(status_code=429, detail="Rate limit exceeded")
    
    return await call_next(request)

Controle de Acesso a Modelos

Para implantações multi-tenant, controle quais usuários podem acessar quais modelos:

ALLOWED_MODELS = {
    "user_tier_1": ["Qwen/Qwen3-8B"],
    "user_tier_2": ["Qwen/Qwen3-8B", "meta-llama/Llama-2-13b-chat-hf"],
    "admin": ["*"]  # Todos os modelos
}

def verify_model_access(user_tier: str, model: str) -> bool:
    allowed = ALLOWED_MODELS.get(user_tier, [])
    return "*" in allowed or model in allowed

Guia de Migração

Da OpenAI para o vLLM

Migrar da OpenAI para o vLLM auto-hospedado é direto graças à compatibilidade de API:

Antes (OpenAI):

from openai import OpenAI

client = OpenAI(api_key="sk-...")
response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "Hello"}]
)

Depois (vLLM):

from openai import OpenAI

client = OpenAI(
    base_url="https://your-vllm-server.com/v1",
    api_key="your-internal-key"  # Se você adicionou autenticação
)
response = client.chat.completions.create(
    model="Qwen/Qwen3-8B",
    messages=[{"role": "user", "content": "Hello"}]
)

Apenas duas mudanças necessárias: atualizar base_url e o nome do model. Todo o outro código permanece idêntico.

Do Ollama para o vLLM

O Ollama usa um formato de API diferente. A mudança básica no lado do cliente é alternar do endpoint REST do Ollama para a API compatível com a OpenAI do vLLM:

API do Ollama:

import requests

response = requests.post('http://localhost:11434/api/generate',
    json={'model': 'llama2', 'prompt': 'Why is the sky blue?'})

Equivalente em vLLM:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")
response = client.completions.create(
    model="meta-llama/Llama-2-7b-chat-hf",
    prompt="Why is the sky blue?"
)

A API do Ollama é REST simples com sua própria forma de requisição, enquanto o vLLM fala o protocolo da OpenAI — essa diferença de formato de API é a principal mudança no lado do cliente, e a abordagem em etapas (executar ambos os servidores, deslocar o tráfego endpoint por endpoint) é coberta no guia de migração vinculado anteriormente neste artigo.

Do HuggingFace Transformers para o vLLM

Migração de uso direto em Python:

HuggingFace:

from transformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-8B")
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-8B")

inputs = tokenizer("Hello", return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=100)
result = tokenizer.decode(outputs[0])

vLLM:

from vllm import LLM, SamplingParams

llm = LLM(model="Qwen/Qwen3-8B")
sampling_params = SamplingParams(max_tokens=100)

outputs = llm.generate("Hello", sampling_params)
result = outputs[0].outputs[0].text

A API Python do vLLM é mais simples e muito mais rápida para inferência em lote.

Releases Recentes: O Que Mudou em 2026

Três releases em setembro–outubro de 2026 (v0.29.0, v0.30.0, v0.31.0) mostram para onde o desenvolvimento está se dirigindo:

Reinicializações rápidas: O vllm preload inicia um daemon persistente de cache de pesos por GPU que mantém pesos pós-quantização e divididos por TP residentes na memória da GPU, de modo que motores reiniciados os mapeiam sobre IPC CUDA (--load-format ipc_cache) em vez de recarregar do disco. O experimental vllm snapshot create/restore faz snapshots de um motor totalmente inicializado com CRIU.

Decodificação especulativa no Model Runner V2: Decodificação especulativa com modelo de rascunho, processadores de logits personalizados e verificação adaptativa foram movidos para o novo model runner, com o adição do rascunhador LiLiCorr e agendamento assíncrono para o rascunhador DFlash.

Entrega em larga escala de MoE: Novos backends balanceados de all2all de paralelismo de especialista (--all2all-backend moonep), DeepEPv2 com paralelismo de sequência, EPLB com sobreposição de especialista compartilhado e paralelismo de contexto de prefill combinado com paralelismo de dados.

Controle de agendamento: --max-num-active-seqs limita a admissão de RUNNING independentemente de max_num_seqs, e a fila de espera agora agenda primeiro as solicitações que já possuem blocos de KV.

Itens de roadmap de guias do vLLM mais antigos já foram lançados desde muito tempo — suporte GGUF, entrega multimodal, prefill/decode desacoplado e inferência multi-nó fazem parte das releases atuais, portanto trate qualquer tutorial que os liste como “em breve” como desatualizado. As notas de release para cada versão estão na página de releases do vLLM.

Links Úteis

Artigos Relacionados Neste Site

• Folha de Dicas do Ollama - Referência completa de comandos e folha de dicas do Ollama cobrindo instalação, gerenciamento de modelos, uso de API e melhores práticas para implantação local de LLM. Essencial para desenvolvedores usando Ollama junto ou em vez de vLLM.

• Docker Model Runner vs Ollama: Qual Escolher? - Comparação aprofundada do Model Runner do Docker e do Ollama para implantação local de LLM, analisando desempenho, suporte a GPU, compatibilidade de API e casos de uso. Ajuda a entender o cenário competitivo em que o vLLM opera.

Recursos Externos e Documentação

• Repositório GitHub do vLLM - Repositório oficial do vLLM com código-fonte, documentação abrangente, guias de instalação e discussões ativas da comunidade. Recurso essencial para estar atualizado com os recursos mais recentes e solução de problemas.

• Documentação do vLLM - Documentação oficial cobrindo todos os aspectos do vLLM, desde a configuração básica até a configuração avançada. Inclui referências de API, guias de ajuste de desempenho e melhores práticas de implantação.

• Papel PagedAttention - Papel acadêmico que introduz o algoritmo PagedAttention que impulsiona a eficiência do vLLM. Leitura essencial para entender as inovações técnicas por trás das vantagens de desempenho do vLLM.

• Blog do vLLM - Blog oficial do vLLM com anúncios de releases, benchmarks de desempenho, análises técnicas profundas e estudos de caso da comunidade de implantações em produção.

• Hub de Modelos HuggingFace - Repositório abrangente de LLMs de código aberto que funcionam com o vLLM. Busque modelos por tamanho, tarefa, licença e características de desempenho para encontrar o modelo certo para seu caso de uso.

• Documentação Ray Serve - Documentação do framework Ray Serve para construir implantações escaláveis e distribuídas do vLLM. O Ray fornece recursos avançados como autoescalamento, entrega multi-modelo e gerenciamento de recursos para sistemas de produção.

• NVIDIA TensorRT-LLM - TensorRT-LLM da NVIDIA para inferência altamente otimizada em GPUs NVIDIA. Alternativa ao vLLM com estratégias de otimização diferentes, útil para comparação e compreensão do cenário de otimização de inferência.

• Referência da API OpenAI - Documentação oficial da API OpenAI com a qual a API do vLLM é compatível. Consulte-a ao construir aplicações que precisam funcionar com endpoints OpenAI e vLLM auto-hospedados de forma intercambiável.