Montar um Servidor de Inferência: vLLM, llama.cpp, SGLang

O hardware chega, o driver funciona, o nvidia-smi mostra todas as placas. A questão agora é o que serve efetivamente tokens. A resposta é uma de quatro ou cinco stacks de serving abertas, e a escolha errada custa 2× de débito, 3× de latência ou três dias de depuração. Este artigo escolhe entre elas com honestidade e percorre a instalação daquela que a maioria dos clientes Kentino deve escolher primeiro: vLLM em Docker, com a imagem validada pela NGC, num endpoint compatível com OpenAI.

Público-alvo: quem já leu o L02, consegue executar docker run --gpus all nvidia-smi e precisa agora da camada seguinte.

A matriz de decisão

Cinco stacks a considerar em maio de 2026. Tudo o resto é um wrapper à volta de uma destas ou um projeto de investigação.

A versão curta e assumida: se não tiver a certeza, execute o vLLM no contentor NGC. Se a sua carga de trabalho assentar em saída estruturada ou em prompts de sistema partilhados, use o SGLang. Se estiver num Jetson ou numa máquina de desenvolvimento com uma única 4090, use o llama.cpp. Todo o resto é um caso de canto.

O vLLM é a opção por omissão — e a razão

O vLLM (v0.20+ em maio de 2026) é a stack de serving aberta mais implementada para LLM e VLM transformer. Três pontos dão-lhe a liderança:

1. Batching contínuo — os pedidos que chegam juntam-se a um batch em curso na passagem seguinte. A utilização da GPU num endpoint com tráfego misto sobe de 40% para mais de 85% face à inferência HuggingFace com batching ingénuo.
2. PagedAttention mais cache de prefixos — a cache KV é gerida em blocos de tamanho fixo, como as páginas de memória virtual de um sistema operativo. Dois pedidos que partilhem um prompt de sistema partilham os blocos KV desse prefixo. Em fluxos de agentes com prompts de sistema de 2 KB, a taxa de acerto da cache de prefixos ronda os 80–95%.
3. Kernels pensados primeiro para Blackwell — FlashAttention 3, atenção FP8, quantização MXFP4 só de pesos e o caminho de matmul baseado em CUTLASS visam sm_120 (5090, RTX Pro 6000 Blackwell) e sm_100 (B200) de forma nativa.

O CUDA 13 é a predefinição nas wheels PyPI da v0.20+ e na imagem vllm/vllm-openai:latest. As wheels de CUDA 12.8 continuam disponíveis como alternativa para sm_120.

Instalar o vLLM: pip ou Docker

Dois caminhos de instalação. Escolha Docker, salvo razão concreta em contrário.

Caminho A — pip num venv (apenas desenvolvimento)

python3.12 -m venv ~/venvs/vllm && source ~/venvs/vllm/bin/activate
pip install --upgrade pip && pip install vllm   # wheels CUDA 13.0 por omissão

vllm serve meta-llama/Llama-3.3-70B-Instruct-FP8 --tensor-parallel-size 4 --port 8000

O pip funciona e é mais rápido para iterar sobre as flags do motor. Também fixa o interpretador Python, o runtime CUDA e a compatibilidade driver-runtime a uma única configuração de host. Use-o em desenvolvimento; não em produção.

Caminho B — Docker com a imagem upstream (predefinição de produção)

docker run --gpus all --runtime nvidia \
  --ipc=host \
  -p 8000:8000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -e HUGGING_FACE_HUB_TOKEN=$HF_TOKEN \
  vllm/vllm-openai:latest \
  --model meta-llama/Llama-3.3-70B-Instruct-FP8 \
  --tensor-parallel-size 4 \
  --gpu-memory-utilization 0.92 \
  --max-model-len 8192 \
  --enable-prefix-caching

Notas que apanham quem as ignora:

• --ipc=host é obrigatório em multi-GPU. Os workers do vLLM comunicam por memória partilhada; o namespace IPC por omissão do Docker tem 64 MB e não comporta os buffers do NCCL.
• Monte a cache do HuggingFace. Caso contrário, cada docker run volta a descarregar 75 GB de pesos.
• Fixe uma tag em produção: vllm/vllm-openai:v0.20.2 e não :latest.

A imagem nvcr.io/nvidia/vllm:25.09-py3 da NGC traz CUDA 13.0, uma build testada do vLLM, NCCL e o selo de QA da NVIDIA. É maior (~12 GB) e está um ou dois meses atrás do upstream. Use-a se também executar TensorRT-LLM ou Triton no mesmo host e quiser uma só stack CUDA/NCCL para todos. Caso contrário, a imagem do Docker Hub é mais pequena, mais recente e equivalente.

As flags que realmente contam

O vLLM expõe cerca de duzentas flags de linha de comandos. A maioria é situacional. As que vai mexer sempre:

A flag --gpu-memory-utilization é a mais afinada de todas. O vLLM usa-a para decidir quanta VRAM pré-aloca depois de carregar os pesos; o que sobra torna-se a pool de cache KV. Valor demasiado baixo → preempção prematura da KV sob carga. Demasiado alto → OOM no primeiro pedido de contexto longo. 0.92 é um ponto de partida razoável numa máquina dedicada a inferência. Baixe para 0.85 se partilhar a GPU.

Três comandos de arranque concretos

Estas são as configurações que os clientes Kentino executam na prática. Todas pressupõem CUDA 13.0, driver 570+, a imagem Docker e --ipc=host.

Qwen 2.5 72B Instruct INT4 (AWQ) em 4× RTX Pro 6000 Blackwell

docker run --gpus all --runtime nvidia --ipc=host \
  -p 8000:8000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -e HUGGING_FACE_HUB_TOKEN=$HF_TOKEN \
  vllm/vllm-openai:v0.20.2 \
  --model Qwen/Qwen2.5-72B-Instruct-AWQ \
  --quantization awq \
  --tensor-parallel-size 4 \
  --max-model-len 32768 \
  --gpu-memory-utilization 0.92 \
  --enable-prefix-caching \
  --max-num-seqs 64 \
  --port 8000

Cerca de 36 GB de pesos em INT4, 4 placas de 96 GB. Com TP=4, cada placa recebe 1/4 da KV por pedido, pelo que 32 K de contexto com 64 utilizadores em simultâneo fica bem dentro do orçamento. Conte com 40–60 tok/s por pedido em baixa concorrência e um agregado de ~600–900 tok/s com 32 em simultâneo.

Llama 3.3 70B Instruct FP8 em 8× RTX 5090

docker run --gpus all --runtime nvidia --ipc=host \
  -p 8000:8000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -e HUGGING_FACE_HUB_TOKEN=$HF_TOKEN \
  vllm/vllm-openai:v0.20.2 \
  --model meta-llama/Llama-3.3-70B-Instruct-FP8 \
  --quantization fp8 \
  --tensor-parallel-size 4 \
  --pipeline-parallel-size 2 \
  --max-model-len 8192 \
  --gpu-memory-utilization 0.90 \
  --enable-prefix-caching \
  --max-num-seqs 64 \
  --swap-space 4 \
  --port 8000

Repare em TP=4 × PP=2, e não TP=8. As 5090 têm 32 GB cada; os pesos FP8 do 70B ocupam ~75 GB, folgadamente abaixo dos 128 GB de quatro placas. A divisão em pipeline evita a explosão de all-reduce que TP=8 sobre PCIe traria (ver K03, N03). Com batching contínuo e concorrência acima de 8, TP=8 sobre PCIe escala pior do que TP=4 × PP=2.

Qwen 2.5 VL 32B em duas 5090

docker run --gpus all --runtime nvidia --ipc=host \
  -p 8000:8000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  vllm/vllm-openai:v0.20.2 \
  --model Qwen/Qwen2.5-VL-32B-Instruct-AWQ \
  --quantization awq \
  --tensor-parallel-size 2 \
  --max-model-len 16384 \
  --limit-mm-per-prompt '{"image": 4, "video": 0}' \
  --gpu-memory-utilization 0.90 \
  --enable-prefix-caching \
  --port 8000

Duas 5090, ~20 GB de pesos INT4, espaço para o encoder de visão + KV. A variante VL de 72B não cabe em duas 5090, nem sequer em INT4; para isso use 4× 5090 ou uma única Pro 6000. A flag --limit-mm-per-prompt limita as imagens por pedido — um único pedido com 20 imagens pode provocar OOM no encoder de visão de uma 5090. O endpoint é compatível com OpenAI (POST /v1/chat/completions com partes image_url).

SGLang — quando o seu router bate o vLLM

O argumento do SGLang é o RadixAttention: reutilização da cache de prefixos implementada como uma árvore radix entre pedidos, e não apenas por correspondência de igualdade de blocos. Em cargas de trabalho em que a maioria dos pedidos partilha prompts de sistema longos, a taxa de acerto supera a cache de prefixos do vLLM. Benchmarks públicos mostram o SGLang com ~16k tok/s contra ~12k tok/s do vLLM em H100 para cargas com prefixo partilhado, com diferenças bastante maiores em tráfego de saída estruturada.

Onde o SGLang ganha:

• JSON estruturado via xGrammar. Mais rápido e mais conforme do que a descodificação condicionada do vLLM. Numa API com saída JSON e milhões de pedidos, isto pesa.
• DeepSeek-V3 e outros MoE de grande dimensão. O paralelismo de peritos em largura e a separação entre prefill e decode chegaram mais cedo; continuam à frente em escala multi-nó.
• Fluxos de agentes com prompts de sistema partilhados. Endpoints de RAG, copilotos, prompts de sistema de 2–4 KB partilhados pela maioria dos pedidos.

Onde o vLLM ganha: processamento em lote com prompts únicos (a vantagem do RadixAttention desaparece), amplitude de modelos (mais arquiteturas suportadas de origem) e tempo até ter o primeiro endpoint a funcionar.

docker run --gpus all --runtime nvidia --ipc=host \
  -p 30000:30000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  lmsysorg/sglang:latest \
  python3 -m sglang.launch_server \
    --model-path Qwen/Qwen2.5-72B-Instruct-AWQ \
    --quantization awq \
    --tp 4 \
    --port 30000 \
    --host 0.0.0.0

O SGLang expõe um endpoint compatível com OpenAI numa porta própria (30000 por omissão). É substituição direta para o mesmo código de cliente, com os endpoints nativos de geração estruturada por acréscimo. A recomendação honesta: experimente primeiro o vLLM. Se a sua taxa de acerto de prefixo partilhado passar os ~60% e a latência de cauda importar, volte a testar com o SGLang e fique com o que vencer.

llama.cpp — quando pequeno e singular vence

O llama.cpp é inferência em C++ sem runtime Python, sem dependência de CUDA e com um formato de pesos GGUF que inclui os metadados de quantização no próprio ficheiro. Corre em CPU, numa só GPU, em Mac da série M, em Jetson, ou parcialmente em cada um. Não faz paralelismo de tensores como o vLLM. Um modelo, um ciclo de inferência, rápido.

Quando o llama.cpp é a resposta certa:

• Jetson Orin. O vLLM não visa bem o Jetson; o llama.cpp sim. Para um modelo a bordo de um Unitree G1, esta é a resposta habitual.
• Máquina de desenvolvimento com uma 5090 / 4090. Um programador a iterar, sem concorrência, com o caminho de instalação mais rápido.
• Divisão mista CPU+GPU. Um 70B não cabe numa 5090 (32 GB). Com -ngl 40, 40 das 80 camadas vão para a GPU e as restantes correm em CPU a uma velocidade aceitável para um só utilizador.
• Appliance embebida. Sem Docker, sem dores de cabeça com versões de driver, sem Python.

Opções de quantização GGUF, por ordem de tamanho face à qualidade:

Q4_K_M é a predefinição certa. Q5_K_M se houver folga. Q8_0 apenas para confirmar que "não há perda de quantização". Os i-quants (IQ4_XS e afins) são uma evolução de 2025/2026 que vale a pena testar ao espremer um 70B para uma única placa de 32 GB.

git clone https://github.com/ggml-org/llama.cpp && cd llama.cpp
cmake -B build -DGGML_CUDA=ON && cmake --build build --config Release -j

./build/bin/llama-server \
  --model models/qwen2.5-72b-instruct-q4_k_m.gguf \
  --n-gpu-layers 99 --ctx-size 32768 \
  --host 0.0.0.0 --port 8080 --api-key sk-localdev

-ngl 99 descarrega para a GPU tantas camadas quantas couberem. O endpoint é compatível com OpenAI em :8080/v1/chat/completions. Para carga multiutilizador é a ferramenta errada — use o vLLM. Para um utilizador numa 5090 ou num Jetson, é a certa.

TensorRT-LLM e Triton — a opção pesada

O TensorRT-LLM é o compilador de otimização da NVIDIA para inferência de LLM. Compila o modelo num motor TensorRT antecipadamente, funde kernels e escolhe o melhor layout para cada GPU. Tipicamente 10–25% de ganho de débito e 15–30% de latência face ao vLLM no mesmo hardware, mais em H100/B200. O custo é um passo de build (de minutos a horas por modelo e configuração de GPU), motores que não são portáveis entre gerações de CUDA, driver ou GPU, e uma realidade operacional mais dura do que um docker run.

O Triton Inference Server é a camada de serving multimodelo que aloja motores TensorRT-LLM (e também PyTorch, ONNX, TensorFlow, Python e vLLM como backend) num só servidor. O padrão de repositório de modelos permite carregar o LLM A, o LLM B, um modelo de visão, um modelo de ASR e um pipeline Python atrás de um único URL, com versionamento, encaminhamento A/B e grafos de ensemble.

Compensa quando: serve vários modelos heterogéneos num servidor; tem meses de produção estável com escolha de modelo fixa; precisa de espremer o último grão de latência p99 em GPUs de centro de dados Hopper/Blackwell.

Não compensa quando: ainda está a escolher o modelo (cada troca obriga a uma nova build de motor); está em GPUs de consumo/estação de trabalho (a vantagem do TRT-LLM encolhe face à H100, e o vLLM suporta o modelo da próxima semana seis semanas antes do TRT-LLM); é uma equipa pequena sem capacidade de operações.

NVIDIA NIM — o caminho pré-construído

O NIM (NVIDIA Inference Microservices) junta "Triton + TensorRT-LLM + uma configuração ótima para este modelo concreto + uma licença empresarial" num só contentor. docker pull nvcr.io/nim/meta/llama-3.3-70b-instruct:latest, defina uma chave NGC, execute e tem um endpoint compatível com OpenAI já testado, sem escolher quantização nem afinar flags.

Encaixa quando: comprou o NVIDIA AI Enterprise (ou um cliente o exige); quer o caminho mais rápido até um endpoint fiável (horas, não dias); o modelo que pretende está no catálogo (Llama, Mistral, Mixtral, Gemma, Nemotron e um conjunto de parceiros em crescimento). Depois da GTC 2026, um nível gratuito cobre até 16 GPUs para membros do Developer Program — suficiente para avaliar na maioria das instalações Kentino de servidor único; confirme os termos de licenciamento em vigor antes de apostar nisso.

Não encaixa quando: o modelo não está no catálogo (os pesos abertos chegam com semanas de atraso); quer afinar (o NIM esconde quase todos os botões por desenho).

Proxy inverso, autenticação, limitação de débito

Não exponha o vLLM diretamente na Internet pública. Coloque o nginx (ou Caddy, ou Traefik) à frente. Uma configuração mínima de nginx:

upstream vllm_backend {
    server 127.0.0.1:8000;
    keepalive 32;
}

limit_req_zone $binary_remote_addr zone=vllm:10m rate=20r/s;

server {
    listen 443 ssl http2;
    server_name infer.example.com;

    ssl_certificate     /etc/letsencrypt/live/infer.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/infer.example.com/privkey.pem;

    location /v1/ {
        if ($http_authorization != "Bearer sk-yourlongrandomtoken") {
            return 401;
        }
        limit_req zone=vllm burst=40 nodelay;

        proxy_pass http://vllm_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_buffering off;             # SSE em streaming
        proxy_read_timeout 600s;
        chunked_transfer_encoding on;
    }
}

Três pontos em que as pessoas falham:

• proxy_buffering off é obrigatório para respostas em streaming. Caso contrário, os tokens acumulam-se no proxy e o cliente recebe tudo de uma vez.
• proxy_read_timeout é 60s por omissão. Prefills multimodais longos a 4 tok/s ultrapassam esse limite. Defina 5–10 minutos.
• O bloco if faz correspondência exata. Para autenticação a sério, use Lua, oauth2-proxy ou um gateway como o Kong.

Monitorização

Duas fontes de métricas, dois alvos de recolha.

• O endpoint /metrics do vLLM. Compatível com Prometheus, na mesma porta da API OpenAI (:8000/metrics). Publica vllm:num_requests_running, vllm:num_requests_waiting, vllm:gpu_cache_usage_perc, vllm:time_to_first_token_seconds, vllm:time_per_output_token_seconds. A utilização da cache KV é a que apanha a preempção antes de esta destruir a latência.
• DCGM exporter (nvcr.io/nvidia/k8s/dcgm-exporter, porta 9400). Exporta utilização de SM e de memória da GPU, potência, temperatura, largura de banda PCIe e contadores ECC.

Ambos para o Prometheus, ambos para o Grafana. Primeiro painel: pedidos em execução, utilização da cache KV, utilização da GPU, temperatura da GPU, TTFT P95, TPOT P95. Se a utilização da cache KV saturar enquanto os pedidos em espera sobem, está a haver preempção — baixe --max-num-seqs, suba --gpu-memory-utilization ou acrescente uma réplica.

A armadilha do aquecimento do modelo

O primeiro pedido a um vLLM acabado de arrancar é 5–30× mais lento do que em regime estável. Os grafos CUDA são capturados para cada forma de batch, a cache de prefixos está vazia e o escalonador está a calibrar. Dispare um pequeno pedido a /v1/chat/completions no arranque, antes de entrar no balanceador de carga; sem isso, o primeiro utilizador real recebe uma resposta em 15 segundos num modelo que normalmente responde em 1. Em implementações blue/green, aqueça a nova réplica antes de drenar a antiga. Saltar o aquecimento é a causa mais comum do "a implementação parecia bem, mas os utilizadores queixaram-se durante dez minutos".

Vários modelos num só servidor

O vLLM é, por natureza, um servidor de um só modelo. Três opções se precisar de vários:

1. Um contentor por modelo, em portas diferentes. Cada um fica com a sua VRAM. Um 70B e um 7B partilham uma máquina de 4 GPUs através do particionamento com CUDA_VISIBLE_DEVICES e valores de --gpu-memory-utilization a condizer. O orçamento de memória é consigo.
2. Carregamento a pedido. Um front-end carrega e descarrega à medida que os pedidos chegam. Carregar um 70B demora 30–120 s; a latência do primeiro acesso é inaceitável em uso interativo. Serve para processamento em lote.
3. Repositório de modelos do Triton. O Triton gere o ciclo de vida de N modelos num só servidor e encaminha por nome de modelo. É o passo seguinte quando a opção 1 deixa de escalar.

Na maioria das instalações Kentino, a opção 1 chega até ter quatro ou mais modelos; a partir daí vale a pena pagar a fatura operacional do Triton.

A opinião honesta

Noventa e cinco por cento dos clientes Kentino devem começar com vllm/vllm-openai em Docker, atrás de nginx, com um modelo, com Prometheus + DCGM exporter a recolher métricas, e não olhar para mais nada nos primeiros três meses. O SGLang conquista o seu lugar na saída estruturada ou no tráfego de agentes com prefixo partilhado em escala. O llama.cpp conquista o seu lugar num Jetson, num Mac ou numa máquina de desenvolvimento de utilizador único. O Triton e o TensorRT-LLM conquistam o seu lugar quando há meses de produção estável com vários modelos. O NIM conquista o seu lugar quando o modelo está no catálogo e a licença está na mão.

O custo de começar demasiado complexo é real. Já vimos instalações de laboratório gastarem três semanas a pôr o Triton + TensorRT-LLM a servir um único Llama 70B que o vLLM teria alojado em vinte minutos. Escolha primeiro o simples. Acrescente complexidade quando tiver provas de que precisa dela.

---

Este texto faz parte da Kentino Wiki, uma série de referência sobre computação de IA, robótica e os sistemas que as ligam. Comentários e correções são bem-vindos em info@kentino.com.