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

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

Эта функция предоставляется ayaka-notes/ayakaleaf-pro и доступна начиная с v6.3.0. Если у вас возникнут проблемы, будем рады вашим отзывам.

​

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

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

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

​

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

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

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-ключи в файле окружения развёртывания и не добавляйте их в систему контроля версий. Значения выше — это заполнители, а не рабочие учётные данные.

Качество ИИ-подсказок зависит от выбранной модели. Если у вас уже есть подписка Codex или ChatGPT, её можно подключить через OpenAI-совместимый эндпоинт CLIProxyAPI.

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

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

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.

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

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 (сброс). Данные об использовании считываются при открытии вкладки и не обновляются непрерывно. Чтобы увидеть актуальное значение, откройте вкладку заново после завершения запроса чата или подсказки по ошибке. Сброс вступает в силу немедленно и очищает только счётчик текущего периода для этого пользователя, после чего отображаемое использование перезагружается. Сохранять остальную форму учётной записи не требуется.

Использование чата и подсказок по ошибкам учитывается в одном общем счётчике 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	Эндпоинт поиска по документации. Задайте пустую строку, чтобы отключить поиск по документации.

Например:

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-сервер.

Чтение веб-страниц появилось в v6.4.0 и более поздних версиях. Чат может прочитать страницу по её URL, например по ссылке, которую дал пользователь, или по результату поиска. Он загружает страницу через прокси связанных URL — тот же сервис, который загружает файлы по внешним URL, поэтому на него распространяются сетевые ограничения, описанные в разделе External URL. Дополнительная настройка не требуется.

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

​

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

ИИ-ассистент не отображается в редакторе

Ответ: ИИ-ассистент отображается на левой панели редактора, только если задано AI_ENABLED=true и заданы все переменные AI_BASE_URL, AI_API_KEY и AI_MODEL. Если какая-либо из них отсутствует, ИИ-ассистент скрыт для всех пользователей.

После изменения config/variables.env пересоздайте контейнер командой bin/up -d. Простое обновление страницы в браузере не применяет новые переменные. Переключатель Enable AI features в панели администратора не показывает и не скрывает ИИ-ассистента; он лишь определяет, может ли пользователь отправлять сообщения.

Я отправляю сообщение, но ИИ-ассистент не отвечает

Ответ: Сначала убедитесь, что пользователь принял карточку согласия на использование ИИ, показанную в ИИ-ассистенте. До этого сообщения отправлять нельзя.

Затем поищите ошибки в журнале сервиса web:

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 и инструменты-функции.

Сохраняется ли история чата?

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