---
title: "vLLM и SGLang: практическое сравнение двух серверов для языковых моделей"
url: "https://romankryvolapov.com/ru/vllm-vs-sglang/"
description: "vLLM 0.34 и SGLang 0.5.23 бок о бок: установка, запуск моделей, видеопамять, форматы и квантование, настройка, API, кэш диалогов, сеть и безопасность, маршрутизация, метрики, журналы и трассировка — с командами, файлами настроек, скриншотами и замерами на видеокарте с 12 ГБ."
language: ru
published: 2026-11-21
updated: 2026-11-21
---
**Привет!**

vLLM и SGLang — два главных открытых сервера для запуска языковых моделей на своих видеокартах. Задача у них одна, API одинаковый, скорость близкая. Различаются они в работе с памятью, настройке, безопасности и мониторинге.

В каждом разделе статьи сначала общая часть, потом подраздел про vLLM и подраздел про SGLang. Версии: **vLLM 0.34.0** от 16 ноября 2026 и **SGLang 0.5.23** от 2 ноября 2026. Команды, файлы настроек и вывод взяты с рабочего стенда; что пересказано по документации без запуска, помечено.

Главное:

- **Один запрос** оба обрабатывают с одинаковой скоростью. Разница появляется под нагрузкой и зависит от модели.
- **Память:** vLLM распределяет её сам, в SGLang долю задаёте вы.
- **Кэш диалогов** у SGLang точнее: он экономит больше на длинных диалогах и агентах.
- **Безопасность:** ни один нельзя выставлять в интернет без прокси.
- **vLLM** — выбор по умолчанию, **SGLang** — под агентов и большие кластеры. Схема выбора — [в конце](#Что-выбрать).

Как движки инференса устроены внутри, разобрано в [отдельной статье](/ru/llm-inference-engines/). Здесь нужны четыре понятия оттуда: [токены](/ru/llm-inference-engines/#Токены-и-веса), [фазы prefill и decode](/ru/llm-inference-engines/#Prefill-и-decode-две-фазы-с-разными-узкими-местами), [KV-кэш](/ru/llm-inference-engines/#KV-кэш) и [батчинг](/ru/llm-inference-engines/#Батчинг-почему-сервер-обслуживает-многих-почти-по-цене-одного). TTFT — время до первого токена ответа.

## Что такое vLLM и SGLang

Сервер инференса держит модель в видеопамяти, принимает запросы по HTTP в формате OpenAI и обрабатывает много запросов одновременно. Путь запроса:

<div style="overflow-x:auto;margin:1.5rem 0" tabindex="0" role="region">
<svg viewBox="0 0 780 290" width="100%" style="min-width:620px;max-width:780px;height:auto;display:block;margin:0 auto" role="img" aria-label="Путь запроса: клиент, API-сервер, очередь, планировщик, видеокарта, ответ" xmlns="http://www.w3.org/2000/svg">
  <defs>
    <marker id="vs-request-head" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
      <path d="M0 0 L10 5 L0 10 z" fill="var(--color-fg-dim)"/>
    </marker>
    <marker id="vs-request-tail" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
      <path d="M0 0 L10 5 L0 10 z" fill="var(--color-fg-dim)"/>
    </marker>
  </defs>
  <rect x="30" y="24" width="200" height="92" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-link)" stroke-width="1.5"/>
  <text x="130" y="48" text-anchor="middle" fill="var(--color-link)" font-family="var(--font-sans)" font-size="14" font-weight="500">клиент</text>
  <text x="130" y="68" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">запрос по HTTP</text>
  <text x="130" y="85" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">в формате OpenAI</text>
  <rect x="290" y="24" width="200" height="92" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-border)" stroke-width="1.5"/>
  <text x="390" y="48" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="14" font-weight="500">API-сервер</text>
  <text x="390" y="68" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">шаблон чата, токены,</text>
  <text x="390" y="85" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">проверка ключа</text>
  <rect x="550" y="24" width="200" height="92" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-border)" stroke-width="1.5"/>
  <text x="650" y="48" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="14" font-weight="500">очередь</text>
  <text x="650" y="68" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">запрос ждёт места</text>
  <text x="650" y="85" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">в памяти и в батче</text>
  <rect x="550" y="176" width="200" height="92" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-accent)" stroke-width="1.5"/>
  <text x="650" y="200" text-anchor="middle" fill="var(--color-accent)" font-family="var(--font-sans)" font-size="14" font-weight="500">планировщик</text>
  <text x="650" y="220" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">каждый шаг собирает батч</text>
  <text x="650" y="237" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">из всех активных запросов</text>
  <rect x="290" y="176" width="200" height="92" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-accent)" stroke-width="1.5"/>
  <text x="390" y="200" text-anchor="middle" fill="var(--color-accent)" font-family="var(--font-sans)" font-size="14" font-weight="500">видеокарта</text>
  <text x="390" y="220" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">prefill: чтение промпта</text>
  <text x="390" y="237" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">decode: токен за токеном</text>
  <rect x="30" y="176" width="200" height="92" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-link)" stroke-width="1.5"/>
  <text x="130" y="200" text-anchor="middle" fill="var(--color-link)" font-family="var(--font-sans)" font-size="14" font-weight="500">ответ</text>
  <text x="130" y="220" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">токены → текст,</text>
  <text x="130" y="237" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">поток по мере генерации</text>
  <path d="M230 70 L290 70" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" marker-end="url(#vs-request-head)"/>
  <path d="M490 70 L550 70" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" marker-end="url(#vs-request-head)"/>
  <path d="M650 116 L650 176" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" marker-end="url(#vs-request-head)"/>
  <path d="M550 222 L490 222" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" marker-end="url(#vs-request-head)" marker-start="url(#vs-request-tail)"/>
  <path d="M290 222 L230 222" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" marker-end="url(#vs-request-head)"/>
  <text x="520" y="212" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12" font-weight="400">шаг</text>
</svg>
</div>

### vLLM: кто его делает

- [Репозиторий](https://github.com/vllm-project/vllm): около 97 тысяч звёзд, лицензия Apache 2.0, новая версия каждые две недели.
- Появился в 2023 году в Беркли. С 2025 года — проект PyTorch Foundation. С января 2026-го за ним стоит компания Inferact (150 млн долларов инвестиций).
- Кто использует: [LinkedIn](https://www.linkedin.com/blog/engineering/ai/how-we-leveraged-vllm-to-power-our-genai-applications) (больше 50 продуктов), Red Hat (основа её продуктов для OpenShift), AWS (SageMaker и Bedrock), NVIDIA (контейнеры [NIM 2](https://docs.nvidia.com/nim/large-language-models/2.1.5/about-nim-llm/overview.html) содержат vLLM или SGLang).

### SGLang: кто его делает

- [Репозиторий](https://github.com/sgl-project/sglang): около 39 тысяч звёзд, лицензия Apache 2.0, новая версия каждые две недели.
- Появился в 2024 году. Ведёт его некоммерческая LMSYS, авторы рейтинга Chatbot Arena. С 2026 года за ним стоит компания RadixArk (100 млн долларов инвестиций).
- Кто использует: xAI ([карточка Grok-2](https://huggingface.co/xai-org/grok-2) велит запускать модель через SGLang), Meta ([по её докладу](https://www.lmsys.org/blog/2026-11-17-sglang-summit-recap) в ноябре 2026-го), Cloudflare (Workers AI), LinkedIn (ранжирование в поиске; LinkedIn использует оба сервера).

## Чем они отличаются от других способов запустить модель

vLLM и SGLang рассчитаны на много одновременных запросов на своих видеокартах. Для одного пользователя они не быстрее простых программ.

| Способ | Для чего | Отличие от vLLM и SGLang |
|---|---|---|
| **llama.cpp**, Ollama, LM Studio | модель на своём компьютере | работает даже без видеокарты, сжатые модели GGUF, старт за секунды; под нагрузкой от многих пользователей слабее |
| **TensorRT-LLM** | максимум скорости на NVIDIA | только NVIDIA, меньше моделей |
| **NVIDIA NIM** | готовый контейнер с платной поддержкой | не движок: внутри vLLM или SGLang |
| **TGI** от Hugging Face | бывший главный соперник | в архиве, авторы советуют vLLM и SGLang |
| **Dynamo, llm-d, AIBrix** | десятки видеокарт в Kubernetes | слой над движками: раздаёт запросы копиям vLLM или SGLang |
| **LiteLLM** | один адрес для разных моделей, ключи, бюджеты | шлюз перед серверами, модели не запускает |
| **Облачный API** | оплата за токены | нечего обслуживать; своя видеокарта окупается только при постоянной загрузке |

Подробнее — в [карте движков](/ru/llm-inference-engines/#Карта-движков).

### vLLM: место среди других систем

Выбор по умолчанию. Самый широкий список моделей и железа. Слои для [Kubernetes](/ru/kubernetes/) (llm-d, AIBrix, KServe), Ray Serve и продукты Red Hat в первую очередь поддерживают его. В тестах MLPerf в апреле 2026 года на нём работали 20 участников ([подсчёт Red Hat](https://www.redhat.com/en/blog/red-hat-ai-tops-mlperf-inference-v60-vllm-qwen3-vl-whisper-and-gpt-oss-120b)).

### SGLang: место среди других систем

Сильнее на запросах с общим началом: агенты, длинные диалоги, один системный промпт у многих пользователей. Часто впереди на очень больших моделях на десятках видеокарт. Те же слои для кластеров его поддерживают, но обычно позже, чем vLLM.

## Стенд

- Видеокарта RTX 5070 Ti Laptop, 12 ГБ; Ryzen 9 9955HX; 64 ГБ оперативной памяти.
- Windows 11, WSL2, Docker Desktop.
- Образы `vllm/vllm-openai:v0.34.0` и `lmsysorg/sglang:v0.5.23-runtime`.
- Prometheus 3.16, Grafana 13.3, Jaeger 2.23, nginx 1.30 — в той же сети Docker.

Модели — семейство Qwen3.5: понимают картинки, рассуждают перед ответом, вызывают функции, лицензия Apache 2.0.

| Модель | Веса | На 12 ГБ |
|---|---|---|
| Qwen3.5-4B, FP8 | 7,5 ГиБ | основная модель статьи |
| Qwen3.5-2B | 4,3 ГиБ | замеры под нагрузкой |
| Qwen3.5-0.8B | 1,7 ГиБ | две копии сразу, для маршрутизации |
| Qwen3.5-4B без сжатия | 8,7 ГиБ | не запускается |
| Qwen3.5-9B, 4 бита | 8,5 ГиБ | не запускается |

Абсолютные цифры скорости на ноутбуке в разы ниже серверных. Настройки, ошибки и содержание журналов на большом железе те же.

## Железо и системы

Обоим серверам нужны Linux, ускоритель с достаточной памятью и свежие драйверы.

### vLLM: железо и системы

- **ОС:** только Linux. Windows — через WSL2 или Docker, Mac — через плагин vllm-metal.
- **Python:** 3.11–3.14.
- **NVIDIA:** от T4 и RTX 20xx. Сборки только под CUDA 13. Для старых драйверов — `VLLM_ENABLE_CUDA_COMPATIBILITY=1`.
- **AMD:** Instinct MI200, MI300, MI350, Radeon RX 7900 и RX 9000 (ROCm).
- **Intel:** Arc и серверные ускорители.
- **Плагинами:** Google TPU, AWS Trainium, Huawei Ascend, Apple Silicon.
- **Без видеокарты:** работает, для маленьких моделей.

### SGLang: железо и системы

- **ОС:** Linux. Windows в документации не упоминается; в Docker поверх WSL2 работает.
- **Python:** 3.11 и новее. На 3.10 установка не падает, а ставит старую версию сервера.
- **NVIDIA:** от A100 до новейших серверных, RTX 30, 40 и 50, DGX Spark, Jetson. Только CUDA 13.
- **AMD:** Instinct MI300X, MI325X, MI350X, MI355X.
- **Intel:** Arc и Xeon.
- **Прочее:** Google TPU, Huawei Ascend, Apple Silicon, Moore Threads.
- **RTX 50 и установка через pip:** ни одна модель не запускается без ручной настройки путей к компилятору CUDA ([открытая задача](https://github.com/sgl-project/sglang/issues/49209)). В образе Docker проблемы нет.

## Установка

Два способа: пакет Python или образ Docker. В продакшене берут образ с номером версии, а не `latest`: обе программы выходят каждые две недели и регулярно меняют флаги.

Модели скачиваются с Hugging Face при первом запуске в `~/.cache/huggingface`. Эту папку подключают к контейнеру, чтобы не качать заново.

### vLLM: установка

```bash
uv pip install vllm --torch-backend=auto
vllm download-kernels
```

Вторая команда скачивает готовые ядра для видеокарты. Без неё сервер компилирует их при первом запуске несколько минут. Запускать после каждой установки и обновления.

```bash
docker pull vllm/vllm-openai:v0.34.0
```

Образ: 10 ГБ при скачивании, 36 ГБ на диске.

### SGLang: установка

```bash
uv pip install --prerelease=allow sglang
```

Без `--prerelease=allow` старые версии `uv` молча ставят SGLang 0.5.9.

```bash
docker pull lmsysorg/sglang:v0.5.23-runtime
```

Образ `-runtime` облегчённый: 14,5 ГБ при скачивании, 50 ГБ на диске. Полный, `v0.5.23`, содержит ещё инструменты сборки.

## Первый запуск

Сервер запускается одной командой. vLLM слушает порт 8000, SGLang — 30000. Запросы к ним одинаковые.

### vLLM: первый запуск

```bash
docker run --gpus all --ipc=host -p 8000:8000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -v vllm-cache:/root/.cache/vllm \
  vllm/vllm-openai:v0.34.0 \
  RedHatAI/Qwen3.5-4B-FP8-dynamic \
  --max-model-len 16384 --max-num-seqs 16
```

- `--ipc=host` — процессы сервера обмениваются данными через общую память.
- Том `vllm-cache` хранит скомпилированное при первом запуске.
- Готовность: строка `Application startup complete`. На стенде — через 155 секунд.

Что сервер пишет о памяти:

```text
Model loading took 6.23 GiB memory and 11.814035 seconds
Available KV cache memory: 3.99 GiB
Graph capturing finished in 1 secs, took 0.14 GiB
GPU KV cache size: 34,492 tokens,
  Maximum concurrency for 16,384 tokens per request: 2.11x
```

Памяти диалогов хватает на 34 492 токена — два диалога максимальной длины.

Запрос:

```bash
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "RedHatAI/Qwen3.5-4B-FP8-dynamic",
    "messages": [{"role": "user",
      "content": "What is a KV cache in LLM inference? Answer in two sentences."}],
    "max_tokens": 400
  }'
```

В поле `content` придут рассуждения модели, а не ответ:

```text
Thinking Process:

1.  **Analyze the Request:**
    *   Topic: KV cache in Large Language Model (LLM) inference.
    *   Constraint: Answer in exactly two sentences.
...
```

Сервер не знает, где у модели кончаются рассуждения, пока не задан флаг `--reasoning-parser` (раздел [о настройке](#Настройка)).

Список всех адресов API — на странице `http://localhost:8000/docs`, там 24 операции:

![Страница /docs сервера vLLM: список адресов API](/images/2026/11/vllm-sglang-swagger-vllm.png)

### SGLang: первый запуск

```bash
docker run --gpus all --ipc=host --shm-size 16g -p 30000:30000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  lmsysorg/sglang:v0.5.23-runtime \
  sglang serve RedHatAI/Qwen3.5-4B-FP8-dynamic \
  --host 0.0.0.0 --port 30000 \
  --context-length 16384 --mem-fraction-static 0.8
```

- `--host 0.0.0.0` обязателен в контейнере. По умолчанию сервер слушает `127.0.0.1`: журнал пишет «готов», а запросы снаружи не проходят.
- Готовность: строка `The server is fired up and ready to roll!`. На стенде — через 85–100 секунд.

Что сервер пишет о памяти:

```text
Load weight end. elapsed=2.19 s, quant=compressed-tensors,
  avail mem=4.44 GB, mem usage=6.28 GB.
Mamba Cache is allocated. max_mamba_cache_size: 20,
  conv_state size: 0.02GB, ssm_state size: 0.98GB
KV Cache is allocated. #tokens: 38949, K size: 0.59 GB, V size: 0.59 GB
max_total_num_tokens=38949, max_running_requests=4,
  context_len=16384, available_gpu_mem=0.37 GB
```

Память диалогов — 38 949 токенов, одновременно не больше четырёх запросов.

Запрос и ответ такие же, как у vLLM, меняется только порт. Рассуждения тоже попадают в `content`, пока не задан `--reasoning-parser`.

На странице `/docs` у SGLang 108 операций:

![Страница /docs сервера SGLang: список адресов API](/images/2026/11/vllm-sglang-swagger-sglang.png)

Кроме API для клиентов здесь управление сервером: сброс кэша, обновление весов, загрузка адаптеров, профилирование. Всё это нужно закрыть от посторонних (раздел [о сети](#Сеть-и-безопасность)).

## Видеопамять

От видеопамяти зависит, запустится ли модель, сколько диалогов поместится одновременно и какой они могут быть длины. Память делят:

1. **Веса модели.** Размер равен размеру файлов модели и не меняется.
2. **Память диалогов** ([KV-кэш](/ru/llm-inference-engines/#KV-кэш)). У Qwen3.5-4B — 32 КиБ на токен: диалог на 16 тысяч токенов занимает 512 МиБ. Растёт с числом пользователей.
3. **Состояние гибридных моделей.** У Qwen3.5 обычное внимание только в 8 слоях из 32. Остальные 24 хранят для диалога сжатое состояние постоянного размера. В журналах оно называется Mamba cache.
4. **Рабочие буферы** для вычислений одного шага. На стенде — около 1,6 ГиБ.
5. **Записанные графы вычислений** (CUDA-графы): 0,1–0,5 ГиБ.
6. **Другие программы.** На ноутбуке рабочий стол и браузер занимают 1,2 ГиБ, на выделенном сервере — ничего.

Одна и та же модель в двух серверах:

<div style="overflow-x:auto;margin:1.5rem 0" tabindex="0" role="region">
<svg viewBox="0 0 810 336" width="100%" style="min-width:620px;max-width:810px;height:auto;display:block;margin:0 auto" role="img" aria-label="На что уходит видеопамять у vLLM и SGLang с одной и той же моделью" xmlns="http://www.w3.org/2000/svg">
  <defs>
    <marker id="vs-memory-head" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
      <path d="M0 0 L10 5 L0 10 z" fill="var(--color-fg-dim)"/>
    </marker>
  </defs>
  <text x="236" y="28" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="14" font-weight="500">vLLM 0.34.0</text>
  <text x="236" y="46" text-anchor="start" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12" font-weight="400">без флагов памяти</text>
  <text x="530" y="28" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="14" font-weight="500">SGLang 0.5.23</text>
  <text x="530" y="46" text-anchor="start" fill="var(--color-fg-dim)" font-family="var(--font-mono)" font-size="12" font-weight="400">--mem-fraction-static 0.8</text>
  <text x="16" y="80" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">другие программы</text>
  <rect x="236" y="66" width="39" height="20" rx="3" fill="var(--color-border)" fill-opacity="0.9" stroke="var(--color-border)" stroke-width="1"/>
  <text x="283" y="80" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">1,22 ГиБ</text>
  <rect x="530" y="66" width="38" height="20" rx="3" fill="var(--color-border)" fill-opacity="0.9" stroke="var(--color-border)" stroke-width="1"/>
  <text x="576" y="80" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">1,19 ГиБ</text>
  <text x="16" y="114" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">веса модели</text>
  <rect x="236" y="100" width="203" height="20" rx="3" fill="var(--color-accent)" fill-opacity="0.55" stroke="var(--color-border)" stroke-width="1"/>
  <text x="447" y="114" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">6,33 ГиБ</text>
  <rect x="530" y="100" width="201" height="20" rx="3" fill="var(--color-accent)" fill-opacity="0.55" stroke="var(--color-border)" stroke-width="1"/>
  <text x="739" y="114" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">6,28 ГиБ</text>
  <text x="16" y="148" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">память диалогов</text>
  <rect x="236" y="134" width="45" height="20" rx="3" fill="var(--color-accent)" fill-opacity="0.3" stroke="var(--color-border)" stroke-width="1"/>
  <text x="289" y="148" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">1,41 ГиБ</text>
  <rect x="530" y="134" width="38" height="20" rx="3" fill="var(--color-accent)" fill-opacity="0.3" stroke="var(--color-border)" stroke-width="1"/>
  <text x="576" y="148" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">1,18 ГиБ</text>
  <text x="16" y="182" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">состояние гибридной модели</text>
  <text x="236" y="182" text-anchor="start" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12" font-weight="400">входит в память диалогов</text>
  <rect x="530" y="168" width="32" height="20" rx="3" fill="var(--color-accent)" fill-opacity="0.3" stroke="var(--color-border)" stroke-width="1"/>
  <text x="570" y="182" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">1,00 ГиБ</text>
  <text x="16" y="216" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">рабочие буферы и служебное</text>
  <rect x="236" y="202" width="51" height="20" rx="3" fill="var(--color-link)" fill-opacity="0.45" stroke="var(--color-border)" stroke-width="1"/>
  <text x="295" y="216" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">1,59 ГиБ</text>
  <rect x="530" y="202" width="44" height="20" rx="3" fill="var(--color-link)" fill-opacity="0.45" stroke="var(--color-border)" stroke-width="1"/>
  <text x="582" y="216" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">1,37 ГиБ</text>
  <text x="16" y="250" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">записанные графы</text>
  <rect x="236" y="236" width="4" height="20" rx="3" fill="var(--color-link)" fill-opacity="0.45" stroke="var(--color-border)" stroke-width="1"/>
  <text x="248" y="250" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">0,14 ГиБ</text>
  <rect x="530" y="236" width="17" height="20" rx="3" fill="var(--color-link)" fill-opacity="0.45" stroke="var(--color-border)" stroke-width="1"/>
  <text x="555" y="250" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">0,52 ГиБ</text>
  <text x="16" y="284" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">осталось свободно</text>
  <rect x="236" y="270" width="39" height="20" rx="3" fill="var(--color-border)" fill-opacity="0.45" stroke="var(--color-border)" stroke-width="1"/>
  <text x="283" y="284" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">1,22 ГиБ</text>
  <rect x="530" y="270" width="12" height="20" rx="3" fill="var(--color-border)" fill-opacity="0.45" stroke="var(--color-border)" stroke-width="1"/>
  <text x="550" y="284" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">0,37 ГиБ</text>
  <text x="16" y="322" text-anchor="start" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">В сумме у каждого сервера 11,91 ГиБ — вся видеокарта. Модель одна и та же: Qwen3.5-4B в FP8.</text>
</svg>
</div>

Порядок, в котором серверы делят память при старте, разный:

<div style="overflow-x:auto;margin:1.5rem 0" tabindex="0" role="region">
<svg viewBox="0 0 800 306" width="100%" style="min-width:620px;max-width:800px;height:auto;display:block;margin:0 auto" role="img" aria-label="Как vLLM и SGLang распределяют видеопамять при старте" xmlns="http://www.w3.org/2000/svg">
  <defs>
    <marker id="vs-memflow-head" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
      <path d="M0 0 L10 5 L0 10 z" fill="var(--color-fg-dim)"/>
    </marker>
  </defs>
  <text x="200" y="26" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="14" font-weight="500">vLLM</text>
  <rect x="30" y="44" width="340" height="62" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-border)" stroke-width="1.5"/>
  <text x="200" y="68" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="14" font-weight="500">1. Загрузить веса</text>
  <text x="200" y="88" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">сколько займут — известно заранее</text>
  <rect x="30" y="136" width="340" height="62" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-border)" stroke-width="1.5"/>
  <text x="200" y="160" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="14" font-weight="500">2. Пробные запросы</text>
  <text x="200" y="180" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">измерить буферы и графы</text>
  <path d="M200 106 L200 136" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" marker-end="url(#vs-memflow-head)"/>
  <rect x="30" y="228" width="340" height="62" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-accent)" stroke-width="1.5"/>
  <text x="200" y="252" text-anchor="middle" fill="var(--color-accent)" font-family="var(--font-sans)" font-size="14" font-weight="500">3. Остаток — памяти диалогов</text>
  <text x="200" y="272" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">сервер считает сам</text>
  <path d="M200 198 L200 228" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" marker-end="url(#vs-memflow-head)"/>
  <text x="600" y="26" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="14" font-weight="500">SGLang</text>
  <rect x="430" y="44" width="340" height="62" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-accent)" stroke-width="1.5"/>
  <text x="600" y="68" text-anchor="middle" fill="var(--color-accent)" font-family="var(--font-sans)" font-size="14" font-weight="500">1. Доля задана заранее</text>
  <text x="600" y="88" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">--mem-fraction-static</text>
  <rect x="430" y="136" width="340" height="62" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-border)" stroke-width="1.5"/>
  <text x="600" y="160" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="14" font-weight="500">2. Внутри доли</text>
  <text x="600" y="180" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">веса, память диалогов, состояние</text>
  <path d="M600 106 L600 136" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" marker-end="url(#vs-memflow-head)"/>
  <rect x="430" y="228" width="340" height="62" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-border)" stroke-width="1.5"/>
  <text x="600" y="252" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="14" font-weight="500">3. Вне доли</text>
  <text x="600" y="272" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">буферы и графы — что осталось</text>
  <path d="M600 198 L600 228" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" marker-end="url(#vs-memflow-head)"/>
</svg>
</div>

Что из этого следует:

- **Кроме весов нужно ещё 3–4 ГиБ.** Модель, которая по размеру файлов почти равна видеопамяти, не запустится.
- **Память диалогов — это остаток** после весов, буферов и графов.
- **Ручек три:** длина диалога, число одновременных запросов, доля памяти сервера.

### vLLM: видеопамять

До версии 0.34 сервер забирал 92% видеопамяти заранее. С 0.34 он загружает веса, прогоняет пробные запросы, измеряет буферы и графы и отдаёт памяти диалогов всё, что осталось. Флаг `--gpu-memory-utilization` теперь лучше не задавать: любое значение только уменьшит память диалогов. Старый совет «не запускается — уменьшите `--gpu-memory-utilization`» устарел.

```text
Actual usage is 6.33 GiB for consumed memory (weights + non-torch),
  1.59 GiB for peak activation, and 0.14 GiB for CUDAGraph memory.
Memory after warmup: 4.17 GiB free,
  1.59 GiB kept for transient activations;
  80 KV cache blocks (1.41 GiB) fit within the requested 11.91 GiB.
```

| Флаг | Что делает |
|---|---|
| `--max-model-len` | максимальная длина диалога в токенах. По умолчанию из модели: у Qwen3.5 это 262 144 |
| `--max-num-seqs` | число одновременных запросов. По умолчанию 256, на больших серверных картах 1024 |
| `--gpu-memory-utilization` | доля видеопамяти сервера. Нужна, когда карту делят несколько программ |
| `--kv-cache-memory-bytes` | точный размер памяти диалогов |
| `--kv-cache-dtype fp8` | сжатая память диалогов: вдвое больше диалогов |

Когда память диалогов кончается, новые запросы ждут в очереди. Если не хватает уже начатым, сервер вытесняет последний принятый запрос и позже читает его промпт заново. Пользователь видит задержку, а не ошибку.

Две копии сервера на одной видеокарте: каждой `--gpu-memory-utilization 0.4`, иначе первая займёт всё.

### SGLang: видеопамять

Флаг `--mem-fraction-static` задаёт долю видеопамяти под веса и память диалогов вместе. Остальное достаётся буферам и графам. Без флага сервер считает долю сам; на карте с 12 ГБ получилось 0,63.

Как подбирать, по документации:

- при старте сервер пишет остаток свободной памяти — `available_gpu_mem`;
- на больших картах норма — 5–8 ГБ остатка;
- остаток намного больше — долю можно поднять;
- сервер падает от нехватки памяти под нагрузкой — долю нужно уменьшить.

На 12 ГБ значение по умолчанию слишком осторожное. Qwen3.5-4B в FP8 с ним не запускается:

```text
RuntimeError: Hybrid (mamba/linear-attention) state cache is too small
  to serve any requests. max_mamba_cache_size=3, mamba_ratio=5,
  resulting max_num_reqs=0. Try: (1) reduce --max-running-requests,
  (2) increase --mem-fraction-static, or (3) use GPUs with more memory.
```

С `--mem-fraction-static 0.8` запускается: четыре одновременных запроса.

| Флаг | Что делает |
|---|---|
| `--mem-fraction-static` | доля видеопамяти под веса и память диалогов |
| `--context-length` | максимальная длина диалога в токенах |
| `--max-running-requests` | число одновременных запросов |
| `--max-total-tokens` | точный размер памяти диалогов в токенах |
| `--chunked-prefill-size` | размер кусков, которыми читается длинный промпт. Меньше — меньше буферы |
| `--kv-cache-dtype fp8_e4m3` | сжатая память диалогов. Для точности нужен файл масштабов: `--quantization-param-path` |
| `--mamba-full-memory-ratio`, `--max-mamba-cache-size` | память под состояние гибридных моделей |

Когда память диалогов кончается, SGLang снимает один из выполняющихся запросов и возвращает его в очередь. В журнале: `KV cache pool is full. Retract requests.` Если это происходит часто, поднимите `--schedule-conservativeness`.

### Что не помещается в 12 ГБ

| Модель | Веса в памяти | vLLM | SGLang |
|---|---|---|---|
| Qwen3.5-4B без сжатия | 8,6 ГиБ | нет места под память диалогов | не хватило 2,57 ГБ под состояние |
| Qwen3.5-9B, 4 бита | 8,4–9,5 ГиБ | то же | то же |

Сжатие до 4 бит уменьшает только основные слои. Блок разбора картинок и таблицы токенов остаются прежними, поэтому модель на 9,7 млрд параметров занимает больше 8 ГиБ.

Отказ vLLM:

```text
Memory after warmup: 0.91 GiB free, 1.59 GiB kept for transient activations;
  0 KV cache blocks (0.0 GiB) fit within the requested 11.91 GiB.
ValueError: No available memory for the cache blocks. [...]
  decrease `max_model_len` or `max_num_seqs`,
  or the model needs a device with more memory.
```

Отказ SGLang:

```text
Load weight end. avail mem=1.37 GB, mem usage=9.35 GB.
RuntimeError: Not enough GPU memory for hybrid (mamba/linear-attention)
  state cache. Computed max_mamba_cache_size=-27
  (total_rest_memory=-2.57 GB, mamba_cache_per_req=49.12 MB).
```

vLLM сообщает о нехватке памяти через 2–4 минуты, в конце прогрева. SGLang — через 20–30 секунд, сразу после загрузки весов.

У vLLM с гибридной моделью бывает ещё одна ошибка при старте: значение `--max-num-seqs` по умолчанию слишком велико.

```text
ValueError: max_num_seqs (256) exceeds available Mamba cache blocks (42).
  Please lower max_num_seqs to at most 42 or increase gpu_memory_utilization.
```

## Форматы моделей и квантование

Оба сервера работают с форматом safetensors с Hugging Face. GGUF, привычный по llama.cpp и Ollama, — не их формат. Что такое квантование — в [разделе о нём](/ru/llm-inference-engines/#Квантование).

Сжатую заранее модель оба сервера распознают сами, без флагов.

### vLLM: форматы и квантование

- **Источники:** Hugging Face, папка на диске, ModelScope (`VLLM_USE_MODELSCOPE=True`), объектное хранилище (`vllm serve s3://bucket/model --load-format runai_streamer`).
- **Готовые сжатые модели:** FP8, AWQ, GPTQ, INT8, INT4, NVFP4, MXFP4, compressed-tensors, NVIDIA ModelOpt, AMD Quark.
- **Сжатие при загрузке:** `--quantization fp8_per_tensor`.
- **GGUF:** отдельный плагин `vllm-gguf-plugin`, экспериментальный.
- **bitsandbytes:** отдельный плагин `vllm-bnb-plugin`.
- **Сжать свою модель:** [LLM Compressor](https://github.com/vllm-project/llm-compressor).
- **LoRA-адаптеры:** `--enable-lora --lora-modules sql=путь`. Клиент выбирает адаптер полем `model`; запросы к разным адаптерам идут в одном батче.

### SGLang: форматы и квантование

- **Источники:** Hugging Face, папка на диске, ModelScope (`SGLANG_USE_MODELSCOPE=true`), адреса `s3://`, `gs://`, `az://`.
- **Готовые сжатые модели:** те же основные форматы. Флаг `--quantization` к уже сжатой модели добавлять нельзя.
- **Сжатие при загрузке:** `--quantization fp8`. Сжатие через torchao из версии 0.5.23 убрано.
- **GGUF:** формат загрузки `gguf` есть, список поддерживаемых архитектур документация не приводит.
- **LoRA-адаптеры:** `--enable-lora --lora-paths sql=путь`. Загружаются и выгружаются на ходу: `/load_lora_adapter`, `/unload_lora_adapter`. В запросе: `"model": "базовая-модель:адаптер"`.

Скорость на стенде, один пользователь:

| Модель | vLLM | SGLang |
|---|---|---|
| Qwen3.5-4B, FP8 | 84 токена/с | 56–60 токенов/с |
| Qwen3.5-2B без сжатия | 110 токенов/с | 109 токенов/с |

Вычисления в FP8 для этой модели у vLLM быстрее. На несжатой модели разницы нет.

## Настройка

Настройки задаются флагами, файлом YAML или переменными окружения. Если значение есть и во флаге, и в файле, побеждает флаг.

Для рассуждающих моделей и вызова функций нужны два разборщика, свои для каждого семейства моделей:

- **reasoning parser** отделяет рассуждения от ответа;
- **tool call parser** превращает текст модели в вызов функции с аргументами.

### vLLM: настройка

```yaml title="vllm/config.yaml"
# vLLM 0.34 — все настройки сервера в одном файле
model: RedHatAI/Qwen3.5-4B-FP8-dynamic
# Под этим именем модель видят клиенты
served-model-name: qwen3.5-4b
host: 0.0.0.0
port: 8000

# Память: самый длинный диалог и число одновременных запросов
max-model-len: 16384
max-num-seqs: 16

# Отделять рассуждения модели от ответа
reasoning-parser: qwen3
# Превращать текст модели в вызовы функций
enable-auto-tool-choice: true
tool-call-parser: qwen3_xml

# Показывать в ответе, сколько токенов промпта взято из кэша
enable-prompt-tokens-details: true
# Возвращать идентификатор запроса в заголовке X-Request-Id
enable-request-id-headers: true
```

```bash
docker run --gpus all --ipc=host -p 8000:8000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -v vllm-cache:/root/.cache/vllm \
  -v ./vllm:/lab/vllm \
  -e VLLM_API_KEY=sk-lab-123 \
  vllm/vllm-openai:v0.34.0 \
  --config /lab/vllm/config.yaml
```

- **Справка:** `vllm serve --help=all` — всё, `--help=max-num-seqs` — один флаг.
- **Вложенные настройки** — через точку: `--logging-config.formatter json`.
- **Короткая запись чисел:** `--max-model-len 16K` — это 16 384. Заглавная `K` — 1024, строчная `k` — 1000.
- **Параметры генерации из модели.** Сервер применяет `generation_config.json` из папки модели. Отключается флагом `--generation-config vllm`.
- **Переменные окружения:** `HF_TOKEN`, `VLLM_API_KEY`, `VLLM_LOGGING_LEVEL`, `VLLM_NO_USAGE_STATS=1` (отказ от телеметрии).
- **Kubernetes:** не называйте сервис `vllm`. Kubernetes создаст переменные с префиксом `VLLM_`, и сервер примет их за свои настройки.

### SGLang: настройка

```yaml title="sglang/config.yaml"
# SGLang 0.5.23 — настройки сервера в одном файле.
# Модель задаётся в командной строке: sglang serve <модель> --config config.yaml
# Под этим именем модель видят клиенты
served-model-name: qwen3.5-4b
host: 0.0.0.0
port: 30000

# Память: самый длинный диалог и доля видеопамяти под веса и кэш диалогов
context-length: 16384
mem-fraction-static: 0.8

# Отделять рассуждения модели от ответа
reasoning-parser: qwen3
# Превращать текст модели в вызовы функций
tool-call-parser: qwen3_coder

# Отдавать метрики для Prometheus по адресу /metrics
enable-metrics: true
# Показывать в ответе, сколько токенов промпта взято из кэша
enable-cache-report: true
```

```bash
docker run --gpus all --ipc=host --shm-size 16g -p 30000:30000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -v ./sglang:/lab/sglang \
  lmsysorg/sglang:v0.5.23-runtime \
  sglang serve RedHatAI/Qwen3.5-4B-FP8-dynamic \
  --config /lab/sglang/config.yaml --api-key sk-lab-123
```

- **Модель — только в командной строке.** С `model-path` в файле и без модели в команде `sglang serve` падает: `Error: --model-path is required`.
- **Ключ доступа — только флагом** `--api-key`.
- **Команда запуска:** `sglang serve`. Прежняя `python -m sglang.launch_server` ещё работает и встречается в большинстве инструкций.
- **Метрики выключены** без `--enable-metrics`.
- **Число токенов из кэша в ответе** — только с `--enable-cache-report`.
- **Имена разборщиков другие:** для той же модели в vLLM `qwen3_xml`, здесь `qwen3_coder`.
- **Справка надёжнее документации:** 91 флаг в таблице документации не описан. Смотрите `sglang serve --help`.
- **Переменные окружения:** `HF_TOKEN`, `SGLANG_CACHE_DIR` (папка скомпилированных ядер, подключите её томом), `SGLANG_LOGGING_CONFIG_PATH` (свой формат журнала).

## API

Оба сервера повторяют API OpenAI. Библиотека `openai` работает с ними без изменений: меняется адрес. Примеры ниже запускались с обоими серверами без правок.

```bash
# vLLM
export BASE_URL=http://localhost:8000/v1 API_KEY=sk-lab-123
# SGLang
export BASE_URL=http://localhost:30000/v1 API_KEY=sk-lab-123
```

**Обычный запрос.** Рассуждения приходят отдельно от ответа:

```python title="chat.py"
import os

from openai import OpenAI

# Один и тот же код работает с обоими серверами: меняется только адрес.
# vLLM: http://localhost:8000/v1, SGLang: http://localhost:30000/v1
client = OpenAI(
    base_url=os.environ["BASE_URL"],
    api_key=os.environ["API_KEY"],
)

response = client.chat.completions.create(
    model="qwen3.5-4b",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {
            "role": "user",
            "content": "What is a KV cache in LLM inference? Answer in two sentences.",
        },
    ],
    max_tokens=2048,
)

message = response.choices[0].message
# Рассуждения приходят отдельным полем: в vLLM оно называется reasoning,
# в SGLang — reasoning_content
reasoning = getattr(message, "reasoning", None) or getattr(message, "reasoning_content", None)
print("REASONING:", (reasoning or "")[:200].replace("\n", " "), "...")
print("ANSWER:", message.content.strip())
print("USAGE:", response.usage.prompt_tokens, "+", response.usage.completion_tokens)
```

```text
REASONING: Thinking Process:  1.  **Analyze the Request:**     *   Topic: KV cache ...
ANSWER: A KV cache stores the attention key-value pairs for all previous tokens,
  allowing the model to retrieve context without re-computing layer activations.
  This reuse significantly reduces the computational cost and latency of
  autoregressive inference, particularly when generating long sequences of text.
USAGE: 36 + 1565
```

Ответ из двух предложений стоил 1565 токенов: почти всё ушло на рассуждения. С маленьким `max_tokens` рассуждающая модель не доходит до ответа, и `content` приходит пустым.

**Поток, отключение рассуждений, замер TTFT:**

```python title="stream.py"
import os
import time

from openai import OpenAI

client = OpenAI(base_url=os.environ["BASE_URL"], api_key=os.environ["API_KEY"])

started = time.perf_counter()
first_token_at = None
tokens = 0

stream = client.chat.completions.create(
    model="qwen3.5-4b",
    messages=[
        {
            "role": "user",
            "content": "Explain in three sentences why one GPU can serve many LLM requests at once.",
        }
    ],
    max_tokens=300,
    stream=True,
    # Попросить сервер прислать в конце потока счётчики токенов
    stream_options={"include_usage": True},
    # Выключить рассуждения: параметр уходит в шаблон чата модели
    extra_body={"chat_template_kwargs": {"enable_thinking": False}},
)

for chunk in stream:
    if chunk.usage:
        tokens = chunk.usage.completion_tokens
    if not chunk.choices:
        continue
    piece = chunk.choices[0].delta.content
    if piece:
        if first_token_at is None:
            first_token_at = time.perf_counter()
        print(piece, end="", flush=True)

total = time.perf_counter() - started
ttft = first_token_at - started
speed = tokens / (total - ttft)
print(f"\n\nTTFT: {ttft * 1000:.0f} ms, tokens: {tokens}, speed: {speed:.0f} tokens/s")
```

```text
vLLM:    TTFT: 71 ms, tokens: 93, speed: 84 tokens/s
SGLang:  TTFT: 82 ms, tokens: 93, speed: 56 tokens/s
```

**Вызов функций.** Модель называет функцию и аргументы, вызывает её ваш код:

```python title="tools.py"
import json
import os

from openai import OpenAI

client = OpenAI(base_url=os.environ["BASE_URL"], api_key=os.environ["API_KEY"])

# Описание функции, которую модели разрешено вызвать
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_gpu_memory",
            "description": "Returns used and total memory of a GPU in megabytes.",
            "parameters": {
                "type": "object",
                "properties": {
                    "gpu_index": {
                        "type": "integer",
                        "description": "Index of the GPU, starting from 0",
                    },
                },
                "required": ["gpu_index"],
            },
        },
    }
]

messages = [{"role": "user", "content": "How much memory is free on GPU 0?"}]

# 1. Модель решает, что нужна функция, и возвращает её имя и аргументы
first = client.chat.completions.create(
    model="qwen3.5-4b",
    messages=messages,
    tools=tools,
    max_tokens=1024,
)
call = first.choices[0].message.tool_calls[0]
print("CALL:", call.function.name, call.function.arguments)

# 2. Функцию выполняет наш код, а не сервер; здесь ответ подставлен вручную
result = {"used_mb": 9896, "total_mb": 12227}
messages.append(first.choices[0].message)
messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})

# 3. Модель получает результат и отвечает человеку
second = client.chat.completions.create(
    model="qwen3.5-4b",
    messages=messages,
    tools=tools,
    max_tokens=1024,
)
print("ANSWER:", second.choices[0].message.content.strip())
```

```text
CALL: get_gpu_memory {"gpu_index": 0}
ANSWER: GPU 0 has approximately **2.3 GB** free memory.
```

**Ответ по схеме.** Сервер запрещает модели токены, нарушающие схему, и ответ всегда получается правильным JSON:

```python title="structured.py"
import json
import os

from openai import OpenAI

client = OpenAI(base_url=os.environ["BASE_URL"], api_key=os.environ["API_KEY"])

# Схема, которой обязан соответствовать ответ
schema = {
    "type": "object",
    "properties": {
        "component": {"type": "string", "enum": ["memory", "network", "model", "other"]},
        "severity": {"type": "string", "enum": ["low", "medium", "high"]},
        "summary": {"type": "string"},
    },
    "required": ["component", "severity", "summary"],
    "additionalProperties": False,
}

log_line = "RuntimeError: Not enough GPU memory for hybrid (mamba/linear-attention) state cache."

response = client.chat.completions.create(
    model="qwen3.5-4b",
    messages=[
        {
            "role": "system",
            "content": "Classify the log line of an inference server. Keep the summary under 20 words.",
        },
        {"role": "user", "content": log_line},
    ],
    # Сервер не даст модели выбрать токен, который нарушает схему
    response_format={
        "type": "json_schema",
        "json_schema": {"name": "incident", "schema": schema, "strict": True},
    },
    max_tokens=300,
    extra_body={"chat_template_kwargs": {"enable_thinking": False}},
)

incident = json.loads(response.choices[0].message.content)
print(incident)
```

```text
{'component': 'memory', 'severity': 'high',
 'summary': 'GPU memory insufficient for hybrid attention cache.'}
```

**Картинка на входе:**

```python title="vision.py"
import base64
import os

from openai import OpenAI

client = OpenAI(base_url=os.environ["BASE_URL"], api_key=os.environ["API_KEY"])

# Картинка уходит в запросе в виде строки base64
with open("dashboard.png", "rb") as file:
    image = base64.b64encode(file.read()).decode()

response = client.chat.completions.create(
    model="qwen3.5-4b",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{image}"}},
                {"type": "text", "text": "What does this picture show? Answer in two sentences."},
            ],
        }
    ],
    max_tokens=200,
    extra_body={"chat_template_kwargs": {"enable_thinking": False}},
)

print(response.choices[0].message.content.strip())
print("prompt tokens:", response.usage.prompt_tokens)
```

Картинка 1200×630 занимает 785 токенов промпта в обоих серверах.

### vLLM: что есть кроме API OpenAI

- **Responses API:** `/v1/responses`.
- **Anthropic Messages API:** `/v1/messages`. Так подключается Claude Code ([инструкция](https://docs.vllm.ai/en/latest/serving/integrations/claude_code/)).
- **Эмбеддинги, переранжирование, распознавание речи.**
- **Токенизатор:** `/tokenize`, `/detokenize`.
- **gRPC:** `vllm serve --grpc`.
- **Поле с рассуждениями:** `reasoning`.
- **Заголовок `X-Request-Id`:** сервер принимает идентификатор запроса от клиента и возвращает его в ответе.
- **Ключ — только в `Authorization: Bearer`.** Заголовок `x-api-key`, который шлют клиенты Anthropic, не принимается: ответ 401.

### SGLang: что есть кроме API OpenAI

- **Responses API и Anthropic Messages API** — на тех же адресах. `x-api-key` тоже не принимается.
- **API Ollama:** `/api/chat`, `/api/generate`, `/api/tags`.
- **Эмбеддинги, переранжирование, распознавание речи, токенизатор.**
- **Запуск без HTTP:** `sgl.Engine(model_path=...)` в коде на Python. У vLLM для этого класс `LLM`.
- **Поле с рассуждениями:** `reasoning_content`. Это единственное место, где клиенту нужно знать, с каким сервером он говорит.
- **Собственный API** `/generate` — сырой текст без шаблона чата:

```bash
curl http://localhost:30000/generate \
  -H "Authorization: Bearer sk-lab-123" -H "Content-Type: application/json" \
  -d '{"text": "The capital of Bulgaria is",
       "sampling_params": {"max_new_tokens": 8, "temperature": 0}}'
```

```json
{
  "text": " Sofia. Sofia is the largest city in",
  "meta_info": {
    "finish_reason": {"type": "length", "length": 8},
    "prompt_tokens": 5,
    "completion_tokens": 8,
    "cached_tokens": 0
  }
}
```

Ответ сокращён: в настоящем ещё два десятка служебных полей.

## Сессии и состояние

Оба сервера не хранят диалоги. Клиент в каждом запросе присылает всю историю.

Чтобы не читать историю заново на каждом ходе, работает [кэш префиксов](/ru/llm-inference-engines/#Кэш-префиксов): сервер сохраняет память диалога после ответа и берёт из неё совпавшее начало следующего запроса. Кэш включён по умолчанию и не привязан к пользователю: совпадение ищется по тексту.

Диалог из четырёх ходов с системным промптом на 2000 токенов:

```python title="cache.py"
import os
import time

from openai import OpenAI

client = OpenAI(base_url=os.environ["BASE_URL"], api_key=os.environ["API_KEY"])

# Длинный системный промпт: около 2000 токенов правил, одинаковых для всех запросов
rules = "\n".join(
    f"Rule {n}: when the user asks about topic {n}, answer politely and mention the number {n * 7}."
    for n in range(1, 81)
)
messages = [{"role": "system", "content": "You are a support assistant.\n" + rules}]

questions = [
    "What does rule 5 say?",
    "And rule 12?",
    "Which rule mentions the number 140?",
    "Thanks. Summarize our conversation in one sentence.",
]

for turn, question in enumerate(questions, start=1):
    messages.append({"role": "user", "content": question})

    started = time.perf_counter()
    first_token_at = None
    answer = ""
    usage = None
    stream = client.chat.completions.create(
        model="qwen3.5-4b",
        messages=messages,
        max_tokens=120,
        stream=True,
        stream_options={"include_usage": True},
        extra_body={"chat_template_kwargs": {"enable_thinking": False}},
    )
    for chunk in stream:
        if chunk.usage:
            usage = chunk.usage
        if chunk.choices and chunk.choices[0].delta.content:
            if first_token_at is None:
                first_token_at = time.perf_counter()
            answer += chunk.choices[0].delta.content

    # Сервер не помнит диалог: историю каждый раз присылает клиент
    messages.append({"role": "assistant", "content": answer})

    details = usage.prompt_tokens_details
    cached = details.cached_tokens if details else 0
    ttft = (first_token_at - started) * 1000
    prompt = usage.prompt_tokens
    print(f"turn {turn}: prompt {prompt} tokens, from cache {cached}, TTFT {ttft:.0f} ms")
```

vLLM:

```text
turn 1: prompt 2157 tokens, from cache 0, TTFT 339 ms
turn 2: prompt 2202 tokens, from cache 1728, TTFT 84 ms
turn 3: prompt 2253 tokens, from cache 1728, TTFT 155 ms
turn 4: prompt 2320 tokens, from cache 1728, TTFT 103 ms
```

SGLang:

```text
turn 1: prompt 2157 tokens, from cache 0, TTFT 341 ms
turn 2: prompt 2210 tokens, from cache 2112, TTFT 61 ms
turn 3: prompt 2266 tokens, from cache 2176, TTFT 55 ms
turn 4: prompt 2323 tokens, from cache 2240, TTFT 48 ms
```

Со второго хода оба отвечают в несколько раз быстрее:

<div style="overflow-x:auto;margin:1.5rem 0" tabindex="0" role="region">
<svg viewBox="0 0 780 232" width="100%" style="min-width:620px;max-width:780px;height:auto;display:block;margin:0 auto" role="img" aria-label="Время до первого токена по ходам диалога у vLLM и SGLang" xmlns="http://www.w3.org/2000/svg">
  <defs>
    <marker id="vs-turns-head" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
      <path d="M0 0 L10 5 L0 10 z" fill="var(--color-fg-dim)"/>
    </marker>
  </defs>
  <path d="M80 200 L730 200" stroke="var(--color-border)" stroke-width="1.5"/>
  <rect x="110" y="51" width="54" height="149" rx="2" fill="var(--color-accent)" fill-opacity="0.6" stroke="var(--color-border)" stroke-width="1"/>
  <text x="137" y="45" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">339</text>
  <rect x="170" y="50" width="54" height="150" rx="2" fill="var(--color-link)" fill-opacity="0.55" stroke="var(--color-border)" stroke-width="1"/>
  <text x="197" y="44" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">341</text>
  <text x="167" y="220" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">ход 1</text>
  <rect x="270" y="163" width="54" height="37" rx="2" fill="var(--color-accent)" fill-opacity="0.6" stroke="var(--color-border)" stroke-width="1"/>
  <text x="297" y="157" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">84</text>
  <rect x="330" y="173" width="54" height="27" rx="2" fill="var(--color-link)" fill-opacity="0.55" stroke="var(--color-border)" stroke-width="1"/>
  <text x="357" y="167" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">61</text>
  <text x="327" y="220" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">ход 2</text>
  <rect x="430" y="132" width="54" height="68" rx="2" fill="var(--color-accent)" fill-opacity="0.6" stroke="var(--color-border)" stroke-width="1"/>
  <text x="457" y="126" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">155</text>
  <rect x="490" y="176" width="54" height="24" rx="2" fill="var(--color-link)" fill-opacity="0.55" stroke="var(--color-border)" stroke-width="1"/>
  <text x="517" y="170" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">55</text>
  <text x="487" y="220" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">ход 3</text>
  <rect x="590" y="155" width="54" height="45" rx="2" fill="var(--color-accent)" fill-opacity="0.6" stroke="var(--color-border)" stroke-width="1"/>
  <text x="617" y="149" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">103</text>
  <rect x="650" y="179" width="54" height="21" rx="2" fill="var(--color-link)" fill-opacity="0.55" stroke="var(--color-border)" stroke-width="1"/>
  <text x="677" y="173" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">48</text>
  <text x="647" y="220" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">ход 4</text>
  <rect x="110" y="14" width="14" height="14" rx="2" fill="var(--color-accent)" fill-opacity="0.6" stroke="var(--color-border)"/>
  <text x="132" y="26" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12.5" font-weight="400">vLLM</text>
  <rect x="200" y="14" width="14" height="14" rx="2" fill="var(--color-link)" fill-opacity="0.55" stroke="var(--color-border)"/>
  <text x="222" y="26" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12.5" font-weight="400">SGLang</text>
  <text x="730" y="26" text-anchor="end" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">время до первого токена, мс</text>
  <path d="M0 0 L0 0" fill="none" stroke="none"/>
</svg>
</div>

SGLang берёт из кэша почти всё, vLLM — 1728 токенов на каждом ходе:

<div style="overflow-x:auto;margin:1.5rem 0" tabindex="0" role="region">
<svg viewBox="0 0 780 252" width="100%" style="min-width:620px;max-width:780px;height:auto;display:block;margin:0 auto" role="img" aria-label="Второй ход диалога: сколько токенов промпта каждый сервер взял из кэша" xmlns="http://www.w3.org/2000/svg">
  <defs>
    <marker id="vs-prefix-head" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
      <path d="M0 0 L10 5 L0 10 z" fill="var(--color-fg-dim)"/>
    </marker>
  </defs>
  <text x="20" y="30" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="14" font-weight="500">vLLM</text>
  <text x="80" y="30" text-anchor="start" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">кэш хранится блоками, у этой модели блок — 576 токенов</text>
  <rect x="20" y="42" width="194" height="46" fill="var(--color-accent)" fill-opacity="0.32" stroke="var(--color-border)" stroke-width="1"/>
  <text x="117" y="69" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12.5" font-weight="400">576</text>
  <rect x="214" y="42" width="194" height="46" fill="var(--color-accent)" fill-opacity="0.32" stroke="var(--color-border)" stroke-width="1"/>
  <text x="311" y="69" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12.5" font-weight="400">576</text>
  <rect x="407" y="42" width="194" height="46" fill="var(--color-accent)" fill-opacity="0.32" stroke="var(--color-border)" stroke-width="1"/>
  <text x="504" y="69" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12.5" font-weight="400">576</text>
  <rect x="601" y="42" width="159" height="46" fill="var(--color-link)" fill-opacity="0.3" stroke="var(--color-border)" stroke-width="1"/>
  <text x="680.5" y="69" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12.5" font-weight="400">474</text>
  <text x="20" y="108" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">из кэша: 1728 токенов из 2202</text>
  <text x="760" y="108" text-anchor="end" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">считается заново: 474</text>
  <text x="20" y="158" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="14" font-weight="500">SGLang</text>
  <text x="96" y="158" text-anchor="start" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">кэш — дерево общих начал, совпадение ищется почти до токена</text>
  <rect x="20" y="170" width="707" height="46" fill="var(--color-accent)" fill-opacity="0.32" stroke="var(--color-border)" stroke-width="1"/>
  <text x="373.5" y="197" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12.5" font-weight="400">2112</text>
  <rect x="727" y="170" width="33" height="46" fill="var(--color-link)" fill-opacity="0.3" stroke="var(--color-border)" stroke-width="1"/>
  <text x="20" y="236" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">из кэша: 2112 токенов из 2210</text>
  <text x="760" y="236" text-anchor="end" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">считается заново: 98</text>
</svg>
</div>

### vLLM: кэш и состояние

**Устройство.** Память диалогов нарезана на блоки. Сервер считает хэш каждого заполненного блока вместе со всем, что было до него, и сравнивает новый запрос с кэшем блок за блоком. Незаполненный блок в кэш не попадает.

**Размер блока** — 64 токена (до версии 0.34 — 16). У гибридных моделей больше: у Qwen3.5 — 576 токенов. Отсюда 1728 в примере: это три блока, а до четвёртого диалог не дорос.

**Следствие.** Общее начало короче блока не кэшируется. При общем системном промпте на 450 токенов vLLM с Qwen3.5 показал попадание в кэш 4%, SGLang на той же нагрузке — 87%. У обычных моделей блок в девять раз меньше, и такого разрыва нет.

**Как увидеть работу кэша:**

- в ответе: `usage.prompt_tokens_details.cached_tokens` (флаг `--enable-prompt-tokens-details`);
- в метриках: `vllm:prefix_cache_hits_total`, `vllm:prefix_cache_queries_total`;
- в журнале: `Prefix cache hit rate`, каждые десять секунд.

**Изоляция клиентов.** По времени ответа можно понять, присылал ли кто-то такое же начало запроса. Если клиенты не должны ничего знать друг о друге, добавьте в запросы поле `cache_salt`, своё для каждого клиента. Запросы с разной солью не делят блоки.

**Хранение ответов на сервере** (параметр `previous_response_id` в Responses API) выключено:

```text
404 invalid_request_error, param: response_id
Response with id 'resp_123' not found.
```

Включается переменной `VLLM_ENABLE_RESPONSES_API_STORE=1`. Ответы лежат в памяти процесса, никогда не удаляются и пропадают при перезапуске. Для продакшена не годится: историю хранит клиент или слой перед сервером.

### SGLang: кэш и состояние

**Устройство.** Кэш — дерево общих начал (radix-дерево). Для нового запроса ищется самое длинное совпадение. Совпадение точнее, чем блоками: в примере 2112 токенов из 2210, и число растёт с каждым ходом. Когда память кончается, удаляются ветки, к которым дольше всего не обращались (`--radix-eviction-policy`).

**Как увидеть работу кэша:**

- в ответе: то же поле `cached_tokens` (флаг `--enable-cache-report`);
- в метриках: `sglang:cache_hit_rate`, `sglang:cached_tokens_total`;
- в журнале, в строке каждого прочитанного промпта:

```text
Prefill batch, #new-seq: 1, #new-token: 69, #cached-token: 448,
  full token usage: 0.02, mamba usage: 0.80, #running-req: 3, #queue-req: 1
```

Из 517 токенов промпта 448 взяты из кэша.

**Защита кэша диалога:** флаг `--enable-session-radix-cache` и поле `session_id` в запросе. Ветки этого диалога удаляются в последнюю очередь. Историю по-прежнему присылает клиент.

**Сессии на сервере.** Через собственный API можно открыть сессию (`/open_session`) и присылать только новый текст: сервер допишет его к хранимому контексту. Сделано для обучения с подкреплением и агентов, работает только через `/generate`. На стенде не запускалось.

**Хранение ответов на сервере** тоже выключено:

```text
400 invalid_request_error, param: previous_response_id
Response store is disabled. Stateful Responses require
  --enable-response-store on a standalone server;
  response storage is unavailable in PD mode.
```

С `--enable-response-store` включается. Ограничения те же, что у vLLM: память процесса, без срока хранения, после перезапуска пусто.

## Сеть и безопасность

Ни один из двух серверов не рассчитан на то, чтобы стоять в интернете без защиты. Ключ доступа есть у обоих, но закрывает не всё. Перед сервером ставят обратный прокси и пропускают наружу только нужные адреса.

<div style="overflow-x:auto;margin:1.5rem 0" tabindex="0" role="region">
<svg viewBox="0 0 800 386" width="100%" style="min-width:620px;max-width:800px;height:auto;display:block;margin:0 auto" role="img" aria-label="Обвязка сервера моделей: прокси, маршрутизатор, копии сервера, метрики и трассы" xmlns="http://www.w3.org/2000/svg">
  <defs>
    <marker id="vs-network-head" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
      <path d="M0 0 L10 5 L0 10 z" fill="var(--color-fg-dim)"/>
    </marker>
  </defs>
  <rect x="20" y="96" width="130" height="84" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-link)" stroke-width="1.5"/>
  <text x="85" y="120" text-anchor="middle" fill="var(--color-link)" font-family="var(--font-sans)" font-size="14" font-weight="500">клиенты</text>
  <text x="85" y="140" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">приложения,</text>
  <text x="85" y="157" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">агенты</text>
  <rect x="196" y="96" width="164" height="84" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-border)" stroke-width="1.5"/>
  <text x="278" y="120" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="14" font-weight="500">прокси</text>
  <text x="278" y="140" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">TLS, ключи, лимиты,</text>
  <text x="278" y="157" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">только /v1/</text>
  <rect x="406" y="96" width="164" height="84" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-border)" stroke-width="1.5"/>
  <text x="488" y="120" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="14" font-weight="500">маршрутизатор</text>
  <text x="488" y="140" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">шлёт запрос туда,</text>
  <text x="488" y="157" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">где его начало в кэше</text>
  <rect x="624" y="30" width="156" height="84" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-accent)" stroke-width="1.5"/>
  <text x="702" y="54" text-anchor="middle" fill="var(--color-accent)" font-family="var(--font-sans)" font-size="14" font-weight="500">сервер модели 1</text>
  <text x="702" y="74" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">vLLM / SGLang</text>
  <text x="702" y="91" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">своя видеокарта</text>
  <rect x="624" y="162" width="156" height="84" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-accent)" stroke-width="1.5"/>
  <text x="702" y="186" text-anchor="middle" fill="var(--color-accent)" font-family="var(--font-sans)" font-size="14" font-weight="500">сервер модели 2</text>
  <text x="702" y="206" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">vLLM / SGLang</text>
  <text x="702" y="223" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">своя видеокарта</text>
  <path d="M150 138 L196 138" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" marker-end="url(#vs-network-head)"/>
  <path d="M360 138 L406 138" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" marker-end="url(#vs-network-head)"/>
  <path d="M570 124 L597 124 L597 72 L624 72" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" marker-end="url(#vs-network-head)"/>
  <path d="M570 152 L597 152 L597 204 L624 204" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" marker-end="url(#vs-network-head)"/>
  <rect x="196" y="296" width="164" height="72" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-border)" stroke-width="1.5" stroke-dasharray="4 4"/>
  <text x="278" y="320" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="14" font-weight="500">Prometheus</text>
  <text x="278" y="340" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">опрашивает /metrics</text>
  <rect x="20" y="296" width="130" height="72" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-border)" stroke-width="1.5" stroke-dasharray="4 4"/>
  <text x="85" y="320" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="14" font-weight="500">Grafana</text>
  <text x="85" y="340" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">графики</text>
  <rect x="406" y="296" width="164" height="72" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-border)" stroke-width="1.5" stroke-dasharray="4 4"/>
  <text x="488" y="320" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="14" font-weight="500">Jaeger</text>
  <text x="488" y="340" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">трассы запросов</text>
  <path d="M196 332 L150 332" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" stroke-dasharray="5 4" marker-end="url(#vs-network-head)"/>
  <path d="M702 246 L702 272 L278 272 L278 296" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" stroke-dasharray="5 4" marker-end="url(#vs-network-head)"/>
  <path d="M740 246 L740 332 L570 332" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" stroke-dasharray="5 4" marker-end="url(#vs-network-head)"/>
  <text x="600" y="266" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12" font-weight="400">метрики</text>
  <text x="656" y="326" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12" font-weight="400">трассы</text>
</svg>
</div>

- **Прокси:** TLS, ключи, ограничение числа запросов, список разрешённых адресов.
- **Маршрутизатор:** выбирает копию сервера (следующий раздел).
- **Серверы моделей и мониторинг** — во внутренней сети.

Настройка nginx для одного сервера:

```nginx title="nginx/vllm.conf"
upstream llm {
    server vllm:8000;
    # Держать соединения с сервером модели открытыми
    keepalive 32;
}

server {
    listen 80;
    # Запросы с картинками бывают большими
    client_max_body_size 20m;

    # Наружу открыт только API для клиентов
    location /v1/ {
        proxy_pass http://llm;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        # Один идентификатор запроса в журналах прокси и сервера модели
        proxy_set_header X-Request-Id $request_id;
        # Без этого прокси копит ответ и отдаёт его одним куском
        proxy_buffering off;
        # Длинный ответ может идти минуты
        proxy_read_timeout 600s;
    }

    # Проверка живости для балансировщика
    location = /health {
        proxy_pass http://llm;
        access_log off;
    }

    # Всё остальное, включая /metrics, /invocations и /docs, снаружи недоступно
    location / {
        return 404;
    }
}
```

- `proxy_buffering off` — иначе вместо текста по словам пользователь получит паузу и весь ответ разом.
- `proxy_read_timeout 600s` — по умолчанию nginx рвёт соединение после 60 секунд тишины.
- `location / { return 404; }` — наружу выходит только перечисленное явно.
- Для продакшена добавьте `listen 443 ssl` и сертификаты. Для SGLang замените адрес на `sglang:30000`.

Что отвечает сервер на запрос **без ключа**, когда ключ задан:

| Адрес | vLLM | SGLang |
|---|---|---|
| `/health` | 200 | 200 |
| `/metrics` | 200 | 200 |
| `/docs`, `/openapi.json` | 200 | 401 |
| `/version` | 200 | — |
| `/v1/models`, `/v1/chat/completions` | 401 | 401 |
| `POST /invocations` (генерация) | 200 | — |
| `POST /tokenize` | 200 | 401 |
| сведения о сервере, сброс кэша | — | 401 |

### vLLM: сеть и безопасность

- **Адрес и порт:** `--host`, `--port` (по умолчанию все интерфейсы, 8000), `--uds` для сокета Unix, `--root-path` для прокси не в корне сайта.
- **Ключ:** `--api-key` или `VLLM_API_KEY`. Можно несколько: `--api-key k1 k2`.
- **Ключ закрывает только `/v1`** и несколько служебных префиксов.
- **`/invocations` генерирует без ключа.** Адрес сделан для AWS SageMaker и принимает те же запросы, что `/v1/chat/completions`:

```bash
curl -X POST http://localhost:8000/invocations \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen3.5-4b",
       "messages": [{"role": "user", "content": "Say OK"}],
       "max_tokens": 5,
       "chat_template_kwargs": {"enable_thinking": false}}'
```

```json
{
  "id": "chatcmpl-ab039d14c5d03cbf",
  "object": "chat.completion",
  "model": "qwen3.5-4b",
  "choices": [{"index": 0, "message": {"role": "assistant", "content": "OK"}}]
}
```

  Это задокументированное поведение: страница о безопасности в документации vLLM перечисляет `/invocations` среди незащищённых адресов. Наружу — только через прокси.

- **TLS:** `--ssl-keyfile`, `--ssl-certfile`, `--enable-ssl-refresh` (перечитывать сертификаты), `--ssl-cert-reqs` (проверять сертификат клиента).
- **CORS:** с версии 0.32 запросы с чужих сайтов запрещены. Разрешённые сайты — `--allowed-origins`.
- **Связь между узлами** не шифруется. Узлы держат в изолированной сети.
- **Картинки по ссылкам:** сервер сам скачивает картинку по адресу из запроса, и так его можно направить на внутренние адреса сети. Ограничение — `--allowed-media-domains`.
- **Телеметрия:** сервер отправляет разработчикам анонимную статистику (видеокарта, архитектура модели, версия, часть настроек; текстов запросов нет). Отключается `VLLM_NO_USAGE_STATS=1` или `DO_NOT_TRACK=1`.

### SGLang: сеть и безопасность

- **Адрес и порт:** `--host`, `--port`. По умолчанию `127.0.0.1:30000` — только с той же машины.
- **Два ключа:** `--api-key` для клиентов, `--admin-api-key` для управления (обновление весов, сброс кэша, сведения о сервере).
- **Без ключа открыты только** проверки состояния и метрики.
- **`/get_server_info` отдаёт ключ.** В ответе все настройки сервера, включая `api_key` открытым текстом. Запрос требует ключа, но каждый клиент с ключом видит все настройки. С `--admin-api-key` адрес закрывается для клиентов.
- **Без `--api-key` открыто всё:** все 108 операций, включая загрузку адаптеров и обновление весов.
- **CORS открыт для всех сайтов.** Это прописано в коде, флага для ограничения нет.
- **TLS:** те же `--ssl-keyfile`, `--ssl-certfile`, `--enable-ssl-refresh`. HTTP/2 — `--enable-http2`.
- **Связь между узлами** не шифруется.
- **Картинки по ссылкам:** `--allowed-media-domains`. Без него сервер скачивает с любого адреса.
- **Телеметрия:** нет.

## Несколько копий и маршрутизация

Когда одной видеокарты мало, запускают несколько копий сервера и раздают запросы между ними. Кэш префиксов у каждой копии свой. Если следующий ход диалога попадёт на другую копию, она прочитает всю историю заново. Поэтому для серверов моделей есть маршрутизаторы, которые отправляют запрос туда, где его начало уже в кэше.

<div style="overflow-x:auto;margin:1.5rem 0" tabindex="0" role="region">
<svg viewBox="0 0 810 256" width="100%" style="min-width:620px;max-width:810px;height:auto;display:block;margin:0 auto" role="img" aria-label="Раздача запросов по кругу и с учётом кэша" xmlns="http://www.w3.org/2000/svg">
  <defs>
    <marker id="vs-routing-head" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
      <path d="M0 0 L10 5 L0 10 z" fill="var(--color-fg-dim)"/>
    </marker>
  </defs>
  <text x="205" y="24" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="13.5" font-weight="500">По кругу</text>
  <rect x="20" y="96" width="120" height="60" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-link)" stroke-width="1.5"/>
  <text x="80" y="120" text-anchor="middle" fill="var(--color-link)" font-family="var(--font-sans)" font-size="14" font-weight="500">диалог</text>
  <text x="80" y="140" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">ходы 1 и 2</text>
  <rect x="250" y="44" width="140" height="60" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-accent)" stroke-width="1.5"/>
  <text x="320" y="68" text-anchor="middle" fill="var(--color-accent)" font-family="var(--font-sans)" font-size="14" font-weight="500">копия 1</text>
  <text x="320" y="88" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">кэш: ход 1</text>
  <rect x="250" y="150" width="140" height="60" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-border)" stroke-width="1.5"/>
  <text x="320" y="174" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="14" font-weight="500">копия 2</text>
  <text x="320" y="194" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">кэш пуст</text>
  <path d="M140 112 L195 112 L195 66 L250 66" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" marker-end="url(#vs-routing-head)"/>
  <text x="170" y="104" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">1</text>
  <path d="M140 140 L195 140 L195 180 L250 180" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" stroke-dasharray="5 4" marker-end="url(#vs-routing-head)"/>
  <text x="170" y="158" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">2</text>
  <text x="205" y="240" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">ход 2 попал на копию 2: история читается заново</text>
  <text x="605" y="24" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="13.5" font-weight="500">С учётом кэша</text>
  <rect x="420" y="96" width="120" height="60" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-link)" stroke-width="1.5"/>
  <text x="480" y="120" text-anchor="middle" fill="var(--color-link)" font-family="var(--font-sans)" font-size="14" font-weight="500">диалог</text>
  <text x="480" y="140" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">ходы 1 и 2</text>
  <rect x="650" y="44" width="140" height="60" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-accent)" stroke-width="1.5"/>
  <text x="720" y="68" text-anchor="middle" fill="var(--color-accent)" font-family="var(--font-sans)" font-size="14" font-weight="500">копия 1</text>
  <text x="720" y="88" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">кэш: ход 1</text>
  <rect x="650" y="150" width="140" height="60" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-border)" stroke-width="1.5"/>
  <text x="720" y="174" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="14" font-weight="500">копия 2</text>
  <text x="720" y="194" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">кэш пуст</text>
  <path d="M540 112 L595 112 L595 66 L650 66" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" marker-end="url(#vs-routing-head)"/>
  <text x="570" y="104" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">1</text>
  <path d="M540 130 L615 130 L615 86 L650 86" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" stroke-dasharray="5 4" marker-end="url(#vs-routing-head)"/>
  <text x="570" y="146" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12" font-weight="400">2</text>
  <text x="605" y="240" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">ход 2 попал на копию 1: история уже в кэше</text>
  <path d="M400 14 L400 246" stroke="var(--color-border)" stroke-width="1" stroke-dasharray="4 4"/>
</svg>
</div>

Замер на стенде: две копии Qwen3.5-0.8B на одной видеокарте, шесть диалогов по пять ходов с длинным системным промптом.

| Сервер | Раздача запросов | Токенов промпта из кэша |
|---|---|---|
| vLLM | одна копия | 59% |
| vLLM | nginx, менее занятому | 34% |
| vLLM | vLLM Router, с учётом кэша | 52% |
| SGLang | маршрутизатор, по кругу | 53% |
| SGLang | маршрутизатор, с учётом кэша | 73% |

Раздача без учёта кэша отнимает у vLLM почти половину попаданий. Тест маленький (30 запросов), доли от прогона к прогону немного меняются.

### vLLM: копии и маршрутизация

**nginx** — вариант из документации vLLM. Меняется начало настройки из раздела о сети:

```nginx title="nginx/balance.conf"
upstream llm {
    # Новый запрос уходит тому серверу, у которого меньше открытых соединений
    least_conn;
    server vllm-a:8000 max_fails=3 fail_timeout=30s;
    server vllm-b:8000 max_fails=3 fail_timeout=30s;
    keepalive 32;
}
```

**[vLLM Router](https://github.com/vllm-project/router)** — маршрутизатор на Rust от команды vLLM. Вырос из маршрутизатора SGLang ([анонс](https://vllm.ai/blog/2025-12-13-vllm-router-release)).

```bash
pip install vllm-router==0.1.17
vllm-router \
  --worker-urls http://vllm-a:8000 http://vllm-b:8000 \
  --policy cache_aware \
  --host 0.0.0.0 --port 8090
```

Правила раздачи (`--policy`):

| Значение | Как раздаёт |
|---|---|
| `round_robin` | по кругу |
| `random` | случайно |
| `power_of_two` | менее занятому из двух случайных |
| `consistent_hash` | по хэшу запроса |
| `sticky_least_loaded` | менее занятому, с закреплением диалога |
| `cache_aware` | туда, где начало запроса в кэше |
| `kv_aware` | по сведениям о кэше от самих серверов |

Ещё умеет: повтор неудавшихся запросов, исключение сбоящей копии, поиск копий в Kubernetes.

**[Production Stack](https://github.com/vllm-project/production-stack)** — набор для Kubernetes от той же команды: маршрутизатор, серверы, мониторинг, ставится через Helm. На стенде не запускался.

**Слои для кластеров:** llm-d, AIBrix, NVIDIA Dynamo, KServe — для каждого есть страница в документации vLLM.

### SGLang: копии и маршрутизация

Маршрутизатор лежит в образе сервера:

```bash
docker run -d --name sglang-router --network lab -p 30010:30000 \
  --entrypoint python lmsysorg/sglang:v0.5.23-runtime \
  -m sglang_router.launch_router \
  --worker-urls http://sglang-a:30000 http://sglang-b:30000 \
  --policy cache_aware \
  --host 0.0.0.0 --port 30000 --prometheus-port 29000
```

Правила раздачи: `round_robin`, `random`, `power_of_two`, `cache_aware`, `consistent_hashing`, `prefix_hash`, `bucket`, `manual`. Ещё умеет: повтор запросов, исключение сбоящих копий, ограничение числа одновременных запросов, поиск копий в Kubernetes. Свои метрики отдаёт на отдельном порту.

Маршрутизаторов у SGLang сейчас три:

| Проект | Пакет | Состояние |
|---|---|---|
| SGLang Model Gateway | `sglang-router` | в образе и в документации; пакет не обновлялся с января 2026 |
| [SMG](https://github.com/smg-project/smg) | `smg` | продолжение первого в отдельном репозитории; работает и с vLLM |
| sgl-router | `sgl-router` | новый облегчённый, первая версия 18 ноября 2026 |

Перед выбором проверьте, какой из них развивается.

**Копии внутри одного сервера:** `--dp-size N`. Документация для этого случая сама советует маршрутизатор.

**Слои для кластеров:** llm-d, AIBrix, Dynamo и собственный оператор для Kubernetes — OME.

## Наблюдаемость

- **Метрики** — счётчики и времена в формате Prometheus по адресу `/metrics` на основном порту.
- **Журналы** — что сервер делает, по желанию каждый запрос.
- **Трассировка** — путь одного запроса по шагам, по стандарту OpenTelemetry.

Времена, которые показывают метрики и трассы:

<div style="overflow-x:auto;margin:1.5rem 0" tabindex="0" role="region">
<svg viewBox="0 0 780 200" width="100%" style="min-width:620px;max-width:780px;height:auto;display:block;margin:0 auto" role="img" aria-label="Времена одного запроса: очередь, чтение промпта, первый токен, генерация" xmlns="http://www.w3.org/2000/svg">
  <defs>
    <marker id="vs-timeline-head" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
      <path d="M0 0 L10 5 L0 10 z" fill="var(--color-fg-dim)"/>
    </marker>
    <marker id="vs-timeline-tail" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
      <path d="M0 0 L10 5 L0 10 z" fill="var(--color-fg-dim)"/>
    </marker>
  </defs>
  <rect x="30" y="92" width="110" height="44" fill="var(--color-border)" fill-opacity="0.9" stroke="var(--color-border)" stroke-width="1"/>
  <text x="85" y="118" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">очередь</text>
  <rect x="140" y="92" width="190" height="44" fill="var(--color-link)" fill-opacity="0.45" stroke="var(--color-border)" stroke-width="1"/>
  <text x="235" y="118" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">prefill: чтение промпта</text>
  <rect x="330" y="92" width="420" height="44" fill="var(--color-accent)" fill-opacity="0.4" stroke="var(--color-border)" stroke-width="1"/>
  <text x="540" y="118" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">decode: токены ответа, один за другим</text>
  <path d="M360 127 L360 136" stroke="var(--color-fg-dim)" stroke-width="1"/>
  <path d="M390 127 L390 136" stroke="var(--color-fg-dim)" stroke-width="1"/>
  <path d="M420 127 L420 136" stroke="var(--color-fg-dim)" stroke-width="1"/>
  <path d="M450 127 L450 136" stroke="var(--color-fg-dim)" stroke-width="1"/>
  <path d="M480 127 L480 136" stroke="var(--color-fg-dim)" stroke-width="1"/>
  <path d="M510 127 L510 136" stroke="var(--color-fg-dim)" stroke-width="1"/>
  <path d="M540 127 L540 136" stroke="var(--color-fg-dim)" stroke-width="1"/>
  <path d="M570 127 L570 136" stroke="var(--color-fg-dim)" stroke-width="1"/>
  <path d="M600 127 L600 136" stroke="var(--color-fg-dim)" stroke-width="1"/>
  <path d="M630 127 L630 136" stroke="var(--color-fg-dim)" stroke-width="1"/>
  <path d="M660 127 L660 136" stroke="var(--color-fg-dim)" stroke-width="1"/>
  <path d="M690 127 L690 136" stroke="var(--color-fg-dim)" stroke-width="1"/>
  <path d="M720 127 L720 136" stroke="var(--color-fg-dim)" stroke-width="1"/>
  <path d="M30 62 L330 62" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" marker-end="url(#vs-timeline-head)" marker-start="url(#vs-timeline-tail)"/>
  <text x="180" y="52" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">время до первого токена (TTFT)</text>
  <path d="M540 62 L570 62" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" marker-end="url(#vs-timeline-head)" marker-start="url(#vs-timeline-tail)"/>
  <text x="585" y="52" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">пауза между токенами</text>
  <path d="M30 166 L750 166" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" marker-end="url(#vs-timeline-head)" marker-start="url(#vs-timeline-tail)"/>
  <text x="390" y="186" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">время запроса целиком</text>
  <text x="30" y="24" text-anchor="start" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12" font-weight="400">запрос пришёл</text>
  <text x="750" y="24" text-anchor="end" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12" font-weight="400">ответ закончен</text>
</svg>
</div>

Prometheus, Grafana и Jaeger рядом с серверами:

```yaml title="monitoring/compose.yaml"
# Prometheus, Grafana и Jaeger рядом с серверами моделей.
# Сеть lab создана заранее: docker network create lab
services:
  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    volumes:
      - ./prometheus.yaml:/etc/prometheus/prometheus.yml:ro
    ports:
      - "9090:9090"
    networks: [lab]

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    environment:
      # Вход без пароля — только для стенда на своём компьютере
      - GF_AUTH_ANONYMOUS_ENABLED=true
      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
    volumes:
      # Источник данных и дашборды подключаются сами при старте
      - ./provisioning:/etc/grafana/provisioning:ro
      - ./dashboards:/var/lib/grafana/dashboards:ro
    ports:
      - "3000:3000"
    networks: [lab]
    depends_on: [prometheus]

  jaeger:
    image: jaegertracing/jaeger:latest
    container_name: jaeger
    ports:
      - "16686:16686" # веб-интерфейс
      - "4317:4317"   # приём трасс по OTLP gRPC
      - "4318:4318"   # приём трасс по OTLP HTTP
    networks: [lab]

networks:
  lab:
    external: true
```

```yaml title="monitoring/prometheus.yaml"
global:
  scrape_interval: 5s

scrape_configs:
  # Оба сервера отдают метрики по адресу /metrics на своём основном порту
  - job_name: vllm
    static_configs:
      - targets: ["vllm:8000"]

  - job_name: sglang
    static_configs:
      - targets: ["sglang:30000"]
```

Два файла, чтобы Grafana сама подключила Prometheus и дашборды из папки:

```yaml title="monitoring/provisioning/datasources/prometheus.yaml"
apiVersion: 1
datasources:
  - name: Prometheus
    uid: prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
```

```yaml title="monitoring/provisioning/dashboards/dashboards.yaml"
apiVersion: 1
providers:
  - name: lab
    type: file
    options:
      path: /var/lib/grafana/dashboards
```

Графики ниже сняты под одинаковой нагрузкой: восемь клиентов без пауз, общий системный промпт, Qwen3.5-4B в FP8, четыре минуты.

### vLLM: метрики, журналы, трассировка

**Метрики** включены всегда.

| Метрика | Что показывает |
|---|---|
| `vllm:num_requests_running` | запросов выполняется |
| `vllm:num_requests_waiting` | запросов в очереди. Главный сигнал для добавления копий |
| `vllm:kv_cache_usage_perc` | заполненность памяти диалогов, 0–1 |
| `vllm:time_to_first_token_seconds` | время до первого токена |
| `vllm:inter_token_latency_seconds` | пауза между токенами |
| `vllm:e2e_request_latency_seconds` | время запроса целиком |
| `vllm:prompt_tokens_total`, `vllm:generation_tokens_total` | прочитано и написано токенов |
| `vllm:prefix_cache_hits_total`, `vllm:prefix_cache_queries_total` | попадания в кэш префиксов |
| `vllm:num_preemptions_total` | вытеснения запросов из-за нехватки памяти |
| `vllm:request_success_total` | законченные запросы с причиной окончания |

**Дашборд** — в репозитории: `examples/observability/prometheus_grafana/grafana.json`. Он рассчитан на ручной импорт; для автоматического подключения замените переменную источника данных:

```bash
sed -i 's/${DS_PROMETHEUS}/prometheus/g' monitoring/dashboards/vllm.json
```

![Дашборд vLLM в Grafana под нагрузкой: задержки, токены в секунду, очередь, заполненность кэша](/images/2026/11/vllm-sglang-grafana-vllm.png)

На графиках: восемь запросов выполняются, очереди нет; около 400 токенов в секунду на выходе; первый токен в среднем через 0,1 секунды; память диалогов заполнена наполовину.

**Журнал.** Каждые десять секунд — строка с итогами:

```text
Engine 000: Avg prompt throughput: 1913.3 tokens/s,
  Avg generation throughput: 371.4 tokens/s,
  Running: 9 reqs, Waiting: 0 reqs, GPU KV cache usage: 49.4%,
  Prefix cache hit rate: 3.6%
```

| Флаг | Что делает |
|---|---|
| `--enable-log-requests` | строка о каждом запросе: идентификатор и параметры. Тексты — только на уровне DEBUG |
| `--enable-log-outputs` | писать и ответы |
| `--max-log-len` | обрезать длинные тексты |
| `--disable-access-log-for-endpoints /health,/metrics` | не писать о проверках состояния |
| `--logging-config.formatter json` | журнал в JSON |

Строка журнала в JSON:

```json
{
  "asctime": "2026-11-21 06:22:43,840",
  "levelname": "INFO",
  "name": "vllm.v1.core.kv_cache_utils",
  "processName": "EngineCore",
  "process": 99,
  "message": "GPU KV cache size: 171,008 tokens, ..."
}
```

**Трассировка.** Библиотеки уже в образе. Нужны адрес приёмника и две переменные:

```bash
docker run --gpus all --ipc=host -p 8000:8000 --network lab --name vllm \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -v ./vllm:/lab/vllm \
  -e VLLM_API_KEY=sk-lab-123 \
  -e OTEL_SERVICE_NAME=vllm \
  -e OTEL_EXPORTER_OTLP_TRACES_INSECURE=true \
  vllm/vllm-openai:v0.34.0 \
  --config /lab/vllm/config.yaml \
  --otlp-traces-endpoint grpc://jaeger:4317 --enable-log-requests
```

На каждый запрос vLLM пишет одну запись с готовыми числами:

![Трасса запроса vLLM в Jaeger: одна запись с временами очереди, чтения промпта и генерации](/images/2026/11/vllm-sglang-jaeger-vllm.png)

Промпт из 517 токенов читался 0,12 секунды, ответ из 93 токенов писался 1,28 секунды, первый токен пришёл через 0,15 секунды. Имена полей — из соглашения OpenTelemetry для генеративного ИИ.

### SGLang: метрики, журналы, трассировка

**Метрики** включаются флагом `--enable-metrics`.

| Метрика | Что показывает |
|---|---|
| `sglang:num_running_reqs` | запросов выполняется |
| `sglang:num_queue_reqs` | запросов в очереди |
| `sglang:token_usage` | заполненность памяти диалогов |
| `sglang:mamba_usage` | заполненность памяти состояния у гибридных моделей |
| `sglang:time_to_first_token_seconds` | время до первого токена |
| `sglang:inter_token_latency_seconds` | пауза между токенами |
| `sglang:e2e_request_latency_seconds` | время запроса целиком |
| `sglang:gen_throughput` | скорость генерации, токенов в секунду |
| `sglang:cache_hit_rate` | доля токенов промпта из кэша |
| `sglang:num_retracted_requests_total` | снятые запросы из-за нехватки памяти |

**Дашборд** — в репозитории: `examples/monitoring/grafana/dashboards/json/sglang-dashboard.json`. В версии 0.5.23 он не показывает данные:

![Готовый дашборд SGLang в Grafana: на всех графиках написано No data](/images/2026/11/vllm-sglang-grafana-sglang-empty.png)

Сервер публикует метрики с двоеточием (`sglang:num_running_reqs`), а запросы в дашборде написаны с подчёркиванием (`sglang_num_running_reqs`). Исправление:

```bash
sed -i 's/sglang_/sglang:/g' monitoring/dashboards/sglang.json
```

![Дашборд SGLang в Grafana под нагрузкой: задержки, токены в секунду, очередь, попадания в кэш](/images/2026/11/vllm-sglang-grafana-sglang.png)

На графиках: четыре запроса выполняются, четыре в очереди — больше на этой видеокарте с этой моделью не помещается; около 215 токенов в секунду; первый токен через 2–4 секунды из-за очереди; попадание в кэш 0,87.

**Журнал.** Строка на каждое чтение промпта и раз в 40 шагов генерации:

```text
Prefill batch, #new-seq: 1, #new-token: 69, #cached-token: 448,
  full token usage: 0.02, mamba usage: 0.80,
  #running-req: 3, #queue-req: 1, input throughput (token/s): 137.62
Decode batch, #running-req: 4, #full token: 1011,
  full token usage: 0.03, mamba num: 16, mamba usage: 0.80,
  gen throughput (token/s): 217.87, #queue-req: 4
```

Память диалогов почти пуста (`full token usage: 0.03`), память состояния заполнена на 80% (`mamba usage: 0.80`). Узкое место — она.

| Флаг | Что делает |
|---|---|
| `--log-requests` | писать о каждом запросе |
| `--log-requests-level` | подробность от 0 (метаданные) до 3 (полные тексты) |
| `--log-requests-format json` | записи о запросах в JSON |
| `--log-requests-target` | куда писать: консоль, папка или оба |
| `--log-level`, `--log-level-http` | подробность журнала сервера и HTTP |

Запись о запросе в JSON, сокращённая:

```json
{
  "timestamp": "2026-11-21T06:09:40.003283",
  "event": "request.finished",
  "rid": "369fb465a2ce4d5294e441b2e8fdba7f",
  "obj": {
    "sampling_params": {"temperature": 1.0, "max_new_tokens": 120, "top_p": 1.0},
    "stream": true
  }
}
```

В JSON пишутся только записи о запросах. Остальной журнал — текст; для JSON нужен свой файл настройки журнала (`SGLANG_LOGGING_CONFIG_PATH`).

**Трассировка:**

```bash
docker run --gpus all --ipc=host --shm-size 16g -p 30000:30000 --network lab --name sglang \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -v ./sglang:/lab/sglang \
  lmsysorg/sglang:v0.5.23-runtime \
  sglang serve RedHatAI/Qwen3.5-4B-FP8-dynamic \
  --config /lab/sglang/config.yaml --api-key sk-lab-123 \
  --enable-trace --otlp-traces-endpoint jaeger:4317 \
  --log-requests --log-requests-level 1 --log-requests-format json
```

SGLang пишет дерево шагов:

![Трасса запроса SGLang в Jaeger: дерево шагов от токенизации до генерации каждой порции токенов](/images/2026/11/vllm-sglang-jaeger-sglang.png)

Токенизация — 3,6 мс, чтение промпта из 2157 токенов — 769 мс, дальше генерация порциями по 16 мс.

Запись vLLM легче: одно событие на запрос. Дерево SGLang подробнее, но это десятки записей на запрос; подробность снижается переменной `SGLANG_TRACE_LEVEL`.

### Проверки состояния

| | vLLM | SGLang |
|---|---|---|
| Процесс жив | `/health`: 200 или 503 | `/health` |
| Сервер реально генерирует | — | `/health_generate`: генерирует один токен |
| Готов принимать запросы | — | `/ready`: 503 во время запуска, паузы и остановки |

Пока модель загружается, порт vLLM закрыт. В Kubernetes нужна стартовая проверка (`startupProbe`) с запасом в несколько минут, иначе под будет перезапускаться бесконечно.

## Производительность

Общего ответа «кто быстрее» нет. Независимые замеры 2026 года расходятся:

- [Winder.AI](https://winder.ai/vllm-vs-ollama-vs-sglang-llm-inference-comparison/), сентябрь, H100, Qwen3.8-27B: SGLang впереди на 7%.
- [Jarvislabs](https://jarvislabs.ai/blog/vllm-sglang-trtllm-comparison), май, H100, модели Qwen прошлых поколений: впереди vLLM.
- Каким публичным тестам верить — в [разделе о бенчмарках](/ru/llm-inference-engines/#Бенчмарки-каким-цифрам-верить).

Замер на стенде:

- **Модель:** Qwen3.5-2B без сжатия.
- **Клиент:** `vllm bench serve` для обоих серверов. Промпт — 512 случайных токенов, ответ — 256 токенов. На каждом уровне новые промпты.
- **vLLM:** `--max-model-len 8192 --max-num-seqs 64`.
- **SGLang:** с настройками по умолчанию и настроенный.

```bash
docker run --rm --network lab --gpus all --entrypoint vllm \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  vllm/vllm-openai:v0.34.0 bench serve \
  --backend openai --base-url http://vllm:8000 --endpoint /v1/completions \
  --model qwen3.5-2b --tokenizer Qwen/Qwen3.5-2B \
  --dataset-name random --random-input-len 512 --random-output-len 256 \
  --num-prompts 96 --max-concurrency 16 --ignore-eos --seed 42185
```

<div style="overflow-x:auto;margin:1.5rem 0" tabindex="0" role="region">
<svg viewBox="0 0 800 304" width="100%" style="min-width:620px;max-width:800px;height:auto;display:block;margin:0 auto" role="img" aria-label="Скорость генерации vLLM и SGLang при разном числе одновременных запросов" xmlns="http://www.w3.org/2000/svg">
  <defs>
    <marker id="vs-bench-head" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
      <path d="M0 0 L10 5 L0 10 z" fill="var(--color-fg-dim)"/>
    </marker>
  </defs>
  <path d="M40 250 L774 250" stroke="var(--color-border)" stroke-width="1.5"/>
  <rect x="60" y="241" width="38" height="9" rx="2" fill="var(--color-accent)" fill-opacity="0.6" stroke="var(--color-border)" stroke-width="1"/>
  <text x="79" y="235" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="11.5" font-weight="400">110</text>
  <rect x="102" y="241" width="38" height="9" rx="2" fill="var(--color-border)" fill-opacity="0.95" stroke="var(--color-border)" stroke-width="1"/>
  <text x="121" y="235" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="11.5" font-weight="400">109</text>
  <rect x="144" y="242" width="38" height="8" rx="2" fill="var(--color-link)" fill-opacity="0.55" stroke="var(--color-border)" stroke-width="1"/>
  <text x="163" y="236" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="11.5" font-weight="400">107</text>
  <text x="121" y="270" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12.5" font-weight="400">1</text>
  <rect x="206" y="213" width="38" height="37" rx="2" fill="var(--color-accent)" fill-opacity="0.6" stroke="var(--color-border)" stroke-width="1"/>
  <text x="225" y="207" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="11.5" font-weight="400">468</text>
  <rect x="248" y="214" width="38" height="36" rx="2" fill="var(--color-border)" fill-opacity="0.95" stroke="var(--color-border)" stroke-width="1"/>
  <text x="267" y="208" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="11.5" font-weight="400">454</text>
  <rect x="290" y="217" width="38" height="33" rx="2" fill="var(--color-link)" fill-opacity="0.55" stroke="var(--color-border)" stroke-width="1"/>
  <text x="309" y="211" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="11.5" font-weight="400">416</text>
  <text x="267" y="270" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12.5" font-weight="400">4</text>
  <rect x="352" y="141" width="38" height="109" rx="2" fill="var(--color-accent)" fill-opacity="0.6" stroke="var(--color-border)" stroke-width="1"/>
  <text x="371" y="135" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="11.5" font-weight="400">1382</text>
  <rect x="394" y="191" width="38" height="59" rx="2" fill="var(--color-border)" fill-opacity="0.95" stroke="var(--color-border)" stroke-width="1"/>
  <text x="413" y="185" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="11.5" font-weight="400">753</text>
  <rect x="436" y="160" width="38" height="90" rx="2" fill="var(--color-link)" fill-opacity="0.55" stroke="var(--color-border)" stroke-width="1"/>
  <text x="455" y="154" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="11.5" font-weight="400">1150</text>
  <text x="413" y="270" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12.5" font-weight="400">16</text>
  <rect x="498" y="112" width="38" height="138" rx="2" fill="var(--color-accent)" fill-opacity="0.6" stroke="var(--color-border)" stroke-width="1"/>
  <text x="517" y="106" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="11.5" font-weight="400">1756</text>
  <rect x="540" y="188" width="38" height="62" rx="2" fill="var(--color-border)" fill-opacity="0.95" stroke="var(--color-border)" stroke-width="1"/>
  <text x="559" y="182" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="11.5" font-weight="400">783</text>
  <rect x="582" y="138" width="38" height="112" rx="2" fill="var(--color-link)" fill-opacity="0.55" stroke="var(--color-border)" stroke-width="1"/>
  <text x="601" y="132" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="11.5" font-weight="400">1427</text>
  <text x="559" y="270" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12.5" font-weight="400">32</text>
  <rect x="644" y="60" width="38" height="190" rx="2" fill="var(--color-accent)" fill-opacity="0.6" stroke="var(--color-border)" stroke-width="1"/>
  <text x="663" y="54" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="11.5" font-weight="400">2415</text>
  <rect x="686" y="191" width="38" height="59" rx="2" fill="var(--color-border)" fill-opacity="0.95" stroke="var(--color-border)" stroke-width="1"/>
  <text x="705" y="185" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="11.5" font-weight="400">756</text>
  <rect x="728" y="131" width="38" height="119" rx="2" fill="var(--color-link)" fill-opacity="0.55" stroke="var(--color-border)" stroke-width="1"/>
  <text x="747" y="125" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="11.5" font-weight="400">1518</text>
  <text x="705" y="270" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-mono)" font-size="12.5" font-weight="400">64</text>
  <text x="407" y="292" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">одновременных запросов</text>
  <rect x="60" y="12" width="14" height="14" rx="2" fill="var(--color-accent)" fill-opacity="0.6" stroke="var(--color-border)"/>
  <text x="82" y="24" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">vLLM</text>
  <rect x="170" y="12" width="14" height="14" rx="2" fill="var(--color-border)" fill-opacity="0.95" stroke="var(--color-border)"/>
  <text x="192" y="24" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">SGLang по умолчанию</text>
  <rect x="390" y="12" width="14" height="14" rx="2" fill="var(--color-link)" fill-opacity="0.55" stroke="var(--color-border)"/>
  <text x="412" y="24" text-anchor="start" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">SGLang настроенный</text>
  <text x="774" y="24" text-anchor="end" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5" font-weight="400">токенов в секунду</text>
</svg>
</div>

Скорость генерации, токенов в секунду:

| Одновременных запросов | vLLM | SGLang по умолчанию | SGLang настроенный |
|---|---|---|---|
| 1 | 110 | 109 | 107 |
| 4 | 468 | 454 | 416 |
| 16 | 1382 | 753 | 1150 |
| 32 | 1756 | 783 | 1427 |
| 64 | 2415 | 756 | 1518 |

Медианное время до первого токена, миллисекунды:

| Одновременных запросов | vLLM | SGLang по умолчанию | SGLang настроенный |
|---|---|---|---|
| 1 | 43 | 45 | 46 |
| 4 | 134 | 154 | 157 |
| 16 | 293 | 400 | 361 |
| 32 | 306 | 7796 | 698 |
| 64 | 330 | 16 667 | 5529 |

Выводы:

1. **Для одного пользователя серверы равны.**
2. **Батчинг работает в обоих.** 64 одновременных запроса дают у vLLM в 22 раза больше текста, чем один.
3. **SGLang по умолчанию ограничил себя 12 запросами:** мало памяти под состояние гибридной модели. Остальные запросы ждали в очереди.
4. **После настройки SGLang вдвое быстрее** (29 одновременных запросов), но vLLM не догнал.

Настроенный SGLang:

```bash
sglang serve Qwen/Qwen3.5-2B --host 0.0.0.0 \
  --served-model-name qwen3.5-2b --context-length 8192 --enable-metrics \
  --max-running-requests 64 --mamba-full-memory-ratio 4 \
  --cuda-graph-max-bs-decode 64 --mem-fraction-static 0.72
```

**Запросы с общим началом:** четыре начала по 3000 токенов, по 24 запроса на каждое, восемь одновременно.

```bash
docker run --rm --network lab --gpus all --entrypoint vllm \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  vllm/vllm-openai:v0.34.0 bench serve \
  --backend openai --base-url http://vllm:8000 --endpoint /v1/completions \
  --model qwen3.5-2b --tokenizer Qwen/Qwen3.5-2B \
  --dataset-name prefix_repetition \
  --prefix-repetition-num-prefixes 4 --prefix-repetition-prefix-len 3000 \
  --prefix-repetition-suffix-len 200 --prefix-repetition-output-len 100 \
  --num-prompts 96 --max-concurrency 8 --ignore-eos --seed 43995
```

| | vLLM | SGLang |
|---|---|---|
| Скорость генерации, токенов в секунду | 689 | 653 |
| Медианное время до первого токена | 141 мс | 172 мс |
| Токенов промпта из кэша | 86% | 92% |

На длинном общем начале серверы равны. Разница видна на коротких совпадениях и в диалоге, который растёт понемногу (раздел [о сессиях](#Сессии-и-состояние)).

Ограничения замера:

- **Ноутбук.** На серверной карте с 80 ГБ память под состояние не будет узким местом.
- **Гибридная модель.** Отставание SGLang связано с тем, как он размещает её состояние. На обычных моделях бывает наоборот.
- **Память на пределе.** Настроенный SGLang занял 11,3 из 12 ГБ.
- **Случайные промпты** — худший случай для кэша.

Замерьте оба сервера на своей модели, своей видеокарте и своей нагрузке.

### vLLM: что настраивать для скорости

| Настройка | Действие |
|---|---|
| `--max-num-seqs` | потолок одновременных запросов. Больше — выше общая скорость, длиннее пауза между токенами у каждого |
| `--max-num-batched-tokens` | токенов за шаг. Меньше — ровнее паузы, больше — быстрее первый токен |
| `--performance-mode` | готовые наборы: `balanced`, `interactivity`, `throughput` |
| `-O0` … `-O3` | уровень оптимизации. `-O0` — быстрый старт и медленная работа |
| `--spec-method`, `--spec-model`, `--spec-tokens` | [спекулятивное декодирование](/ru/llm-inference-engines/#Спекулятивное-декодирование) |
| том `/root/.cache/vllm` | кэш компиляции; без него каждый новый контейнер компилирует заново |
| `VLLM_WSL2_ENABLE_PIN_MEMORY=1` | под WSL2 около 12% скорости генерации, по [замеру из обсуждений проекта](https://github.com/vllm-project/vllm/issues/58849). На стенде не проверялось |

### SGLang: что настраивать для скорости

| Настройка | Действие |
|---|---|
| `--max-running-requests` | потолок одновременных запросов |
| `--cuda-graph-max-bs-decode` | самый большой батч, для которого записан граф. На картах меньше 20 ГБ — 8; сверх этого сервер работает без графа и медленнее |
| `--schedule-policy` | порядок очереди. `fcfs` — по времени прихода, `lpm` — сначала с самым длинным совпадением в кэше |
| `--schedule-conservativeness` | осторожность приёма запросов. Меньше 1 — смелее |
| `--chunked-prefill-size` | размер кусков чтения промпта |
| `--mamba-full-memory-ratio`, `--max-mamba-cache-size` | память под состояние гибридных моделей |
| `--speculative-algorithm` | спекулятивное декодирование |
| `SGLANG_CACHE_DIR` и том | кэш скомпилированных ядер |

Правило из документации: память диалогов заполнена меньше чем на 90%, а очередь не пуста — уменьшите `--schedule-conservativeness`.

## Несколько видеокарт

Раздел написан по документации, без запуска. Способы разложить модель по картам описаны в [разделе о масштабировании](/ru/llm-inference-engines/#Масштабирование-от-одной-видеокарты-до-стойки); здесь — флаги.

| Способ | vLLM | SGLang |
|---|---|---|
| Слои делятся между картами (TP) | `--tensor-parallel-size` | `--tp-size` |
| Слои по очереди на разных картах (PP) | `--pipeline-parallel-size` | `--pp-size` |
| Копии модели (DP) | `--data-parallel-size` | `--dp-size` |
| Эксперты MoE по картам (EP) | `--enable-expert-parallel` | `--ep-size` |

### vLLM: несколько видеокарт

Четыре карты одного сервера:

```bash
vllm serve <модель> --tensor-parallel-size 4
```

Два сервера по восемь карт, главный узел и второй:

```bash
vllm serve <модель> --tensor-parallel-size 8 --pipeline-parallel-size 2 \
  --nnodes 2 --node-rank 0 --master-addr <адрес главного узла>

vllm serve <модель> --tensor-parallel-size 8 --pipeline-parallel-size 2 \
  --nnodes 2 --node-rank 1 --master-addr <адрес главного узла> --headless
```

- **Разделение prefill и decode** по разным серверам есть, но помечено экспериментальным. Оно выравнивает задержки, а не увеличивает общую скорость. В продакшене его делают через llm-d, Dynamo или AIBrix.
- **Выгрузка памяти диалогов** в оперативную память: `--kv-offloading-size`.
- **Автомасштабирование в Kubernetes** — по метрике `vllm:num_requests_waiting`. Загрузка процессора здесь ничего не говорит.

### SGLang: несколько видеокарт

Четыре карты одного сервера:

```bash
sglang serve <модель> --tp-size 4
```

Два сервера по четыре карты:

```bash
sglang serve <модель> --tp-size 4 --nnodes 2 --node-rank 0 \
  --dist-init-addr <адрес первого узла>:50000

sglang serve <модель> --tp-size 4 --nnodes 2 --node-rank 1 \
  --dist-init-addr <адрес первого узла>:50000
```

- **Разделение prefill и decode** — сильная сторона SGLang: серверы с `--disaggregation-mode prefill` и `--disaggregation-mode decode`, перед ними маршрутизатор с `--pd-disaggregation`.
- **Многоуровневый кэш HiCache:** память диалогов выгружается в оперативную память и на диск.
- **Большие модели с экспертами:** `--attn-dp-size`.

## Обновления

Обе программы выходят каждые две недели, и в каждой версии что-то переименовано или убрано.

1. Фиксируйте версию образа.
2. Читайте раздел о несовместимых изменениях в примечаниях к выпуску.
3. Проверяйте обновление на копии с той же моделью.

### vLLM: обновления

| Версия | Что сломалось |
|---|---|
| 0.34 | память диалогов считается по-новому; блок кэша 64 токена вместо 16 |
| 0.33 | убраны сборки под CUDA 12 и два способа спекулятивного декодирования |
| 0.32 | убран Python 3.10; запросы из браузера с чужих сайтов запрещены |
| 0.31 | сжатие `fp8` переименовано в `fp8_per_tensor` |

- **Документация отстаёт.** В 0.34 страница установки называет сборкой по умолчанию CUDA 12.9, хотя пакеты собраны под 13.0. Верьте `vllm serve --help=all`.
- **Вызовы функций проверяйте на своих данных.** У хостинга Ubicloud они соответствовали схеме в 92% случаев, пока не включили строгую проверку на сервере ([разбор](https://www.ubicloud.com/blog/fixing-tool-call-accuracy-in-vllm)).

### SGLang: обновления

| Версия | Что сломалось |
|---|---|
| 0.5.23 | маршрутизатор переехал, его флаги переименованы |
| 0.5.22 | нужен Python 3.11; `--enable-dp-attention` заменён на `--attn-dp-size` |
| 0.5.21 | убраны несколько адресов API; шаблон чата из запроса отклоняется |
| 0.5.20 | убраны сборки под CUDA 12 и 17 флагов; хранилище Responses API выключено |

- **Устаревшее убирают через два выпуска,** то есть через месяц.
- **Ставьте обновления безопасности.** С 27 августа по 9 сентября 2026 года сервис Cloudflare на SGLang вернул в 155 ответах данные других клиентов: ошибка SGLang в режиме разделения фаз плюс неверная настройка памяти у Cloudflare ([разбор](https://blog.cloudflare.com/kv-cache-exposure-remediation/)). Исправлено в 0.5.20–0.5.22.
- **Версия 1.0 объявлена** в ноябре 2026 года, но ещё не вышла.

## Частые ошибки

| Что происходит | Причина | Что делать |
|---|---|---|
| Сервер не запускается, хотя модель меньше видеопамяти | кроме весов нужно 3–4 ГиБ | модель меньше или сжатая; раздел [о видеопамяти](#Видеопамять) |
| Вместо ответа приходят рассуждения | не задан разборщик рассуждений | `--reasoning-parser` |
| Вызов функции приходит текстом | не задан разборщик вызовов | `--tool-call-parser` |
| SGLang в контейнере не отвечает снаружи | слушает `127.0.0.1` | `--host 0.0.0.0` |
| SGLang: `--model-path is required` | модель указана только в файле настроек | модель в командной строке |
| SGLang: `state cache is too small` | мала доля памяти по умолчанию | `--mem-fraction-static 0.8` |
| vLLM: `max_num_seqs exceeds available Mamba cache blocks` | слишком много одновременных запросов для гибридной модели | уменьшить `--max-num-seqs` |
| Дашборд SGLang пуст | в запросах `sglang_` вместо `sglang:` | заменить имена метрик |
| vLLM отвечает без ключа | `/invocations` не защищён ключом | прокси со списком адресов |
| Клиент SGLang видит ключ сервера | `/get_server_info` отдаёт настройки | `--admin-api-key` |
| Общий системный промпт не кэшируется в vLLM | он короче блока кэша | для гибридных моделей — промпт длиннее 576 токенов |
| Ответ через nginx приходит одним куском | прокси буферизует | `proxy_buffering off` |

## Что выбрать

<div style="overflow-x:auto;margin:1.5rem 0" tabindex="0" role="region">
<svg viewBox="0 0 800 340" width="100%" style="min-width:620px;max-width:800px;height:auto;display:block;margin:0 auto" role="img" aria-label="Как выбрать между llama.cpp, облачным API, SGLang и vLLM" xmlns="http://www.w3.org/2000/svg">
  <defs>
    <marker id="vs-choose-head" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
      <path d="M0 0 L10 5 L0 10 z" fill="var(--color-fg-dim)"/>
    </marker>
  </defs>
  <rect x="20" y="16" width="380" height="56" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-border)" stroke-width="1.5"/>
  <text x="210" y="49" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="14" font-weight="500">Пользователь один?</text>
  <rect x="500" y="16" width="280" height="56" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-link)" stroke-width="1.5"/>
  <text x="640" y="40" text-anchor="middle" fill="var(--color-link)" font-family="var(--font-sans)" font-size="14" font-weight="500">llama.cpp / Ollama</text>
  <text x="640" y="60" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">проще и не медленнее</text>
  <path d="M400 44 L500 44" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" marker-end="url(#vs-choose-head)"/>
  <text x="450" y="36" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12" font-weight="400">да</text>
  <path d="M210 72 L210 100" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" marker-end="url(#vs-choose-head)"/>
  <text x="222" y="90" text-anchor="start" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12" font-weight="400">нет</text>
  <rect x="20" y="100" width="380" height="56" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-border)" stroke-width="1.5"/>
  <text x="210" y="133" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="14" font-weight="500">Нагрузка малая или неровная?</text>
  <rect x="500" y="100" width="280" height="56" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-link)" stroke-width="1.5"/>
  <text x="640" y="124" text-anchor="middle" fill="var(--color-link)" font-family="var(--font-sans)" font-size="14" font-weight="500">облачный API</text>
  <text x="640" y="144" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">видеокарта не окупится</text>
  <path d="M400 128 L500 128" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" marker-end="url(#vs-choose-head)"/>
  <text x="450" y="120" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12" font-weight="400">да</text>
  <path d="M210 156 L210 184" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" marker-end="url(#vs-choose-head)"/>
  <text x="222" y="174" text-anchor="start" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12" font-weight="400">нет</text>
  <rect x="20" y="184" width="380" height="56" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-border)" stroke-width="1.5"/>
  <text x="210" y="217" text-anchor="middle" fill="var(--color-fg)" font-family="var(--font-sans)" font-size="14" font-weight="500">Агенты, длинные диалоги, общие начала?</text>
  <rect x="500" y="184" width="280" height="56" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-accent)" stroke-width="1.5"/>
  <text x="640" y="208" text-anchor="middle" fill="var(--color-accent)" font-family="var(--font-sans)" font-size="14" font-weight="500">SGLang</text>
  <text x="640" y="228" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">и замерить против vLLM</text>
  <path d="M400 212 L500 212" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" marker-end="url(#vs-choose-head)"/>
  <text x="450" y="204" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12" font-weight="400">да</text>
  <path d="M210 240 L210 268" fill="none" stroke="var(--color-fg-dim)" stroke-width="1.5" marker-end="url(#vs-choose-head)"/>
  <text x="222" y="258" text-anchor="start" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12" font-weight="400">нет</text>
  <rect x="20" y="268" width="380" height="56" rx="8" fill="var(--color-bg-elevated)" stroke="var(--color-accent)" stroke-width="1.5"/>
  <text x="210" y="292" text-anchor="middle" fill="var(--color-accent)" font-family="var(--font-sans)" font-size="14" font-weight="500">vLLM</text>
  <text x="210" y="312" text-anchor="middle" fill="var(--color-fg-dim)" font-family="var(--font-sans)" font-size="12.5">выбор по умолчанию</text>
</svg>
</div>

| | vLLM 0.34 | SGLang 0.5.23 |
|---|---|---|
| Кто делает | PyTorch Foundation, Inferact | LMSYS, RadixArk |
| Лицензия | Apache 2.0 | Apache 2.0 |
| Модели и железо | самый широкий выбор | немного уже |
| Запуск на стенде | 155 секунд | 85–100 секунд |
| Отказ при нехватке памяти | через 2–4 минуты | через 20–30 секунд |
| Память | сам измеряет и распределяет | долю задаёте вы |
| Файл настроек | всё, включая модель | всё, кроме модели |
| API | OpenAI, Anthropic | OpenAI, Anthropic, Ollama, свой |
| Кэш префиксов | блоками | деревом, точнее на коротких совпадениях |
| Состояние на сервере | нет | сессии в собственном API |
| Открыто без ключа | проверки, метрики, документация, `/invocations` | проверки и метрики |
| Метрики | включены всегда | включаются флагом |
| Готовый дашборд | работает | нужна правка имён метрик |
| Трассировка | одна запись на запрос | дерево шагов |
| Телеметрия разработчикам | есть, отключается | нет |
| Маршрутизатор | отдельный пакет | в образе; проектов три |
| Скорость, один запрос | одинаковая | одинаковая |
| Скорость, 64 запроса | 2415 токенов/с | 1518 токенов/с после настройки |

- **vLLM** — выбор по умолчанию: чаще работает без настройки, больше моделей и железа, вся обвязка поддерживает его первым.
- **SGLang** — для агентов и длинных диалогов с общими началами, для сессий на сервере и разделения фаз на большом кластере. Требует настройки памяти.
- **Оба** стоит замерить, если сервис большой. Клиентский код от выбора не зависит; меняются команда запуска, файл настроек и дашборд.
- **Ни один,** если пользователь один: проще [llama.cpp](/ru/llama-cpp/). При малой или неровной нагрузке дешевле облачный API.
