README.md

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

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

<div align="center">

[![Hugging Face](https://img.shields.io/badge/Hugging%20Face-Spaces-yellow.svg)](https://huggingface.co/spaces)
[![Model](https://img.shields.io/badge/Model-UI--TARS--1.5--7B-blue.svg)](https://huggingface.co/ByteDance-Seed/UI-TARS-1.5-7B)
[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)
[![Speed](https://img.shields.io/badge/Speed-⚡%20Lightning%20Fast-green.svg)]()

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

</div>

---

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

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

- ⚡ **سرعة فائقة**: يستخدم 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](https://huggingface.co/new-space)
2. اختر **Docker** كـ SDK
3. اختر **CPU Basic** (مجاني!)
4. قم برفع الملفات التالية:
   - `app.py`
   - `requirements.txt`
   - `Dockerfile`
   - `action_parser.py`
   - `README.md`
5. انتظر 30 ثانية فقط! 🎉

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

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

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

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

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

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

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

---

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

### أمثلة Python

#### 1. استدعاء بسيط

```python
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. رفع ملف

```python
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

```python
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. الحصول على إحداثيات عنصر

```python
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

```javascript
// مثال باستخدام 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](https://github.com/bytedance/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 (يحدث في أول استخدام)

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

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

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

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

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

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

---

## 📚 مراجع

- [UI-TARS Paper](https://arxiv.org/abs/2501.12326)
- [UI-TARS GitHub](https://github.com/bytedance/UI-TARS)
- [UI-TARS-desktop](https://github.com/bytedance/UI-TARS-desktop)
- [Hugging Face Model](https://huggingface.co/ByteDance-Seed/UI-TARS-1.5-7B)
- [HF Inference API Docs](https://huggingface.co/docs/api-inference)

---

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

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

```python
from PIL import Image

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

### 2. استخدام Cache

```python
import functools
import hashlib

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

### 3. Batch Processing

```python
# معالجة عدة طلبات دفعة واحدة
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](https://huggingface.co/ByteDance-Seed) على النموذج الرائع
- [Qwen2.5-VL](https://huggingface.co/Qwen) على البنية الأساسية
- [Hugging Face](https://huggingface.co) على Inference API المجاني

---

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

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

<div align="center">

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

</div>