Home.ru

English | Русский | 中文

kv-persistence

Постоянный KV-кэш для vLLM — перезапуск сервера перестаёт быть пересчётом истории.

kv-persistence записывает вычисленные vLLM-ом KV-блоки промптов на общем диске ВМ-диск и восстанавливает их после перезапусков. Разговор в любом OpenAI-совместимом чат-клиенте на 100 тыс.–1 млн токенов, который раньше после каждого рестарта пересчитывался десятки минут, переиспользует кэш вместо повторного prefill.

Чат-клиент → vLLM (TP4) → LMCacheMPConnector → lmcache-сервер (отдельный процесс)
       → постоянный уровень L2 (nixl_store_dynamic, POSIX) → NVMe

Зачем

• Встроенный prefix cache vLLM живёт в памяти GPU и умирает вместе с процессом. Каждый перезапуск сервера с большими разговорами означал новый предсчёт всей истории.
• Постоянный слой хранит переиспользуемые KV-чанки на общем диске ВМ. Рестарт vLLM (и даже рестарт сервиса кэша) их не стирает: поиск при промахе уходит на диск, а индекс восстанавливается лениво при старте.

Что гарантируется

• Персистентность при рестартах — данные переживают и рестарт vLLM, и полный рестарт сервиса кэша (сценарии A и B в разделе Персистентность и восстановление).
• Ограниченное хранилище — жёсткий лимит (1.5 ТБ по умолчанию; фактическая граница — свободное место на ОБЩЕМ диске ВМ, где также лежат Docker-образы и веса модели) и автоматической эвикцией с мягким порогом (90 %). Кэш никогда сам себя не очищает при старте.
• Пространства совместимости — ревизия модели, токенизатор, KV-тип и чат-шаблон входят в ключ кэша. Несовместимые конфигурации никогда не читают чужие KV-данные; любая неопределённость даёт промах кэша, а не неверное попадание.
• Lossless-хранение — уровень L2 работает только без потерь. Чанки хранятся байт-в-байт (LMCACHE_L2_SERDE=none, дефолт) или со lossless-сжатием zstd/lz4; lossy-квантизация (fp8 / turboquant / lbq) отвергается при старте. Каждый фрейм несёт CRC32: повреждение обнаруживается и трактуется как промах кэша, никогда не возвращается как неверный KV.
• Опциональный мониторинг Prometheus + Grafana — официальный стек наблюдаемости LMCache (OTel Collector + Tempo + Prometheus + Grafana) поставляется в observability/ и поднимается одной командой; кэш полноценно работает и без него.
• Модельно-агностичное ядро — слой кэш-политики отделён от интеграции с моделью; новые модели добавляют конфигурацию, а не код.

Статус

Реализация завершена, офлайн-тесты проходят (143 unit-теста + ещё 34 офлайн интеграционных/конфиговых = 160 пройдено, 2 пропущено; всего 177 — плюс 302 пройдено из 307 в репозитории sikkatu/recipes). Приёмочные hardware-прогоны на 4× RTX PRO 6000 с MiMo-V2.6-Pro (референсная конфигурация) заскриптованы в scripts/test-recovery.sh / scripts/benchmark.sh и запускаются эксплуатирующей стороной. Непроверенные возможности помечены честно — непроверенное не выдаётся за работающее.

С чего начать

• Быстрый старт — установка, настройка, запуск, проверка (один линейный путь)
• Архитектура — как устроено, модель отказов
• Конфигурация — все переменные cache.env, identity.env, lmcache-server.env
• Персистентность и восстановление — приёмочные сценарии и как доказать дисковое попадание
• Хранилище и эвикция — бюджет, квоты, эвикция, дедупликация
• Интеграция с рецептами — KV_PERSIST=1 в лаунчерах sikkatu/recipes
• Безопасность — права, эндпоинты, работа с данными
• Устранение неполадок — что проверять, когда что-то не так
• FAQ — короткие ответы на частые вопросы

Репозиторий: github.com/sikkatu/kv-persistence (Apache-2.0 + NOTICE: форки и пользователи обязаны упоминать sikkatu / kv-persistence; файл NOTICE).