Як оновлювати базу знань ШІ, коли змінюються документи в Notion, Confluence і Google Docs

Коротка відповідь: підключити конектор недостатньо. Щоб асистент відповідав за актуальними документами, потрібен конвеєр оновлення з трьох частин: реакція на події змін, регулярна звірка індексу з джерелом і контроль прав доступу в момент відповіді. Події дають швидкість, але не гарантують, що жодна зміна не загубиться. Звірка ловить пропущене. Перевірка прав не дає асистенту цитувати документ, до якого людина вже не має доступу.

Головна умова: видалений документ або відкликаний доступ мають перестати впливати на відповіді так само надійно, як оновлений текст починає впливати. Після статті ви зможете описати цикл «документ змінено, індекс оновлено, відповідь перевірено» для своїх джерел, визначити допустиму затримку і скласти список перевірок після збою.

Що вважати актуальністю

Перед вибором технології варто домовитися, що саме означає «актуальна база знань». Без цього неможливо зрозуміти, чи працює синхронізація, і неможливо налаштувати тривоги.

Для кожного документа в індексі корисно зберігати щонайменше чотири значення:

• Ідентифікатор у джерелі. Сторінка Notion, сторінка Confluence чи файл Google Drive мають власний стабільний ID. Саме за ним, а не за назвою, треба знаходити старі фрагменти для заміни.
• Версію або час зміни в джерелі. Це дозволяє зрозуміти, чи індекс уже містить останню редакцію.
• Час останньої успішної індексації. Не час спроби, а час, коли нові фрагменти реально замінили старі.
• Права доступу, з якими документ потрапив в індекс. Хто міг його читати на момент індексації і як ця інформація оновлюється.

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

Корисно розділити документи на кілька класів за критичністю і для кожного записати допустиму затримку оновлення та окремо допустиму затримку видалення. Це стане основою для вибору між подіями, звіркою чи їх поєднанням.

Події чи періодична звірка

Є два базові способи дізнатися про зміни.

Події (webhooks). Платформа сама надсилає повідомлення на вашу адресу, коли щось змінилося. Notion має webhooks для змін сторінок, баз даних і коментарів. Для Confluence на платформі Forge задокументовано події створення, оновлення, переміщення в кошик, відновлення, видалення сторінки та зміни її дозволів. У Google Drive можна підписатися на сповіщення про зміни, але сповіщення лише сигналізує, що зміни є, а подробиці треба забрати зі стрічки змін.

У подій є важливі обмеження, які варто знати заздалегідь:

• Подія часто не містить змісту. Наприклад, у Notion подія повідомляє ідентифікатор сторінки й тип зміни, а актуальний текст інтеграція має отримати окремим запитом до API.
• Частина подій агрегується. Часті правки однієї сторінки Notion можуть прийти одним повідомленням із невеликою затримкою, зазвичай до хвилини. Під час тестування не варто очікувати миттєвої реакції на кожен символ.
• Доставка не гарантується абсолютно. Notion прямо описує доставку як «щонайбільше один раз» з повторними спробами, якщо ваш сервер не підтвердив отримання. Якщо сервер лежав довше, ніж тривають повтори, подію можна втратити.
• Не все генерує подію. У Notion немає окремої події про зміну прав доступу до сторінки. Під час видалення цілого простору Confluence не надсилає окремих подій видалення для його дочірніх сторінок. Подія також не прийде, якщо інтеграція не має доступу до об'єкта.

Періодична звірка. Інтеграція за розкладом сама питає джерело, що змінилося. Google Drive має для цього стрічку змін із токеном продовження: ви зберігаєте токен після кожного проходу, а наступного разу отримуєте лише зміни після нього. Для джерел без такої стрічки звірка може порівнювати список документів і їхні дати зміни з тим, що зберігається в індексі.

Звірка повільніша за події, але вона ловить те, що події пропустили. Тому для робочої системи ми рекомендуємо не вибирати одне, а поєднувати: події забезпечують швидке оновлення, а регулярна звірка закриває пропуски, видалення без подій і зміни прав.

Ідемпотентне оновлення

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

Що потрібно для ідемпотентного оновлення:

1. Ключ документа. Усі фрагменти в індексі мають посилання на ID документа в джерелі. Тоді оновлення виглядає як «видалити всі фрагменти документа X і записати нові», а не «додати нові фрагменти».
2. Перевірка версії. Перед заміною система порівнює версію або час зміни з тим, що вже є в індексі. Якщо в індексі новіша або та сама версія, повторна подія нічого не змінює.
3. Атомарна заміна. Старі фрагменти не видаляються, доки нові не записані. Інакше в проміжку асистент може не знайти нічого або знайти половину документа.
4. Журнал результату. Для кожної обробки записується: який документ, яка версія, скільки фрагментів, успіх чи помилка, час.

Типова помилка без ідемпотентності: після кожної повторної події в індексі з'являється ще одна копія тих самих фрагментів. Пошук починає повертати дублікати, витісняючи інші корисні фрагменти, а після кількох редакцій старі версії тексту продовжують знаходитися поруч із новими.

Видалення і права доступу

Видалення і відкликання доступу найчастіше ламають бази знань. Новий документ помітний: його хтось шукає і скаржиться, якщо не знаходить. Видалений документ, який продовжує впливати на відповіді, помічають пізно, зазвичай коли асистент цитує скасоване правило.

Видалення. Коли документ видалено, переміщено в кошик або архів, його фрагменти треба прибрати з індексу або позначити як недоступні для пошуку. Варто перевірити й похідні місця: кеш відповідей, збережені посилання в історії діалогів, окремі копії для інших мов. Якщо джерело не надсилає подію про видалення (наприклад, для дочірніх сторінок під час видалення цілого простору Confluence), його має виявити регулярна звірка: документ є в індексі, але його немає в джерелі або до нього немає доступу.

Права доступу. Тут є два рівні.

Перший рівень: права самої інтеграції. Якщо інтеграцію відключили від простору чи сторінки, вона перестає отримувати події й не може прочитати документ. Індекс при цьому не очищується сам. Звірка має помітити, що документ став недоступним, і прибрати його фрагменти.

Другий рівень: права людини, яка питає. Інтеграція може мати доступ до всього простору, а конкретний співробітник лише до частини. Тому під час відповіді система повинна фільтрувати знайдені фрагменти за правами користувача. Надійніше, коли ця перевірка виконується на рівні пошуку або окремого сервісу прав, а не довіряється моделі через інструкцію «не показуй закрите». Модель не повинна взагалі отримувати фрагмент, який людина не має права бачити.

Оскільки не всі платформи повідомляють про зміну прав подією, права в індексі треба оновлювати і під час звірки. Для найчутливіших документів має сенс перевіряти доступ безпосередньо в джерелі перед видачею відповіді, якщо це дозволяють квоти API.

Помилки і відновлення

Синхронізація ламається не лише через пропущені події. Типові причини: ліміти запитів API, тимчасова недоступність джерела, протермінований токен авторизації, документ надто великий для обробки, помилка в коді розбиття тексту. Важливо, щоб кожна з них була видимою і мала шлях відновлення.

Мінімальний набір механізмів:

• Черга з повторами. Подія спершу записується в чергу, а обробник забирає її звідти. Якщо обробка впала, подія повертається в чергу з паузою, що поступово збільшується. Після кількох невдалих спроб вона потрапляє в окремий список проблемних, і про це дізнається відповідальна людина.
• Повага до квот. Масова звірка може вичерпати ліміт запитів і заблокувати обробку подій. Звірку варто планувати з обмеженням швидкості й пріоритетом для подій.
• Збереження курсорів. Для стрічки змін Google Drive токен продовження зберігається лише після успішної обробки сторінки змін. Якщо зберегти його раніше і впасти, зміни між токенами будуть пропущені.
• Журнал і тривоги. Окремо відстежується час останнього успішного оновлення для кожного джерела, кількість подій у черзі, кількість проблемних подій і розбіжності, знайдені звіркою. Тривога спрацьовує не на кожну помилку, а коли порушено допустиму затримку з першого розділу.
• Повна переіндексація як запасний план. Має бути спосіб перебудувати індекс одного простору або всього джерела з нуля. Це довго, але це єдиний гарантований вихід, якщо курсор втрачено або логіка оновлення мала помилку.

Після будь-якого збою корисно відповісти на три питання. Які документи змінилися за час збою? Чи всі вони вже оброблені? Чи були серед них видалення або зміни прав?

Перевірка після зміни

Технічний журнал показує, що оновлення відбулося. Але бізнесу важливо інше: чи асистент відповідає за новою версією і чи не розкриває закритого. Це перевіряється контрольними запитаннями.

Нижче навчальний приклад циклу. Час у ньому умовний і не є гарантованим часом реакції будь-якої платформи.

Навчальний сценарій оновлення регламенту

З цього прикладу випливає набір контрольних запитань для кожного критичного документа:

• Запитання на новий зміст. Відповідь має відображати поточну версію, а не попередню.
• Запитання на видалений зміст. Після видалення документа асистент не повинен його цитувати і має чесно сказати, що актуальної інформації не знайдено.
• Запитання від користувача без доступу. Відповідь не повинна містити закритої інформації ні напряму, ні переказом.
• Повтор події. Після повторної обробки кількість фрагментів документа не змінюється.

Висновок

Актуальна база знань тримається не на конекторі, а на процесі: події для швидкості, звірка для повноти, ідемпотентна заміна для коректності і перевірка прав у момент відповіді для безпеки. Найслабші місця зазвичай не в оновленні тексту, а у видаленнях і відкликанні доступу, бо про них платформи повідомляють менш надійно.

Що можна зробити на своєму процесі:

1. Складіть перелік джерел і класів документів. Для кожного класу запишіть допустиму затримку оновлення і окремо затримку видалення або відкликання доступу.
2. Перевірте, які події реально надає кожна платформа для ваших сценаріїв, зокрема для видалень і зміни прав. Те, що не покривається подіями, має покривати звірка.
3. Переконайтеся, що кожен фрагмент в індексі має ID документа і версію, а оновлення замінює фрагменти атомарно.
4. Налаштуйте журнал із часом останнього успішного оновлення для кожного джерела і тривогу на перевищення допустимої затримки.
5. Для критичних документів підготуйте контрольні запитання: новий зміст, видалений зміст, запит без доступу, повтор події. Проганяйте їх після кожної зміни логіки і після збоїв.
6. Перевірте, що є процедура повної переіндексації і хто має право її запускати.

Якщо ваш асистент працює з документами, що постійно змінюються, команда BotLabs може розібрати це з вами на 15-хвилинній консультації. Обговоримо, які джерела і класи документів у вас є, яка затримка оновлення допустима і з яких контрольних запитань почати перевірку актуальності. Наступним кроком визначимо, що варто перевірити у вашій поточній схемі синхронізації.

Часті запитання