feat: Automatically set generation config's `pad_token_id` and `eos_token_id` from the tokenizer and suppress Hugging Face logging warnings.

README.md

@@ -11,25 +11,107 @@ license: apache-2.0
 
 # DeepSeek-OCR-2 & MedGemma-1.5 Multimodal Analysis
 
-Цей проект призначений для аналізу медичних та загальних документів за допомогою сучасних мультимодальних моделей: **DeepSeek-OCR-2** та **MedGemma-1.5-4B-IT**.
+Локальна демонстрація OCR та мультимодального аналізу, що стикає дві найсучасніші моделі Hugging Face: **deepseek-ai/DeepSeek-OCR-2** для загального OCR і **google/medgemma-1.5-4b-it** для медичних зображень.
 
-## 🚀 Основні можливості
+## 🚀 Що тут є
 
-- **DeepSeek-OCR-2**: Високоточне розпізнавання тексту (OCR) на основі архітектури Mixture-of-Experts (MoE).
-- **MedGemma-1.5-4B-IT**: Мультимодальна модель від Google, спеціалізована на медичних зображеннях та текстах.
-- **Веб-інтерфейс Gradio**: Зручне завантаження зображень/PDF, вибір моделі та візуалізація результатів.
-- **ZeroGPU Support**: Оптимізовано для запуску на Hugging Face Spaces.
+- **Гнучкий 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`).
 
-## 📦 Склад проекту
+## 🧠 Архітектура
 
-- `app_hf.py`: Версія для Hugging Face з підтримкою ZeroGPU.
-- `app.py`: Локальна версія з підтримкою MPS (Metal Performance Shaders) для Mac.
-- `requirements.txt`: Список необхідних бібліотек.
+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, кастомний промпт передається до обох моделей.
 
-## 🛠 Налаштування на Hugging Face Spaces
+## 🧰 Потрібне середовище
 
-1. Додайте `HF_TOKEN` у **Settings -> Variables and secrets** для доступу до MedGemma.
-2. Система автоматично запустить `app_hf.py` завдяки метаданим у цьому файлі.
+- Python 3.10+ (рекомендується 3.10/3.11 через сумісність із `transformers`).
+- CUDA 11+ та GPU, якщо хочете запускати DeepSeek/MedGemma локально на CUDA; Mac з MPS теж підтримується.
+- `hf_token` (особливо для MedGemma) з повноваженнями моделі.
+- Залежності: `pip install -r requirements.txt`.
 
----
-*Проект розроблено для тестування та демонстрації можливостей сучасних LLM у сфері розпізнавання медичних документів.*
+## ⚙️ Налаштування
+
+### 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`.

app_hf.py

@@ -11,6 +11,7 @@ except ImportError:
 
 import gradio as gr
 from transformers import AutoModel, AutoTokenizer, AutoProcessor, AutoModelForImageTextToText
+from transformers import logging as hf_logging
 import torch
 import os
 from PIL import Image
@@ -49,6 +50,7 @@ warnings.filterwarnings("ignore", message="CUDA is not available or torch_xla is
 warnings.filterwarnings("ignore", message="The following generation flags are not valid and may be ignored")
 warnings.filterwarnings("ignore", message="The attention mask and the pad token id were not set")
 warnings.filterwarnings("ignore", message="You are using a model of type .* to instantiate a model of type .*")
+hf_logging.set_verbosity_error()
 
 # --- Configuration ---
 DEEPSEEK_MODEL = 'deepseek-ai/DeepSeek-OCR-2'
@@ -104,6 +106,11 @@ class ModelManager:
                 )
                 if hasattr(model, "config") and getattr(model.config, "pad_token_id", None) is None and getattr(tokenizer, "pad_token_id", None) is not None:
                     model.config.pad_token_id = tokenizer.pad_token_id
+                if hasattr(model, "generation_config"):
+                    if getattr(model.generation_config, "pad_token_id", None) is None and getattr(tokenizer, "pad_token_id", None) is not None:
+                        model.generation_config.pad_token_id = tokenizer.pad_token_id
+                    if getattr(model.generation_config, "eos_token_id", None) is None and getattr(tokenizer, "eos_token_id", None) is not None:
+                        model.generation_config.eos_token_id = tokenizer.eos_token_id
                 model.eval()
                 self.models[model_name] = model
                 self.processors[model_name] = tokenizer
@@ -120,6 +127,11 @@ class ModelManager:
                 # Ensure pad_token_id is set
                 if processor.tokenizer.pad_token_id is None:
                     processor.tokenizer.pad_token_id = processor.tokenizer.eos_token_id
+                if hasattr(model, "generation_config"):
+                    if getattr(model.generation_config, "pad_token_id", None) is None:
+                        model.generation_config.pad_token_id = processor.tokenizer.pad_token_id
+                    if getattr(model.generation_config, "eos_token_id", None) is None:
+                        model.generation_config.eos_token_id = processor.tokenizer.eos_token_id
                 self.models[model_name] = model
                 self.processors[model_name] = processor