Démarrage rapide de SGLang : Installation, configuration et déploiement de LLM via l’API OpenAI

Faites fonctionner rapidement les modèles ouverts avec SGLang.

Sommaire

SGLang est un framework de service haute performance pour les grands modèles de langage et les modèles multimodaux, conçu pour fournir une inférence à faible latence et à haut débit sur tout, d’une seule GPU à des clusters distribués.

Pour une comparaison plus large des options d’hébergement de LLM auto-hébergés et cloud — incluant Ollama, vLLM, llama-swap, LocalAI et les fournisseurs cloud gérés — consultez le guide d’hébergement LLM pour 2026.

Si vous avez déjà des applications connectées à la forme de l’API OpenAI, SGLang est particulièrement attrayant car il peut exposer des points de fin compatibles OpenAI pour les complétions de chat et de complétion, vous aidant ainsi à migrer des API hébergées vers des modèles auto-hébergés avec des modifications minimales côté client. Lorsque vous devez acheminer des requêtes vers plusieurs backends (llama.cpp, vLLM, SGLang, etc.) avec un remplacement à chaud et un déchargement basé sur le TTL, llama-swap fournit une couche de proxy transparente qui maintient une URL unique /v1 stable tout en échangeant les amonts à la demande.

sglang infographic

Ce démarrage rapide vous guide à travers l’installation (méthodes multiples), des modèles de configuration pratiques, et un flux de travail propre « installer → servir → vérifier → intégrer → ajuster », avec des exemples fonctionnels pour le service HTTP et l’inférence par lot hors ligne.

Si vous avez besoin d’une prise en charge multimodale (texte, embeddings, images, audio) avec une interface Web intégrée et une compatibilité maximale « plug-and-play » avec l’API OpenAI, LocalAI offre un ensemble de fonctionnalités plus large avec un support de plus de formats de modèles.

Qu’est-ce que SGLang pour le service à haut débit de LLM et de modèles multimodaux

À sa base, SGLang est conçu pour une inférence efficace et un service évolutif. La pile « runtime rapide » inclut RadixAttention pour la mise en cache de préfixes, un planificateur CPU sans surcoût, le décodage spéculatif, le regroupement continu (continuous batching), l’attention paginée, plusieurs stratégies de parallélisme (tensor, pipeline, expert, données), des sorties structurées, un préremplissage par morceaux (chunked prefill) et plusieurs options de quantification (par exemple FP4, FP8, INT4, AWQ, GPTQ).

Il vise un déploiement multiplateforme : GPU NVIDIA, GPU AMD, CPU Intel Xeon, TPU Google, NPU Ascend, et plus encore.

PyPI nécessite Python >= 3.10. Au 20 mars 2026, la ligne publiée comprenait la 0.5.9 (sortie le 23 février 2026) — fixez ou vérifiez les versions actuelles lors de l’installation.

Comment installer SGLang sur des hôtes Linux GPU avec uv pip, des compilations sources ou Docker

Les options d’installation incluent uv ou pip, des compilations sources, des images Docker, des manifests Kubernetes, Docker Compose, SkyPilot et AWS SageMaker. La plupart des tutoriels supposent des configurations GPU NVIDIA courantes ; d’autres accélérateurs ont leurs propres notes de configuration ailleurs.

Installer SGLang rapidement avec uv ou pip sur Python 3.10+

Pour une installation locale simple, uv est généralement la voie la plus rapide :

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

Notes CUDA 13

Pour CUDA 13, Docker évite les incompatibilités PyTorch/CUDA côté hôte. Sans Docker : installez une build PyTorch CUDA 13, puis sglang, puis la roue sglang-kernel correspondante depuis les versions de roues publiées (la version doit correspondre à la pile).

# 1) Installer PyTorch avec support CUDA 13 (remplacez X.Y.Z si nécessaire)
uv pip install torch==X.Y.Z torchvision torchaudio --index-url https://download.pytorch.org/whl/cu130

# 2) Installer SGLang
uv pip install sglang

# 3) Installer la roue sglang-kernel CUDA 13 correspondante (remplacez 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"

Installer et exécuter SGLang avec des images Docker Hub

Pour des déploiements conteneurisés — ou pour contourner l’appariement CUDA/PyTorch de l’hôte — utilisez les images Docker Hub publiées. Une commande docker run typique monte le cache Hugging Face et passe HF_TOKEN lors du téléchargement de modèles gated.

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

Pour des images de style production, latest-runtime supprime les outils de build et les dépendances de développement, de sorte que l’image reste beaucoup plus petite que la variante latest par défaut.

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

Installer depuis le source et autres méthodes de déploiement

Pour développer avec SGLang ou appliquer des correctifs locaux, clonez une branche de release et installez le package Python en mode editable :

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

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

Pour l’orchestration, le dépôt inclut des manifests Kubernetes (mono et multi-nœuds) et une disposition Docker Compose minimale — des points de départ raisonnables avant un câblage personnalisé.

Comment configurer les arguments du serveur SGLang avec des fichiers de configuration YAML et des variables d’environnement

La configuration de SGLang est pilotée par des arguments de serveur et des variables d’environnement. Les drapeaux couvrent la sélection de modèle, le parallélisme, la mémoire et les paramètres d’optimisation ; l’ensemble complet est listé avec python3 -m sglang.launch_server --help.

Les variables d’environnement utilisent deux préfixes : SGL_ et SGLANG_ (de nombreux drapeaux acceptent la forme CLI ou env — launch_server --help montre le mappage).

Certaines variables d’environnement couramment pertinentes incluent le contrôle de l’hôte et du port tels que SGLANG_HOST_IP et SGLANG_PORT.

Utiliser un fichier de configuration YAML pour des lancements de serveur SGLang reproductibles

Pour des déploiements reproductibles et des lignes de commande plus courtes, passez un fichier YAML avec --config. Les arguments CLI écrasent les valeurs du fichier lorsque les deux définissent la même option.

# Créer 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

# Lancer le serveur avec le fichier de configuration
python -m sglang.launch_server --config config.yaml

Quelques essentiels de configuration et de réglage à garder à l’esprit :

Le --model-path de SGLang peut pointer vers un dossier local ou un ID de repo Hugging Face, ce qui facilite le passage entre des poids locaux et des modèles hébergés sur le Hub sans changer votre code de service.

Pour le multi-GPU, activez le parallélisme tensor avec --tp. Si le démarrage échoue avec « peer access is not supported between these two devices », ajoutez --enable-p2p-check.

Si le service rencontre OOM (Out Of Memory), réduisez la pression du cache KV avec un --mem-fraction-static plus petit (la valeur par défaut est 0.9).

Si les prompts longs OOM pendant le préremplissage (prefill), baissez --chunked-prefill-size.

Comment exécuter un serveur SGLang compatible OpenAI et l’appeler depuis le client Python OpenAI

Un flux de travail pratique « chemin heureux » ressemble à ceci :

  1. Installer SGLang (uv/pip ou Docker).
  2. Démarrer le serveur avec votre modèle et port choisis.
  3. Vérifier le service de base via les points de fin compatibles OpenAI.
  4. Intégrer votre application en pointant le base_url du SDK OpenAI vers le serveur local.
  5. Ajuster le débit et la mémoire avec des arguments serveur une fois que vous avez du trafic réel.

Envoyer une requête de complétion de chat locale à SGLang en utilisant le SDK OpenAI

Pour une utilisation compatible OpenAI, deux détails comptent :

Le serveur implémente la surface HTTP OpenAI et, lorsque le tokenizer en fournit un, applique le modèle de chat Hugging Face automatiquement. Remplacez avec --chat-template au lancement si nécessaire.

Pointez un client OpenAI vers le préfixe /v1 du serveur (base_url → http://<host>:<port>/v1), puis appelez client.chat.completions.create(...) comme d’habitude.

Démarrage du serveur avec l’un des deux points d’entrée : python -m sglang.launch_server fonctionne toujours, mais sglang serve est la CLI préférée.

# Point d'entrée CLI recommandé
sglang serve --model-path qwen/qwen2.5-0.5b-instruct --host 0.0.0.0 --port 30000

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

Ensuite, appelez-le avec le 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": "List 3 countries and their capitals."}],
    temperature=0,
    max_tokens=64,
)

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

Comment exécuter une inférence par lot avec l’API Moteur Hors Ligne SGLang et les points de fin natifs

SGLang prend en charge plusieurs « surfaces API » selon ce que vous construisez :

Le point de fin /generate est l’API runtime de bas niveau. Préférez les routes compatibles OpenAI /v1/... lorsque vous voulez que les modèles de chat et l’écosystème client habituel soient gérés pour vous.

Sans aucun serveur HTTP, le Moteur Hors Ligne (Offline Engine) exécute l’inférence dans le processus : adapté aux jobs par lot et aux services personnalisés. Il prend en charge les combinaisons synchrone/asynchrone et streaming/non-streaming — choisissez le mode qui correspond au modèle d’appel.

Exemple utilisant le point de fin natif /generate

Modèle minimal : lancez un serveur, puis POST /generate avec temperature et max_new_tokens (et tout autre champ d’échantillonnage dont vous avez besoin).

import requests

response = requests.post(
    "http://localhost:30000/generate",
    json={
        "text": "The capital of France is",
        "sampling_params": {
            "temperature": 0,
            "max_new_tokens": 32,
        },
    },
)

print(response.json())

temperature = 0 est un échantillonnage glouton ; des valeurs plus élevées augmentent la diversité.

Exemple utilisant l’API Moteur Hors Ligne pour l’inférence par lot dans le processus

Flux typique : construire sgl.Engine(model_path=...), exécuter llm.generate(...) sur un lot de prompts, puis llm.shutdown() pour libérer la GPU et d’autres ressources.

import sglang as sgl

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

prompts = [
    "Write a concise self-introduction.",
    "Explain what prefix caching is in one paragraph.",
]

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()