USAGE_GUIDE.md

راهنمای استفاده از dots.ocr Space

نصب و راه‌اندازی

1. آپلود به Hugging Face Space

1. فایل‌های پروژه را به یک Hugging Face Space جدید آپلود کنید
2. مطمئن شوید که Space از نوع Gradio است
3. GPU را در تنظیمات Space فعال کنید (توصیه می‌شود: T4 یا بالاتر)

2. استفاده از رابط کاربری

بعد از راه‌اندازی Space:

1. تصویر سند خود را آپلود کنید
2. نوع پرامپت را انتخاب کنید:
   • Full Layout + OCR: تحلیل کامل با bounding box، دسته‌بندی و متن
   • OCR Only: استخراج ساده متن
   • Layout Detection Only: فقط تشخیص چیدمان
   • Custom: پرامپت سفارشی
3. دکمه "Process Document" را بزنید
4. نتیجه را در قالب JSON دریافت کنید

3. استفاده از API

روش Python:

from gradio_client import Client

# آدرس Space خود را وارد کنید
client = Client("YOUR_USERNAME/YOUR_SPACE_NAME")

# پردازش تصویر
result = client.predict(
    image="path/to/your/image.jpg",
    prompt_type="Full Layout + OCR (English)",
    custom_prompt="",
    api_name="/predict"
)

print(result)

استفاده از اسکریپت آماده:

# نصب کتابخانه
pip install gradio_client

# اجرای اسکریپت
python api_example.py \
    --image your_document.jpg \
    --space-url YOUR_SPACE_URL \
    --prompt-type "Full Layout + OCR (English)"

4. استفاده از cURL:

curl -X POST "YOUR_SPACE_URL/api/predict" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {"path": "base64_encoded_image_or_url"},
      "Full Layout + OCR (English)",
      ""
    ]
  }'

فرمت خروجی

Full Layout + OCR:

[
  {
    "bbox": [x1, y1, x2, y2],
    "category": "Text",
    "text": "محتوای متن..."
  },
  {
    "bbox": [x1, y1, x2, y2],
    "category": "Table",
    "text": "<table>...</table>"
  },
  {
    "bbox": [x1, y1, x2, y2],
    "category": "Formula",
    "text": "\\LaTeX{formula}"
  }
]

نکات مهم

1. کیفیت تصویر: برای نتایج بهتر از تصاویر با کیفیت بالا استفاده کنید
2. رزولوشن: حداکثر 11,289,600 پیکسل توصیه می‌شود
3. زبان: مدل از زبان‌های متعدد پشتیبانی می‌کند
4. PDF: فایل‌های PDF با DPI=200 بهترین نتیجه را می‌دهند

عیب‌یابی

خطای Out of Memory:

• سایز تصویر را کاهش دهید
• از GPU بزرگتری استفاده کنید

خروجی نادرست:

• پرامپت دیگری امتحان کنید
• کیفیت تصویر را بهبود دهید

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

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

پشتیبانی

• GitHub: https://github.com/rednote-hilab/dots.ocr
• Hugging Face Model: https://huggingface.co/rednote-hilab/DotsOCR

مثال‌های کاربردی

1. استخراج متن از فاکتور:

result = client.predict(
    image="invoice.jpg",
    prompt_type="Full Layout + OCR (English)",
    custom_prompt=""
)

2. تشخیص فرمول‌های ریاضی:

result = client.predict(
    image="math_document.png",
    prompt_type="Full Layout + OCR (English)",
    custom_prompt=""
)
# فرمول‌ها به فرمت LaTeX استخراج می‌شوند

3. استخراج جداول:

result = client.predict(
    image="table_document.jpg",
    prompt_type="Full Layout + OCR (English)",
    custom_prompt=""
)
# جداول به فرمت HTML استخراج می‌شوند