SGLang запускается одной командой sglang serve <модель> в Docker-контейнере lmsysorg/sglang или в Python-окружении, после чего отдаёт OpenAI-совместимый API на порту 30000. Для работы нужны Linux, видеокарта NVIDIA и драйвер с поддержкой CUDA 13: начиная с версии 0.5.20 образы и колёса под CUDA 12 не публикуются. Ниже — установка, первый запуск, проверка API, основные параметры памяти и планирования, метрики и защита.
Инструкцию подготовила AI студия Владимира Ломтева 16 ноября 2026 года по краткому руководству SGLang, руководству по установке, справочнику аргументов сервера и заметкам к выпуску 0.5.23. Команды проверены на синтаксис, но мы не запускали их на конкретном GPU. Значения по умолчанию проверяйте по --help своей версии.
Содержание
- Когда выбирать SGLang
- Требования
- Установка и запуск через Docker
- Установка в Python-окружение
- Проверка API
- Основные параметры сервера
- Несколько GPU
- Метрики
- Безопасность и обновления
- Частые ошибки
- Частые вопросы
Когда выбирать SGLang
SGLang — сервер инференса для GPU с сильной стороной в повторном использовании общего префикса: его RadixAttention хранит кэш в виде дерева и переиспользует его между запросами с одинаковым началом. Это полезно для агентов, многоходовых диалогов, RAG с общими инструкциями и структурированного вывода. vLLM решает похожие задачи и шире распространён. Выбор между ними обычно делают тестом на своей нагрузке; ориентиры есть в статье «vLLM, Ollama, llama.cpp или SGLang».
Требования
| Компонент | Что нужно |
|---|---|
| ОС | Linux |
| GPU | Поддерживаемая видеокарта NVIDIA (есть отдельные инструкции для AMD, Intel, TPU и других платформ) |
| Драйвер | Совместимый с CUDA 13 |
| Docker-путь | Docker Engine и NVIDIA Container Toolkit |
| Python-путь | Python 3.11 или новее |
В руководстве по установке сказано, что образы SGLang поставляются с окружением CUDA 13, а последняя метка под CUDA 12 — lmsysorg/sglang:v0.5.19-cu129. Переход связан с обновлением на PyTorch 2.14, у которого нет сборок под CUDA 12.9. Если драйвер на хосте старый, сначала обновите его — иначе свежий образ не запустится.
Установка и запуск через Docker
Docker — самый простой путь: в образе уже есть Python, SGLang и зависимости. Закрепите версию образа вместо latest, чтобы обновления происходили осознанно:
docker pull lmsysorg/sglang:v0.5.23
docker run --rm --gpus all --ipc=host --shm-size 32g \
-p 127.0.0.1:30000:30000 \
-v /srv/hf-cache:/root/.cache/huggingface \
-e HF_TOKEN \
lmsysorg/sglang:v0.5.23 \
sglang serve Qwen/Qwen3-8B --host 0.0.0.0 --port 30000 \
--api-key "$SGLANG_API_KEY"
Что здесь важно:
--ipc=hostи--shm-size 32gдают процессам движка разделяемую память, без неё возможны сбои;- каталог
/srv/hf-cacheсохраняет скачанные веса между перезапусками контейнера; -e HF_TOKENнужен только для закрытых моделей на Hugging Face;- публикация порта на
127.0.0.1оставляет сервер доступным только с хоста, а внешний доступ лучше давать через обратный прокси.
Сервер готов, когда в логе появится строка The server is fired up and ready to roll!.
Установка в Python-окружение
Если Docker не подходит, руководство предлагает установку через uv:
uv venv --python 3.12
source .venv/bin/activate
uv pip install --prerelease=allow sglang
sglang serve Qwen/Qwen3-8B --host 127.0.0.1 --port 30000 --api-key "$SGLANG_API_KEY"
Флаг --prerelease=allow указан в официальной инструкции: некоторые зависимости публикуются как предварительные версии. Для воспроизводимости закрепите версию пакета, например sglang==0.5.23.
В старых инструкциях встречается команда python -m sglang.launch_server --model-path .... Она по-прежнему используется в части документации, но краткое руководство теперь показывает sglang serve.
Проверка API
curl http://127.0.0.1:30000/v1/chat/completions \
-H "Authorization: Bearer $SGLANG_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"Qwen/Qwen3-8B","messages":[{"role":"user","content":"Назови три признака перегрузки сервера LLM"}],"max_tokens":200}'
Ответ ищите в choices[0].message.content. Из Python подходит клиент OpenAI:
import os
from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:30000/v1", api_key=os.environ["SGLANG_API_KEY"])
stream = client.chat.completions.create(
model="Qwen/Qwen3-8B",
messages=[{"role": "user", "content": "Объясни, что такое prefix caching, в трёх предложениях"}],
max_tokens=300,
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="", flush=True)
Флаг --served-model-name меняет имя, которое сервер возвращает в /v1/models; это удобно, когда клиенты не должны зависеть от пути к весам.
Основные параметры сервера
| Параметр | По умолчанию | Зачем менять |
|---|---|---|
--api-key |
не задан | Защитить API ключом |
--context-length |
из config.json модели |
Ограничить максимальный контекст и память под него |
--mem-fraction-static |
рассчитывается по памяти GPU, 0.88 если её не удалось определить | Доля памяти под веса и пул KV-кэша; уменьшить при ошибках нехватки памяти |
--tp-size |
1 | Разделить модель между несколькими GPU |
--chunked-prefill-size |
не задан | Размер частей при chunked prefill; -1 отключает разбиение |
--max-running-requests |
не задан | Ограничить число одновременно обрабатываемых запросов |
--schedule-policy |
fcfs |
Выбрать порядок обслуживания: lpm, priority, routing-key и другие |
--kv-cache-dtype |
auto |
Сжать KV-кэш, например до fp8_e4m3 |
--enable-metrics |
выключено | Включить метрики Prometheus |
--tool-call-parser |
не задан | Разбор вызовов инструментов; auto берёт его из шаблона чата |
--disable-radix-cache |
выключено | Отключить кэширование префиксов, например для тестов |
Справочник аргументов предлагает при нехватке памяти уменьшить --mem-fraction-static, например до 0.7. Подробно про сжатие кэша — в статье «KV-кэш в FP8», про выгрузку кэша в оперативную память через HiCache — в статье о выгрузке KV-кэша в RAM и на NVMe.
Параметры можно хранить в YAML-файле и передавать через --config; значения из командной строки перекрывают файл.
Несколько GPU
Если модель не помещается в одну видеокарту, используйте тензорный параллелизм:
sglang serve Qwen/Qwen3-32B --host 127.0.0.1 --port 30000 \
--tp-size 2 --api-key "$SGLANG_API_KEY"
Если модель помещается, но нужна большая пропускная способность, в справочнике есть пример сочетания параллелизма данных --dp и тензорного --tp. Когда что выбирать, разобрано в статье «LLM на нескольких GPU».
Метрики
С флагом --enable-metrics SGLang отдаёт метрики Prometheus. По описанию производственных метрик для начала полезны:
| Метрика | Что показывает |
|---|---|
sglang:num_running_reqs |
Запросы в обработке |
sglang:num_queue_reqs |
Запросы в очереди |
sglang:token_usage |
Доля занятой памяти под токены |
sglang:cache_hit_rate |
Доля попаданий в кэш префиксов |
sglang:gen_throughput |
Скорость генерации, токенов в секунду |
sglang:time_to_first_token_seconds |
Гистограмма времени до первого токена |
sglang:inter_token_latency_seconds |
Гистограмма задержки между токенами |
Растущая num_queue_reqs при высокой token_usage означает, что не хватает памяти под кэш; растущая очередь при свободной памяти — что упираетесь в вычисления или лимит --max-running-requests. Как строить очередь с лимитами на шлюзе, описано в статье об очереди запросов к LLM.
Безопасность и обновления
- Задавайте
--api-keyи не публикуйте порт 30000 на внешний интерфейс без обратного прокси с TLS. - Если используете раздельные prefill и decode, обновитесь: в 2026 году в SGLang исправляли утечку KV-кэша между пользователями, подробности в статье «Утечка KV-кэша в SGLang».
- Закрепляйте версию образа и читайте заметки к выпускам перед обновлением.
- Храните кэш весов на отдельном томе с ограниченным доступом.
Частые ошибки
- Контейнер не видит GPU — не установлен или не настроен NVIDIA Container Toolkit, либо драйвер не поддерживает CUDA 13.
- Нехватка памяти при запуске или под нагрузкой — уменьшите
--mem-fraction-staticили--context-length. - Сбои процессов без понятной ошибки — проверьте, что контейнеру выделена разделяемая память (
--ipc=host,--shm-size). - Вызовы инструментов возвращаются текстом — не задан
--tool-call-parserдля модели. - Сервер доступен из сети без пароля — в команде
--host 0.0.0.0без--api-keyи без ограничения публикации порта.
Частые вопросы
Чем sglang serve отличается от python -m sglang.launch_server? Обе формы встречаются в документации; краткое руководство использует sglang serve. Параметры в них те же.
Можно ли запустить SGLang на CUDA 12? Последняя метка образа под CUDA 12 — v0.5.19-cu129. На ней не будет исправлений из более поздних выпусков, включая исправления безопасности.
Есть ли у SGLang приоритеты запросов? Да, среди политик --schedule-policy есть priority. Для справедливости между отделами всё равно нужен шлюз с лимитами.
Подходит ли SGLang для одного пользователя на рабочей станции? Подходит, но для одного пользователя проще Ollama или llama-server. SGLang раскрывается на многопользовательской нагрузке.
Как AI студия Владимира Ломтева помогает развернуть SGLang
AI студия Владимира Ломтева разворачивает LLM на серверах компании и сопровождает их. Для SGLang это означает:
- проверить совместимость драйверов, GPU и выбранной модели с текущей версией SGLang;
- настроить сервер с ключами, обратным прокси, метриками и закреплёнными версиями;
- сравнить SGLang и vLLM нагрузочным тестом на ваших запросах;
- интегрировать API с корпоративными системами и передать команде порядок обновления.
Первый шаг — выбрать модель и одну рабочую задачу, записать требования к задержке и числу пользователей и проверить их на тестовом сервере. Обсудить задачу.
Итог: SGLang запускается быстро, но требует CUDA 13
Запуск SGLang сводится к одной команде в Docker, если на хосте свежий драйвер NVIDIA и настроен Container Toolkit. Закрепите версию образа, задайте ключ и метрики, подберите память под кэш и проверьте сервер на своей нагрузке. Сильнее всего SGLang проявляет себя там, где у запросов много общего начала: агенты, диалоги и RAG.






