SvodPro: Автоматизированный ETL-пайплайн подготовки базы знаний из нормативных PDF-документов

Enterprise-grade ETL-процесс, разработанный для извлечения, очистки, секционирования и синхронной индексации сложных инженерных документов (СП, ГОСТ) в реляционное и векторное хранилища для последующего использования в AI/RAG-системах.

📋 О проекте

SvodPro — это коммерческая инициатива по автоматизации обработки и интеллектуального анализа нормативно-технической документации в строительной и инженерной отраслях. Проект решает бизнес-задачу по сокращению времени поиска нормативных требований инженерами за счет трансформации неструктурированных регламентов (PDF-документов) в структурированную базу знаний, адаптированную для интеграции с корпоративными ИИ-ассистентами и LLM-сервисами.

Проект разработан командой инженеров. Моя роль в проекте: проектирование и реализация ETL-пайплайна данных (компоненты Extract, Transform, Load в Vector DB), создание проверочного контура и юнит-тестирование.

---

🛠 Ключевой функционал и зоны ответственности (DE)

1. Сквозной оркестрируемый пайплайн (DAG)

• Что сделано: Построен полный pipeline подготовки базы знаний: объединены конвертация, очистка, выделение структуры, чанкование и загрузка данных в хранилища в едином сценарии run_full_pipeline.py.
• Стек: Python, run_full_pipeline.py, python-dotenv.
• Ценность: Опыт разработки воспроизводимого и отказоустойчивого ETL-процесса для AI/RAG-систем.

2. Преобразование тяжелых PDF в Markdown

• Что сделано: Реализовано преобразование PDF в Markdown с поддержкой больших документов. Для объемных файлов предусмотрена обработка по страницам с последующей сборкой результата.
• Стек: Docling, pypdf, Python.
• Ценность: Навыки работы с неструктурированными данными и оптимизация ресурсоемкого document processing.

3. Очистка данных и извлечение метаданных

• Что сделано: Разработана система очистки документов и извлечения метаданных: обработка оглавлений, переносов слов, служебной разметки. Формирование структурированного JSON со сведениями о документах, датах введения, статусах обязательности и секциях.
• Стек: Python, регулярные выражения (re), JSON.
• Ценность: Понимание влияния качества исходных данных на точность поиска, индексацию и ответы AI-системы.

4. Специализированный контекстный чанкинг

• Что сделано: Реализован кастомный чанкинг нормативных текстов, учитывающий иерархию пунктов, ложные границы, табличные блоки, тип содержимого (text/table), номера разделов и точное число токенов.
• Стек: Python, langchain-text-splitters, tokenizer embedding-модели.
• Ценность: Создание предметной логики разбиения данных вместо универсального подхода split-by-length.

5. Генерация Embeddings для семантического поиска

• Что сделано: Сформированы embeddings для семантического поиска: преобразование чанков документов в векторные представления для дальнейшего retrieval по смысловой близости.
• Стек: sentence-transformers, модель ai-forever/ru-en-RoBERTa.
• Ценность: Практический опыт подготовки и векторизации данных для vector search.

6. Согласованная гибридная загрузка (Supabase & Qdrant)

• Что сделано: Организована согласованная загрузка данных. Документы, секции и текст чанков сохраняются в реляционном хранилище, а векторы загружаются в коллекцию sp_chunks с жесткой привязкой через UUID-идентификаторы чанков.
• Стек: Supabase Python client, Qdrant client, batch upsert (вставка пачками по 100 объектов).
• Ценность: Интеграция relational и vector databases, поддержка идемпотентности (повторной загрузки данных).

7. Проектирование SQL-схемы и безопасности данных

• Что сделано: Спроектирована SQL-схема и политики доступа для AI-сервиса: созданы модели документов, секций, чанков, пользователей, рабочих пространств, сессий и сообщений. Добавлены индексы (включая GIN), функции и Row Level Security (RLS).
• Стек: PostgreSQL / Supabase SQL, JSONB, GIN-индексы, RLS.
• Ценность: Навыки data modeling, безопасности доступа и подготовки данных для взаимодействия DE- и DS-компонентов.

8. Эксплуатационный и проверочный контур pipeline

• Что сделано: Добавлен проверочный контур: настроен запуск локального Qdrant через Docker Compose, подготовлен шаблон окружения, логирование и коды завершения оркестратора, а также unit-тесты парсинга и чанкинга с mock-эмбеддером.
• Стек: Docker Compose, Qdrant, Python logging, pytest.
• Ценность: Опыт поддержки data pipeline, диагностики интеграций и изолированного тестирования критической логики без загрузки тяжелой ML-модели.

---

📋 Системные требования и окружение

• Язык разработки: Python >= 3.10.
• Контейнеризация: Docker Desktop (для локального развертывания баз данных).
• Ключевые расширения и библиотеки: Полный список зафиксирован в requirements.txt.

---

📂 Структура проекта

├── config/                  # Конфигурационные файлы проекта
├── data/
│   └── pdfs/                # Папка для входящих исходных PDF-документов
├── output/
│   ├── cleaned/             # Очищенный текст документов
│   ├── json/                # Иерархические JSON метаданных
│   └── markdown/            # Сырые Markdown файлы после конвертации
├── scripts/                 # Модули пайплайна
│   ├── 01_pdf_to_markdown.py    # Конвертация тяжелых PDF (с нарезкой)
│   ├── 02_clean_markdown.py     # Очистка текста и сборка метаданных
│   ├── 03_supabase_writer.py    # Регистрация структуры в реляционной БД
│   ├── 04_chunking.py           # Контекстное разделение текста на пункты
│   ├── 05_embedding.py          # Математический модуль генерации векторов
│   ├── 06_upsert_chunks_supb.py # Пакетная загрузка чанков в Supabase
│   └── 07_insert_to_qdrant.py   # Индексация векторов в Qdrant
├── tests/
│   └── test_sp_parser.py    # Unit-тесты критических узлов парсинга (pytest)
├── docker-compose.yml       # Контейнер для локального запуска Qdrant
├── env.example              # Шаблон конфигурации переменных окружения
├── requirements.txt         # Зависимости проекта с фиксированными версиями
└── run_full_pipeline.py     # Мастер-оркестратор (Точка входа / DAG)

---

📦 Инструкция по развертыванию локальной песочницы

1. Зависимости: Установите библиотеки:

   pip install -r requirements.txt

2. Инфраструктура: Запустите локальную векторную базу данных:

   docker-compose up -d

3. Конфигурация: Создайте файл .env в корне проекта на основе шаблона env.example и укажите актуальные доступы.
4. Тестирование: Прогоните проверочный контур юнит-тестов:

   pytest tests/

5. Запуск: Положите PDF-документы в data/pdfs/ и выполните мастер-скрипт:

   python run_full_pipeline.py

---

📈 Выводы по проекту

1. Преодоление hardware-лимитов: Разделение сквозной обработки тяжелых файлов на контролируемые изолированные итерации (постраничная нарезка) позволило снизить пиковую нагрузку на RAM в 5 раз и гарантировать стабильную работу ETL на рядовых машинах.
2. Качество данных решает: Изоляция таблиц и очистка от мусорных переносов строк снизили уровень шума в эмбеддингах, повысив точность семантического поиска (retrieval) в Qdrant.
3. Безопасность и масштабируемость: Разделение хранения текстового контекста (Supabase) и векторов (Qdrant) с помощью сквозных UUID обеспечило гибкость системы. Использование PostgreSQL RLS гарантирует изоляцию рабочих пространств пользователей.