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.

Создание развертываний

Скрипты в папке examples/<backend>/launch, например agg.sh, показывают, как можно локально обслуживать модели. Соответствующие YAML-файлы, например agg.yaml, показывают, как создать развертывание Kubernetes для вашего inference-графа.

nvidia.com/v1alpha1 устарел в пользу nvidia.com/v1beta1. Эквивалентные манифесты v1beta1 доступны в каталоге deploy/v1beta1/ каждого backend'а.

Это руководство объясняет, как создавать собственные файлы развертывания.

Шаг 1: Выберите архитектурный шаблон

Прежде чем выбирать шаблон, разберитесь в разных архитектурных паттернах:

Агрегированное обслуживание (agg.yaml)

Паттерн: Prefill и decode работают на одном GPU в одном процессе.

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

• Небольшие и средние модели (менее 70B параметров)
• Разработка и тестирование
• Низкий или умеренный трафик
• Приоритет простоты над максимальной пропускной способностью

Компромиссы:

• Более простая настройка и отладка
• Меньшая операционная сложность
• Использование GPU может быть неоптимальным (prefill и decode конкурируют за ресурсы)
• Нижний потолок пропускной способности по сравнению с раздельным обслуживанием

Пример: agg.yaml

Агрегированное обслуживание + Router (agg_router.yaml)

Паттерн: Балансировщик распределяет запросы между несколькими агрегированными экземплярами worker'ов.

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

• Средний трафик, где нужна высокая доступность
• Требуется горизонтальное масштабирование
• Нужен некоторый балансировщик без сложности раздельного обслуживания

Компромиссы:

• Лучшая масштабируемость, чем у обычного агрегированного варианта
• Высокая доступность за счет нескольких реплик
• При этом остаются проблемы неэффективного использования GPU, характерные для агрегированного обслуживания
• Сложнее, чем обычный агрегированный вариант, но проще, чем раздельный

Пример: agg_router.yaml

Раздельное обслуживание (disagg_router.yaml)

Паттерн: Отдельные worker'ы для prefill и decode с оптимизацией под каждую роль.

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

• Развертывания производственного уровня
• Требования к высокой пропускной способности
• Большие модели (70B+ параметров)
• Нужна максимальная загрузка GPU

Компромиссы:

• Максимальная производительность и пропускная способность
• Более эффективное использование GPU (prefill и decode специализированы)
• Независимое масштабирование prefill и decode
• Более сложная настройка и отладка
• Требуется понимание разделения prefill/decode

Пример: disagg_router.yaml

Краткое руководство по выбору

Выберите в качестве шаблона архитектурный паттерн, который лучше всего подходит для вашего сценария.

Например, при использовании backend'а vLLM:

• Разработка / тестирование: используйте agg.yaml как базовую конфигурацию.

• Продакшен с балансировкой нагрузки: используйте agg_router.yaml, чтобы включить масштабируемое inference с балансировкой.

• Высокая производительность / раздельное развертывание: используйте disagg_router.yaml для максимальной пропускной способности и модульной масштабируемости.

Шаг 2: Настройте шаблон

Вы можете запустить Frontend на одной машине, например на CPU-узле, а worker - на другой машине (GPU-узле). Frontend служит HTTP-точкой входа, не зависящей от фреймворка, и обычно не требует многих изменений.

Он выполняет следующие роли:

1. OpenAI-совместимый HTTP-сервер

• Предоставляет endpoint /v1/chat/completions
• Обрабатывает форматирование HTTP-запросов и ответов
• Поддерживает потоковые ответы
• Валидирует входящие запросы

2. Обнаружение сервисов и маршрутизация

• Автоматически находит backend worker'ов через etcd
• Направляет запросы к нужным компонентам Processor/Worker
• Выполняет балансировку нагрузки между несколькими worker'ами

3. Предобработка запросов

• Первичная валидация запроса
• Проверка имени модели
• Стандартизация формата запроса

Затем нужно выбрать worker и специализировать конфигурацию. Например,

VllmWorker:         # vLLM-specific config
  enforce-eager: true
  enable-prefix-caching: true

SglangWorker:       # SGLang-specific config
  router-mode: kv
  disagg-mode: true

TrtllmWorker:       # TensorRT-LLM-specific config
  engine-config: ./engine.yaml
  kv-cache-transfer: ucx

Ниже приведена структура шаблона на основе примеров:

    YourWorker:
      componentType: worker
      replicas: N
      envFromSecret: your-secrets  # e.g., hf-token-secret
      # Health checks for worker initialization
      readinessProbe:
        exec:
          command: ["/bin/sh", "-c", 'grep "Worker.*initialized" /tmp/worker.log']
      resources:
        requests:
          gpu: "1"  # GPU allocation
      extraPodSpec:
        mainContainer:
          image: your-image
          command:
            - /bin/sh
            - -c
          args:
            - python -m dynamo.YOUR_INFERENCE_ENGINE --model YOUR_MODEL --your-flags

См. соответствующий sh-файл. Каждая команда python для запуска компонента должна попасть в YAML-спецификацию под extraPodSpec: -> mainContainer: -> args:

Frontend запускается командой python3 -m dynamo.frontend [--http-port 8000] [--router-mode kv] Каждый worker запускает команду python -m dynamo.YOUR_INFERENCE_BACKEND --model YOUR_MODEL --your-flags.

Шаг 3: Ключевые точки настройки

Конфигурация модели

   args:
     - "python -m dynamo.YOUR_INFERENCE_BACKEND --model YOUR_MODEL --your-flag"

Выделение ресурсов

   resources:
     requests:
       cpu: "N"
       memory: "NGi"
       gpu: "N"

Масштабирование

   replicas: N  # Number of worker instances

Режим маршрутизации

   args:
     - --router-mode
     - kv  # Enable KV-cache routing

Специализация worker'а

   args:
     - --disaggregation-mode
     - prefill  # For disaggregated prefill workers

Топологически осознанное планирование

При желании можно упаковать связанные pod'ы в пределах домена топологии (например, стойки или блока), чтобы уменьшить межузловую задержку. Это особенно полезно для нагрузок раздельного обслуживания. Добавьте topologyConstraint на уровне развертывания, уровня сервиса или на обоих уровнях:

spec:
  topologyConstraint:
    packDomain: rack
  services:
    VllmWorker:
      # ...

Это требует Grove и ClusterTopology CR, настроенный администратором кластера. Подробности, доступные домены, правила иерархии и примеры см. в Topology Aware Scheduling.

Конфигурация image pull secret

Автоматическое обнаружение и внедрение

По умолчанию оператор Dynamo автоматически обнаруживает и внедряет image pull secret'ы на основе соответствия хоста контейнерного реестра. Оператор сканирует secret'ы Docker config в том же namespace и сопоставляет их registry hostname с URL образов контейнеров, автоматически добавляя подходящие secret'ы в imagePullSecrets pod'а.

Отключение автоматического обнаружения: Чтобы отключить это поведение для компонента и управлять image pull secret'ами вручную:

    YourWorker:
      componentType: worker
      annotations:
        nvidia.com/disable-image-pull-secret-discovery: "true"

Если отключено, secret'ы можно указать вручную так же, как в обычной pod-spec:

    YourWorker:
      componentType: worker
      annotations:
        nvidia.com/disable-image-pull-secret-discovery: "true"
      extraPodSpec:
        imagePullSecrets:
          - name: my-registry-secret
          - name: another-secret
        mainContainer:
          image: your-image

Автоматическое обнаружение избавляет от необходимости вручную настраивать image pull secret'ы для каждого развертывания.

Шаг 6: Разверните адаптеры LoRA (опционально)

После того как развертывание базовой модели запущено, можно развернуть адаптеры LoRA с помощью пользовательского ресурса DynamoModel. Это позволяет дообучать и расширять модели без изменения базового развертывания.

Чтобы добавить LoRA-адаптер в развертывание, свяжите его через modelRef в конфигурации worker'а:

apiVersion: nvidia.com/v1alpha1
kind: DynamoGraphDeployment
metadata:
  name: my-deployment
spec:
  services:
    Worker:
      modelRef:
        name: Qwen/Qwen3-0.6B  # Base model identifier
      componentType: worker
      # ... rest of worker config

Затем создайте ресурс DynamoModel для вашего LoRA:

apiVersion: nvidia.com/v1alpha1
kind: DynamoModel
metadata:
  name: my-lora
spec:
  modelName: my-custom-lora
  baseModelName: Qwen/Qwen3-0.6B  # Must match modelRef.name above
  modelType: lora
  source:
    uri: s3://my-bucket/loras/my-lora

Полные сведения об управлении моделями и адаптерами LoRA см. здесь: 📖 Руководство по управлению моделями с DynamoModel