Repository navigation
Configuration.ru
Три файла, их читают все скрипты. Переменные, уже экспортированные в окружении,
имеют приоритет над файлами (удобно для разовых переопределений). Локальные правки —
в configs/generic/cache.env.local (в .gitignore); поставляемые файлы не правьте.
| Переменная | По умолчанию | Назначение |
|---|---|---|
KVP_CACHE_BUDGET_GB |
1500 |
Жёсткий лимит постоянного кэша в ГБ (1.5 ТБ намеренно большой — сохраняет больше истории prefill). Фактическая граница — свободное место на общем диске ВМ (там же Docker и веса модели). |
KVP_CACHE_ROOT |
/var/lib/kv-persistence/l2 |
Каталог кэша. ОБЯЗАН лежать на локальном NVMe; сетевой диск ломает атомарный rename (preflight предупреждает). |
KVP_EVICT_TRIGGER_WATERMARK |
0.9 |
Мягкий порог: эвикция начинается с этой доли бюджета. Отличается от жёсткого лимита. |
KVP_EVICT_RATIO |
0.1 |
Что возвращается за один цикл эвикции (доля занятой ёмкости). |
KVP_LMCACHE_HOST |
127.0.0.1 |
Хост запросов lmcache (ZMQ). Оставляйте loopback. |
KVP_LMCACHE_PORT |
5555 |
Порт запросов lmcache. |
KVP_LMCACHE_HTTP_PORT |
8080 |
HTTP-фронтенд управления/метрик. Только loopback — по дизайну. |
KVP_L1_SIZE_GB |
64 |
Буфер L1 в RAM хоста между vLLM и NVMe. |
KVP_CHUNK_SIZE |
256 |
Гранулярность KV-чанка в токенах (задокументированный продовый дефолт). |
KVP_PERSIST_ENABLED |
true |
Сохранять файлы при выключении. false удаляет их — ломает главное требование. |
KVP_CACHE_BYPASS |
0 |
1 = постоянный кэш выключен (для A/B-сравнений). |
KVP_NAMESPACE_HINT |
(пусто) | Только человекочитаемая метка; на совместимость НЕ влияет. |
Каждое значение участвует в пространстве кэша. Любое изменение делает старые записи несовместимыми (промах — никогда неверные данные). Пустое значение = ошибка.
| Переменная | Форма значения | Примечания |
|---|---|---|
KVP_MODEL_ID |
HF-id | например XiaomiMiMo/MiMo-V2.6-Pro-MOPD
|
KVP_MODEL_REVISION |
полный 40-hex SHA | коммит используемых весов |
KVP_TOKENIZER_NAME |
имя/путь | обычно тот же репозиторий |
KVP_TOKENIZER_REVISION |
полный 40-hex SHA | как веса, если не разведено намеренно |
KVP_KV_CACHE_DTYPE |
разрешённый dtype | KV-тип ДВИЖКА, записывается как в vLLM CacheDType: float16 / bfloat16 / fp8*; auto отклоняется. Синонимы fp16/bf16 закреплённая сборка (vllm 8e2beaa3) НЕ принимает — движок с ними не стартует (preflight предупреждает). Это формат KV, который вычисляет vLLM — НЕ кодек хранения L2 (см. LMCACHE_L2_SERDE ниже). fp8 здесь — легитимный тип движка и никак не связан с lossy-сжатием L2. |
KVP_BLOCK_SIZE |
int | размер KV-блока в токенах (из лога движка) |
KVP_NUM_KV_HEADS |
int | из конфига модели |
KVP_HEAD_DIM |
int | из конфига модели |
KVP_TP_SIZE |
int | 4 для этой конфигурации |
KVP_CONNECTOR |
имя | LMCacheMPConnector |
KVP_CONNECTOR_VERSION |
строка-пин | например vllm-<commit>@lmcache-mp
|
KVP_MAX_MODEL_LEN |
int | 1048576 |
KVP_CHAT_TEMPLATE_DIGEST |
64 hex | считает preflight из каталога модели |
KVP_LORA_ADAPTERS |
(опционально) | через запятую <adapter-id>@<revision> — реально подключённые LoRA при подаче. Пусто = без LoRA. Заданное значение меняет namespace — деплои с разными LoRA не должны делить кэшированный KV. |
KVP_MULTIMODAL_COMPONENTS |
(опционально) | через запятую <component-id>@<revision> — реально подаваемые компоненты (vision/audio-энкодеры). Пусто = нет. Заданное значение меняет namespace.
|
KVP_ROPE_CONFIG_DIGEST |
(опционально, 64 hex) | sha256 реально действующей конфигурации RoPE (scaling/theta/sections). Пусто = без изменений/по умолчанию. Заданное значение меняет namespace — смена RoPE меняет позиции токенов, старый KV переиспользовать нельзя. |
KVP_SPECULATIVE_CONFIG |
(опционально) | стабильная метка активных speculative/MTP/draft настроек (напр. mtp-draft@rev, num_speculative_tokens=2). Пусто = выключено. Заданное значение меняет namespace.
|
Все четыре расширенных поля читаются kvpersist.identity и включаются в
namespace кэша и model_name. Пустое значение легально («не применимо»);
задание любого из них разделяет namespace (безопасный промах).
| Переменная | По умолчанию | Назначение |
|---|---|---|
LMCACHE_HOST / LMCACHE_PORT
|
127.0.0.1 / 5555
|
ZMQ-эндпоинт запросов, куда подключается vLLM |
LMCACHE_HTTP_HOST / LMCACHE_HTTP_PORT
|
127.0.0.1 / 8080
|
фронтенд управления — только loopback |
LMCACHE_L1_SIZE_GB |
64 |
уровень L1 в RAM |
LMCACHE_CHUNK_SIZE |
256 |
гранулярность чанка (токены) |
LMCACHE_EVICTION_POLICY |
LRU |
оба уровня |
LMCACHE_EVICTION_TRIGGER_WATERMARK |
0.9 |
мягкий порог L2 |
LMCACHE_EVICTION_RATIO |
0.1 |
возврат за цикл |
LMCACHE_L2_SERDE |
none |
Кодек L2, только lossless: none = байт-точный сырой KV; zstd / lz4 = lossless-сжатие (оценка 1.1–1.4x). Lossy-кодеки (fp8 / turboquant / lbq) отвергаются при старте. Кодек входит в namespace идентичности кэша. |
LMCACHE_LOG_LEVEL |
DEBUG |
Уровень логирования сервиса кэша. DEBUG необходим для аппаратной приёмки (scripts/test-recovery.sh): строки-доказательства L2 store/load (L2 store completed: adapter N, N succeeded, L2 prefetch load completed: request N, N loaded, Prefetch request completed (L1+L2)) в закреплённой сборке LMCache 0.5.3 пишутся на уровне DEBUG — без него регэкспы приёмки ничего не найдут, и прогон станет INCONCLUSIVE. Для меньшего лога без приёмки используйте INFO. |
KVP_L2_COMPRESS_LEVEL |
3 |
уровень zstd (1–19, lz4 игнорирует) |
USE_LOSSLESS_SERDE |
(не задано) | операторский переключатель: 1/zstd = zstd, lz4 = lz4, 0/пусто = оставить LMCACHE_L2_SERDE. Применяется только когда LMCACHE_L2_SERDE не экспортирован (env выигрывает). |
KVP_OTLP_ENDPOINT |
(не задано) | OTLP gRPC endpoint для метрик кэша (например http://localhost:4320). Телеметрия по умолчанию выключена. |
USE_OBSERVABILITY |
(не задано) |
1 = сокращение для KVP_OTLP_ENDPOINT=http://localhost:4320
|
LMCACHE_OTLP_ENDPOINT |
(не задано) | тот же endpoint под именем LMCACHE_*; выигрывает у KVP_OTLP_ENDPOINT
|
Зависимости кодеков (fail-fast до старта, требуется только выбранный):
none — ничего; zstd — только zstandard; lz4 — только lz4.
- Поправьте
KVP_CACHE_BUDGET_GBвcache.env.local. -
bash scripts/stop-cache.sh && bash scripts/start-cache.sh— данные сохраняются. -
bash scripts/budget-report.sh status— убедиться в новом бюджете.
Повышение требует свободного места. Снижение ниже текущего занятия немедленно блокирует новые записи; эвикция затем подчищает до целевого уровня.
bash scripts/budget-report.sh quota --set-namespace=NAME --gb 200
bash scripts/budget-report.sh quota # списокИмена пространств берутся из budget-report.sh status (поле namespaces);
используйте форму --set-namespace=NAME, потому что реальные имена часто
начинаются с -.
Что квоты делают и чего НЕ делают. Квоты — это слой политики и учёта:
они записывают лимит пространства и позволяют отчётам показать, какое пространство
его превышает. Они НЕ подключены к производственному пути записи — решение
BudgetLedger.admit() не вызывается адаптером LMCache, поэтому пространство может
превысить квоту, и ничто не отклонит запись. Единственная жёсткая граница ёмкости,
применяемая к записям, — max_capacity_gb адаптера (KVP_CACHE_BUDGET_GB) для
L2 целиком. Считайте квоты инструментом планирования/учёта, пока интеграционный
тест не подтвердит принуждение.
Экспортированные переменные всегда важнее файлов. Пример разового изменения:
KVP_CACHE_BUDGET_GB=500 bash scripts/start-cache.shExport терминала неперсистентен — в новых терминалах повторите (так работает shell, это не баг).