PROJECT_SUMMARY.md

خلاصه پروژه dots.ocr Space

✅ آنچه انجام شد

پروژه شما برای استقرار در Hugging Face Space کاملاً آماده شده است. این Space از مدل dots.ocr برای OCR چندزبانه و تشخیص layout اسناد استفاده می‌کند.

📁 ساختار پروژه

ocr/
├── app.py                 # فایل اصلی Gradio (رابط کاربری)
├── requirements.txt       # وابستگی‌های Python
├── config.py             # تنظیمات و کانفیگ
├── api_example.py        # مثال استفاده از API
├── README.md             # مستندات اصلی (برای HF Space)
├── DEPLOYMENT.md         # راهنمای استقرار
├── USAGE_GUIDE.md        # راهنمای استفاده (فارسی)
├── PROJECT_SUMMARY.md    # این فایل
├── .gitignore           # فایل‌های نادیده گرفته شده
└── examples/            # پوشه برای تصاویر نمونه
    └── README.md

🚀 مراحل بعدی (برای استقرار)

1. ایجاد Space در Hugging Face

# به این آدرس بروید:
https://huggingface.co/spaces

# روی "Create new Space" کلیک کنید
# تنظیمات:
- SDK: Gradio
- Hardware: GPU (حداقل T4)
- License: MIT

2. آپلود فایل‌ها

روش Git:

git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE
cd YOUR_SPACE
# کپی کردن فایل‌های این پروژه
git add .
git commit -m "Setup dots.ocr Space"
git push

یا آپلود مستقیم از رابط وب Hugging Face

3. صبر کنید تا Build شود

• نصب dependencies: ~5-10 دقیقه
• دانلود مدل: ~10-15 دقیقه
• بعد آماده است! ✨

🎯 قابلیت‌های Space

1. رابط کاربری Gradio

• آپلود تصویر
• انتخاب نوع پردازش
• خروجی JSON structured

2. API Endpoint

from gradio_client import Client

client = Client("YOUR_USERNAME/YOUR_SPACE_NAME")
result = client.predict(
    image="path/to/image.jpg",
    prompt_type="Full Layout + OCR (English)",
    custom_prompt=""
)

3. پشتیبانی از چند نوع پردازش

• Full Layout + OCR: تحلیل کامل + استخراج متن
• OCR Only: فقط استخراج متن
• Layout Detection: فقط تشخیص layout
• Custom: پرامپت سفارشی

📊 فرمت‌های خروجی

متن معمولی

Markdown formatted text

JSON (برای Full Layout)

[
  {
    "bbox": [x1, y1, x2, y2],
    "category": "Text|Table|Formula|...",
    "text": "محتوا..."
  }
]

فرمت‌های خاص

• فرمول‌ها: LaTeX
• جداول: HTML
• متن: Markdown

🌍 زبان‌های پشتیبانی شده

• انگلیسی
• فارسی
• عربی
• چینی
• و بسیاری دیگر (چندزبانه)

⚙️ تنظیمات مهم

در config.py:

• MAX_NEW_TOKENS = 8192: حداکثر طول خروجی
• TEMPERATURE = 0.1: دقت بالاتر
• GPU_DURATION = 120: مدت زمان GPU (ثانیه)

در app.py:

• استفاده از @spaces.GPU برای بهینه‌سازی
• Lazy loading مدل
• پشتیبانی از JSON formatting

💡 نکات استفاده

کیفیت تصویر

• رزولوشن: کمتر از 11,289,600 پیکسل
• فرمت: JPG, PNG, PDF
• DPI توصیه شده: 200 (برای PDF)

بهینه‌سازی

• از تصاویر با کیفیت مناسب استفاده کنید
• برای PDF های بزرگ، صفحه به صفحه پردازش کنید
• برای استفاده production، GPU دائمی فعال کنید

📚 مستندات

• DEPLOYMENT.md: راهنمای کامل استقرار
• USAGE_GUIDE.md: راهنمای استفاده به فارسی
• README.md: مستندات برای Hugging Face Space
• api_example.py: نمونه کد Python برای API

🔧 عیب‌یابی سریع

مشکل	راه حل
Build error	چک کردن requirements.txt و لاگ‌ها
Out of memory	GPU بزرگتر یا کاهش سایز تصویر
مدل لود نمی‌شود	مطمئن شوید GPU فعال است
خروجی نادرست	پرامپت دیگری امتحان کنید

📞 پشتیبانی

• GitHub: https://github.com/rednote-hilab/dots.ocr
• Model: https://huggingface.co/rednote-hilab/DotsOCR
• HF Docs: https://huggingface.co/docs/hub/spaces

✨ ویژگی‌های کلیدی مدل

• Parameters: 1.7B
• Base: Qwen2.5-VL
• Performance: SOTA on OmniDocBench
• Multilingual: پشتیبانی از زبان‌های کم‌منبع

🎉 آماده برای استقرار!

همه فایل‌ها آماده هستند. فقط کافیست:

1. Space بسازید
2. فایل‌ها را آپلود کنید
3. GPU را فعال کنید
4. منتظر Build شوید

موفق باشید! 🚀

---

توضیحات فنی:

• استفاده از Transformers + Gradio
• GPU optimization با @spaces.GPU decorator
• Lazy loading برای صرفه‌جویی در منابع
• پشتیبانی از multiple prompt types
• خروجی JSON structured
• API-ready برای integration