--- 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_.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_.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`.