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.

Управление моделями с помощью DynamoModel

Обзор

DynamoModel — это пользовательский ресурс Kubernetes, который представляет модель машинного обучения, развернутую в Dynamo. Он позволяет:

Развертывать адаптеры LoRA поверх работающих базовых моделей
Отслеживать конечные точки модели и их готовность во всем кластере
Декларативно управлять жизненным циклом модели с помощью Kubernetes

DynamoModel работает совместно с ресурсами DynamoGraphDeployment (DGD) или DynamoComponentDeployment (DCD). Если DGD/DCD разворачивают инфраструктуру инференса (pod'ы, сервисы), то DynamoModel отвечает за операции, специфичные для модели, например загрузку адаптеров LoRA.

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

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

Перед созданием DynamoModel вам нужны:

Запущенный DynamoGraphDeployment или DynamoComponentDeployment
Компоненты, настроенные с modelRef, указывающим на базовую модель
Pod'ы, готовые и обслуживающие базовую модель

Полную настройку, включая конфигурацию DGD, см. в разделе Интеграция с DynamoGraphDeployment.

Развертывание адаптера LoRA

1. Создайте DynamoModel:

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

2. Примените и проверьте:

# Apply the DynamoModel
kubectl apply -f my-lora.yaml

# Check status
kubectl get dynamomodel my-lora

Ожидаемый вывод:

NAME      TOTAL   READY   AGE
my-lora   2       2       30s

Вот и все. Оператор автоматически обнаруживает конечные точки и загружает LoRA.

Для подробного мониторинга состояния см. Мониторинг и операции.

Как устроен DynamoModel

Типы моделей

DynamoModel поддерживает три типа моделей:

Тип	Описание	Сценарий использования
`base`	Ссылка на существующую базовую модель	Отслеживание конечных точек базовой модели (по умолчанию)
`lora`	Адаптер LoRA, расширяющий базовую модель	Развертывание дообученных адаптеров поверх существующих моделей
`adapter`	Универсальный адаптер модели	Будущая расширяемость для других типов адаптеров

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

Как это работает

Когда вы создаете DynamoModel, оператор:

Обнаруживает конечные точки: находит все pod'ы, в которых запущен baseModelName (сопоставляя modelRef.name в DGD/DCD)
Создает сервис: автоматически создает Kubernetes Service для отслеживания этих pod'ов
Загружает LoRA: вызывает API загрузки LoRA на каждой конечной точке (для типа lora)
Обновляет статус: сообщает, какие конечные точки готовы

Key linkage:

# DGD modelRef.name ↔ DynamoModel baseModelName must match
Worker:
  modelRef:
    name: Qwen/Qwen3-0.6B
---
spec:
  baseModelName: Qwen/Qwen3-0.6B

Обзор конфигурации

Для развертывания модели или адаптера DynamoModel требует всего несколько ключевых полей:

Поле	Обязательно	Назначение	Пример
`modelName`	Да	Идентификатор модели	`my-custom-lora`
`baseModelName`	Да	Связь с `modelRef` в DGD	`Qwen/Qwen3-0.6B`
`modelType`	Нет	Тип: base/lora/adapter	`lora` (по умолчанию: `base`)
`source.uri`	Для LoRA	Расположение модели	`s3://bucket/path` или `hf://org/model`

Пример минимальной конфигурации LoRA:

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

Полные спецификации полей, правила проверки и все параметры см.: 📖 DynamoModel API Reference

Сводка статуса

Статус показывает обнаруженные конечные точки и их готовность:

kubectl get dynamomodel my-lora

Ключевые поля статуса:

totalEndpoints / readyEndpoints: количество обнаруженных и готовых конечных точек
endpoints[]: список адресов, имен pod'ов и статуса готовности
conditions: стандартные условия Kubernetes (EndpointsReady, ServicesFound)

Подробное использование статуса см. в разделе Мониторинг и операции ниже

Типовые сценарии

Сценарий 1: LoRA-адаптер, размещенный в S3

Разверните адаптер LoRA, хранящийся в корзине S3.

apiVersion: nvidia.com/v1alpha1
kind: DynamoModel
metadata:
  name: customer-support-lora
  namespace: production
spec:
  modelName: customer-support-adapter-v1
  baseModelName: meta-llama/Llama-3.3-70B-Instruct
  modelType: lora
  source:
    uri: s3://my-models-bucket/loras/customer-support/v1

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

S3-корзина доступна из ваших pod'ов (IAM-роль или учетные данные)
Базовая модель meta-llama/Llama-3.3-70B-Instruct запущена через DGD/DCD

Проверка:

# Проверить, что LoRA загружена
kubectl get dynamomodel customer-support-lora -o jsonpath='{.status.readyEndpoints}'
# Should output: 2 (or your number of replicas)

# Посмотреть, какие pod'ы обслуживают модель
kubectl get dynamomodel customer-support-lora -o jsonpath='{.status.endpoints[*].podName}'

Сценарий 2: LoRA, размещенная в HuggingFace

Разверните адаптер LoRA из HuggingFace Hub.

apiVersion: nvidia.com/v1alpha1
kind: DynamoModel
metadata:
  name: multilingual-lora
  namespace: dynamo-system
spec:
  modelName: multilingual-adapter
  baseModelName: Qwen/Qwen3-0.6B
  modelType: lora
  source:
    uri: hf://myorg/qwen-multilingual-lora@v1.0.0  # Optional: @revision

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

HuggingFace Hub доступен из ваших pod'ов
Если репозиторий приватный: токен HF настроен как secret и смонтирован в pod'ах
Базовая модель Qwen/Qwen3-0.6B запущена через DGD/DCD

С токеном HuggingFace:

# В вашем DGD/DCD
spec:
  services:
    worker:
      envFromSecret: hf-token-secret  # Provides HF_TOKEN env var
      modelRef:
        name: Qwen/Qwen3-0.6B
      # ... rest of config

Сценарий 3: Несколько LoRA на одной базовой модели

Разверните несколько адаптеров LoRA поверх одного развертывания базовой модели.

---
# LoRA для поддержки клиентов
apiVersion: nvidia.com/v1alpha1
kind: DynamoModel
metadata:
  name: support-lora
spec:
  modelName: support-adapter
  baseModelName: Qwen/Qwen3-0.6B
  modelType: lora
  source:
    uri: s3://models/support-lora

---
# LoRA для генерации кода
apiVersion: nvidia.com/v1alpha1
kind: DynamoModel
metadata:
  name: code-lora
spec:
  modelName: code-adapter
  baseModelName: Qwen/Qwen3-0.6B  # Same base model
  modelType: lora
  source:
    uri: s3://models/code-lora

Обе LoRA будут загружены во все pod'ы, обслуживающие Qwen/Qwen3-0.6B. Затем ваше приложение сможет направлять запросы к нужному адаптеру.

Мониторинг и операции

Проверка статуса

Quick status check:

kubectl get dynamomodel

Example output:

NAME              TOTAL   READY   AGE
my-lora           2       2       5m
customer-lora     4       3       2h

Detailed status:

kubectl describe dynamomodel my-lora

Example output:

Name:         my-lora
Namespace:    dynamo-system
Spec:
  Model Name:       my-custom-lora
  Base Model Name:  Qwen/Qwen3-0.6B
  Model Type:       lora
  Source:
    Uri:  s3://my-bucket/my-lora
Status:
  Ready Endpoints:  2
  Total Endpoints:  2
  Endpoints:
    Address:   http://10.0.1.5:9090
    Pod Name:  worker-0
    Ready:     true
    Address:   http://10.0.1.6:9090
    Pod Name:  worker-1
    Ready:     true
  Conditions:
    Type:     EndpointsReady
    Status:   True
    Reason:   EndpointsDiscovered
Events:
  Type    Reason              Message
  ----    ------              -------
  Normal  EndpointsReady      Discovered 2 ready endpoints for base model Qwen/Qwen3-0.6B

Понимание готовности

Конечная точка считается готовой, когда:

Pod запущен и исправен
Вызов API загрузки LoRA завершился успешно

Состояния условий:

EndpointsReady=True: все конечные точки готовы (полная доступность)
EndpointsReady=False, Reason=NotReady: готовы не все конечные точки (проверьте счетчики в сообщении)
EndpointsReady=False, Reason=NoEndpoints: конечные точки не найдены

Когда readyEndpoints < totalEndpoints, оператор автоматически повторяет попытку загрузки каждые 30 секунд.

Просмотр конечных точек

Получить адреса конечных точек:

kubectl get dynamomodel my-lora -o jsonpath='{.status.endpoints[*].address}' | tr ' ' '\n'

Вывод:

http://10.0.1.5:9090
http://10.0.1.6:9090

Получить имена pod'ов конечных точек:

kubectl get dynamomodel my-lora -o jsonpath='{.status.endpoints[*].podName}' | tr ' ' '\n'

Проверить готовность каждой конечной точки:

kubectl get dynamomodel my-lora -o json | jq '.status.endpoints[] | {podName, ready}'

Вывод:

{
  "podName": "worker-0",
  "ready": true
}
{
  "podName": "worker-1",
  "ready": true
}

Обновление модели

Чтобы обновить LoRA (например, развернуть новую версию):

# Edit the source URI
kubectl edit dynamomodel my-lora

# Or apply an updated YAML
kubectl apply -f my-lora-v2.yaml

Оператор обнаружит изменение и перезагрузит LoRA на всех конечных точках.

Удаление модели

kubectl delete dynamomodel my-lora

Для моделей LoRA оператор:

Выгрузит LoRA из всех конечных точек
Очистит связанные ресурсы
Удалит ресурс DynamoModel

Развертывание базовой модели (DGD/DCD) продолжит работать в обычном режиме.

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

Конечные точки не найдены

Симптом:

status:
  totalEndpoints: 0
  readyEndpoints: 0
  conditions:
  - type: EndpointsReady
    status: "False"
    reason: NoEndpoints
    message: "No endpoint slices found for base model Qwen/Qwen3-0.6B"

Распространенные причины:

Развертывание базовой модели не запущено
```
# Проверить, существуют ли pod'ы
kubectl get pods -l nvidia.com/dynamo-component-type=worker
```
Решение: Сначала разверните DGD/DCD и дождитесь готовности pod'ов.
Несоответствие baseModelName
```
# Проверить modelRef в вашем DGD
kubectl get dynamographdeployment my-deployment -o yaml | grep -A2 modelRef
```
Решение: Убедитесь, что baseModelName в DynamoModel точно совпадает с modelRef.name в DGD.
Pod'ы не готовы
```
# Проверить статус pod'ов
kubectl get pods -l nvidia.com/dynamo-component-type=worker
```
Решение: Дождитесь, пока pod'ы достигнут состояний Running и Ready.
Неверный namespace Решение: Убедитесь, что DynamoModel находится в том же namespace, что и ваш DGD/DCD.

Ошибки загрузки LoRA

Symptom:

status:
  totalEndpoints: 2
  readyEndpoints: 0  # ← No endpoints ready despite pods existing
  conditions:
  - type: EndpointsReady
    status: "False"
    reason: NoReadyEndpoints

Распространенные причины:

Источник URI недоступен
```
# Проверить журналы оператора
kubectl logs -n dynamo-system deployment/dynamo-operator-controller-manager -f | grep "Failed to load"
```
Решение:
- Для S3: проверьте права на корзину, IAM-роль и учетные данные
- Для HuggingFace: проверьте, что токен действителен, репозиторий существует и доступен
Неверный формат LoRA Решение: Убедитесь, что веса LoRA имеют формат, ожидаемый вашим backend-фреймворком (SGLang, vLLM и т. д.)

Ошибки API конечной точки

# Проверить журналы оператора на HTTP-ошибки
kubectl logs -n dynamo-system deployment/dynamo-operator-controller-manager | grep "error"

Решение: Проверьте журналы backend-фреймворка в worker pod'ах:

kubectl logs worker-0

Нехватка памяти Решение: Адаптерам LoRA требуется дополнительная память. Увеличьте лимиты памяти в DGD:
```
resources:
  limits:
    memory: "32Gi"  # Increase if needed
```

Статус показывает Not Ready

Symptom: Некоторые конечные точки остаются неготовыми длительное время.

Диагностика:

# Проверить, какие конечные точки не готовы
kubectl get dynamomodel my-lora -o json | jq '.status.endpoints[] | select(.ready == false)'

# Просмотреть журналы оператора для этого pod'а
kubectl logs -n dynamo-system deployment/dynamo-operator-controller-manager | grep "worker-0"

# Проверить журналы worker pod'а
kubectl logs worker-0 | tail -50

Распространенные причины:

Проблемы сети: pod не может достучаться до S3/HuggingFace
Ограничения ресурсов: pod уходит в OOM или подвергается throttling
API конечной точки не отвечает: backend-фреймворк не обслуживает API LoRA

Когда ждать, а когда разбираться:

Ждать: если readyEndpoints со временем растет (LoRA загружаются постепенно)
Разбираться: если значение readyEndpoints не меняется более 5 минут

Просмотр событий и журналов

Проверить события:

kubectl describe dynamomodel my-lora | tail -20

Просмотреть журналы оператора:

# Следить за журналами
kubectl logs -n dynamo-system deployment/dynamo-operator-controller-manager -f

# Отфильтровать по конкретной модели
kubectl logs -n dynamo-system deployment/dynamo-operator-controller-manager | grep "my-lora"

Типовые события и сообщения:

Событие/сообщение	Значение	Действие
`EndpointsReady`	Все конечные точки готовы	✅ Хорошо: полная доступность сервиса
`NotReady`	Не все конечные точки готовы	⚠️ Проверьте число `readyEndpoints` - оператор повторит попытку
`PartialEndpointFailure`	Не удалось загрузить часть конечных точек	Проверьте журналы на наличие ошибок
`NoEndpointsFound`	Pod'ы не обнаружены	Убедитесь, что DGD запущен и `modelRef` совпадает
`EndpointDiscoveryFailed`	Невозможно запросить конечные точки	Проверьте RBAC-права оператора
`Successfully reconciled`	Согласование завершено	✅ Хорошо

Интеграция с DynamoGraphDeployment

В этом разделе показан полный end-to-end рабочий процесс совместного развертывания базовых моделей и адаптеров LoRA.

DynamoModel и DynamoGraphDeployment вместе обеспечивают полное развертывание модели:

DGD: разворачивает инфраструктуру (pod'ы, сервисы, ресурсы)
DynamoModel: управляет операциями, специфичными для модели (загрузка LoRA)

Связывание моделей с компонентами

Связь устанавливается через поле modelRef в вашем DGD:

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

---
# 1. Развернуть инфраструктуру базовой модели
apiVersion: nvidia.com/v1alpha1
kind: DynamoGraphDeployment
metadata:
  name: my-deployment
spec:
  backendFramework: vllm
  services:
    Frontend:
      componentType: frontend
      replicas: 1
      extraPodSpec:
        mainContainer:
          image: nvcr.io/nvidia/ai-dynamo/vllm-runtime:latest

    Worker:
      # Этот modelRef создает связь с DynamoModel
      modelRef:
        name: Qwen/Qwen3-0.6B  # ← Ключевое поле связи

      componentType: worker
      replicas: 2
      resources:
        limits:
          gpu: "1"
      extraPodSpec:
        mainContainer:
          image: nvcr.io/nvidia/ai-dynamo/vllm-runtime:latest
          args:
            - --model
            - Qwen/Qwen3-0.6B
            - --tensor-parallel-size
            - "1"

---
# 2. Развернуть адаптеры LoRA поверх
apiVersion: nvidia.com/v1alpha1
kind: DynamoModel
metadata:
  name: my-lora
spec:
  modelName: my-custom-lora
  baseModelName: Qwen/Qwen3-0.6B  # ← Должно совпадать с `modelRef.name` выше
  modelType: lora
  source:
    uri: s3://my-bucket/loras/my-lora

Рабочий процесс развертывания

Рекомендуемый порядок:

# 1. Развернуть инфраструктуру базовой модели
kubectl apply -f my-deployment.yaml

# 2. Дождаться готовности pod'ов
kubectl wait --for=condition=ready pod -l nvidia.com/dynamo-component-type=worker --timeout=5m

# 3. Развернуть адаптеры LoRA
kubectl apply -f my-lora.yaml

# 4. Проверить, что LoRA загружена
kubectl get dynamomodel my-lora

Что происходит внутри:

Шаг	DGD	DynamoModel
1	Создает pod'ы с `modelRef`	-
2	Pod'ы переходят в состояние running и ready	-
3	-	CR создан, обнаруживает конечные точки через автоматически созданный Service
4	-	Вызывает API загрузки LoRA на каждой конечной точке
5	-	Все конечные точки готовы ✓

Оператор автоматически выполняет все операции discovery - вручную настраивать сервисы, метки или селекторы не нужно.

API Reference

Полные спецификации полей, правила проверки и подробные определения типов см.:

📖 Dynamo CRD API Reference

Итог

DynamoModel предоставляет декларативное управление моделями для развертываний Dynamo:

✅ Просто: развертывание LoRA в 2 шага ✅ Автоматически: обнаружение конечных точек и загрузку берет на себя оператор ✅ Наблюдаемость: подробные статусы и условия ✅ Интеграция: бесшовная работа с DynamoGraphDeployment

Следующие шаги:

Попробуйте пример Быстрый старт
Изучите Типовые сценарии
Ознакомьтесь с API Reference для расширенной настройки

Обзор​

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

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

Развертывание адаптера LoRA​

Как устроен DynamoModel​

Типы моделей​

Как это работает​

Обзор конфигурации​

Сводка статуса​

Типовые сценарии​

Сценарий 1: LoRA-адаптер, размещенный в S3​

Сценарий 2: LoRA, размещенная в HuggingFace​

Сценарий 3: Несколько LoRA на одной базовой модели​

Мониторинг и операции​

Проверка статуса​

Понимание готовности​

Просмотр конечных точек​

Обновление модели​

Удаление модели​

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

Конечные точки не найдены​

Ошибки загрузки LoRA​

Статус показывает Not Ready​

Просмотр событий и журналов​

Интеграция с DynamoGraphDeployment​

Связывание моделей с компонентами​

Рабочий процесс развертывания​

API Reference​

Итог​

Обзор

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

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

Развертывание адаптера LoRA

Как устроен DynamoModel

Типы моделей

Как это работает

Обзор конфигурации

Сводка статуса

Типовые сценарии

Сценарий 1: LoRA-адаптер, размещенный в S3

Сценарий 2: LoRA, размещенная в HuggingFace

Сценарий 3: Несколько LoRA на одной базовой модели

Мониторинг и операции

Проверка статуса

Понимание готовности

Просмотр конечных точек

Обновление модели

Удаление модели

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

Конечные точки не найдены

Ошибки загрузки LoRA

Статус показывает Not Ready

Просмотр событий и журналов

Интеграция с DynamoGraphDeployment

Связывание моделей с компонентами

Рабочий процесс развертывания

API Reference

Итог