Skip to content

Quick Start.ru

Jump to bottom
sikkatu edited this page Nov 2, 2026 · 8 revisions

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

Быстрый старт

Один линейный путь: установка → настройка → запуск → проверка. Все команды работают как есть; setup-identity.sh (шаг 3) заполняет и проверяет все значения идентичности автоматически, поэтому ручного поля ревизии заполнять не нужно. Единственная настоятельно рекомендуемая строка вручную — KVP_CACHE_DEVICE (шаг 2), чтобы кэш гарантированно лежал на нужном NVMe: без него проверки завершатся INCONCLUSIVE, а не PASS, но первый запуск ничто не блокирует.

Все команды выполняются на хосте с GPU (и с NVMe, где будет лежать кэш), от пользователя, под которым работает Docker. Не в Docker, не на другой машине. REPO ниже — каталог клона; команды называют его явно, чтобы ничего не приходилось дописывать.

0. Предусловия

  • Linux-хост (любой дистрибутив) с NVIDIA GPU, Docker, закреплённый образ vLLM и локальный каталог модели MiMo-V2.6-Pro.
  • Локальный NVMe со свободным местом не меньше бюджета кэша (1.5 ТБ по умолчанию; фактическая граница — свободное место на конечном диске общего хранилища ВМ).
  • Production-рецепт sikkatu/recipes породный лаунчер позиционируется: скрипты kv-persistence используют из него только tp4.env.example (дайджест IMAGE) и patches/ + MANIFEST.sha256 (монтируются только чтение); сам рецепт не изменяется.

1. Клонируем репозиторий

git clone https://github.com/sikkatu/kv-persistence ~/kv-persistence
cd ~/kv-persistence
REPO=~/kv-persistence

2. Настраиваем кэш

cp "$REPO/configs/generic/cache.env" "$REPO/configs/generic/cache.env.local"

KVP_CACHE_ROOT в копии (по умолчанию /var/lib/kv-persistence/l2) — путь на NVMe для кэша. Оставьте как есть, если NVMe на месте; если нет — поправьте эту строку на путь к NVMe. KVP_CACHE_BUDGET_GB (1500 по умолчанию) — жёсткий бюджет.

3. Идентификация модели (отпечаток)

Одна команда заполняет И проверяет ВСЕ обязательные поля идентичности (KVP_MODEL_REVISION, KVP_TOKENIZER_REVISION, KVP_CHAT_TEMPLATE_DIGEST):

bash "$REPO/scripts/setup-identity.sh" "$HOME/models/<your-model-dir>"

Детерминированные отпечатки выводятся из реально лежащих файлов (индекс весов, файлы токенизатора, чат-шаблон по единому документированному алгоритму) и сразу записываются в configs/mimo-v2.6-pro/identity.env; в конце скрипт проверяет записанную конфигурацию (пространство кэша должно вычислиться). Ручной вставки нет. Если выход ненулевой — идентичность не готова, читайте сообщение.

Уже отслеживаете upstream-коммит SHA? Задайте его сначала — выводятся только оставшиеся поля:

export KVP_MODEL_REVISION="$(curl -fsSL https://huggingface.co/api/models/XiaomiMiMo/MiMo-V2.6-Pro-MOPD | python3 -c 'import json,sys; print(json.load(sys.stdin)["sha"])')"
bash "$REPO/scripts/setup-identity.sh" "$HOME/models/<your-model-dir>"

4. Устанавливаем LMCache CLI

python3 -m venv ~/.venvs/lmcache
~/.venvs/lmcache/bin/pip install --upgrade pip
~/.venvs/lmcache/bin/pip install -r "$REPO/requirements-lmcache.txt"
export PATH="$HOME/.venvs/lmcache/bin:$PATH"

Для создания venv требуется Python 3.12 (runtime production-образа и то, на что ориентирован requirements-lmcache.txt). На Debian/Ubuntu (tested on Debian 12) системный Python — 3.11: установите интерпретатор 3.12 (например, из bookworm-backports или через pyenv) и используйте python3.12 -m venv ~/.venvs/lmcache. Пакет python3-venv на Debian ставится отдельно.

PATH экспортируется только в пределах одного терминала (в новом терминале повторите этот export, если планируете вызывать lmcache напрямую). В КАЖДОМ новом терминале повторяйте экспорты (REPO, IMAGE, MODEL_DIR, PATH) — переменные shell не переживают смену терминала. Если wheel не совпадает с ABI образа (ошибки импорта), см. Устранение неполадок — запасной вариант запускает lmcache server из самого закреплённого образа.

5. Предварительная проверка

bash "$REPO/scripts/preflight.sh"

preflight PASSED — можно двигаться дальше. Каждое [!!] говорит, что именно починить. Один раз запустите с каталогом модели — digest чат-шаблона посчитается автоматически:

KVP_MODEL_DIR="$HOME/models/<your-model-dir>" bash "$REPO/scripts/preflight.sh"

Ручного копирования здесь не требуется: setup-identity.sh (шаг 3) уже записал digest; команда выше лишь подтверждает совпадение с каталогом модели.

6. Запускаем сервис постоянного кэша

bash "$REPO/scripts/start-cache.sh"

Сервис запущен отвязанно (setsid nohup), поэтому переживает обрыв SSH и закрытие этого терминала; лог и pid — под KVP_CACHE_ROOT. Ранее закэшированные данные сохраняются — старт никогда не стирает кэш.

Опционально: lossless-сжатие

По умолчанию чанки хранятся байт-в-байт (LMCACHE_L2_SERDE=none) — без преобразований и внешних зависимостей. Чтобы хранить их со lossless-сжатием zstd или lz4 (примерно в 1.1–1.4x меньше на реальных KV-данных):

USE_LOSSLESS_SERDE=1 bash "$REPO/scripts/start-cache.sh"     # zstd
USE_LOSSLESS_SERDE=lz4 bash "$REPO/scripts/start-cache.sh"   # lz4

Тот же переключатель нужен и на шаге 7 (он входит в namespace идентичности кэша). zstd требует только пакет zstandard, lz4 — только lz4: проверка до старта требует ровно выбранный кодек, а кэшу none пакеты сжатия не нужны вообще. Каждый фрейм несёт CRC32: повреждение обнаруживается и трактуется как промах кэша, никогда не возвращается как неверный KV.

Опционально: мониторинг Prometheus + Grafana

bash "$REPO/scripts/start-observability.sh"
# Grafana -> http://localhost:3000 (анонимный Admin, без входа)

Затем запустите кэш с USE_OBSERVABILITY=1, чтобы метрики пошли в коллектор. Порты стека привязаны только к 127.0.0.1. Кэш полноценно работает и без стека.

7. Запускаем vLLM с кэшем

Предусловия этого шага (все три обязательны):

  1. Production-рецепт должен лежать на диске по пути, который ожидает лаунчер (либо укажите RECIPE_DIR на него): 
    git clone https://github.com/sikkatu/recipes ~/recipes
    Лаунчер читает tp4.env.example только чтобы переиспользовать закреплённый дайджест IMAGE рецепта и его проверенные по контрольным суммам patches/ (монтируются read-only); сам рецепт никогда не изменяется.
  2. Нужен API_KEY. Лаунчер читает его из live/api_key в текущем каталоге (или из уже экспортированного API_KEY). Если ключа ещё нет: 
    mkdir -p live && openssl rand -hex 24 > live/api_key && chmod 600 live/api_key
  3. MODEL_DIR должен указывать на ТОТ ЖЕ локальный каталог модели, что и на шаге 3 — построенная там идентичность и загружаемые здесь веса обязаны совпадать.
cd "$REPO"
export IMAGE="$(bash "$REPO/scripts/print-recipe-image.sh" "$HOME/recipes/recipes/rtx-pro-6000/mimo-v2.6-pro-hotsplit")"
export MODEL_DIR="$HOME/models/<your-model-dir>"
bash "$REPO/scripts/run-vllm-with-persist.sh"

Лаунчер основан на аргументах production-рецепта и добавляет KV-коннектор, монтирование namespace идентичности кэша, --enable-prompt-tokens-details и зафиксированный --block-size — это НЕ зеркало один в один (ветка KV_PERSIST=1 рецепта теперь совпадает с ним по этим четырём пунктам; см. Интеграция с рецептами). Патчи рецепта проверяются по контрольным суммам и монтируются только на чтение.

8. Проверяем

bash "$REPO/scripts/verify-engine-identity.sh"   # обязательный барьер: конфиг движка == пины identity
bash "$REPO/scripts/test-recovery.sh"            # приёмка: PASS / INCONCLUSIVE / FAIL (exit 0/5/1)

test-recovery.sh вызывает verify-engine-identity.sh ДО любого обращения к кэшу: если какой-либо пин identity расходится с запущенным движком, переиспользование кэша отклоняется (exit 4). Если значение нельзя проверить (например KVP_MODEL_DIR не задан), прогон считается INCONCLUSIVE (exit 5) — никогда тихим PASS. Физическая проверка NVMe идёт через KVP_CACHE_DEVICE; задайте его в cache.env.local, чтобы PASS был достижим.

Разогрев → рестарт vLLM → повторная отправка; затем разогрев → рестарт обоих сервисов → повторная отправка. Скрипт выводит фазовые cached_tokens и доказательства восстановления в benchmarks/results/. Доказательство дискового восстановления — cached_tokens > 0 плюс события чтения из L2/диска в логе кэша после каждого рестарта, что подтверждается физическими счётчиками чтения NVMe — одного ускорения как доказательства никогда не принимается.

Дальше

Clone this wiki locally