README.md

metadata

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. Загальні кроки

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. Локальний запуск

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.