Обзор

Модуль добавляет в 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 через публичный каталог и импортировать локальную копию в другом кластере.

Роли

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

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

Что происходит после создания модели

  flowchart LR
  User["Пользователь"] --> API["Model / ClusterModel"]
  API --> Controller["Контроллер"]
  Controller --> Worker["Служебный процесс подготовки"]
  Worker --> Store["OCI-артефакт в DMCR"]
  Controller --> Status["Статус, условия, метаданные"]
  Workload["Рабочая нагрузка с аннотацией модели"] --> Delivery["Контроллер доставки"]
  Delivery --> SharedPVC["RWX PVC"]
  Delivery --> NodeCache["Кэш на узле"]

Пользователь задаёт только источник модели: 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 в пространстве имён рабочей нагрузки, служебная Job загружает туда модель, Pod’ы читают её только на чтение. Локальный RWO PVC не является отдельным режимом доставки.
• NodeCache — режим локального кэша на узле поверх SDS. На выбранных нодах создаётся общий кэш, а рабочая нагрузка получает CSI-монтирование только на чтение.

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

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

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

Компоненты

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

• Руководство пользователя — создание моделей и подключение в рабочие нагрузки.
• Руководство администратора — включение, хранилище, RBAC, мониторинг и эксплуатация.
• Конфигурация — параметры ModuleConfig.
• Пользовательские ресурсы — ресурсы Model и ClusterModel.
• Примеры — YAML-манифесты для типовых сценариев.
• FAQ — частые вопросы и диагностика.

Внешние компоненты

Список стороннего программного обеспечения, используемого в модуле ai-models (информация представлена на английском языке):

• AI Models 0.0.1

  License: Apache License 2.0

  Deckhouse module for AI/ML model registry and catalog services.