Как запустить SGLang: установка, сервер и OpenAI API

запуск SGLang
SGLang установка Docker
sglang serve OpenAI API
Как запустить SGLang: установка, сервер и OpenAI API

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

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.

Оставить заявку

Заполните форму и мы свяжемся с вами

← Все статьи

Комментарии (0)

Пока нет комментариев. Будьте первым!

Оставить комментарий
Регистрация не требуется