Быстрый старт SGLang: установка, настройка и развертывание больших языковых моделей через API OpenAI

Запускайте открытые модели быстро с помощью SGLang.

Содержимое страницы

SGLang — это высокопроизводительный фреймворк для развертывания больших языковых и мультимодальных моделей, созданный для обеспечения низколатентного и высокопроизводительного вывода на устройствах от одной GPU до распределенных кластеров.

Для более широкого сравнения вариантов размещения самовосстанавливаемых и облачных LLM, включая Ollama, vLLM, llama-swap, LocalAI и управляемых облачных провайдеров, см. руководство по размещению LLM на 2026 год.

Если у вас уже есть приложения, настроенные на работу с API OpenAI, SGLang особенно привлекателен, так как он предоставляет совместимые с OpenAI конечные точки для чата и генерации, помогая вам перейти от размещенных API к самовосстанавливаемым моделям с минимальными изменениями на стороне клиента. Когда вам нужно маршрутизировать запросы между несколькими бэкендами (llama.cpp, vLLM, SGLang и т. д.) с возможностью горячей замены и разгрузкой на основе TTL, llama-swap предоставляет прозрачный прокси-слой, который сохраняет стабильный URL /v1, одновременно меняя вышестоящие серверы по требованию.

sglang infographic

Это быстрое руководство описывает установку (множество методов), практические паттерны конфигурации и чистый рабочий процесс «установка → запуск → проверка → интеграция → настройка», с рабочими примерами как для HTTP-сервера, так и для офлайн-выполнения пакетного вывода.

Если вам нужна поддержка мультимодальности (текст, эмбеддинги, изображения, аудио) со встроенным веб-интерфейсом и максимальной совместимостью с API OpenAI, LocalAI предлагает более широкий набор функций с поддержкой большего количества форматов моделей.

Что такое SGLang для высокопроизводительного развертывания LLM и мультимодальных моделей

В основе SGLang лежит эффективный вывод и масштабируемое развертывание. Стек «быстрого времени выполнения» включает RadixAttention для кэширования префиксов, планировщик CPU без накладных расходов, спекулятивную декомпозицию, непрерывную пакетную обработку (continuous batching), paginated attention, несколько стратегий параллелизма (тензорный, конвейерный, экспертный, параллелизм данных), структурированный вывод, чанкованную предзагрузку и множество вариантов квантования (например, FP4, FP8, INT4, AWQ, GPTQ).

Оно предназначено для развертывания на широкой платформе: GPU NVIDIA, GPU AMD, CPU Intel Xeon, TPU Google, NPU Ascend и многое другое.

PyPI требует Python >= 3.10. По состоянию на 23 марта 2026 года опубликованная версия включала 0.5.9 (выпущенную 23 февраля 2026 года) — при установке фиксируйте или проверяйте текущие версии.

Как установить SGLang на Linux-хосты с GPU с помощью uv pip, сборки из исходного кода или Docker

Варианты установки включают uv или pip, сборку из исходного кода, образы Docker, манифесты Kubernetes, Docker Compose, SkyPilot и AWS SageMaker. Большинство инструкций предполагают стандартные настройки GPU NVIDIA; для других ускорителей есть свои примечания по настройке.

Быстрая установка SGLang с помощью uv или pip на Python 3.10+

Для простой локальной установки uv обычно является самым быстрым путем:

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

Примечания по CUDA 13

Для CUDA 13 Docker позволяет избежать несоответствий PyTorch/CUDA на стороне хоста. Без Docker: установите сборку PyTorch с поддержкой CUDA 13, затем sglang, а затем соответствующий колесо sglang-kernel из опубликованных релизов (версия должна соответствовать стеку).

# 1) Установите PyTorch с поддержкой CUDA 13 (замените X.Y.Z при необходимости)
uv pip install torch==X.Y.Z torchvision torchaudio --index-url https://download.pytorch.org/whl/cu130

# 2) Установите SGLang
uv pip install sglang

# 3) Установите соответствующий колесо sglang-kernel для CUDA 13 (замените 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"

Установка и запуск SGLang с помощью образов Docker Hub

Для контейнерных развертываний — или чтобы обойти проблему связывания CUDA/PyTorch на хосте — используйте опубликованные образы Docker Hub. Типичный docker run монтирует кэш Hugging Face и передает HF_TOKEN при загрузке закрытых моделей.

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

Для продуктовых образов latest-runtime исключает инструменты сборки и зависимости разработки, поэтому образ остается намного меньше, чем стандартный вариант 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

Установка из исходного кода и другие методы развертывания

Для разработки с SGLang или внесения локальных исправлений клонируйте ветку релиза и установите пакет Python в режиме редактирования:

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

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

Для оркестрации репозиторий включает манифесты Kubernetes (одноузловые и многоузловые) и минимальную структуру Docker Compose — разумные отправные точки перед кастомной настройкой.

Как настроить аргументы сервера SGLang с помощью YAML-файлов конфигурации и переменных окружения

Конфигурация SGLang управляется аргументами сервера и переменными окружения. Флаги охватывают выбор модели, параллелизм, память и параметры оптимизации; полный набор перечислен в python3 -m sglang.launch_server --help.

Переменные окружения используют две префиксы: SGL_ и SGLANG_ (многие флаги принимают либо CLI, либо env-форму — launch_server --help показывает сопоставление).

Некоторые часто используемые переменные окружения включают управление хостом и портом, такие как SGLANG_HOST_IP и SGLANG_PORT.

Используйте YAML-файл конфигурации для воспроизводимого запуска сервера SGLang

Для повторяемых развертываний и более коротких командных строк передайте YAML-файл с помощью --config. Аргументы CLI переопределяют значения из файла, когда оба устанавливаются для одного и того же параметра.

# Создайте 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

# Запустите сервер с файлом конфигурации
python -m sglang.launch_server --config config.yaml

Вот несколько существенных моментов конфигурации и настройки, которые следует учитывать:

Параметр --model-path в SGLang может указывать на локальную папку или ID репозитория Hugging Face, что позволяет легко переключаться между локальными весами и моделями на Hub без изменения кода сервера.

Для многоядерных GPU включите тензорный параллелизм с помощью --tp. Если при запуске возникает ошибка «peer access is not supported between these two devices», добавьте --enable-p2p-check.

Если при обслуживании возникает OOM, уменьшите давление на кэш KV с помощью меньшего значения --mem-fraction-static (по умолчанию 0.9).

Если при предзагрузке длинных промптов возникает OOM, уменьшите --chunked-prefill-size.

Как запустить сервер SGLang, совместимый с OpenAI, и вызывать его из клиента Python OpenAI

Практический «идеальный» рабочий процесс выглядит следующим образом:

  1. Установите SGLang (uv/pip или Docker).
  2. Запустите сервер с выбранной моделью и портом.
  3. Проверьте базовое обслуживание через совместимые с OpenAI конечные точки.
  4. Интегрируйте ваше приложение, указав base_url SDK OpenAI на локальный сервер.
  5. Настройте пропускную способность и память с помощью аргументов сервера, как только появится реальный трафик.

Отправка локального запроса на завершение чата в SGLang с помощью SDK OpenAI

Для использования, совместимого с OpenAI, важны две детали:

Сервер реализует HTTP-интерфейс OpenAI и, когда токенизатор предоставляет шаблон, автоматически применяет шаблон чата Hugging Face. При необходимости перезапишите его с помощью --chat-template при запуске.

Направьте клиент OpenAI на префикс сервера /v1 (base_url → http://<host>:<port>/v1), затем вызовите client.chat.completions.create(...) как обычно.

Запустите сервер с любым из двух входов: python -m sglang.launch_server все еще работает, но sglang serve является предпочтительным CLI.

# Рекомендуемая точка входа CLI
sglang serve --model-path qwen/qwen2.5-0.5b-instruct --host 0.0.0.0 --port 30000

# Все еще поддерживается
python3 -m sglang.launch_server --model-path qwen/qwen2.5-0.5b-instruct --host 0.0.0.0 --port 30000

Затем вызовите его с помощью клиента 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": "Перечислите 3 страны и их столицы."}],
    temperature=0,
    max_tokens=64,
)

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

Как выполнить пакетный вывод с помощью API SGLang Offline Engine и нативных конечных точек

SGLang поддерживает несколько «поверхностей API» в зависимости от того, что вы строите:

Конечная точка /generate — это низкоуровневый API времени выполнения. Отдавайте предпочтение маршрутам OpenAI /v1/..., когда вы хотите, чтобы шаблоны чата и обычная экосистема клиентов обрабатывались за вас.

Без HTTP-сервера Offline Engine выполняет вывод внутри процесса: подходит для пакетных заданий и пользовательских сервисов. Он поддерживает синхронные/асинхронные и потоковые/непотоковые комбинации — выберите режим, который соответствует паттерну вызова.

Пример использования нативной конечной точки /generate

Минимальный паттерн: запустите сервер, затем отправьте POST-запрос на /generate с параметрами temperature и max_new_tokens (и любыми другими параметрами выборки, которые вам нужны).

import requests

response = requests.post(
    "http://localhost:30000/generate",
    json={
        "text": "Столица Франции —",
        "sampling_params": {
            "temperature": 0,
            "max_new_tokens": 32,
        },
    },
)

print(response.json())

temperature = 0 означает жадную выборку; более высокие значения увеличивают разнообразие.

Пример использования API Offline Engine для пакетного вывода внутри процесса

Типичный поток: создайте sgl.Engine(model_path=...), выполните llm.generate(...) для пакета промптов, затем llm.shutdown() для освобождения GPU и других ресурсов.

import sglang as sgl

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

prompts = [
    "Напишите краткое самовыступление.",
    "Объясните, что такое кэширование префиксов, в одном абзаце.",
]

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