Перейти к содержанию

Обработка файлов и распознавание

Обработка загруженного файла происходит в несколько этапов: преобразование в изображения, исправление ориентации, сегментация на отдельные документы, извлечение данных и сохранение результатов. В этом разделе описаны модули, отвечающие за первые два этапа --- работу с файлами и распознавание текста.

Поддерживаемые форматы

Система принимает файлы двух типов:

Формат Расширения Особенности
PDF .pdf Основной формат, обрабатывается напрямую
TIFF .tif, .tiff Многостраничные изображения, перед обработкой автоматически преобразуются в PDF

Определение формата выполняется по расширению имени файла (регистр не учитывается). Файлы остальных форматов системой не принимаются.

Преобразование TIFF в PDF

Многостраничный TIFF-файл преобразуется в PDF постранично с целью экономии памяти: каждый кадр обрабатывается отдельно, преобразуется в промежуточный PNG, а затем --- в страницу PDF. После обработки промежуточные данные кадра удаляются из памяти. Готовый PDF сжимается алгоритмом deflate.

Преобразование выполняется библиотекой PyMuPDF (fitz) совместно с Pillow.

Преобразование страниц в изображения

Класс PDFProcessor (модуль pdf_processor.py) отвечает за работу со страницами PDF: подсчёт страниц, преобразование в растровые изображения, извлечение диапазонов страниц в отдельные файлы.

Разрешение

Изображения создаются с разрешением, заданным параметром dpi (по умолчанию --- 150 точек на дюйм). Коэффициент масштабирования вычисляется как dpi / 72, где 72 --- базовое разрешение PDF.

Повышение dpi улучшает качество распознавания текста, но увеличивает размер изображений и время обработки. Значение 150 обеспечивает баланс между качеством и скоростью для типичных бухгалтерских документов.

Автоматическое исправление ориентации

При преобразовании страницы в изображение система может автоматически определить и исправить поворот текста. Для этого используется механизм определения ориентации и письменности Tesseract (OSD --- Orientation and Script Detection).

Порядок действий:

  1. Изображение страницы передаётся в Tesseract OSD.
  2. Tesseract возвращает угол поворота (0, 90, 180 или 270 градусов) и степень уверенности.
  3. Если уверенность превышает порог 1,0 --- изображение поворачивается в обратную сторону для компенсации.

Автоматическое исправление ориентации управляется переменной окружения AUTO_FIX_ROTATION (по умолчанию --- включено). Если используется Google Cloud Vision для распознавания текста, автоповорот через Tesseract отключается, чтобы избежать двойной коррекции.

Преобразование в формат base64

Перед отправкой изображения в Claude его необходимо закодировать в формат base64. При кодировании система автоматически контролирует размер:

  1. Изображение преобразуется в формат JPEG (если исходный формат иной).
  2. Если какая-либо сторона превышает 2048 пикселей --- изображение пропорционально уменьшается.
  3. Если размер закодированных данных превышает 4,5 мегабайта (при ограничении Claude в 5 мегабайт) --- снижается качество JPEG (от 90 до 30).
  4. Если снижение качества не помогает --- изображение уменьшается на 25% и процесс повторяется.
  5. Минимальный допустимый размер --- 800 пикселей по любой стороне.

Извлечение страниц в отдельный PDF

После определения границ документа (какие страницы относятся к одному документу) система извлекает соответствующий диапазон страниц из исходного PDF в новый файл. Этот файл сохраняется в хранилище MinIO и привязывается к записи документа в базе данных.

При извлечении также выполняется автоматический поворот страниц: каждая страница проверяется через Tesseract OSD, и если обнаружен поворот --- он компенсируется на уровне PDF (свойство rotation страницы).

Превью документа

Для каждого извлечённого документа создаётся миниатюра первой страницы в формате PNG. Максимальный размер превью --- 400 на 566 пикселей. Превью сохраняется в отдельном хранилище MinIO и используется для отображения в пользовательском интерфейсе.

Распознавание текста через Google Cloud Vision

Модуль gcp_vision.py реализует распознавание текста с помощью Google Cloud Vision API. Это альтернативный способ получения текста со страниц, который может использоваться вместо Tesseract.

Подключение

Сервис инициализируется как единственный экземпляр (синглтон). Для работы необходимы:

  • Включённая настройка GCP_VISION_ENABLED (по умолчанию --- выключено).
  • Файл учётных данных сервисного аккаунта Google (путь задаётся в GCP_CREDENTIALS_PATH) либо стандартные учётные данные через переменную окружения GOOGLE_APPLICATION_CREDENTIALS.

Если оплата сервиса Google Cloud отключена, система выбрасывает специальную ошибку GCPBillingDisabledError, чтобы задание не обрабатывалось молча с пустыми результатами.

Пакетная обработка

Для повышения производительности изображения обрабатываются пакетами:

  • До 16 изображений включаются в один запрос к сервису (ограничение API).
  • Пакеты обрабатываются параллельно в 4 потока (настройка GCV_PARALLEL_BATCHES).
  • Для 650 изображений это означает около 41 пакетного запроса вместо 650 отдельных, распределённых по 4 потокам --- то есть примерно 11 раундов.

Определение поворота

Помимо распознавания текста, сервис определяет угол поворота страницы. Для этого анализируются координаты ограничивающего прямоугольника первого существенного блока текста:

  • Если верхний край прямоугольника направлен слева направо --- поворот 0 градусов (нормальная ориентация).
  • Если сверху вниз --- 90 градусов по часовой стрелке.
  • Если справа налево --- 180 градусов.
  • Если снизу вверх --- 270 градусов.

Сегментация и сохранение результатов

Класс SegmentationService (модуль segmentation.py) объединяет все этапы обработки в единую последовательность. Именно этот класс вызывается при обработке загруженного файла.

Последовательность обработки задания

  1. Подготовка. Из базы данных извлекается задание, определяется количество страниц в PDF.

  2. Разбиение на порции. Страницы обрабатываются порциями (по умолчанию --- 20 страниц, настраивается через параметр batch_size в настройках программы). Это позволяет обрабатывать большие файлы без чрезмерного потребления памяти.

  3. Преобразование и отправка. Для каждой порции:

    • страницы преобразуются в изображения;
    • изображения кодируются в base64;
    • пакет отправляется в Claude для анализа (подробнее --- в разделе Распознавание через Claude);
    • результаты накапливаются.

  4. Создание документов. Для каждого распознанного документа:

    • извлекаются соответствующие страницы в отдельный PDF;
    • создаётся превью первой страницы;
    • PDF и превью сохраняются в MinIO;
    • определяется контрагент на основе типа документа и извлечённых сторон;
    • выполняется валидация дат (дата договора должна быть раньше даты документа --- если даты перепутаны, они меняются местами);
    • данные из содержимого и имени файла объединяются (приоритет отдаётся содержимому);
    • вычисляются нормализованные значения для последующей группировки;
    • проверяется расхождение между данными из содержимого и именем файла (флаг sync_error);
    • запись документа сохраняется в коллекцию documents.

  5. Группировка. Если найдено два или более документов, запускается автоматическая группировка (подробнее --- в разделе «Группировка документов»).

  6. Завершение. В задании обновляются статус, количество документов и групп, предупреждения и сведения об использовании языковой модели. Если задание связано с файлом из архива --- обновляется и статус архивного файла.

Проверка расхождений (sync_error)

Если данные извлечены одновременно из содержимого документа и из имени файла, система сравнивает их и выявляет расхождения. Сравниваются:

  • номер документа (после нормализации);
  • дата (после приведения к единому формату);
  • контрагент (с учётом частичного вхождения);
  • номер договора.

Если найдены расхождения --- в записи документа устанавливается флаг sync_error и сохраняется список несовпадающих полей. Это позволяет пользователю увидеть документы, требующие ручной проверки.

Обновление шаблонов

После создания каждого документа система обновляет счётчик в коллекции templates. Если шаблон для данного типа и подтипа документа ещё не существует --- он создаётся автоматически. Шаблоны используются на экране «Типы документов» для отображения статистики.

Учёт потребления ресурсов языковой модели

При каждом запросе к Claude фиксируются:

  • количество входящих и исходящих токенов;
  • использованная модель;
  • текст подсказки (сохраняется из первого запроса порции, поскольку подсказка одинакова для всех порций);
  • число запросов.

Все значения накапливаются по порциям и сохраняются в задании в поле usage.

Переменные окружения

Переменная Значение по умолчанию Описание
AUTO_FIX_ROTATION true Включить автоматическое исправление ориентации через Tesseract
DEBUG_SAVE_IMAGES отключено Сохранять изображения страниц в /tmp/debug_images для отладки
GCP_VISION_ENABLED false Использовать Google Cloud Vision вместо Tesseract для распознавания текста
GCP_CREDENTIALS_PATH (не задан) Путь к файлу учётных данных сервисного аккаунта Google

Связь с другими разделами

  • Распознавание через Claude --- анализ изображений страниц, классификация и извлечение данных
  • Группировка документов --- автоматическое объединение связанных документов
  • Конфигурация --- полный список переменных окружения
  • Хранилища данных --- описание коллекций MongoDB и хранилищ MinIO