DEPLOYMENT.md

راهنمای استقرار (Deployment Guide)

مراحل استقرار در Hugging Face Spaces

1. ایجاد Space جدید

1. به https://huggingface.co/spaces بروید
2. روی "Create new Space" کلیک کنید
3. اطلاعات را پر کنید:
   • Owner: نام کاربری خود
   • Space name: نام دلخواه (مثلاً dots-ocr)
   • License: MIT
   • Select the Space SDK: Gradio
   • Space hardware: GPU T4 (یا بالاتر - مهم!)

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

دو روش برای آپلود:

روش 1: استفاده از Git

# کلون کردن Space
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME

# کپی کردن تمام فایل‌های این پروژه
# سپس:
git add .
git commit -m "Initial commit: dots.ocr integration"
git push

روش 2: آپلود مستقیم از رابط وب

1. در صفحه Space خود، روی "Files" کلیک کنید
2. فایل‌ها را یکی یکی آپلود کنید:
   • app.py
   • requirements.txt
   • README.md
   • config.py
   • api_example.py
   • .gitignore
   • USAGE_GUIDE.md

3. تنظیمات Space

⚠️ مهم: تنظیم HF Token (ضروری!)

مدل dots.ocr نیاز به احراز هویت دارد:

1. ایجاد Token:

   • به https://huggingface.co/settings/tokens بروید
   • یک توکن با دسترسی Read ایجاد کنید
   • توکن را کپی کنید

2. درخواست دسترسی:

   • به https://huggingface.co/rednote-hilab/DotsOCR بروید
   • روی "Request Access" کلیک کنید (در صورت وجود)
   • منتظر تایید بمانید

3. اضافه کردن Token به Space:

   • Settings → Repository secrets
   • Add a secret:
     • Name: HF_TOKEN
     • Value: توکن کپی شده
   • Save

📖 راهنمای کامل: HF_TOKEN_SETUP.md یا QUICK_FIX_FA.md

فعال‌سازی GPU (ضروری):

1. در صفحه Space، روی "Settings" بروید
2. در بخش "Hardware"، GPU را انتخاب کنید:
   • توصیه: T4 small (رایگان با محدودیت)
   • بهتر: T4 medium یا A10G (نیاز به اشتراک)

تنظیمات اضافی:

• Sleep time: می‌توانید روی "Always running" تنظیم کنید (نیاز به اشتراک)
• Secrets: HF_TOKEN را اضافه کنید (الزامی!)

4. اولین اجرا

پس از آپلود فایل‌ها:

1. Space به صورت خودکار شروع به build می‌کند
2. نصب dependencies حدود 5-10 دقیقه طول می‌کشد
3. دانلود مدل (اولین بار): 10-15 دقیقه
4. بعد از Build موفق، Space آماده است!

5. تست

1. تصویر نمونه‌ای آپلود کنید
2. "Full Layout + OCR" را انتخاب کنید
3. "Process Document" را بزنید
4. منتظر بمانید (اولین درخواست کمی طول می‌کشد)

استفاده از API

بعد از استقرار، می‌توانید از API استفاده کنید:

دریافت URL:

URL Space شما: https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space

مثال Python:

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="",
    api_name="/predict"
)
print(result)

مثال cURL:

# ابتدا فایل را به base64 تبدیل کنید یا URL آن را بدهید
curl -X POST "https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/api/predict" \
  -H "Content-Type: application/json" \
  -d '{
    "data": ["image_url_or_base64", "Full Layout + OCR (English)", ""]
  }'

نکات مهم

هزینه‌ها:

• GPU T4 Small: رایگان با محدودیت زمانی
• GPU های بزرگتر: نیاز به Hugging Face Pro subscription

محدودیت‌ها:

• فضای disk: 50GB (برای Space رایگان)
• RAM: بستگی به نوع GPU
• Timeout: 60 ثانیه (قابل افزایش با subscription)

بهینه‌سازی:

• از @spaces.GPU decorator استفاده شده تا فقط موقع inference از GPU استفاده شود
• مدل یک بار لود می‌شود و در memory نگه داشته می‌شود
• برای استفاده production، GPU دائمی توصیه می‌شود

عیب‌یابی

مشکل: Space build نمی‌شود

• لاگ‌ها را چک کنید
• مطمئن شوید تمام فایل‌ها به درستی آپلود شده‌اند
• requirements.txt را چک کنید

مشکل: Out of Memory

• GPU بزرگتری انتخاب کنید
• سایز تصویر ورودی را محدود کنید

مشکل: مدل لود نمی‌شود

• مطمئن شوید GPU فعال است
• به اینترنت Space دسترسی دارد (برای دانلود مدل)
• صبر کنید تا دانلود کامل شود

مشکل: خطای ModuleNotFoundError

• چک کنید که dependency در requirements.txt وجود دارد
• Space را rebuild کنید

مانیتورینگ

در داشبورد Space می‌توانید ببینید:

• تعداد استفاده‌ها
• زمان پاسخگویی
• خطاها و لاگ‌ها
• مصرف منابع

آپدیت مدل

برای آپدیت مدل یا کد:

git pull  # در دایرکتوری Space
# تغییرات را اعمال کنید
git add .
git commit -m "Update model/code"
git push

Space به صورت خودکار rebuild می‌شود.

پشتیبانی

• Hugging Face Forums: https://discuss.huggingface.co/
• Documentation: https://huggingface.co/docs/hub/spaces
• GitHub Issues: https://github.com/rednote-hilab/dots.ocr/issues

---

موفق باشید! 🚀