Spaces:
Running
on
Zero
Running
on
Zero
| 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`. | |