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.

Передача KV с учетом топологии

Передача KV с учетом топологии ограничивает выбор decode worker или смещает его после того, как выбран prefill worker. Router выводит стандартные RoutingConstraints из опубликованных топологических метаданных выбранного prefill worker, а затем объединяет эти ограничения с decode request.

По возможности используйте путь через Kubernetes operator. Примеры развертывания см. в разделе Передача KV с учетом топологии в Kubernetes.

Контракт runtime

Workers публикуют поля топологии и политики через ModelRuntimeConfig:

Поле	Значение
`topology_domains`	Отображение имени логического домена в значение топологии этого worker, например `{"zone": "us-east-1a"}`.
`kv_transfer_domain`	Ключ домена, используемый для маршрутизации KV transfer от prefill к decode, например `zone`.
`kv_transfer_enforcement`	`required` или `preferred`.
`kv_transfer_preferred_weight`	Вес preferred-taint, используемый только когда enforcement равен `preferred`.

Каждая запись топологии также становится канонической taint worker:

dynamo.topology/<domain>=<value>

Например:

{
  "topology_domains": {
    "zone": "us-east-1a",
    "rack": "rack-22"
  },
  "kv_transfer_domain": "zone",
  "kv_transfer_enforcement": "preferred",
  "kv_transfer_preferred_weight": 0.85
}

Это создает worker taints:

dynamo.topology/zone=us-east-1a
dynamo.topology/rack=rack-22

Политика KV-transfer использует только kv_transfer_domain для вывода decode constraint. Остальные домены топологии остаются доступны как обычные routing taints.

Поток запроса

sequenceDiagram
    participant F as Frontend
    participant PR as Prefill Router
    participant P as Prefill Worker
    participant DR as Decode Router
    participant D as Decode Worker

    F->>PR: request
    PR->>P: select prefill worker
    PR->>PR: read selected worker topology metadata
    PR->>PR: build RoutingConstraints
    PR->>DR: decode request + topology constraints
    DR->>D: select compatible or preferred decode worker

Prefill router формирует decode constraint до отправки prefill, если выбранный worker уже известен. Это делает политику required fail-closed: если router не может вывести authoritative decode constraints для требуемой политики, он завершает request с ошибкой вместо того, чтобы отправить prefill и только потом обнаружить, что decode нельзя безопасно маршрутизировать.

Режимы enforcement

Required

required превращает топологию transfer-domain выбранного prefill worker в required taint.

required_taints = {"dynamo.topology/zone=us-east-1a"}

Decode worker без такой taint не подходят. Если подходящий decode worker отсутствует, routing не возвращает endpoint для этого request.

Preferred

preferred превращает ту же топологию в preferred taint.

preferred_taints = {"dynamo.topology/zone=us-east-1a": 0.85}

Все decode worker по-прежнему подходят, но совпадающие worker получают меньшую routing cost. preferredWeight задает силу предпочтения в диапазоне от 0 до 1.

Контракт среды worker

Утилита Python backend читает топологию из файлов, а политику передачи — из переменных окружения:

Переменная окружения	Описание
`DYN_TOPOLOGY_ENABLED`	Установите в `true`, чтобы включить чтение топологии.
`DYN_TOPOLOGY_MOUNT_PATH`	Каталог, содержащий файлы топологии. По умолчанию `/etc/dynamo/topology`.
`DYN_KV_TRANSFER_DOMAIN`	Обязательно, когда топология включена. Задает имя файла топологии и runtime domain, используемые для KV transfer constraints.
`DYN_KV_TRANSFER_ENFORCEMENT`	`required` или `preferred`. По умолчанию `required`, если домен задан.
`DYN_KV_TRANSFER_PREFERRED_WEIGHT`	Вес, используемый когда enforcement равен `preferred`.

Каждый не скрытый и непустой файл в DYN_TOPOLOGY_MOUNT_PATH интерпретируется как один домен топологии. Имя файла — это домен, а содержимое файла — значение worker для этого домена.

Например:

mkdir -p /tmp/dynamo-topology
printf 'us-east-1a\n' > /tmp/dynamo-topology/zone

export DYN_TOPOLOGY_ENABLED=true
export DYN_TOPOLOGY_MOUNT_PATH=/tmp/dynamo-topology
export DYN_KV_TRANSFER_DOMAIN=zone
export DYN_KV_TRANSFER_ENFORCEMENT=required

Когда топология включена, worker опрашивает систему, пока файл выбранного transfer-domain не появится и не получит содержимое. Если он остается отсутствующим или пустым до истечения таймаута, worker завершает работу, чтобы проблема с источником топологии была видна при запуске.

Поддержка backend

Интегрированные Python backend применяют конфигурацию топологии во время регистрации worker:

vLLM
SGLang
TensorRT-LLM

Утилита топологии записывает поля в ModelRuntimeConfig; валидация и генерация канонических topology-taint находятся на стороне Rust.

Взаимодействие с существующими RoutingConstraints

Передача KV с учетом топологии использует существующий путь RoutingConstraints. Она не добавляет отдельный selector для топологии. Если у request уже есть routing constraints, prefill router объединяет сгенерированные топологические ограничения с decode request:

Required topology taints добавляются к существующим required_taints.
Preferred topology taints добавляются к существующим preferred_taints.

Пользовательские ограничения по-прежнему применяются. Decode worker должен удовлетворять всем required constraints, чтобы считаться подходящим.

Операционные замечания

Настраивайте это только для disaggregated prefill/decode развертываний. Aggregated workers не выполняют удаленную передачу KV от prefill к decode.
Оставляйте DYN_ROUTER_MODE=kv на frontend, чтобы пути маршрутизации prefill и decode использовали KV router.
Убедитесь, что у каждого prefill domain достаточно decode capacity при использовании required; иначе router может корректно отклонять requests в доменах без decode worker.
Используйте preferred во время поэтапных rollout, когда передача внутри одного домена является предпочтением по latency, а не жестким требованием к размещению.
Состояние транспорта отделено от выбора топологии. Маршрутизация с учетом топологии выбирает более подходящего peer, но RDMA, EFA, UCX или libfabric все равно должны быть настроены корректно для NIXL KV transfer.

Диагностические сигналы

Симптом	Вероятная причина	Проверка
Worker завершается во время запуска	Не задан `DYN_KV_TRANSFER_DOMAIN` или файл топологии так и не был заполнен.	Логи worker и содержимое `DYN_TOPOLOGY_MOUNT_PATH`.
Политика `required` не возвращает endpoint	Ни один decode worker не имеет сгенерированной topology taint выбранного prefill worker.	Топологические метаданные `ModelRuntimeConfig` worker и размещение decode worker.
Политика `preferred` все равно маршрутизирует междоменно	Совпадающий домен перегружен или недоступен, либо вес слишком мал относительно нагрузки.	Увеличьте `preferredWeight`, добавьте decode capacity в том же домене или переключитесь на `required`.
Router не видит метаданные топологии	Worker не опубликовал поля топологии.	Логи запуска backend и метрики/данные обнаружения runtime config.

Команды проверки, специфичные для Kubernetes, см. в разделе Проверка развертывания.

Передача KV с учетом топологии

Контракт runtime​

Поток запроса​

Режимы enforcement​

Required​

Preferred​

Контракт среды worker​

Поддержка backend​

Взаимодействие с существующими RoutingConstraints​

Операционные замечания​

Диагностические сигналы​