Индексация баз знаний (Confluence, Notion, SharePoint) для RAG

Индексация баз знаний для 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 за два дня. Закажите пилотный проект, чтобы убедиться в эффективности.

Data Engineering для ML: пайплайны, разметка и качество данных

«У нас много данных» — фраза, которая на деле часто означает «у нас много сырых логов в S3, которые никто не трогал два года». Перед тем как обучить модель, нужно понять, что вообще есть: какова структура, есть ли дубли, как часто меняется схема, насколько репрезентативна выборка.

Data Engineering для ML — не просто ETL. Это построение воспроизводимой инфраструктуры данных, которая делает обучение моделей надёжным, а переобучение — предсказуемым. По опыту нашей команды (8 лет в дата-инжиниринге, более 30 проектов в ML) каждая вторая проблема в продакшене связана не с архитектурой модели, а с качеством данных.

ETЛ-пайплайны для ML: чем отличаются от BI

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

Инструменты. Apache Spark (Wikipedia) для больших объёмов (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% качества модели на валидации.

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

Синтетические данные. Когда реальных данных мало или получить их дорого. Для 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.

Что входит в проект по дата-инжинирингу для ML

Мы предоставляем полный цикл:

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

Как мы строим пайплайн: пошагово

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

Почему стоит доверить это нам

Мы занимаемся дата-инжинирингом и ML с 2016 года. За это время реализовали более 40 проектов — от построения пайплайнов для NLP-моделей до разметки датасетов для компьютерного зрения. Гарантируем воспроизводимость пайплайнов и полную прозрачность процессов. В каждом проекте используем инструменты с открытым исходным кодом, чтобы вы не были привязаны к вендору.

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