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:

• Llama (Llama, Llama 2, Llama 3)
• Mistral & Mixtral
• Qwen & Qwen2
• GPT-2, GPT-J, GPT-NeoX
• OPT
• Bloom
• Falcon
• MPT
• E muitos outros, incluindo modelos multimodais.

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:

• PagedAttention: Este é o recurso principal do vLLM. Em mecanismos de atenção tradicionais, o cache de Key-Value (KV) (que armazena resultados intermediários para geração) requer blocos de memória contíguos. Isso leva à fragmentação e desperdício de memória (interna e externa). PagedAttention funciona como memória virtual em sistemas operacionais. Ele divide o cache KV em blocos não contíguos (páginas), permitindo uma gestão de memória muito mais flexível e eficiente. Reduz significativamente a sobrecarga de memória (em até 90% em alguns casos relatados pelos desenvolvedores) e habilita recursos como prefixos compartilhados sem duplicação de memória.
• Batching Contínuo: Em vez de esperar um número fixo de solicitações chegarem antes de iniciar o cálculo (batching estático), o batching contínuo permite que o motor vLLM comece a processar novas sequências assim que as antigas terminam de gerar tokens dentro de um lote. Isso mantém a GPU constantemente ocupada, maximizando o throughput e reduzindo o tempo médio de espera para solicitações.

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:

• temperature: Controla a aleatoriedade. Valores mais baixos (por exemplo, 0.2) tornam a saída mais determinística e focada; valores mais altos (por exemplo, 0.8) aumentam a aleatoriedade.
• top_p (Amostragem de Núcleo): Considera apenas os tokens mais prováveis cuja probabilidade cumulativa excede top_p. Um valor comum é 0.95.
• top_k: Considera apenas os top_k tokens mais prováveis a cada passo.
• max_tokens: O número máximo de tokens a gerar para cada prompt.
• stop: Uma lista de strings que, quando geradas, interromperão o processo de geração para esse prompt específico.

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á:

• Baixar o modelo especificado (se ainda não estiver em cache).
• Carregar o modelo em sua(s) GPU(s).
• Iniciar um servidor web (usando Uvicorn por padrão).
• Escutar por solicitações de API recebidas, tipicamente em http://localhost:8000.

Opções Comuns:

• -model <nome_ou_caminho_do_modelo>: (Requerido) O modelo a ser servido.
• -host <endereço_ip>: O endereço IP ao qual o servidor deve se ligar (por exemplo, 0.0.0.0 para torná-lo acessível na sua rede). O padrão é localhost.
• -port <número_da_porta>: A porta a ser escutada. O padrão é 8000.
• -tensor-parallel-size <N>: Para servição em múltiplas GPUs, divide o modelo entre N GPUs.
• -api-key <sua_chave>: Se definido, o servidor esperará esta chave de API no cabeçalho Authorization: Bearer <sua_chave> das solicitações recebidas. Você também pode definir a variável de ambiente VLLM_API_KEY.
• -generation-config vllm: Use os parâmetros de amostragem padrão do vLLM em vez do generation_config.json do modelo.
• -chat-template <caminho_para_arquivo_template>: Use um arquivo template de chat Jinja personalizado em vez do definido na configuração do tokenizador.

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):

• Problema: Você vê erros como torch.cuda.OutOfMemoryError: CUDA out of memory.
• Causa: O LLM que você está tentando carregar requer mais VRAM da GPU do que está disponível em seu hardware. Modelos maiores (por exemplo, 7B parâmetros ou mais) consomem memória significativa.
• Soluções:
• Use um Modelo Menor: Tente carregar uma variante menor (por exemplo, opt-1.3b, Qwen/Qwen2-1.5B-Instruct) primeiro para confirmar que sua configuração funciona.
• Reduza o Tamanho do Lote (Servidor): Embora o vLLM gerencie o batching dinamicamente, uma concorrência muito alta ainda pode exceder a memória. Monitore o uso.
• Use Quantização: Carregue versões quantizadas do modelo (por exemplo, AWQ, GPTQ, GGUF - consulte a documentação do vLLM para tipos de quantização suportados). A quantização reduz a pegada de memória, frequentemente com uma pequena troca na precisão. Exemplo: llm = LLM(model="TheBloke/Mistral-7B-Instruct-v0.1-AWQ"). Note que bibliotecas específicas de quantização podem precisar ser instaladas.
• Paralelismo de Tensor: Se você tiver várias GPUs, use o argumento -tensor-parallel-size N ao lançar o servidor ou tensor_parallel_size=N ao inicializar a classe LLM para distribuir o modelo entre N GPUs.
• Verifique Outros Processos: Certifique-se de que nenhum outro aplicativo esté consumindo uma quantidade significativa de memória da GPU. Use nvidia-smi no terminal para verificar o uso de memória.

1. Erros de Instalação (Compatibilidade CUDA/PyTorch):

• Problema: pip install vllm falha com erros relacionados à CUDA, PyTorch ou compilação de extensões.
• Causa: Desencontro entre o driver NVIDIA instalado, a versão do CUDA Toolkit e a versão do PyTorch que o vLLM está tentando instalar ou usar.
• Soluções:
• Verifique a Compatibilidade: Assegure-se de que a versão do seu driver NVIDIA suporta a versão do CUDA Toolkit exigida pela construção do PyTorch que você pretende usar. Consulte a matriz de instalação do site do PyTorch.
• Instale o PyTorch Manualmente: Às vezes, instalar explicitamente uma versão compatível do PyTorch antes de instalar o vLLM ajuda. Vá para o site oficial do PyTorch, selecione seu SO, gerenciador de pacotes (pip/conda), plataforma de computação (versão do CUDA) e execute o comando fornecido. Em seguida, pip install vllm.
• Use a Imagem Docker Oficial: Considere usar as imagens Docker oficiais do vLLM. Elas vêm pré-configuradas com versões compatíveis do CUDA, PyTorch e vLLM, evitando problemas de instalação local. Confira o Docker Hub para vllm/vllm-openai.
• Verifique as Ferramentas de Compilação: Assegure-se de que você tem as ferramentas de compilação necessárias instaladas (build-essential no Debian/Ubuntu ou equivalente).

1. Falhas ao Carregar Modelos:

• Problema: o vLLM não consegue carregar o modelo especificado, talvez com erros de "não encontrado" ou problemas de configuração.
• Causa: Nome/caminho do modelo incorreto, o modelo requer confiança em código remoto, problemas de formato do modelo ou problemas de rede que impedem o download.
• Soluções:
• Verifique o Nome do Modelo: Verifique o identificador exato do Hugging Face Hub (por exemplo, mistralai/Mistral-7B-Instruct-v0.1).
• Confie no Código Remoto: Alguns modelos requerem a execução de código personalizado definido em seu repositório. Para a classe LLM, use trust_remote_code=True. Para o servidor, use a flag -trust-remote-code: vllm serve meu_modelo --trust-remote-code. Faça isso somente se você confiar na fonte do modelo.
• Use o Caminho Local: Se você tiver o modelo baixado localmente, forneça o caminho para o diretório que contém os arquivos do modelo e a configuração do tokenizador: llm = LLM(model="/caminho/para/modelo/local").
• Verifique o Espaço em Disco: Assegure-se de que você tenha espaço em disco suficiente para baixar os pesos do modelo (podem ser dezenas de GBs).
• Problemas de Rede: Verifique sua conexão com a internet. Se estiver atrás de um proxy, configure as variáveis de ambiente HTTP_PROXY e HTTPS_PROXY.

1. Desempenho Lento:

• Problema: A velocidade de inferência é muito menor do que o esperado.
• Causa: Backend de atenção subótimo selecionado, fallback na CPU, parâmetros de amostragem ineficientes, gargalos no sistema.
• Soluções:
• Verifique a Utilização da GPU: Use nvidia-smi ou nvtop para ver se a GPU está sendo totalmente utilizada durante a inferência. Se não, o gargalo pode estar em outro lugar (pré-processamento da CPU, carregamento de dados).
• Atualize o vLLM & Dependências: Assegure-se de que você está usando as versões mais recentes do vLLM, PyTorch, drivers CUDA e bibliotecas como FlashAttention/xFormers.
• Experimente com Backends de Atenção: Embora a seleção automática geralmente seja boa, tente definir manualmente VLLM_ATTENTION_BACKEND (veja a seção anterior) para ver se outro backend tem um desempenho melhor na sua combinação específica de hardware/modelo.
• Revise os Parâmetros de Amostragem: Valores muito grandes de max_tokens podem levar a tempos de geração mais longos por solicitação.

1. Saída Incorreta ou Incoerente:

• Problema: O modelo gera texto sem sentido, repete-se excessivamente ou não segue instruções.
• Causa: Formatação de prompt incorreta (especialmente para modelos de instruções/chat), parâmetros de amostragem inadequados, problemas com os pesos do modelo em si, ou aplicação incorreta do template de chat.
• Soluções:
• Verifique o Formato do Prompt: Assegure-se de que seus prompts estão de acordo com o formato que o modelo específico foi treinado (por exemplo, usando tokens especiais como [INST], <s>, </s> para modelos de instrução Llama/Mistral). Consulte o cartão do modelo no Hugging Face para instruções de formatação.
• Ajuste os Parâmetros de Amostragem: Alta temperature pode levar à incoerência. Temperaturas muito baixas podem causar repetição. Experimente com temperature, top_p, top_k e repetition_penalty.
• Verifique o Modelo: Tente um modelo diferente, conhecido por funcionar bem, para descartar problemas com os pesos do modelo específico que você baixou.
• Templates de Chat (Servidor): Ao usar a API de chat completions, certifique-se de que o template de chat correto está sendo aplicado. O vLLM geralmente carrega isso da configuração do tokenizador. Se os problemas persistirem, você pode precisar fornecer um template personalizado usando o argumento -chat-template durante o lançamento do servidor.

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:

• Instalar vLLM usando gerenciadores de pacotes padrão como pip, Conda ou uv dentro de ambientes isolados.
• Realizar inferência em lote offline de forma eficiente usando as classes LLM e SamplingParams do vLLM.
• Lançar e interagir com o servidor compatível com OpenAI do vLLM, permitindo integração sem costura com aplicações existentes usando as APIs de completions e chat completions.
• Apreciação do papel de diferentes backends de atenção (FlashAttention, xFormers, FlashInfer) e como o vLLM otimiza sua seleção.
• Resolver alguns dos problemas comuns que iniciantes enfrentam ao trabalhar com vLLM e modelos grandes.

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