Quem gere um servidor de inferência para modelos de linguagem grandes conhece o dilema: o vLLM tornou-se o padrão de facto, mas em cargas com prompts repetidos, conversas longas ou agentes que ramificam chamadas, o desperdício de cálculo começa a pesar na fatura de GPU. O SGLang, motor de inferência open source nascido no LMSYS Org (a mesma equipa por trás do Chatbot Arena), ataca exatamente esse problema com uma estrutura de cache em árvore chamada RadixAttention. Em setembro de 2026 a equipa lançou a versão v0.5.20, trouxe suporte para GPUs Intel XPU e relatou ganhos de até 52% na velocidade de decodificação graças a novas máscaras de amostragem por reforço.
Este tutorial mostra, passo a passo, como instalar o SGLang, lançar um servidor local compatível com a API da OpenAI, ativar as suas funcionalidades mais valiosas (cache de prefixos, saídas estruturadas, speculative decoding, paralelismo multi-GPU) e implantá-lo em produção com Docker. No final, terá um projeto funcional completo: um assistente de chat com memória de conversa que aproveita o cache de prefixos do SGLang para responder mais depressa a cada nova mensagem.
Vale contextualizar porque este tipo de motor de inferência ganhou tanto peso em 2026. As equipas que servem LLMs em produção deixaram de perguntar apenas “o modelo é bom?” e passaram a perguntar “quanto custa cada milhão de tokens servidos, com que latência e a que escala?”. Um motor que reaproveita cálculo já feito, em vez de o repetir a cada pedido, tem impacto direto na fatura de GPU, sobretudo em aplicações de agentes que reenviam o mesmo contexto dezenas de vezes numa única tarefa. É esse o nicho onde o SGLang foi construído para competir.
O que é o SGLang e porque está a ganhar tração em 2026
O SGLang (Structured Generation Language) é um sistema de execução e serviço para modelos de linguagem e modelos de visão-linguagem, mantido no repositório sgl-project no GitHub. A documentação oficial do projeto descreve-o como “an inference framework meant for production level serving”, acrescentando que foi desenhado para “deliver low-latency and high-throughput inference across a wide range of setups, from a single GPU to large distributed clusters” (docs.sglang.io). Na prática, isto significa que o mesmo binário serve tanto um investigador a testar um modelo numa única placa gráfica como uma empresa a distribuir tráfego por dezenas de nós.
A diferença central em relação a motores mais genéricos está na forma como o SGLang trata o cache de atenção. Em vez de recalcular o prefixo de cada pedido, a técnica RadixAttention guarda os blocos de chave-valor já processados numa árvore de radix e reutiliza-os sempre que um novo pedido partilha o mesmo início de prompt, seja um system prompt fixo, exemplos de few-shot ou o histórico de uma conversa. Isto é especialmente valioso em fluxos de agentes, RAG e chat multi-turno, onde o mesmo contexto é reenviado repetidamente.
O ecossistema à volta do projeto cresceu depressa ao longo de 2026. A Hugging Face descreve o SGLang nos seus próprios documentos como “a fast serving framework for large language models and vision language models” (huggingface.co), a Google associou-se ao trabalho de portar as funcionalidades do motor para TPUs através do projeto RadixArk, e a NVIDIA já publica contentores oficiais com o SGLang pré-instalado (a versão 26.08 do contentor CUDA inclui o SGLang 0.5.17 sobre CUDA 13.4.1). Em setembro de 2026, a Intel juntou-se à lista de parceiros ao trazer suporte para as suas GPUs XPU diretamente para os lançamentos padrão do projeto, a partir da versão 0.5.20.
Também vale a pena situar o SGLang face ao trabalho mais recente em modelos de grande escala. A equipa reportou que a versão 0.5.14 alcançou um ganho de “5× higher throughput at the same interactivity” ao servir o DeepSeek-V4 em hardware NVIDIA GB300, um resultado atribuído a otimizações específicas como o balanceamento de carga em paralelismo de especialistas (Waterfill e LPLB), kernels CuteDSL de prefill e otimizações do cache de prefixos para atenção linear. É um número concreto, mas específico a esse modelo e a esse hardware, não uma promessa universal de “5 vezes mais rápido” em qualquer configuração.
Pré-requisitos: hardware, Python, CUDA e modelos suportados
Antes de instalar seja o que for, confirme que o seu ambiente cumpre os requisitos mínimos. O SGLang distribui wheels pré-compilados no PyPI para CPython 3.10 em Linux, e a via de instalação documentada oficialmente assume uma placa NVIDIA com drivers atualizados. Também existem caminhos de instalação para ROCm (AMD) e, desde a v0.5.20, para GPUs Intel XPU, mas o percurso mais testado continua a ser CUDA em Linux.
| Requisito | Versão/valor recomendado | Nota |
|---|---|---|
| Sistema operativo | Linux (Ubuntu 22.04+) | Caminho mais testado pela comunidade; Windows requer WSL2 |
| Python | 3.10 | Wheels oficiais do PyPI são compilados para cp310 |
| GPU | NVIDIA com 16 GB+ de VRAM | ROCm (AMD) e Intel XPU também suportados desde a v0.5.20 |
| CUDA | 12.4 ou superior | A documentação oficial usa CUDA 12.4 com PyTorch 2.5 como referência |
| Pacote principal | sglang v0.5.20 | Lançado a 18 de setembro de 2026 |
| Pacote auxiliar | sgl-kernel | Kernels otimizados, instalado à parte |
| Docker (opcional) | 24.x+ | Necessário para o método de implantação em contentor |
Quanto a modelos, o SGLang cobre uma lista alargada de arquiteturas compatíveis com a Hugging Face, incluindo a família Llama, Qwen, GLM e Nemotron. Em 2026 o projeto anunciou suporte no dia de lançamento (“day-zero”) para o DeepSeek-V4.1 (em conjunto com o projeto Miles) e para os modelos Nemotron 3 Ultra e Nemotron 3 Super, além de servir o GLM 5.2 em formato NVFP4 para cargas de trabalho agênticas. Também existe um subprojeto, o SGLang-Omni, focado em modelos multimodais e de voz como o AuK e o AuK-Flash, com a versão 0.1.6 lançada a 17 de setembro de 2026.
Para este tutorial vamos usar um modelo pequeno e aberto para que os exemplos corram em hardware de gama média (uma única GPU com 16 a 24 GB de VRAM chega perfeitamente). Se tiver acesso a mais GPUs, os passos de paralelismo tensor mais à frente mostram como escalar para modelos maiores.
Como regra prática de dimensionamento, um modelo denso (não MoE) precisa de aproximadamente 2 GB de VRAM por mil milhões de parâmetros quando servido em precisão de 16 bits, mais uma margem para o cache de atenção que cresce com o número de pedidos concorrentes e o tamanho do contexto. Um Llama de 8 mil milhões de parâmetros cabe confortavelmente numa GPU de 24 GB com espaço de sobra para o cache. Já um modelo de 70 mil milhões exige paralelismo tensor por várias GPUs ou quantização agressiva. Modelos MoE como o DeepSeek-V4 ou o GLM 5.2 têm uma pegada de memória diferente, porque só uma fração dos parâmetros está ativa por token, mas continuam a exigir hardware distribuído pela dimensão total do modelo guardado em memória.
Passo 1 e 2: preparar o ambiente e instalar o SGLang
Comece por criar um ambiente virtual isolado. Misturar o SGLang com outras dependências de PyTorch já instaladas no sistema é uma das causas mais comuns de conflitos de versão, por isso um ambiente limpo poupa tempo mais tarde.
python3 -m venv sglang-env
source sglang-env/bin/activate
python -m pip install --upgrade pipCom o ambiente ativo, instale o pacote sgl-kernel primeiro (contém os kernels CUDA otimizados) e só depois o pacote principal com o extra [all], que traz as dependências de servir, treinar e avaliar:
pip install sgl-kernel --force-reinstall --no-deps
pip install "sglang[all]"Se o seu sistema usa uma versão de CUDA diferente da 12.4 usada como referência na documentação, pode ser preciso apontar explicitamente para o índice de wheels do FlashInfer correspondente à sua combinação de CUDA e PyTorch, algo do género:
pip install flashinfer-python -i https://flashinfer.ai/whl/cu124/torch2.5/Confirme a instalação a correr um pequeno teste de importação. Se o comando abaixo não devolver erros nem avisos sobre CUDA em falta, está pronto para avançar:
python -c "import sglang; print(sglang.__version__)"Utilizadores de AMD podem seguir o caminho ROCm documentado no repositório oficial, e quem tem GPUs Intel pode usar o suporte XPU introduzido na v0.5.20. Em qualquer dos casos, o resto deste tutorial funciona da mesma forma, apenas mudam as flags de instalação inicial.
Passo 3: escolher e descarregar um modelo compatível
O SGLang descarrega os pesos diretamente do Hugging Face Hub na primeira execução, tal como o Transformers. Não precisa de converter o modelo para um formato próprio antes de o servir, desde que a arquitetura conste da lista de suporte do projeto.
Para seguir este tutorial sem depender de uma GPU topo de gama, escolha um modelo pequeno e aberto compatível, como um Llama de 8 mil milhões de parâmetros ou um Qwen na mesma escala. Se já tiver credenciais configuradas no Hugging Face CLI para modelos com acesso condicionado (gated), autentique-se antes do próximo passo:
huggingface-cli loginNão é obrigatório descarregar o modelo manualmente. Basta indicar o identificador do repositório do Hugging Face no comando de arranque do servidor, no passo seguinte, e o SGLang trata do download e da colocação em cache localmente.
Passo 4: lançar o primeiro servidor SGLang
Chegou a parte que a documentação oficial resume como o objetivo do quickstart: “Get up and running with SGLang in minutes: install, launch a server, and send your first request” (docs.sglang.io/docs/get-started/quickstart). O comando abaixo arranca um servidor local na porta 30000, escolhendo o modelo pelo identificador do Hugging Face:
python -m sglang.launch_server \
--model-path meta-llama/Llama-3.1-8B-Instruct \
--port 30000 \
--host 0.0.0.0Na primeira execução, o terminal mostra o progresso do download dos pesos, seguido da inicialização do motor CUDA e, por fim, uma mensagem a confirmar que o servidor está a aceitar pedidos. Um exemplo típico do que deve ver no final do arranque:
[2026-09-26 10:14:02] INFO: Started server process
[2026-09-26 10:14:02] INFO: Waiting for application startup.
[2026-09-26 10:14:02] INFO: Application startup complete.
[2026-09-26 10:14:02] INFO: Uvicorn running on http://0.0.0.0:30000Se o processo terminar antes de chegar a esta mensagem, o problema quase sempre está relacionado com memória de GPU insuficiente ou uma versão de driver desatualizada, dois pontos que retomamos na secção de resolução de problemas mais abaixo.
Passo 5: testar a API compatível com OpenAI
Uma das decisões de design que facilita a adoção do SGLang é a compatibilidade com o formato de API da OpenAI. Isto significa que qualquer código já escrito para o SDK oficial da OpenAI funciona apontando apenas para o endereço local, sem reescrever chamadas.
curl http://localhost:30000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "meta-llama/Llama-3.1-8B-Instruct",
"messages": [{"role": "user", "content": "Explica o RadixAttention em duas frases."}],
"temperature": 0.3
}'Para quem prefere Python, o SDK oficial da OpenAI funciona sem alterações, bastando trocar o base_url:
from openai import OpenAI
client = OpenAI(base_url="http://localhost:30000/v1", api_key="nao-e-necessaria")
resposta = client.chat.completions.create(
model="meta-llama/Llama-3.1-8B-Instruct",
messages=[{"role": "user", "content": "Resume o que é o SGLang em 3 pontos."}],
)
print(resposta.choices[0].message.content)Se receber uma resposta em JSON com o texto gerado, o servidor está a funcionar corretamente e pode avançar para as funcionalidades que distinguem o SGLang de um simples wrapper de inferência.
Passo 6: RadixAttention, a peça central do desempenho do SGLang
O RadixAttention está ativo por predefinição, não precisa de nenhuma flag extra para o ligar. O que vale a pena entender é como tirar partido dele na forma como estrutura os seus pedidos. Sempre que dois pedidos partilham o mesmo início de prompt, seja o mesmo system prompt, o mesmo conjunto de exemplos de few-shot ou o histórico acumulado de uma conversa, o SGLang deteta essa sobreposição e reaproveita os blocos de cache já calculados em vez de reprocessar tudo do zero.
Na prática, isto tem um impacto direto no desenho de aplicações. Se está a construir um chatbot com histórico de conversa, um agente que reenvia o mesmo conjunto de instruções do sistema, ou um pipeline de RAG que injeta o mesmo bloco de contexto em múltiplos pedidos, o SGLang recompensa manter esse prefixo estável e inalterado entre chamadas. Mudar a ordem das mensagens, reformular o system prompt a cada pedido ou introduzir timestamps dinâmicos no início do prompt anula parte do benefício do cache, porque o radix tree deixa de encontrar uma correspondência longa.
Pode confirmar a taxa de acerto do cache através do endpoint de métricas do próprio servidor, que expõe contadores de tokens processados a partir do cache face a tokens recalculados. Para cargas com prefixos muito repetidos, como um agente que reenvia sempre o mesmo prompt de sistema de 2.000 tokens, a diferença entre um pedido “frio” e um pedido “quente” costuma ser visível já na latência da primeira resposta.
Passo 7: saídas estruturadas com JSON Schema e gramáticas
Em vez de gerar texto livre e validar o resultado depois (uma abordagem frágil, porque o modelo pode falhar o formato), o SGLang restringe a escolha de tokens durante a própria decodificação para garantir que o resultado final cumpre um esquema JSON, uma expressão regular ou uma gramática formal. Isto é particularmente útil em pipelines de extração de dados ou em chamadas de ferramentas (tool calling) onde uma resposta mal formatada quebra o passo seguinte do fluxo.
O exemplo abaixo pede uma resposta que segue obrigatoriamente um esquema com dois campos, “resumo” e “pontuacao”:
curl http://localhost:30000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "meta-llama/Llama-3.1-8B-Instruct",
"messages": [{"role": "user", "content": "Avalia esta critica de filme: Adorei o final."}],
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "avaliacao",
"schema": {
"type": "object",
"properties": {
"resumo": {"type": "string"},
"pontuacao": {"type": "integer", "minimum": 1, "maximum": 5}
},
"required": ["resumo", "pontuacao"]
}
}
}
}'O resultado devolvido respeita sempre a estrutura pedida, o que elimina a necessidade de código de validação e novas tentativas em caso de resposta mal formatada, um problema comum quando se depende apenas de instruções em texto livre pedindo “responde só em JSON”.
Passo 8: speculative decoding para reduzir a latência
O speculative decoding funciona com dois modelos: um modelo “rascunho”, mais pequeno e rápido, propõe vários tokens seguidos, e o modelo principal verifica-os em lote numa única passagem. Quando o modelo rascunho acerta na maioria das previsões, o número de passagens caras pelo modelo grande cai, o que reduz a latência percebida sem alterar a qualidade final da resposta (o modelo principal continua a ter a palavra final sobre cada token aceite).
Para ativar esta funcionalidade, indique o modelo rascunho no arranque do servidor:
python -m sglang.launch_server \
--model-path meta-llama/Llama-3.1-8B-Instruct \
--speculative-draft-model-path meta-llama/Llama-3.2-1B-Instruct \
--speculative-num-steps 5 \
--port 30000O ganho real depende de quanto o modelo rascunho e o modelo principal concordam nas suas previsões. Para textos previsíveis, como respostas curtas ou código com padrões repetitivos, a concordância tende a ser alta. Para geração mais criativa ou aberta, o ganho pode ser mais modesto, por isso vale a pena medir com o seu próprio caso de uso em vez de assumir um número fixo.
Passo 9: paralelismo tensor e MoE em múltiplas GPU
Quando um modelo não cabe numa única GPU, ou quando quer distribuir a carga para aumentar o débito, o SGLang suporta paralelismo tensor (dividindo cada camada por várias placas) e paralelismo de especialistas para arquiteturas de mistura de especialistas (MoE), como o DeepSeek-V4 ou o GLM 5.2. Para ligar o paralelismo tensor com quatro GPUs, o comando fica assim:
python -m sglang.launch_server \
--model-path Qwen/Qwen2.5-72B-Instruct \
--tp-size 4 \
--port 30000Para modelos MoE de grande escala, o SGLang expõe ainda parâmetros de paralelismo de especialistas e balanceamento de carga entre eles, o mesmo tipo de otimizações que a equipa associou ao ganho de “5× higher throughput” reportado para o DeepSeek-V4 sobre hardware NVIDIA GB300. Vale repetir: esse número é específico àquela combinação de modelo e hardware, e não deve ser lido como uma garantia genérica para qualquer implantação.
Passo 10: implantar em produção com Docker
Para ambientes de produção, correr o SGLang dentro de um contentor Docker simplifica a gestão de dependências e alinha-se com o contentor oficial que a NVIDIA já distribui com o motor pré-instalado. Um exemplo de arranque com a imagem oficial:
docker run --gpus all \
--shm-size 16g \
-p 30000:30000 \
-v ~/.cache/huggingface:/root/.cache/huggingface \
lmsysorg/sglang:latest \
python3 -m sglang.launch_server \
--model-path meta-llama/Llama-3.1-8B-Instruct \
--host 0.0.0.0 \
--port 30000Note o parâmetro --shm-size: o valor predefinido do Docker (64 MB) é insuficiente para cargas de inferência com múltiplos workers, e a falta desta flag é uma causa frequente de falhas silenciosas ou lentidão anómala em contentores. Para clusters maiores, o projeto documenta ainda caminhos de implantação via Kubernetes, Docker Compose e SkyPilot, cobrindo desde um único nó até execução distribuída em cloud.
Passo 11: medir e comparar o desempenho
Antes de tirar conclusões sobre desempenho, meça com a sua própria carga de trabalho. O SGLang inclui uma ferramenta de benchmarking integrada que simula tráfego concorrente e reporta métricas de débito e latência:
python -m sglang.bench_serving \
--backend sglang \
--host localhost \
--port 30000 \
--num-prompts 200 \
--request-rate 10O resultado inclui métricas como o tempo até ao primeiro token (TTFT), o débito em tokens por segundo e a latência ponta a ponta por pedido. Corra o mesmo teste antes e depois de ativar RadixAttention, speculative decoding ou paralelismo, para perceber o impacto real na sua combinação específica de modelo, hardware e padrão de tráfego, em vez de confiar apenas em números publicados para outra configuração.
Passo 12: projeto completo – assistente de chat com cache de conversa
Para fechar o tutorial com um exemplo aplicado, eis um pequeno assistente de linha de comandos em Python que mantém o histórico da conversa num prefixo estável, tirando partido direto do RadixAttention a cada nova mensagem trocada com o mesmo utilizador:
import time
from openai import OpenAI
client = OpenAI(base_url="http://localhost:30000/v1", api_key="nao-e-necessaria")
SYSTEM_PROMPT = (
"Es um assistente tecnico que responde em portugues de Portugal, "
"de forma direta e sem rodeios."
)
def conversar():
historico = [{"role": "system", "content": SYSTEM_PROMPT}]
print("Assistente SGLang pronto. Escreve 'sair' para terminar.\n")
while True:
pergunta = input("Tu: ")
if pergunta.strip().lower() == "sair":
break
historico.append({"role": "user", "content": pergunta})
inicio = time.time()
resposta = client.chat.completions.create(
model="meta-llama/Llama-3.1-8B-Instruct",
messages=historico,
temperature=0.4,
)
duracao = time.time() - inicio
texto = resposta.choices[0].message.content
historico.append({"role": "assistant", "content": texto})
print(f"Assistente ({duracao:.2f}s): {texto}\n")
if __name__ == "__main__":
conversar()Repare que o historico cresce a cada troca, mas o início da lista de mensagens (o system prompt e as primeiras trocas) mantém-se sempre igual entre pedidos. É exatamente esse prefixo estável que o RadixAttention reconhece e reaproveita, pelo que a partir da segunda ou terceira mensagem deverá notar que o tempo de resposta reportado pela variável duracao deixa de crescer proporcionalmente ao tamanho do histórico, ao contrário do que aconteceria num motor sem cache de prefixos.
Como encaixar o SGLang num pipeline de RAG
Um dos cenários onde o RadixAttention traz mais valor prático é a geração aumentada por recuperação (RAG). Num pipeline típico, cada pedido ao modelo inclui um bloco de contexto recuperado de uma base vetorial, seguido da pergunta do utilizador. Se o mesmo documento ou o mesmo conjunto de chunks for reutilizado em várias perguntas seguidas, por exemplo quando vários utilizadores consultam a mesma base de conhecimento ou quando o mesmo utilizador faz perguntas de seguimento sobre o mesmo documento, o SGLang consegue reaproveitar o processamento desse bloco de contexto em vez de o recalcular a cada pedido.
Para tirar o máximo partido disto, a estrutura do prompt importa mais do que num motor sem cache de prefixos. A prática recomendada é colocar sempre o conteúdo estável primeiro (instruções de sistema, depois o contexto recuperado) e deixar a pergunta variável do utilizador para o final do prompt. Isto maximiza o comprimento do prefixo partilhável entre pedidos diferentes que consultam o mesmo documento, mesmo que a pergunta final seja distinta em cada caso.
def montar_prompt(contexto_recuperado, pergunta_utilizador):
return [
{"role": "system", "content": "Responde apenas com base no contexto fornecido."},
{"role": "user", "content": f"Contexto:\n{contexto_recuperado}\n\nPergunta: {pergunta_utilizador}"},
]Combinado com saídas estruturadas (para forçar respostas em JSON com campos como “resposta” e “fontes”), este padrão cobre grande parte das necessidades de um sistema de RAG em produção, sem precisar de uma camada extra de validação de formato nem de reprocessar o mesmo documento a cada nova pergunta feita sobre ele.
Monitorização, métricas e logs em produção
Antes de expor um servidor SGLang a tráfego real, vale a pena ligar observabilidade básica. O servidor expõe um endpoint de métricas no formato Prometheus, que pode ser recolhido por uma stack de monitorização já existente e visualizado num painel Grafana ao lado dos restantes serviços da sua infraestrutura:
python -m sglang.launch_server \
--model-path meta-llama/Llama-3.1-8B-Instruct \
--port 30000 \
--enable-metricsAs métricas expostas incluem contadores de pedidos em fila, tokens processados a partir do cache face a tokens recalculados, tempo até ao primeiro token e utilização da GPU. Estes números são particularmente úteis para detetar cedo dois problemas comuns: uma fila de pedidos a crescer sem controlo (sinal de que precisa de mais réplicas ou de paralelismo) e uma taxa de acerto de cache a cair (sinal de que os prompts deixaram de partilhar prefixos estáveis, talvez por uma alteração recente no código da aplicação).
Também vale a pena configurar um endpoint de verificação de saúde (/health) na sua infraestrutura de orquestração, seja um load balancer, Kubernetes ou um sistema de gestão de processos, para reiniciar automaticamente o servidor caso deixe de responder. Combinado com os logs estruturados que o SGLang já produz por predefinição, isto fecha o ciclo básico de operação: saber quando algo correu mal, perceber porquê e recuperar sem intervenção manual.
SGLang vs vLLM vs TensorRT-LLM: qual motor escolher
Nenhum destes três motores é universalmente “melhor”. Cada um foi otimizado para prioridades diferentes, e a escolha certa depende do seu caso de uso, do hardware disponível e da maturidade operacional da sua equipa.
| Motor | Ponto forte principal | Melhor cenário de uso |
|---|---|---|
| SGLang | RadixAttention, reutilização de prefixos, saídas estruturadas, speculative decoding | Agentes, RAG, chat multi-turno e cargas com prompts repetidos |
| vLLM | Serviço genérico maduro, batching contínuo, ecossistema alargado | Escolha por defeito para servir modelos compatíveis com OpenAI em produção |
| TensorRT-LLM | Otimização de kernels e grafos específica da NVIDIA | Máximo desempenho em hardware NVIDIA quando compensa o esforço de configuração |
Na prática, o vLLM e o SGLang competem de perto em muitos cenários de servir um modelo compatível com a API da OpenAI. O SGLang tende a destacar-se quando o padrão de tráfego tem prefixos partilhados (o cenário onde o RadixAttention brilha) ou quando a aplicação precisa de saídas estruturadas garantidas sem lógica extra de validação. O TensorRT-LLM continua a ser a opção quando o objetivo é espremer o máximo de desempenho possível de hardware NVIDIA específico, ao custo de uma configuração mais fechada ao ecossistema da própria NVIDIA. A recomendação prática é testar mais do que um motor com a sua carga real antes de comprometer a arquitetura de produção a um deles.
Vale ainda considerar o custo de manutenção de cada opção. O vLLM tem hoje o ecossistema mais alargado de integrações com frameworks de terceiros, o que reduz o esforço de adaptação quando já existe uma aplicação construída à volta dele. O SGLang, por ser mais recente, exige por vezes mais leitura da documentação oficial para configurações avançadas, mas compensa com um ritmo de lançamentos rápido e suporte no dia zero para modelos recentes como o DeepSeek-V4.1. O TensorRT-LLM, por seu lado, tende a exigir a maior curva de aprendizagem inicial, mas é a opção natural para equipas já profundamente integradas com as ferramentas da NVIDIA em produção.
Erros comuns ao configurar o SGLang
- Instalar o sgl-kernel depois do pacote principal: a ordem recomendada é sgl-kernel primeiro, com
--force-reinstall --no-deps, e só depois o pacotesglang[all]. Trocar a ordem gera frequentemente conflitos de versão silenciosos. - Ignorar a versão de CUDA do FlashInfer: instalar o FlashInfer sem apontar para o índice de wheels correto para a sua combinação de CUDA e PyTorch causa erros de símbolo em tempo de execução, não em tempo de instalação, o que torna o diagnóstico mais lento.
- Deixar o –shm-size predefinido em Docker: o valor por omissão do Docker é demasiado baixo para cargas de inferência com múltiplos workers, e o sintoma costuma ser lentidão inexplicada em vez de um erro claro.
- Mudar o system prompt a cada pedido: reformular ligeiramente as instruções de sistema entre chamadas parece inofensivo, mas quebra a correspondência de prefixo do RadixAttention e anula parte do ganho de cache.
- Assumir que os benchmarks publicados se aplicam ao seu caso: números como o ganho de “5× throughput” documentado para o DeepSeek-V4 em GPUs GB300 são específicos a esse modelo e hardware. Corra sempre o seu próprio
bench_servingantes de dimensionar infraestrutura com base em números de terceiros. - Descarregar modelos GGUF de fontes não verificadas: um relatório de segurança independente, não confirmado oficialmente pelo projeto SGLang, associou o identificador CVE-2026-5760 a modelos GGUF manipulados que poderiam permitir execução remota de código. Até haver confirmação e correção oficiais, descarregue pesos apenas de repositórios verificados no Hugging Face Hub e evite fontes de terceiros sem reputação estabelecida.
Resolução de problemas
| Sintoma | Causa provável | Solução |
|---|---|---|
| Servidor termina logo após arrancar, sem erro claro | Memória de GPU insuficiente para o modelo escolhido | Reduza o tamanho do modelo, ative quantização ou use –tp-size para dividir por mais GPUs |
| ImportError ao importar sglang | Ordem de instalação trocada entre sgl-kernel e sglang | Reinstale seguindo exatamente a ordem: sgl-kernel primeiro, depois sglang[all] |
| Erro de símbolo indefinido em tempo de execução | Wheel do FlashInfer incompatível com a versão de CUDA instalada | Reinstale o FlashInfer apontando para o índice de wheels da sua versão exata de CUDA/PyTorch |
| Respostas muito lentas em contentor Docker | –shm-size demasiado baixo | Aumente para pelo menos 16g no comando docker run |
| Download do modelo falha a meio | Falta de autenticação para modelo gated no Hugging Face | Execute huggingface-cli login antes de lançar o servidor |
| JSON Schema não é respeitado na resposta | Parâmetro response_format mal formado no pedido | Valide o schema JSON isoladamente antes de o incluir no pedido à API |
| Speculative decoding não traz ganho percetível | Baixa concordância entre modelo rascunho e modelo principal | Teste um modelo rascunho mais próximo em estilo do modelo principal, ou desative a funcionalidade para essa carga |
| Débito não escala ao adicionar GPUs | Configuração de paralelismo tensor incorreta para a topologia de rede disponível | Confirme que –tp-size corresponde ao número real de GPUs e que existe interligação NVLink ou equivalente |
| Métricas de cache mostram 0% de reutilização | Prefixo do prompt muda a cada pedido (timestamps, IDs dinâmicos no início) | Mova qualquer conteúdo variável para o fim do prompt, mantendo o início estável |
Dicas avançadas para produção
Depois de dominar os passos base, há um conjunto de ajustes que fazem diferença real num ambiente de produção. Primeiro, mantenha o SGLang atualizado com regularidade: o ritmo de lançamentos do projeto tem sido elevado ao longo de 2026, com múltiplas builds publicadas por mês e melhorias de desempenho frequentes, como as máscaras de amostragem por reforço introduzidas na v0.5.20 que reportaram até 52% de ganho na decodificação para determinadas cargas.
Segundo, separe ambientes de teste e produção com versões fixadas (pin) de todas as dependências, não só do sglang. A própria documentação recomenda registar a versão exata de Python, PyTorch, CUDA ou ROCm, driver de GPU e FlashInfer usada, precisamente porque o ecossistema evolui depressa e uma atualização não planeada de qualquer uma destas peças pode alterar comportamento em produção sem aviso.
Terceiro, se está a avaliar migrar de um sistema já em produção com vLLM, corra os dois motores em paralelo durante um período de transição, com a mesma carga de tráfego espelhada, antes de desligar o sistema antigo. Isto permite comparar latência, débito e taxa de erros com dados reais da sua aplicação, em vez de decidir apenas com base em benchmarks publicados por terceiros.
Por fim, para cargas multimodais ou de voz, vale a pena acompanhar o subprojeto SGLang-Omni separadamente do motor principal, já que segue o seu próprio ciclo de lançamentos (a versão 0.1.6 saiu a 17 de setembro de 2026) e cobre modelos como o AuK e o AuK-Flash que não fazem parte do pacote base.
Perguntas frequentes
O SGLang substitui o vLLM?
Não de forma automática. Os dois motores resolvem o mesmo problema geral, servir modelos de linguagem com uma API compatível com a OpenAI, mas com prioridades de otimização diferentes. O SGLang tende a destacar-se em cargas com prefixos repetidos ou necessidade de saídas estruturadas garantidas. Já o vLLM continua a ser uma escolha sólida e madura para serviço genérico. Teste ambos com a sua carga antes de decidir.
Preciso de uma GPU NVIDIA para usar o SGLang?
Não exclusivamente. O caminho mais testado e documentado é CUDA em GPUs NVIDIA, mas o projeto também suporta ROCm para GPUs AMD e, desde a versão 0.5.20 lançada em setembro de 2026, GPUs Intel XPU nos lançamentos padrão.
O que é exatamente o RadixAttention?
É a técnica de cache central do SGLang: guarda os blocos de chave-valor de atenção já calculados numa estrutura de árvore de radix e reutiliza-os sempre que um novo pedido partilha o mesmo prefixo de um pedido anterior, evitando recalcular tokens idênticos.
O SGLang funciona com modelos DeepSeek e GLM?
Sim. O projeto anunciou suporte no dia de lançamento para o DeepSeek-V4.1 e serve o GLM 5.2 em formato NVFP4 para cargas agênticas, além de suportar as famílias Llama, Qwen e Nemotron, entre outras arquiteturas compatíveis com a Hugging Face.
É seguro descarregar qualquer modelo GGUF para usar com o SGLang?
Não sem cuidado. Um relatório de segurança independente associou o identificador CVE-2026-5760 a modelos GGUF manipulados capazes de possibilitar execução remota de código, sem confirmação oficial de correção por parte do projeto até à data da divulgação. A prática mais segura é descarregar pesos apenas de repositórios verificados e evitar ficheiros de origem duvidosa.
Quanto custa correr o SGLang?
O software em si é open source e gratuito. O custo real está no hardware (GPU própria ou alugada na cloud) necessário para correr o modelo escolhido. Modelos pequenos, como um Llama de 8 mil milhões de parâmetros, correm em GPUs de gama média com 16 a 24 GB de VRAM. Modelos de grande escala como o DeepSeek-V4 exigem hardware distribuído e multi-GPU.
O SGLang suporta múltiplas GPUs e múltiplos nós?
Sim, através de paralelismo tensor para dividir camadas por várias GPUs e paralelismo de especialistas para arquiteturas MoE de grande escala, além de caminhos de implantação documentados via Docker Compose, Kubernetes e SkyPilot para clusters distribuídos.
Preciso de reescrever a minha aplicação se já uso a API da OpenAI?
Normalmente não. O SGLang expõe um endpoint compatível com a API de chat completions da OpenAI, pelo que a maioria das aplicações só precisa de alterar o parâmetro base_url do cliente para apontar ao servidor local, mantendo o resto do código inalterado.