.. _settings-ai:

AI-агенты
=========

Настройка AI-агентов осуществляется в общем окне настроек программы (кнопка :guilabel:`Настройки` со значком шестеренки в верхнем правом углу). В списке групп, расположенном в левой части интерфейса, выберите группу **AI-агенты**.

В данном разделе настроек находятся две вкладки:

* **AI-ассистент** — выбор активного AI-агента;
* **OpenAI-совместимый ассистент** — управление профилями OpenAI-совместимых агентов.

.. figure:: image/settings_ai_openai.png
   :align: center

   Рисунок 1. Вкладка «OpenAI-совместимый ассистент»

.. _settings-ai-assistant:

AI-ассистент
------------

На этой вкладке выбирается активный AI-агент, который будет использоваться в программе.

В выпадающем списке **Агент** отображаются все AI-агенты, зарегистрированные в системе, а не только профили, созданные на вкладке **OpenAI-совместимый ассистент**. Сюда также попадают агенты, добавленные установленными расширениями (плагинами). Таким образом, список активных агентов всегда содержит полный перечень доступных в текущей конфигурации программы агентов.

Выберите нужного агента из списка и нажмите :guilabel:`Применить` или :guilabel:`ОК` для сохранения настроек. Если нужного агента в списке нет, перейдите на вкладку **OpenAI-совместимый ассистент** и создайте соответствующий профиль.

.. figure:: image/settings_ai_assistant.png
   :align: center

   Рисунок 2. Выбор активного AI-агента

.. _settings-openai:

OpenAI-совместимый ассистент
----------------------------

Эта вкладка предназначена для управления профилями подключения к OpenAI-совместимым сервисам. Можно создать несколько профилей для разных провайдеров или моделей — все они появятся в списке активных агентов на вкладке **AI-ассистент**.

OpenAI-совместимые агенты работают по открытому протоколу OpenAI API. Это означает, что в качестве провайдера можно использовать не только OpenAI, но и любой сервис, поддерживающий данный протокол. Подробное описание получения ключа доступа и списка доступных моделей для одного из таких провайдеров приведено в документации Cloud.ru: https://cloud.ru/docs/foundation-models/ug/topics/quickstart

Интерфейс раздела разделен на две части: слева расположен список созданных профилей, справа — форма настроек выбранного профиля.

Настройка профиля
~~~~~~~~~~~~~~~~~

Для добавления нового профиля нажмите кнопку :guilabel:`Добавить` под списком профилей. В открывшемся диалоговом окне введите имя нового профиля (например, ``OpenAI GigaChat``).

Чтобы удалить профиль, выделите его в списке и нажмите :guilabel:`Удалить`. Для изменения имени профиля используйте кнопку :guilabel:`Переименовать`.

В правой части окна задаются параметры подключения и ограничения для выбранного профиля:

**Группа «Подключение»**

* **Адрес API** — URL-адрес точки доступа к API провайдера;
* **Ключ доступа** — секретный токен (API-ключ) для авторизации. Ключ хранится в настройках в зашифрованном виде;
* **Модель** — идентификатор модели, которую будет использовать агент (например, ``openai/gpt-oss-120b``).

**Группа «Ограничения»**

* **Максимум токенов** — максимальное количество токенов в ответе модели;
* **Таймаут** — время ожидания ответа от сервера в секундах.

Дополнительные настройки
~~~~~~~~~~~~~~~~~~~~~~~~

Для доступа к расширенным параметрам генерации и работы нейросетей установите флажок **Показать дополнительные настройки**.

.. figure:: image/settings_ai_openai_advanced.png
   :align: center

   Рисунок 3. Дополнительные настройки AI-агента

В группе **Дополнительные настройки** доступны следующие параметры.

**Группа «Генерация»**

* **Температура** — управляет случайностью ответов. Чем выше значение, тем более творческим и непредсказуемым будет ответ;
* **Top P** — альтернативный метод управления случайностью (ядерная выборка);
* **Штраф за частоту** — снижает вероятность повторения одних и тех же фраз в ответе;
* **Штраф за присутствие** — стимулирует модель говорить о новых темах;
* **Зерно (Seed)** — если задано, модель будет стараться выдавать детерминированные (повторяемые) ответы при одинаковых запросах.

**Группа «Размышления»**

Данные настройки актуальны для моделей, поддерживающих режим рассуждений (reasoning models).

* **Управлять размышлениями** — позволяет явно указать, нужно ли модели «думать» перед ответом;
* **Отключить размышления** — принудительно отключает режим рассуждений для экономии токенов и ускорения ответа;
* **Лимит токенов на размышления** — задает максимальный объем токенов, который модель может потратить на скрытые рассуждения.

.. note::
   В текущей версии программы скрытые размышления модели не выводятся в интерфейсе, даже если они включены в настройках профиля. Параметры группы «Размышления» влияют только на работу модели и расход токенов.

.. note::
   Не все модели и провайдеры поддерживают экспериментальные параметры генерации. Если при запросе возникает ошибка с кодом 400 (Bad Request), попробуйте снять соответствующие флажки в дополнительных настройках.

.. warning::
   При использовании моделей с размышлениями с малым лимитом токенов весь лимит может уйти на скрытые рассуждения, и в ответе будет получен «Пустой ответ». В этом случае рекомендуется увеличить параметр **Максимум токенов** (до 16000–32000) или принудительно отключить размышления.