SGLang QuickStart: installeer, configureer en serveer LLM's via de OpenAI API

Serveer open modellen snel met SGLang.

Inhoud

SGLang is een high-performance framework voor het uitvoeren van inference bij grote taalmodellen en multimodale modellen, ontworpen om lage latentie en hoge doorvoer te leveren, variërend van een enkele GPU tot gedistribueerde clusters.

Voor een bredere vergelijking van opties voor self-hosted en cloud LLM-hosting — waaronder Ollama, vLLM, llama-swap, LocalAI en beheerde cloudproviders — zie de LLM-hostinggids voor 2026.

Als je al applicaties hebt die zijn gekoppeld aan de OpenAI-API-indeling, is SGLang bijzonder aantrekkelijk omdat het OpenAI-compatibele endpoints kan blootstellen voor chat-completies en completies. Dit helpt bij het migreren van gehoste APIs naar zelfgehoste modellen met minimale wijzigingen aan de clientkant. Wanneer je requests moet routeren over meerdere backends (llama.cpp, vLLM, SGLang, enz.) met hot-swap en TTL-gebaseerd unloaden, biedt llama-swap een transparante proxy-laag die een stabiele /v1 URL behoudt terwijl upstreams op aanvraag worden gewisseld.

sglang infographic

Deze QuickStart loopt installatie (met meerdere methoden), praktische configuratiepatronen en een schoon “install → serveer → verifieer → integreer → tuneer” workflow door, met werkende voorbeelden voor zowel HTTP-servings als offline batch-inference.

Als je multimodale ondersteuning nodig hebt (tekst, embeddings, afbeeldingen, audio) met een ingebouwde Web UI en maximale drop-in compatibiliteit met de OpenAI-API, biedt LocalAI een bredere set functies met ondersteuning voor meer modelformaten.

Waarvoor is SGLang voor high-throughput LLM- en multimodale model-serving

In de kern is SGLang ontworpen voor efficiënte inference en schaalbare serving. De “fast runtime”-stack omvat RadixAttention voor prefix-caching, een CPU-scheduler zonder overhead, speculatief decoderen, continue batching, paged attention, meerdere parallelisme-strategieën (tensor, pipeline, expert, data parallelisme), gestructureerde outputs, chunked prefill en meerdere kwantisatie-opties (bijvoorbeeld FP4, FP8, INT4, AWQ, GPTQ).

Het is gericht op breed-platform deployment: NVIDIA GPUs, AMD GPUs, Intel Xeon CPUs, Google TPUs, Ascend NPUs en meer.

PyPI vereist Python >= 3.10. Per 20 maart 2026 bevatte de gepubliceerde lijn 0.5.9 (uitgegeven 23 februari 2026) — pin of controleer de huidige versies bij installatie.

Hoe SGLang installeren op Linux GPU-hosts met uv pip, source builds of Docker

Installatie-opties omvatten uv of pip, source builds, Docker-images, Kubernetes-manifests, Docker Compose, SkyPilot en AWS SageMaker. De meeste walkthroughs gaan uit van gangbare NVIDIA GPU-opstellingen; andere accelerators hebben hun eigen setup-notities elders.

Installeer SGLang snel met uv of pip op Python 3.10+

Voor een eenvoudige lokale installatie is uv meestal de snelste weg:

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

CUDA 13-opmerkingen

Voor CUDA 13 voorkomt Docker mismatch tussen host-side PyTorch/CUDA. Zonder Docker: installeer een CUDA 13 PyTorch-build, daarna sglang, en vervolgens het overeenkomende sglang-kernel-wheel uit de gepubliceerde wheel-releases (de versie moet overeenkomen met de stack).

# 1) Installeer PyTorch met CUDA 13-ondersteuning (vervang X.Y.Z indien nodig)
uv pip install torch==X.Y.Z torchvision torchaudio --index-url https://download.pytorch.org/whl/cu130

# 2) Installeer SGLang
uv pip install sglang

# 3) Installeer het overeenkomende CUDA 13 sglang-kernel wheel (vervang 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"

Installeer en start SGLang met Docker Hub-images

Voor containerisatie-deployments — of om host CUDA/PyTorch-koppeling te vermijden — gebruik de gepubliceerde Docker Hub-images. Een typische docker run mount het Hugging Face-cache en geeft HF_TOKEN door bij het ophalen van gated modellen.

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

Voor productie-stijl images, latest-runtime verwijdert build-tools en dev-dependencies, zodat het image veel kleiner blijft dan de standaard latest-variant.

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

Installeer vanuit source en andere deployment-methoden

Om tegen SGLang te ontwikkelen of lokale patches toe te passen, kloon een release-tak en installeer het Python-pakket in bewerkbare modus:

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

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

Voor orchestratie bevat de repo Kubernetes-manifests (single- en multi-node) en een minimale Docker Compose-opzet — redelijke startpunten voordat er aangepaste bedrading plaatsvindt.

Hoe SGLang server-argumenten configureren met YAML-configuratiebestanden en omgevingsvariabelen

SGLang-configuratie wordt gestuurd door server-argumenten en omgevingsvariabelen. Vlaggen dekken modelselectie, parallelisme, geheugen en optimalisatie-knoppen; de volledige set staat genoteerd met python3 -m sglang.launch_server --help.

Omgevingsvariabelen gebruiken twee prefixen: SGL_ en SGLANG_ (veel vlaggen accepteren zowel CLI- als env-vorm — launch_server --help toont de mapping).

Sommige veelvoorkomende relevante omgevingsvariabelen omvatten host- en poortcontroles zoals SGLANG_HOST_IP en SGLANG_PORT.

Gebruik een YAML-configuratiebestand voor reproduceerbare SGLang-serverstarts

Voor herhaalbare deployments en kortere command lines, geef een YAML-bestand door met --config. CLI-argumenten overschrijven waarden uit het bestand wanneer beide dezelfde optie instellen.

# Creë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

# Start server met configuratiebestand
python -m sglang.launch_server --config config.yaml

Een paar configuratie- en tuningessentials om in gedachten te houden:

SGLang’s --model-path kan naar een lokale map of een Hugging Face-repo ID wijzen, wat het makkelijk maakt om tussen lokale gewichten en Hub-gehoste modellen te wisselen zonder je serving-code te wijzigen.

Voor multi-GPU, activeer tensor-parallelisme met --tp. Als het opstarten faalt met “peer access is not supported between these two devices”, voeg --enable-p2p-check toe.

Als serving op OOM stuit, verlaag de KV-cache-druk met een kleinere --mem-fraction-static (standaard is 0.9).

Als lange prompts OOM geven tijdens prefill, verlaag --chunked-prefill-size.

Hoe een OpenAI-compatibele SGLang-server draaien en aanroepen vanuit de OpenAI Python-client

Een praktische “happy path”-workflow ziet er als volgt uit:

  1. Installeer SGLang (uv/pip of Docker).
  2. Start de server met je gekozen model en poort.
  3. Verifieer basis-serving via OpenAI-compatibele endpoints.
  4. Integreer je applicatie door de OpenAI SDK base_url naar de lokale server te wijzen.
  5. Tuneer doorvoer en geheugen met server-argumenten zodra je echt verkeer hebt.

Stuur een lokale chat-completie-aanvraag naar SGLang met behulp van de OpenAI SDK

Voor OpenAI-compatibel gebruik tellen twee details:

De server implementeert de OpenAI HTTP-opvlak en, als de tokenizer er een biedt, past de Hugging Face chat-template automatisch toe. Overschrijf met --chat-template bij het opstarten indien nodig.

Wijs een OpenAI-client naar het /v1-prefix van de server (base_url → http://<host>:<port>/v1), en roep client.chat.completions.create(...) aan zoals gewoonlijk.

Start de server met een van beide entrypoints: python -m sglang.launch_server werkt nog steeds, maar sglang serve is de voorkeurs-CLI.

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

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

Roep het vervolgens aan met de OpenAI Python-client:

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)

Hoe batch-inference draaien met de SGLang Offline Engine API en native endpoints

SGLang ondersteunt meerdere “API-opvlakken” afhankelijk van wat je bouwt:

Het /generate-endpoint is de low-level runtime-API. Geef de voorkeur aan /v1/... OpenAI-compatibele routes als je chat-templates en het gebruikelijke client-ecosysteem voor je wilt laten regelen.

Zonder enige HTTP-server draait de Offline Engine inference in-process: geschikt voor batch-jobs en custom services. Het ondersteunt sync/async en streaming/non-streaming combinaties — kies de modus die past bij het aanroep-patroon.

Voorbeeld met behulp van het native /generate-endpoint

Minimale patroon: start een server, en POST dan /generate met temperature en max_new_tokens (en andere sampling-velden die je nodig hebt).

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 is greedy sampling; hogere waarden verhogen de diversiteit.

Voorbeeld met behulp van de Offline Engine API voor in-process batch-inference

Typische flow: construeer sgl.Engine(model_path=...), voer llm.generate(...) uit over een batch van prompts, en llm.shutdown() om GPU en andere resources vrij te geven.

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