README.md

---
title: Local OCR Demo
emoji: 🔍
colorFrom: blue
colorTo: indigo
sdk: gradio
app_file: app_hf.py
pinned: false
license: apache-2.0
---

# DeepSeek-OCR-2 & MedGemma-1.5 Multimodal Analysis

Локальна демонстрація OCR та мультимодального аналізу, що стикає дві найсучасніші моделі Hugging Face: **deepseek-ai/DeepSeek-OCR-2** для загального OCR і **google/medgemma-1.5-4b-it** для медичних зображень.

## 🚀 Що тут є

- **Гнучкий Gradio-інтерфейс**: підтримка завантаження PDF та зображень, вибір моделі, додатковий промпт, клавіші «очистити», «запустити», «зберегти в файл» і автоматичне очікування відповідей.
- **ZeroGPU-готовність**: `app_hf.py` оптимізовано для Hugging Face Spaces з переходом моделей на GPU тільки на час inference.
- **Локальна версія з MPS**: `app.py` підтримує запуск на Python + Metal (Mac) без ZeroGPU.
- **Модулі для порівняння**: `compare_models.py`, `test_real_docs.py` та інші демонструють, як застосувати моделі скриптово.
- **Підтримка PDF**: усереднювання через PyMuPDF (`fitz`) і перетворення кожної сторінки в зображення для подальшого аналізу.
- **Збереження результатів**: усі результати пишуться до `outputs/ocr_result_<timestamp>.txt`, а окремі структури для відлагодження (`outputs/`, `ocr_results*`, `temp_comp.png`).

## 🧠 Архітектура

1. **ModelManager** (`app_hf.py`/`app.py`) кешує завантаження під різні моделі, налаштовує `pad_token_id`, `eos_token_id` та відповідні `generation_config`.
2. Вхід — зображення або PDF (через `gr.Image` чи `gr.File`). Якщо це PDF, кожна сторінка рендериться через `fitz.Matrix(2, 2)`.
3. DeepSeek запускається через метод `model.infer()` з файлами з диску. MedGemma — через `processor.apply_chat_template` + `model.generate()`.
4. Вивід накопичується в пам’яті і показується в текстовому полі Gradio, кастомний промпт передається до обох моделей.

## 🧰 Потрібне середовище

- Python 3.10+ (рекомендується 3.10/3.11 через сумісність із `transformers`).
- CUDA 11+ та GPU, якщо хочете запускати DeepSeek/MedGemma локально на CUDA; Mac з MPS теж підтримується.
- `hf_token` (особливо для MedGemma) з повноваженнями моделі.
- Залежності: `pip install -r requirements.txt`.

## ⚙️ Налаштування

### 1. Загальні кроки

```bash
git clone https://github.com/deepseek-ai/DeepSeek-OCR-2.git
cd DeepSeek-OCR-2
python -m venv venv      # або ваш улюблений venv
source venv/bin/activate
pip install -r requirements.txt
```

### 2. Для Hugging Face Spaces (ZeroGPU)

1. У Settings ➜ Variables and secrets додайте `HF_TOKEN=<ваш токен>` (потрібен для `google/medgemma-1.5-4b-it`).
2. Переконайтеся, що `app_hf.py` використовується як `app_file` (вказано у metadata).
3. Spaces автоматично запускає `demo.queue().launch()`; GPU буде використовуватися тільки в `@spaces.GPU`.
4. У критичних системах з нульовим GPU подбайте про `TRANSFORMERS_CACHE`, `HF_HOME`, `HF_HUB_CACHE` — вони вже прив’язані до `~/.cache/huggingface` або `/data/.huggingface`.

### 3. Локальний запуск

```bash
source venv/bin/activate
python app.py             # Створює інтерфейс Gradio з підтримкою MPS/CUDA
```

- Для MPS (Mac) переконайтеся, що `torch.backends.mps.is_available()` повертає `True`; після завершення скрипт викликає `torch.mps.empty_cache()`.
- При запуску на CUDA рекомендується додати перемінну `TRANSFORMERS_VERBOSITY=info` для діагностики та вивчати журнали.

## 🎮 Як користуватись

1. У веб-інтерфейсі завантажте зображення (`.png`, `.jpg`, `.jpeg`) або PDF.
2. Оберіть модель: DeepSeek для OCR або MedGemma для медичних сценаріїв.
3. За потреби напишіть **користувацький промпт** (див. `prompt_input`).
4. Натисніть **«Запустити аналіз»**.
5. Результат з’явиться у текстовому полі; можна зберегти кнопкою 💾 або завантажити файл.
6. «Очистити» скидає усі поля.

## 💾 Результати і структура виводу

- `outputs/ocr_result_<YYYYMMDD_HHMMSS>.txt`: основний текстовий файл із результатами (згенеровано через `save_result_to_file`).
- `ocr_results/` та `ocr_results_pdf12/`: історичні папки для тестових документів.
- `temp_comp.png`: проміжні зображення, які створюються під час розробки.
- `ocr_results_package.zip`: приклад пакетованих результатів.

## 🧪 Тестування та сценарії

- `test_inference.py`, `test_real_docs.py`, `test_minimal.py`, `test_medgemma.py` — приклади запуску обох моделей без Gradio.
- `compare_models.py` — бенчмарк порівняння DeepSeek і MedGemma.
- `ocr_full_pdf12.py` — повна обробка PDF довжиною до 12 сторінок.
- `generate_test_image.py` — генерація синтетичного зображення для швидких перевірок.
- Запускайте тести через `python test_real_docs.py` тощо, переконайтесь, що моделі завантажені і в кеші.

## 🛠️ Поширені проблеми

- `The following generation flags are not valid... temperature`: виникає при передачі параметрів із CLI – лог зараз приглушений.
- `attention mask and pad token id were not set`: переконайтеся, що `pad_token_id`/`eos_token_id` встановлені в токенізаторі й `generation_config`.
- `MedGemma` вимагає `HF_TOKEN` із доступом до моделі — без нього завантаження не пройде.
- `CUDA` або `MPS` може бути відсутній: `run_ocr` автоматично використовує `contextlib.nullcontext` і не вимагає GPU.
- Якщо бачите `torch.cuda.empty_cache()` або `gc.collect()` у логах — це нормальна очистка ZeroGPU-ресурсів.

## 🗂️ Структура проекту

- `app_hf.py`: Gradio demo для Hugging Face Spaces + ZeroGPU, GPU-секція охоплена `spaces.GPU`.
- `app.py`: локальний Gradio-інтерфейс із підтримкою MPS.
- `compare_models.py`: скрипт порівняння.
- `convert_docs.py`, `convert_full_pdf.py`: конвертери та допоміжні утиліти.
- `requirements.txt`: основні залежності (`transformers`, `gradio`, `torch`, `Pillow`, `PyMuPDF`, `huggingface_hub`).
- `doc_images`, `doc_for_testing`: набір тестових файлів.

## 🤝 Контрибуція

1. Створіть issue з описом завдання/помилки.
2. Відгалужте репозиторій, реалізуйте зміни, напишіть тести/опис.
3. Відкрийте PR із обґрунтуванням впливу.

## 📜 Ліцензія

Проект поширюється під ліцензією Apache-2.0. Деталі див. у `LICENSE`.