Экземпляры ИИ

Запись таблицы Экземпляры ИИ (mai_nn_instance) описывает экземпляр модели или ИИ-сервиса, размещенный у провайдера или развернутый на вашей инфраструктуре. Экземпляр – это то, к чему в итоге обращается нексус: он задает провайдера, хост и набор ресурсов, которые разрешено использовать.

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

tip

Требуемые роли:

• Чтение – mai_reporter.
• Создание – mai_admin.
• Обновление – mai_admin.
• Удаление – mai_admin.

Создание записи экземпляра ИИ

---

1. Перейдите в навигаторе в Управление инсталляциями приложений (MAI) → Маршрутизация ИИ → Экземпляры ИИ.
2. Нажмите Создать и заполните поля формы.
3. Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.

Поля формы Экземпляры ИИ

Поле	Обязательно	Описание
Название	Нет	Укажите отображаемое название экземпляра.
Описание	Нет	Добавьте описание экземпляра, например, адреса веб-интерфейса и документации провайдера или список разрешенных IP-адресов.
Провайдер	Нет	Выберите провайдера нейросети из справочника.
Тип	Да	Выберите тип экземпляра. Доступные опции: Модель – модель нейросети; ИИ сервис – сервис обработки данных.
Хост	Да	Укажите хост, на котором размещен API модели или сервиса. Например: https://api.deepseek.com. Для модели или сервиса в собственном контуре укажите схему, DNS-имя или IP-адрес виртуальной машины и порт, опубликованный в файле Compose, например http://10.0.0.15:5525. Путь не указывается – его задает конечная точка.
Self-hosted	Нет	Установите флажок, если модель или сервис разворачивается в вашем контуре, а не размещен у провайдера. После установки флажка на форме появляется раздел Deploy с параметрами развертывания. Читайте подробнее ниже, в разделе Развертывание в собственном контуре.
Доступные конечные точки	Нет	Добавьте конечные точки, которые разрешено использовать с этим экземпляром.
Доступные модели	Нет	Добавьте модели из справочника Модели провайдера (mai_nn_model), которые разрешено использовать с этим экземпляром.
Доступные токены	Нет	Добавьте токены аутентификации, которые разрешено использовать с этим экземпляром.

Связанные списки

• Нексусы – конфигурации нексусов, которые обращаются к этому экземпляру.
• Токены аутентификации (mai_nn_instance_token) – токены, созданные для этого экземпляра.
• Control Plane Tasks – задачи общей зоны управления.

Управление доступностью ресурсов

---

Поля Доступные модели, Доступные конечные точки и Доступные токены определяют, что можно выбрать в конфигурации нексуса для этого экземпляра. Проверка работает в обе стороны.

При настройке нексуса. Если в конфигурации нексуса выбрать модель, конечную точку или токен, которых нет в соответствующем списке выбранного экземпляра, сохранение прерывается и отображается сообщение:

• «Модель "название модели" недоступна для выбранного экземпляра ИИ»
• «Конечная точка название конечной точки недоступна для выбранного экземпляра ИИ»
• «Токен "название токена" недоступен для выбранного экземпляра ИИ»

При изменении списков. Если убрать из списка элемент, который уже используется в конфигурациях нексусов, сохранение прерывается и отображается сообщение «Существуют нексусы с удаляемой моделью/токеном/конечной точкой». Слово «нексусы» в сообщении – ссылка на список затронутых конфигураций с уже подставленным фильтром, поэтому вы можете сразу перейти к ним и изменить настройки.

note

Чтобы вывести модель, конечную точку или токен из использования, сначала измените конфигурации нексусов, которые на них ссылаются, и только затем уберите элемент из списка доступного.

Развертывание в собственном контуре

---

Кроме подключения моделей и сервисов, размещенных у провайдера, запись экземпляра ИИ позволяет установить модель или сервис в вашем контуре и управлять им.

Устанавливаемый сервис должен запускаться в Docker через Docker Compose. Технически платформа позволяет запустить любой Docker-контейнер.

Установку выполняет машина Control Plane – машина, на которой размещена поставка платформы и с которой выполняется развертывание ее компонентов. Она подключается к виртуальной машине по SSH и запускает на ней сервис.

Готовые конфигурации собраны в реестре моделей и сервисов Ainergy. Карточка модели или сервиса содержит файл Docker Compose, переменные окружения, ссылки на скачивание Docker-образа и весов модели, а также требования к виртуальной машине. По умолчанию реестр показывает конфигурации для последней версии поставки. Если у вас установлена другая версия, выберите ее в списке версий реестра. Порядок установки описан ниже, в разделе Установка из реестра моделей и сервисов.

Подготовка виртуальной машины

tip

Требуемые роли для таблицы Виртуальные машины:

• Чтение – mai_reporter.
• Создание – mai_admin.
• Обновление – mai_admin.
• Удаление – mai_admin.

Модель или сервис устанавливается на виртуальную машину из таблицы Виртуальные машины (mai_virtual_machine). Чтобы создать запись виртуальной машины:

1. Перейдите в навигаторе в Управление инсталляциями приложений (MAI) → Внутренняя инфраструктура → Виртуальные машины.
2. Нажмите Создать и укажите DNS-имя или IP-адрес машины, ключ из таблицы Ключи SSH (mai_ssh_keys) и имя пользователя для подключения. Если имя пользователя не указано, подключение выполняется от имени root.
3. Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.

Требования к виртуальной машине:

• Установлен Docker, служба запущена. Если Docker недоступен, установка завершается ошибкой Docker precheck failed.
• Установлен Docker Compose v2 (команда docker compose).
• Установлен Python 3.
• Для моделей, работающих на GPU, установлены драйвер NVIDIA и NVIDIA Container Toolkit.
• С машины Control Plane открыт доступ по SSH на порт 22.
• Если Docker-образ или веса модели скачиваются по ссылке, с виртуальной машины открыт доступ по HTTPS к хранилищу: файлы скачивает сама виртуальная машина. Ссылки из реестра ведут на s3.ainergy.ru.

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

1. На форме экземпляра ИИ установите флажок Self-hosted. На форме появится раздел Deploy.
2. Заполните поля раздела Deploy.
3. Нажмите Сохранить, чтобы применить изменения.
4. Нажмите ⬆️ Deploy в правом верхнем углу формы, чтобы запустить установку. Кнопка становится доступной только после сохранения записи с заполненными обязательными полями.

Экземпляр переходит в статус SendToDeploy, а после завершения установки – в Deployed. Статус Deployed означает, что контейнеры запущены. Модели может потребоваться дополнительное время на загрузку весов, прежде чем она начнет отвечать на запросы. После этого можно переходить к созданию конфигурации нексуса.

Если установка завершилась ошибкой, экземпляр переходит в статус Error. Каждое нажатие ⬆️ Deploy и Destroy создает задачу в связанном списке Control Plane Tasks. Чтобы узнать причину ошибки, откройте последнюю задачу:

• в поле Ответ – журнал установки или удаления. Причина указана в сообщении последнего шага, завершившегося ошибкой;
• в поле Ошибка – текст ошибки выполнения задачи, если она возникла.

Чтобы повторить установку после ошибки или применить измененные поля раздела Deploy, например новый файл Compose или окружение, нажмите Сохранить, а затем ⬆️ Deploy. Если веса модели скачиваются по ссылке, при повторной установке они скачиваются заново – для больших моделей это занимает время.

Поля Виртуальная машина и Deploy path доступны для изменения в статусах New, Destroyed и Error.

caution

Если установка завершилась ошибкой, не меняйте поле Deploy path до нажатия Destroy: действие останавливает сервис только в каталоге, указанном в поле на момент нажатия. Чтобы перенести сервис в другой каталог, нажмите Destroy, дождитесь статуса Destroyed, измените поле и нажмите ⬆️ Deploy.

Установка из реестра моделей и сервисов

1. Откройте в реестре карточку модели или сервиса. Убедитесь, что виртуальная машина соответствует требованиям, указанным на карточке.

   Если на карточке сервиса есть раздел Зависимости, сервису для работы нужны перечисленные в нем модели или сервисы. Сначала установите каждую зависимость по этой же инструкции отдельной записью экземпляра ИИ на ту же виртуальную машину, затем – сам сервис. Сервисы из реестра обращаются к зависимостям по имени контейнера в общей сети Docker ainergy-net, которая создается на машине при первой установке.

2. Перейдите в навигаторе в Управление инсталляциями приложений (MAI) → Маршрутизация ИИ → Экземпляры ИИ и нажмите Создать. В поле Тип выберите Модель для карточки модели или ИИ сервис для карточки сервиса.

3. Установите флажок Self-hosted и заполните поля Виртуальная машина и Deploy path.

4. Нажмите Compose на карточке и вставьте скопированное содержимое в поле Compose.

5. Заполните поле Хост: укажите адрес виртуальной машины и порт из раздела ports вставленного файла Compose.

6. Если на карточке есть кнопка Environment, нажмите ее и вставьте скопированное содержимое в поле Окружение.

7. Укажите источник Docker-образа:

   • если на карточке есть кнопка Docker образ, выберите в поле Источник Docker образа значение S3, нажмите Docker образ и вставьте скопированную ссылку в поле S3 URL;
   • если кнопки нет, как у моделей, работающих на vLLM, выберите значение Локально. Скопируйте архив vllm/v0.16.0/image.tar.gz из поставки в каталог local/docker на машине Control Plane и укажите в поле Имя локального архива образов путь /opt/ainergy-playbook/local/docker/image.tar.gz.

8. Если на карточке есть кнопка Копировать ссылку для скачивания, выберите в поле Источник модели значение S3, нажмите кнопку и вставьте скопированную ссылку в поле URL модели в S3.

   note

   Ссылки на скачивание образа и весов модели действуют 14 дней. Если установка запускается позже, скопируйте ссылки на карточке заново.

9. Нажмите Сохранить, чтобы применить изменения.

10. Нажмите ⬆️ Deploy в правом верхнем углу формы, чтобы запустить установку.

Если у виртуальной машины нет доступа к s3.ainergy.ru, скачайте архивы по ссылкам карточки на компьютере с доступом в интернет, перенесите их на машину Control Plane в каталоги local/docker и local/models и выберите в полях Источник Docker образа и Источник модели значение Локально.

Поля раздела Deploy

Поле	Обязательно	Описание
Виртуальная машина	Да	Укажите виртуальную машину, на которую будет установлена модель или сервис. В записи виртуальной машины заданы адрес и SSH-ключ для подключения.
Deploy path	Да	Укажите абсолютный путь к каталогу на виртуальной машине, в который будут помещены файл Compose, файл окружения и веса модели, например /opt/olmocr. Корневой каталог / указать нельзя. Веса модели размещаются в подкаталоге model. Архив весов, скачиваемый по ссылке или из локального каталога, должен содержать верхний каталог model/ – так устроены архивы из реестра.
Compose	Да	Вставьте содержимое файла Docker Compose, который запускает модель или сервис. Если сервис использует веса модели, смонтируйте в контейнер каталог ./model: в нем размещаются веса модели.
Источник Docker образа	Да	Выберите, откуда взять Docker-образ. Доступные опции: Реестр Docker – образ скачивается из реестра, например Docker Hub; Локально – образ доставлен на машину Control Plane вручную в виде архива. Вариант для полностью закрытого контура; S3 – архив с образом скачивается из S3-совместимого хранилища.
Имя локального архива образов	Да/Нет	Укажите полный путь к архиву с образом внутри контейнера Control Plane: /opt/ainergy-playbook/local/docker/<имя файла>. Перед установкой поместите архив на машину Control Plane в каталог local/docker, расположенный рядом с каталогом поставки. Поле обязательно, если в поле Источник Docker образа выбрано Локально.
S3 URL	Да/Нет	Укажите presigned URL для скачивания архива с образом, например ссылку, скопированную кнопкой Docker образ в реестре. Поле обязательно, если в поле Источник Docker образа выбрано S3.
Источник модели	Нет	Выберите, откуда скачать веса модели. Заполняется, если сервис использует нейросетевую или классическую ML-модель. Доступные опции: S3 – веса скачиваются из S3-совместимого хранилища; HuggingFace – веса скачиваются напрямую с Hugging Face. Вариант доступен, если из контура есть доступ к Hugging Face; Локально – веса расположены на машине Control Plane в виде архива.
URL модели в S3	Да/Нет	Укажите presigned URL для скачивания весов модели, например ссылку, скопированную кнопкой Копировать ссылку для скачивания в реестре. Поле обязательно, если в поле Источник модели выбрано S3.
HF Name	Да/Нет	Укажите имя модели на Hugging Face, например Qwen/Qwen3.8-27B. Поле обязательно, если в поле Источник модели выбрано HuggingFace.
HF Token	Нет	Укажите токен авторизации Hugging Face. Токен ускоряет загрузку и дает доступ к моделям с ограниченным доступом.
Имя локального архива модели	Да/Нет	Укажите полный путь к архиву с весами модели внутри контейнера Control Plane: /opt/ainergy-playbook/local/models/<имя файла>. Перед установкой поместите архив на машину Control Plane в каталог local/models, расположенный рядом с каталогом поставки. Если веса уже распакованы в подкаталог model каталога Deploy path на виртуальной машине, помещать архив на машину Control Plane не нужно. Поле обязательно, если в поле Источник модели выбрано Локально.
Окружение	Нет	Укажите переменные окружения в формате ИМЯ=значение, по одной на строке. Значение сохраняется на виртуальной машине в файл .env рядом с файлом Compose – подключите его в Compose параметром env_file.
Статус	Нет	Текущее состояние экземпляра. Возможные опции: New – запись создана; SendToDeploy – отправлен на установку; Deployed – установлен; SendToDestroy – отправлен на удаление; Destroyed – удален; Error – ошибка установки или удаления.

Действия раздела Deploy

UI-действие	Описание
⬆️ Deploy	Нажмите, чтобы запустить установку модели или сервиса на выбранную виртуальную машину. Повторное нажатие применяет сохраненные изменения полей раздела Deploy. Действие доступно в статусах New, Deployed, Destroyed и Error.
Destroy	Нажмите кнопку в правом верхнем углу формы, чтобы остановить модель или сервис и удалить их контейнеры. Действие доступно в статусах Deployed и Error. Каталог Deploy path с весами модели, Docker-образы и тома Docker, если файл Compose их создавал, остаются на виртуальной машине. Чтобы освободить диск, удалите на машине каталог Deploy path, образы командой docker image rm <образ> и тома командой docker volume rm <том>.