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

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

Если локальный API отвечает, но пользователи жалуются на задержки, /metrics позволяет раздельно наблюдать число ожидающих и исполняемых запросов, использование блоков KV-кеша и распределение времени до первого токена. Это серверная телеметрия, не измерение качества ответа модели, не проверка конфиденциальности и не прогноз на любой GPU. Клиентский нагрузочный тест нужен дополнительно, чтобы связать графики с известным потоком запросов. s1 s2 s3

Маршрут: задача → модель с подходящими аппаратными условиями → vLLM → успешный ответ → /metrics → собственная контролируемая нагрузка → решение о ёмкости. Прежде чем смотреть графики, запустите конкретную модель по гайду vLLM, запишите её ревизию и конфигурацию и получите ответ API. Размер файлов весов сам по себе не даёт минимального требования к памяти. s4

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

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

curl -fsS http://127.0.0.1:8000/v1/models
curl -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 s3 s4

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

• vllm:num_requests_waiting и vllm:num_requests_running — мгновенные gauges ожидания и выполнения. В v0.30.0 есть также vllm:num_requests_waiting_by_reason с причинами capacity и deferred. Значение ноль после одиночного запроса не говорит, было ли ожидание во время исполнения. s3
• vllm:kv_cache_usage_perc — доля занятых блоков KV-кеша: 1 означает 100% его ёмкости, а не 100% видеопамяти GPU. Смотрите динамику рядом с очередью и задержкой; одиночный высокий показатель не доказывает сам по себе нехватку RAM/VRAM. s2 s3
• vllm:prefix_cache_queries и vllm:prefix_cache_hits учитывают токены, а не запросы. Доля совпадений за интервал вычисляется как прирост hits / прирост queries при ненулевом знаменателе; накопленные абсолютные значения нельзя выдавать за текущий процент. При отключённом или неиспользуемом prefix cache не выводите «плохую эффективность» из нулевых серий. s2 s3
• vllm:time_to_first_token_seconds и vllm:e2e_request_latency_seconds — гистограммы задержки. _count и _sum дают число наблюдений и их сумму, _bucket — интервалы для оценки квантиля по окну времени; одно мгновенное значение очереди не эквивалентно p95. vllm:request_queue_time_seconds отдельно учитывает ожидание. s2 s3

Не путайте vllm:inter_token_latency_seconds (промежуток между потоковыми порциями) с vllm:request_time_per_output_token_seconds (TPOT за завершённый запрос). При выдаче нескольких токенов за одну порцию, например при speculative decoding, или разных весах усреднения они различаются; vLLM отдельно предупреждает, что TPOT у запроса с одним токеном записывается в Prometheus как ноль, а bench serve исключает такой запрос из своего TPOT. 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 s8

Следующий пример действует только для Prometheus на том же хосте и в том же сетевом namespace, что и vLLM. s7 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 s7 s8

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

1. Снимите /metrics до теста и сохраните время, версию vLLM, модель/ревизию, настройки сервера, GPU и режим кеша. Убедитесь, что работающее API отвечает на обычный тестовый запрос с вымышленным текстом, а не клиентскими данными. s1 s4
2. На изолированном стенде задайте небольшой фиксированный поток через гайд vllm bench serve. Пример документации vLLM сам скачивает набор ShareGPT и использует модель Mistral; это не обязательные компоненты и не соответствует требованию не отправлять реальные данные: здесь выбирайте контролируемый локальный набор и сопоставимые параметры. Не нагружайте рабочий сервер ради красивого графика. s7
3. Во время теста сопоставьте серии num_requests_waiting, num_requests_running, kv_cache_usage_perc с ростом _count гистограмм TTFT/очереди. Сохраните клиентские задержки и число ошибок, повторите тест при тех же длинах запросов и одновременности. Если ожидание и TTFT растут, проверьте конкуренцию, длины входа и условия GPU; это гипотеза диагностики, не доказательство одной причины. s2 s3
4. Зафиксируйте результат как «версия + модель + железо + нагрузка + интервалы метрик + ошибки». Порог тревоги выводите из собственной цели задержки и наблюдаемого поведения, не из условных 80% KV-кеша. Если запросы не завершились, график пуст или Prometheus DOWN, сначала устраните сбой сети/API; пустой график не означает нулевую задержку. s1 s2 s8

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