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

Request Plane

Обзор

Dynamo поддерживает два транспортных механизма для request plane (коммуникационного слоя между сервисами):

• TCP (по умолчанию): прямое TCP-соединение для оптимальной производительности
• NATS: request plane на основе брокера сообщений

В этом руководстве объясняется, как настроить и использовать request plane в развертывании Dynamo.

Что такое Request Plane?

Request plane — это транспортный слой, который обрабатывает коммуникацию между сервисами Dynamo (например, от frontend к backend, от worker к worker). Разные request plane дают разные компромиссы:

Request Plane	Подходит для	Характеристики
NATS	Развертываний, где выбран брокерный транспорт запросов	Требует инфраструктуру NATS, предоставляет шаблоны pub/sub, максимальная гибкость
TCP	Прямой коммуникации с низкой задержкой	Прямые соединения, минимальные накладные расходы

Request Plane vs KV Event Plane

Dynamo имеет две независимые коммуникационные плоскости:

• Request plane (DYN_REQUEST_PLANE): как RPC-запросы проходят между компонентами (frontend → router → worker), через tcp или nats.
• KV event plane (DYN_EVENT_PLANE): как события KV-кэша (и опциональная синхронизация реплик router) распределяются для KV-aware routing, через nats или zmq.

Примечание: Если вы используете request plane tcp с включенными KV-событиями на router (настройка по умолчанию на стороне router), настроенная event plane инициализируется независимо. Транспорт событий на основе NATS использует NATS_SERVER (по умолчанию nats://localhost:4222), тогда как ZMQ позволяет обойтись без внешней инфраструктуры NATS. Для публикации событий SGLang требует явного --kv-events-config, а TRT-LLM требует --publish-events-and-metrics. Для vLLM KV-события сейчас настраиваются автоматически, когда активно prefix caching (устарело — используйте --kv-events-config явно, чтобы подготовиться к будущему выпуску, где все backend по умолчанию будут отключать события). Чтобы отключить прослушиватель KV-событий router, используйте --no-router-kv-events на frontend.

Поскольку эти плоскости независимы, их можно комбинировать.

Например, развертывание с TCP request plane может использовать разные KV event plane:

• JetStream KV events: запросы используют TCP, а KV routing по-прежнему использует NATS JetStream + object store для персистентности.
• NATS Core KV events (локальный индексатор): запросы используют TCP, KV-события используют NATS Core pub/sub, а персистентность находится на worker.
• без KV events: запросы используют TCP, а KV routing работает без событий (NATS не требуется, но нет персистентности на основе событий).

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

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

Задайте режим request plane с помощью переменной окружения DYN_REQUEST_PLANE:

export DYN_REQUEST_PLANE=<mode>

Где <mode> — одно из значений:

• tcp (default)
• nats

Значение не зависит от регистра.

Поведение по умолчанию

Если DYN_REQUEST_PLANE не задана или содержит недопустимое значение, Dynamo по умолчанию использует tcp.

Примеры использования

Использование TCP (по умолчанию)

TCP — это request plane по умолчанию, обеспечивающая прямую коммуникацию между сервисами с низкой задержкой.

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

# TCP is the default, so no need to set DYN_REQUEST_PLANE explicitly
# But you can explicitly set it if desired:
export DYN_REQUEST_PLANE=tcp

# Optional: Configure TCP server host and port
export DYN_TCP_RPC_HOST=0.0.0.0  # Default host
# export DYN_TCP_RPC_PORT=9999   # Optional: specify a fixed port

# Run your Dynamo service
DYN_REQUEST_PLANE=tcp python -m dynamo.frontend --http-port=8000 &
DYN_REQUEST_PLANE=tcp python -m dynamo.vllm --model Qwen/Qwen3-0.6B

Примечание: По умолчанию TCP использует свободный порт, назначенный ОС (порт 0). Это удобно для сред, где на одной машине могут работать несколько сервисов, или когда нужно избежать конфликтов портов. Если нужен конкретный порт (например, для правил firewall), задайте DYN_TCP_RPC_PORT явно.

Когда использовать TCP:

• Простые развертывания с прямой коммуникацией service-to-service (например, frontend к backend)
• Минимальные требования к инфраструктуре (NATS инициализируется, когда router прослушивает KV-события; отключается с помощью --no-router-kv-events)
• Требования к низкой задержке

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

Дополнительные переменные окружения, специфичные для TCP:

• DYN_TCP_RPC_HOST: адрес хоста сервера (по умолчанию: определяется автоматически)
• DYN_TCP_RPC_PORT: порт сервера. Если не задан, ОС автоматически назначает свободный порт (рекомендуется для большинства развертываний). Задавайте явно только если нужен конкретный порт для правил firewall.
• DYN_TCP_MAX_MESSAGE_SIZE: максимальный размер сообщения для TCP client (по умолчанию: 32MB)
• DYN_TCP_SHRINK_MESSAGE_SIZE: порог, после которого буфер zero-copy decoder уменьшается обратно до начального размера после обработки больших сообщений (по умолчанию: 8MB, максимум: DYN_TCP_MAX_MESSAGE_SIZE)
• DYN_TCP_REQUEST_TIMEOUT: timeout запроса для TCP client (по умолчанию: 10 секунд)
• DYN_TCP_POOL_SIZE: размер пула соединений для TCP client (по умолчанию: 50)
• DYN_TCP_CONNECT_TIMEOUT: timeout подключения для TCP client (по умолчанию: 3 секунды)
• DYN_TCP_CHANNEL_BUFFER: размер буфера канала запросов для TCP client (по умолчанию: 100)

Использование NATS

NATS предоставляет durable messaging через jetstream для request plane и может использоваться для KV-событий (и синхронизации реплик router).

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

• Сервер NATS должен быть запущен и доступен
• Настройте подключение NATS через стандартные переменные окружения Dynamo NATS

# Explicitly set to NATS
export DYN_REQUEST_PLANE=nats

# Run your Dynamo service
DYN_REQUEST_PLANE=nats python -m dynamo.frontend --http-port=8000 &
DYN_REQUEST_PLANE=nats python -m dynamo.vllm --model Qwen/Qwen3-0.6B

Когда использовать NATS:

• Production-развертывания с service discovery
• KV-aware routing на основе событий при использовании NATS как транспорта событий. Примечание: транспорт событий ZMQ и approximate mode (--no-router-kv-events) оба обеспечивают KV routing без NATS, при этом approximate mode использует прогнозируемое состояние кэша.
• Требуются функции replay сообщений и персистентности

Ограничения:

• NATS не поддерживает payload больше 16MB (для более крупных payload используйте TCP)

Полный пример

Ниже приведен полный пример, показывающий, как запустить развертывание Dynamo с разными request plane:

Полный рабочий пример, демонстрирующий запуск Dynamo с request plane TCP или NATS, см. в examples/backends/vllm/launch/agg_request_planes.sh.

Реальный пример

Репозиторий Dynamo включает полный пример, демонстрирующий обе request plane:

Расположение: examples/backends/vllm/launch/agg_request_planes.sh

cd examples/backends/vllm/launch

# Run with TCP
./agg_request_planes.sh --tcp

# Run with NATS
./agg_request_planes.sh --nats

Детали архитектуры

Network Manager

Реализация request plane централизована в Network Manager (lib/runtime/src/pipeline/network/manager.rs), который:

1. Читает переменную окружения DYN_REQUEST_PLANE при запуске
2. Создает соответствующие реализации server и client
3. Предоставляет транспортно-независимый интерфейс для остальной кодовой базы
4. Управляет всей сетевой конфигурацией и жизненным циклом

Абстракция транспорта

Все реализации request plane соответствуют общим trait-интерфейсам:

• RequestPlaneServer: server-side interface для приема запросов
• RequestPlaneClient: client-side interface для отправки запросов

Эта абстракция означает, что код приложения не нужно менять при переключении request plane.

Загрузка конфигурации

Конфигурация request plane загружается из переменных окружения при запуске и кэшируется глобально. Иерархия конфигурации:

1. Выбор режима: DYN_REQUEST_PLANE (по умолчанию tcp)
2. Конфигурация, специфичная для транспорта: переменные окружения, специфичные для режима (например, DYN_TCP_*)

Руководство по миграции

С NATS на TCP

1. Остановите сервисы Dynamo
2. Задайте переменную окружения DYN_REQUEST_PLANE=tcp
3. При необходимости настройте параметры, специфичные для TCP (например, DYN_TCP_RPC_HOST). Примечание: DYN_TCP_RPC_PORT опционален; если он не задан, автоматически используется свободный порт, назначенный ОС.
4. Перезапустите сервисы

Проверка миграции

После переключения request plane проверьте развертывание:

# Test with a simple request
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-0.6B",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

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

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

Симптомы: запросы завершаются по timeout или не доходят до backend

Решения:

• Убедитесь, что все сервисы используют одинаковую настройку DYN_REQUEST_PLANE
• Проверьте, что порты сервера не заблокированы сетевыми политиками k8s или firewall
• Для TCP: убедитесь, что конфигурации host/port корректны и доступны
• Для NATS: убедитесь, что сервер NATS запущен и доступен

Проблема: ошибка "Invalid request plane mode"

Симптомы: сервис не запускается из-за ошибки конфигурации

Решения:

• Проверьте написание DYN_REQUEST_PLANE (допустимые значения: nats, tcp)
• Значение не зависит от регистра, но должно быть одним из двух вариантов
• Если значение не задано, по умолчанию используется tcp

Проблема: конфликты портов

Симптомы: сервер не запускается из-за "address already in use"

Решения:

• TCP: по умолчанию TCP использует свободный порт, назначенный ОС, поэтому конфликты портов должны быть редкими. Если вы явно задали DYN_TCP_RPC_PORT на конкретный порт и получили конфликт, измените порт или удалите эту настройку, чтобы использовать автоматическое назначение порта.

Соображения производительности

Задержка

• TCP: минимальная задержка благодаря прямым соединениям и бинарной сериализации
• NATS: умеренная задержка из-за персистентности nats jet stream

Использование ресурсов

• TCP: минимальная инфраструктура request-plane. KV-события используют настроенную event plane; NATS нужен только когда DYN_EVENT_PLANE=nats, а потребление событий на стороне router можно отключить с помощью --no-router-kv-events.
• NATS: требует запущенный сервер NATS (дополнительные память/CPU)