Document Checker

Инструмент для автоматического сопоставления информации из PDF документов с данными архивных справочников.

Описание проекта

Document Checker анализирует PDF-документы (архивные справки) и извлекает из них ключевую информацию:

• Название архивного отдела
• Наименование организации

Затем выполняется поиск по справочнику (CSV файл) и определяются наиболее близкие совпадения с использованием:

1. Точного текстового поиска по ключевым словам
2. Семантического поиска с использованием векторных вложений (embeddings)

Для повышения производительности используется кэширование векторных представлений.

Проблема

Ручное сопоставление PDF-документов со справочными данными требует большого количества времени, подвержено человеческим ошибкам и затрудняет обработку крупных массивов архивной информации.

Цель проекта

Автоматизировать процесс проверки документов, обеспечивая высокую точность и скорость работы.

Функциональные возможности

• Извлечение структурированных данных из PDF документов
• Точный поиск совпадений по наименованию архива и организации
• Семантический поиск с использованием модели Sentence Transformers
• Кэширование векторных представлений для ускорения повторных запусков
• Детальное логирование процесса обработки документов

Веб-интерфейс Streamlit (обновление 2025-06)

В проект добавлено современное мульти-страничное Web-приложение на Streamlit (>= 1.36):

Страница	Назначение
Проверка N2	Семантическая сверка PDF со справочником
Проверка N8	OCR-поиск блоков «Утверждено / Согласовано» и сравнение подписей

Обе страницы доступны через встроенную навигацию st.navigation, используют общие директории pdf_documents/ и data/, а также единые кэш-директории.

Порог «точного совпадения» теперь считается при коэффициенте ≥ 0.9.

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

project_root/
├── src/
│   ├── main.py                    # Точка входа
│   ├── services/
│   │   ├── document_checker.py         # Основная логика
│   │   ├── pdf_parser.py               # Парсер
│   │   └── reference_index.py          # Векторизация
│   ├── utilities/
│   │   └── text_normalizer.py          # Нормализатор текста
│   ├── models/
│   └── controllers/
├── data/
│   └── merged.csv                 # Справочник
├── config/
│   └── config.py
├── embeddings_cache/              # Кэш эмбеддингов
├── results/                       # JSON отчёты
├── logs/                          # Логи
├── pdf_documents/                 # PDF документы для обработки
├── pyproject.toml
├── stream_app.py            # Мульти-страничный Web-UI (N2+N8)
├── proverka8/                       # Логика OCR-проверки N8
└── README.md

Установка

1. Клонируйте репозиторий:

git clone https://github.com/your-username/document-checker.git
cd document-checker

2. Подготовьте окружение (рекомендуемый способ):

# однократно установите Python 3.8 (при необходимости)
uv python install 3.8

# создайте/обновите виртуальное окружение и установите зависимости
uv sync

uv sync автоматически:

• выбирает интерпретатор, закреплённый в .python-version (3.8);
• создаёт каталог .venv;
• устанавливает точные версии пакетов из uv.lock.

3. Альтернативный способ (pip):

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.lock.txt

Использование

Базовое использование

python -m src.main

Параметры командной строки

• --reference, -r: Путь к CSV файлу со справочными данными (по умолчанию: "data/merged.csv")
• --pdf_dir, -p: Директория с PDF файлами для обработки (по умолчанию: "pdf_documents")
• --cache_dir, -c: Директория для кэширования эмбеддингов (по умолчанию: "embeddings_cache")
• --save_embeddings, -s: Сохранить эмбеддинги после обработки
• --debug_pdf, -d: Включить режим отладки PDF парсера
• --pdf_file, -f: Обработать только один указанный PDF файл
• --force_rebuild, -b: Принудительно пересоздать кэш эмбеддингов

Примеры

Обработать все PDF файлы в указанной директории:

python -m src.main --pdf_dir my_documents

Обработать один файл с включенным режимом отладки:

python -m src.main --pdf_file "documents/example.pdf" --debug_pdf

Пересоздать кэш эмбеддингов:

python -m src.main --force_rebuild

Формат справочных данных

Входной CSV файл должен содержать как минимум две колонки приведённых к единому виду:

• Архив: Название архивного отдела
• Наименование: Наименование организации

Запуск Streamlit-приложения

Активация окружения (если ещё не выполнена)

uv sync # создаст .venv и установит зависимости source .venv/bin/activate # Windows: .venv\Scripts\activate

Запуск Web-UI

streamlit run src/stream_app.py

## Изменения последней итерации

* Добавлено Streamlit-приложение с двумя страницами.
* Интегрирована проверка **N8** (`proverka8`) в общий UI.
* Порог точного совпадения увеличен до **0.9**.
* Удалён виджет показа «детального JSON» (упрощение интерфейса).

## Технологический стек

- **Python 3.8+**
- **sentence-transformers**, **FAISS**, **PyMuPDF**, **NumPy**, **Pandas**
- **uv** — управление зависимостями и виртуальной средой
- ***Ruff**, **Black** — линтинг, форматирование

## Используемая языковая модель

> Эта секция описывает, какая модель "большого" языкового пространства применяется, где она задаётся
> и как обеспечивается её наличие на локальной машине.

### Какая модель используется?

По умолчанию проект работает с мульти-языковой моделью [**`paraphrase-multilingual-MiniLM-L12-v2`**](https://huggingface.co/sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2). Её название задаётся в конфигурационном файле:

```3:8:config/config.py
CONFIG = {
    "model_name": "paraphrase-multilingual-MiniLM-L12-v2",
    ...
}

Как скачивается модель?

Библиотека sentence-transformers автоматически загружает модель при первом обращении и кэширует её в каталоге ~/.cache/sentence-transformers (можно переопределить переменной окружения SENTENCE_TRANSFORMERS_HOME). Поэтому дополнительных шагов для установки модели не требуется — достаточно интернет-доступа при первом запуске.

Режим офлайн / предзагрузка

Если требуется работать без доступа в сеть, скачайте модель заранее:

huggingface-cli download sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 --local-dir ~/.cache/sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2

Либо установите собственный путь к кэшу:

export SENTENCE_TRANSFORMERS_HOME="/path/to/models_cache"  # Windows: setx SENTENCE_TRANSFORMERS_HOME "C:\models_cache"

Как сменить модель?

1. Отредактируйте значение model_name в config/config.py,
2. (Опционально) добавьте чтение переменной окружения, например:

   import os
   MODEL_NAME = os.getenv("MODEL_NAME", CONFIG["model_name"])

3. Запустите проект — новая модель будет автоматически загружена и закэширована.

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

Категория	Состояние
Извлечение данных из PDF	✅ Готово
Точный и семантический поиск	✅ Готово
Мульти-страничный Web-UI	✅ Готово
Интеграция проверки N8 (OCR)	✅ Готово

Вклад

PR и issue приветствуются! Перед созданием запроса убедитесь, что код отформатирован с помощью black и проверен ruff.