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

Конфигурация и настройка

На этой странице собраны основные флаги router для встроенных во frontend и standalone-развертываний. О модели стоимости маршрутизации и поведении выбора worker-узла см. Routing Concepts.

Поведение маршрутизации

• --router-kv-overlap-score-credit: Множитель кредита за локальное на устройстве перекрытие префикса в расчете стоимости prefill, от 0.0 до 1.0. Более высокие значения улучшают Time To First Token (TTFT) ценой увеличения Inter-Token Latency (ITL). При значении 0 router игнорирует кеши префиксов и не создает локальный indexer. По умолчанию: 1.
• --router-prefill-load-scale: Коэффициент, применяемый к скорректированной prefill-нагрузке на стороне prompt после вычитания кредитов за device, lower-tier и shared-cache. По умолчанию: 1.
• --load-aware: Пресет для load-aware KV routing без сигналов повторного использования кеша. На frontend он подразумевает --router-mode kv. Он устанавливает overlap_score_credit=0, отключает KV events, durable KV events и предположения о повторном использовании KV, включает учет нагрузки active-block и prefill-token, отключает remote/shared cache indexers и сохраняет --router-prefill-load-scale.
• --router-temperature: Управляет случайностью выбора worker-узла через softmax-сэмплирование нормализованных logits стоимости router. Значение 0 (по умолчанию) обеспечивает детерминированный выбор worker с наименьшей стоимостью, а более высокие значения вносят больше случайности.
• --router-track-prefill-tokens: Включает учет нагрузки на стороне prompt в модели стоимости worker. Этот флаг должен оставаться включенным, если вы хотите, чтобы пороги очереди, active_prefill_tokens и спад prefill-нагрузки AIC отражали работу prompt.
• --router-prefill-load-model: Выбирает модель нагрузки на стороне prompt для router. none сохраняет текущий статический учет нагрузки prompt. aic предсказывает одну ожидаемую длительность prefill для каждого принятого запроса и лениво снижает нагрузку только у самого старого активного prefill-запроса на каждом worker.
• --router-queue-threshold: Порог очереди как доля емкости prefill-токенов (по умолчанию: 16.0). Router удерживает входящие запросы в очереди с приоритетом, пока все worker-узлы превышают эту долю max_num_batched_tokens, и выпускает их, когда capacity освобождается. Это откладывает dispatch вместо отказа от работы, поэтому решения маршрутизации используют самые свежие метрики нагрузки в момент фактической отправки запроса на worker. Параметр также включает приоритетное планирование через подсказки priority в nvext.agent_hints. Должен быть больше 0. Установите None, чтобы отключить очереди. См. примечание про SGLang в разделе Tuning Guidelines для ограничений, связанных с тем, как max_num_batched_tokens заполняется на этом backend.
• --router-queue-policy: Scheduling policy for the router queue (default: fcfs).

О том, чем queue backpressure отличается от фильтрации кандидатов и обработки перегрузки по busy-threshold, см. Router Filtering.

fcfs сортирует по скорректированному времени прибытия (priority_jump - arrival_offset) и оптимизирует tail TTFT. lcfs сортирует по скорректированному обратному времени прибытия (priority_jump + arrival_offset) и в основном используется для контролируемых сравнительных экспериментов. wspt сортирует по (1 + priority_jump) / isl_tokens и оптимизирует средний TTFT.

Для --router-mode device-aware-weighted задайте DYN_ENCODER_CUDA_TO_CPU_RATIO как приблизительное отношение пропускной способности одного non-CPU worker к одному CPU worker. Значение по умолчанию — 8.

Модель нагрузки AIC для prefill

Используйте --router-prefill-load-model aic, когда хотите, чтобы учет нагрузки на стороне prompt уменьшал вклад самого старого активного prefill-запроса по длительности, предсказанной AIC, вместо того чтобы держать prompt-нагрузку неизменной до первого токена. О поведении модели стоимости см. Prefill Load Modeling.

Включите это на frontend так:

python -m dynamo.frontend \
    --router-mode kv \
    --router-prefill-load-model aic \
    --aic-backend vllm \
    --aic-system h200_sxm \
    --aic-model-path nvidia/Llama-3.1-8B-Instruct-FP8

Обязательно при включенном --router-prefill-load-model=aic:

• --router-mode kv на frontend
• --router-track-prefill-tokens
• --aic-backend
• --aic-system
• --aic-model-path

Необязательные параметры AIC:

• --aic-backend-version: закрепленная версия базы AIC; если не указана, Dynamo использует значение по умолчанию для конкретного backend.
• --aic-tp-size: размер tensor-parallel для моделируемого backend; по умолчанию 1
• --aic-moe-tp-size: размер tensor-parallel для MoE-моделей, которым требуется AIC MoE parallelism
• --aic-moe-ep-size: размер expert-parallel для MoE-моделей, которым требуется AIC MoE parallelism
• --aic-attention-dp-size: размер attention data-parallel для MoE-моделей, которым требуется AIC MoE parallelism

Для MoE-моделей эти значения должны удовлетворять ограничению параллелизма AIC: aic_tp_size * aic_attention_dp_size == aic_moe_tp_size * aic_moe_ep_size. Для TP-only MoE-запусков в стиле Kimi используйте --aic-moe-tp-size, равный --aic-tp-size, --aic-moe-ep-size 1, and --aic-attention-dp-size 1.

Передача и сохранение KV-событий

• --no-router-kv-events: Отключает отслеживание KV events. По умолчанию router потребляет KV events, чтобы отслеживать создание и удаление блоков у worker, которые их публикуют. Если флаг отключен, router предсказывает состояние кеша на основе решений маршрутизации с TTL-based expiration.
• --router-durable-kv-events: Deprecated. Включает режим JetStream для передачи KV-событий. Сейчас рекомендуемым путем является подписчик event plane в режиме local indexer.
• --router-reset-states: Применяется только в JetStream mode (--router-durable-kv-events). Сбрасывает состояние router при запуске, очищая и JetStream event stream, и NATS object store, чтобы начать с чистого состояния.
• --router-snapshot-threshold: Применяется только в JetStream mode (--router-durable-kv-events). Задает число сообщений в JetStream перед созданием snapshot.

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

Передача KV с учетом топологии настраивается на worker-узлах через runtime metadata, а не через флаги router во frontend. В Kubernetes используйте spec.experimental.kvTransferPolicy в DynamoGraphDeployment; operator подставит переменные окружения worker-узла и topology-файлы. Вне Kubernetes задайте на worker-узлах DYN_TOPOLOGY_ENABLED, DYN_TOPOLOGY_MOUNT_PATH, DYN_KV_TRANSFER_DOMAIN, DYN_KV_TRANSFER_ENFORCEMENT и DYN_KV_TRANSFER_PREFERRED_WEIGHT.

Полный контракт runtime и поведение маршрутизации см. в Topology-Aware KV Transfer. Примеры Kubernetes-развертывания см. в Kubernetes Topology-Aware KV Transfer.

Отслеживание блоков

• --no-router-track-active-blocks: Отключает отслеживание active blocks, используемых на этапах ongoing generation или decode. Отключайте это при маршрутизации к worker, которые выполняют только prefill.
• --router-track-output-blocks: Experimental. Включает отслеживание output-блоков во время генерации. При включении router добавляет блоки-заглушки по мере генерации токенов и применяет дробное уменьшение веса в зависимости от прогресса к ожидаемой длине выходной последовательности (agent_hints.osl в nvext). О поведении модели стоимости см. Decode Load Modeling.
• --no-router-assume-kv-reuse: При отслеживании active blocks отключает предположение о повторном использовании KV cache. Это полезно в disaggregated-схемах, где переданные блоки фактически не дедуплицируются на decode-side.
• --no-router-track-prefill-tokens: Отключает учет prefill-токенов на стороне prompt в модели активной нагрузки router. Используйте это для decode-only путей маршрутизации, где обработка prompt уже произошла в другом месте.
• --router-replica-sync: Отключен по умолчанию. Включает синхронизацию локальных решений маршрутизации между router replicas на основе NATS.

Индексатор KV / приблизительный KV indexer

• --router-ttl-secs: Time-to-live в секундах для блоков в локальных прогнозах кеша router. По умолчанию 120.0 секунд, когда используется --no-router-kv-events.
• --router-event-threads: Количество worker thread для KV indexer (по умолчанию: 4). Значения больше 1 используют concurrent radix tree для event-driven routing, approximate routing с --no-router-kv-events и side indexer для predict-on-route.
• --router-predicted-ttl-secs: Включает predict-on-route с этим TTL в секундах для записей в локальном side indexer. Требует KV events; опустите флаг, чтобы отключить. При включении router передает каждое решение маршрутизации в side indexer и оценивает каждого worker по большему overlap из primary indexer и локального side indexer. Не зависит от --router-ttl-secs; значение держат небольшим, чтобы решения, которые engine никогда не подтверждает (отмененные запросы, сбои prefill), быстро устаревали.

Когда использовать --router-predicted-ttl-secs

Без этого параметра event-driven router полностью зависит от KV events от engine, чтобы узнать, какой worker теперь держит какой prefix. Это работает для steady-state traffic, но создает race condition, когда много sibling-запросов приходит в одном батче, например 16 задач × 4 sample каждая с общим system prompt, или при любом parallel-sampling / best-of-N workload. Ни один engine еще не отправил событие "block stored", поэтому router присваивает каждому sibling нулевой overlap и распределяет их по worker в режиме round-robin. В итоге prefix prefill-ится на каждом worker вместо повторного использования.

Если задать --router-predicted-ttl-secs 5, router будет записывать каждое решение маршрутизации во вторичный approximate indexer с коротким TTL. Когда оценивается следующий sibling, router запрашивает оба indexer и берет по worker максимальный overlap, так что sibling сразу видят prefix первого sibling и закрепляются за тем же worker. Основной event-driven indexer при этом не затрагивается: engine вычисляют sequence hashes с salt и cryptographic digest, которые router не может воспроизвести, поэтому если вставлять вычисленные router hashes в primary, один и тот же физический блок получит два разных хеша, и дерево будет загрязнено. Параллельный запуск двух деревьев полностью обходится без этого; side tree живет недолго, а его записи просто истекают, когда управление берет на себя primary.

Не сочетайте этот параметр с --no-router-kv-events, включая случаи, когда approximate primary находится удаленно: approximate mode уже по своей конструкции добавляет записи на основе решений маршрутизации, и запуск второго approximate side indexer избыточен. При --use-remote-indexer и включенных KV events side indexer остается локальным для consumer router, а remote indexer остается общей primary-view. Если router также обслуживает indexer для других router-узлов, side indexer все равно остается только локальным; он никогда не обслуживается и не используется как remote primary.

О том, как реализовать публикацию KV events для custom inference engines, см. KV Event Publishing for Custom Engines. Подробности о подсказках agent на уровне запроса (priority, osl, speculative_prefill) см. в NVIDIA Request Extensions (nvext).

Управление сессией и закрепленная маршрутизация

Когда запрос содержит nvext.session_control, KV router может активировать два связанных сессией компонента:

• StickySessionRouter: Поддерживает в памяти карту affinity session_id -> (worker_id, dp_rank) со sliding-window TTL. action: "bind" создает affinity только на стороне router без RPC к backend engine. Последующие запросы с тем же session_id направляются на закрепленный worker/rank, минуя оценку KV overlap.
• AgentController: Отправляет RPC жизненного цикла сессии (open_session, close_session) в endpoint session_control worker, когда action равен "open" или "close". Клиент event-plane лениво инициализируется при первом запросе жизненного цикла.

Они активируются автоматически при --router-mode kv -- дополнительных флагов не требуется. Запросы без session_control не затрагиваются и идут по стандартному KV-aware пути маршрутизации. Для закрепленной маршрутизации только на уровне router достаточно action: "bind"; для жизненного цикла с поддержкой engine сейчас требуется backend SGLang с --enable-streaming-session. Подробности см. в SGLang for Agentic Workloads -- Session Control.

Рекомендации по настройке

--router-kv-overlap-score-credit — основной параметр для повторного использования кеша. Он засчитывает локальное на устройстве перекрытие префикса в счет prefill-нагрузки и должен быть в диапазоне от 0.0 до 1.0. Более высокие значения направляют запросы к worker-узлам с лучшим перекрытием кеша и уменьшают TTFT. Более низкие значения распределяют нагрузку равномернее и уменьшают ITL. Значение по умолчанию 1.0 — разумная отправная точка. Этот кредит можно также переопределить для отдельного запроса через nvext.agent_hints.kv_overlap_score_credit.

Используйте --load-aware, когда вам нужна модель активной нагрузки KV scheduler без повторного использования префикса/кеша. Это эквивалентно работе в KV mode с кредитом overlap, равным 0, отключенными KV events, отключенными предположениями о повторном использовании KV, включенным отслеживанием активной нагрузки и отключенной маршрутизацией через shared-cache. --router-prefill-load-scale по-прежнему доступен для настройки нагрузки на стороне prompt относительно decode-блоков.

Устаревшие параметры --router-kv-overlap-score-weight, --kv-overlap-score-weight, DYN_ROUTER_KV_OVERLAP_SCORE_WEIGHT и DYN_OVERLAP_SCORE_WEIGHT по-прежнему принимаются, но выводят предупреждения об устаревании. Ненулевые legacy-значения сопоставляются с prefill_load_scale, чтобы сохранить прежнее поведение без изменения overlap credit. Legacy-значение 0 сопоставляется сразу с prefill_load_scale=0 и overlap_score_credit=0, что сохраняет старое поведение без overlap и без indexer. Если устаревший overlap score weight все еще задан, он имеет приоритет над новым полем prefill load scale; legacy-значение 0 также имеет приоритет над новым полем overlap credit. При миграции на --router-prefill-load-scale или DYN_ROUTER_PREFILL_LOAD_SCALE удалите устаревший флаг, переменную окружения или JSON-поле из конфигурации развертывания. Используйте --router-kv-overlap-score-credit или DYN_ROUTER_KV_OVERLAP_SCORE_CREDIT только тогда, когда действительно хотите настроить именно кредит за cache-overlap.

Если в старой конфигурации использовался overlap score weight выше 1.0, чтобы router сильнее учитывал TTFT, оставьте overlap credit на уровне 1.0 или ниже, а большее значение перенесите в --router-prefill-load-scale. prefill_load_scale умножает скорректированную по overlap нагрузку на стороне prompt, поэтому он по-прежнему косвенно учитывает кредиты device, host, disk и shared-cache.

Используйте --router-prefill-load-scale, когда нагрузка на стороне prompt должна весить больше или меньше, чем нагрузка decode-блоков после применения кредитов за cache-hit. Итоговый счет равен prefill_load_scale * adjusted_prefill_blocks + decode_blocks.

Используйте --no-router-kv-events, если не уверены, что backend-движок корректно публикует KV events. В этом режиме router переходит к approximate routing и предсказывает состояние кеша на основе собственных решений маршрутизации с TTL-based expiration.

Используйте --router-predicted-ttl-secs 5, когда нагрузка порождает серии sibling-запросов с общими префиксами — parallel sampling, best-of-N, agent fan-out. Это сокращает окно между решением маршрутизации и первым событием engine "block stored", чтобы sibling-запросы размещались на worker-узле, выбранном первым sibling-запросом. Механику side-indexer см. в разделе конфигурации выше.

Используйте --no-router-assume-kv-reuse в disaggregated-схемах, где decode worker не повторно использует переданные KV cache blocks. Без этого флага router недоучитывает decode blocks при наличии дубликатов, что приводит к неточным оценкам нагрузки.

Используйте --no-router-track-prefill-tokens, когда router обслуживает только decode-трафик и обработка prompt уже завершилась в другом месте. Это позволяет принимать решения о decode-маршрутизации, ориентируясь на нагрузку decode-side, вместо того чтобы кратковременно начислять prompt-токены decode worker после передачи.

Используйте --router-track-output-blocks, когда ваша нагрузка output-heavy и вы хотите, чтобы router учитывал рост KV cache на стороне вывода при балансировке нагрузки. Если вы также передаете nvext.agent_hints.osl для каждого запроса, router применяет дробное уменьшение веса к output-блокам, чтобы запросы, близкие к завершению, вносили меньший будущий вклад в нагрузку. Подробности модели стоимости см. в Decode Load Modeling.

--router-queue-threshold определяет, когда входящие запросы удерживаются в очереди с приоритетом. Router ждет, пока все worker-узлы превысят заданную долю max_num_batched_tokens, а затем выпускает работу по мере освобождения capacity. Установите None, чтобы полностью отключить очереди.

Этот threshold задерживает dispatch. Он не удаляет worker-узлы из множества кандидатов; о таком различии см. Router Filtering.

Используйте DYN_ROUTER_OVERLAP_REFRESH_AFTER_SECS, когда запросы в очереди могут ждать достаточно долго, чтобы состояние кеша worker-узла заметно изменилось до dispatch. Значение по умолчанию — 10 секунд; установите 0, чтобы отключить обновление overlap в момент dequeue.

Примечание для backend SGLang. Начиная с #8220, значение, которое SGLang worker публикует для max_num_batched_tokens в своей карточке Model Deployment Card, зависит от аргументов запуска:

• Если --max-prefill-tokens задан, max_num_batched_tokens в MDC равен этому значению (окно prefill на один шаг — то, что большинство пользователей ожидает).
• Если --max-prefill-tokens не задан, max_num_batched_tokens в MDC откатывается к max_total_num_tokens из scheduler_info SGLang, то есть к общему KV cache pool в токенах. На больших GPU с высоким mem-fraction-static этот пул может составлять сотни тысяч токенов — намного больше, чем chunked-prefill-size.

Порог применяется как active_tokens > threshold * max_num_batched_tokens, поэтому такой fallback увеличивает эффективный знаменатель, и порог вроде 1.0 может практически никогда не создавать очередь. Чтобы получить изначально задуманную семантику "доля окна prefill на один шаг" в SGLang, либо явно задайте --max-prefill-tokens на backend SGLang, чтобы значение MDC совпадало с окном prefill, либо используйте гораздо меньший --router-queue-threshold (например 0.1), чтобы компенсировать увеличенный знаменатель.

Используйте --router-prefill-load-model aic, когда хотите, чтобы учет нагрузки на стороне prompt уменьшал вклад самого старого активного prefill-запроса по длительности, предсказанной AIC, вместо того чтобы держать prompt-нагрузку неизменной до первого токена. Для этого нужны --router-track-prefill-tokens и общая конфигурация --aic-*; полный набор флагов см. в AIC Prefill Load Model, а подробности модели стоимости — в Prefill Load Modeling.

Используйте --router-queue-policy wspt, когда в вашей нагрузке есть смесь коротких и длинных запросов и вы хотите минимизировать средний TTFT. Используйте значение по умолчанию fcfs, когда нужно минимизировать tail TTFT.

Метрики Prometheus

Router публикует метрики Prometheus на HTTP-порту frontend (по умолчанию 8000) по адресу /metrics:

• Метрики запросов router (dynamo_component_router_*): Регистрируются через иерархию метрик компонента и публикуются на frontend через bridge drt_metrics. В KV mode они заполняются на каждый запрос; в non-KV режимах они регистрируются с нулевыми значениями. Standalone router также регистрирует эти метрики, они доступны на DYN_SYSTEM_PORT, если он задан.
• Метрики служебных накладных расходов маршрутизации (dynamo_router_overhead_*) и счетчики по worker-узлам (dynamo_frontend_worker_*): Регистрируются в собственном Prometheus registry frontend. Они доступны только на frontend и отсутствуют в standalone router.

Полный список метрик router см. в Metrics reference.