Чтобы получить чистый Markdown-контент этой страницы, добавьте .md к этому URL. Полный индекс документации см. по адресу https://docs.nvidia.com/dynamo/llms.txt. Полное содержимое, включая API reference и примеры SDK, доступно по адресу https://docs.nvidia.com/dynamo/llms-full.txt.

FlexKV

Введение

FlexKV - это масштабируемый распределенный runtime для выгрузки KV cache, разработанный командой TACO из Tencent Cloud и NVIDIA совместно с сообществом. Он выступает в роли единого уровня KV-кэширования для inference-движков вроде SGLang, TensorRT-LLM и vLLM.

Основные возможности

• Многоуровневое кэширование: память CPU, локальный SSD и масштабируемое хранилище (облако) для выгрузки KV cache
• Распределенное повторное использование KV cache: совместное использование KV cache между несколькими узлами с помощью распределенного RadixTree
• Высокопроизводительный I/O: поддержка io_uring и GPU Direct Storage (GDS) для ускоренной передачи данных
• Асинхронные операции: операции get и put могут перекрываться с вычислениями благодаря prefetching

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

1. Dynamo установлен с поддержкой vLLM
2. Запущены инфраструктурные сервисы:

   docker compose -f dev/docker-compose.yml up -d

3. FlexKV установлен:

   git clone https://github.com/taco-project/FlexKV.git
   cd FlexKV
   ./build.sh

4. Необязательно: зависимости для выгрузки на SSD (нужны только для многоуровневой выгрузки CPU + SSD):

   apt install liburing-dev libxxhash-dev

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

Включение FlexKV

Установите переменную окружения DYNAMO_USE_FLEXKV и используйте флаг --kv-transfer-config:

export DYNAMO_USE_FLEXKV=1
python -m dynamo.vllm --model Qwen/Qwen3-0.6B --kv-transfer-config '{"kv_connector":"FlexKVConnectorV1","kv_role":"kv_both"}'

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

Базовая настройка

# Terminal 1: Start frontend
python -m dynamo.frontend &

# Terminal 2: Start vLLM worker with FlexKV
DYNAMO_USE_FLEXKV=1 \
FLEXKV_CPU_CACHE_GB=32 \
  python -m dynamo.vllm --model Qwen/Qwen3-0.6B --kv-transfer-config '{"kv_connector":"FlexKVConnectorV1","kv_role":"kv_both"}'

С KV-aware маршрутизацией

Для развертываний с несколькими воркерами и KV-aware routing, чтобы максимизировать повторное использование cache:

# Terminal 1: Start frontend with KV router
python -m dynamo.frontend \
    --router-mode kv \
    --router-reset-states &

# Terminal 2: Worker 1
DYNAMO_USE_FLEXKV=1 \
FLEXKV_CPU_CACHE_GB=32 \
FLEXKV_SERVER_RECV_PORT="ipc:///tmp/flexkv_server_0" \
CUDA_VISIBLE_DEVICES=0 \
python -m dynamo.vllm \
    --model Qwen/Qwen3-0.6B \
    --kv-transfer-config '{"kv_connector":"FlexKVConnectorV1","kv_role":"kv_both"}' \
    --gpu-memory-utilization 0.2 \
    --kv-events-config '{"publisher":"zmq","topic":"kv-events","endpoint":"tcp://*:20080","enable_kv_cache_events":true}' &

# Terminal 3: Worker 2
DYNAMO_USE_FLEXKV=1 \
FLEXKV_CPU_CACHE_GB=32 \
FLEXKV_SERVER_RECV_PORT="ipc:///tmp/flexkv_server_1" \
CUDA_VISIBLE_DEVICES=1 \
python -m dynamo.vllm \
    --model Qwen/Qwen3-0.6B \
    --kv-transfer-config '{"kv_connector":"FlexKVConnectorV1","kv_role":"kv_both"}' \
    --gpu-memory-utilization 0.2 \
    --kv-events-config '{"publisher":"zmq","topic":"kv-events","endpoint":"tcp://*:20081","enable_kv_cache_events":true}'

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

Примечание: Disaggregated FlexKV serving является экспериментальным. Prefill-воркер должен использовать PdConnector с двумя sub-connectors: FlexKVConnectorV1 (выгрузка KV cache) и NixlConnector (P/D KV transfer). Использование одного только FlexKVConnectorV1 в качестве top-level connector в disaggregated mode не поддерживается и приведет к TypeError.

FlexKV можно использовать с disaggregated prefill/decode serving. Prefill-воркер использует FlexKV для выгрузки KV cache, а NIXL отвечает за передачу KV между prefill- и decode-воркерами. PdConnector оборачивает оба connector'а, чтобы они работали совместно.

Поддерживаемая конфигурация connector'ов

Role	Connector	Description
Decode worker	NixlConnector	Забирает KV blocks у prefill-воркера через NIXL
Prefill worker	PdConnector, оборачивающий [FlexKVConnectorV1, NixlConnector]	FlexKV выгружает и поднимает KV blocks; NIXL передает их decode-воркеру

# Terminal 1: Start frontend
python -m dynamo.frontend &

# Terminal 2: Decode worker (without FlexKV)
CUDA_VISIBLE_DEVICES=0 python -m dynamo.vllm --model Qwen/Qwen3-0.6B \
  --kv-transfer-config '{"kv_connector":"NixlConnector","kv_role":"kv_both"}' &

# Terminal 3: Prefill worker (with FlexKV + NIXL via PdConnector)
DYN_VLLM_KV_EVENT_PORT=20081 \
VLLM_NIXL_SIDE_CHANNEL_PORT=20097 \
DYNAMO_USE_FLEXKV=1 \
FLEXKV_CPU_CACHE_GB=32 \
CUDA_VISIBLE_DEVICES=1 \
  python -m dynamo.vllm \
  --model Qwen/Qwen3-0.6B \
  --is-prefill-worker \
  --kv-transfer-config '{"kv_connector":"PdConnector","kv_role":"kv_both","kv_connector_extra_config":{"connectors":[{"kv_connector":"FlexKVConnectorV1","kv_role":"kv_both"},{"kv_connector":"NixlConnector","kv_role":"kv_both"}]},"kv_connector_module_path":"kvbm.vllm_integration.connector"}' \
  --kv-events-config '{"publisher":"zmq","topic":"kv-events","endpoint":"tcp://*:20081","enable_kv_cache_events":true}'

Можно также напрямую использовать предоставленный launch script:

examples/backends/vllm/launch/disagg_flexkv.sh

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

Переменные окружения

Variable	Description	Default
DYNAMO_USE_FLEXKV	Включает интеграцию FlexKV	0 (выключено)
FLEXKV_CPU_CACHE_GB	Размер cache в памяти CPU в GB	Обязательно
FLEXKV_CONFIG_PATH	Путь к YAML-файлу конфигурации FlexKV	Не задан
FLEXKV_SERVER_RECV_PORT	IPC-порт для сервера FlexKV	Auto

Выгрузка только в CPU

Для простой выгрузки в память CPU:

unset FLEXKV_CONFIG_PATH
export FLEXKV_CPU_CACHE_GB=32

Многоуровневая выгрузка CPU + SSD

Для многоуровневой выгрузки с SSD-хранилищем создайте файл конфигурации:

cat > ./flexkv_config.yml <<EOF
cpu_cache_gb: 32
ssd_cache_gb: 1024
ssd_cache_dir: /data0/flexkv_ssd/;/data1/flexkv_ssd/
enable_gds: false
EOF

export FLEXKV_CONFIG_PATH="./flexkv_config.yml"

Параметры конфигурации

Option	Description
cpu_cache_gb	Размер cache в памяти CPU в GB
ssd_cache_gb	Размер SSD cache в GB
ssd_cache_dir	Каталоги SSD cache (несколько SSD разделяются точкой с запятой)
enable_gds	Включает GPU Direct Storage для SSD I/O

Примечание: Полный список параметров конфигурации см. в FlexKV Configuration Reference.

Распределенное повторное использование KV cache

FlexKV поддерживает распределенное повторное использование KV cache для общего использования cache между несколькими узлами. Это позволяет:

• Distributed RadixTree: каждый узел хранит локальный снимок глобального индекса
• Lease Mechanism: обеспечивает валидность данных во время передачи между узлами
• RDMA-based Transfer: использует Mooncake Transfer Engine для высокопроизводительной передачи KV cache

Инструкции по настройке см. в FlexKV Distributed Reuse Guide.

Архитектура

FlexKV состоит из трех основных модулей:

StorageEngine

Инициализирует трехуровневый cache (GPU → CPU → SSD/облако). Он группирует несколько токенов в blocks и хранит KV cache на уровне blocks, сохраняя ту же форму KV, что и в памяти GPU.

GlobalCacheEngine

Control plane, который определяет направление передачи данных и идентифицирует source/destination block ID. Включает:

• RadixTree для сопоставления префиксов
• memory pool для отслеживания использования пространства и запуска eviction

TransferEngine

Data plane, который выполняет передачу данных:

• многопоточность для параллельных передач
• высокопроизводительный I/O (io_uring, GDS)
• асинхронные операции, перекрывающиеся с вычислениями

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

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
  }'

См. также

• FlexKV GitHub Repository
• FlexKV vLLM Adapter Documentation