Вы запустили vLLM. Токены летят. Но вдруг TTFT начинает скакать, память утекает, а воркеры падают без внятной причины. Логи есть, но их много. Prometheus и Grafana вы ещё не настраивали (или настроили, но дашборды пылятся). Что делать?
Снова лезть в исходники vLLM? Писать велосипед на bash с curl и awk? Есть вариант проще — vllm-doctor. Это CLI-утилита, которая за несколько секунд собирает диагноз по вашему инференс-серверу: от состояния KV-кэша до очередей запросов и здоровья GPU.
vllm-doctor не заменяет полноценный мониторинг (Grafana + Prometheus), но даёт быструю картину «прямо сейчас» — идеально для дежурного инженера или первичной диагностики.
Что под капотом? Команды, которые реально нужны
Утилита подключается к эндпоинтам vLLM (health, metrics, stats) и выводит структурированные данные. Три ключевые команды:
vllm-doctor check— прогоняет 15+ правил: проверяет HTTP-статус, версию vLLM, утилизацию GPU, количество свободных слотов KV-кэша, время жизни воркеров. Если что-то не так — подсвечивает красным и даёт рекомендацию.vllm-doctor metrics— выгружает основные прометеевские метрики в читаемом виде: TTFT, TPOT, throughput, количество активных запросов, процент заполнения KV-кэша. Можно указать интервал опроса.vllm-doctor config— парсит запущенный конфиг vLLM и сравнивает с лучшими практиками. Например, проверит, не забыли ли вы включить--enable-prefix-cachingили не выставили ли слишком маленькийmax-model-len.
Главная фишка — встроенные правила диагностики. Вы не просто смотрите на сырые цифры, а получаете вердикт: «KV-кэш заполнен на 92% — пора добавлять ноды» или «TTFT превышает 2 секунды — вероятно, перегрузка CPU, проверьте scheduler». Это экономит часы гугления.
Ставим за 30 секунд
pip install vllm-doctorИли через Docker:
docker run --network host ghcr.io/your-org/vllm-doctor check --uri http://localhost:8000По умолчанию утилита стучится на localhost:8000, но флаг --uri рулит любым адресом. Для работы достаточно включить эндпоинт /metrics в vLLM (он активен по умолчанию).
Пример из жизни: ловим утечку памяти
Сценарий: сервер vLLM на одной A100 держится сутки, потом TTFT ползёт вверх, а память GPU плавно растёт. vllm-doctor check выводит:
$ vllm-doctor check --uri http://10.0.0.42:8000
> Health: OK (200)
> GPU Memory Used: 78.1 GiB / 80.0 GiB (97.6%) 🔴
> KV Cache Usage: 94.2% 🔴
> Scheduler Policy: preempt (1 active request)
> Recommendation: KV cache almost full. Consider increasing --max-num-seqs or reducing max-model-len. Also check MALLOC_* fragmentation — see our guide on glibc heap fragmentation.Подсказка насчёт MALLOC_* — не просто так. Если память GPU не освобождается, проблема часто не в vLLM, а в фрагментации кучи. Инструмент заботливо даёт ссылку на статью (вы уже знаете, о чём я).
Ещё полезный сценарий — динамическая лень. При пиковых нагрузках vllm-doctor metrics покажет резкий рост TTFT. Тут стоит подумать о LazyGate — мы писали как его настроить.
Сравнение: велосипед vs профессионал
| Способ | Время установки | Глубина диагностики | Готовые правила |
|---|---|---|---|
| Самописный скрипт + curl | 1-2 часа | Низкая (сырые метрики) | Нет |
| Grafana + Prometheus | День-два | Высокая (история) | Нужно создавать |
| vllm-doctor | 5 минут | Средняя (текущий срез) | 15+ встроенных |
Да, Grafana даёт тренды за неделю. Но чтобы понять, почему сервер лёг прямо сейчас, vllm-doctor удобнее. Особенно если вы быстро разворачиваете ноды и не хотите тащить за каждой тяжёлую обвязку.
Кстати, похожий подход используется в MCP Doctor — только для отладки конфигов MCP. Тот же принцип: запустил, увидел проблему, исправил.
А что с гибридными и старыми железками?
vllm-doctor работает с любым vLLM сервером, будь то облачный GPU или Dell T7910. Если вы используете гибридную архитектуру (локальный CPU + облачный GPU), утилита всё равно показывает метрики по тому инстансу, куда стучится. Главное — чтобы эндпоинты были доступны.
Важно: vllm-doctor не управляет сервером — только читает. Не бойтесь пускать его в прод, он не сломает инференс.
Кому на самом деле нужен этот инструмент?
- MLOps-инженерам, у которых десятки LLM-серверов и нет времени разворачивать Prometheus на каждом.
- Dev-командам, тестирующим новую модель: быстро проверить, не упёрлась ли в лимиты.
- Админам старых ферм — чтобы не умереть от ручного гребка логов.
- Тем, кто хочет автоматизировать алертинг: vllm-doctor легко встраивается в скрипты — парсите JSON-вывод и шлёте в Telegram.
Важный момент: утилита не требует доступа к файловой системе сервера — только HTTP. Значит, можно мониторить инстансы, к которым у вас нет SSH. Идеально для SaaS-провайдеров.
Грабли, которые vllm-doctor показывает до того, как вы на них наступите
Попробуйте запустить vllm-doctor config на вашей продакшн-конфигурации. Скорее всего, он найдёт что-то, о чём вы не знали. Например, отключённый prefix caching или слишком агрессивный max-num-seqs, из-за которого падает throughput. Сравнить свои настройки с лучшими практиками — бесценно.
Кстати, если вы ещё не настраивали мониторинг «по-взрослому», вот полный гайд по Grafana + Prometheus. Но даже с ним vllm-doctor пригодится как быстрый «фонарик».
Напоследок — совет. Не держите vllm-doctor только в голове. Запишите в ~/.bashrc алиас: alias doctor='vllm-doctor check --uri $VLLM_URI'. И когда что-то пойдёт не так, вы сэкономите 10 минут на том, чтобы вспомнить, где лежит ссылка на метрики.
А если захотите автоматизировать проверки — интегрируйте его с GitOps-пайплайном: перед деплоем новой модели прогоняйте check, и только если зелёный — пушите.
