SGLang

Framework de serving de alto desempenho para LLMs e VLMs com RadixAttention para cache automático de prefixos.

Quando usar SGLang

Use SGLang quando:

• Precisa de saídas estruturadas (JSON, regex, gramática)
• Construindo agentes com prefixos repetidos (prompts de sistema, ferramentas)
• Workflows com agentes e chamadas de funções
• Conversas com múltiplos turnos e contexto compartilhado
• Precisa de decodificação JSON mais rápida (3× vs padrão)

Use vLLM em vez disso quando:

• Geração de texto simples sem estrutura
• Não precisa de cache de prefixos
• Quer um sistema de produção maduro e amplamente testado

Use TensorRT-LLM em vez disso quando:

• Latência máxima de requisição única (sem batching necessário)
• Deploy apenas em NVIDIA
• Precisa de quantização FP8/INT4 em H100

Início rápido

Instalação

# pip install (recomendado)
pip install "sglang[all]"

# Com FlashInfer (mais rápido, CUDA 11.8/12.1)
pip install sglang[all] flashinfer -i https://flashinfer.ai/whl/cu121/torch2.4/

# Desde a fonte
git clone https://github.com/sgl-project/sglang.git
cd sglang
pip install -e "python[all]"

Inicie o servidor

# Servidor básico (Llama 3-8B)
python -m sglang.launch_server \
    --model-path meta-llama/Meta-Llama-3-8B-Instruct \
    --port 30000

# Com RadixAttention (cache automático de prefixos)
python -m sglang.launch_server \
    --model-path meta-llama/Meta-Llama-3-8B-Instruct \
    --port 30000 \
    --enable-radix-cache  # Padrão: habilitado

# Multi-GPU (tensor parallelism)
python -m sglang.launch_server \
    --model-path meta-llama/Meta-Llama-3-70B-Instruct \
    --tp 4 \
    --port 30000

Inferência básica

import sglang as sgl

# Defina backend
sgl.set_default_backend(sgl.OpenAI("http://localhost:30000/v1"))

# Geração simples
@sgl.function
def simple_gen(s, question):
    s += "Q: " + question + "\n"
    s += "A:" + sgl.gen("answer", max_tokens=100)

# Execute
state = simple_gen.run(question="What is the capital of France?")
print(state["answer"])
# Output: "The capital of France is Paris."

Saída JSON estruturada

import sglang as sgl

@sgl.function
def extract_person(s, text):
    s += f"Extract person information from: {text}\n"
    s += "Output JSON:\n"

    # Geração JSON restrita
    s += sgl.gen(
        "json_output",
        max_tokens=200,
        regex=r'\{"name": "[^"]+", "age": \d+, "occupation": "[^"]+"\}'
    )

# Execute
state = extract_person.run(
    text="John Smith is a 35-year-old software engineer."
)
print(state["json_output"])
# Output: {"name": "John Smith", "age": 35, "occupation": "software engineer"}

RadixAttention (Inovação Principal)

O que faz: Automaticamente faz cache e reutiliza prefixos comuns entre requisições.

Desempenho:

• 5× mais rápido para workloads com agentes e prompts de sistema compartilhados
• 10× mais rápido para few-shot prompting com exemplos repetidos
• Zero configuração - funciona automaticamente

Como funciona:

1. Constrói árvore radix de todos os tokens processados
2. Detecta automaticamente prefixos compartilhados
3. Reutiliza cache KV para prefixos correspondentes
4. Computa apenas novos tokens

Exemplo (Agente com prompt de sistema):

Requisição 1: [SYSTEM_PROMPT] + "What's the weather?"
→ Computa prompt completo (1000 tokens)

Requisição 2: [SAME_SYSTEM_PROMPT] + "Book a flight"
→ Reutiliza cache KV do prompt de sistema (998 tokens)
→ Computa apenas 2 novos tokens
→ 5× mais rápido!

Padrões de geração estruturada

JSON com schema

@sgl.function
def structured_extraction(s, article):
    s += f"Article: {article}\n\n"
    s += "Extract key information as JSON:\n"

    # Constraint de schema JSON
    schema = {
        "type": "object",
        "properties": {
            "title": {"type": "string"},
            "author": {"type": "string"},
            "summary": {"type": "string"},
            "sentiment": {"type": "string", "enum": ["positive", "negative", "neutral"]}
        },
        "required": ["title", "author", "summary", "sentiment"]
    }

    s += sgl.gen("info", max_tokens=300, json_schema=schema)

state = structured_extraction.run(article="...")
print(state["info"])
# Output: JSON válido correspondendo ao schema

Geração restrita por regex

@sgl.function
def extract_email(s, text):
    s += f"Extract email from: {text}\n"
    s += "Email: "

    # Padrão regex de email
    s += sgl.gen(
        "email",
        max_tokens=50,
        regex=r'[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
    )

state = extract_email.run(text="Contact john.doe@example.com for details")
print(state["email"])
# Output: "john.doe@example.com"

Geração baseada em gramática

@sgl.function
def generate_code(s, description):
    s += f"Generate Python code for: {description}\n"
    s += "```python\n"

    # Gramática EBNF para Python
    python_grammar = """
    ?start: function_def
    function_def: "def" NAME "(" [parameters] "):" suite
    parameters: parameter ("," parameter)*
    parameter: NAME
    suite: simple_stmt | NEWLINE INDENT stmt+ DEDENT
    """

    s += sgl.gen("code", max_tokens=200, grammar=python_grammar)
    s += "\n```"

Workflows com agentes e chamadas de funções

import sglang as sgl

# Defina ferramentas
tools = [
    {
        "name": "get_weather",
        "description": "Get weather for a location",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {"type": "string"}
            }
        }
    },
    {
        "name": "book_flight",
        "description": "Book a flight",
        "parameters": {
            "type": "object",
            "properties": {
                "from": {"type": "string"},
                "to": {"type": "string"},
                "date": {"type": "string"}
            }
        }
    }
]

@sgl.function
def agent_workflow(s, user_query, tools):
    # Prompt de sistema (cacheado com RadixAttention)
    s += "You are a helpful assistant with access to tools.\n"
    s += f"Available tools: {tools}\n\n"

    # Consulta do usuário
    s += f"User: {user_query}\n"
    s += "Assistant: "

    # Gere com function calling
    s += sgl.gen(
        "response",
        max_tokens=200,
        tools=tools,  # SGLang manipula o formato de chamadas de função
        stop=["User:", "\n\n"]
    )

# Múltiplas consultas reutilizam prompt de sistema
state1 = agent_workflow.run(
    user_query="What's the weather in NYC?",
    tools=tools
)
# Primeira chamada: Computa prompt de sistema completo

state2 = agent_workflow.run(
    user_query="Book a flight to LA",
    tools=tools
)
# Segunda chamada: Reutiliza prompt de sistema (5× mais rápido)

Benchmarks de desempenho

Speedup do RadixAttention

Few-shot prompting (10 exemplos no prompt):

• vLLM: 2.5 seg/requisição
• SGLang: 0.25 seg/requisição (10× mais rápido)
• Throughput: 4× maior

Workflows com agentes (prompt de sistema com 1000 tokens):

• vLLM: 1.8 seg/requisição
• SGLang: 0.35 seg/requisição (5× mais rápido)

Decodificação JSON:

• Padrão: 45 tok/s
• SGLang: 135 tok/s (3× mais rápido)

Throughput (Llama 3-8B, A100)

Workload	vLLM	SGLang	Speedup
Geração simples	2500 tok/s	2800 tok/s	1.12×
Few-shot (10 exemplos)	500 tok/s	5000 tok/s	10×
Agente (chamadas de ferramentas)	800 tok/s	4000 tok/s	5×
Saída JSON	600 tok/s	2400 tok/s	4×

Conversas com múltiplos turnos

@sgl.function
def multi_turn_chat(s, history, new_message):
    # Prompt de sistema (sempre cacheado)
    s += "You are a helpful AI assistant.\n\n"

    # Histórico de conversa (cacheado conforme cresce)
    for msg in history:
        s += f"{msg['role']}: {msg['content']}\n"

    # Nova mensagem do usuário (apenas a nova parte)
    s += f"User: {new_message}\n"
    s += "Assistant: "
    s += sgl.gen("response", max_tokens=200)

# Turno 1
history = []
state = multi_turn_chat.run(history=history, new_message="Hi there!")
history.append({"role": "User", "content": "Hi there!"})
history.append({"role": "Assistant", "content": state["response"]})

# Turno 2 (reutiliza cache KV do Turno 1)
state = multi_turn_chat.run(history=history, new_message="What's 2+2?")
# Computa apenas a nova mensagem (muito mais rápido!)

# Turno 3 (reutiliza cache KV do Turno 1 + Turno 2)
state = multi_turn_chat.run(history=history, new_message="Tell me a joke")
# Progressivamente mais rápido conforme o histórico cresce

Recursos avançados

Decodificação especulativa

# Inicie com modelo draft (2-3× mais rápido)
python -m sglang.launch_server \
    --model-path meta-llama/Meta-Llama-3-70B-Instruct \
    --speculative-model meta-llama/Meta-Llama-3-8B-Instruct \
    --speculative-num-steps 5

Multi-modal (modelos de visão)

@sgl.function
def describe_image(s, image_path):
    s += sgl.image(image_path)
    s += "Describe this image in detail: "
    s += sgl.gen("description", max_tokens=200)

state = describe_image.run(image_path="photo.jpg")
print(state["description"])

Batching e requisições paralelas

# Batching automático (continuous batching)
states = sgl.run_batch(
    [
        simple_gen.bind(question="What is AI?"),
        simple_gen.bind(question="What is ML?"),
        simple_gen.bind(question="What is DL?"),
    ]
)

# Todos os 3 processados em um único batch (eficiente)

API compatível com OpenAI

# Inicie servidor com API OpenAI
python -m sglang.launch_server \
    --model-path meta-llama/Meta-Llama-3-8B-Instruct \
    --port 30000

# Use com cliente OpenAI
curl http://localhost:30000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [
      {"role": "system", "content": "You are helpful"},
      {"role": "user", "content": "Hello"}
    ],
    "temperature": 0.7,
    "max_tokens": 100
  }'

# Funciona com SDK Python do OpenAI
from openai import OpenAI
client = OpenAI(base_url="http://localhost:30000/v1", api_key="EMPTY")

response = client.chat.completions.create(
    model="default",
    messages=[{"role": "user", "content": "Hello"}]
)

Modelos suportados

Modelos de texto:

• Llama 2, Llama 3, Llama 3.1, Llama 3.2
• Mistral, Mixtral
• Qwen, Qwen2, QwQ
• DeepSeek-V2, DeepSeek-V3
• Gemma, Phi-3

Modelos de visão:

• LLaVA, LLaVA-OneVision
• Phi-3-Vision
• Qwen2-VL

100+ modelos do HuggingFace

Suporte a hardware

NVIDIA: A100, H100, L4, T4 (CUDA 11.8+) AMD: MI300, MI250 (ROCm 6.0+) Intel: Xeon com GPU (em breve) Apple: M1/M2/M3 via MPS (experimental)

Referências

• Guia de Geração Estruturada - Schemas JSON, regex, gramáticas, validação
• Mergulho Profundo em RadixAttention - Como funciona, otimização, benchmarks
• Deploy em Produção - Multi-GPU, monitoramento, autoscaling

Recursos

• GitHub: https://github.com/sgl-project/sglang
• Docs: https://sgl-project.github.io/
• Paper: RadixAttention (arXiv:2312.07104)
• Discord: https://discord.gg/sglang