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

Планирование с учетом топологии

Планирование с учетом топологии (Topology Aware Scheduling, TAS) позволяет управлять тем, как Dynamo размещает поды инференс-нагрузки относительно сетевой топологии кластера. Если сгруппировать связанные поды в пределах одного rack, block или другого домена топологии, можно снизить межузловую задержку и повысить пропускную способность, особенно в disaggregated serving, где компоненты prefill, decode и routing часто обмениваются данными.

TAS включается по желанию. Существующие развертывания без ограничений топологии продолжают работать без изменений.

TAS управляет размещением подов. Чтобы ограничить или сместить передачу от prefill к decode в Dynamo router после того, как поды уже запущены, см. Передача KV с учетом топологии.

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

Требование	Подробности
Grove	Установлен в кластере. См. Grove Installation Guide.
ClusterTopology CR	Ресурс `ClusterTopology` уровня кластера, настроенный администратором кластера и сопоставляющий имена доменов топологии с метками узлов. Инструкции по настройке см. в документации Grove.
KAI Scheduler	KAI Scheduler требуется Grove для размещения подов с учетом топологии.
Dynamo operator	Последний Helm chart Dynamo operator включает RBAC только для чтения для `clustertopologies.grove.io` через отдельный ClusterRole. Дополнительная настройка не нужна.

Домены топологии

Домены топологии — это произвольные идентификаторы, определяемые администратором кластера в ClusterTopology CR. Частые примеры: region, zone, datacenter, block, rack, host и numa, но допустимо любое имя, соответствующее шаблону ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$ (без начального или конечного дефиса).

Имена доменов должны точно совпадать с тем, что настроено в ClusterTopology CR, на который ссылается topologyProfile. Во время создания DGD Dynamo webhook проверяет, что каждый packDomain существует в указанном ClusterTopology.

Когда вы указываете packDomain, планировщик размещает все replicas ограниченного компонента внутри одного экземпляра этого домена. Например, packDomain: rack означает «разместить все поды в одном rack».

Профиль топологии

Каждый DGD, использующий ограничения топологии, должен ссылаться на ClusterTopology CR по имени через поле topologyProfile. Это поле задается в spec.topologyConstraint (на уровне deployment) и наследуется всеми services — services не должны задавать topologyProfile самостоятельно.

topologyProfile сообщает Dynamo operator и базовому framework, какую иерархию топологии использовать для планирования и валидации.

Включение TAS в DGD

Добавьте поле topologyConstraint в DynamoGraphDeployment на уровне deployment, на уровне service или на обоих. Уровень deployment должен включать topologyProfile. Каждое ограничение задает packDomain.

Пример 1: Ограничение на уровне deployment (services наследуют)

Все services наследуют ограничение уровня deployment. Это самая простая конфигурация, когда вам нужен единообразный набор правил размещения по топологии.

apiVersion: nvidia.com/v1alpha1
kind: DynamoGraphDeployment
metadata:
  name: my-llm
spec:
  topologyConstraint:
    topologyProfile: my-cluster-topology
    packDomain: zone
  services:
    VllmWorker:
      componentType: worker
      replicas: 2
      envFromSecret: hf-token-secret
      resources:
        limits:
          gpu: "1"
      extraPodSpec:
        mainContainer:
          image: my-image
          command: ["/bin/sh", "-c"]
          args:
            - python3 -m dynamo.vllm --model Qwen/Qwen3-0.6B
    Frontend:
      componentType: frontend
      replicas: 1
      extraPodSpec:
        mainContainer:
          image: my-image
          command: ["/bin/sh", "-c"]
          args:
            - python3 -m dynamo.frontend

Пример 2: Только ограничение на уровне service

Только указанный service получает размещение с учетом топологии. Остальные services планируются без ограничений топологии. На уровне deployment все равно нужно задать topologyProfile.

apiVersion: nvidia.com/v1alpha1
kind: DynamoGraphDeployment
metadata:
  name: my-llm
spec:
  topologyConstraint:
    topologyProfile: my-cluster-topology
  services:
    VllmWorker:
      componentType: worker
      replicas: 2
      multinode:
        nodeCount: 4
      topologyConstraint:
        packDomain: rack
      envFromSecret: hf-token-secret
      resources:
        limits:
          gpu: "8"
      extraPodSpec:
        mainContainer:
          image: my-image
          command: ["/bin/sh", "-c"]
          args:
            - python3 -m dynamo.vllm --model meta-llama/Llama-4-Maverick-17B-128E
    Frontend:
      componentType: frontend
      replicas: 1
      extraPodSpec:
        mainContainer:
          image: my-image
          command: ["/bin/sh", "-c"]
          args:
            - python3 -m dynamo.frontend

Пример 3: Смешанный вариант (default на уровне deployment + переопределение для service)

Задайте широкое ограничение на уровне deployment и более узкое переопределение для конкретных services. Ограничения на уровне service должны быть равны ограничению уровня deployment или уже него (это определяется порядком в ClusterTopology CR).

apiVersion: nvidia.com/v1alpha1
kind: DynamoGraphDeployment
metadata:
  name: my-llm
spec:
  topologyConstraint:
    topologyProfile: my-cluster-topology
    packDomain: zone
  services:
    VllmWorker:
      componentType: worker
      replicas: 2
      multinode:
        nodeCount: 4
      topologyConstraint:
        packDomain: block    # narrower than zone — valid
      envFromSecret: hf-token-secret
      resources:
        limits:
          gpu: "8"
      extraPodSpec:
        mainContainer:
          image: my-image
          command: ["/bin/sh", "-c"]
          args:
            - python3 -m dynamo.vllm --model meta-llama/Llama-4-Maverick-17B-128E
    Frontend:
      componentType: frontend
      replicas: 1
      # inherits zone from spec.topologyConstraint
      extraPodSpec:
        mainContainer:
          image: my-image
          command: ["/bin/sh", "-c"]
          args:
            - python3 -m dynamo.frontend

Правила иерархии

Когда заданы и ограничение уровня deployment, и ограничение уровня service, packDomain service должен быть равен или уже packDomain уровня deployment. «Уже» определяется порядком уровней в указанном ClusterTopology CR — уровни, которые идут позже в массиве spec.levels, считаются более узкими.

Webhook Dynamo отклоняет DGD при создании, если ограничение service шире ограничения deployment (при проверке по ClusterTopology CR).

Когда задан только один уровень (только deployment или только service), проверка иерархии не выполняется.

Конфигурация	Поведение
`spec.topologyConstraint` задан, у service нет своего	Service наследует ограничение уровня deployment
`spec.topologyConstraint` задан, у service тоже задано	Применяются оба; service должен быть уже или равен
`spec.topologyConstraint.topologyProfile` задан, но `packDomain` в spec отсутствует	Профиль предоставляется только для ограничений на уровне service
Ничего не задано	Ограничений топологии нет (по умолчанию)

Справочник полей

Поле	Уровень	Обязательно	Описание
`topologyProfile`	`spec.topologyConstraint`	Да (если задано любое ограничение)	Имя `ClusterTopology` CR, определяющего иерархию топологии.
`topologyProfile`	service-level `topologyConstraint`	Н/Д (в схеме отсутствует)	Наследуется из `spec.topologyConstraint`. Тип на уровне service не включает это поле.
`packDomain`	`spec.topologyConstraint`	Необязательно	Домен packing по умолчанию для services, которые не задают свой.
`packDomain`	service-level `topologyConstraint`	Обязательно	Домен packing для этого service. Должен совпадать с уровнем в `ClusterTopology` CR.

Особенности multinode

Для multinode services (сервисы с секцией multinode) ограничение топологии применяется на уровне scaling group, а не отдельных worker-подов. Это важно, потому что multinode service создает replicas × nodeCount подов — например, 2 replicas с nodeCount: 4 дают 8 подов на 8 узлах. Применение ограничения на уровне scaling group означает, что планировщик размещает набор узлов каждой replica внутри запрошенного домена, не чрезмерно ограничивая отдельные поды одним host.

Например, при такой конфигурации:

VllmWorker:
  replicas: 2
  multinode:
    nodeCount: 4
  topologyConstraint:
    packDomain: rack

Четыре узла каждой replica размещаются в пределах одного rack. Две replicas могут оказаться в разных rack (ограничение действует для каждой replica отдельно, а не для всех replicas сразу).

Рекомендация: Для multinode services используйте rack или block в качестве packDomain, чтобы удерживать worker'ы внутри домена с высокой пропускной способностью и при этом позволять планировщику распределять их по host внутри этого домена. Избегайте host для multinode services, потому что размещение нескольких узлов на одном host не имеет смысла.

Неизменяемость

Ограничения топологии нельзя изменять после создания DGD. Это включает:

Добавление ограничения топологии в DGD или service, у которого его не было
Удаление существующего ограничения топологии
Изменение значения topologyProfile
Изменение значения packDomain

Чтобы изменить ограничения топологии, удалите и создайте DGD заново. Это соответствует поведению базового framework, который обеспечивает неизменяемость ограничений топологии для генерируемых ресурсов.

Мониторинг применения топологии

Когда задано любое ограничение топологии, статус DGD включает condition TopologyLevelsAvailable, которая сообщает, существуют ли еще уровни топологии, на которые ссылаются ваши ограничения, в topology кластера.

Нормальное состояние:

status:
  conditions:
    - type: Ready
      status: "True"
    - type: TopologyLevelsAvailable
      status: "True"
      reason: AllTopologyLevelsAvailable
      message: "All required topology levels are available in the cluster topology"

Пониженное состояние (например, администратор удалил уровень топологии из ClusterTopology CR после развертывания):

status:
  conditions:
    - type: Ready
      status: "True"
    - type: TopologyLevelsAvailable
      status: "False"
      reason: TopologyLevelsUnavailable
      message: "Topology level 'rack' is no longer available in the cluster topology"

Когда уровни топологии становятся недоступны, Dynamo отправляет событие Warning для DGD. Развертывание по-прежнему может выглядеть Ready, потому что базовый framework продолжает держать поды запущенными, но размещение по топологии больше не гарантируется.

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

DGD отклонен: "ClusterTopology not found"

Dynamo webhook проверяет, что ClusterTopology CR, на который ссылается topologyProfile, существует, когда задано любое ограничение топологии. Если он не может прочитать ClusterTopology CR:

Проверьте, что администратор кластера создал ресурс ClusterTopology, указанный в topologyProfile. Инструкции по настройке см. в документации Grove.
Проверьте, что у Dynamo operator есть RBAC для чтения clustertopologies.grove.io (входит в стандартный Helm chart).

DGD отклонен: "packDomain not found in cluster topology"

Указанный packDomain не существует как уровень в указанном ClusterTopology CR. Проверьте, какие домены определены:

kubectl get clustertopology <topology-profile-name> -o yaml

Убедитесь, что запрашиваемый домен (например, rack) настроен в ClusterTopology с соответствующей меткой узла.

DGD отклонен: "topologyProfile is required"

Любой DGD, у которого есть ограничение топологии (на уровне spec или service), должен задать spec.topologyConstraint.topologyProfile именем ClusterTopology CR. Добавьте поле topologyProfile в spec.topologyConstraint.

Поды застряли в Pending

Планировщик не может удовлетворить ограничение топологии. Частые причины:

Недостаточно узлов внутри одного экземпляра запрошенного домена (например, требуется упаковать 8 GPU в один rack, но ни в одном rack нет 8 доступных GPU).
Метки узлов не совпадают с конфигурацией ClusterTopology.

Подробности смотрите в событиях планировщика:

kubectl describe pod <pod-name> -n <namespace>

TopologyLevelsAvailable = False

DGD был успешно развернут, но определение топологии с тех пор изменилось. Базовый framework обнаружил, что один или несколько требуемых уровней топологии больше недоступны.

Проверьте сообщение condition, чтобы увидеть детали.
Изучите ClusterTopology CR, чтобы понять, не был ли домен удален или переименован.
Если топология изменилась намеренно, удалите и создайте DGD заново, чтобы он подхватил новую топологию.

DGD отклонен: нарушение иерархии

packDomain уровня service шире, чем packDomain уровня deployment. «Шире» и «уже» определяются порядком уровней в ClusterTopology CR — уровни, которые идут раньше в spec.levels, считаются более широкими.

Убедитесь, что ограничения уровня service равны ограничению уровня deployment или уже его.

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

Домены топологии​

Профиль топологии​

Включение TAS в DGD​

Пример 1: Ограничение на уровне deployment (services наследуют)​

Пример 2: Только ограничение на уровне service​

Пример 3: Смешанный вариант (default на уровне deployment + переопределение для service)​

Правила иерархии​

Справочник полей​

Особенности multinode​

Неизменяемость​

Мониторинг применения топологии​

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

DGD отклонен: "ClusterTopology not found"​

DGD отклонен: "packDomain not found in cluster topology"​

DGD отклонен: "topologyProfile is required"​

Поды застряли в Pending​

TopologyLevelsAvailable = False​

DGD отклонен: нарушение иерархии​