Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Implementação com vLLM

Aula 11 de 14 Atualizada a 29 de julho de 2026 Avancado
Nesta página
  1. vLLM: O Motor de Inferência Recomendado
  2. O Que Vai Precisar
  3. Modo Offline: Processamento em Lote
  4. Modo Servidor: Expor uma API
  5. Implementação com Docker
  6. As Três Flags Essenciais da Mistral
  7. Ajuste de Desempenho
  8. Pontos-chave

vLLM: O Motor de Inferência Recomendado

O vLLM é o motor de inferência Python mais popular para LLMs. A Mistral AI recomenda-o para autoalojamento (self-hosting) devido à sua facilidade de utilização, bom desempenho e oferta de uma API compatível com a OpenAI. Vamos percorrer a instalação e configuração, abordando depois os seus dois modos de utilização: modo em lote (batch, offline) e modo servidor. Estes modos não são mutuamente exclusivos; muitas equipas utilizam o primeiro para preparar dados e o segundo para servir aplicações.

O Que Vai Precisar

A transferência de modelos ocorre através do Hugging Face, o que exige um token com permissão READ:

export HF_TOKEN="hf_your_token_here"

Antes da sua primeira transferência, aceite os termos de utilização na página do modelo no Hugging Face (por exemplo: huggingface.co/mistralai/Mistral-Nemo-Instruct-2407). Trata-se de um passo manual único por conta. Esquecer-se disto provoca falhas na transferência que podem levar uma hora a diagnosticar, pois parecem problemas de autenticação.

Para o ambiente Python, utilize um virtualenv dedicado para evitar conflitos de versão com os seus outros projetos:

# Criar um ambiente virtual
python -m venv vllm-env
source vllm-env/bin/activate

# Instalar o vLLM (versão >= 0.6.1.post1)
pip install vllm

Depois, há o hardware, que determina o que consegue realmente servir. O Mistral 7B e o Nemo cabem numa única GPU de 24 GB, tipicamente uma A10G, RTX 4090 ou L4. O Mixtral 8x7B requer duas GPUs de 80 GB, na prática placas A100-80GB. O Mistral Large 2, na sua versão de pesos abertos, com os seus 123 mil milhões de parâmetros, necessita de pelo menos quatro GPUs A100-80GB. Em todos os casos, instale os controladores NVIDIA e o CUDA 12.x antes do vLLM.

Modo Offline: Processamento em Lote

O modo offline gere lotes de pedidos sem um servidor HTTP. Carrega o modelo na memória, processa os seus pedidos e recupera os resultados. Note os três argumentos tokenizer_mode, load_format e config_format: voltaremos a eles, não são opcionais.

from vllm import LLM
from vllm.sampling_params import SamplingParams

# Carregar o modelo com as flags da Mistral
llm = LLM(
    model="mistralai/Mistral-Nemo-Instruct-2407",
    tokenizer_mode="mistral",
    load_format="mistral",
    config_format="mistral"
)

# Parâmetros de geração
sampling = SamplingParams(
    max_tokens=8192,
    temperature=0.3
)

# Processar um lote de pedidos
messages_batch = [
    [{"role": "user", "content": "What is PagedAttention?"}],
    [{"role": "user", "content": "Explain tensor parallelism."}],
    [{"role": "user", "content": "How does the KV cache work?"}],
]

results = llm.chat(messages=messages_batch[0], sampling_params=sampling)
for output in results:
    print(output.outputs[0].text)

Este modo destaca-se no processamento de documentos em lote — resumo, classificação — avaliação de modelos face a benchmarks, geração de dados sintéticos e scripts de teste ou prototipagem. Sempre que ninguém espera uma resposta imediata, beneficia de ignorar a camada HTTP.

Modo Servidor: Expor uma API

O modo servidor lança um ponto final HTTP compatível com a API da OpenAI:

vllm serve mistralai/Mistral-Nemo-Instruct-2407 \
    --tokenizer_mode mistral \
    --config_format mistral \
    --load_format mistral \
    --host 0.0.0.0 \
    --port 8000

O servidor expõe a API na porta 8000. A consequência prática é significativa: uma aplicação escrita para a API da OpenAI muda para o seu modelo autoalojado alterando apenas duas linhas, base_url e api_key. As suas bibliotecas, estruturas de agentes e ferramentas de teste continuam a funcionar.

from openai import OpenAI

# Ligar ao servidor vLLM local
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed"  # Sem autenticação por defeito
)

response = client.chat.completions.create(
    model="mistralai/Mistral-Nemo-Instruct-2407",
    messages=[
        {"role": "system", "content": "You are a DevOps expert."},
        {"role": "user", "content": "How do I monitor a vLLM server in production?"}
    ],
    temperature=0.3,
    max_tokens=1024
)
print(response.choices[0].message.content)

O comentário # Sem autenticação por defeito merece atenção: um servidor vLLM lançado desta forma não autentica ninguém. Num computador de desenvolvimento, isso é conveniente. Num computador acessível pela rede, é uma porta aberta. Um teste rápido na linha de comandos confirma que tudo responde antes de avançar:

curl http://localhost:8000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "mistralai/Mistral-Nemo-Instruct-2407",
        "messages": [{"role": "user", "content": "Hello, is this working?"}],
        "temperature": 0.3
    }'

Implementação com Docker

Para uma implementação reproduzível, a imagem oficial evita a reinstalação em cada máquina:

docker run --runtime nvidia --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HUGGING_FACE_HUB_TOKEN=${HF_TOKEN}" \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:latest \
    --model mistralai/Mistral-Nemo-Instruct-2407 \
    --tokenizer_mode mistral \
    --load_format mistral \
    --config_format mistral

Três opções neste comando merecem explicação. --runtime nvidia --gpus all dá ao contentor acesso às GPUs NVIDIA; sem isto, o modelo tentaria correr no CPU. A montagem -v ~/.cache/huggingface:... partilha a cache do modelo com o anfitrião, poupando-o de voltar a transferir dezenas de gigabytes sempre que o contentor reinicia. --ipc=host concede a memória partilhada necessária para a comunicação entre processos entre GPUs; omiti-la provoca falhas difíceis de diagnosticar assim que passa para múltiplas placas.

As Três Flags Essenciais da Mistral

FlagPropósito
--tokenizer_mode mistralUtiliza o tokenizador nativo da Mistral (não o do HF)
--config_format mistralCarrega a configuração no formato Mistral
--load_format mistralCarrega os pesos no formato nativo Mistral

Sem estas flags, o modelo pode correr, mas com desempenho degradado ou resultados incorretos. Esta é a armadilha mais comum no autoalojamento da Mistral: nada falha, o servidor inicia, as respostas chegam — são apenas piores do que deveriam ser, e corre o risco de concluir erradamente que o modelo é dececionante.

Ajuste de Desempenho

Quando um modelo não cabe numa única placa, o paralelismo de tensores distribui as suas camadas por várias GPUs. O valor passado corresponde ao número de placas utilizadas:

vllm serve mistralai/Mixtral-8X7B-Instruct-v0.1 \
    --tokenizer_mode mistral \
    --config_format mistral \
    --load_format mistral \
    --tensor-parallel-size 2

A segunda alavanca diz respeito à proporção de memória GPU que o vLLM reserva:

vllm serve mistralai/Mistral-Nemo-Instruct-2407 \
    --tokenizer_mode mistral \
    --config_format mistral \
    --load_format mistral \
    --gpu-memory-utilization 0.9

O valor por defeito (0.9) funciona na maioria dos casos. Reduza-o se outros processos utilizarem a GPU — um serviço de visão, um notebook esquecido — caso contrário, o primeiro processo toma toda a memória e o segundo falha ao iniciar.

Finalmente, duas chamadas bastam para verificar se um servidor está ativo, tornando-as boas sondas para o seu orquestrador:

# Listar modelos disponíveis
curl http://localhost:8000/v1/models

# Verificar a saúde do servidor
curl http://localhost:8000/health

Pontos-chave

  • O vLLM expõe uma API compatível com a OpenAI — pode utilizar o SDK openai para comunicar
  • As três flags --tokenizer_mode mistral, --config_format mistral, --load_format mistral são obrigatórias
  • O modo offline adequa-se ao processamento em lote; o modo servidor adequa-se a aplicações em tempo real
  • O Docker simplifica a implementação e garante a reprodutibilidade
  • O paralelismo de tensores permite distribuir modelos grandes por várias GPUs