Перейти к основному содержимому

For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://docs.nvidia.com/dynamo/llms.txt. For full content including API reference and SDK examples, see https://docs.nvidia.com/dynamo/llms-full.txt.

LMCache

Введение​

LMCache — это высокопроизводительный слой KV cache, который ускоряет serving LLM за счет семантики prefill once, reuse everywhere. Как описано в официальной документации, LMCache позволяет LLM выполнять prefill каждого текста только один раз, сохраняя KV cache всех переиспользуемых текстов и давая возможность переиспользовать KV cache для любого повторно используемого текста (не обязательно prefix) в любом экземпляре serving engine.

В этом документе описано, как LMCache интегрирован в backend vLLM Dynamo, чтобы обеспечить более высокую производительность и эффективность использования памяти.

Примечания по установке​

Runtime vLLM Dynamo ожидает, что LMCache будет установлен в том же Python-окружении. В поддерживаемых средах (x86_64, Python 3.10-3.13, PyTorch, собранный против CUDA 12.x) опубликованный wheel устанавливается напрямую:

uv pip install lmcache

LMCache публикует только x86_64 manylinux wheels, собранные с CUDA 12. Для aarch64-хостов или хостов, где PyTorch собран под другую основную версию CUDA, собирайте LMCache из исходников под вашу связку torch + CUDA — см. официальный LMCache installation guide.

Примечание о совместимости

LMCacheMPConnector нужна правка из LMCache#3282, которая уже есть в LMCache main, но еще не выпущена. Без нее MP-путь падает на vLLM ≥ 0.20.0 (включая vllm==0.21.0, который Dynamo сейчас закрепляет) с RuntimeError: Unsupported GPUKVFormat: 7 — vLLM 0.20+ использует GPU KV formats 6 / 7, которые MP-путь пока не умеет обрабатывать.

До следующего релиза LMCache собирайте LMCache из исходников с этой PR.

Агрегированный режим​

Конфигурация​

LMCache запускает cache engine как out-of-process sidecar (lmcache server); worker Dynamo подключается к нему через LMCacheMPConnector. Сначала запустите sidecar, затем worker:

lmcache server --l1-size-gb 100 --eviction-policy LRU &

python -m dynamo.vllm \
  --model <model_name> \
  --disable-hybrid-kv-cache-manager \
  --kv-transfer-config '{"kv_connector":"LMCacheMPConnector","kv_role":"kv_both"}'

Настройка​

LMCache MP server настраивается через CLI-аргументы. Полный список флагов lmcache server см. в Configuration Reference.

LMCache MP использует двухуровневую архитектуру хранения: in-memory L1 cache (размер задается --l1-size-gb) плюс необязательные persistent L2 adapters, настраиваемые через --l2-adapter. Поддерживаемые L2 storage backends:

  • POSIX: Стандартный POSIX file I/O на любой файловой системе
  • GDS / GDS_MT: NVIDIA GPU Direct Storage (одно- и многопоточный), обходящий CPU для NVMe SSD, поддерживающих GDS
  • HF3FS: Backend распределенной / общей файловой системы
  • OBJ: Backend object storage
  • AZURE_BLOB: Azure Blob Storage

Развертывание​

Для быстрого запуска используйте предоставленный launch script:

./examples/backends/vllm/launch/agg_lmcache_mp.sh

Это:

  1. Запустит LMCache MP server
  2. Запустит Dynamo frontend
  3. Поднимет одного vLLM worker'а с LMCacheMPConnector, подключенным к sidecar

Архитектура агрегированного режима​

В агрегированном режиме система использует:

  • KV Connector: LMCacheMPConnector
  • KV Role: kv_both (обрабатывает и чтение, и запись)

Раздельный режим​

Раздельный режим разделяет операции prefill и decode на выделенных worker'ов. Это дает лучшее использование ресурсов и масштабируемость для production-развертываний.

Развертывание​

Используйте предоставленный disaggregated launch script (требуется минимум 2 GPU):

./examples/backends/vllm/launch/disagg_lmcache.sh

Это:

  1. Запустит Dynamo frontend
  2. Поднимет decode worker на GPU 0
  3. Дождется инициализации
  4. Поднимет prefill worker на GPU 1 с включенным LMCache

Роли worker'ов​

Decode worker​

  • Назначение: Обрабатывает генерацию токенов (decode phase)
  • Назначение GPU: CUDA_VISIBLE_DEVICES=0
  • Конфигурация LMCache: Использует NixlConnector только для KV transfer между prefill и decode worker'ами

Prefill worker​

  • Назначение: Обрабатывает обработку prompt'ов (prefill phase)
  • Назначение GPU: CUDA_VISIBLE_DEVICES=1
  • Конфигурация LMCache: Использует MultiConnector с коннекторами LMCache и NIXL. Это позволяет prefill worker'у использовать LMCache для KV offloading и NIXL для KV transfer между prefill и decode worker'ами.
  • Флаг: --disaggregation-mode prefill

Архитектура​

Конфигурация KV Transfer​

Система автоматически настраивает KV transfer в зависимости от режима развертывания и типа worker'а:

Aggregated Mode​

kv_transfer_config = KVTransferConfig(
    kv_connector="LMCacheMPConnector",
    kv_role="kv_both",
    kv_connector_extra_config={"lmcache.mp.port": 5555},
)

Prefill worker (Disaggregated Mode)​

kv_transfer_config = KVTransferConfig(
    kv_connector="PdConnector",
    kv_role="kv_both",
    kv_connector_extra_config={
        "connectors": [
            {"kv_connector": "LMCacheConnectorV1", "kv_role": "kv_both"},
            {"kv_connector": "NixlConnector", "kv_role": "kv_both"}
        ]
    }
)

Decode worker (Disaggregated Mode)​

kv_transfer_config = KVTransferConfig(
    kv_connector="LMCacheConnectorV1",
    kv_role="kv_both"
)

Fallback (без LMCache)​

kv_transfer_config = KVTransferConfig(
    kv_connector="NixlConnector",
    kv_role="kv_both"
)

Точки интеграции​

  1. Парсинг аргументов (args.py):

    • Настраивает соответствующие параметры KV transfer
    • Формирует конфигурации connector'ов в зависимости от типа worker'а

  2. Настройка Engine (main.py):

    • Создает vLLM engine с корректной конфигурацией KV transfer
    • Обрабатывает и aggregated, и disaggregated режимы

  3. Жизненный цикл sidecar (launch script):

    • Запускает процесс lmcache server до worker'а Dynamo
    • Останавливает его при выходе через cleanup trap скрипта

Лучшие практики​

  1. Настройка chunk size: Передавайте --chunk-size в lmcache server в зависимости от сценария:

    • Меньшие chunks (128-256): Лучшая гранулярность повторного использования для разнообразного контента
    • Большие chunks (512-1024): Эффективнее для повторяющихся паттернов контента

  2. Выделение памяти: Задавайте --l1-size-gb для lmcache server консервативно:

    • Оставляйте достаточно RAM для других системных процессов
    • Следите за использованием памяти в пиковые нагрузки

  3. Оптимизация workload: LMCache лучше всего работает с:

    • Повторяющимися prompt-паттернами (RAG, многооборотные conversations)
    • Общим контекстом между сессиями
    • Долго работающими сервисами с warm cache

Метрики и мониторинг​

LMCache MP server записывает метрики через OpenTelemetry SDK и публикует их на собственном HTTP admin port (по умолчанию :8080/metrics) с префиксом lmcache_mp_:

curl -s localhost:8080/metrics | grep '^lmcache_mp_'

Метрики vLLM и Dynamo остаются на :8081/metrics Dynamo (задайте DYN_SYSTEM_PORT=8081 на worker'е, чтобы включить этот endpoint).

Подробную информацию о метриках LMCache, включая полный список доступных метрик и способы доступа к ним, см. в разделе LMCache Metrics в vLLM Prometheus Metrics Guide.

Устранение неполадок​

Лог vLLM: Found PROMETHEUS_MULTIPROC_DIR was set by user​

vLLM v1 использует prometheus_client.multiprocess и хранит промежуточные значения метрик в PROMETHEUS_MULTIPROC_DIR.

  • Если вы задали PROMETHEUS_MULTIPROC_DIR сами, vLLM предупреждает, что каталог нужно очищать между запусками, чтобы избежать устаревших или неверных метрик.
  • При запуске через Dynamo wrapper vLLM может внутренне задать PROMETHEUS_MULTIPROC_DIR как временный каталог, чтобы избежать проблем с очисткой vLLM. Если предупреждение все равно появляется, проверьте, что вы не экспортируете PROMETHEUS_MULTIPROC_DIR в shell или container environment.

Ссылки и дополнительные ресурсы​