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

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.

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

Обзор​

Dynamo KV Router интеллектуально направляет запросы, оценивая их вычислительную стоимость на разных workers. Он учитывает и стоимость decode (по активным блокам), и стоимость prefill (по вновь вычисляемым блокам), используя перекрытие KV cache, чтобы минимизировать лишние вычисления. Настройка KV Router критически важна для достижения максимального throughput и минимальной задержки в распределенных сценариях inference. Это руководство поможет начать работу с Dynamo router и подскажет страницы, где подробнее разобраны концепции роутинга, конфигурация, disaggregated serving и эксплуатация.

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

Router можно развернуть через Python / CLI, Kubernetes или как самостоятельный компонент.

Развертывание через Python / CLI​

Чтобы запустить Dynamo frontend с KV Router:

python -m dynamo.frontend --router-mode kv --http-port 8000

Эта команда:

  • запускает сервис Dynamo frontend с включенным KV routing
  • открывает сервис на порту 8000 (можно изменить)
  • автоматически обрабатывает всех backend workers, зарегистрированных в Dynamo endpoint

Backend workers регистрируются через API register_model. Чтобы состояние prefix-cache было точным, workers также должны публиковать KV cache events с backend-specific флагами событий; иначе router может работать в approximate mode с --no-router-kv-events.

Аргументы CLI​

АргументПо умолчаниюОписание
--router-mode kvround-robinВключить KV cache-aware routing
--router-temperature <float>0.0Управляет случайностью роутинга (0.0 = детерминированно, больше - случайнее)
--kv-cache-block-size <size>Backend-specificРазмер блока KV cache (должен совпадать с конфигурацией backend)
--router-kv-events / --no-router-kv-events--router-kv-eventsВключить/отключить отслеживание KV events в реальном времени
--load-aware / --no-load-aware--no-load-awareРоутить по активной нагрузке без сигналов повторного использования cache; подразумевает --router-mode kv на frontend
--router-kv-overlap-score-credit <float>1.0Множитель кредитов для device-local prefix overlap, от 0.0 до 1.0
--router-prefill-load-scale <float>1.0Масштабировать скорректированную нагрузку prompt-side prefill перед добавлением decode blocks
--router-track-prefill-tokens / --no-router-track-prefill-tokens--router-track-prefill-tokensУчитывать prompt-side load в учете активной нагрузки worker'а
--router-prefill-load-model <none|aic>noneМодель нагрузки prompt-side; см. Routing Concepts и Configuration and Tuning
--router-queue-threshold <float>16.0Доля порога очереди; включает приоритетное планирование через priority
--router-queue-policy <str>fcfsПолитика планирования очереди: fcfs (tail TTFT), wspt (avg TTFT) или lcfs (обратный порядок только для сравнения)
--serve-indexerfalseОтдавать из этого frontend/router Dynamo-native remote indexer на worker component
--use-remote-indexerfalseЗапрашивать remote indexer, отданный worker component, вместо поддержки локального overlap indexer

Для всех доступных опций: python -m dynamo.frontend --help

Для всех доступных опций: python -m dynamo.frontend --help

Подробные опции конфигурации и параметры настройки см. в Configuration and Tuning. Правила допуска кандидатов см. в Router Filtering. О том, как router моделирует нагрузку prefill и decode в cost function, см. в Routing Concepts.

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

Чтобы включить KV Router в Kubernetes, добавьте переменную окружения DYN_ROUTER_MODE в service frontend:

apiVersion: nvidia.com/v1alpha1
kind: DynamoGraphDeployment
metadata:
  name: my-deployment
spec:
  services:
    Frontend:
      componentType: frontend
      replicas: 1
      envs:
        - name: DYN_ROUTER_MODE
          value: kv  # Включить KV Smart Router

Ключевые моменты:

  • Устанавливайте DYN_ROUTER_MODE=kv только для service Frontend
  • Настраивайте публикацию KV events на стороне worker, когда нужен event-driven prefix-cache state
  • Используйте --no-router-kv-events для approximate cache-state prediction, если workers не публикуют events

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

Все аргументы CLI можно настроить через переменные окружения с префиксом DYN_:

Аргумент CLIПеременная окруженияПо умолчанию
--router-mode kvDYN_ROUTER_MODE=kvround-robin
--load-awareDYN_ROUTER_LOAD_AWARE=truefalse
--router-temperatureDYN_ROUTER_TEMPERATURE0.0
--kv-cache-block-sizeDYN_KV_CACHE_BLOCK_SIZEBackend-specific
--no-router-kv-eventsDYN_ROUTER_USE_KV_EVENTS=falsetrue
--router-kv-overlap-score-creditDYN_ROUTER_KV_OVERLAP_SCORE_CREDIT1.0
--router-prefill-load-scaleDYN_ROUTER_PREFILL_LOAD_SCALE1.0
--router-queue-policyDYN_ROUTER_QUEUE_POLICYfcfs
DYN_ENCODER_CUDA_TO_CPU_RATIO8Соотношение throughput не-CPU worker'а к одному CPU worker'у для роутинга device-aware-weighted

Полные примеры для K8s и продвинутую настройку см. в K8s Examples и Configuration and Tuning. Для A/B-тестирования и продвинутой K8s-настройки см. KV Router A/B Benchmarking Guide.

Самостоятельный Router​

KV router можно также запускать как самостоятельный service (без Dynamo frontend) для disaggregated serving (например, для маршрутизации к prefill workers), многоуровневых архитектур или любого сценария, где нужны интеллектуальные решения KV cache-aware routing. Подробнее см. компонент Standalone Router.

Router, встроенный во Frontend, и Standalone Router​

РазвертываниеПроцессПорт метрикСценарий использования
Frontend-embeddedpython -m dynamo.frontend --router-mode kvHTTP-порт Frontend (по умолчанию 8000)Стандартное развертывание; router работает внутри процесса frontend
Standalonepython -m dynamo.routerDYN_SYSTEM_PORT (если задан)Многоуровневые архитектуры, продвинутый disaggregated prefill routing, кастомные pipelines

Standalone router не включает HTTP frontend (нет endpoint /v1/chat/completions). Он экспонирует только RouterRequestMetrics через system status server. См. Standalone Router README.

Режимы развертывания​

Dynamo router можно развернуть в нескольких конфигурациях. В таблице ниже показаны все комбинации и случаи, когда их использовать:

РежимКомандаЛогика роутингаKV EventsТопологияСценарий использования
Frontend + Round-Robinpython -m dynamo.frontend --router-mode round-robinПоследовательно циклирует по workersНетAggregatedСамый простой baseline; без учета KV
Frontend + Randompython -m dynamo.frontend --router-mode randomСлучайный выбор worker'аНетAggregatedStateless load balancing
Frontend + KV (Aggregated)python -m dynamo.frontend --router-mode kvПерекрытие KV cache + loadNATS Core / JetStream / ZMQ / ApproxAggregatedProduction single-pool serving с повторным использованием cache
Frontend + KV (Disaggregated)python -m dynamo.frontend --router-mode kv with prefill + decode workersПерекрытие KV cache + loadNATS Core / JetStream / ZMQ / ApproxDisaggregated (prefill + decode pools)Раздельные prefill/decode для крупномасштабного serving
Frontend + Least-Loadedpython -m dynamo.frontend --router-mode least-loadedМеньше всего активных соединенийНетAggregated или disaggregated fallbackПростое балансирование с учетом нагрузки без учета KV
Frontend + Device-Aware Weightedpython -m dynamo.frontend --router-mode device-aware-weightedDevice-aware budget + least-loaded внутри выбранной группы устройствНетAggregated или disaggregated fallbackБалансирование разнородного парка (CPU/non-CPU); при одном классе устройств сводится к least-loaded
Frontend + Directpython -m dynamo.frontend --router-mode directWorker ID из hints запросаНетAggregatedВнешний orchestrator (например, EPP/GAIE) выбирает workers
Standalone Routerpython -m dynamo.routerПерекрытие KV cache + loadNATS Core / JetStream / ZMQЛюбаяРоутинг без HTTP frontend (multi-tier, custom pipelines)

Режимы роутинга (--router-mode)​

РежимЗначениеКак выбираются workers
Round-Robinround-robin (по умолчанию)Обходит доступных workers по порядку
RandomrandomВыбирает случайного worker'а для каждого запроса
KVkvОценивает перекрытие KV cache и decode load для каждого worker'а; выбирает вариант с минимальной стоимостью
Least-Loadedleast-loadedНаправляет запрос к worker'у с наименьшим числом активных соединений; в disaggregated prefill-путях пропускает bootstrap optimization и переходит к synchronous prefill
Device-Aware Weighteddevice-aware-weightedДелит workers на группы CPU и non-CPU, применяет budget, нормализованный по возможностям, с использованием DYN_ENCODER_CUDA_TO_CPU_RATIO, чтобы решить, какая группа получит запрос, а затем выбирает наименее загруженного worker'а внутри этой группы
DirectdirectЧитает целевой worker_id из routing hints запроса; логики выбора нет

Маршрутизация с учетом типа устройства​

device-aware-weighted предназначен для гетерогенных флотилий, где workers разной вычислительной мощности, например CPU embedding encoders рядом с GPU embedding encoders, используют один и тот же endpoint.

Workers делятся на группы CPU и non-CPU. Router сравнивает нагрузку, нормализованную по возможностям, между двумя группами:

normalized_load = total_inflight(group) / (instance_count(group) x throughput_weight)

Вес throughput равен 1 для CPU workers и DYN_ENCODER_CUDA_TO_CPU_RATIO для non-CPU workers. Следующий запрос направляется в группу с меньшей нормализованной нагрузкой, а затем к наименее загруженному worker'у внутри этой группы.

Используйте DYN_ENCODER_CUDA_TO_CPU_RATIO, чтобы приблизить отношение throughput non-CPU worker'а к одному CPU worker'у. Значение по умолчанию - 8.

Когда присутствует только один класс устройств, политика сводится к стандартному least-loaded routing.

Режимы транспортировки KV Events (внутри --router-mode kv)​

При использовании KV routing router должен знать, что закэшировал каждый worker. Есть четыре способа получить эту информацию:

Режим событийКак включитьОписание
NATS Core (local indexer)Router по умолчанию (без флага router)Workers ведут локальный indexer; настройте публикацию KV events на стороне backend, чтобы router мог восстанавливать состояние и получать events через NATS Core
JetStream (durable)--router-durable-kv-eventsEvents сохраняются в NATS JetStream; поддерживаются snapshots и durable consumers. Устарело.
ZMQ--event-plane zmqWorkers публикуют через ZMQ PUB sockets; самостоятельный сервис dynamo.indexer агрегирует events
Approximate (no events)--no-router-kv-eventsEvents не потребляются; router предсказывает состояние cache на основе собственных решений о роутинге с истечением по TTL

Топология aggregated и disaggregated​

ТопологияWorkersКак это работает
AggregatedОдин pool (prefill + decode в одном процессе)Все workers обрабатывают полный жизненный цикл запроса
DisaggregatedРаздельные pool'ы prefill и decodeFrontend сначала направляет запрос к prefill worker'у, затем к decode worker'у; требуется, чтобы workers были зарегистрированы с ModelType.Prefill

Режим disaggregated включается автоматически, когда prefill workers регистрируются вместе с decode workers. Подробности см. в Раздельном обслуживании.

Дополнительная документация по Router​