SGLang QuickStart: Instale, Configure e Execute LLMs via API OpenAI

Execute modelos abertos com rapidez usando o SGLang.

Conteúdo da página

O SGLang é um framework de serviço de alto desempenho para grandes modelos de linguagem e modelos multimodais, construído para fornecer inferência de baixa latência e alto throughput, desde uma única GPU até clusters distribuídos.

Para uma comparação mais ampla das opções de hospedagem de LLMs auto-hospedados e em nuvem — incluindo Ollama, vLLM, llama-swap, LocalAI e provedores de nuvem gerenciados — consulte o Guia de hospedagem de LLM para 2026.

Se você já possui aplicativos conectados à estrutura da API do OpenAI, o SGLang é especialmente atraente, pois pode expor endpoints compatíveis com o OpenAI para conversas e conclusões, ajudando você a migrar de APIs hospedadas para modelos auto-hospedados com alterações mínimas no lado do cliente. Quando você precisa rotear solicitações entre vários backends (llama.cpp, vLLM, SGLang, etc.) com troca dinâmica (hot-swap) e descarregamento baseado em TTL, o llama-swap fornece uma camada de proxy transparente que mantém uma única URL /v1 estável enquanto troca os upstreams sob demanda.

infográfico do sglang

Este QuickStart percorre a instalação (métodos múltiplos), padrões de configuração práticos e um fluxo de trabalho limpo de “instalar → servir → verificar → integrar → ajustar”, com exemplos funcionais tanto para serviço HTTP quanto para inferência em lote offline.

Se você precisa de suporte multimodal (texto, embeddings, imagens, áudio) com uma interface Web nativa e compatibilidade máxima de drop-in da API do OpenAI, o LocalAI oferece um conjunto de recursos mais amplo com suporte a mais formatos de modelo.

O que é o SGLang para serviço de LLM e modelos multimodais de alto throughput

Em seu núcleo, o SGLang é projetado para inferência eficiente e escalável. A pilha de “runtime rápido” inclui RadixAttention para cache de prefixos, um agendador de CPU sem sobrecarga, decodificação especulativa, batching contínuo, atenção paginada, múltiplas estratégias de paralelismo (tensor, pipeline, especialista, paralelo de dados), saídas estruturadas, prefill em fatias (chunked) e múltiplas opções de quantização (por exemplo, FP4, FP8, INT4, AWQ, GPTQ).

Ele tem como alvo implantação em várias plataformas: GPUs NVIDIA, GPUs AMD, CPUs Intel Xeon, TPUs do Google, NPUs Ascend e mais.

O PyPI requer Python >= 3.10. Até 23 de março de 2026, a linha publicada incluía a versão 0.5.9 (lançada em 23 de fevereiro de 2026) — fixe ou verifique as versões atuais ao instalar.

Como instalar o SGLang em hosts Linux com GPU usando uv pip, compilações de fonte ou Docker

As opções de instalação incluem uv ou pip, compilações de fonte, imagens Docker, manifestos Kubernetes, Docker Compose, SkyPilot e AWS SageMaker. A maioria dos tutoriais pressupõe configurações comuns de GPU NVIDIA; outros aceleradores possuem suas próprias notas de configuração em outros lugares.

Instale o SGLang rapidamente com uv ou pip no Python 3.10+

Para uma instalação local direta, uv geralmente é o caminho mais rápido:

pip install --upgrade pip
pip install uv
uv pip install sglang

Notas sobre CUDA 13

Para o CUDA 13, o Docker evita incompatibilidades de PyTorch/CUDA no host. Sem Docker: instale uma compilação do PyTorch com CUDA 13, depois o sglang e, em seguida, a roda (wheel) correspondente do sglang-kernel das versões publicadas de rodas (a versão deve corresponder à pilha).

# 1) Instale o PyTorch com suporte ao CUDA 13 (substitua X.Y.Z conforme necessário)
uv pip install torch==X.Y.Z torchvision torchaudio --index-url https://download.pytorch.org/whl/cu130

# 2) Instale o SGLang
uv pip install sglang

# 3) Instale a roda sglang-kernel correspondente ao CUDA 13 (substitua X.Y.Z)
uv pip install "https://github.com/sgl-project/whl/releases/download/vX.Y.Z/sglang_kernel-X.Y.Z+cu130-cp310-abi3-manylinux2014_x86_64.whl"

Instale e execute o SGLang com imagens do Docker Hub

Para implantações containerizadas — ou para contornar a combinação de CUDA/PyTorch do host — use as imagens publicadas no Docker Hub. Um docker run típico monta o cache do Hugging Face e passa HF_TOKEN ao baixar modelos restritos.

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

Para imagens de estilo de produção, latest-runtime remove as ferramentas de construção e dependências de desenvolvimento, mantendo a imagem muito menor do que a variante padrão latest.

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-runtime \
  python3 -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-8B-Instruct \
    --host 0.0.0.0 \
    --port 30000

Instale do fonte e outros métodos de implantação

Para desenvolver com o SGLang ou aplicar patches locais, clone uma分支 de lançamento e instale o pacote Python em modo editável:

git clone -b v0.5.9 https://github.com/sgl-project/sglang.git
cd sglang

pip install --upgrade pip
pip install -e "python"

Para orquestração, o repositório inclui manifestos Kubernetes (de nó único e múltiplos) e um layout mínimo do Docker Compose — pontos de partida razoáveis antes de configurações personalizadas.

Como configurar argumentos do servidor SGLang com arquivos de configuração YAML e variáveis de ambiente

A configuração do SGLang é impulsionada por argumentos do servidor e variáveis de ambiente. As flags cobrem seleção de modelo, paralelismo, memória e controles de otimização; o conjunto completo é listado com python3 -m sglang.launch_server --help.

As variáveis de ambiente usam dois prefixos: SGL_ e SGLANG_ (muitas flags aceitam a forma de CLI ou de ambiente — launch_server --help mostra o mapeamento).

Algumas variáveis de ambiente frequentemente relevantes incluem controles de host e porta como SGLANG_HOST_IP e SGLANG_PORT.

Use um arquivo de configuração YAML para lançamentos de servidor SGLang reproduzíveis

Para implantações repetíveis e linhas de comando mais curtas, passe um arquivo YAML com --config. Argumentos de CLI substituem valores do arquivo quando ambos definem a mesma opção.

# Crie config.yaml
cat > config.yaml << 'EOF'
model-path: meta-llama/Meta-Llama-3-8B-Instruct
host: 0.0.0.0
port: 30000
tensor-parallel-size: 2
enable-metrics: true
log-requests: true
EOF

# Inicie o servidor com o arquivo de configuração
python -m sglang.launch_server --config config.yaml

Alguns essenciais de configuração e ajuste a ter em mente:

O --model-path do SGLang pode apontar para uma pasta local ou um ID de repositório do Hugging Face, o que facilita alternar entre pesos locais e modelos hospedados no Hub sem alterar seu código de serviço.

Para multi-GPU, ative o paralelismo de tensor com --tp. Se a inicialização falhar com “peer access is not supported between these two devices”, adicione --enable-p2p-check.

Se o serviço atingir OOM (erro de memória), reduza a pressão do cache KV com um --mem-fraction-static menor (o padrão é 0.9).

Se prompts longos causarem OOM durante o prefill, diminua --chunked-prefill-size.

Como executar um servidor SGLang compatível com OpenAI e chamá-lo do cliente Python do OpenAI

Um fluxo de trabalho prático de “caminho feliz” parece com isso:

  1. Instale o SGLang (uv/pip ou Docker).
  2. Inicie o servidor com seu modelo e porta escolhidos.
  3. Verifique o serviço básico via endpoints compatíveis com OpenAI.
  4. Integre seu aplicativo apontando o base_url do SDK do OpenAI para o servidor local.
  5. Ajuste o throughput e a memória com argumentos do servidor assim que tiver tráfego real.

Envie uma solicitação de conclusão de chat local ao SGLang usando o SDK do OpenAI

Para uso compatível com OpenAI, dois detalhes importam:

O servidor implementa a superfície HTTP do OpenAI e, quando o tokenizador fornece um, aplica o modelo de chat do Hugging Face automaticamente. Substitua com --chat-template na inicialização, se necessário.

Aponte um cliente do OpenAI para o prefixo /v1 do servidor (base_url → http://<host>:<port>/v1), depois chame client.chat.completions.create(...) como de costume.

Inicie o servidor com qualquer ponto de entrada: python -m sglang.launch_server ainda funciona, mas sglang serve é a CLI preferida.

# Ponto de entrada de CLI recomendado
sglang serve --model-path qwen/qwen2.5-0.5b-instruct --host 0.0.0.0 --port 30000

# Ainda suportado
python3 -m sglang.launch_server --model-path qwen/qwen2.5-0.5b-instruct --host 0.0.0.0 --port 30000

Depois, chame-o com o cliente Python do OpenAI:

import openai

client = openai.Client(base_url="http://127.0.0.1:30000/v1", api_key="None")

response = client.chat.completions.create(
    model="qwen/qwen2.5-0.5b-instruct",
    messages=[{"role": "user", "content": "Liste 3 países e suas capitais."}],
    temperature=0,
    max_tokens=64,
)

print(response.choices[0].message.content)

Como executar inferência em lote com a API do SGLang Offline Engine e endpoints nativos

O SGLang suporta múltiplas “superfícies de API” dependendo do que você está construindo:

O endpoint /generate é a API de runtime de baixo nível. Prefira as rotas compatíveis com OpenAI /v1/... quando quiser que modelos de chat e o ecossistema de clientes habituais sejam tratados para você.

Sem nenhum servidor HTTP, o Offline Engine executa inferência no processo: adequado para trabalhos em lote e serviços personalizados. Ele suporta combinações síncrono/assíncrono e streaming/não-streaming — escolha o modo que corresponda ao padrão de chamada.

Exemplo usando o endpoint nativo /generate

Padrão mínimo: execute um servidor, depois faça POST em /generate com temperature e max_new_tokens (e quaisquer outros campos de amostragem que você precise).

import requests

response = requests.post(
    "http://localhost:30000/generate",
    json={
        "text": "A capital da França é",
        "sampling_params": {
            "temperature": 0,
            "max_new_tokens": 32,
        },
    },
)

print(response.json())

temperature = 0 é amostragem gulosa; valores mais altos aumentam a diversidade.

Exemplo usando a API Offline Engine para inferência em lote no processo

Fluxo típico: construa sgl.Engine(model_path=...), execute llm.generate(...) sobre um lote de prompts, depois llm.shutdown() para liberar a GPU e outros recursos.

import sglang as sgl

llm = sgl.Engine(model_path="qwen/qwen2.5-0.5b-instruct")

prompts = [
    "Escreva uma breve autoapresentação.",
    "Explique o que é cache de prefixos em um parágrafo.",
]

sampling_params = {"temperature": 0.2, "top_p": 0.9}

outputs = llm.generate(prompts, sampling_params)
for prompt, output in zip(prompts, outputs):
    print("PROMPT:", prompt)
    print("SAÍDA:", output["text"])
    print()

llm.shutdown()