.

DEPLOYMENT.md

@@ -45,6 +45,29 @@ git push
 
 ### 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" بروید
@@ -55,7 +78,7 @@ git push
 #### تنظیمات اضافی:
 
 - **Sleep time**: می‌توانید روی "Always running" تنظیم کنید (نیاز به اشتراک)
-- **Secrets**: در صورت نیاز به API keys
+- **Secrets**: HF_TOKEN را اضافه کنید (الزامی!)
 
 ### 4. اولین اجرا
 

FIX_SUMMARY.md

@@ -0,0 +1,186 @@
+# 🔧 خلاصه تغییرات برای رفع خطای 401
+
+## ✅ آنچه انجام شد:
+
+### 1. آپدیت `app.py`
+- اضافه شدن پشتیبانی از HF Token
+- استفاده از `huggingface_hub.login()`
+- ارسال token به `from_pretrained()`
+- مدیریت خطا با پیام‌های مفید
+
+### 2. آپدیت `requirements.txt`
+- اضافه شدن `huggingface-hub>=0.20.0`
+
+### 3. ایجاد راهنماها
+- **HF_TOKEN_SETUP.md**: راهنمای کامل انگلیسی
+- **QUICK_FIX_FA.md**: راهنمای سریع فارسی (شما اینجا هستید!)
+- آپدیت **README.md** با اطلاعات Token
+- آپدیت **DEPLOYMENT.md** با مراحل تنظیم Token
+
+---
+
+## 🚀 مراحل حل مشکل (3 قدم ساده):
+
+### قدم 1: ساخت Hugging Face Token
+
+```
+1. برو به: https://huggingface.co/settings/tokens
+2. کلیک: "Create new token"
+3. نام: dots-ocr
+4. نوع: Read
+5. کپی کن توکن را
+```
+
+### قدم 2: درخواست دسترسی به مدل
+
+```
+1. برو به: https://huggingface.co/rednote-hilab/DotsOCR
+2. اگر دکمه "Request Access" دیدی → کلیک کن
+3. صبر کن تا تایید شه (چند دقیقه تا چند ساعت)
+```
+
+### قدم 3: اضافه کردن Token به Space
+
+```
+1. Space خودت در HuggingFace → Settings
+2. پیدا کن: "Repository secrets"
+3. کلیک: "Add a secret"
+4. وارد کن:
+   Name: HF_TOKEN
+   Value: [توکن کپی شده]
+5. کلیک: "Add"
+6. Space خودکار rebuild میشه
+```
+
+---
+
+## 📋 چک‌لیست قبل از استقرار:
+
+- [ ] HF Token ساخته شده
+- [ ] دسترسی به مدل درخواست شده (اگر gated بود)
+- [ ] Token به Secrets اضافه شده (نام دقیق: `HF_TOKEN`)
+- [ ] GPU در Space فعال شده (حداقل T4)
+- [ ] فایل‌های پروژه آپلود شده
+
+---
+
+## 🎯 تست موفقیت:
+
+بعد از rebuild، در لاگ‌های Space باید ببینی:
+
+### ✅ موفق:
+```
+Authenticating with Hugging Face token...
+Loading model and processor...
+Model loaded successfully!
+Running on local URL: http://0.0.0.0:7860
+```
+
+### ❌ ناموفق (همچنان خطا):
+```
+401 Client Error: Unauthorized
+```
+
+**راه حل:**
+- چک کن نام Secret دقیقاً `HF_TOKEN` باشه
+- مطمئن شو توکن صحیح کپی شده
+- ببین دسترسی به مدل تایید شده یا نه
+
+---
+
+## 🔄 مدل‌های جایگزین (اگر dots.ocr کار نکرد):
+
+اگر نتونستی به مدل دسترسی پیدا کنی، می‌تونی از این مدل‌ها استفاده کنی:
+
+### گزینه 1: GOT-OCR 2.0 (توصیه می‌شود)
+```python
+# در app.py خط 12:
+MODEL_PATH = "stepfun-ai/GOT-OCR2_0"
+```
+- ✅ Public (نیازی به Token نداره)
+- ✅ OCR قوی
+- ✅ پشتیبانی از چند زبان
+
+### گزینه 2: Qwen2-VL
+```python
+# در app.py خط 12:
+MODEL_PATH = "Qwen/Qwen2-VL-2B-Instruct"
+```
+- ✅ Public
+- ✅ سبک‌تر (2B parameters)
+- ✅ سریع‌تر
+
+### گزینه 3: Nougat (برای اسناد علمی)
+```python
+# در app.py خط 12:
+MODEL_PATH = "facebook/nougat-base"
+```
+- ✅ Public
+- ✅ مخصوص اسناد آکادمیک
+- ✅ فرمول‌های ریاضی
+
+---
+
+## 📁 فایل‌های مهم:
+
+| فایل | توضیح |
+|------|-------|
+| `app.py` | ✅ آپدیت شده (پشتیبانی از Token) |
+| `requirements.txt` | ✅ آپدیت شده (huggingface-hub اضافه شد) |
+| `README.md` | ✅ آپدیت شده (راهنمای Token) |
+| `HF_TOKEN_SETUP.md` | 🆕 راهنمای کامل Token |
+| `QUICK_FIX_FA.md` | 🆕 راهنمای سریع فارسی |
+| `DEPLOYMENT.md` | ✅ آپدیت شده |
+
+---
+
+## 💡 نکات مهم:
+
+1. **امنیت Token**:
+   - ❌ هرگز توکن رو در کد commit نکن
+   - ✅ فقط از Secrets استفاده کن
+   - ✅ توکن رو با کسی شریک نشو
+
+2. **نام Secret**:
+   - حتماً `HF_TOKEN` باشه (دقیقاً همینطور)
+   - حساس به حروف بزرگ/کوچکه!
+
+3. **GPU**:
+   - حتماً GPU رو فعال کن
+   - بدون GPU مدل لود نمیشه
+
+4. **اولین بار**:
+   - دانلود مدل 10-15 دقیقه طول میکشه
+   - صبور باش!
+
+---
+
+## 🆘 کمک بیشتر:
+
+### مستندات:
+- `QUICK_FIX_FA.md` - راهنمای سریع فارسی ⭐
+- `HF_TOKEN_SETUP.md` - راهنمای کامل انگلیسی
+- `DEPLOYMENT.md` - راهنمای استقرار
+- `USAGE_GUIDE.md` - راهنمای استفاده
+
+### لینک‌های مفید:
+- HF Tokens: https://huggingface.co/settings/tokens
+- مدل dots.ocr: https://huggingface.co/rednote-hilab/DotsOCR
+- مستندات: https://huggingface.co/docs/hub/security-tokens
+
+### پشتیبانی:
+- GitHub: https://github.com/rednote-hilab/dots.ocr/issues
+- HF Forums: https://discuss.huggingface.co/
+
+---
+
+## ✨ آماده‌ای!
+
+همه چیز آماده شده. فقط:
+1. Token بساز
+2. دسترسی بگیر
+3. به Space اضافه کن
+4. منتظر rebuild باش
+
+**موفق باشی! 🚀**
+

HF_TOKEN_SETUP.md

@@ -0,0 +1,121 @@
+# راهنمای تنظیم Hugging Face Token
+
+## مشکل: 401 Unauthorized Error
+
+مدل `dots.ocr` یک **gated model** است و برای استفاده از آن نیاز به احراز هویت دارید.
+
+## راه حل: تنظیم HF Token در Space
+
+### مرحله 1: ایجاد Hugging Face Token
+
+1. به https://huggingface.co/settings/tokens بروید
+2. روی **"Create new token"** کلیک کنید
+3. اطلاعات را پر کنید:
+   - **Name**: `dots-ocr-space` (یا نام دلخواه)
+   - **Type**: **Read** (کافی است)
+4. روی **"Generate token"** کلیک کنید
+5. **توکن را کپی کنید** (مهم: فقط یک بار نمایش داده می‌شود!)
+
+### مرحله 2: درخواست دسترسی به مدل (در صورت لزوم)
+
+1. به صفحه مدل بروید: https://huggingface.co/rednote-hilab/DotsOCR
+2. اگر مدل **gated** است، روی **"Request Access"** کلیک کنید
+3. فرم را پر کنید و ارسال کنید
+4. منتظر تایید بمانید (معمولاً چند دقیقه تا چند ساعت)
+
+### مرحله 3: اضافه کردن Token به Space
+
+#### روش 1: استفاده از Secrets (توصیه می‌شود)
+
+1. به Space خود در Hugging Face بروید
+2. روی **"Settings"** کلیک کنید
+3. پایین بروید تا بخش **"Repository secrets"**
+4. روی **"Add a secret"** کلیک کنید
+5. اطلاعات را وارد کنید:
+   - **Name**: `HF_TOKEN`
+   - **Value**: توکنی که در مرحله 1 کپی کردید
+6. روی **"Add"** کلیک کنید
+
+#### روش 2: استفاده از Environment Variable (در صورت نیاز)
+
+اگر روش 1 کار نکرد، می‌توانید مستقیماً در کد تنظیم کنید (توصیه نمی‌شود):
+
+```python
+import os
+os.environ["HF_TOKEN"] = "hf_xxxxxxxxxxxxxxxxxxxx"
+```
+
+⚠️ **هشدار**: توکن خود را هرگز به صورت عمومی commit نکنید!
+
+### مرحله 4: راه‌اندازی مجدد Space
+
+1. بعد از اضافه کردن Secret، Space به صورت خودکار rebuild می‌شود
+2. یا می‌توانید به صورت دستی restart کنید:
+   - Settings → Factory Rebuild
+
+### مرحله 5: تست
+
+1. منتظر بمانید تا Space build شود
+2. تصویری آپلود کنید و تست کنید
+3. اگر موفق بود، مدل باید بدون خطا لود شود! ✅
+
+## عیب‌یابی
+
+### خطا: 401 Unauthorized همچنان وجود دارد
+
+**راه حل:**
+- مطمئن شوید که نام secret دقیقاً `HF_TOKEN` است (حساس به حروف بزرگ/کوچک)
+- بررسی کنید که توکن صحیح است
+- مطمئن شوید که دسترسی به مدل را درخواست کرده‌اید و تایید شده است
+
+### خطا: Token has expired
+
+**راه حل:**
+- یک توکن جدید ایجاد کنید
+- توکن قدیمی را در Secrets با توکن جدید جایگزین کنید
+
+### خطا: Repository Not Found
+
+**راه حل:**
+- بررسی کنید که نام مدل صحیح است
+- مطمئن شوید که از مدل درخواست دسترسی کرده‌اید
+
+## نکات امنیتی
+
+1. ❌ **هرگز توکن را در کد commit نکنید**
+2. ✅ همیشه از Secrets استفاده کنید
+3. ✅ توکن‌های قدیمی را حذف کنید
+4. ✅ فقط دسترسی Read برای توکن تنظیم کنید
+
+## مدل‌های جایگزین (در صورتی که دسترسی به dots.ocr ندارید)
+
+اگر نمی‌توانید به مدل `dots.ocr` دسترسی پیدا کنید، می‌توانید از این مدل‌های جایگزین استفاده کنید:
+
+### 1. GOT-OCR 2.0
+```python
+MODEL_PATH = "stepfun-ai/GOT-OCR2_0"
+```
+
+### 2. Qwen2-VL
+```python
+MODEL_PATH = "Qwen/Qwen2-VL-7B-Instruct"
+```
+
+### 3. Nougat (برای اسناد علمی)
+```python
+MODEL_PATH = "facebook/nougat-base"
+```
+
+برای استفاده از مدل‌های جایگزین، فقط `MODEL_PATH` را در `app.py` تغییر دهید.
+
+## پشتیبانی
+
+اگر همچنان مشکل دارید:
+- GitHub Issues: https://github.com/rednote-hilab/dots.ocr/issues
+- Hugging Face Forums: https://discuss.huggingface.co/
+- مستندات HF: https://huggingface.co/docs/hub/security-tokens
+
+---
+
+**موفق باشید! 🚀**
+

QUICK_FIX_FA.md

@@ -0,0 +1,120 @@
+# 🔧 راهنمای سریع رفع خطای 401
+
+## مشکل شما:
+```
+401 Client Error: Unauthorized
+Repository Not Found for url: https://huggingface.co/rednote-hilab/DotsOCR
+```
+
+## دلیل:
+مدل `dots.ocr` یک **gated model** است و نیاز به احراز هویت دارد.
+
+## راه حل (3 قدم):
+
+### قدم 1️⃣: ساخت Token
+
+1. به این لینک بروید:
+   ```
+   https://huggingface.co/settings/tokens
+   ```
+
+2. روی **"Create new token"** کلیک کنید
+
+3. تنظیمات:
+   - نام: `dots-ocr`
+   - نوع: **Read**
+
+4. **کپی کنید** توکن را! (فقط یکبار نمایش می‌شود)
+
+### قدم 2️⃣: درخواست دسترسی به مدل
+
+1. به این لینک بروید:
+   ```
+   https://huggingface.co/rednote-hilab/DotsOCR
+   ```
+
+2. اگر دکمه **"Request Access"** دیدید، روی آن کلیک کنید
+
+3. منتظر تایید بمانید (معمولاً چند دقیقه)
+
+### قدم 3️⃣: اضافه کردن Token به Space
+
+1. به Space خود بروید در Hugging Face
+
+2. **Settings** → **Repository secrets**
+
+3. روی **"Add a secret"** کلیک کنید
+
+4. وارد کنید:
+   ```
+   Name: HF_TOKEN
+   Value: [توکنی که کپی کردید]
+   ```
+
+5. روی **Add** کلیک کنید
+
+6. Space به صورت خودکار **rebuild** می‌شود
+
+## بررسی نتیجه:
+
+✅ بعد از rebuild، اگر پیام زیر را دیدید، موفق شده‌اید:
+```
+Authenticating with Hugging Face token...
+Loading model and processor...
+Model loaded successfully!
+```
+
+❌ اگر همچنان خطا می‌گیرید:
+- نام Secret باید دقیقاً `HF_TOKEN` باشد
+- توکن را درست کپی کرده باشید
+- دسترسی به مدل تایید شده باشد
+
+## تصویر راهنما:
+
+### ساخت Token:
+```
+HuggingFace → Settings → Access Tokens → Create new token
+```
+
+### اضافه کردن Secret:
+```
+Space → Settings → Repository secrets → Add a secret
+Name: HF_TOKEN
+Value: hf_xxxxxxxxxxxxxx
+```
+
+## مشکل دارید؟
+
+### اگر نمی‌توانید به مدل دسترسی پیدا کنید:
+
+می‌توانید از مدل‌های جایگزین استفاده کنید:
+
+#### روش 1: استفاده از GOT-OCR
+در فایل `app.py` خط 12 را تغییر دهید:
+```python
+MODEL_PATH = "stepfun-ai/GOT-OCR2_0"
+```
+
+#### روش 2: استفاده از Qwen2-VL
+```python
+MODEL_PATH = "Qwen/Qwen2-VL-2B-Instruct"
+```
+
+این مدل‌ها public هستند و نیازی به token ندارند!
+
+## نکات مهم:
+
+⚠️ **هرگز توکن را در کد commit نکنید**  
+⚠️ **فقط از Secrets استفاده کنید**  
+⚠️ **توکن را با کسی به اشتراک نگذارید**  
+
+## کمک بیشتر:
+
+- راهنمای کامل: `HF_TOKEN_SETUP.md`
+- راهنمای استقرار: `DEPLOYMENT.md`
+- مستندات: https://huggingface.co/docs/hub/security-tokens
+
+---
+
+**با موفقیت راه‌اندازی کنید! 🚀**
+

README.md

@@ -45,6 +45,28 @@ This Hugging Face Space provides an easy-to-use interface for the [dots.ocr](htt
 - Text
 - Title
 
+## ⚠️ Important: Hugging Face Token Required
+
+The `dots.ocr` model is **gated** and requires authentication. To use this Space:
+
+1. **Get a Hugging Face Token**:
+   - Go to https://huggingface.co/settings/tokens
+   - Create a new token with **Read** access
+   
+2. **Request Access to the Model**:
+   - Visit https://huggingface.co/rednote-hilab/DotsOCR
+   - Click "Request Access" (if gated)
+   - Wait for approval
+
+3. **Add Token to Space**:
+   - Go to your Space → Settings
+   - Add a new Secret:
+     - Name: `HF_TOKEN`
+     - Value: Your HF token
+   - Rebuild the Space
+
+📖 **Full guide**: See `HF_TOKEN_SETUP.md` for detailed instructions
+
 ## Usage
 
 1. **Upload an Image**: Upload a document image (photo, scan, or screenshot)

START_HERE.md

@@ -0,0 +1,67 @@
+# 🚀 شروع از اینجا - راهنمای سریع
+
+## ⚠️ مشکل فعلی شما:
+
+خطای **401 Unauthorized** هنگام لود کردن مدل `dots.ocr`
+
+---
+
+## ✅ راه حل (فقط 3 مرحله):
+
+### 1️⃣ ساخت Token
+
+https://huggingface.co/settings/tokens
+- کلیک: **Create new token**
+- نوع: **Read**
+- **کپی کن** توکن را!
+
+### 2️⃣ درخواست دسترسی
+
+https://huggingface.co/rednote-hilab/DotsOCR
+- اگر دکمه **"Request Access"** دیدی → کلیک کن
+- صبر کن تا تایید شه
+
+### 3️⃣ اضافه کردن به Space
+
+در Space خودت:
+```
+Settings → Repository secrets → Add a secret
+Name: HF_TOKEN
+Value: [توکن کپی شده]
+```
+
+---
+
+## 📖 راهنماهای کامل:
+
+| فایل | برای چی؟ |
+|------|----------|
+| **QUICK_FIX_FA.md** ⭐ | راه حل سریع خطای 401 (فارسی) |
+| **FIX_SUMMARY.md** | خلاصه تغییرات و راه حل |
+| **HF_TOKEN_SETUP.md** | راهنمای کامل Token (انگلیسی) |
+| **DEPLOYMENT.md** | راهنمای استقرار در HF Space |
+| **README.md** | مستندات اصلی |
+
+---
+
+## 🎯 بعد از اضافه کردن Token:
+
+1. Space خودکار rebuild میشه
+2. صبر کن 10-15 دقیقه (اولین بار)
+3. تست کن!
+
+---
+
+## 🔄 اگر کار نکرد:
+
+می‌تونی از مدل‌های public استفاده کنی (بدون Token):
+
+```python
+# در app.py خط 12:
+MODEL_PATH = "stepfun-ai/GOT-OCR2_0"
+```
+
+---
+
+**شروع کن از: QUICK_FIX_FA.md** 👈
+

app.py

@@ -2,15 +2,36 @@ import gradio as gr
 import torch
 import json
 import spaces
+import os
 from PIL import Image
 from transformers import AutoModelForCausalLM, AutoProcessor
 from qwen_vl_utils import process_vision_info
+from huggingface_hub import login
 
 # Model configuration
 MODEL_PATH = "rednote-hilab/DotsOCR"
 
+# Try to login with HF token if available (for gated models)
+HF_TOKEN = os.environ.get("HF_TOKEN", None)
+if HF_TOKEN:
+    print("Authenticating with Hugging Face token...")
+    login(token=HF_TOKEN)
+
 print("Loading model and processor...")
-processor = AutoProcessor.from_pretrained(MODEL_PATH, trust_remote_code=True)
+try:
+    processor = AutoProcessor.from_pretrained(
+        MODEL_PATH, 
+        trust_remote_code=True,
+        token=HF_TOKEN
+    )
+except Exception as e:
+    print(f"Error loading model: {e}")
+    print("\n⚠️ The dots.ocr model may be gated or not publicly available yet.")
+    print("Please check: https://huggingface.co/rednote-hilab/DotsOCR")
+    print("\nAlternatives:")
+    print("1. Request access to the gated model and add HF_TOKEN to Secrets")
+    print("2. Use an alternative OCR model (see README.md)")
+    raise
 
 # Model will be loaded on GPU when decorated function is called
 model = None
@@ -23,7 +44,8 @@ def load_model():
             MODEL_PATH,
             torch_dtype=torch.bfloat16,
             device_map="auto",
-            trust_remote_code=True
+            trust_remote_code=True,
+            token=HF_TOKEN
         )
     return model
 

requirements.txt

@@ -1,6 +1,7 @@
 gradio>=5.0.0
 torch>=2.0.0
 transformers>=4.37.0
+huggingface-hub>=0.20.0
 pillow
 qwen-vl-utils
 accelerate