--- title: UI TARS API (Optimized) emoji: 🚀 colorFrom: indigo colorTo: blue sdk: docker pinned: false --- # UI-TARS-1.5-7B API Server ⚡ (نسخة محسّنة)
[![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 المجاني!**
--- ## 🌟 ما الجديد في هذه النسخة؟ ### ✨ التحسينات الرئيسية - ⚡ **سرعة فائقة**: يستخدم 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 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!
**صُنع بـ ❤️ للمجتمع العربي**