Szybki start z SGLang: instalacja, konfiguracja i uruchamianie modeli LLM przez API OpenAI

SGLang – szybkie uruchamianie otwartych modeli.

Page content

SGLang to wysokowydajny framework do obsługi dużych modeli językowych i multimodalnych, zaprojektowany do zapewnienia niskiego opóźnienia i wysokiej przepustowości podczas wnioskowania, niezależnie od tego, czy działa na pojedynczej karcie GPU, czy w rozproszonych klastrach.

Aby uzyskać szersze porównanie opcji hostowania LLM na własnym serwerze i w chmurze – w tym Ollama, vLLM, llama-swap, LocalAI oraz dostawców zarządzanej chmury – zobacz poradnik dotyczący hostowania LLM na rok 2026.

Jeśli Twoje aplikacje są już skonfigurowane z interfejsem API OpenAI, SGLang jest szczególnie atrakcyjny, ponieważ może udostępniać punkty końcowe kompatybilne z OpenAI dla czatów i wnioskowań, co pomaga w migracji z hostowanych API do modeli hostowanych lokalnie przy minimalnych zmianach po stronie klienta. Kiedy potrzebujesz przekierowywać żądania do wielu backendów (llama.cpp, vLLM, SGLang itp.) z możliwością wymiany na gorąco i usuwania modeli na podstawie TTL, llama-swap zapewnia przezroczystą warstwę proxy, która utrzymuje stabilny URL /v1, jednocześnie wymieniając upstreamy zgodnie z potrzebami.

sglang infographic

Ten przewodnik szybkiego startu opisuje instalację (wiele metod), praktyczne wzorce konfiguracji oraz czysty przepływ pracy „zainstaluj → uruchom → zweryfikuj → zintegruj → dostosuj", z działającymi przykładami zarówno dla serwowania HTTP, jak i offline’owej inferencji wsadowej.

Jeśli potrzebujesz wsparcia multimodalnego (tekst, wektory, obrazy, audio) z wbudowanym interfejsem WWW i maksymalną kompatybilnością drop-in z API OpenAI, LocalAI oferuje szerszy zestaw funkcji z większym wsparciem dla formatów modeli.

Do czego służy SGLang w wysokiej wydajności dla modeli LLM i multimodalnych

W swojej istocie SGLang został zaprojektowany dla efektywnej inferencji i skalowalnego serwowania. Stos „szybkiego czasu wykonania" obejmuje RadixAttention do buforowania prefiksów, harmonogramist CPU o zerowym narzucie, spekulacyjne dekodowanie, ciągłe grupowanie (continuous batching), paginated attention, wiele strategii równoległości (równoległość tensorowa, rurociągowa, ekspercka, danych), strukturalne wyjścia, grupowane prefille oraz wiele opcji kwantyzacji (na przykład FP4, FP8, INT4, AWQ, GPTQ).

Jego celem jest szerokie wdrożenie na różnych platformach: karty NVIDIA GPU, karty AMD GPU, procesory Intel Xeon, procesory Google TPU, jednostki Ascend NPU i inne.

PyPI wymaga Python >= 3.10. Stanem na 23 marca 2026 roku wersja publikowana to 0.5.9 (wydana 23 lutego 2026) – podczas instalacji ustal wersję lub sprawdź aktualne.

Jak zainstalować SGLang na hostach z GPU w systemie Linux za pomocą uv pip, kompilacji ze źródeł lub Docker

Opcje instalacji obejmują uv lub pip, kompilację ze źródeł, obrazy Docker, manifesty Kubernetes, Docker Compose, SkyPilot oraz AWS SageMaker. Większość przewodników zakłada typowe konfiguracje GPU NVIDIA; inne akceleratory mają swoje własne uwagi dotyczące konfiguracji.

Szybka instalacja SGLang za pomocą uv lub pip na Python 3.10+

W przypadku prostej instalacji lokalnej, uv jest zazwyczaj najszybszą drogą:

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

Uwagi dotyczące CUDA 13

Dla CUDA 13, Docker uniknie rozbieżności PyTorch/CUDA po stronie hosta. Bez Docker: zainstaluj build PyTorch z CUDA 13, następnie sglang, a potem pasujący koło sglang-kernel z opublikowanych wydań (wersja musi pasować do stosu).

# 1) Zainstaluj PyTorch z obsługą CUDA 13 (zastąp X.Y.Z jak potrzebne)
uv pip install torch==X.Y.Z torchvision torchaudio --index-url https://download.pytorch.org/whl/cu130

# 2) Zainstaluj SGLang
uv pip install sglang

# 3) Zainstaluj pasujące koło sglang-kernel dla CUDA 13 (zastąp 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"

Instalacja i uruchamianie SGLang z obrazami Docker Hub

W przypadku wdrożeń kontenerowych – lub aby ominąć parowanie CUDA/PyTorch na hostcie – użyj opublikowanych obrazów Docker Hub. Typowe docker run montuje cache Hugging Face i przekazuje HF_TOKEN podczas pobierania modeli z ograniczonym dostępem.

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

Dla obrazów produkcyjnych, latest-runtime usuwa narzędzia budowania i zależności deweloperskie, dzięki czemu obraz pozostaje znacznie mniejszy niż domyślna wersja latest.

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

Instalacja ze źródeł i inne metody wdrożenia

Aby pracować nad SGLang lub stosować lokalne poprawki, sklonuj gałąź wydania i zainstaluj pakiet Python w trybie edytowalnym:

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

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

Dla orkiestracji repo zawiera manifesty Kubernetes (pojedyncze- i wielowęzłowe) oraz minimalny układ Docker Compose – rozsądne punkty wyjścia przed niestandardową konfiguracją.

Jak konfigurować argumenty serwera SGLang z plikami konfiguracyjnymi YAML i zmiennymi środowiskowymi

Konfiguracja SGLang jest sterowana argumentami serwera i zmiennymi środowiskowymi. Flagi obejmują wybór modelu, równoległość, pamięć i parametry optymalizacji; pełny zestaw jest wymieniony za pomocą python3 -m sglang.launch_server --help.

Zmienne środowiskowe używają dwóch prefiksów: SGL_ i SGLANG_ (wiele flag akceptuje formę CLI lub zmienną środowiskową – launch_server --help pokazuje mapowanie).

Do często istotnych zmiennych środowiskowych należą sterowanie hostem i portem, takie jak SGLANG_HOST_IP i SGLANG_PORT.

Użyj pliku konfiguracyjnego YAML dla powtarzalnych uruchomień serwera SGLang

Dla powtarzalnych wdrożeń i krótszych linii poleceń, podaj plik YAML z --config. Argumenty CLI nadpisują wartości z pliku, gdy oba ustawiają tę samą opcję.

# Stwórz 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

# Uruchom serwer z plikiem konfiguracyjnym
python -m sglang.launch_server --config config.yaml

Kilka podstawowych kwestii konfiguracji i tuningu, o których należy pamiętać:

--model-path w SGLang może wskazywać na lokalny folder lub ID repozytorium Hugging Face, co ułatwia przełączanie między wagami lokalnymi a modelami hostowanymi na Hubie bez zmiany kodu serwera.

Dla wielu GPU włącz równoległość tensorową z --tp. Jeśli uruchomienie kończy się błędem „peer access is not supported between these two devices”, dodaj --enable-p2p-check.

Jeśli serwowanie napotyka błąd OOM, zmniejsz ciśnienie cache KV z mniejszym --mem-fraction-static (domyślnie 0.9).

Jeśli długie prompty powodują OOM podczas prefilla, zmniejsz --chunked-prefill-size.

Jak uruchomić serwer SGLang kompatybilny z OpenAI i wywoływać go z klienta Python OpenAI

Praktyczny, optymalny przepływ pracy wygląda następująco:

  1. Zainstaluj SGLang (uv/pip lub Docker).
  2. Uruchom serwer z wybranym modelem i portem.
  3. Zweryfikuj podstawowe serwowanie poprzez punkty końcowe kompatybilne z OpenAI.
  4. Zintegruj swoją aplikację, wskazując base_url SDK OpenAI na lokalny serwer.
  5. Dostosuj przepustowość i pamięć z argumentami serwera, gdy masz już ruch produkcyjny.

Wyślij lokalne żądanie czatu do SGLang używając SDK OpenAI

W przypadku użycia kompatybilnego z OpenAI, dwie kwestie mają znaczenie:

Serwer implementuje powierzchnię HTTP OpenAI i, gdy tokenizer to zapewnia, automatycznie stosuje szablon czatu Hugging Face. Nadpisz to z --chat-template przy uruchamieniu, jeśli potrzebne.

Wskaż klienta OpenAI na prefiks /v1 serwera (base_url → http://<host>:<port>/v1), a następnie wywołaj client.chat.completions.create(...) jak zwykle.

Uruchom serwer z dowolnego punktu wejścia: python -m sglang.launch_server nadal działa, ale sglang serve jest preferowanym CLI.

# Rekomendowany punkt wejścia CLI
sglang serve --model-path qwen/qwen2.5-0.5b-instruct --host 0.0.0.0 --port 30000

# Nadal obsługiwane
python3 -m sglang.launch_server --model-path qwen/qwen2.5-0.5b-instruct --host 0.0.0.0 --port 30000

Następnie wywołaj go z klienta 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": "Wymień 3 państwa i ich stolice."}],
    temperature=0,
    max_tokens=64,
)

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

Jak uruchomić wnioskowanie wsadowe z API Offline Engine SGLang i natywnymi punktami końcowymi

SGLang obsługuje wiele „powierzchni API" w zależności od tego, co budujesz:

Punkt końcowy /generate jest niskopoziomowym API czasu wykonania. Preferuj trasy /v1/... kompatybilne z OpenAI, gdy chcesz, aby szablony czatu i zwykły ekosystem klientów były obsłużone za Ciebie.

Bez żadnego serwera HTTP, Offline Engine uruchamia wnioskowanie w procesie: odpowiedni do zadań wsadowych i niestandardowych usług. Obsługuje kombinacje sync/async i streaming/non-streaming – wybierz tryb pasujący do wzorca wywołań.

Przykład używania natywnego punktu końcowego /generate

Minimalny wzorzec: uruchom serwer, następnie wyślij POST /generate z temperature i max_new_tokens (oraz innymi polami próbkowania, jakich potrzebujesz).

import requests

response = requests.post(
    "http://localhost:30000/generate",
    json={
        "text": "Stolice Francji to",
        "sampling_params": {
            "temperature": 0,
            "max_new_tokens": 32,
        },
    },
)

print(response.json())

temperature = 0 to próbkowanie zachłanne; wyższe wartości zwiększają różnorodność.

Przykład używania API Offline Engine do wnioskowania wsadowego w procesie

Typowy przepływ: zbuduj sgl.Engine(model_path=...), uruchom llm.generate(...) nad wsadem promptów, a następnie llm.shutdown() do zwolnienia GPU i innych zasobów.

import sglang as sgl

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

prompts = [
    "Napisz zwięzłą samookreślenie.",
    "Wyjaśnij, czym jest buforowanie prefiksów, w jednym akapicie.",
]

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