> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Интеграция с ИИ

> Настройка ИИ-чата, подсказок по ошибкам LaTeX, доступа пользователей, квот и дополнительных сервисов поиска.

> [!NOTE]
>
> Эта функция предоставляется [ayaka-notes/ayakaleaf-pro](https://github.com/ayaka-notes/ayakaleaf-pro) и доступна начиная с v6.3.0. Если у вас возникнут проблемы, будем рады вашим отзывам.

## ИИ-ассистент и ассистент по ошибкам LaTeX

Ayakaleaf Pro добавляет функции ИИ в редактор двумя способами.

* ИИ-ассистент может использовать документы проекта и текущее выделение в качестве контекста, чтобы отвечать на вопросы и предлагать правки для вашей проверки.
* Ассистент по ошибкам предлагает точечное исправление, когда вы выбираете ошибку компиляции LaTeX.

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-49.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=609d6a28104dfb16264790c00123eeb4)

### Конфигурация Toolkit

Добавьте следующее в `config/variables.env` в вашем развёртывании Toolkit, заменив пример URL, ключа и модели значениями от вашего провайдера:

```dotenv theme={null}
AI_ENABLED=true
AI_BASE_URL=https://ai-gateway.example.com/v1
AI_API_KEY=REPLACE_WITH_YOUR_GATEWAY_API_KEY
AI_MODEL=YOUR_TEXT_MODEL_ID
```

Храните настоящие API-ключи в файле окружения развёртывания и не добавляйте их в систему контроля версий. Значения выше — это заполнители, а не рабочие учётные данные.

> [!NOTE]
>
> Качество ИИ-подсказок зависит от выбранной модели. Если у вас уже есть подписка Codex или ChatGPT, её можно подключить через OpenAI-совместимый эндпоинт [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI).

`AI_BASE_URL` — это базовый URL OpenAI-совместимого API, включая префикс версии провайдера, если он требуется. Не добавляйте `/chat/completions`, так как он добавляется внутренне. Шлюз и модель должны поддерживать потоковые chat completions и инструменты-функции (function tools). Обе функции отправляют в этот шлюз контекст документа; чат также может отправлять загруженные изображения и PDF-файлы при использовании модели, которая их принимает.

Toolkit передаёт `config/variables.env` в контейнер приложения. Используйте указанные здесь имена переменных и не добавляйте префикс `OVERLEAF_`. После изменения этих переменных пересоздайте контейнер приложения из каталога Toolkit:

```sh theme={null}
bin/up -d
```

### Настройки шлюза

| Переменная | По умолчанию | Назначение |
| - | - | - |
| `AI_ENABLED` | `false` | Установите ровно `true`, чтобы включить чат и подсказки по ошибкам для экземпляра. Если переменная не задана или имеет любое другое значение, функции остаются отключёнными. Также требуется рабочая конфигурация шлюза. |
| `AI_BASE_URL` | Нет; обязательно | Базовый URL OpenAI-совместимого API. |
| `AI_API_KEY` | Нет; обязательно | API-ключ для этого шлюза, используемый сервером. |
| `AI_MODEL` | Нет; обязательно | Текстовая модель, используемая конфигурацией чата по умолчанию и подсказками по ошибкам LaTeX. |
| `AI_IMAGE_MODEL` | Не задано | Необязательная модель с поддержкой изображений на том же шлюзе, использующая тот же API-ключ. |
| `AI_PDF_MODEL` | Не задано | Необязательная модель на том же шлюзе для чатов с PDF-файлами, использующая тот же API-ключ. Начиная с v6.4.0. |
| `AI_MAX_STEPS` | `20` | Максимальное число вызовов инструментов на одно сообщение пользователя в ИИ-чате, включая автоматические продолжения. Используйте положительное целое число. |
| `AI_PROXY_URL` | Не задано | Необязательный URL HTTP-прокси для обращений к ИИ-шлюзу. Не влияет на клиенты веб-поиска и поиска по документации. |
| `AI_TOKEN_QUOTA` | `0` | Лимит токенов на пользователя за период, общий для чата и подсказок по ошибкам. Если не задано или `0` — без ограничений; для установки лимита используйте положительное целое число. |
| `AI_TOKEN_QUOTA_PERIOD` | `month` | `month` сбрасывается в первый день месяца в 00:00 UTC; `week` — в понедельник в 00:00 UTC. Другие значения трактуются как `month`. |

Для загрузки изображений задайте в `AI_IMAGE_MODEL` модель, которая принимает изображения на вход и поддерживает инструменты, используемые чатом. Любой запрос чата, история которого содержит вложенное изображение, использует эту модель, включая последующие сообщения в этом диалоге. Без этой настройки запросы с изображениями используют обычную модель чата, которая сама должна поддерживать изображения. Подсказки по ошибкам LaTeX по-прежнему используют `AI_MODEL`.

Вложения PDF появились в v6.4.0 и более поздних версиях. Пользователи могут прикреплять PDF-файлы размером до 2 МБ, как и изображения. Чат отправляет каждый PDF-файл как есть, в виде части `file` Chat Completions, поэтому шлюз и модель должны принимать PDF на вход: модели OpenAI с поддержкой зрения это умеют, тогда как многие самостоятельно размещаемые шлюзы, например vLLM, принимают изображения, но отклоняют PDF-файлы. Задайте в `AI_PDF_MODEL` модель, которая читает PDF-файлы; любой чат, история которого содержит PDF-файл, использует её, включая последующие сообщения и любые изображения в этом диалоге, поэтому она также должна принимать изображения. Без этой настройки чаты с PDF используют `AI_MODEL`. Если модель отклоняет PDF-файл, чат предлагает пользователю попросить администратора задать `AI_PDF_MODEL`.

Например, чтобы включить модель для изображений и еженедельную квоту ИИ:

```dotenv theme={null}
AI_IMAGE_MODEL=YOUR_IMAGE_CAPABLE_MODEL_ID
AI_TOKEN_QUOTA=100000
AI_TOKEN_QUOTA_PERIOD=week
```

### Доступ пользователей и согласие

Доступность для экземпляра и разрешения пользователей — это разные вещи. `AI_ENABLED` и конфигурация шлюза управляют доступностью для экземпляра. Вошедший пользователь также должен пройти существующую проверку учётной записи: `aiFeatures.enabled` не должно быть равно `false`. Это существующее поле базы данных управляет как чатом, так и подсказками по ошибкам LaTeX. Если оно не задано, функции ИИ для пользователя включены.

`AI_TOKEN_QUOTA` — лимит, одинаково применяемый к каждому пользователю с разрешением; текущий модуль не позволяет задать индивидуальный числовой лимит для отдельной учётной записи.

В списке пользователей панели администратора выберите пользователя и откройте **Update account info → AI features**. **Enable AI features** обновляет `aiFeatures.enabled` при сохранении изменений учётной записи. Сервер проверяет текущие разрешения при новых запросах к ИИ, включая запросы из уже открытого редактора. Пользователь без разрешения по-прежнему видит ИИ-ассистента в редакторе, но не может отправлять сообщения.

### Использование и сброс

Вкладка AI features в панели администратора показывает в одной строке **Usage** (использование) за текущий период, **Limit** (лимит) и кнопку **Reset** (сброс). Данные об использовании считываются при открытии вкладки и не обновляются непрерывно. Чтобы увидеть актуальное значение, откройте вкладку заново после завершения запроса чата или подсказки по ошибке. Сброс вступает в силу немедленно и очищает только счётчик текущего периода для этого пользователя, после чего отображаемое использование перезагружается. Сохранять остальную форму учётной записи не требуется.

![](https://mintcdn.com/ayakaleaf-pro/x9kfDjtWlyyhG_mR/images/on-premises/img-2f5a5399.png?fit=max\&auto=format\&n=x9kfDjtWlyyhG_mR\&q=85\&s=3c52c12aa1551cda22f218ec2dfda63b)

Использование чата и подсказок по ошибкам учитывается в одном общем счётчике Redis, который обновляется по общему числу токенов, сообщаемому провайдером модели после завершения запроса. Сюда входят входные и выходные токены на всех шагах модели. Входные данные могут включать историю диалога, контекст документа и результаты инструментов, поэтому последующий запрос может израсходовать больше токенов, чем одно новое сообщение. Использование учитывается, даже если лимит — **Unlimited**. Запросы без сообщённого общего числа токенов не увеличивают счётчик; восстановить ранее не учтённое использование модуль не может.

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

Обе функции используют `AI_TOKEN_QUOTA`; отдельного лимита на количество запросов для подсказок по ошибкам нет. Сброс счётчика не меняет разрешения, согласие, настроенный лимит или собственные записи о расходах у провайдера. Счётчики используют ключи периодов в UTC и истекают через 40 дней; сохранение данных Redis позволяет сохранить текущее использование при перезапусках приложения.

### Дополнительные сервисы поиска

Веб-поиск использует API, совместимый с Tavily. Он доступен, если настроен API-ключ поиска. Эти настройки не зависят от ИИ-шлюза:

| Переменная | По умолчанию | Назначение |
| - | - | - |
| `TAVILY_API_KEY` | Не задано | API-ключ поиска. Имеет приоритет над `WEB_SEARCH_API_KEY`. |
| `WEB_SEARCH_API_KEY` | Не задано | Альтернативное имя для API-ключа поиска. |
| `WEB_SEARCH_URL` | `https://api.tavily.com/search` | Эндпоинт поиска; пользовательские эндпоинты должны принимать формат запросов и ответов Tavily. |
| `WEB_SEARCH_MAX_RESULTS` | `5` | Количество результатов, запрашиваемых при поиске; используйте положительное целое число, поддерживаемое сервисом. |
| `WEB_SEARCH_DEPTH` | `basic` | Глубина поиска, обычно `basic` или `advanced`. |
| `WEB_SEARCH_PROVIDER` | `tavily` | Текущая реализация поддерживает только протокол, совместимый с Tavily; изменение этого значения не выбирает другой адаптер. |
| `DOCS_MCP_URL` | `https://docs.overleaf.com/~gitbook/mcp` | Эндпоинт поиска по документации. Задайте пустую строку, чтобы отключить поиск по документации. |

Например:

```dotenv theme={null}
TAVILY_API_KEY=REPLACE_WITH_YOUR_SEARCH_API_KEY
WEB_SEARCH_MAX_RESULTS=5
WEB_SEARCH_DEPTH=basic
DOCS_MCP_URL=https://docs.overleaf.com/~gitbook/mcp
```

Поиск по документации вызывает инструмент `searchDocumentation` настроенного эндпоинта GitBook MCP и принимает ответы в формате JSON или SSE. Это MCP-клиент для поиска по документации. Чтобы ИИ-клиенты за пределами Ayakaleaf могли работать с проектом, см. [MCP-сервер](https://ayakaleaf-pro.mintlify.site/ru/on-premises/configuration/overleaf-toolkit/integrations/mcp-server.md).

Чтение веб-страниц появилось в v6.4.0 и более поздних версиях. Чат может прочитать страницу по её URL, например по ссылке, которую дал пользователь, или по результату поиска. Он загружает страницу через прокси связанных URL — тот же сервис, который загружает файлы по внешним URL, поэтому на него распространяются сетевые ограничения, описанные в разделе [External URL](https://ayakaleaf-pro.mintlify.site/ru/on-premises/configuration/overleaf-toolkit/external-url.md). Дополнительная настройка не требуется.

Поисковые запросы отправляются в настроенный сервис поиска. Затем результаты поиска могут включаться в запросы к ИИ-шлюзу. Меню **Tools** в чате позволяет пользователям включать или отключать **Web** и **Documentation** для своих запросов; кроме того, чтобы инструмент был доступен модели, он должен быть настроен на сервере.

### Вопросы и ответы

> [accordion] ИИ-ассистент не отображается в редакторе
>
> **Ответ:** ИИ-ассистент отображается на левой панели редактора, только если задано `AI_ENABLED=true` и заданы все переменные `AI_BASE_URL`, `AI_API_KEY` и `AI_MODEL`. Если какая-либо из них отсутствует, ИИ-ассистент скрыт для всех пользователей.
>
> После изменения `config/variables.env` пересоздайте контейнер командой `bin/up -d`. Простое обновление страницы в браузере не применяет новые переменные. Переключатель **Enable AI features** в панели администратора не показывает и не скрывает ИИ-ассистента; он лишь определяет, может ли пользователь отправлять сообщения.

> [accordion] Я отправляю сообщение, но ИИ-ассистент не отвечает
>
> **Ответ:** Сначала убедитесь, что пользователь принял карточку согласия на использование ИИ, показанную в ИИ-ассистенте. До этого сообщения отправлять нельзя.
>
> Затем поищите ошибки в журнале сервиса web:
>
> ```sh theme={null}
> bin/logs web
> ```
>
> | Сообщение в журнале | Значение |
> | - | - |
> | `workbench AI chat requested but no AI gateway is configured` | В запущенном контейнере отсутствует одна из переменных `AI_ENABLED`, `AI_BASE_URL`, `AI_API_KEY` или `AI_MODEL`. Пересоздайте его командой `bin/up -d`. |
> | `workbench chat stream error` | Шлюз вернул ошибку. Пользователь видит «The AI service returned an error». В записанной ошибке указаны код состояния и сообщение шлюза. |
> | `workbench chat failed` | Запрос завершился ошибкой до или во время потоковой передачи, например потому что шлюз недоступен. |
>
> Если панель вашего провайдера не показывает использования, запрос не дошёл до провайдера. Частые причины:
>
> * Неверно задан `AI_BASE_URL`, например отсутствует или лишний `/v1` либо к нему добавлен `/chat/completions`.
> * Сервер не может связаться со шлюзом. Если исходящий трафик должен идти через прокси, задайте `AI_PROXY_URL`.
> * `AI_MODEL` не является идентификатором модели, известным шлюзу.
>
> Если провайдер показывает запросы, но чат всё равно не работает, убедитесь, что модель поддерживает потоковые chat completions и инструменты-функции.

> [accordion] Сохраняется ли история чата?
>
> **Ответ:** Нет. Чат хранится только в открытой вкладке браузера. Обновление или закрытие страницы очищает его, а **Start new chat** заменяет текущий чат. Списка прежних чатов нет, и в каждом проекте одновременно отображается один чат.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.