Local TTN Parser

Локальная система извлечения структурированных данных из ТТН (товарно-транспортных накладных) без отправки документов во внешние облачные сервисы.

Проект ориентирован на демонстрационный и прикладной сценарий: загрузка скана/фото ТТН, получение промежуточного распознавания и формирование итогового JSON для дальнейшей интеграции.

Содержание

• Что умеет проект
• Архитектура
• Структура репозитория
• Демо-видео
• Результаты проверки качества
• Установка и запуск с нуля (Windows / macOS / Linux)
• Запуск тестов
• Известные ограничения
• Дополнительная документация

Что умеет проект

• Локально обрабатывает сканы и фотографии ТТН.
• Поддерживает извлечение ключевых полей и табличных блоков по шаблону.
• Показывает промежуточный Markdown-результат от визуальной модели.
• Формирует итоговый JSON (через локальный LLM-слой для нормализации и структурирования).
• Позволяет скачать результат в формате JSON из интерфейса.

Архитектура

В репозитории фактически представлены два контура обработки:

1. Основной (актуальный) VLM-пайплайн
   Streamlit UI -> Qwen2-VL -> Markdown -> Ollama (qwen2.5:14b) -> JSON.

2. Legacy OCR-пайплайн (MVP, для совместимости и экспериментов)
   OpenCV preprocessing -> PaddleOCR -> rule-based parsing.

1) UI-слой (src/app.py)

• Веб-интерфейс на Streamlit.
• Пользователь выбирает шаблон документа, загружает изображение и запускает разбор.
• Визуальная модель Qwen2-VL-2B-Instruct получает изображение + строгий промпт.
• Далее отдельным шагом запускается нормализация результата в JSON.

2) VLM-слой (визуальное распознавание)

• Используется transformers-модель Qwen/Qwen2-VL-2B-Instruct.
• Генерация настроена в детерминированном режиме (temperature=0.0, do_sample=False) для снижения галлюцинаций.
• Выход модели сначала хранится как Markdown/текстовый промежуточный слой.

3) LLM-слой структурирования (src/llm_parser.py)

• Используется локальный endpoint Ollama в OpenAI-совместимом формате (http://localhost:11434/v1).
• Модель qwen2.5:14b получает Markdown и преобразует его в целевой JSON.
• На выходе: JSON-объект + сырой текст ответа модели (для отладки).

4) OCR/эвристический контур (src/services.py, src/table_parser.py)

• OpenCV-предобработка (контраст, grayscale и т.д.).
• PaddleOCR для распознавания текста.
• Эвристики и fuzzy matching для:
  • выделения регионов таблиц;
  • распознавания заголовков и строк;
  • извлечения полей свободного текста.

Этот контур полезен как fallback/исследовательский baseline и как база для unit-тестов.

Структура репозитория

• src/app.py — основной Streamlit UI и запуск VLM/LLM пайплайна.
• src/llm_parser.py — преобразование промежуточного текста в JSON через Ollama.
• src/table_parser.py — парсинг таблиц и полей на OCR-результатах.
• src/services.py — legacy OCR-пайплайн.
• src/config.py и src/config_ttn_sample_*.py — шаблоны и конфигурации полей/таблиц.
• tests/ — тесты и фикстуры.
• docs/ttn_samples/ — примеры ТТН.
• docs/media/ — демонстрационные материалы.
• Analysis_and_structure.md — аналитика и архитектурные решения.
• Roadmap.md — план работ.

Демо-видео

Демонстрация работы проекта доступна по внешней ссылке:

• YouTube: демонстрация работы TTN Parser

Результаты проверки качества

По внутренней проверке на 20 ТТН:

• Успешный разбор: 97%.
• Основной поток обработки в целом работает стабильно.

Наиболее частые источники оставшихся ошибок:

1. Английские названия иногда распознаются на русском языке
   (смешение кириллицы/латиницы в OCR/VLM-слое).
2. Неточности форматирования JSON
   (например, кавычки без корректного экранирования в промежуточном ответе модели).

Установка и запуск с нуля (Windows / macOS / Linux)

Ниже полная пошаговая инструкция для чистой машины.

0. Требования

• Git
• Python 3.10+ (рекомендуется 3.10/3.11)
• pip
• Ollama (для локального LLM-слоя JSON-структурирования)
• Достаточно RAM/VRAM для запуска VLM-модели (минимум зависит от конфигурации устройства)

---

1. Клонирование репозитория

git clone https://github.com/DakariLuin/local-ttn-parser.git
cd local-ttn-parser

---

2. Создание и активация виртуального окружения

Windows (PowerShell)

python -m venv .venv
.venv\Scripts\Activate.ps1

Если политика выполнения блокирует активацию:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate

---

3. Установка Python-зависимостей

cd src
pip install --upgrade pip
pip install -r requirements.txt

В проекте используются дополнительные пакеты для VLM/LLM-контура (torch, transformers, openai, qwen-vl-utils).
При необходимости установите их явно:

pip install torch transformers openai qwen-vl-utils

---

4. Установка и подготовка Ollama

1. Установите Ollama:
   • Windows: https://ollama.com/download
   • macOS: https://ollama.com/download
   • Linux:

     curl -fsSL https://ollama.com/install.sh | sh

2. Убедитесь, что сервис Ollama запущен.
3. Загрузите модель для JSON-структурирования:

ollama pull qwen2.5:14b

---

5. Запуск приложения

Из директории src:

streamlit run app.py

После запуска откройте URL из терминала (обычно http://localhost:8501).

---

6. Базовый сценарий проверки после запуска

1. Откройте веб-интерфейс Streamlit.
2. Выберите шаблон документа в боковой панели.
3. Загрузите изображение ТТН (png/jpg/jpeg).
4. Нажмите "Начать разбор".
5. Проверьте промежуточный Markdown.
6. Нажмите "Сформировать JSON".
7. Скачайте результат через "Скачать JSON".

Запуск тестов

Из корня проекта:

python -m unittest tests/test_table_pipeline.py

Известные ограничения

• Качество зависит от качества скана/фото и читаемости таблиц.
• Сложные случаи смешанной кириллицы/латиницы могут ухудшать точность полей.
• Иногда требуется пост-валидация JSON перед отправкой в downstream-системы.
• Производительность и стабильность VLM-контура зависят от ресурсов машины.

Дополнительная документация

• Анализ и Архитектура
• Roadmap

---

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