Інтеграція ШІ

Налаштування ШІ-чату, підказок щодо помилок LaTeX, доступу користувачів, квот і додаткових служб пошуку.

Цю функцію надає ayaka-notes/ayakaleaf-pro, і вона доступна починаючи з v6.3.0. Будемо раді вашим відгукам, якщо виникнуть проблеми.

​

ШІ-помічник і помічник з помилок LaTeX

Ayakaleaf Pro додає функції ШІ до редактора двома способами.

• ШІ-помічник (AI Assistant) може використовувати документи вашого проєкту та поточне виділення як контекст, щоб відповідати на запитання й пропонувати правки, які ви можете переглянути.
• Помічник з помилок (Error Assistant) пропонує цільове виправлення, коли ви вибираєте помилку компіляції 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). Обидві функції надсилають контекст документа на цей шлюз; чат також може надсилати завантажені зображення, якщо використовується модель із підтримкою зображень.

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_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.

Наприклад, щоб увімкнути модель для зображень і щотижневий ліміт ШІ:

AI_IMAGE_MODEL=YOUR_IMAGE_CAPABLE_MODEL_ID
AI_TOKEN_QUOTA=100000
AI_TOKEN_QUOTA_PERIOD=week

​

Доступ користувачів і згода

Доступність для екземпляра та дозволи користувача — окремі речі. AI_ENABLED і конфігурація шлюзу визначають доступність для екземпляра. Користувач, який увійшов у систему, також має пройти наявні перевірки облікового запису:

• aiFeatures.enabled не повинно дорівнювати false. Це наявне поле бази даних керує як чатом, так і підказками щодо помилок LaTeX.
• Ефективне значення features.aiUsageQuota користувача має відповідати налаштованому необмеженому рівню (за замовчуванням unlimited), або має бути ввімкнено наявний застарілий дозвіл features.aiErrorAssistant. Ефективні функції враховують застосовні перевизначення функцій облікового запису.

Саме лише ввімкнення прапорця не змінює план користувача. Поле aiUsageQuota — це рівень дозволів, а не числовий ліміт токенів. 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 зберігає поточне використання після перезапуску застосунку.

​

Додаткові служби пошуку

Вебпошук використовує Tavily-сумісний API. Він доступний, якщо налаштовано ключ 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-клієнт для пошуку в документації; ці модулі не надають файли проєктів як MCP-сервер і не надають загального реєстру MCP-серверів.

Пошукові запити надсилаються до налаштованої служби пошуку. Потім результати пошуку можуть бути включені в запити до ШІ-шлюзу. Меню Tools у чаті дає змогу користувачам вмикати або вимикати Web і Documentation для своїх запитів; щоб інструмент був доступний моделі, його також має бути налаштовано на сервері.