Version: 1.4.2

Руководство по запуску нексуса

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

tip

Требуемая роль: mai_admin. Все записи, которые создаются в этом руководстве, доступны для создания, изменения и удаления только с ней. Роль mai_reporter дает чтение. Состав ролей на чтение отличается от записи к записи – он указан в статье о каждой из них.

Предварительные настройки

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

Экземпляр ИИ – экземпляр ИИ-модели или сервиса, развернутый на конкретной инфраструктуре.
Конечная точка – конечная точка, на которую будут отправляться запросы.
Модель – модель, которая будет использована в теле запроса. Запись обязательна для больших языковых моделей (LLM), таких как gpt-5.
(опционально) Токен аутентификации – токен авторизации через Bearer token.

Все перечисленные записи находятся в навигаторе в разделе Управление инсталляциями приложений (MAI) → Маршрутизация ИИ.

Экземпляр ИИ

Перейдите в навигаторе в Управление инсталляциями приложений (MAI) → Маршрутизация ИИ → Экземпляры ИИ.
Нажмите Создать, чтобы открыть форму новой записи.
Заполните поля:
- Название – укажите отображаемое название экземпляра.
- Провайдер – выберите существующего провайдера. Вы можете создать запись нового провайдера через кнопку . В этом случае укажите название нового провайдера в поле Name и сохраните запись.
- Тип – выберите Модель для модели нейросети или ИИ сервис для сервиса обработки данных.
- Хост – укажите хост, на котором размещен API модели или сервиса, например: https://api.openai.com/v1.
Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.

Читайте подробнее об остальных полях формы в статье Экземпляры ИИ.

Конечная точка

Перейдите в навигаторе в Управление инсталляциями приложений (MAI) → Маршрутизация ИИ → Конечные точки.
Нажмите Создать, чтобы открыть форму новой записи.
Заполните поля:
- Endpoint – укажите путь конечной точки API, например: /chat/completions.
- Description – опишите, что делает конечная точка, и укажите ссылку на документацию провайдера.
Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.

Читайте подробнее в статье Конечные точки.

Модель

Перейдите в навигаторе в Управление инсталляциями приложений (MAI) → Маршрутизация ИИ → Модели провайдера.
Нажмите Создать, чтобы открыть форму новой записи.
Заполните поля:
- Провайдер – выберите существующего провайдера.
- Name – укажите название модели, например, gpt-5.2-2025-12-11.
Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.

Токен аутентификации

Перейдите в навигаторе в Управление инсталляциями приложений (MAI) → Маршрутизация ИИ → Токены аутентификации.
Нажмите Создать, чтобы открыть форму новой записи.
Заполните поля:
- Экземпляр ИИ – выберите запись экземпляра ИИ, к которому относится токен.
- Name – понятное имя токена, например: OpenAI DEV KEY.
- Token – значение токена доступа.
Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.

Добавление ресурсов в списки доступного

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

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

note

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

Создание и тестирование нексуса

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

Декорация нексуса

Справочник Декорации нексусов (mai_nexus_decoration) содержит записи декораций, которые позволяют выполнять пользовательские скрипты на этапах до и после обращения к API. С помощью декораций также осуществляется настройка нексусов, которая будет доступна клиентам для ознакомления.

Чтобы создать запись декорации нексуса, выполните следующие шаги:

Перейдите в навигаторе в Управление инсталляциями приложений (MAI) → Маршрутизация ИИ → Декорации нексусов.
Нажмите Создать и заполните поля формы.
- Title – название нексуса, которое увидит клиент.
- Operation State – состояние нексуса, например Active.
- Type – тип нексуса. Например, Chat для взаимодействия с нейросетью в виде чата.
- Method – метод класса API. Например, Completion для отправки сообщений в чат.
- Request script – скрипт преобразования запроса. Поле обязательно, поэтому, если преобразование не требуется – например, нейросеть принимает формат OpenAI, – оставьте пустой каркас: ((data) => { })(data);
- Response script – скрипт преобразования ответа:
  Пример для формата OpenAI
```
((data, message) => {
const incomingMessage = data.choices[0].message;
message.completion = incomingMessage.content;
message.$$tools = incomingMessage.tool_calls
    ? JSON.stringify({
        tools: data.choices[0].message.tool_calls.map(tool => {
        return {
            name: tool.function.name,
            arguments: JSON.parse(tool.function.arguments)
        }
        })
    })
    : '';
})(data, AIMessage);
```
Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.

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

Читайте подробнее в статье Декорации нексусов.

Действие фильтра данных

Механизм Действия фильтра данных (PII) предназначен для обнаружения конфиденциальных персональных данных в запросах к нейросетям и выполнения заданных действий для их защиты. Механизм активируется на стороне прокси-сервера при передаче данных.

Перейдите в навигаторе в Управление инсталляциями приложений (MAI) → Маршрутизация ИИ → Действия фильтра данных, чтобы открыть таблицу Действия фильтра данных (mai_nexus_action_pii).
Нажмите Создать и заполните поля формы.
- Name – название действия, например: reroute to local OSS.
- Detection nexus – нексус для обнаружения персональных данных.
  
  В текущей версии платформы актуальный нексус: ain.pii-detection.ner.
- If detected – действие при обнаружении персональных данных:
  - Block (блокировка) – запрос блокируется и не отправляется.
  - Re-route (перемаршрутизация) – требуется указать Re-route nexus, чтобы перенаправить запрос в другой нексус, например в защищенный локальный контур.
  - Mask (маскирование) – требуется указать Mask nexus и Unmask nexus. При обнаружении персональных данных запрос в нейросеть будет отправлен с плейсхолдерами вместо персональных данных. После получения ответа плейсхолдеры будут заменены на исходные значения на уровне платформы. В текущей версии платформы актуальные нексусы: ain.pii-detection.mask и ain.pii-detection.unmask.
Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.

Читайте подробнее в статье Защита персональной информации.

Тестирование нексуса

Создайте тестовый запрос, чтобы проверить функциональность созданного нексуса.

На форме конфигурации нексуса в связанном списке Nexus Test Case нажмите Создать.
Заполните поля:
- Name – название тестового запроса
- Нексус – ссылка на конфигурацию нексуса, для которой создан запрос. Поле заполняется автоматически.
- Request – тестовый запрос.
Пример запроса
```
    {
    "messages": [
      { "role": "user", "content": "Привет, как твои дела?" }
      ]
    }
```
Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.
Вернитесь на созданную запись конфигурации нексуса.
Нажмите Test Configuration в правом верхнем углу, чтобы отправить тестовый запрос.
Уведомление о завершении теста появится во всплывающем сообщении, а в связанном списке Nexus Test Result появится запись с результатом.

Развертывание конфигурации в приложении

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

Если изменения не применились, перезалейте конфигурацию вручную: откройте запись инфраструктуры Middleware и в бургер-меню выберите Обновление конфигурации → ⬆️ Нексусы.

Читайте подробнее в статье Доставка конфигураций.

Добавление нексуса потребителю через лицензию

Перейдите в навигаторе в Управление инсталляциями приложений (MAI) → License and Quota Management → License.
Откройте запись нужной лицензии из списка.
В связанном списке License Nexus Limit нажмите Add.
В поле Nexus выберите ранее созданную конфигурацию.
(опционально) Заполните поля лимитов и квоты, чтобы ограничить этот нексус на уровне лицензии.
(опционально) Установите флажок Specify rate limits for consumers, чтобы те же лимиты были проставлены потребителям в строках лимитов этого нексуса.
(опционально) Установите флажок Available for all, чтобы сделать нексус доступным всем потребителям в рамках лицензии.

Если флажок снят, укажите потребителей в поле Specify consumers that will have access to the nexus.
Нажмите Add nexus, чтобы добавить настроенный нексус в лицензию.
Повторите шаги 3-8 для всех нексусов, которые необходимо добавить в лицензию.

Читайте подробнее в статье Лицензии.

Проверка работоспособности на стороне клиента

Проверьте доступность нексуса. Для этого:

Перейдите в навигаторе в Ainergy → Настройки ИИ → Виджет настройки.
Нажмите значок обновления рядом с заголовком списка All nexuses.
Убедитесь, что новый нексус появился в списке.

Предварительные настройки​

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

Конечная точка​

Модель​

Токен аутентификации​

Добавление ресурсов в списки доступного​

Создание и тестирование нексуса​

Декорация нексуса​

Действие фильтра данных​

Тестирование нексуса​

Развертывание конфигурации в приложении​

Добавление нексуса потребителю через лицензию​

Проверка работоспособности на стороне клиента​