Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,185 @@
+---
+license: mit
+tags:
+  - ocr
+  - document-processing
+  - computer-vision
+  - deepseek
+  - colab
+  - jupyter
+  - optical-character-recognition
+  - text-detection
+  - document-to-markdown
+  - notebook
+library_name: transformers
+pipeline_tag: image-to-text
+---
+
+# DeepSeek-OCR Google Colab Notebook
+
+A ready-to-use Google Colab notebook for running DeepSeek-OCR, a state-of-the-art optical character recognition model that converts images and documents to markdown format with high accuracy.
+
+## 🚀 Quick Start
+
+### Open in Google Colab
+
+Click the badge below to open the notebook directly in Google Colab:
+
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ahczhg/DeepSeek-OCR-Colab/blob/main/DeepSeek_OCR_Colab.ipynb)
+
+**Or download the notebook from this repository and upload to Google Colab manually.**
+
+### Steps:
+1. Click the "Open in Colab" badge above
+2. Select **Runtime → Change runtime type → GPU** (T4 or better recommended)
+3. Run all cells sequentially
+4. Upload your image when prompted
+5. Get markdown-formatted text output
+
+## ✨ Features
+
+- **Easy Setup**: One-click deployment on Google Colab
+- **GPU Acceleration**: Optimized for NVIDIA GPUs (T4, L4, A100, V100)
+- **Flexible Processing**: Single image or batch processing support
+- **High Quality OCR**: Converts documents to markdown with text detection and grounding
+- **Multiple Resolution Modes**: Tiny, Small, Base, Large, and Gundam (cropped) modes
+- **Real-time Preview**: View uploaded images before processing
+
+## 📋 Requirements
+
+### For Google Colab:
+- GPU Runtime (T4 or better recommended)
+- ~15-20 minutes setup time
+- ~23GB GPU memory (L4 or equivalent)
+
+### For Local Setup:
+- NVIDIA GPU with CUDA support (12.1+)
+- Python 3.8+
+- PyTorch 2.0+
+- 22GB+ GPU VRAM
+
+## 💡 Usage
+
+### Single Image Processing
+
+1. **Upload your image** in the designated cell
+2. **Run the inference cell** to process the image
+3. **Download results** from the output directory
+
+Example prompt:
+```python
+prompt = "<image>\n<|grounding|>Convert the document to markdown."
+```
+
+### Batch Processing
+
+Process multiple images at once with automatic iteration through uploaded files. Results are saved to the output directory.
+
+## ⚙️ Model Configuration
+
+The notebook supports different processing modes:
+
+| Mode | base_size | image_size | crop_mode | Use Case |
+|------|-----------|------------|-----------|----------|
+| Tiny | 512 | 512 | False | Quick processing, lower quality |
+| Small | 640 | 640 | False | Balanced speed/quality |
+| Base | 1024 | 1024 | False | Standard quality |
+| Large | 1280 | 1280 | False | High quality, slower |
+| Gundam | 1024 | 640 | True | Recommended (cropped processing) |
+
+**Default Configuration (Recommended):**
+```python
+base_size = 1024
+image_size = 640
+crop_mode = True
+```
+
+## 📤 Output Format
+
+The model outputs:
+- **Markdown formatted text** with proper heading structure
+- **Bounding box coordinates** for detected elements (`<|det|>`)
+- **Element references** (`<|ref|>`) for text, titles, tables, etc.
+- **Tables** converted to markdown format
+- **Compression ratio** metrics for analysis
+
+Example output structure:
+```
+<|ref|>text<|/ref|><|det|>[[x1, y1, x2, y2]]<|/det|>
+Extracted text content here...
+
+<|ref|>sub_title<|/ref|><|det|>[[x1, y1, x2, y2]]<|/det|>
+## Heading Text
+```
+
+## 🛠️ Troubleshooting
+
+### Out of Memory (OOM)
+- Use a higher-tier GPU (A100, V100)
+- Reduce image resolution before processing
+- Use smaller processing modes (Tiny or Small)
+
+### Flash Attention Installation Fails
+- The notebook removes `attn_implementation='flash_attention_2'` by default
+- Standard attention mechanism is used as fallback
+
+### Model Download Slow
+- First download takes 10-15 minutes (normal)
+- Model is cached after first download
+- Check your Colab internet connection
+
+### Image Format Issues
+```python
+# Ensure RGB format
+from PIL import Image
+img = Image.open('image.png').convert('RGB')
+```
+
+## 📊 Performance Tips
+
+1. **Image Resolution**: Use native resolutions (512, 640, 1024, 1280) for best results
+2. **Batch Processing**: More efficient for multiple images
+3. **GPU Selection**: L4 or better recommended for faster processing
+4. **Compression**: Enable `test_compress=True` to see compression metrics
+
+## 📁 Repository Files
+
+- `DeepSeek_OCR_Colab.ipynb` - Main Google Colab notebook
+- `requirements.txt` - Python dependencies
+- `LICENSE` - MIT License
+- `README.md` - This documentation
+
+## 🙏 Credits
+
+Based on the official DeepSeek-OCR repository:
+- **Repository**: [deepseek-ai/DeepSeek-OCR](https://github.com/deepseek-ai/DeepSeek-OCR)
+- **Model**: [deepseek-ai/DeepSeek-OCR on HuggingFace](https://huggingface.co/deepseek-ai/DeepSeek-OCR)
+- **Paper**: DeepSeek-OCR: High-Accuracy Document OCR
+
+## 📄 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+The DeepSeek-OCR model itself is subject to its own license terms from DeepSeek AI.
+
+## 🔗 Links
+
+- **Hugging Face Model**: [https://huggingface.co/ahczhg/DeepSeek-OCR-Colab](https://huggingface.co/ahczhg/DeepSeek-OCR-Colab)
+- **Hugging Face Space**: [https://huggingface.co/spaces/ahczhg/DeepSeek-OCR-Colab](https://huggingface.co/spaces/ahczhg/DeepSeek-OCR-Colab)
+- **Open in Colab**: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ahczhg/DeepSeek-OCR-Colab/blob/main/DeepSeek_OCR_Colab.ipynb)
+
+## 📖 Citation
+
+If you use this notebook in your research, please cite the original DeepSeek-OCR paper:
+
+```bibtex
+@article{deepseek2024ocr,
+  title={DeepSeek-OCR: High-Accuracy Document OCR},
+  author={DeepSeek AI},
+  year={2024}
+}
+```
+
+---
+
+**Note**: This is a community-contributed notebook wrapper for the DeepSeek-OCR model. For the official model and implementation, please visit the [DeepSeek-OCR repository](https://github.com/deepseek-ai/DeepSeek-OCR).