QUICKSTART_AR.md

دليل الاستخدام السريع ⚡

🎯 ملخص التحسينات

تم تحسين النموذج بالكامل ليعمل على Hugging Face Spaces المجاني بسرعة فائقة!

ما تم تغييره:

• ✅ استخدام Hugging Face Inference API بدلاً من تحميل النموذج
• ✅ تقليل حجم Docker من 15+ GB إلى < 500 MB
• ✅ تقليل وقت البدء من 7+ دقائق إلى < 30 ثانية
• ✅ العمل على CPU بدلاً من GPU المكلف
• ✅ مجاني 100% على Hugging Face Spaces

---

🚀 البدء في 3 خطوات

الخطوة 1: إنشاء Space

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

الخطوة 2: رفع الملفات

ارفع هذه الملفات (اسحبها وأفلتها):

✅ app.py
✅ requirements.txt
✅ Dockerfile
✅ action_parser.py
✅ README.md

الخطوة 3: الاختبار

بعد 30 ثانية، جرّب:

import requests

# استبدل YOUR_SPACE باسم Space الخاص بك
API_URL = "https://YOUR_SPACE.hf.space"

# فحص الصحة
health = requests.get(f"{API_URL}/health").json()
print(health)  # يجب أن ترى: {"status": "healthy"}

🎉 مبروك! API جاهز!

---

💻 أمثلة الاستخدام

مثال 1: نقرة بسيطة

import requests
import base64

# قراءة صورة الشاشة
with open("screenshot.png", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode()

# إرسال طلب
response = requests.post(
    "https://YOUR_SPACE.hf.space/v1/inference",
    json={
        "instruction": "انقر على زر تسجيل الدخول",
        "image": image_b64,
        "system_prompt_type": "computer"
    }
)

result = response.json()
print(f"الإجراء: {result['action']}")
print(f"الإحداثيات: {result['coordinates']}")

مثال 2: استخدام العميل المحسّن

from ui_tars_client import UITarsClient

# إنشاء عميل
client = UITarsClient("https://YOUR_SPACE.hf.space")

# نقرة بسيطة
result = client.click_on("زر البحث", "screenshot.png")
print(f"تم النقر على: {result['coordinates']}")

# البحث عن عنصر
coords = client.find_element("أيقونة الإعدادات", "screenshot.png")
print(f"وُجد في: x={coords['x']}, y={coords['y']}")

# كتابة نص
result = client.type_text("مرحباً", "حقل البحث", "screenshot.png")
print(f"تم الكتابة: {result['action']}")

مثال 3: تنسيق OpenAI

response = requests.post(
    "https://YOUR_SPACE.hf.space/v1/chat/completions",
    json={
        "model": "ui-tars-1.5-7b",
        "messages": [
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": "اضغط على زر الإرسال"},
                    {
                        "type": "image_url",
                        "image_url": {"url": f"data:image/png;base64,{image_b64}"}
                    }
                ]
            }
        ]
    }
)

print(response.json()["choices"][0]["message"]["content"])

---

🔧 حل المشاكل الشائعة

مشكلة: "Model is loading"

السبب: النموذج يُحمّل على خوادم Hugging Face (أول مرة فقط)

الحل:

import time
time.sleep(15)  # انتظر 15 ثانية
# ثم أعد الطلب

أو استخدم العميل المحسّن (يعيد المحاولة تلقائياً):

client = UITarsClient("https://YOUR_SPACE.hf.space")
# يعيد المحاولة تلقائياً إذا كان النموذج يحمّل

مشكلة: "Connection timeout"

الحل:

# زيادة وقت الانتظار
response = requests.post(
    url,
    json=payload,
    timeout=120  # 120 ثانية
)

مشكلة: الصورة كبيرة جداً

الحل: قلل حجم الصورة:

from PIL import Image

img = Image.open("screenshot.png")
img = img.resize((1280, 720))  # تصغير
img.save("screenshot_small.png")

# استخدم الصورة الصغيرة

أو استخدم العميل المحسّن (يحسّن الصورة تلقائياً):

result = client.click_on(
    "زر",
    "screenshot.png",
    optimize_image=True  # تحسين تلقائي
)

---

📚 الملفات المهمة

الملف	الوصف
app.py	السيرفر الرئيسي (محسّن)
requirements.txt	المكتبات المطلوبة (خفيفة)
Dockerfile	إعداد Docker
action_parser.py	محلل الإجراءات
ui_tars_client.py	عميل Python سهل
test_optimized.py	اختبارات شاملة
README.md	توثيق كامل
DEPLOYMENT.md	دليل النشر
COMPARISON.md	مقارنة النسخ

---

🎮 الإجراءات المدعومة

للكمبيوتر:

• click - نقرة واحدة
• left_double - نقرة مزدوجة
• right_single - نقرة يمين
• drag - سحب وإفلات
• type - كتابة نص
• hotkey - اختصارات (Ctrl+C, etc.)
• scroll - تمرير
• wait - انتظار
• finished - انتهى

للجوال:

• long_press - ضغطة طويلة
• open_app - فتح تطبيق
• press_home - زر الرئيسية
• press_back - زر الرجوع

---

🔗 الروابط المفيدة

• التوثيق الكامل: README.md
• دليل النشر: DEPLOYMENT.md
• المقارنة: COMPARISON.md
• النموذج الأصلي: https://huggingface.co/ByteDance-Seed/UI-TARS-1.5-7B
• Hugging Face Spaces: https://huggingface.co/spaces

---

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

1. تحسين الصور

# قلل حجم الصورة
img = Image.open("screenshot.png")
img.thumbnail((1280, 720))

2. إعادة الاستخدام

# أنشئ العميل مرة واحدة
client = UITarsClient("https://YOUR_SPACE.hf.space")

# استخدمه عدة مرات
result1 = client.click_on("زر 1", "screen1.png")
result2 = client.click_on("زر 2", "screen2.png")

3. معالجة دفعات

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

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

---

❓ أسئلة شائعة

س: هل هذا مجاني فعلاً؟ ج: نعم! 100% مجاني على Hugging Face Spaces

س: كم مرة يمكنني استخدامه؟ ج: لا يوجد حد محدد للاستخدام المعقول

س: هل يعمل بدون GPU؟ ج: نعم! يعمل على CPU فقط

س: هل السرعة جيدة؟ ج: نعم! 1-3 ثواني للاستجابة

س: هل متوافق مع UI-TARS-desktop؟ ج: نعم! 100% متوافق

س: ماذا لو توقف النموذج عن العمل؟ ج: العميل المحسّن يعيد المحاولة تلقائياً

---

🎉 الخلاصة

• ✅ سريع جداً (< 30 ثانية للبدء)
• ✅ مجاني 100%
• ✅ سهل الاستخدام
• ✅ موثوق وقوي
• ✅ متوافق مع كل شيء

ابدأ الآن وجرّب! 🚀

---

صُنع بـ ❤️ للمجتمع العربي