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.

Руководство по KVBM

Диспетчер Dynamo KV Block Manager (KVBM) - это масштабируемый компонент runtime, предназначенный для управления выделением памяти, администрирования и удаленного совместного использования Key-Value (KV) блоков для inference-задач в гетерогенных и распределенных окружениях. Он работает как единый слой памяти и write-through cache для frameworks вроде vLLM и TensorRT-LLM.

KVBM модульный: его можно использовать отдельно через pip install kvbm или как компонент управления памятью в полном стеке Dynamo. Это руководство описывает установку, конфигурацию и развертывание Dynamo KV Block Manager (KVBM) и других систем управления KV cache.

Быстрый старт с готовым контейнером NGC

Самый быстрый путь - использовать опубликованный контейнер Dynamo, в который уже включен KVBM:

docker run --gpus all --rm -it \
  nvcr.io/nvidia/ai-dynamo/vllm-runtime:1.2.0 \
  /bin/bash

Для установки из исходников или пользовательских сборок см. Local Installation и Release Artifacts.

Запуск KVBM отдельно

KVBM можно использовать независимо, без остального стека Dynamo:

pip install kvbm

См. support matrix для совместимости версий.

Сборка из исходников

Чтобы собрать KVBM из исходников, см. подробные инструкции в KVBM bindings README.

Запуск KVBM в Dynamo с vLLM

Настройка Docker

# Запустить etcd для регистрации и обнаружения leader/worker KVBM
docker compose -f dev/docker-compose.yml up -d

Выберите один из вариантов ниже, чтобы получить контейнер Dynamo vLLM со встроенным KVBM. Последующие команды serving в обоих случаях будут одинаковыми.

Вариант A: готовый контейнер NGC (рекомендуется для быстрого старта)

docker run --gpus all --network host --rm -it nvcr.io/nvidia/ai-dynamo/vllm-runtime:1.2.0

См. Local Installation Guide для полной инструкции по настройке и Release Artifacts для доступных версий.

Вариант B: сборка из исходников

# Собрать контейнер dynamo vLLM (KVBM встроен по умолчанию)
# x86_64
python container/render.py --framework vllm --target runtime --output-short-filename --platform linux/amd64
docker buildx build --platform linux/amd64 -t dynamo:latest-vllm-runtime -f container/rendered.Dockerfile .
# arm64 (Grace, Jetson, arm64 EC2)
python container/render.py --framework vllm --target runtime --output-short-filename --platform linux/arm64
docker buildx build --platform linux/arm64 -t dynamo:latest-vllm-runtime -f container/rendered.Dockerfile .

# Запустить контейнер
container/run.sh --image dynamo:latest-vllm-runtime -it --mount-workspace --use-nixl-gds

Агрегированное обслуживание

cd $DYNAMO_HOME/examples/backends/vllm
./launch/agg_kvbm.sh

Проверка развертывания

curl localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-0.6B",
    "messages": [{"role": "user", "content": "Hello, how are you?"}],
    "stream": false,
    "max_tokens": 10
  }'

Альтернатива: прямой запуск `vllm serve`

Можно также напрямую использовать vllm serve с KVBM:

vllm serve --kv-transfer-config '{"kv_connector":"DynamoConnector","kv_role":"kv_both", "kv_connector_module_path": "kvbm.vllm_integration.connector"}' Qwen/Qwen3-0.6B

Запуск KVBM в Dynamo с TensorRT-LLM

Предварительные требования:

Убедитесь, что etcd и nats запущены до старта
KVBM поддерживает только PyTorch backend TensorRT-LLM
Отключите partial reuse (enable_partial_reuse: false), чтобы повысить число попаданий в offloading cache
KVBM требует TensorRT-LLM v1.2.0rc2 или новее

Настройка Docker

# Запустить etcd для регистрации и обнаружения leader/worker KVBM
docker compose -f dev/docker-compose.yml up -d

Выберите один из вариантов ниже, чтобы получить контейнер Dynamo TensorRT-LLM со встроенным KVBM. Последующие команды serving в обоих случаях будут одинаковыми.

Вариант A: готовый контейнер NGC (рекомендуется для быстрого старта)

docker run --gpus all --network host --rm -it nvcr.io/nvidia/ai-dynamo/tensorrtllm-runtime:1.2.0

См. Local Installation Guide для полной инструкции по настройке и Release Artifacts для доступных версий.

Вариант B: сборка из исходников

# Собрать контейнер dynamo TRTLLM (KVBM встроен по умолчанию)
# x86_64
python container/render.py --framework trtllm --target runtime --output-short-filename --cuda-version=13.1 --platform linux/amd64
docker buildx build --platform linux/amd64 -t dynamo:latest-trtllm-runtime -f container/rendered.Dockerfile .
# arm64 with NVIDIA GPUs (GH200, GB200, P6e-GB200 UltraServer — *not* generic Graviton instances, which have no GPU)
python container/render.py --framework trtllm --target runtime --output-short-filename --cuda-version=13.1 --platform linux/arm64
docker buildx build --platform linux/arm64 -t dynamo:latest-trtllm-runtime -f container/rendered.Dockerfile .

# Запустить контейнер
container/run.sh --image dynamo:latest-trtllm-runtime -it --mount-workspace --use-nixl-gds

Агрегированное обслуживание

# Записать конфигурацию LLM API
cat > "/tmp/kvbm_llm_api_config.yaml" <<EOF
backend: pytorch
cuda_graph_config: null
kv_cache_config:
  enable_partial_reuse: false
  free_gpu_memory_fraction: 0.80
kv_connector_config:
  connector_module: kvbm.trtllm_integration.connector
  connector_scheduler_class: DynamoKVBMConnectorLeader
  connector_worker_class: DynamoKVBMConnectorWorker
EOF

# Запустить Dynamo frontend
python3 -m dynamo.frontend --http-port 8000 &

# Поднять модель с KVBM
python3 -m dynamo.trtllm \
  --model-path Qwen/Qwen3-0.6B \
  --served-model-name Qwen/Qwen3-0.6B \
  --extra-engine-args /tmp/kvbm_llm_api_config.yaml &

Проверка развертывания

curl localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-0.6B",
    "messages": [{"role": "user", "content": "Hello, how are you?"}],
    "stream": false,
    "max_tokens": 30
  }'

Альтернатива: использование `trtllm-serve`

trtllm-serve Qwen/Qwen3-0.6B --host localhost --port 8000 --backend pytorch --extra_llm_api_options /tmp/kvbm_llm_api_config.yaml

Запуск Dynamo с SGLang HiCache

Hierarchical Cache (HiCache) в SGLang расширяет хранение KV cache за пределы GPU memory, добавляя host CPU memory. При использовании NIXL в качестве storage backend HiCache интегрируется с инфраструктурой памяти Dynamo.

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

# Запустить SGLang worker с включенным HiCache
python -m dynamo.sglang \
  --model-path Qwen/Qwen3-0.6B \
  --host 0.0.0.0 --port 8000 \
  --enable-hierarchical-cache \
  --hicache-ratio 2 \
  --hicache-write-policy write_through \
  --hicache-storage-backend nixl

# В отдельном терминале запустить frontend
python -m dynamo.frontend --http-port 8000

# Отправить тестовый запрос
curl localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-0.6B",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": false,
    "max_tokens": 30
  }'

Подробнее: см. SGLang HiCache Integration Guide, где есть подробная конфигурация, примеры развертывания и troubleshooting.

Раздельное обслуживание с KVBM

KVBM поддерживает disaggregated serving, где операции prefill и decode выполняются на разных workers. KVBM включается на prefill worker, чтобы выгружать KV cache.

Раздельное обслуживание с vLLM

# 1P1D - один prefill worker и один decode worker
# NOTE: требуется как минимум 2 GPU
cd $DYNAMO_HOME/examples/backends/vllm
./launch/disagg_kvbm.sh

# 2P2D - два prefill worker'а и два decode worker'а
# NOTE: требуется как минимум 4 GPU
cd $DYNAMO_HOME/examples/backends/vllm
./launch/disagg_kvbm_2p2d.sh

Раздельное обслуживание с TRT-LLM

# Запустить prefill worker с KVBM
python3 -m dynamo.trtllm \
  --model-path Qwen/Qwen3-0.6B \
  --served-model-name Qwen/Qwen3-0.6B \
  --extra-engine-args /tmp/kvbm_llm_api_config.yaml \
  --disaggregation-mode prefill &

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

Конфигурация уровней cache

Настройте уровни cache KVBM с помощью переменных окружения:

# Вариант 1: только CPU cache (offloading GPU -> CPU)
export DYN_KVBM_CPU_CACHE_GB=4  # 4GB of pinned CPU memory

# Вариант 2: и CPU cache, и Disk cache (многоуровневый offloading GPU -> CPU -> Disk)
export DYN_KVBM_CPU_CACHE_GB=4
export DYN_KVBM_DISK_CACHE_GB=8  # 8GB of disk

# [Экспериментально] Вариант 3: только Disk cache (прямой offloading GPU -> Disk)
# NOTE: Экспериментально, может не обеспечить оптимальную производительность
# NOTE: Фильтрация disk offload не поддерживается с этим вариантом
export DYN_KVBM_DISK_CACHE_GB=8

Можно также задать точное число блоков вместо GB:

DYN_KVBM_CPU_CACHE_OVERRIDE_NUM_BLOCKS
DYN_KVBM_DISK_CACHE_OVERRIDE_NUM_BLOCKS

[!NOTE] KVBM - это write-through cache, и его можно неправильно настроить. При добавлении новых уровней каждый следующий capacity должен быть больше предыдущего. Например, если для GPU device выделено 100GB памяти под KV cache storage, то задайте DYN_KVBM_CPU_CACHE_GB >= 100. То же относится и к disk cache: DYN_KVBM_DISK_CACHE_GB >= DYN_KVBM_CPU_CACHE_GB. Если cpu cache настроен меньше, чем device cache, от KVBM не будет никакой пользы. Во многих случаях вы увидите ухудшение производительности, потому что KVBM будет постоянно переливать блоки с GPU в CPU после каждого forward pass. Чтобы понять, каким должно быть минимальное значение DYN_KVBM_CPU_CACHE_GB для вашей конфигурации, обратитесь к настройкам kv cache вашего llm engine.

Защита срока службы SSD

Когда включен disk offloading, фильтрация disk offload по умолчанию включается, чтобы продлить срок службы SSD. Текущая политика выгружает KV blocks с CPU на disk только если frequency блоков ≥ 2. Frequency удваивается при cache hit (начальное значение 1) и уменьшается на 1 на каждом шаге time decay.

Чтобы отключить фильтрацию disk offload:

export DYN_KVBM_DISABLE_DISK_OFFLOAD_FILTER=true

Реплицированный режим NCCL для MLA-моделей

Для MLA (Multi-Layer Attention) моделей, таких как DeepSeek, KVBM может использовать NCCL replicated mode, чтобы только rank 0 загружал KV blocks из хранилища G2/G3, а затем broadcast'ил их на все GPU через NCCL. Это избавляет от повторных загрузок и может улучшить производительность, когда несколько GPU используют один и тот же replicated KV cache.

Включить NCCL MLA mode:

export DYN_KVBM_NCCL_MLA_MODE=true

Требования:

MPI должен быть инициализирован (например, при запуске через mpirun или эквивалент), чтобы rank и world size были доступны для NCCL.
Для оптимальной broadcast-based replication соберите KVBM с фичей NCCL: cargo build -p kvbm --features nccl. Без этого connector вернется к worker-level replication (каждый GPU загружает данные независимо).

Когда режим отключен (по умолчанию), каждый GPU загружает KV blocks независимо. Установите DYN_KVBM_NCCL_MLA_MODE=true, чтобы при запуске MLA-моделей с KVBM использовать NCCL broadcast optimization.

Включение и просмотр метрик KVBM

Настройка стека мониторинга

# Запустить базовые сервисы (etcd и natsd), а также Prometheus и Grafana
docker compose -f dev/docker-observability.yml up -d

Включить метрики для vLLM

DYN_KVBM_METRICS=true \
DYN_KVBM_CPU_CACHE_GB=20 \
python -m dynamo.vllm \
    --model Qwen/Qwen3-0.6B \
    --enforce-eager \
    --kv-transfer-config '{"kv_connector":"DynamoConnector","kv_connector_module_path":"kvbm.vllm_integration.connector","kv_role":"kv_both"}'

Включить метрики для TensorRT-LLM

DYN_KVBM_METRICS=true \
DYN_KVBM_CPU_CACHE_GB=20 \
python3 -m dynamo.trtllm \
  --model-path Qwen/Qwen3-0.6B \
  --served-model-name Qwen/Qwen3-0.6B \
  --extra-engine-args /tmp/kvbm_llm_api_config.yaml &

Настройка firewall (необязательно)

# Если firewall блокирует порты метрик KVBM
sudo ufw allow 6880/tcp

Просмотр метрик

Откройте Grafana по адресу http://localhost:3000 (логин по умолчанию: dynamo/dynamo) и найдите KVBM Dashboard.

Доступные метрики

Метрика	Описание
`kvbm_matched_tokens`	Количество совпавших токенов
`kvbm_offload_blocks_d2h`	Выгруженные blocks с device в host
`kvbm_offload_blocks_h2d`	Выгруженные blocks с host на disk
`kvbm_offload_blocks_d2d`	Выгруженные blocks с device на disk (минуя host)
`kvbm_onboard_blocks_d2d`	Загруженные blocks с disk на device
`kvbm_onboard_blocks_h2d`	Загруженные blocks с host на device
`kvbm_host_cache_hit_rate`	Коэффициент попаданий в host cache (0.0-1.0)
`kvbm_disk_cache_hit_rate`	Коэффициент попаданий в disk cache (0.0-1.0)

Бенчмаркинг KVBM

Для оценки производительности KVBM используйте LMBenchmark.

Подготовка

git clone https://github.com/LMCache/LMBenchmark.git
cd LMBenchmark/synthetic-multi-round-qa

Запуск бенчмарка

# Synthetic multi-turn chat dataset
# Arguments: model, endpoint, output prefix, qps
./long_input_short_output_run.sh \
    "Qwen/Qwen3-0.6B" \
    "http://localhost:8000" \
    "benchmark_kvbm" \
    1

В выводе будут средние TTFT и другие показатели производительности.

СОВЕТ: Если метрики включены, следите за KV offloading и onboarding на dashboard Grafana.

Сравнение с baseline

Базовый vLLM без KVBM

vllm serve Qwen/Qwen3-0.6B

Базовый TensorRT-LLM без KVBM

# Создать конфигурацию без kv_connector_config
cat > "/tmp/llm_api_config.yaml" <<EOF
backend: pytorch
cuda_graph_config: null
kv_cache_config:
  enable_partial_reuse: false
  free_gpu_memory_fraction: 0.80
EOF

trtllm-serve Qwen/Qwen3-0.6B --host localhost --port 8000 --backend pytorch --extra_llm_api_options /tmp/llm_api_config.yaml

Поиск и устранение неполадок

Нет улучшения TTFT

Симптом: Включение KVBM не дает улучшения TTFT или приводит к деградации производительности.

Причина: Недостаточно попаданий в prefix cache на KVBM, чтобы повторно использовать выгруженные KV blocks.

Решение: Включите метрики KVBM и проверьте Grafana dashboard на наличие Onboard Blocks - Host to Device и Onboard Blocks - Disk to Device. Большое число onboarded KV blocks говорит о хорошем повторном использовании cache:

Grafana Example

Тайм-аут инициализации KVBM Worker

Симптом: KVBM не запускается при выделении большого объема memory или disk storage.

Решение: Увеличьте leader-worker initialization timeout (по умолчанию: 1800 секунд):

export DYN_KVBM_LEADER_WORKER_INIT_TIMEOUT_SECS=3600  # 1 hour

Выгрузка на диск не запускается

Симптом: KVBM не запускается, когда включен disk offloading.

Причина: fallocate() не поддерживается файловой системой (например, Lustre, некоторые network filesystems), или storage backend требует другого способа установки O_DIRECT.

Решение:

Если fallocate() не поддерживается, включите zerofill fallback:

export DYN_KVBM_DISK_ZEROFILL_FALLBACK=true

Если файловая система игнорирует fcntl(F_SETFL, O_DIRECT) (например, IBM Storage Scale), задайте тип disk allocator так, чтобы O_DIRECT передавался в момент открытия файла:

export DYN_KVBM_DISK_ALLOCATOR_TYPE=open-direct

Поддерживаемые значения DYN_KVBM_DISK_ALLOCATOR_TYPE:

default: применяет O_DIRECT через fcntl после создания файла. Работает на большинстве POSIX файловых систем (ext4, XFS, Lustre и т. д.).
open-direct: передает O_DIRECT в mkostemp в момент открытия файла. Требуется на файловых системах, где fcntl(F_SETFL, O_DIRECT) игнорируется (например, IBM Storage Scale).

Если вы видите "write all error" или EINVAL (errno 22), либо нужно отладить работу без O_DIRECT:

export DYN_KVBM_DISK_DISABLE_O_DIRECT=true

Локальная разработка

Внутри контейнера Dynamo, после изменений в коде, связанном с KVBM (Rust и/или Python):

cd /workspace/lib/bindings/kvbm
uv pip install maturin[patchelf]
maturin build --release --out /workspace/dist
uv pip install --upgrade --force-reinstall --no-deps /workspace/dist/kvbm*.whl

Чтобы использовать Nsight Systems для анализа производительности, выполните шаги ниже (на примере vLLM). У KVBM есть NVTX-аннотации на верхнеуровневых KV Connector API (ищите @nvtx_annotate). Если нужно больше, добавьте их и пересоберите.

# собрать и запустить local-dev container, в котором есть nsys
python container/render.py --framework=vllm --target=local-dev --output-short-filename
docker build --build-arg USER_UID=$(id -u) --build-arg USER_GID=$(id -g) -f container/rendered.Dockerfile -t dynamo:latest-vllm-local-dev .

container/run.sh --image dynamo:latest-vllm-local-dev -it --mount-workspace --use-nixl-gds

# добавить nsys в PATH
# NOTE: подберите версию соответствующим образом
export PATH=/opt/nvidia/nsight-systems/2025.5.1/bin:$PATH

# пример использования nsys: задержка 30 секунд, затем сбор 60 секунд
python -m dynamo.frontend &

DYN_KVBM_CPU_CACHE_GB=10 \
nsys profile -o /tmp/kvbm-nsys --trace-fork-before-exec=true --cuda-graph-trace=node --delay 30 --duration 60 \
python -m dynamo.vllm --model Qwen/Qwen3-0.6B --kv-transfer-config '{"kv_connector":"DynamoConnector","kv_connector_module_path":"kvbm.vllm_integration.connector","kv_role":"kv_both"}'

См. также

KVBM Overview - краткий обзор KV Caching, KVBM и его архитектуры
KVBM Design - подробный разбор архитектуры KVBM
LMCache Integration
FlexKV Integration
SGLang HiCache

Быстрый старт с готовым контейнером NGC​

Запуск KVBM отдельно​

Сборка из исходников​

Запуск KVBM в Dynamo с vLLM​

Настройка Docker​

Агрегированное обслуживание​

Проверка развертывания​

Альтернатива: прямой запуск vllm serve​

Запуск KVBM в Dynamo с TensorRT-LLM​

Настройка Docker​

Агрегированное обслуживание​

Проверка развертывания​

Альтернатива: использование trtllm-serve​

Запуск Dynamo с SGLang HiCache​

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

Раздельное обслуживание с KVBM​

Раздельное обслуживание с vLLM​

Раздельное обслуживание с TRT-LLM​

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

Конфигурация уровней cache​

Защита срока службы SSD​

Реплицированный режим NCCL для MLA-моделей​

Включение и просмотр метрик KVBM​

Настройка стека мониторинга​

Включить метрики для vLLM​

Включить метрики для TensorRT-LLM​

Настройка firewall (необязательно)​

Просмотр метрик​

Доступные метрики​

Бенчмаркинг KVBM​

Подготовка​

Запуск бенчмарка​

Сравнение с baseline​

Базовый vLLM без KVBM​

Базовый TensorRT-LLM без KVBM​

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

Нет улучшения TTFT​

Тайм-аут инициализации KVBM Worker​

Выгрузка на диск не запускается​

Локальная разработка​

См. также​

Быстрый старт с готовым контейнером NGC

Запуск KVBM отдельно

Сборка из исходников

Запуск KVBM в Dynamo с vLLM

Настройка Docker

Агрегированное обслуживание

Проверка развертывания

Альтернатива: прямой запуск `vllm serve`

Запуск KVBM в Dynamo с TensorRT-LLM

Настройка Docker

Агрегированное обслуживание

Проверка развертывания

Альтернатива: использование `trtllm-serve`

Запуск Dynamo с SGLang HiCache

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

Раздельное обслуживание с KVBM

Раздельное обслуживание с vLLM

Раздельное обслуживание с TRT-LLM

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

Конфигурация уровней cache

Защита срока службы SSD

Реплицированный режим NCCL для MLA-моделей

Включение и просмотр метрик KVBM

Настройка стека мониторинга

Включить метрики для vLLM

Включить метрики для TensorRT-LLM

Настройка firewall (необязательно)

Просмотр метрик

Доступные метрики

Бенчмаркинг KVBM

Подготовка

Запуск бенчмарка

Сравнение с baseline

Базовый vLLM без KVBM

Базовый TensorRT-LLM без KVBM

Поиск и устранение неполадок

Нет улучшения TTFT

Тайм-аут инициализации KVBM Worker

Выгрузка на диск не запускается

Локальная разработка

См. также