Implementação com vLLM
Nesta página
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
| Flag | Propósito |
|---|---|
--tokenizer_mode mistral | Utiliza o tokenizador nativo da Mistral (não o do HF) |
--config_format mistral | Carrega a configuração no formato Mistral |
--load_format mistral | Carrega 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
openaipara comunicar - As três flags
--tokenizer_mode mistral,--config_format mistral,--load_format mistralsã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