Провайдер ИИ

Где найти в админ-панели: System › Settings › AI provider (/settings/ai). Переключатель модуля ИИ есть там и в System › Admin › License & updates (/license), карточка Module.

Назначение

AI Chat (автоматическая поддержка) и AI Agent (управление ВМ на естественном языке) поставляются без встроенной модели. Вы выбираете собственного провайдера: любой сервис с chat/completions API, совместимым с OpenAI, — например OpenAI, OpenRouter, шлюз LiteLLM или собственный сервер vLLM. NexCMP сохраняет эндпоинт и API-ключ (в зашифрованном виде) и использует их для всех функций ИИ. Оплата производится напрямую провайдеру.

Требования

Параметр	Требование
Endpoint	OpenAI-совместимый базовый URL (https://api.openai.com/v1, https://ai.example.com/v1). NexCMP добавляет /chat/completions к URL, заканчивающимся на /v1; для других URL добавляется /v1/chat/completions; URL, уже оканчивающийся на /chat/completions, используется как есть.
Модель	Модель с поддержкой вызова инструментов (функций). На нее опираются как AI Chat, так и агент.
API-ключ	Ключ для этого эндпоинта. Рекомендуется использовать ключ с лимитом расходов на стороне провайдера (например, виртуальный ключ LiteLLM с месячным бюджетом).
Сеть	Сервер панели должен иметь доступ к эндпоинту по HTTP(S). URL, указанный в форме, может вести только в интернет на порты 80, 443, 8080 или 8443; чтобы использовать внутренний адрес, сначала сохраните провайдера, а затем выполните проверку.
Зависимости	Включенный модуль AI. Информацию об агенте см. в AI Agent.

Подготовка инфраструктуры

1. Зарегистрируйтесь у провайдера и создайте API-ключ. Если провайдер поддерживает бюджеты или лимиты запросов, установите ежемесячный лимит.

2. Запишите базовый URL и точное название модели (а также, при необходимости, до четырех резервных моделей).

3. Проверьте его с сервера NexCMP перед вводом:

   curl -s https://ai.example.com/v1/chat/completions \
     -H "Authorization: Bearer XXXX" -H "Content-Type: application/json" \
     -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Reply with one word: OK"}]}'

   Ответ JSON с choices[0].message.content означает, что эндпоинт работает.

Подключение в NexCMP

1. Перейдите в System › Settings › AI provider.

2. В карточке Module AI переключите модуль в положение on. Пока он не включен, клиенты не видят AI Chat и AI Agent в портале. (Его также можно включить в License & updates.)

3. В карточке Connection заполните:

   Поле	Пример	Примечания
   Использовать этого провайдера	включено	Для включения требуются базовый URL, модель и ключ.
   Display name	LiteLLM	До 60 символов.
   Базовый URL (OpenAI-совместимый)	https://ai.example.com/v1	http:// или https://, до 300 символов, без пробелов.
   API-ключ провайдера	sk-XXXX	Хранится в зашифрованном виде; после сохранения отображаются только последние 4 символа. Оставьте пустым, чтобы сохранить текущий ключ.
   Модель по умолчанию	gpt-4o-mini	Буквы, цифры и - _ . / : @.
   Резервные модели	gemini-2.5-flash	Разделяются запятыми, до 4 моделей. Используются при сбое модели по умолчанию.
   Reasoning effort	Default (не отправляется)	Minimal, Low, Medium или High. Для рассуждающих моделей (Gemini, серия o) низкий уровень обеспечивает гораздо более быстрый ответ. Для обычных моделей оставьте значение Default.

4. Нажмите Save, затем Test connection. Проверка отправит один короткий вопрос и отобразит Connected — <model>, <ms> ms или ошибку, возвращенную провайдером.

Что происходит при сохранении

• Настройки провайдера сохраняются как единая запись конфигурации, а ключ шифруется с помощью AES-256-GCM для этой цели с использованием мастер-ключа установки.
• Параметры поддержки Primary model и Fallback model (используемые в AI Chat) автоматически настраиваются на вашу модель по умолчанию и первую резервную модель.
• Изменение записывается в журнал аудита (эндпоинт, модель, факт изменения ключа — сам ключ никогда не записывается).

Проверка

1. Test connection отображается зеленым цветом.
2. Войдите в портал под тестовым клиентом: в меню теперь доступны AI Chat (или значок чата) и AI Agent.
3. Спросите у AI Chat «What is my balance?». Ответ с указанием вашего реального баланса подтверждает, что провайдер корректно обрабатывает вызовы инструментов.

Ограничения и примечания

• Один провайдер. NexCMP использует единого настроенного провайдера для чата, агента и анализа тикетов. Резервные модели обеспечивают отказоустойчивость в рамках этого провайдера.
• Безопасность ключа. Сохраненный ключ отправляется только на сохраненный эндпоинт. При изменении Base URL необходимо заново ввести ключ перед тестированием.
• Лимиты на клиента. AI Chat доступен только авторизованным клиентам с лимитами сообщений в минуту и на чат. Для агента действует суточный лимит вызовов на аккаунт. См. AI Chat и AI Agent.
• Конфиденциальность. Вопросы клиентов и данные, которые считывает AI для этого клиента (в режиме только для чтения), отправляются вашему провайдеру. Укажите это в своей политике конфиденциальности.
• Контроль затрат. NexCMP не ведет учет стоимости AI; используйте функции управления бюджетом у провайдера.
• Модуль можно отключить в любой момент: пункты меню AI исчезнут, а маршруты AI будут возвращать 404 module_disabled. Некоторые фоновые задачи AI Chat (анализ тикетов, отложенные ответы) применят изменения после следующего перезапуска панели.

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

Симптом	Причина	Решение
base_url must be an http(s) URL	Пропущена схема или присутствуют пробелы	Используйте https://host/v1.
api_key is required to enable the provider	Ключ не сохранен	Введите ключ и сохраните.
base_url and model are required to enable the provider	Пустое поле	Заполните оба поля.
"Базовый URL заблокирован: только публичные http(s), порты 80/443/8080/8443"	Тестирование несохраненного внутреннего адреса или другого порта	Сначала сохраните провайдера, затем выполните проверку.
api_key is required (enter the key again when you change the endpoint)	Base URL отличается от сохраненного	Введите ключ повторно.
model: letters, digits and - _ . / : @	Недопустимый символ	Укажите точный идентификатор модели провайдера.
fallback_models: up to 4 model names	Слишком много	Оставьте не более четырех.
Тест завершается с ошибкой 401	Неверный ключ	Проверьте ключ и эндпоинт.
Тест завершается с ошибкой 404 или "model not found"	Неверный путь или модель	Проверьте base URL (/v1) и идентификатор модели.
Too many tests — wait a minute (429)	Более 10 проверок в минуту	Подождите.
В портале по-прежнему не отображается меню AI	Модуль отключен или провайдер не отмечен как "in use"	Включите модуль и активируйте провайдера.