# SGLang в Docker: запуск на NVIDIA GPU и проверка локального API

Источник: https://modelium.tech/zhurnal/sglang-v-docker/

Официальный образ SGLang позволяет запустить локальный сервер модели в Docker на совместимом NVIDIA GPU. Закрепите digest образа и ревизию модели, направьте порт только на localhost, затем проверьте реальный ответ Chat API. Docker не заменяет проверку драйвера, памяти и сетевой изоляции; это инструкция по первоисточникам, а не результат прогона Modelium.

На 6 октября 2026 года официальный quickstart SGLang предлагает образ `lmsysorg/sglang` для сервера на Linux с NVIDIA GPU. В нём уже есть Python и зависимости SGLang, но совместимый GPU, драйвер и настроенный NVIDIA Container Toolkit нужны на хосте отдельно. Ниже — контрольный запуск текстовой модели и проверка API, а не тест производительности или качества русского языка. [s1](#src-s1) [s2](#src-s2)

## Что проверить до запуска контейнера

Подготовьте Docker Engine, поддерживаемый NVIDIA GPU и драйвер, совместимый с CUDA 13, затем настройте NVIDIA Container Toolkit для Docker. Именно такую комбинацию описывает текущая документация SGLang для обычного CUDA-образа; AMD ROCm, CPU и Windows не следует подставлять в эту команду без отдельного образа и инструкции. Проверка доступности GPU на хосте и внутри Docker — предварительное условие, не выводимое из модели видеокарты или размера файла весов. Modelium не проверял конкретное устройство читателя. [s1](#src-s1)

Для контрольного запроса возьмите `Qwen/Qwen3-0.6B`: модель приведена в официальном Docker quickstart, а карточка Hugging Face закреплена на ревизии `c1899de289a04d12100db370d81485cdf75e47ca`. Метка `apache-2.0` описывает репозиторий модели; при рабочем использовании отдельно изучите полный текст лицензии и условия ваших данных. Выбор компактного примера не означает гарантии скорости, вместимости GPU или пригодности ответов для российских документов. [s2](#src-s2) [s5](#src-s5)

## Как запустить SGLang в Docker с локальным портом

На дату проверки Docker Hub показывает тег `v0.5.21` и индексный digest `sha256:b1259f3ea3275f66237c498ea388919729018bc9f01c3d638391e06e2cf3f469`; индекс включает образы Linux amd64 и arm64. Использование полного digest, а не изменяемого `latest`, фиксирует состав скачиваемого образа в этом примере. Перед реальным запуском сверьте архитектуру хоста, размер загрузки, совместимость драйвера и наличие свободного места; образ крупный, Modelium его не скачивал. [s4](#src-s4) [s1](#src-s1)

Пример для **доверенного тестового Linux-хоста**, составленный по официальной инструкции, но **не запущенный Modelium**: `docker run --rm --gpus all --ipc=host -p 127.0.0.1:30000:30000 -v "$HOME/.cache/huggingface:/root/.cache/huggingface" lmsysorg/sglang@sha256:b1259f3ea3275f66237c498ea388919729018bc9f01c3d638391e06e2cf3f469 sglang serve Qwen/Qwen3-0.6B --revision c1899de289a04d12100db370d81485cdf75e47ca --host 0.0.0.0 --port 30000`. Документация подтверждает образ, `--gpus all`, порт 30000, кеш HF и `--ipc=host`; аргумент `--revision` принимает commit модели. Привязка `127.0.0.1` — сознательное ограничение хостового порта по документации Docker, тогда как `--host 0.0.0.0` нужен *внутри* контейнера для доступности через опубликованный порт. Используйте только свой доверенный кеш; общий IPC даёт контейнеру доступ к пространству IPC хоста. [s1](#src-s1) [s2](#src-s2) [s3](#src-s3) [s4](#src-s4) [s5](#src-s5) [s6](#src-s6)

`--rm` удаляет остановившийся контейнер, но смонтированный кеш на хосте остаётся. Не копируйте официальный `docker/compose.yaml` вслепую для одного тестового сервера: он включает `privileged: true`, `network_mode: host`, `ipc: host` и пример `HF_TOKEN`; такая конфигурация меняет сетевые и привилегированные границы, а ключ нельзя хранить прямо в общедоступном Compose-файле. Ключ к публичной Qwen-модели в данном примере не нужен. [s2](#src-s2) [s7](#src-s7) [s5](#src-s5)

## Как проверить, что отвечает именно выбранная модель

Дождитесь сообщения готовности, указанного в quickstart SGLang. С того же хоста обратитесь к `http://127.0.0.1:30000/v1/models` и убедитесь, что `data` содержит ожидаемый идентификатор модели. Это проверка объявленного ID, **не** подтверждение реальной генерации: флаг `--served-model-name` позволяет переименовать опубликованный ID. Если имя отличается от ожидаемого, уточните его до Chat API запроса. [s2](#src-s2) [s3](#src-s3)

Далее отправьте `POST http://127.0.0.1:30000/v1/chat/completions` с заголовком `Content-Type: application/json` и телом `{"model":"Qwen/Qwen3-0.6B","messages":[{"role":"user","content":"Ответь одним словом: привет"}],"max_tokens":256}`. Используйте ровно тот ID, который объявлен сервером; проверьте код HTTP и JSON в `choices[0].message.content`. У Qwen3 есть режим рассуждения, а в документации SGLang отдельно показано поле `reasoning_content`; если лимит токенов исчерпан без содержательного `content`, это **не** успешный ответ: изучите оба поля и повторите контролируемый тест с уместными параметрами. Оценку качества на своей задаче проводите отдельно. Это протокол проверки по документации, не фактический ответ Modelium. [s2](#src-s2) [s3](#src-s3) [s5](#src-s5) [s8](#src-s8)

## Какие ошибки и границы безопасности учитывать

Если сервер не стартует, отдельно проверьте работу GPU-контейнерного runtime, видимость устройства, совместимость драйвера с образом и логи контейнера. Если Chat API не отвечает при доступном `/v1/models`, проверьте совпадение model ID, логи загрузки, шаблон чата и HTTP-ошибку; один ответ списка моделей не доказывает успешную генерацию. Не называйте размер файла весов минимальной VRAM: рабочая память зависит от модели, контекста и конфигурации сервера. [s1](#src-s1) [s2](#src-s2) [s3](#src-s3)

Публикация `-p 127.0.0.1:30000:30000` уже безопаснее обычного `-p 30000:30000`, но это не доказательство полной изоляции. Docker предупреждает, что до версии Engine 28.0.0 хосты в том же L2-сегменте могли достигать даже опубликованного на localhost порта. Перед подключением клиентов из сети настройте отдельные правила, аутентификацию и проверку внешней доступности; в справочнике SGLang есть флаг `--api-key`, но сам по себе он не заменяет сетевой периметр. [s6](#src-s6) [s3](#src-s3)

Остановите интерактивный тест через Ctrl+C и проверьте оставшийся кеш модели на хосте. Следующий шаг — [основной гайд SGLang](/zhurnal/sglang/): соотнесите задачу, формат выбранной модели, доступное железо и версию сервера перед рабочей нагрузкой. Для сравнения с альтернативным runtime откройте [SGLang или vLLM](/zhurnal/sglang-ili-vllm/). Modelium не запускал этот контейнер и не измерял память или скорость. [s1](#src-s1) [s2](#src-s2)

## Источники

1. [SGLang: Installation, Docker и требования к GPU](https://github.com/sgl-project/sglang/blob/968726f3cea0f6d6f44bea84797e5e5914658f4e/docs/docs/get-started/install.mdx) — получено 2026-10-06
2. [SGLang: Quickstart, Docker и Chat API](https://github.com/sgl-project/sglang/blob/968726f3cea0f6d6f44bea84797e5e5914658f4e/docs/docs/get-started/quickstart.mdx) — получено 2026-10-06
3. [SGLang: Server Arguments, revision, host, port и ID модели](https://github.com/sgl-project/sglang/blob/968726f3cea0f6d6f44bea84797e5e5914658f4e/docs/docs/advanced_features/server_arguments.mdx) — получено 2026-10-06
4. [Docker Hub: lmsysorg/sglang v0.5.21, индексный digest](https://hub.docker.com/v2/repositories/lmsysorg/sglang/tags/v0.5.21) — получено 2026-10-06
5. [Qwen/Qwen3-0.6B: карточка конкретной ревизии](https://huggingface.co/Qwen/Qwen3-0.6B/blob/c1899de289a04d12100db370d81485cdf75e47ca/README.md) — получено 2026-10-06
6. [Docker: Publishing and exposing ports, localhost и предупреждение до 28.0.0](https://docs.docker.com/engine/network/port-publishing/) — получено 2026-10-06
7. [SGLang: официальный compose.yaml и права контейнера](https://github.com/sgl-project/sglang/blob/968726f3cea0f6d6f44bea84797e5e5914658f4e/docker/compose.yaml) — получено 2026-10-06
8. [SGLang: OpenAI-Compatible Completions и поле reasoning_content](https://github.com/sgl-project/sglang/blob/968726f3cea0f6d6f44bea84797e5e5914658f4e/docs/docs/basic_usage/openai_api_completions.mdx) — получено 2026-10-06