SGLang: disponibilizar um LLM local para vários utilisateurs

#O que faz o SGLang

O SGLang se apresenta como um framework de alto desempenho para servir LLMs e modelos multimodais, projetado para inferência com baixa latência e alta taxa de processamento, desde uma única GPU até grandes clusters distribuídos. O projeto afirma ter implantações em produção que geram trilhões de tokens por dia em mais de 400.000 GPUs no mundo e é hospedado pela LMSYS, uma organização de código aberto sem fins lucrativos.

Compatível com as APIs OpenAI e Hugging Face, o SGLang suporta uma ampla gama de modelos (Llama, Qwen, DeepSeek, GLM, Mistral, Gemma) e de hardware (GPU NVIDIA, AMD, CPU Intel Xeon, TPU Google, NPU Ascend). Em 28 de setembro de 2026, a versão mais recente é a v0.5.20, publicada em 18 de setembro de 2026.

#Instalar e iniciar o servidor

A instalação recomendada pela documentação oficial utiliza o uv, que é mais rápido que o pip tradicional. O flag --prerelease=allow é necessário porque algumas dependências do SGLang publicam apenas versões prévias no PyPI.

pip install --upgrade pip
pip install uv
uv pip install --prerelease=allow sglang

A execução em um contêiner Docker continua sendo a forma mais reprodutível de implantação em servidor, com a porta 30000 usada por padrão para a API.

docker run --gpus all \
    --shm-size 32g \
    -p 30000:30000 \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=<secret>" \
    --ipc=host \
    lmsysorg/sglang:latest \
    python3 -m sglang.launch_server --model-path meta-llama/Llama-3.1-8B-Instruct --host 0.0.0.0 --port 30000

A documentação especifica que o SGLang agora exige CUDA 13: as imagens e os pacotes wheel para CUDA 12 (cu129) foram removidos desde que o PyTorch 2.14 deixou de publicar builds para CUDA 12.9, e a versão 0.5.19 continua sendo a última a oferecer uma opção para CUDA 12. Uma implantação em hardware mais antigo deve, portanto, fixar essa versão ou verificar o driver da GPU antes de atualizar.

#RadixAttention e o cache de prefixos

O ponto central da promessa de taxa de processamento do SGLang é a RadixAttention: os prefixos de sequências já calculados (um prompt de sistema compartilhado, o início de uma conversa com múltiplos turnos) são organizados em uma árvore radix e reutilizados entre requisições, em vez de serem recalculados a cada chamada. O anúncio original do projeto, em janeiro de 2024, alegava uma inferência até 5 vezes mais rápida graças a esse mecanismo — um número divulgado pelo projeto com base em sua própria bancada de testes da época, não uma medição independente recente no seu hardware.

Esse ganho beneficia principalmente cenários com préfixos compartilhados: vários usuários fazendo consultas com o mesmo prompt de sistema, um agente que relê o mesmo contexto a cada turno ou few-shot com os mesmos exemplos. Um fluxo de requisições sem nenhum préfixo comum (perguntas totalmente independentes, sem histórico) se beneficia muito menos do RadixAttention.

O runtime combina RadixAttention com um escalonador de CPU com overhead zero, desagregação prefill-decode, decodificação especulativa, escalonamento contínuo de requisições (continuous batching) e paginação da atenção (paged attention) — um conjunto de técnicas de otimização, e não um mecanismo isolado.

#Ajustar a concorrência e a memória

Três parâmetros de inicialização controlam a forma como o SGLang atende vários usuários em paralelo. --mem-fraction-static define a fração da memória da GPU reservada para os pesos do modelo e para o cache KV; a documentação recomenda reduzi-la em caso de erro por falta de memória; caso contrário, ela é calculada automaticamente com base na memória disponível da GPU.

Sem limite explícito em --max-running-requests, o SGLang aceita tantas requisições quanto a memória do cache KV permitir, o que pode degradar a latência por requisição sob carga alta, em vez de recusar gentilmente as novas conexões. Definir um limite explícito, coerente com a VRAM disponível, é o primeiro ajuste a fazer antes de abrir o servidor para vários usuários reais.

#Quando escolher SGLang em vez de vLLM ou Ollama

As três ferramentas atendem a necessidades diferentes. O Ollama visa o uso pessoal por um único usuário, com um aprendizado inicial mínimo; SGLang e vLLM se destinam a atender vários usuários em GPUs de servidor, com filosofias próximas (cache de prefixos, batching contínuo), mas históricos e ecossistemas distintos.

Um único usuário, computador pessoal

Ollama ou llama.cpp continuam sendo mais fáceis de instalar e rodar em CPUs ou GPUs de uso doméstico, sem configurar um serviço de rede.

Vários usuários, sistema já construído com vLLM

Permanecer com vLLM evita uma migração; nosso guia específico aborda sua implantação em produção.

Vários usuários, prioridade ao throughput com prefixos compartilhados

SGLang, com RadixAttention, é o candidato natural — desde que você tenha uma GPU compatível com CUDA.

Você deseja compatibilidade com o cliente Ollama sem instalar o Ollama

SGLang oferece uma API compatível com a CLI e a biblioteca Python Ollama, o que permite reutilizar scripts existentes sem precisar rodar o servidor Ollama em si.

Para um panorama mais amplo das arquiteturas de inferência (llama.cpp, vLLM, Exllama), o comparativo de backends do site detalha as vantagens e limitações para além do caso específico do SGLang.

#O que o hardware exige

O guia de início rápido do SGLang é explícito: uma GPU NVIDIA com suporte a CUDA sm80 ou superior (A10, A100, L4, L40S, H100) é um pré-requisito para a instalação padrão no Linux, a plataforma recomendada. O projeto também anuncia suporte a uma gama mais ampla de hardware — GPUs AMD (MI355, MI300), CPUs Intel Xeon, TPUs Google, NPUs Ascend — por meio de procedimentos de instalação específicos e distintos do procedimento principal para GPUs NVIDIA.

#O custo de memória por requisição

“Servir vários usuários” significa, na prática, um consumo de VRAM que cresce com o número de requisições ativas, não apenas com o tamanho do modelo. O cache KV gerenciado por --mem-fraction-static e --max-total-tokens armazena, para cada token já gerado em uma requisição, dois vetores (chave e valor) por camada de atenção. A fórmula geral é: bytes por token = 2 × número de camadas × número de cabeças de atenção KV × dimensão de uma cabeça × bytes por valor (2 em FP16/BF16, 1 em FP8).

Cálculo ilustrativo para uma arquitetura próxima de Llama-3.1-8B-Instruct (32 camadas, 8 cabeças KV em atenção agrupada, dimensão de cada cabeça de 128): em FP16, isso dá 2 × 32 × 8 × 128 × 2 = 131.072 bytes por token, ou aproximadamente 128 KB por token. Para uma requisição com 8.192 tokens de contexto (prompt e resposta somados), o cache KV dessa única requisição ocupa então aproximadamente 1 GB de VRAM — antes mesmo de contar os pesos do modelo. Em uma GPU de 24 GB com cerca de 16 GB reservados para os pesos em Q4 e para a infraestrutura básica do runtime, a margem restante deixa espaço apenas para algumas requisições ativas simultâneas nesse nível de contexto, o que explica por que um limite explícito em --max-running-requests evita uma degradação em vez de uma rejeição controlada das novas conexões.

#Segurança e observabilidade

Por padrão, a API SGLang iniciada com sglang.launch_server não exige autenticação: qualquer pessoa que consiga acessar a porta 30000 pode enviar requisições. A opção --api-key define uma chave exigida pelo servidor, inclusive no seu endpoint compatível com OpenAI; sem ela, expor o servidor além de localhost ou de uma rede interna de confiança equivale a deixar o acesso aberto à inferência e, portanto, aos custos de GPU associados.

Para o acompanhamento em produção, a opção --enable-metrics (desativada por padrão) publica métricas no formato Prometheus em um endpoint /metrics: taxa de requisições, latência de inferência, velocidade de geração de tokens e eficiência do cache são expostas para scraping periódico, em vez de adivinhar o estado do servidor a partir apenas dos logs.

• Princípios de segurança de um servidor de inferência exposto
• Fonte: referência dos argumentos do servidor (--api-key, --enable-metrics)

#Solução de problemas: sintomas, causa, correção

#Limitações e pontos de atenção

O número “até 5 vezes mais rápido” que ainda acompanha a apresentação do RadixAttention remonta ao anúncio inicial do projeto em janeiro de 2024: ele ilustra a contribuição do mecanismo no ambiente de testes da época, não um ganho garantido em uma implantação recente com modelos e GPUs diferentes. O dimensionamento real depende da taxa de compartilhamento de prefixos entre requisições, do modelo escolhido e da GPU utilizada — deve ser avaliado no seu próprio tráfego, em vez de deduzido do anúncio original.

A migração obrigatória para CUDA 13 (a versão 0.5.19 é a última a oferecer uma opção com CUDA 12) merece uma verificação do driver da GPU e da versão do CUDA instalada antes de qualquer atualização para uma versão recente, sob pena de falha na instalação em um servidor que tenha permanecido com CUDA 12.

A frequência de lançamento do projeto também deve ser monitorada para uma implantação em produção: o SGLang lança versões menores aproximadamente a cada duas ou três semanas (v0.5.20 em 18 de setembro de 2026, v0.5.19 em 5 de setembro, v0.5.18 em 22 de agosto), o que exige fixar uma versão específica nas imagens Docker em vez de seguir a tag latest em um serviço em produção, sob o risco de uma mudança de comportamento inesperada durante uma nova implantação.

• Implantar vLLM em produção
• vLLM: o que é, para quem e quando usar?
• llama.cpp vs vLLM vs Exllama
• Fonte: documentação oficial SGLang
• Fonte: README oficial do repositório SGLang
• Fonte: referência dos argumentos do servidor