O que é vLLM? Um guia prático sobre o mecanismo de inferência de LLM de alta taxa de processamento

vLLM é um mecanismo de inferência e serviço de código aberto para modelos de linguagem de grande porte. Ele carrega um modelo em uma ou mais GPUs e o expõe por meio de uma API HTTP compatível com a OpenAI, utilizando duas técnicas — PagedAttention e agrupamento contínuo — para atender a muitas solicitações simultâneas com uma taxa de processamento muito maior do que a abordagem ingênua de serviço. Foi criado no Sky Computing Lab da UC Berkeley e lançado em 2023.

O que é o vLLM e para quem é indicado

Imagine o vLLM como o equivalente voltado para produção das ferramentas desktop, como o Ollama. Ambos recebem um modelo e respondem às solicitações, mas otimizam objetivos opostos. O Ollama prioriza obter uma resposta para uma única pessoa em hardware modesto. Já o vLLM prioriza taxa de processamento: número total de tokens gerados por segundo em dezenas ou centenas de solicitações simultâneas direcionadas à mesma GPU.

Isso torna o vLLM a ferramenta certa quando você:

• Servir um modelo de linguagem de grande porte (LLM) por trás de uma API interna ou pública utilizada por várias pessoas ou serviços
• Executar tarefas em lote — classificação, extração, geração de dados sintéticos — em grandes conjuntos de dados
• Substituir uma API paga por um modelo de pesos abertos auto-hospedado para reduzir os custos por token (o calculador de ponto de equilíbrio entre auto-hospedagem e API ajuda você a verificar se a conta da GPU realmente supera a conta da API no seu volume de uso)

E a ferramenta errada quando você deseja um assistente de conversação em seu próprio laptop, inferência esporádica para um único usuário ou qualquer outra coisa em uma máquina sem uma GPU potente. O vLLM pressupõe um ambiente de servidor: Linux, uma GPU NVIDIA como caminho padrão (backends para AMD ROCm, Intel, TPU e CPU existem, mas são menos utilizados) e uma carga de trabalho com concorrência.

No lançamento em 2023, os benchmarks do vLLM mostraram até 24× o débito (throughput) em comparação com servir usando diretamente a biblioteca Hugging Face Transformers e aproximadamente 2–3,5× o débito dos sistemas de serviço disponíveis na época. Os valores exatos variam conforme o modelo, o hardware e a carga de trabalho — mas vale a pena compreender a razão dessa diferença, pois ela indica exatamente quando o vLLM faz a diferença.

PagedAttention, em termos simples

Quando um LLM gera texto, ele mantém um cache KV cache KV na memória da GPU: as chaves e valores de atenção para cada token em todas as conversas ativas. Esse cache cresce a cada token gerado e, em contextos longos, pode consumir mais VRAM do que os próprios pesos do modelo.

Antes do vLLM, os mecanismos de serviço alocavam para cada requisição um bloco contíguo de memória dimensionado para o comprimento máximo possível da sequência, pois não era possível saber antecipadamente quanto tempo a saída teria. A maioria das requisições termina muito antes desse limite máximo, portanto grande parte dessa memória reservada ficava ociosa. O artigo do vLLM mediu um desperdício de 60–80% da memória do cache KV em sistemas anteriores devido a esse tipo de fragmentação.

O PagedAttention adapta a solução usada pelos sistemas operacionais: paginação de memória virtual. O cache KV é dividido em pequenos blocos de tamanho fixo (16 tokens por padrão), alocados sob demanda e que não precisam ser contíguos. Uma tabela de blocos mapeia as posições lógicas de cada sequência para quaisquer blocos físicos livres — exatamente como um sistema operacional mapeia páginas virtuais para RAM física. O desperdício de memória cai para menos de 4%, e os blocos podem até ser compartilhados entre sequências (útil ao gerar várias conclusões a partir de um mesmo prompt).

A consequência prática: muito mais sequências simultâneas cabem na mesma VRAM. Mais sequências na memória significam lotes efetivos maiores, e lotes maiores são o que mantém a GPU ocupada. Essa é toda a história do débito — o PagedAttention não torna nenhuma única requisição mais rápida; ele permite que muitas mais requisições sejam executadas simultaneamente.

Agrupamento contínuo

A segunda técnica ataca o escalonamento (scheduling), em vez da memória. O agrupamento ingênuo (naive batching) reúne requisições, executa todo o lote até a conclusão e só então inicia o próximo lote — assim, uma requisição que termina em 20 tokens espera pelaquela que está gerando 2.000 tokens, enquanto novas requisições aguardam na fila externa. Agrupamento contínuo (também chamado de escalonamento em nível de iteração) reforma o lote a cada passo de geração: sequências concluídas saem imediatamente e requisições em espera entram imediatamente.

A GPU permanece saturada, requisições curtas não ficam reféns das longas e a latência sob carga melhora juntamente com o débito. O PagedAttention e o agrupamento contínuo (continuous batching) se reforçam mutuamente: o primeiro permite acomodar mais sequências na memória, e o segundo garante que essa capacidade seja efetivamente aproveitada.

Instalação do vLLM: as restrições que costumam causar problemas

A instalação requer apenas um comando, mas três restrições causam a maioria das falhas:

1. Versão do Python. As versões recentes visam aproximadamente o intervalo Python 3.9–3.12, e essa faixa suportada varia entre lançamentos. Se pip relatar 'nenhuma distribuição correspondente', sua versão do Python é o primeiro suspeito.
2. Versão do CUDA. As versões pré-compiladas (wheels) são construídas contra uma versão principal específica do CUDA (CUDA 12.x nas versões atuais). Você precisa de um driver NVIDIA recente; versões para outras versões do CUDA estão disponíveis para alguns lançamentos por meio de URLs especiais de índice documentadas na documentação oficial do vLLM.
3. Conflitos com o PyTorch. O vLLM fixa (pina) sua própria versão do PyTorch. Instalá-lo em um ambiente que já contenha uma versão diferente do PyTorch é a causa clássica de erros cripticos de importação. Use sempre um ambiente virtual limpo.

Do ponto de vista de hardware, o caminho principal exige uma GPU NVIDIA com capacidade de computação 7.0 ou superior — V100, T4, séries RTX 20 e posteriores. Se você estiver escolhendo hardware, consulte o guia sobre as melhores GPUs para executar LLMs localmente.

Linux (plataforma suportada)

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

A documentação do vLLM também recomenda uv (uv venv e depois uv pip install vllm), que resolve as dependências fixas mais rapidamente. De qualquer forma, o objetivo é manter um ambiente limpo.

Windows: use WSL2 ou Docker

Não há compilação nativa para Windows. As configurações funcionais são WSL2 com uma distribuição Ubuntu (o driver NVIDIA para Windows transmite o CUDA ao WSL2, portanto as instruções Linux acima funcionam dentro dele) ou Docker Desktop com suporte a GPU ativado, utilizando a imagem oficial:

docker run --gpus all -p 8000:8000 vllm/vllm-openai --model Qwen/Qwen2.5-7B-Instruct

macOS: não é a ferramenta adequada

O vLLM não possui backend para GPU Metal/Apple. Uma compilação experimental para CPU pode ser feita a partir do código-fonte, mas isso vai contra o propósito de um mecanismo voltado para alto débito. Em um Mac, use LM Studio llama.cpp

Executando um servidor: vllm serve

ou Ollama em vez disso — ambos aproveitam adequadamente a GPU da Apple Silicon.

Um único comando inicia um servidor de inferência (o modelo é baixado automaticamente do Hugging Face na primeira execução):

vllm serve Qwen/Qwen2.5-7B-Instruct

Observe que o vLLM pré-aloca a maior parte da GPU por design — uma leitura quase completa da VRAM é normal, não um vazamento. Antes de escolher um modelo, verifique se os pesos combinados com o cache KV cabem em sua placa usando a Calculadora de VRAM; como regra geral, pesos em FP16 exigem cerca de 2 GB por bilhão de parâmetros, enquanto pesos em 8 bits exigem aproximadamente metade disso, além de espaço adicional para o cache.

A API compatível com a OpenAI

O servidor implementa a interface de API OpenAI: /v1/chat/completions, /v1/completions, /v1/models, e /v1/embeddings (para modelos de incorporação). Qualquer ferramenta desenvolvida com base no SDK OpenAI funciona apenas alterando a URL base:

curl http://localhost:8000/v1/chat/completions 
  -H "Content-Type: application/json" 
  -d '{
    "model": "Qwen/Qwen2.5-7B-Instruct",
    "messages": [{"role": "user", "content": "Explique PagedAttention em uma frase."}]
  }'

Em Python, OpenAI(base_url="http://localhost:8000/v1", api_key="none") é toda a migração necessária. Essa compatibilidade representa grande parte da adoção do vLLM: ferramentas existentes, agentes e frameworks funcionam sem modificações.

Quando o Ollama ou o llama.cpp são escolhas melhores

Escolher Ollama quando há apenas um usuário e o hardware é um laptop ou desktop — sua instalação requer apenas um único instalador e ele executa confortavelmente modelos quantizados GGUF em CPUs e Apple Silicon (veja o Guia completo do Ollama). Escolha llama.cpp diretamente quando você precisa de máxima portabilidade ou deseja incorporar a inferência dentro de outro aplicativo. Escolha vLLM quando as solicitações chegam simultaneamente e a métrica relevante é tokens por segundo por dólar. Uma carga de trabalho com um único usuário obtém poucos benefícios da PagedAttention; já uma carga com 50 usuários obtém ganhos enormes.

Perguntas frequentes

O vLLM é gratuito?

Sim. O vLLM é de código aberto sob a licença Apache 2.0, originalmente desenvolvido pela UC Berkeley e atualmente mantido como projeto comunitário sob a fundação PyTorch. Não há versão paga; seus custos limitam-se ao hardware e à energia elétrica.

O vLLM consegue executar modelos GGUF, como faz o Ollama?

O suporte a GGUF existe, mas é experimental e não representa o caminho recomendado. O vLLM foi projetado em torno de pontos de verificação padrão do Hugging Face (safetensors), com quantização via checkpoints AWQ, GPTQ ou FP8. Se seus modelos só existirem em arquivos GGUF, o Ollama ou o llama.cpp são opções mais adequadas.

O vLLM funciona sem uma GPU NVIDIA?

Existem back-ends para AMD ROCm, hardware Intel, Google TPUs, AWS Neuron e CPUs, mas o caminho CUDA da NVIDIA é, de longe, o mais maduro e melhor documentado. O vLLM em CPU funciona apenas para testes, não para atender às demandas de throughput para as quais o mecanismo foi projetado.

Quanta VRAM o vLLM precisa?

O suficiente para os pesos do modelo mais o cache KV: aproximadamente 2 GB por bilhão de parâmetros em FP16, cerca da metade disso em 8 bits, além de espaço adicional para o cache, que aumenta com o comprimento do contexto e a concorrência. Um modelo de 7B em FP16 cabe confortavelmente em uma placa de 24 GB; já um modelo de 70B exige múltiplas GPUs ou quantização agressiva. A referência sobre requisitos de VRAM por modelo contém valores específicos para cada modelo.

Como o vLLM se compara ao TensorRT-LLM, SGLang ou TGI?

Todos pertencem à mesma categoria — mecanismos de inferência para produção. O vLLM geralmente oferece o suporte mais amplo a modelos, a configuração mais simples e a comunidade maior; o TensorRT-LLM pode extrair desempenho máximo das GPUs NVIDIA, mas exige um processo mais complexo de construção e ajuste; o SGLang é um forte concorrente, especialmente para saídas estruturadas. Realize testes comparativos com seu próprio modelo e carga de trabalho antes de decidir — as classificações mudam entre versões.

Posso realizar fine-tuning de modelos com o vLLM?

Não — o vLLM é voltado exclusivamente para inferência. Ele é frequentemente usado como backend rápido de geração dentro de frameworks de treinamento RLHF, mas o treinamento propriamente dito ocorre em outro lugar. Realize o fine-tuning com ferramentas como Hugging Face TRL, Axolotl ou Unsloth, e depois sirva o ponto de verificação resultante com o vLLM.