README.md

metadata

title: UI TARS API (Optimized)
emoji: 🚀
colorFrom: indigo
colorTo: blue
sdk: docker
pinned: false

UI-TARS-1.5-7B API Server ⚡ (نسخة محسّنة)

نسخة محسّنة للعمل بسرعة فائقة على Hugging Face Spaces المجاني!

---

🌟 ما الجديد في هذه النسخة؟

✨ التحسينات الرئيسية

• ⚡ سرعة فائقة: يستخدم Hugging Face Inference API بدلاً من تحميل النموذج محلياً
• 💰 مجاني 100%: يعمل على Hugging Face Spaces المجاني بدون GPU
• 🚀 استجابة فورية: لا حاجة لانتظار تحميل النموذج (7+ دقائق)
• 📦 حجم صغير: Docker image أقل من 500 MB (بدلاً من 15+ GB)
• 🔄 إعادة محاولة تلقائية: يتعامل مع حالة تحميل النموذج تلقائياً
• 🌐 API متوافقة 100%: نفس endpoints مع أداء أفضل

📊 المقارنة

الميزة	النسخة القديمة	النسخة الجديدة (محسّنة)
وقت البدء	7-10 دقائق	< 30 ثانية
استهلاك الذاكرة	16+ GB	< 1 GB
يتطلب GPU	✅ نعم	❌ لا
مجاني على HF	❌ لا	✅ نعم
حجم Docker	15+ GB	< 500 MB
سرعة الاستجابة	متوسطة	سريعة جداً

---

🚀 البدء السريع

1️⃣ النشر على Hugging Face Spaces

الطريقة الأسهل (بدون كود):

1. اذهب إلى Hugging Face Spaces
2. اختر Docker كـ SDK
3. اختر CPU Basic (مجاني!)
4. قم برفع الملفات التالية:
   • app.py
   • requirements.txt
   • Dockerfile
   • action_parser.py
   • README.md
5. انتظر 30 ثانية فقط! 🎉

متغيرات البيئة (اختيارية):

# في إعدادات Space الخاص بك، أضف:
HF_TOKEN=hf_xxx...  # فقط للنماذج الخاصة
TEMPERATURE=0.7
TOP_P=0.9
MAX_TOKENS=2048

2️⃣ التشغيل المحلي

# استنساخ المشروع
git clone <your-repo-url>
cd ui-tars-api

# تثبيت المتطلبات
pip install -r requirements.txt

# تشغيل السيرفر
python app.py

السيرفر سيعمل على: http://localhost:7860

---

📖 دليل الاستخدام

أمثلة Python

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['thought']}")
print(f"الإجراء: {result['action']}")
print(f"الإحداثيات: {result['coordinates']}")

2. رفع ملف

with open("screenshot.png", "rb") as f:
    response = requests.post(
        "https://your-space.hf.space/v1/inference/file",
        files={"image": ("screenshot.png", f, "image/png")},
        data={
            "instruction": "اضغط على أيقونة الإعدادات",
            "system_prompt_type": "computer"
        }
    )

print(response.json())

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"])

4. الحصول على إحداثيات عنصر

with open("screenshot.png", "rb") as f:
    response = requests.post(
        "https://your-space.hf.space/v1/grounding",
        files={"image": ("screenshot.png", f, "image/png")},
        data={
            "instruction": "ابحث عن زر الإرسال",
            "image_width": 1920,
            "image_height": 1080
        }
    )

coords = response.json().get("absolute_coordinates")
print(f"الإحداثيات: x={coords['x']}, y={coords['y']}")

استخدام JavaScript/TypeScript

// مثال باستخدام fetch
const response = await fetch("https://your-space.hf.space/v1/inference", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    instruction: "Click the submit button",
    image: imageBase64,
    system_prompt_type: "computer"
  })
});

const result = await response.json();
console.log("Action:", result.action);
console.log("Coordinates:", result.coordinates);

---

🎯 الـ Endpoints المتاحة

Endpoint	الطريقة	الوصف
/	GET	معلومات API
/health	GET	فحص الحالة
/model/info	GET	معلومات النموذج
/v1/inference	POST	استدلال مع base64
/v1/inference/file	POST	استدلال برفع ملف
/v1/chat/completions	POST	متوافق مع OpenAI
/v1/grounding	POST	الحصول على إحداثيات
/v1/batch/inference	POST	معالجة دفعة

التوثيق التفاعلي

بعد تشغيل السيرفر، تفضل بزيارة:

• Swagger UI: https://your-space.hf.space/docs
• ReDoc: https://your-space.hf.space/redoc

---

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

للكمبيوتر (Computer Use)

الإجراء	الوصف	مثال
click	نقرة واحدة	click(start_box='<|box_start|>(500,300)<|box_end|>')
left_double	نقرة مزدوجة	left_double(start_box='...')
right_single	نقرة يمين	right_single(start_box='...')
drag	سحب	drag(start_box='...', end_box='...')
type	كتابة نص	type(content='مرحباً')
hotkey	اختصار لوحة مفاتيح	hotkey(key='ctrl+c')
scroll	تمرير	scroll(start_box='...', direction='down')
wait	انتظار	wait()
finished	انتهى	finished(content='تم')

للجوال (Mobile Use)

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

---

🔧 كيف يعمل؟

البنية التقنية

┌─────────────┐
│   Client    │
│  (Your App) │
└──────┬──────┘
       │ HTTP Request
       ↓
┌─────────────────────┐
│  FastAPI Server     │
│  (Your HF Space)    │
└──────┬──────────────┘
       │ API Call
       ↓
┌──────────────────────────┐
│ HF Inference API         │
│ (ByteDance UI-TARS-1.5)  │
└──────┬───────────────────┘
       │ AI Response
       ↓
┌─────────────────────┐
│  Parsed Action      │
│  + Coordinates      │
└─────────────────────┘

المزايا الرئيسية

1. بدون تحميل النموذج: يستخدم Hugging Face Inference API
2. معالجة ذكية: يحاول تلقائياً 3 مرات إذا كان النموذج يُحمّل
3. تحليل متقدم: يستخرج الأفكار والإجراءات والإحداثيات
4. متوافق 100%: نفس API السابق مع أداء أفضل

---

🔗 التكامل مع UI-TARS-desktop

هذا API متوافق تماماً مع UI-TARS-desktop:

خطوات الإعداد:

1. افتح إعدادات UI-TARS-desktop
2. اضبط VLM Provider على Custom
3. اضبط VLM Base URL على: https://your-space.hf.space/v1
4. اضبط VLM Model Name على: ui-tars-1.5-7b
5. (اختياري) اضبط VLM API Key إذا كان Space خاص

---

🐛 استكشاف الأخطاء

المشكلة: "Model is loading"

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

الحل:

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

المشكلة: "API not available"

الحل:

# تحقق من حالة API
response = requests.get("https://your-space.hf.space/health")
print(response.json())

المشكلة: "Rate limited"

السبب: طلبات كثيرة جداً

الحل:

# أضف تأخير بين الطلبات
import time
time.sleep(2)  # ثانيتان بين الطلبات

---

📚 مراجع

• UI-TARS Paper
• UI-TARS GitHub
• UI-TARS-desktop
• Hugging Face Model
• HF Inference API Docs

---

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

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

from PIL import Image

# قلل حجم الصورة لسرعة أكبر
img = Image.open("screenshot.png")
img = img.resize((1280, 720))  # بدلاً من 1920x1080

2. استخدام Cache

import functools
import hashlib

@functools.lru_cache(maxsize=100)
def get_action(instruction_hash, image_hash):
    # يحفظ النتائج المتكررة
    pass

3. Batch Processing

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

response = requests.post(
    "https://your-space.hf.space/v1/batch/inference",
    json={"requests": requests_batch}
)

---

🤝 المساهمة

نرحب بالمساهمات! إذا كان لديك اقتراحات أو تحسينات:

1. Fork المشروع
2. أنشئ branch للميزة الجديدة
3. Commit التغييرات
4. Push إلى Branch
5. افتح Pull Request

---

📄 الترخيص

هذا المشروع مرخص بموجب Apache License 2.0

---

🙏 شكر وتقدير

• ByteDance Seed Team على النموذج الرائع
• Qwen2.5-VL على البنية الأساسية
• Hugging Face على Inference API المجاني

---

⭐ إذا أعجبك المشروع

لا تنسَ وضع نجمة ⭐ على GitHub!

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