Індексація баз знань для RAG: синхронізація Confluence, Notion, SharePoint

Індексація баз знань для RAG: як ми вирішуємо проблему застарілих даних і прав доступу

Корпоративні бази знань — головне джерело контексту для enterprise RAG-систем. Retrieval-Augmented Generation (RAG) без актуального індексу втрачає сенс: на практиці ми стикалися з ситуацією, коли RAG видавав відповіді за застарілим контентом, тому що сторінки Confluence не переіндексовувалися тижнями. Або — що гірше — користувач отримував дані з документа, доступ до якого йому заборонено. Обидві проблеми вирішуються правильною архітектурою індексації баз знань Confluence, Notion та SharePoint.

Ми розробили інкрементальний пайплайн, який обробляє лише змінені сторінки та суворо дотримується прав доступу. За понад 50 проєктів ми напрацювали типові конектори та правила обробки розмітки. Інкрементальна синхронізація в 6 разів швидша за повну переіндексацію — це знижує витрати на інфраструктуру та прискорює оновлення відповідей RAG. Отримайте консультацію: ми покажемо демо на ваших даних.

Які проблеми вирішує індексація під ключ

• Інкрементальна синхронізація. Повна переіндексація Confluence з 5000 сторінок займає 30–40 хвилин і споживає 10 млн токенів. Інкрементальна — 2–5 хвилин. Без неї RAG-система швидко втрачає актуальність.
• Permission-aware пошук. Користувач не повинен бачити відповіді з документів, на які він не має прав. Ми зберігаємо mapping user→doc_ids і фільтруємо результати на стороні vector DB. Це знижує кількість нерелевантних відповідей на 30%.
• Обробка специфічної розмітки. Confluence використовує storage format (XHTML), Notion — блочну структуру, SharePoint — список елементів. Кожен формат вимагає окремого парсера, інакше втрачаються заголовки, код та посилання.

Чому інкрементальна синхронізація критична для RAG?

Повна індексація щогодини — дорого та повільно. Ми використовуємо watermark-підхід: зберігаємо timestamp останньої успішної синхронізації для кожного space/database. При наступному запуску завантажуємо лише сторінки з last_modified > watermark. Для Confluence — через Atlassian REST API з параметром expand=version,body.storage, для Notion — через фільтр по last_edited_time.

Приклад конектора для Confluence:

from atlassian import Confluence
from datetime import datetime

class ConfluenceIndexer:
    def __init__(self, url: str, username: str, api_token: str):
        self.confluence = Confluence(
            url=url,
            username=username,
            password=api_token,
            cloud=True  # True для Atlassian Cloud
        )
        self.watermark_store = WatermarkStore()

    def get_updated_pages(self, space_key: str) -> list[dict]:
        """Інкрементальне завантаження: тільки оновлені сторінки"""
        last_indexed = self.watermark_store.get(f"confluence:{space_key}")

        pages = self.confluence.get_all_pages_from_space(
            space=space_key,
            start=0,
            limit=100,
            expand='body.storage,metadata,version,ancestors'
        )

        if last_indexed:
            pages = [
                p for p in pages
                if datetime.fromisoformat(p['version']['when']) > last_indexed
            ]

        return pages

    def parse_page(self, page: dict) -> dict:
        from bs4 import BeautifulSoup
        from markdownify import markdownify

        # Confluence зберігає контент у storage format (XHTML)
        html_content = page['body']['storage']['value']
        soup = BeautifulSoup(html_content, 'html.parser')

        # Обробка Confluence-специфічних тегів
        for macro in soup.find_all('ac:structured-macro'):
            macro_name = macro.get('ac:name', '')
            if macro_name == 'code':
                # Code blocks → markdown code blocks
                body = macro.find('ac:plain-text-body')
                lang = macro.find('ac:parameter', {'ac:name': 'language'})
                code = body.get_text() if body else ''
                lang_str = lang.get_text() if lang else ''
                macro.replace_with(f'\n```{lang_str}\n{code}\n```\n')
            else:
                macro.decompose()

        text = markdownify(str(soup), heading_style="ATX")

        return {
            'id': page['id'],
            'title': page['title'],
            'text': text,
            'url': f"{self.confluence.url}/wiki{page['_links']['webui']}",
            'space': page['space']['key'],
            'ancestors': [a['title'] for a in page.get('ancestors', [])],
            'labels': [l['name'] for l in page.get('metadata', {}).get('labels', {}).get('results', [])],
            'last_modified': page['version']['when'],
            'author': page['version']['by']['displayName'],
            # Права доступу для permission-aware пошуку
            'restrictions': self._get_page_restrictions(page['id'])
        }

Аналогічний конектор для Notion використовується з фільтрацією по last_edited_time та рекурсивним вилученням блоків. Деталі можна знайти в документації Notion API.

Як налаштувати permission-aware пошук?

Для інтеграції з корпоративними IDP (Azure AD, Okta) ми проксіюємо ролі у векторну БД. Приклад реалізації:

class PermissionAwareRetriever:
    def search(self, query: str, user_id: str, top_k: int = 5) -> list:
        # Отримання дозволених document IDs для користувача
        allowed_docs = self.permission_store.get_allowed_docs(user_id)

        # Векторний пошук з фільтрацією за правами
        results = self.vector_store.similarity_search(
            query=query,
            filter={"doc_id": {"$in": allowed_docs}},
            k=top_k
        )
        return results

Інкрементальна синхронізація кожні 15–60 хвилин забезпечує актуальність RAG-системи без повної переіндексації гігабайтів контенту. Ми використовуємо watermark-підхід, який скорочує обсяг оброблюваних даних до 10–20% від повного дампу.

Що входить в роботу при індексації?

• Документація конекторів — опис кожного конектора, його налаштування та логіки обробки.
• Permission mapping — таблиця відповідності ролей IDP та груп векторної БД.
• Chunking-стратегія — вибір розміру чанка (token-based або semantic) з обґрунтуванням.
• MLOps-пайплайн — автоматичний запуск синхронізації з моніторингом через Weights & Biases.
• Навчання команди — дві години воркшопу з експлуатації індексу.

Які стратегії chunking вибрати?

Які моделі ембедінгів використовувати?

Типові помилки при індексації

• Пропуск макросів Confluence — macros «info», «warning» виглядають як блоки, але їхній вміст часто втрачається. Наш парсер зберігає їх як цитати.
• Ігнорування вкладень — PDF, DOCX у Confluence/SharePoint містять важливий контекст. Ми підключаємо OCR-пайплайн.
• Відсутність дедуплікації — однакові сторінки в різних space призводять до дублювання ембедінгів. Hash-фільтр вирішує проблему.

Економія на хмарних ресурсах може досягати 40% за рахунок зниження кількості токенів при інкрементальній обробці. Зв'яжіться з нами для демо — проіндексуємо один space за два дні. Замовте пілотний проєкт, щоб переконатися в ефективності.

Чому дата-інжиніринг визначає успіх ML-моделі

Минулого року до нас звернулася компанія, яка витратила $50 000 на навчання NLP-моделі, але отримала лише 60% точності на продакшені. Причина — data leakage через випадковий split часових даних. Перед тим як навчати модель, потрібно зрозуміти структуру даних: чи є дублі, як часто змінюється схема, наскільки репрезентативна вибірка. Дата-інжиніринг для ML — це не просто ETL, а побудова відтворюваної інфраструктури, яка робить навчання надійним, а перенавчання — передбачуваним. За досвідом нашої команди (понад 8 років у дата-інжинірингу, 30+ проектів у ML) кожна друга проблема в продакшені пов’язана не з архітектурою моделі, а з якістю даних. Замовте аудит ваших даних — оцінимо поточний пайплайн безкоштовно.

Як ETL-пайплайни для ML відрізняються від BI

ETL для аналітики та ETL для ML — різні завдання. В аналітиці важлива агрегація, у ML — індивідуальні записи з історією. В аналітиці train/val/test split не потрібен, у ML — критичний. В аналітиці skew даних заважає інтерпретації, у ML — безпосередньо впливає на якість моделі.

Інструменти. Apache Spark для великих обсягів (10GB+): PySpark з DataFrames, оптимізації через partitioning та caching. dbt для трансформацій поверх DWH (Snowflake, BigQuery, Redshift) — декларативно, версіонується, тестується. Pandas + Polars для обсягів до кількох GB — Polars у 5–10x швидше за Pandas на типових трансформаціях.

Temporal splits. Для ML важливо, що split за часом, а не випадковий. Якщо дані часові (транзакції, події користувачів), випадковий split дає data leakage: модель бачить «майбутні» дані при навчанні. Правило: train на періоді T1–T2, validation на T2–T3 (з gap для запобігання leakage), test на T3–T4. Неправильний split може коштувати 10–15% якості моделі на валідації. Temporal split best practices (scikit-learn docs)

Інкрементальні пайплайни. Модель перенавчається щотижня на нових даних. Потрібен пайплайн, який інкрементально додає нові записи до навчальної вибірки, не перевантажуючи все з нуля. Delta Lake або Apache Iceberg — формати з ACID-транзакціями, Change Data Capture, time travel.

Як уникнути training-serving skew за допомогою Feature Store

Feature Store вирішує проблему розсинхронізації між навчанням та інференсом. Найпідступніша помилка в ML-інфраструктурі — training-serving skew: ознака обчислюється по-різному в навчанні та в продакшені. Модель вчиться на «правильних» даних, а інференс отримує інші.

Feast (open source) — офлайн store на Parquet/Delta в S3 для навчання, онлайн store на Redis для low-latency інференсу (<10ms). Feature definitions як Python-код:

from feast import FeatureView, Field
from feast.types import Float32, Int64

user_features = FeatureView(
    name="user_features",
    entities=["user_id"],
    schema=[
        Field(name="purchase_count_7d", dtype=Int64),
        Field(name="avg_session_duration", dtype=Float32),
    ],
    ttl=timedelta(days=7),
    source=user_features_source,
)

Один definition використовується всюди — немає розбіжностей.

Потокові ознаки. Коли ознака має оновлюватися в реальному часі (кількість транзакцій за останні 10 хвилин), потрібна потокова обробка. Apache Kafka + Apache Flink або Kafka Streams для обчислення ознак у реальному часі → запис в онлайн store. Складніше, дорожче, потрібно лише коли staleness ознак критична для якості.

Розмітка даних: як не витратити бюджет даремно

Розмітка — найтрудомісткіша та недооцінювана частина ML-проекту. Погано розмічені дані не виправить жодна архітектура.

Label Studio — open source, підтримує розмітку зображень (bounding box, polygon, segmentation), тексту (NER, класифікація), аудіо, відео. Піднімається за 10 хвилин через Docker. Для невеликих команд — перший вибір.

Оцінка якості розмітки. Inter-annotator agreement — наскільки згодні розмітники між собою. Cohen's Kappa > 0.8 — добре, 0.6–0.8 — прийнятно, < 0.6 — завдання неоднозначне або інструкція погана. Перетин розміток (10–20% прикладів розмічають два незалежних анотатори) — обов'язкова практика.

Active learning. Не розмічати випадкові приклади, а вибирати ті, на яких модель найбільш невпевнена (low confidence, high uncertainty). Дозволяє досягти тієї ж якості при 50–70% обсягу розмітки. Modals, Prodigy, Label Studio підтримують active learning workflows. На одному з проектів для NLP ми скоротили бюджет на розмітку в 2,5 рази завдяки active learning — економія склала $15 000 на 100 000 розмічених прикладів.

Синтетичні дані. Коли реальних даних мало або отримати їх дорого. Для CV: рендеринг у Blender/Unity з реалістичними текстурами (domain randomization). Для NLP: parafrase через LLM, backtranslation. Ризик: модель навчається на distribution синтетичних даних, а не реальних — потрібна обережність і перевірка на реальному holdout.

Якість даних: валідація та моніторинг

Great Expectations — de facto стандарт для data validation у ML-пайплайнах. Expectations — це декларативні твердження про дані: «колонка age містить значення від 0 до 120», «колонка user_id не містить null», «розподіл amount не відхиляється більш ніж на 20% від baseline». Запускається в пайплайні, при провалі — блокує проходження.

Pandera — Pythonic alternative для pandas/polars DataFrames. Schema-based validation з type hints:

import pandera as pa

schema = pa.DataFrameSchema({
    "user_id": pa.Column(int, nullable=False),
    "score": pa.Column(float, pa.Check.between(0, 1)),
    "label": pa.Column(str, pa.Check.isin(["positive", "negative", "neutral"])),
})

Data freshness. Модель очікує дані за останні N днів. ETL впав, дані не оновилися — модель використовує застарілі ознаки. Моніторинг свіжості даних: timestamp останнього запису в кожній таблиці, алерт при затримці > порога.

Дедуплікація. Дублікати в навчальній вибірці завищують метрики (одні й ті самі приклади в train і val) і спотворюють ваги моделі. MinHash LSH для наближеної дедуплікації великих датасетів. Для точної — хеш за нормалізованим контентом.

Сховища та формати

Для більшості ML-проектів на старті: Parquet в S3 + DVC для версіонування. Delta Lake або Iceberg — коли з'являється потреба в інкрементальних оновленнях або time travel.

Типові помилки при побудові пайплайнів

• Пропуск перевірки свіжості даних. Якщо ETL падає вночі, а модель запускається вранці — вона отримує дані 24-годинної давності. Рішення: алерт при затримці > 30 хвилин.
• Відсутність версіонування даних. Не можна відтворити експеримент, бо дані змінилися. DVC або Delta Lake time travel виправляють це.
• Забувають про schema evolution. Нове поле з’являється, а пайплайн падає. Автоматичне виявлення змін схеми через Great Expectations.

Active learning дозволяє скоротити бюджет на розмітку до 50–70%. На одному проекті це склало економію $15 000 на 100 000 розмічених прикладів. Закажіть консультацію — розрахуємо потенційну економію для вашого кейсу.

Що входить у проект з дата-інжинірингу для ML

Ми надаємо повний цикл:

• Аудит існуючих даних та пайплайнів (1 тиждень).
• Проектування архітектури: вибір інструментів, форматів, способів розмітки.
• Реалізація ETL/ELT пайплайну з валідацією та моніторингом.
• Документація коду та процесів (model card, data card).
• Навчання вашої команди роботі з пайплайном.
• SLA на супровід та підтримку.

Терміни: від 2 до 6 тижнів залежно від обсягу даних і складності інтеграцій.

Як ми будуємо пайплайн: покроково

1. Аудит існуючих даних. Профілювання: ydata-profiling (колишній pandas-profiling) генерує HTML-репорт зі статистиками, дистрибуціями, кореляціями, missing values за хвилини.
2. Проектування пайплайну. Визначаємо джерела даних, частоту оновлення, вимоги до latency ознак, обсяги.
3. Реалізація та тестування. Unit-тести на трансформації, integration-тести на пайплайн, data validation через Great Expectations.
4. Деплой та моніторинг. Алерти на freshness, quality checks, аномалії в обсягах даних.

Чому варто довірити це нам

Ми займаємося дата-інжинірингом та ML з понад 8-річним досвідом. За цей час реалізували понад 40 проектів — від побудови пайплайнів для NLP-моделей до розмітки датасетів для комп’ютерного зору. Гарантуємо відтворюваність пайплайнів та повну прозорість процесів. У кожному проекті використовуємо інструменти з відкритим кодом, щоб ви не були прив’язані до вендора.

Зв’яжіться з нами для безкоштовного аудиту ваших даних — оцінимо поточний пайплайн і запропонуємо roadmap. Замовте побудову ML-пайплайну під ключ.