Guida rapida a SGLang: installazione, configurazione e distribuzione di LLM tramite l'API OpenAI

Servire modelli open-source rapidamente con SGLang.

Indice

SGLang è un framework di serving ad alte prestazioni per grandi modelli linguistici e modelli multimodali, progettato per fornire inferenza a bassa latenza e alto throughput in tutto, da una singola GPU a cluster distribuiti.

Per un confronto più ampio delle opzioni di hosting LLM self-hosted e cloud — inclusi Ollama, vLLM, llama-swap, LocalAI e provider cloud gestiti — consulta la guida all’hosting LLM per il 2026.

Se hai già applicazioni collegate alla struttura dell’API OpenAI, SGLang è particolarmente attraente perché può esporre endpoint compatibili con OpenAI per completi conversazionali e completamenti, aiutandoti a migrare da API ospitate a modelli self-hosted con modifiche minime lato client. Quando hai bisogno di instradare le richieste attraverso più backend (llama.cpp, vLLM, SGLang, ecc.) con hot-swap e scaricamento basato su TTL, llama-swap fornisce uno strato proxy trasparente che mantiene stabile un singolo URL /v1 mentre sostituisce gli upstream su richiesta.

sglang infographic

Questo QuickStart illustra l’installazione (con metodi multipli), modelli di configurazione pratici e un flusso di lavoro pulito “installa → serve → verifica → integra → ottimizza”, con esempi funzionanti sia per il serving HTTP che per l’inferenza batch offline.

Se hai bisogno di supporto multimodale (testo, embedding, immagini, audio) con un’interfaccia Web integrata e la massima compatibilità plug-and-play dell’API OpenAI, LocalAI offre un set di funzionalità più ampio con supporto per più formati di modello.

Cos’è SGLang per il serving ad alto throughput di LLM e modelli multimodali

Nel suo nucleo, SGLang è progettato per un’inferenza efficiente e un serving scalabile. Lo stack “runtime veloce” include RadixAttention per la cache dei prefissi, uno scheduler CPU a zero overhead, decodifica speculativa, batching continuo, attenzione a pagine, multiple strategie di parallelismo (tensoriale, pipeline, esperti, dati), output strutturati, prefill a blocchi e multiple opzioni di quantizzazione (ad esempio FP4, FP8, INT4, AWQ, GPTQ).

Si rivolge a una distribuzione su piattaforme ampie: GPU NVIDIA, GPU AMD, CPU Intel Xeon, TPU Google, NPU Ascend e molto altro.

PyPI richiede Python >= 3.10. Al 20 marzo 2026, la linea pubblicata includeva 0.5.9 (rilasciata il 23 febbraio 2026) — fissa o controlla le versioni attuali durante l’installazione.

Come installare SGLang su host Linux GPU con uv pip, build da sorgente o Docker

Le opzioni di installazione includono uv o pip, build da sorgente, immagini Docker, manifesti Kubernetes, Docker Compose, SkyPilot e AWS SageMaker. La maggior parte delle guide presuppone configurazioni comuni di GPU NVIDIA; altri acceleratori hanno le proprie note di configurazione altrove.

Installa SGLang rapidamente con uv o pip su Python 3.10+

Per un’installazione locale diretta, uv è solitamente il percorso più veloce:

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

Note su CUDA 13

Per CUDA 13, Docker evita incompatibilità lato host tra PyTorch e CUDA. Senza Docker: installa una build PyTorch per CUDA 13, poi sglang, quindi la ruota sglang-kernel corrispondente dalle release di ruote pubblicate (la versione deve corrispondere allo stack).

# 1) Installa PyTorch con supporto CUDA 13 (sostituisci X.Y.Z se necessario)
uv pip install torch==X.Y.Z torchvision torchaudio --index-url https://download.pytorch.org/whl/cu130

# 2) Installa SGLang
uv pip install sglang

# 3) Installa la ruota sglang-kernel corrispondente per CUDA 13 (sostituisci 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"

Installa ed esegui SGLang con immagini Docker Hub

Per deployment containerizzati — o per evitare l’abbinamento CUDA/PyTorch dell’host — usa le immagini Docker Hub pubblicate. Un tipico docker run monta la cache di Hugging Face e passa HF_TOKEN quando si scaricano modelli protetti.

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

Per immagini di stile produzione, latest-runtime elimina gli strumenti di build e le dipendenze di sviluppo, mantenendo l’immagine molto più piccola rispetto alla variante latest predefinita.

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

Installa da sorgente e altri metodi di deployment

Per sviluppare contro SGLang o applicare patch locali, clona un ramo di release e installa il pacchetto Python in modalità modificabile:

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

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

Per l’orchestrazione, il repo include manifesti Kubernetes (single e multi-nodo) e una layout Docker Compose minimale — punti di partenza ragionevoli prima di un cablaggio personalizzato.

Come configurare gli argomenti del server SGLang con file di configurazione YAML e variabili d’ambiente

La configurazione di SGLang è guidata da argomenti del server e variabili d’ambiente. I flag coprono la selezione del modello, il parallelismo, la memoria e manopole di ottimizzazione; l’insieme completo è elencato con python3 -m sglang.launch_server --help.

Le variabili d’ambiente usano due prefissi: SGL_ e SGLANG_ (molti flag accettano sia la forma CLI che quella ambientale — launch_server --help mostra il mapping).

Alcune variabili d’ambiente comunemente rilevanti includono controlli di host e porta come SGLANG_HOST_IP e SGLANG_PORT.

Usa un file di configurazione YAML per avvii del server SGLang riproducibili

Per deployment ripetibili e linee di comando più brevi, passa un file YAML con --config. Gli argomenti CLI sovrascrivono i valori dal file quando entrambi impostano la stessa opzione.

# Crea 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

# Avvia il server con file di configurazione
python -m sglang.launch_server --config config.yaml

Alcuni elementi essenziali di configurazione e tuning da tenere a mente:

Il --model-path di SGLang può puntare a una cartella locale o a un ID repository di Hugging Face, rendendo facile passare tra pesi locali e modelli ospitati sull’Hub senza cambiare il codice di serving.

Per multi-GPU, abilita il parallelismo tensoriale con --tp. Se l’avvio fallisce con “peer access is not supported between these two devices”, aggiungi --enable-p2p-check.

Se il serving incontra OOM, riduci la pressione sulla cache KV con un --mem-fraction-static più piccolo (il predefinito è 0.9).

Se i prompt lunghi causano OOM durante il prefill, abbassa --chunked-prefill-size.

Come eseguire un server SGLang compatibile con OpenAI e chiamarlo dal client Python OpenAI

Un flusso di lavoro pratico “happy path” è simile a questo:

  1. Installa SGLang (uv/pip o Docker).
  2. Avvia il server con il modello e la porta scelti.
  3. Verifica il serving di base tramite endpoint compatibili con OpenAI.
  4. Integra la tua applicazione puntando il base_url SDK OpenAI al server locale.
  5. Ottimizza throughput e memoria con argomenti del server una volta che hai traffico reale.

Invia una richiesta di completamento chat locale a SGLang usando SDK OpenAI

Per l’uso compatibile con OpenAI, due dettagli sono importanti:

Il server implementa la superficie HTTP di OpenAI e, quando il tokenizer ne fornisce uno, applica automaticamente il template chat di Hugging Face. Sovrascrivi con --chat-template all’avvio se necessario.

Punta un client OpenAI al prefisso /v1 del server (base_url → http://<host>:<port>/v1), poi chiama client.chat.completions.create(...) come al solito.

Avvia il server con uno dei due entrypoint: python -m sglang.launch_server funziona ancora, ma sglang serve è la CLI preferita.

# Entrypoint CLI consigliato
sglang serve --model-path qwen/qwen2.5-0.5b-instruct --host 0.0.0.0 --port 30000

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

Poi chiamalo con il client Python 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": "Elenca 3 paesi e le loro capitali."}],
    temperature=0,
    max_tokens=64,
)

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

Come eseguire l’inferenza batch con l’API Offline Engine di SGLang e endpoint nativi

SGLang supporta multiple “superfici API” a seconda di cosa stai costruendo:

L’endpoint /generate è l’API runtime a basso livello. Preferisci le rotte OpenAI-compatible /v1/... quando vuoi che i template chat e l’ecosistema client abituale siano gestiti per te.

Senza alcun server HTTP, l’Offline Engine esegue l’inferenza in-process: adatto a lavori batch e servizi personalizzati. Supporta combinazioni sync/async e streaming/non-streaming — scegli la modalità che corrisponde al pattern di chiamata.

Esempio usando l’endpoint nativo /generate

Pattern minimale: avvia un server, poi fai POST /generate con temperature e max_new_tokens (e qualsiasi altro campo di campionamento di cui hai bisogno).

import requests

response = requests.post(
    "http://localhost:30000/generate",
    json={
        "text": "La capitale della Francia è",
        "sampling_params": {
            "temperature": 0,
            "max_new_tokens": 32,
        },
    },
)

print(response.json())

temperature = 0 è campionamento greedy; valori più alti aumentano la diversità.

Esempio usando l’API Offline Engine per inferenza batch in-process

Flusso tipico: costruisci sgl.Engine(model_path=...), esegui llm.generate(...) su un batch di prompt, poi llm.shutdown() per rilasciare GPU e altre risorse.

import sglang as sgl

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

prompts = [
    "Scrivi una breve presentazione di te stesso.",
    "Spiega cos'è la cache dei prefissi in un paragrafo.",
]

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("OUTPUT:", output["text"])
    print()

llm.shutdown()