DEPLOYMENT.md

دليل النشر السريع 🚀

خطوات النشر على Hugging Face Spaces

الطريقة 1: واجهة الويب (الأسهل)

1. إنشاء Space جديد

   • اذهب إلى: https://huggingface.co/new-space
   • اسم Space: اختر اسماً مثل ui-tars-api-fast
   • SDK: اختر Docker
   • Hardware: اختر CPU basic (مجاني!)
   • اضغط Create Space

2. رفع الملفات قم برفع الملفات التالية (اسحبها وأفلتها):

   ✅ app.py
   ✅ requirements.txt
   ✅ Dockerfile
   ✅ action_parser.py
   ✅ README.md
   ✅ .gitignore (اختياري)
   

3. الانتظار

   • انتظر حوالي 30-60 ثانية
   • سترى "Building..." ثم "Running"
   • عند ظهور "Running" ✅، API جاهز!

4. الاختبار

   # استبدل YOUR_SPACE باسم Space الخاص بك
   curl https://YOUR_SPACE.hf.space/health
   

الطريقة 2: Git (للمطورين)

# 1. استنساخ Space الخاص بك
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE
cd YOUR_SPACE

# 2. نسخ الملفات
cp /path/to/optimized/files/* .

# 3. إرسال التغييرات
git add .
git commit -m "Deploy optimized UI-TARS API"
git push

---

إضافة متغيرات البيئة (اختياري)

في صفحة Space:

1. اذهب إلى Settings (الإعدادات)
2. اذهب إلى Variables and secrets
3. أضف:

# للنماذج الخاصة فقط (اختياري)
HF_TOKEN=hf_xxxxxxxxxxxxx

# إعدادات مخصصة (اختياري)
TEMPERATURE=0.7
TOP_P=0.9
MAX_TOKENS=2048

---

التحقق من النجاح

اختبار سريع:

import requests

# استبدل YOUR_SPACE
API_URL = "https://YOUR_SPACE.hf.space"

# 1. فحص الصحة
health = requests.get(f"{API_URL}/health").json()
print("Health:", health)

# 2. معلومات النموذج
info = requests.get(f"{API_URL}/model/info").json()
print("Model:", info["model_name"])

# 3. اختبار بسيط
response = requests.post(
    f"{API_URL}/v1/inference",
    json={
        "instruction": "Click the start button",
        "system_prompt_type": "computer"
    }
)
print("Action:", response.json()["action"])

النتيجة المتوقعة:

{
  "status": "healthy",
  "api_available": true,
  "model_name": "ByteDance-Seed/UI-TARS-1.5-7B"
}

---

استكشاف المشاكل

مشكلة: "Space build failed"

الحل:

# تحقق من:
1. هل جميع الملفات موجودة؟
2. هل requirements.txt صحيح؟
3. هل Dockerfile صحيح؟

# أعد بناء Space:
git commit --allow-empty -m "Rebuild"
git push

مشكلة: "Model is loading"

الحل:

# هذا طبيعي في أول استخدام
# انتظر 10-20 ثانية وأعد المحاولة
import time
time.sleep(15)
# ثم أعد الطلب

مشكلة: "Out of memory"

الحل:

# هذا لا يجب أن يحدث مع النسخة المحسّنة!
# ولكن إذا حدث:
1. تحقق أنك تستخدم app.py المحسّن (يستخدم HF Inference API)
2. لا تستخدم النسخة القديمة التي تحمّل النموذج محلياً

---

نصائح للأداء الأفضل

1. استخدام CDN (للتطبيقات العامة)

// بدلاً من استدعاء API مباشرة من المتصفح
// استخدم Cloudflare Workers أو Vercel Edge Functions

2. Caching الذكي

# احفظ النتائج المتكررة
cache = {}

def get_action(instruction, image_hash):
    key = f"{instruction}:{image_hash}"
    if key in cache:
        return cache[key]
    
    result = call_api(instruction, image)
    cache[key] = result
    return result

3. Batch Processing

# عالج عدة طلبات دفعة واحدة
requests = [
    {"instruction": "Click button 1", "image": img1},
    {"instruction": "Click button 2", "image": img2}
]

response = requests.post(
    f"{API_URL}/v1/batch/inference",
    json={"requests": requests}
)

---

الخطوات التالية

✅ Space جاهز وشغال ✅ API يستجيب بسرعة ✅ الاختبارات نجحت

الآن يمكنك:

1. دمج مع تطبيقك

   from ui_tars_client import UITarsClient
   
   client = UITarsClient("https://YOUR_SPACE.hf.space")
   result = client.inference("Click login", "screenshot.png")
   

2. استخدام مع UI-TARS-desktop

   • افتح الإعدادات
   • VLM Provider: Custom
   • Base URL: https://YOUR_SPACE.hf.space/v1
   • Model: ui-tars-1.5-7b

3. بناء تطبيقات RPA

   • Automation scripts
   • Web scraping
   • Testing automation
   • Process automation

---

الدعم

إذا واجهت مشاكل:

1. تحقق من Logs في Space
2. اختبر مع test_optimized.py
3. راجع التوثيق الكامل
4. افتح Issue على GitHub

---

مقارنة الأداء

المقياس	قبل التحسين	بعد التحسين
وقت البدء	7-10 دقائق	< 30 ثانية
الذاكرة	16+ GB	< 1 GB
وقت الاستجابة	2-5 ثواني	1-2 ثانية
التكلفة	يتطلب GPU	مجاني 100%
الموثوقية	متوسطة	عالية جداً

---

🎉 مبروك! API الخاص بك جاهز للاستخدام!