README.md

# 🤖 Qwen3-14B على ZeroGPU المجاني

## 🎉 أحدث إصدار (مايو 2025) - مجاني 100%!

تطبيق دردشة ذكي يستخدم **Qwen3-14B** - أحدث وأقوى نموذج من Alibaba، يعمل على **Hugging Face ZeroGPU** المجاني تماماً. بدون أي رسوم أو حدود يومية!

## ✨ المميزات الرئيسية

- 💯 **مجاني بالكامل** - ZeroGPU من Hugging Face
- 🧠 **نموذج قوي** - 14 مليار معامل
- 🌍 **دعم عربي ممتاز** - يفهم ويكتب بالعربية
- ⚡ **سريع** - 30-50 token/ثانية
- 🎛️ **خيارات متقدمة** - تحكم كامل في الإخراج
- 💬 **واجهة جميلة** - تصميم عصري وسهل
- 🔄 **ذاكرة محادثة** - يتذكر سياق الحديث
- 📱 **متجاوب** - يعمل على الجوال والكمبيوتر

## 🚀 كيف تبدأ؟

### الطريقة 1: استخدم Space مباشرة (الأسهل)
1. اضغط "Use this Space" في الأعلى
2. ابدأ الكتابة فوراً!

### الطريقة 2: انسخ Space لحسابك (للتخصيص)
1. اضغط "⋮" ثم "Duplicate this Space"
2. اختر اسم جديد للـ Space
3. تأكد من تفعيل **ZeroGPU** (مجاني)
4. اضغط "Duplicate Space"
5. انتظر 2-3 دقائق حتى يجهز النموذج
6. استمتع!

### الطريقة 3: التثبيت المحلي (للمطورين)

```bash
# استنساخ المشروع
git clone https://huggingface.co/spaces/sassil/maverick-engineer
cd maverick-engineer

# إنشاء بيئة افتراضية
python -m venv venv
source venv/bin/activate  # على Windows: venv\Scripts\activate

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

# تشغيل التطبيق (يحتاج GPU)
python app.py
```

⚠️ **ملاحظة**: التشغيل المحلي يحتاج GPU قوي (24GB+ VRAM)

## 🎯 الاستخدام

### واجهة الدردشة
1. **اكتب رسالتك** في الصندوق الأسفل
2. **اضغط إرسال** أو Enter
3. **انتظر الرد** (5-15 ثانية)
4. **استمر في المحادثة** - النموذج يتذكر السياق!

### الإعدادات المتقدمة (الشريط الجانبي)

#### 📝 رسالة النظام
- غيّر شخصية المساعد
- مثال: "أنت مهندس كهرباء خبير"
- مثال: "أنت مدرس صبور للمبتدئين"

#### 🎨 التحكم في الإبداع

**Temperature (0.1 - 2.0)**
- `0.1 - 0.3`: ردود دقيقة وموثوقة (للحقائق)
- `0.7 - 0.9`: ردود متوازنة (الافتراضي) ✅
- `1.0 - 2.0`: ردود إبداعية ومتنوعة (للقصص)

**Max Tokens (128 - 4096)**
- عدد الكلمات الأقصى في الرد
- 512: إجابات قصيرة
- 2048: إجابات متوسطة ✅
- 4096: إجابات مفصلة جداً

**Top-p (0.1 - 1.0)**
- يتحكم في تنوع الكلمات
- 0.9: موصى به ✅

**Top-k (1 - 100)**
- عدد الكلمات المحتملة للاختيار
- 50: موصى به ✅

**Repetition Penalty (1.0 - 2.0)**
- يمنع تكرار الكلمات
- 1.1: مثالي ✅

## 💡 أمثلة الاستخدام

### للطلاب والدارسين
```
اشرح لي قانون أوم بطريقة بسيطة مع أمثلة
```

### للمهندسين
```
كيف أصمم دائرة Buck Converter لتحويل 12V إلى 5V بتيار 3A؟
```

### للمبرمجين
```
اكتب لي كود Arduino لقراءة DHT22 وإرسال البيانات عبر WiFi
```

### للمبتدئين في IoT
```
اقترح مشروع إنترنت الأشياء سهل للمنزل
```

### للباحثين
```
ما أحدث تقنيات الأتمتة الصناعية في 2024؟
```

## 🛠️ التخصيص

### تغيير النموذج

في `app.py`، سطر 7:

```python
# للنموذج الكبير (14B) - الافتراضي
MODEL_NAME = "Qwen/Qwen2.5-14B-Instruct"

# أو للنموذج الأسرع (7B)
MODEL_NAME = "Qwen/Qwen2.5-7B-Instruct"

# أو للنموذج الصغير (3B) - أسرع جداً
MODEL_NAME = "Qwen/Qwen2.5-3B-Instruct"
```

### تخصيص رسالة النظام الافتراضية

في `app.py`، سطر 103:

```python
system_message = gr.Textbox(
    value="أنت مساعد ذكي متخصص في [مجالك هنا]",
    # ...
)
```

### تغيير الألوان والتصميم

عدّل CSS في `app.py`، سطر 86-96:

```python
css="""
    .rtl {direction: rtl; text-align: right;}
    .gpu-badge {
        background: linear-gradient(90deg, #ff6b6b 0%, #ee5a6f 100%);
        /* ألوان مخصصة */
    }
"""
```

## 📊 الأداء والمواصفات

| المواصفة | القيمة |
|---------|--------|
| **النموذج** | Qwen2.5-14B-Instruct |
| **المعاملات** | 14.2 مليار |
| **السياق** | 32,768 token |
| **GPU** | Nvidia H200 (ديناميكي) |
| **VRAM** | ~28GB |
| **السرعة** | 30-50 token/ثانية |
| **التكلفة** | 0$ - مجاني! |

## 🔧 المتطلبات التقنية

### للاستخدام على Hugging Face (موصى به)
- ✅ لا شيء! فقط حساب Hugging Face مجاني

### للتشغيل المحلي
- Python 3.10+
- CUDA 12.1+
- GPU: 24GB+ VRAM (مثل RTX 4090, A5000)
- RAM: 32GB+
- تخزين: 30GB+

## 🆘 حل المشاكل الشائعة

### ❓ "Model is loading, please wait"
- **السبب**: النموذج يتحمل لأول مرة
- **الحل**: انتظر 2-3 دقائق

### ❓ "Queue is full"
- **السبب**: عدد مستخدمين كبير
- **الحل**: انتظر قليلاً أو duplicate الـ Space

### ❓ الردود بطيئة
- **السبب**: أوقات الذروة أو Max Tokens عالي
- **الحل**: قلل Max Tokens إلى 1024

### ❓ الردود غير منطقية
- **السبب**: Temperature عالي جداً
- **الحل**: اضبطه على 0.7 أو أقل

### ❓ يكرر نفس الكلمات
- **السبب**: Repetition Penalty منخفض
- **الحل**: ارفعه إلى 1.2 أو 1.3

## 🤝 المساهمة

نرحب بأي مساهمات!

1. Fork المشروع
2. أنشئ branch جديد (`git checkout -b feature/AmazingFeature`)
3. Commit تغييراتك (`git commit -m 'Add AmazingFeature'`)
4. Push للـ branch (`git push origin feature/AmazingFeature`)
5. افتح Pull Request

## 📄 الترخيص

هذا المشروع مرخص تحت **Apache 2.0**

النموذج (Qwen2.5) مرخص من Alibaba Cloud - انظر [صفحة النموذج](https://huggingface.co/Qwen/Qwen2.5-14B-Instruct)

## 🙏 شكر وتقدير

- **Alibaba Qwen Team** - على النموذج الرائع
- **Hugging Face** - على ZeroGPU المجاني
- **Gradio Team** - على المكتبة السهلة
- **المجتمع العربي التقني** - للدعم المستمر

## 📞 التواصل والدعم

- **Issues**: [فتح issue جديد](../../issues)
- **Discussions**: [منتدى المناقشات](../../discussions)
- **التحديثات**: تابع Space للتحديثات

---

<div align="center">

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

⭐ إذا أعجبك المشروع، لا تنسَ النجمة! ⭐

[![GitHub stars](https://img.shields.io/github/stars/yourusername/yourrepo?style=social)](../../stargazers)
[![HF Space](https://img.shields.io/badge/🤗%20Hugging%20Face-Space-blue)](https://huggingface.co/spaces/sassil/maverick-engineer)

</div>

## 🗺️ خارطة الطريق

- [ ] إضافة دعم الصور (Qwen-VL)
- [ ] تحميل وتخزين المحادثات
- [ ] وضع الخبير (Expert Mode)
- [ ] دعم ملفات PDF
- [ ] API للمطورين
- [ ] تطبيق موبايل

---

**آخر تحديث**: أكتوبر 2024 | **الإصدار**: 1.0.0