Доступно в редакциях:  EE

Стадия жизненного цикла модуля: Experimental
У модуля есть требования для установки

Модуль добавляет в DKP каталог файлов AI/ML-моделей и подключает эти файлы к приложениям Kubernetes. Пользователь создаёт Model или ClusterModel с источником модели. Контроллер получает файлы, проверяет формат, упаковывает их во внутренний OCI-артефакт, сохраняет локальную копию в DMCR и показывает состояние в status.

Модуль не запускает среду инференса и не ограничен только LLM. Он работает с артефактами моделей в поддерживаемых форматах, например Safetensors, GGUF и Diffusers. Приложение получает путь к файлам модели и само выбирает, как их использовать.

Сценарии использования

  • Создать Model из Hugging Face, Ollama или локальной загрузки и получить директорию с файлами модели внутри Pod.
  • Создать ClusterModel, чтобы несколько команд использовали одну подготовленную модель по стабильному имени.
  • Подключить модель к Deployment, StatefulSet, DaemonSet или CronJob одной аннотацией в верхнем metadata.
  • Доставить подготовленную модель через SharedPVC, если в кластере есть хранилище с поддержкой ReadWriteMany.
  • Доставить большую модель через NodeCache, если несколько рабочих нагрузок читают её на одних и тех же узлах.
  • Отдать кластерные модели в фазе Ready через публичный каталог и импортировать локальную копию в другом кластере.

Роли

Роль Ответственность С чего начать
Администратор кластера Включает модуль, настраивает объектное хранилище, выбирает способ доставки, открывает публичный каталог, выдаёт доступ и следит за состоянием служебных компонентов. Руководство администратора
Пользователь неймспейса Создаёт или импортирует модели, загружает локальные файлы, подключает модели в фазе Ready к приложениям. Руководство пользователя
Оператор приложения Хранит манифесты рабочих нагрузок в Git и использует модели через аннотации. Руководство пользователя

Основные ресурсы

Ресурс Область Назначение
Model неймспейс Модель команды или приложения в одном неймспейсе.
ClusterModel кластер Общая модель, которой управляет администратор кластера.
ModelCatalogSource кластер Описание внешнего каталога ClusterModel, из которого кластер импортирует локальные копии.

Model поддерживает приватные Hugging Face источники через секрет в том же неймспейсе. ClusterModel предназначен для общих удалённых источников и не ссылается на секрет из неймспейса приложения. ModelCatalogSource ссылается на учётные данные в d8-system. Доступ к публичному каталогу проверяется через Kubernetes RBAC в кластере, который раздаёт каталог.

Обработка модели после создания

Пользователь задаёт только источник модели: URL, сессию загрузки или запись во внешнем каталоге. Контроллер сам выбирает внутренний путь в DMCR, проверяет данные, упаковывает исходные файлы в OCI-артефакт и записывает результат в status. Контрольная сумма появляется в status.artifact.digest после успешной проверки.

ModelPack — это внутренний формат такой OCI-упаковки. Он нужен модулю для проверки, возобновления после сбоя, очистки и повторной доставки. Это не конвертация весов модели: GGUF остаётся GGUF, Safetensors остаётся Safetensors. Пользователь не выбирает ModelPack, контрольную сумму, тег или путь в реестре.

status.phase: Ready означает, что локальная копия модели проверена и сохранена, а контроллер может начать доставку в рабочую нагрузку или импорт в другой кластер. В рабочую нагрузку передаётся стабильный контракт:

  • директория моделей: /data/modelcache/models;
  • переменная AI_MODELS_MODELS_DIR;
  • переменная AI_MODELS_MODELS со списком моделей, путей, контрольных сумм и семейств.

Доставка и раздача каталога

Доставка отвечает за подключение модели в фазе Ready к рабочей нагрузке внутри кластера.

Способы доставки:

  • SharedPVC — режим по умолчанию. Контроллер создаёт PVC с ReadWriteMany в неймспейсе рабочей нагрузки, служебная задача загружает туда модель, Pod’ы читают её только на чтение. Локальный RWO PVC не является отдельным режимом доставки.
  • NodeCache — режим локального кэша на узле поверх SDS. На выбранных нодах создаётся общий кэш, а рабочая нагрузка получает CSI-монтирование только на чтение.

Раздача каталога относится к обмену моделями между кластерами, а не к способу доставки в приложения. Она нужна для топологий с DMZ, внутренним периметром или внешним проверенным каталогом: один кластер отдаёт список ClusterModel в фазе Ready, другой импортирует выбранную модель в локальный DMCR и только после этого использует обычную доставку. Внутренние @sha256 и OCI-пути остаются служебными деталями копирования.

Публичный каталог включается через distribution.mode=PublicCatalog и использует публичный адрес модуля из глобальных настроек Deckhouse. Администратор раздающего кластера выдаёт доступ субъекту Kubernetes, обычно ServiceAccount, через ClusterRole d8:ai-models:distribution:reader. Потребляющий кластер хранит полученный токен в секрете неймспейса d8-system и описывает источник через ModelCatalogSource.

Импорт из внешнего каталога восстанавливается после ошибок на стороне источника. Если истёк токен, исправили CA или источник временно был не готов, выбранная ревизия каталога и удалённая контрольная сумма остаются зафиксированными, а контроллер повторяет импорт после восстановления источника.

Компоненты

Компонент Неймспейс Назначение
ai-models-controller d8-ai-models Управляет ресурсами Model / ClusterModel, загрузками, доставкой и метриками.
publish-worker d8-ai-models Читает источник модели и сохраняет проверенный OCI-артефакт в DMCR.
upload-gateway d8-ai-models Принимает прямую загрузку файла или архива.
DMCR d8-ai-models Deckhouse Model Container Registry: служебный OCI-реестр модуля, где хранятся подготовленные модели. Работает поверх настроенного объектного хранилища.
node-cache-runtime выбранные ноды Подготавливает локальный кэш на узле и CSI-монтирование для NodeCache.

Документация