SGLang: servire un LLM locale a più persone utilisateurs

#Cosa fa SGLang

SGLang si presenta come un framework ad alte prestazioni per servire LLM e modelli multimodali, progettato per un'inferenza a bassa latenza e ad alto throughput, da una singola GPU fino a grandi cluster distribuiti. Il progetto dichiara che le sue implementazioni in produzione generano trilioni di token ogni giorno su oltre 400.000 GPU nel mondo ed è ospitato dall'organizzazione open source senza scopo di lucro LMSYS.

Compatibile con le API OpenAI e Hugging Face, SGLang supporta una vasta gamma di modelli (Llama, Qwen, DeepSeek, GLM, Mistral, Gemma) e di hardware (GPU NVIDIA, AMD, CPU Intel Xeon, TPU Google, NPU Ascend). Al 28 settembre 2026, la versione più recente è v0.5.20, pubblicata il 18 settembre 2026.

#Installare e avviare il server

L'installazione consigliata dalla documentazione ufficiale prevede uv, più veloce di pip classico. È necessario il flag --prerelease=allow perché alcune dipendenze di SGLang pubblicano solo versioni pre-release su PyPI.

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

L'avvio in un container Docker resta la soluzione più riproducibile per un deployment su server, con la porta 30000 utilizzata per impostazione predefinita per l'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

La documentazione precisa che SGLang richiede ora CUDA 13: le immagini e i pacchetti wheel CUDA 12 (cu129) sono stati rimossi da quando PyTorch 2.14 non pubblica più build CUDA 12.9, e la versione 0.5.19 rimane l'ultima a offrire un'opzione per CUDA 12. Un deployment su hardware meno recente deve quindi mantenere fissa questa versione o verificare il driver GPU prima di aggiornare.

#RadixAttention e la cache dei prefissi

Il cuore della promessa di throughput di SGLang è RadixAttention: i prefissi delle sequenze già calcolati (un system prompt condiviso, l'inizio di una conversazione a più turni) vengono organizzati in un albero radix e riutilizzati tra richieste, invece di essere ricalcolati a ogni chiamata. Nell'annuncio iniziale del progetto, a gennaio 2024, si dichiarava un'inferenza fino a 5 volte più veloce grazie a questo meccanismo — un dato annunciato dal progetto sulla base del proprio banco di prova dell'epoca, non una misurazione indipendente recente sul tuo hardware.

Questo vantaggio si manifesta soprattutto negli scenari con prefissi condivisi: più utenti che inviano richieste con lo stesso system prompt, un agente che rilegge lo stesso contesto a ogni turno oppure il few-shot con gli stessi esempi. Un flusso di richieste senza alcun prefisso comune (domande del tutto indipendenti, senza cronologia) trae molto meno beneficio da RadixAttention.

Il runtime combina RadixAttention con uno scheduler CPU senza overhead, la disaggregazione prefill-decode, la decodifica speculativa, la schedulazione continua delle richieste (continuous batching) e la paginazione dell'attenzione (paged attention): un insieme di tecniche di ottimizzazione anziché un meccanismo isolato.

#Regola la concorrenza e la memoria

Tre parametri di avvio regolano il modo in cui SGLang gestisce più utenti in parallelo. --mem-fraction-static fissa la quota di memoria GPU riservata ai pesi del modello e alla cache KV; la documentazione consiglia di ridurla in caso di errore per esaurimento della memoria, altrimenti viene calcolata automaticamente in base alla memoria GPU disponibile.

Senza un limite esplicito per --max-running-requests, SGLang accetta tutte le richieste consentite dalla memoria della cache KV, il che può peggiorare la latenza per richiesta sotto un carico elevato anziché rifiutare cortesemente le nuove connessioni. Impostare un limite esplicito, coerente con la VRAM disponibile, è la prima regolazione da effettuare prima di aprire il server a più utenti reali.

#Quando scegliere SGLang piuttosto che vLLM o Ollama

I tre strumenti rispondono a esigenze diverse. Ollama è pensato per l'uso personale da parte di un solo utente e richiede pochissimo sforzo per iniziare a usarlo; SGLang e vLLM sono pensati per servire più utenti su GPU per server, con filosofie simili (cache dei prefissi, batching continuo) ma storie ed ecosistemi distinti.

Un solo utente, postazione personale

Ollama o llama.cpp restano più semplici da installare e da eseguire su CPU o GPU consumer, senza dover configurare un servizio di rete.

Più utenti, sistema già costruito attorno a vLLM

Restare su vLLM evita una migrazione; la nostra guida dedicata ne descrive il deployment in produzione.

Più utenti, priorità al throughput con prefissi condivisi

SGLang, con RadixAttention, è il candidato naturale, a patto di disporre di una GPU CUDA compatibile.

Compatibilità con i client Ollama desiderata senza installare Ollama

SGLang offre un'API compatibile con la CLI e la libreria Python Ollama, il che permette di riutilizzare script esistenti senza avviare il server Ollama stesso.

Per una panoramica più ampia delle architetture di inferenza (llama.cpp, vLLM, Exllama), il confronto dei backend del sito illustra in dettaglio i compromessi anche al di fuori del solo caso SGLang.

#Ciò che l'hardware impone

La guida rapida di SGLang è esplicita: una GPU NVIDIA con supporto CUDA sm80 o superiore (A10, A100, L4, L40S, H100) è un prerequisito per il percorso di installazione standard su Linux, la piattaforma consigliata. Il progetto annuncia inoltre un supporto hardware più ampio — GPU AMD (MI355, MI300), CPU Intel Xeon, TPU Google, NPU Ascend — attraverso percorsi di installazione dedicati e distinti dal percorso principale per le GPU NVIDIA.

#Quanto costa la memoria per richiesta

«Servire più utenti» si traduce molto concretamente in un consumo di VRAM che aumenta con il numero di richieste attive, non solo con la dimensione del modello. La cache KV gestita da --mem-fraction-static e --max-total-tokens memorizza, per ogni token già generato di una richiesta, due vettori (chiave e valore) per ogni strato di attenzione. La formula generale è: byte per token = 2 × numero di strati × numero di teste di attenzione KV × dimensione di una testa × byte per valore (2 in FP16/BF16, 1 in FP8).

Calcolo illustrativo per un'architettura simile a Llama-3.1-8B-Instruct (32 strati, 8 teste KV con attenzione raggruppata, dimensione delle teste pari a 128): in FP16, si ottiene 2 × 32 × 8 × 128 × 2 = 131.072 byte per token, cioè circa 128 KB per token. Per una richiesta con 8.192 token di contesto (prompt e risposta sommati), la cache KV di questa sola richiesta occupa quindi circa 1 GB di VRAM, prima ancora di contare i pesi del modello. Su una GPU da 24 GB con circa 16 GB riservati ai pesi in Q4 e alla memoria di base del runtime, il margine restante lascia spazio soltanto a poche richieste attive contemporaneamente con questa lunghezza di contesto. Questo spiega perché un limite esplicito su --max-running-requests evita un degrado delle prestazioni anziché un rifiuto ordinato delle nuove connessioni.

#Sicurezza e osservabilità

Per impostazione predefinita, l'API SGLang avviata con sglang.launch_server non richiede alcuna autenticazione: chiunque possa raggiungere la porta 30000 può inviare richieste. L'opzione --api-key imposta una chiave richiesta dal server, anche sul suo endpoint compatibile con OpenAI; senza questa opzione, esporre il server al di fuori di localhost o di una rete interna fidata equivale a lasciare libero accesso all'inferenza e quindi ai relativi costi GPU.

Per il monitoraggio in produzione, l'opzione --enable-metrics (disattivata per impostazione predefinita) pubblica metriche in formato Prometheus su un endpoint /metrics: frequenza delle richieste, latenza di inferenza, velocità di generazione dei token ed efficienza della cache vengono esposte per una raccolta periodica tramite scraping, anziché dedurre lo stato del server dai soli log.

• Principi di sicurezza di un server di inferenza esposto
• Fonte: elenco degli argomenti del server (--api-key, --enable-metrics)

#Risoluzione dei problemi: sintomi, causa, soluzione

#Limiti e aspetti a cui prestare attenzione

Il dato « fino a 5 volte più veloce » che accompagna ancora la presentazione di RadixAttention risale all'annuncio iniziale del progetto nel gennaio 2024: illustra il contributo del meccanismo sul banco di prova dell'epoca, non un miglioramento garantito in un deployment recente con modelli e GPU diversi. Il dimensionamento effettivo dipende dal grado di condivisione dei prefissi tra le richieste, dal modello scelto e dalla GPU utilizzata: va valutato misurando il proprio traffico, anziché dedotto dall'annuncio originale.

Il passaggio obbligatorio a CUDA 13 (la versione 0.5.19 è l'ultima a offrire un'opzione per CUDA 12) richiede di verificare il driver GPU e la versione CUDA installata prima di qualsiasi aggiornamento a una versione recente, pena il fallimento dell'installazione su un server rimasto a CUDA 12.

Anche il ritmo di pubblicazione del progetto va monitorato per un deployment in produzione: SGLang rilascia versioni minori ogni due o tre settimane circa (v0.5.20 il 18 settembre 2026, v0.5.19 il 5 settembre, v0.5.18 il 22 agosto), il che impone di fissare una versione precisa nelle immagini Docker anziché seguire il tag latest per un servizio in produzione, per evitare un cambiamento di comportamento imprevisto durante un nuovo deployment.

• Mettere vLLM in produzione
• vLLM: cos'è, per chi e quando usarlo?
• llama.cpp vs vLLM vs Exllama
• Fonte: documentazione ufficiale SGLang
• Fonte: README ufficiale del repository SGLang
• Fonte: riferimento degli argomenti del server