---
title: "vLLM і SGLang: практичне порівняння двох серверів для мовних моделей"
url: "https://romankryvolapov.com/uk/vllm-vs-sglang/"
description: "vLLM 0.34 і SGLang 0.5.23 пліч-о-пліч: встановлення, запуск моделей, відеопам'ять, формати та квантування, налаштування, API, кеш діалогів, мережа і безпека, маршрутизація, метрики, журнали й трасування — з командами, файлами налаштувань, скриншотами та замірами на відеокарті з 12 ГБ."
language: uk
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** — для агентів і великих кластерів. Схема вибору — [наприкінці](#Що-вибрати).

Як рушії інференсу влаштовані всередині, розібрано в [окремій статті](/uk/llm-inference-engines/). Тут потрібні чотири поняття звідти: [токени](/uk/llm-inference-engines/#Токени-й-ваги), [фази prefill і decode](/uk/llm-inference-engines/#Prefill-і-decode-дві-фази-з-різними-вузькими-місцями), [KV-кеш](/uk/llm-inference-engines/#KV-кеш) і [батчинг](/uk/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** | оплата за токени | нічого обслуговувати; власна відеокарта окупається лише за постійного завантаження |

Докладніше — в [мапі рушіїв](/uk/llm-inference-engines/#Мапа-рушіїв).

### vLLM: місце серед інших систем

Вибір за замовчуванням. Найширший список моделей і заліза. Шари для [Kubernetes](/uk/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-кеш](/uk/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, — не їхній формат. Що таке квантування — у [розділі про нього](/uk/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
  }
}
```

Відповідь скорочено: у справжній ще два десятки службових полів.

## Сесії та стан

Обидва сервери не зберігають діалоги. Клієнт у кожному запиті надсилає всю історію.

Щоб не читати історію заново на кожному кроці, працює [кеш префіксів](/uk/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.
- Яким публічним тестам вірити — в [розділі про бенчмарки](/uk/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` | [спекулятивне декодування](/uk/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`.

## Кілька відеокарт

Розділ написано за документацією, без запуску. Способи розкласти модель по картах описані в [розділі про масштабування](/uk/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](/uk/llama-cpp/). За малого або нерівного навантаження дешевший хмарний API.
