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

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

​

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

Вебпошук використовує 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-клієнт для пошуку в документації. Щоб дозволити ШІ-клієнтам поза 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 в адмін-панелі не показує й не приховує ШІ-помічника; він лише визначає, чи може користувач надсилати повідомлення.

Я надсилаю повідомлення, але ШІ-помічник не відповідає

Відповідь: Спершу переконайтеся, що користувач прийняв картку згоди на використання ШІ, яку показує ШІ-помічник. До цього повідомлення надсилати не можна.

Потім пошукайте помилки в журналі вебслужби:

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 замінює поточний чат. Списку попередніх чатів немає, і кожен проєкт показує один чат одночасно.