Blog

O que é vLLM? Como Instalar e Usar vLLM, Explicado

@apidog

@apidog

26 junho 2025

O que é vLLM? Como Instalar e Usar vLLM, Explicado

Bem-vindo ao guia abrangente sobre vLLM! Se você está envolvido no mundo dos Modelos de Linguagem de Grande Escala (LLMs), provavelmente já encontrou os desafios de velocidade de inferência e throughput. Servir esses modelos massivos de forma eficiente pode ser um gargalo. É aqui que o vLLM entra como uma solução revolucionária. Este tutorial irá guiá-lo por tudo o que você precisa saber como iniciante: o que é vLLM, por que é importante, como instalá-lo e como usá-lo tanto para processamento em lote offline quanto para servição online.

O Que é vLLM?

Em sua essência, vLLM é uma biblioteca de alto throughput e eficiente em memória, especificamente projetada para inferência e servição de Modelos de Linguagem de Grande Escala (LLM). Desenvolvido por pesquisadores e engenheiros que buscam superar as limitações de desempenho dos sistemas de servição existentes, o vLLM acelera significativamente o processo de obtenção de previsões (inferência) de LLMs.

Os métodos tradicionais para inferência de LLM frequentemente enfrentam dificuldades em gerenciar o grande consumo de memória do mecanismo de atenção do modelo (especificamente, o cache KV) e em agrupar eficientemente as solicitações recebidas. O vLLM introduz técnicas inovadoras, mais notavelmente a PagedAttention, para enfrentar esses desafios de frente. Ele permite um throughput muito mais alto (mais solicitações processadas por segundo) e pode servir modelos mais rapidamente e de forma mais econômica em comparação com muitas implementações padrão do Hugging Face Transformers ou outras estruturas de servição ao lidar com solicitações concorrentes.

Pense no vLLM como um motor altamente otimizado para executar LLMs pré-treinados. Você fornece o modelo e os prompts, e o vLLM lida com a tarefa complexa de gerar texto de forma rápida e eficiente, seja para um único lote grande de prompts ou para muitos usuários simultâneos interagindo com um modelo em produção.

Por Que Escolher vLLM para Inferência de LLM?

Há várias razões convincentes que fazem do vLLM uma escolha preferencial para desenvolvedores e organizações que trabalham com LLMs:

  1. Desempenho de Última Geração: o vLLM oferece um throughput significativamente mais alto em comparação com muitas implementações de referência. Isso significa que você pode lidar com mais solicitações de usuários simultaneamente ou processar grandes conjuntos de dados mais rapidamente com o mesmo hardware.
  2. Gestão Eficiente de Memória: A inovação central, PagedAttention, reduz drasticamente o desperdício de memória ao gerenciar o cache KV de forma mais eficaz. Isso permite que você encaixe modelos maiores em suas GPUs ou sirva modelos existentes com menos sobrecarga de memória, potencialmente reduzindo os custos de hardware.
  3. Batching Contínuo: Ao contrário do batching estático (onde o servidor espera por um lote completo antes de processar), o vLLM utiliza batching contínuo. Ele processa as solicitações dinamicamente à medida que chegam, melhorando significativamente a utilização da GPU e reduzindo a latência para solicitações individuais.
  4. Servidor Compatível com OpenAI: O vLLM inclui um servidor embutido que imita a API da OpenAI. Isso torna incrivelmente fácil usar o vLLM como um substituto em aplicações já construídas usando o cliente Python da OpenAI ou ferramentas compatíveis. Você pode frequentemente trocar sua URL de endpoint e chave de API, e seu código existente funcionará com sua instância vLLM auto-hospedada.
  5. Facilidade de Uso: Apesar de seus sistemas internos sofisticados, o vLLM oferece uma API relativamente simples tanto para inferência offline (LLM class) quanto para servição online (vllm serve command).
  6. Ampla Compatibilidade de Modelos: O vLLM suporta uma ampla gama de LLMs populares de código aberto disponíveis no Hugging Face Hub (e potencialmente no ModelScope).
  7. Desenvolvimento Ativo e Comunidade: O vLLM é um projeto de código aberto mantido ativamente com uma comunidade crescente, garantindo melhorias contínuas, correções de bugs e suporte para novos modelos e recursos.
  8. Kernels Otimizados: O vLLM utiliza kernels CUDA altamente otimizados para várias operações, aumentando ainda mais o desempenho em GPUs NVIDIA.

Se velocidade, eficiência e escalabilidade são cruciais para sua aplicação de LLM, o vLLM é uma tecnologia que você deve considerar seriamente.

Quais Modelos o vLLM Suporta?

O vLLM suporta uma ampla variedade de modelos baseados em transformadores hospedados no Hugging Face Hub. Isso inclui muitas variantes de:

A lista está em constante crescimento. Para a lista mais atualizada e abrangente de modelos suportados oficialmente, sempre consulte a documentação oficial do vLLM:

Lista de Modelos Suportados pelo vLLM

Se um modelo não estiver listado explicitamente, ele pode ainda funcionar se sua arquitetura for semelhante a uma suportada, mas a compatibilidade não é garantida sem suporte ou teste oficial. Adicionar novas arquiteturas de modelo geralmente requer contribuições de código para o projeto vLLM.

Algumas Terminologias Chave do vLLM:

Embora o vLLM seja fácil de usar à primeira vista, entender alguns de seus conceitos centrais ajuda a apreciar por que ele é tão eficaz:

Essas duas técnicas trabalham juntas de forma sinérgica para fornecer as impressivas características de desempenho do vLLM.

Antes de Começar com o vLLM, Você Precisa Verificar:

Antes de instalar e executar o vLLM, assegure-se de que seu sistema atende aos seguintes requisitos:

  1. Sistema Operacional: Linux é o principal sistema operacional suportado. Embora esforços da comunidade possam existir para outros SOs (como WSL2 no Windows ou macOS), o Linux oferece a experiência mais direta e oficialmente suportada.
  2. Versão do Python: o vLLM requer Python 3.9, 3.10, 3.11 ou 3.12. É altamente recomendado usar um ambiente virtual para gerenciar suas dependências Python.
  3. GPU NVIDIA com CUDA: Para desempenho ideal e acesso aos recursos principais, você precisa de uma GPU NVIDIA com uma capacidade de computação suportada pelo PyTorch e com o kit de ferramentas CUDA necessário instalado. O vLLM depende fortemente do CUDA para seus kernels otimizados. Embora a inferência apenas com CPU e suporte para outros aceleradores (como GPUs AMD ou AWS Inferentia/Trainium) estejam disponíveis ou em desenvolvimento, o caminho principal envolve hardware NVIDIA. Verifique o site oficial do PyTorch para compatibilidade do CUDA com a versão específica do seu driver de GPU.
  4. PyTorch: o vLLM é construído sobre o PyTorch. O processo de instalação geralmente lida com a instalação de uma versão compatível, mas assegure-se de ter uma instalação do PyTorch funcionando que seja compatível com a sua versão do CUDA se você encontrar problemas.

Guia Passo a Passo para Instalar o vLLM

A maneira recomendada para instalar o vLLM é usando um gerenciador de pacotes dentro de um ambiente virtual. Isso evita conflitos com outros projetos Python. Aqui estão os passos usando ferramentas populares:

Usando pip com vLLM

pip é o instalador padrão de pacotes Python.

Criar e Ativar um Ambiente Virtual (Recomendado):

python -m venv vllm-env
source vllm-env/bin/activate
# No Windows use: vllm-env\\\\Scripts\\\\activate

Instalar vLLM:

pip install vllm

Este comando irá baixar e instalar a versão estável mais recente do vLLM e suas dependências principais, incluindo uma versão compatível do PyTorch para a sua configuração do CUDA detectada (se possível).

Usando Conda com vLLM

Conda é outro gerenciador de ambientes e pacotes popular, especialmente na comunidade de ciência de dados.

Criar e Ativar um Ambiente Conda:

conda create -n vllm-env python=3.11 -y # Ou use 3.9, 3.10, 3.12
conda activate vllm-env

Instalar vLLM usando pip dentro do Conda: Geralmente é recomendado usar pip para instalar o vLLM mesmo dentro de um ambiente Conda para garantir que você obtenha a versão compatível mais recente facilmente.

pip install vllm

Você pode precisar instalar o PyTorch separadamente via Conda primeiro se preferir gerenciá-lo dessa forma, garantindo a compatibilidade: conda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia (ajuste a versão do CUDA conforme necessário). Em seguida, execute pip install vllm.

Usando uv com vLLM

uv é um instalador e resolvedor de pacotes Python muito rápido e recente.

Instalar uv (se você ainda não o fez): Siga as instruções na documentação oficial do uv.

Criar e Ativar um Ambiente usando uv:

uv venv vllm-env --python 3.12 --seed # Ou use 3.9, 3.10, 3.11
source vllm-env/bin/activate
# No Windows use: vllm-env\\\\Scripts\\\\activate

Instalar vLLM usando uv:

uv pip install vllm

Verificando Sua Instalação do vLLM

Após a instalação, você pode verificar rapidamente tentando importar o vLLM em um interpretador Python ou executando um comando básico:

# Ative seu ambiente virtual primeiro (por exemplo, source vllm-env/bin/activate)
python -c "import vllm; print(vllm.__version__)"

Isso deve imprimir a versão instalada do vLLM sem erros.

Alternativamente, tente o comando de ajuda para o servidor (requer instalação bem-sucedida):

vllm --help

Realizando Inferência em Lote Offline com vLLM

Inferência em lote offline refere-se à geração de texto para uma lista predefinida de prompts de entrada todos de uma vez. Isso é útil para tarefas como avaliar um modelo, gerar respostas para um conjunto de dados ou pré-computar resultados. O vLLM torna isso eficiente usando sua classe LLM.

Entendendo a Classe LLM do vLLM

A classe vllm.LLM é o principal ponto de entrada para inferência offline. Você a inicializa especificando o modelo que deseja usar.

from vllm import LLM

# Inicialize o motor LLM com um modelo do Hugging Face Hub
# Certifique-se de ter memória GPU suficiente para o modelo escolhido!
# Exemplo: Usando um modelo menor como OPT-125m
llm = LLM(model="facebook/opt-125m")

# Exemplo: Usando um modelo maior como Llama-3-8B-Instruct (requer memória GPU significativa)
# llm = LLM(model="meta-llama/Meta-Llama-3-8B-Instruct")

print("Motor vLLM inicializado.")

Por padrão, o vLLM baixa modelos do Hugging Face Hub. Se seu modelo estiver hospedado no ModelScope, você precisa definir a variável de ambiente VLLM_USE_MODELSCOPE=1 antes de executar seu script Python.

Configurando os Parâmetros de Amostragem do vLLM

Para controlar como o texto é gerado, você usa a classe vllm.SamplingParams. Isso permite que você defina parâmetros como:

from vllm import SamplingParams

# Defina os parâmetros de amostragem
# Se não especificado, o vLLM pode usar os padrões do generation_config.json do modelo
sampling_params = SamplingParams(
    temperature=0.7,
    top_p=0.9,
    max_tokens=100, # Limite o comprimento do texto gerado
    stop=["\\\\n", " Humano:", " Assistente:"] # Pare a geração se esses tokens aparecerem
)

print("Parâmetros de amostragem configurados.")

Nota Importante: Por padrão, o vLLM tenta carregar e usar configurações do arquivo generation_config.json associado ao modelo no Hugging Face Hub. Se você deseja ignorar isso e usar os parâmetros de amostragem padrão do vLLM, a menos que sejam substituídos pelo seu objeto SamplingParams, inicialize a classe LLM assim: llm = LLM(model="...", generation_config="vllm"). Se você for fornecer um objeto SamplingParams para o método generate, esses parâmetros sempre terão precedência sobre a config do modelo e os padrões do vLLM.

Executando Seu Primeiro Trabalho em Lote vLLM

Agora, vamos combinar o objeto LLM, SamplingParams e uma lista de prompts para gerar texto.

from vllm import LLM, SamplingParams

# 1. Defina seus prompts de entrada
prompts = [
    "A capital da França é",
    "Explique a teoria da relatividade em termos simples:",
    "Escreva um poema curto sobre um dia chuvoso:",
    "Traduza 'Olá, mundo!' para o alemão:",
]

# 2. Configure os parâmetros de amostragem
sampling_params = SamplingParams(temperature=0.7, top_p=0.95, max_tokens=150)

# 3. Inicialize o motor vLLM (use um modelo adequado para seu hardware)
try:
    # Usando um modelo relativamente pequeno e capaz
    llm = LLM(model="mistralai/Mistral-7B-Instruct-v0.1")
    # Ou para GPUs menores:
    # llm = LLM(model="facebook/opt-1.3b")
    # llm = LLM(model="facebook/opt-125m")
except Exception as e:
    print(f"Erro ao inicializar LLM: {e}")
    print("Por favor, certifique-se de ter memória GPU suficiente e que o CUDA está configurado corretamente.")
    exit()

# 4. Gere texto para os prompts
# O método generate recebe a lista de prompts e parâmetros de amostragem
print("Gerando respostas...")
outputs = llm.generate(prompts, sampling_params)
print("Geração concluída.")

# 5. Imprima os resultados
# A saída é uma lista de objetos RequestOutput
for output in outputs:
    prompt = output.prompt
    generated_text = output.outputs[0].text # Obtenha o texto da primeira sequência gerada
    print("-" * 20)
    print(f"Prompt: {prompt!r}")
    print(f"Texto Gerado: {generated_text!r}")
    print("-" * 20)

Este script inicializa o vLLM, define prompts e parâmetros, executa o processo de geração de forma eficiente em lote e, em seguida, imprime a saída para cada prompt. A chamada llm.generate() lida com as complexidades do batching e da execução na GPU internamente.

Configurando o Servidor Compatível com OpenAI do vLLM

Um dos recursos mais poderosos do vLLM é sua capacidade de atuar como um servidor backend de alto desempenho que se comunica na mesma linguagem da API da OpenAI. Isso permite que você hospede facilmente seus próprios modelos de código aberto e os integre em aplicativos projetados para OpenAI.

Iniciando o Servidor vLLM

Iniciar o servidor é simples usando o comando vllm serve no seu terminal.

Ative seu ambiente virtual onde o vLLM está instalado.

source vllm-env/bin/activate

Execute o comando vllm serve: Você precisa especificar o modelo que deseja servir.

# Exemplo usando Mistral-7B-Instruct
vllm serve mistralai/Mistral-7B-Instruct-v0.1

# Exemplo usando um modelo menor como Qwen2-1.5B-Instruct
# vllm serve Qwen/Qwen2-1.5B-Instruct

Este comando irá:

Opções Comuns:

O servidor exibirá logs indicando que está em execução e pronto para aceitar solicitações.

Interagindo com o Servidor vLLM: API de Completions

Uma vez que o servidor esteja em execução, você pode enviar solicitações para seu endpoint /v1/completions, assim como faria com a API de completions mais antiga da OpenAI.

Usando curl:

curl <http://localhost:8000/v1/completions> \\\\
    -H "Content-Type: application/json" \\\\
    -d '{
        "model": "mistralai/Mistral-7B-Instruct-v0.1",
        "prompt": "São Francisco é uma cidade em",
        "max_tokens": 50,
        "temperature": 0.7
    }'

(Substitua "mistralai/Mistral-7B-Instruct-v0.1" pelo nome real do modelo que você está servindo)

Usando a Biblioteca Python openai:

from openai import OpenAI

# Direcione o cliente para seu endpoint do servidor vLLM
client = OpenAI(
    api_key="EMPTY", # Use "EMPTY" ou sua chave real se você configurar uma com --api-key
    base_url="<http://localhost:8000/v1>"
)

print("Enviando solicitação para o servidor vLLM (Completions)...")

try:
    completion = client.completions.create(
        model="mistralai/Mistral-7B-Instruct-v0.1", # O nome do modelo deve corresponder ao que está sendo servido
        prompt="Explique os benefícios de usar vLLM:",
        max_tokens=150,
        temperature=0.5
    )

    print("Resposta:")
    print(completion.choices[0].text)

except Exception as e:
    print(f"Ocorreu um erro: {e}")

(Lembre-se de substituir o nome do modelo se você estiver servindo um diferente)

Interagindo com o Servidor vLLM: API de Chat Completions

O vLLM também suporta o mais moderno endpoint /v1/chat/completions, adequado para modelos conversacionais e formatos de mensagens estruturados (funções de sistema, usuário, assistente).

Usando curl:

curl <http://localhost:8000/v1/chat/completions> \\\\
    -H "Content-Type: application/json" \\\\
    -d '{
        "model": "mistralai/Mistral-7B-Instruct-v0.1",
        "messages": [
            {"role": "system", "content": "Você é um assistente útil."},
            {"role": "user", "content": "Qual é a principal vantagem do PagedAttention no vLLM?"}
        ],
        "max_tokens": 100,
        "temperature": 0.7
    }'

(Substitua o nome do modelo conforme necessário)

Usando a Biblioteca Python openai:

from openai import OpenAI

# Direcione o cliente para seu endpoint do servidor vLLM
client = OpenAI(
    api_key="EMPTY", # Use "EMPTY" ou sua chave real
    base_url="<http://localhost:8000/v1>"
)

print("Enviando solicitação para o servidor vLLM (Chat Completions)...")

try:
    chat_response = client.chat.completions.create(
        model="mistralai/Mistral-7B-Instruct-v0.1", # O nome do modelo deve corresponder ao que está sendo servido
        messages=[
            {"role": "system", "content": "Você é um assistente de programação útil."},
            {"role": "user", "content": "Escreva uma função Python simples para calcular o fatorial."}
        ],
        max_tokens=200,
        temperature=0.5
    )

    print("Resposta:")
    print(chat_response.choices[0].message.content)

except Exception as e:
    print(f"Ocorreu um erro: {e}")

(Lembre-se de substituir o nome do modelo se necessário)

Usar o servidor compatível com a OpenAI é uma maneira poderosa de implantar endpoints de inferência LLM de alto desempenho com mudanças mínimas na lógica de aplicação existente.

Vamos Falar Sobre os Backends de Atenção do vLLM

O vLLM utiliza "backends" especializados para calcular o mecanismo de atenção de forma eficiente. Esses backends são implementações otimizadas que aproveitam diferentes bibliotecas ou técnicas, visando principalmente GPUs NVIDIA. A escolha do backend pode impactar o desempenho e o uso de memória. Os principais incluem:

  1. FlashAttention: Usa a biblioteca FlashAttention (versões 1 e 2). FlashAttention é um algoritmo de atenção altamente otimizado que acelera significativamente a computação e reduz o uso de memória ao evitar a necessidade de materializar a grande matriz de atenção intermediária na Memória de Alta Largura de Banda (HBM) da GPU. É frequentemente a opção mais rápida para muitas GPUs modernas (como arquiteturas Ampere, Hopper) e comprimentos de sequência. O vLLM geralmente inclui rodas pré-construídas com suporte ao FlashAttention.
  2. Xformers: Aproveita a biblioteca xFormers, desenvolvida pela Meta AI. O xFormers também fornece implementações de atenção otimizadas e eficientes em memória (como MemoryEfficientAttention). Ele oferece ampla compatibilidade entre várias arquiteturas de GPU e pode ser uma boa alternativa ou fallback se o FlashAttention não estiver disponível ou não for ideal para um cenário específico. A instalação padrão do vLLM geralmente inclui suporte ao xFormers.
  3. FlashInfer: Uma opção de backend mais recente que utiliza a biblioteca FlashInfer. O FlashInfer fornece kernels altamente otimizados especificamente adaptados para implantar LLMs, focando em vários cenários de pré-preenchimento e decodificação, incluindo recursos como decodificação especulativa e manipulação eficiente de caches KV paginados. Normalmente, não há rodas pré-construídas do vLLM contendo o FlashInfer, o que significa que você deve instalá-lo separadamente em seu ambiente antes que o vLLM possa usá-lo. Consulte a documentação oficial do FlashInfer ou os Dockerfiles do vLLM para obter instruções de instalação se você pretende usar este backend.

Seleção Automática de Backend: Por padrão, o vLLM detecta automaticamente o backend de atenção mais adequado e performático com base no seu hardware (arquitetura da GPU), bibliotecas instaladas (o FlashAttention/xFormers/FlashInfer está disponível?) e o modelo específico sendo utilizado. Ele realiza verificações para garantir compatibilidade e visa fornecer o melhor desempenho imediato sem configuração manual.

Seleção Manual de Backend: Em alguns casos de uso avançados ou para fins de benchmarking, você pode querer forçar o vLLM a usar um backend específico. Você pode fazer isso definindo a variável de ambiente VLLM_ATTENTION_BACKEND antes de iniciar seu processo vLLM (seja o script offline ou o servidor).

# Exemplo: Forçar o uso do FlashAttention (se instalado e compatível)
export VLLM_ATTENTION_BACKEND=FLASH_ATTN
python seu_script_offline.py
# ou
# export VLLM_ATTENTION_BACKEND=FLASH_ATTN
# vllm serve seu_modelo ...

# Exemplo: Forçar o uso do xFormers
export VLLM_ATTENTION_BACKEND=XFORMERS
python seu_script_offline.py

# Exemplo: Forçar o uso do FlashInfer (requer instalação prévia)
export VLLM_ATTENTION_BACKEND=FLASHINFER
python seu_script_offline.py

Para a maioria dos iniciantes, é recomendado confiar na seleção automática de backend do vLLM. Configurar o backend manualmente é tipicamente reservado para experimentação ou resolução de problemas de desempenho específicos.

Solução de Problemas Comuns de Instalação e Uso do vLLM

Embora o vLLM tenha como objetivo a facilidade de uso, você pode encontrar alguns obstáculos comuns, especialmente durante a configuração. Aqui estão alguns problemas frequentes e suas possíveis soluções:

  1. Erros de Memória da CUDA (OOM):
  1. Erros de Instalação (Compatibilidade CUDA/PyTorch):
  1. Falhas ao Carregar Modelos:
  1. Desempenho Lento:
  1. Saída Incorreta ou Incoerente:

Consultar a documentação oficial do vLLM e a página de Issues do GitHub do projeto também é altamente recomendado ao enfrentar problemas.

Conclusão: Sua Jornada com o vLLM

Parabéns! Você deu seus primeiros passos no mundo da inferência LLM de alto desempenho com vLLM. Nós cobrimos os conceitos fundamentais, desde a compreensão do que é vLLM e por que sua tecnologia PagedAttention é revolucionária, até os passos práticos de instalação e uso.

Agora você sabe como:

vLLM reduz significativamente a barreira para implantar poderosos LLMs de forma eficiente. Ao aproveitar sua velocidade e otimização de memória, você pode construir aplicações de IA mais rápidas, escaláveis e potencialmente mais econômicas. Seja processando grandes conjuntos de dados ou construindo agentes conversacionais em tempo real, vLLM fornece o motor para atender suas necessidades de inferência de LLM.

Este guia fornece uma base sólida, mas o ecossistema vLLM é rico em recursos mais avançados, como suporte a quant

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar