# vLLM Prometheus: очередь, KV-кеш и задержка локального API

Источник: https://modelium.tech/zhurnal/vllm-metrics-prometheus/

vLLM выдаёт серверные метрики на `/metrics` того же OpenAI-совместимого API. Смотрите вместе `vllm:num_requests_waiting`, `vllm:kv_cache_usage_perc` и гистограммы задержки: один снимок пустой очереди не доказывает запас мощности. Подключайте Prometheus только через контролируемый сетевой доступ и проверяйте показатели на собственной модели под своей нагрузкой.

**Проверено по документации и коду vLLM v0.30.0, Git SHA **`**ced6857**`**, 28 сентября 2026 года.** Команды ниже предназначены для вашего стенда: Modelium не скачивал модель, не запускал vLLM или Prometheus и не измерял нагрузку. Значения и пороги нужно определять на вашей модели и оборудовании, а не брать из образцов документации. [s1](#src-s1) [s2](#src-s2)

## Когда нужны серверные метрики vLLM?

Если локальный API отвечает, но пользователи жалуются на задержки, `/metrics` позволяет раздельно наблюдать число ожидающих и исполняемых запросов, использование блоков KV-кеша и распределение времени до первого токена. Это **серверная телеметрия**, не измерение качества ответа модели, не проверка конфиденциальности и не прогноз на любой GPU. Клиентский [нагрузочный тест](/zhurnal/vllm-bench-serve/) нужен дополнительно, чтобы связать графики с известным потоком запросов. [s1](#src-s1) [s2](#src-s2) [s3](#src-s3)

Маршрут: **задача → модель с подходящими аппаратными условиями → vLLM → успешный ответ → **`**/metrics**`** → собственная контролируемая нагрузка → решение о ёмкости**. Прежде чем смотреть графики, запустите конкретную модель по [гайду vLLM](/zhurnal/vllm/), запишите её ревизию и конфигурацию и получите ответ API. Размер файлов весов сам по себе не даёт минимального требования к памяти. [s4](#src-s4)

## Как проверить `/metrics` без установки Prometheus?

vLLM v0.30.0 экспортирует метрики на том же HTTP-порту, что и OpenAI-совместимый API; отдельный `--enable-metrics` в официальном примере не нужен. Запустите **свою уже выбранную совместимую модель** на loopback с `--host 127.0.0.1 --port 8000` (точные параметры и модель возьмите из гайда запуска), затем на **той же машине**: [s1](#src-s1) [s4](#src-s4) [s7](#src-s7)

curl -fsS http://127.0.0.1:8000/v1/modelscurl -fsS http://127.0.0.1:8000/metrics | grep -E '^vllm:(num_requests_waiting|num_requests_running|kv_cache_usage_perc|prefix_cache_queries|prefix_cache_hits|time_to_first_token_seconds)'

Проверьте HTTP 200, список моделей и строки `# TYPE`/серии с указанными именами. Не считайте отсутствующую серию нулём: некоторые показатели появляются только после подходящего запроса и конкретной конфигурации. Если `/v1/models` работает, а `/metrics` не отвечает, уточните версию, фактический порт и сетевой namespace. [s1](#src-s1) [s3](#src-s3) [s4](#src-s4)

## Что означают очередь, KV-кеш и задержка?

- `vllm:num_requests_waiting` и `vllm:num_requests_running` — мгновенные gauges ожидания и выполнения. В v0.30.0 есть также `vllm:num_requests_waiting_by_reason` с причинами `capacity` и `deferred`. Значение ноль **после** одиночного запроса не говорит, было ли ожидание во время исполнения. [s3](#src-s3)

- `vllm:kv_cache_usage_perc` — доля занятых блоков KV-кеша: `1` означает 100% его ёмкости, а не 100% видеопамяти GPU. Смотрите динамику рядом с очередью и задержкой; одиночный высокий показатель не доказывает сам по себе нехватку RAM/VRAM. [s2](#src-s2) [s3](#src-s3)

- `vllm:prefix_cache_queries` и `vllm:prefix_cache_hits` учитывают **токены**, а не запросы. Доля совпадений за интервал вычисляется как `прирост hits / прирост queries` при ненулевом знаменателе; накопленные абсолютные значения нельзя выдавать за текущий процент. При отключённом или неиспользуемом prefix cache не выводите «плохую эффективность» из нулевых серий. [s2](#src-s2) [s3](#src-s3)

- `vllm:time_to_first_token_seconds` и `vllm:e2e_request_latency_seconds` — гистограммы задержки. `_count` и `_sum` дают число наблюдений и их сумму, `_bucket` — интервалы для оценки квантиля по окну времени; одно мгновенное значение очереди не эквивалентно p95. `vllm:request_queue_time_seconds` отдельно учитывает ожидание. [s2](#src-s2) [s3](#src-s3)

Не путайте `vllm:inter_token_latency_seconds` (промежуток между потоковыми порциями) с `vllm:request_time_per_output_token_seconds` (TPOT за завершённый запрос). При выдаче нескольких токенов за одну порцию, например при speculative decoding, или разных весах усреднения они различаются; vLLM отдельно предупреждает, что TPOT у запроса с одним токеном записывается в Prometheus как ноль, а `bench serve` исключает такой запрос из своего TPOT. [s2](#src-s2)

## Как собирать Prometheus, не открывая API наружу?

Для первого прохода достаточно `curl`: Prometheus и Grafana не нужны. Пример vLLM помещает Prometheus/Grafana в Docker и использует target `host.docker.internal:8000`. Этот адрес относится к **сетевой схеме примера** и может не работать на Linux без настройки host gateway; в отдельном контейнере `127.0.0.1` указывает на сам контейнер, а не на хостовый vLLM. Выбирайте достижимый target в вашей разрешённой сети и проверяйте его из окружения Prometheus, не открывая порт vLLM всему интернету. [s7](#src-s7) [s8](#src-s8)

Следующий пример действует только для Prometheus на том же хосте и в том же сетевом namespace, что и vLLM. [s7](#src-s7) [s8](#src-s8)

scrape_configs:  - job_name: vllm    scrape_interval: 5s    static_configs:      - targets: ['127.0.0.1:8000']

В Prometheus статус `UP` подтверждает лишь успешный сбор, не наличие полезной выборки. Документация vLLM предупреждает: `--api-key` защищает не все пути сервера; нельзя публиковать HTTP-порт в сеть «только ради `/metrics`». В официальном примере Grafana фигурируют стандартные учётные данные `admin/admin`: при переносе в рабочую среду смените их и настройте сетевой доступ, а не копируйте пример как защищённый стек. [s5](#src-s5) [s7](#src-s7) [s8](#src-s8)

## Как получить проверяемый сигнал на своей нагрузке?

- Снимите `/metrics` до теста и сохраните время, версию vLLM, модель/ревизию, настройки сервера, GPU и режим кеша. Убедитесь, что работающее API отвечает на обычный тестовый запрос с вымышленным текстом, а не клиентскими данными. [s1](#src-s1) [s4](#src-s4)

- На **изолированном** стенде задайте небольшой фиксированный поток через [гайд `vllm bench serve`](/zhurnal/vllm-bench-serve/). Пример документации vLLM сам скачивает набор ShareGPT и использует модель Mistral; это не обязательные компоненты и не соответствует требованию не отправлять реальные данные: здесь выбирайте контролируемый локальный набор и сопоставимые параметры. Не нагружайте рабочий сервер ради красивого графика. [s7](#src-s7)

- Во время теста сопоставьте серии `num_requests_waiting`, `num_requests_running`, `kv_cache_usage_perc` с ростом `_count` гистограмм TTFT/очереди. Сохраните клиентские задержки и число ошибок, повторите тест при тех же длинах запросов и одновременности. Если ожидание и TTFT растут, проверьте конкуренцию, длины входа и условия GPU; это **гипотеза диагностики**, не доказательство одной причины. [s2](#src-s2) [s3](#src-s3)

- Зафиксируйте результат как «версия + модель + железо + нагрузка + интервалы метрик + ошибки». Порог тревоги выводите из собственной цели задержки и наблюдаемого поведения, не из условных 80% KV-кеша. Если запросы не завершились, график пуст или Prometheus `DOWN`, сначала устраните сбой сети/API; пустой график не означает нулевую задержку. [s1](#src-s1) [s2](#src-s2) [s8](#src-s8)

После проверки остановите тестовую нагрузку и закройте неиспользуемый мониторинговый доступ. У vLLM есть отдельный путь логирования статистики и Prometheus registry; удалять модель или сбрасывать кеш для чтения `/metrics` не требуется. Основной следующий шаг — [запустить vLLM и подтвердить локальный ответ](/zhurnal/vllm/), затем проверить собственные серии в контролируемом тесте. [s2](#src-s2) [s6](#src-s6)

## Источники

1. [vLLM v0.30.0 — Production Metrics](https://github.com/vllm-project/vllm/blob/ced6857afa0ea7b2e3f0846a62e1394e90f15607/docs/usage/metrics.md) — получено 2026-09-28
2. [vLLM v0.30.0 — Metrics design and metric semantics](https://github.com/vllm-project/vllm/blob/ced6857afa0ea7b2e3f0846a62e1394e90f15607/docs/design/metrics.md) — получено 2026-09-28
3. [vLLM v0.30.0 — Prometheus metric logger source](https://github.com/vllm-project/vllm/blob/ced6857afa0ea7b2e3f0846a62e1394e90f15607/vllm/v1/metrics/loggers.py) — получено 2026-09-28
4. [vLLM v0.30.0 — Quickstart and OpenAI-compatible HTTP server](https://github.com/vllm-project/vllm/blob/ced6857afa0ea7b2e3f0846a62e1394e90f15607/docs/getting_started/quickstart.md) — получено 2026-09-28
5. [vLLM v0.30.0 — Server security guidance](https://github.com/vllm-project/vllm/blob/ced6857afa0ea7b2e3f0846a62e1394e90f15607/docs/usage/security.md) — получено 2026-09-28
6. [vLLM v0.30.0 — Prometheus multiprocess registry](https://github.com/vllm-project/vllm/blob/ced6857afa0ea7b2e3f0846a62e1394e90f15607/vllm/v1/metrics/prometheus.py) — получено 2026-09-28
7. [vLLM v0.30.0 — Prometheus/Grafana example](https://github.com/vllm-project/vllm/blob/ced6857afa0ea7b2e3f0846a62e1394e90f15607/examples/observability/prometheus_grafana/README.md) — получено 2026-09-28
8. [vLLM v0.30.0 — Example Prometheus scrape configuration](https://github.com/vllm-project/vllm/blob/ced6857afa0ea7b2e3f0846a62e1394e90f15607/examples/observability/prometheus_grafana/prometheus.yaml) — получено 2026-09-28