# الجلسة 4: بناء تطبيقات دردشة جاهزة للإنتاج باستخدام Chainlit

## نظرة عامة

تركز هذه الجلسة على بناء تطبيقات دردشة جاهزة للإنتاج باستخدام Chainlit وMicrosoft Foundry Local. ستتعلم كيفية إنشاء واجهات ويب حديثة للمحادثات الذكية، تنفيذ استجابات متدفقة، ونشر تطبيقات دردشة قوية مع معالجة الأخطاء وتصميم تجربة المستخدم بشكل صحيح.

**ما ستقوم ببنائه:**
- **تطبيق دردشة Chainlit**: واجهة ويب حديثة مع استجابات متدفقة
- **عرض WebGPU**: استنتاج داخل المتصفح لتطبيقات تحافظ على الخصوصية  
- **تكامل Open WebUI**: واجهة دردشة احترافية مع Foundry Local
- **أنماط الإنتاج**: معالجة الأخطاء، المراقبة، واستراتيجيات النشر

## أهداف التعلم

- بناء تطبيقات دردشة جاهزة للإنتاج باستخدام Chainlit
- تنفيذ استجابات متدفقة لتحسين تجربة المستخدم
- إتقان أنماط تكامل Foundry Local SDK
- تطبيق معالجة الأخطاء والتدهور التدريجي بشكل صحيح
- نشر وتكوين تطبيقات الدردشة لبيئات مختلفة
- فهم أنماط واجهات الويب الحديثة للذكاء الاصطناعي الحواري

## المتطلبات الأساسية

- **Foundry Local**: مثبت ويعمل ([دليل التثبيت](https://learn.microsoft.com/azure/ai-foundry/foundry-local/))
- **Python**: الإصدار 3.10 أو أحدث مع دعم البيئة الافتراضية
- **النموذج**: تحميل نموذج واحد على الأقل (`foundry model run phi-4-mini`)
- **المتصفح**: متصفح ويب حديث يدعم WebGPU (Chrome/Edge)
- **Docker**: لتكامل Open WebUI (اختياري)

## الجزء 1: فهم تطبيقات الدردشة الحديثة

### نظرة عامة على الهيكلية

```
User Browser ←→ Chainlit UI ←→ Python Backend ←→ Foundry Local ←→ AI Model
      ↓              ↓              ↓              ↓            ↓
   Web UI      Event Handlers   OpenAI Client   HTTP API    Local GPU
```

### التقنيات الرئيسية

**أنماط Foundry Local SDK:**
- `FoundryLocalManager(alias)`: إدارة الخدمة تلقائيًا
- `manager.endpoint` و `manager.api_key`: تفاصيل الاتصال
- `manager.get_model_info(alias).id`: تحديد النموذج

**إطار عمل Chainlit:**
- `@cl.on_chat_start`: بدء جلسات الدردشة
- `@cl.on_message`: معالجة الرسائل الواردة من المستخدم  
- `cl.Message().stream_token()`: بث في الوقت الحقيقي
- إنشاء واجهة المستخدم تلقائيًا وإدارة WebSocket

## الجزء 2: مصفوفة القرار بين المحلي والسحابي

### خصائص الأداء

| الجانب | المحلي (Foundry) | السحابي (Azure OpenAI) |
|--------|------------------|-----------------------|
| **الكمون** | 🚀 50-200ms (بدون شبكة) | ⏱️ 200-2000ms (يعتمد على الشبكة) |
| **الخصوصية** | 🔒 البيانات لا تغادر الجهاز أبدًا | ⚠️ البيانات تُرسل إلى السحابة |
| **التكلفة** | 💰 مجاني بعد شراء الأجهزة | 💸 الدفع لكل رمز |
| **عدم الاتصال بالإنترنت** | ✅ يعمل بدون إنترنت | ❌ يتطلب الإنترنت |
| **حجم النموذج** | ⚠️ محدود بالأجهزة | ✅ الوصول إلى أكبر النماذج |
| **التوسع** | ⚠️ يعتمد على الأجهزة | ✅ توسع غير محدود |

### أنماط الاستراتيجية الهجينة

**الأولوية للمحلي مع التراجع:**
```python
async def hybrid_completion(prompt: str, complexity_threshold: int = 100):
    if len(prompt.split()) < complexity_threshold:
        return await local_completion(prompt)  # Fast, private
    else:
        return await cloud_completion(prompt)   # Complex reasoning
```

**التوجيه بناءً على المهام:**
```python
async def smart_routing(prompt: str, task_type: str):
    routing_rules = {
        "code_generation": "local",     # Privacy-sensitive
        "creative_writing": "cloud",    # Benefits from larger models
        "data_analysis": "local",       # Fast iteration needed
        "research": "cloud"             # Requires broad knowledge
    }
    
    if routing_rules.get(task_type) == "local":
        return await foundry_completion(prompt)
    else:
        return await azure_completion(prompt)
```

## الجزء 3: العينة 04 - تطبيق دردشة Chainlit

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

```cmd
# Navigate to Module08 directory  
cd Module08

# Start your preferred model
foundry model run phi-4-mini

# Run the Chainlit application (avoiding port conflicts)
chainlit run samples\04\app.py -w --port 8080
```

يفتح التطبيق تلقائيًا على `http://localhost:8080` مع واجهة دردشة حديثة.

### التنفيذ الأساسي

تُظهر العينة 04 أنماط جاهزة للإنتاج:

**اكتشاف الخدمة تلقائيًا:**
```python
import chainlit as cl
from openai import OpenAI
from foundry_local import FoundryLocalManager

# Global variables for client and model
client = None
model_name = None

async def initialize_client():
    global client, model_name
    alias = os.environ.get("MODEL", "phi-4-mini")
    
    try:
        # Use FoundryLocalManager for proper service management
        manager = FoundryLocalManager(alias)
        model_info = manager.get_model_info(alias)
        
        client = OpenAI(
            base_url=manager.endpoint,
            api_key=manager.api_key or "not-required"
        )
        model_name = model_info.id if model_info else alias
        return True
    except Exception as e:
        # Fallback to manual configuration
        base_url = os.environ.get("BASE_URL", "http://localhost:51211")
        client = OpenAI(base_url=f"{base_url}/v1", api_key="not-required")
        model_name = alias
        return True
```

**معالج دردشة متدفقة:**
```python
@cl.on_message
async def main(message: cl.Message):
    # Create streaming response
    msg = cl.Message(content="")
    await msg.send()
    
    stream = client.chat.completions.create(
        model=model_name,
        messages=[
            {"role": "system", "content": "You are a helpful AI assistant."},
            {"role": "user", "content": message.content}
        ],
        stream=True
    )
    
    # Stream tokens in real-time
    for chunk in stream:
        if chunk.choices[0].delta.content:
            await msg.stream_token(chunk.choices[0].delta.content)
    
    await msg.update()
```

### خيارات التكوين

**متغيرات البيئة:**

| المتغير | الوصف | الافتراضي | المثال |
|---------|-------|----------|---------|
| `MODEL` | الاسم المستعار للنموذج المستخدم | `phi-4-mini` | `qwen2.5-7b` |
| `BASE_URL` | نقطة نهاية Foundry Local | يتم اكتشافها تلقائيًا | `http://localhost:51211` |
| `API_KEY` | مفتاح API (اختياري للمحلي) | `""` | `your-api-key` |

**الاستخدام المتقدم:**
```cmd
# Use different model
set MODEL=qwen2.5-7b
chainlit run samples\04\app.py -w --port 8080

# Use different ports (avoid 51211 which is used by Foundry Local)
chainlit run samples\04\app.py -w --port 3000
chainlit run samples\04\app.py -w --port 5000
```

## الجزء 4: إنشاء واستخدام دفاتر Jupyter

### نظرة عامة على دعم الدفاتر

تتضمن العينة 04 دفتر Jupyter شامل (`chainlit_app.ipynb`) يوفر:

- **📚 محتوى تعليمي**: مواد تعليمية خطوة بخطوة
- **🔬 استكشاف تفاعلي**: تشغيل وتجربة خلايا الكود
- **📊 عروض مرئية**: رسوم بيانية، مخططات، وعرض النتائج
- **🛠️ أدوات تطوير**: اختبار وتصحيح الأخطاء

### إنشاء دفاتر خاصة بك

#### الخطوة 1: إعداد بيئة Jupyter

```cmd
# Ensure you're in the Module08 directory
cd Module08

# Activate your virtual environment
.venv\Scripts\activate

# Install Jupyter and dependencies
pip install jupyter notebook jupyterlab ipykernel
pip install -r requirements.txt

# Register the kernel for VS Code
python -m ipykernel install --user --name=foundry-local --display-name="Foundry Local"
```

#### الخطوة 2: إنشاء دفتر جديد

**باستخدام VS Code:**
1. افتح VS Code في دليل Module08
2. أنشئ ملفًا جديدًا بامتداد `.ipynb`
3. اختر "Foundry Local" كالنواة عند الطلب
4. ابدأ بإضافة خلايا بمحتواك

**باستخدام Jupyter Lab:**
```cmd
# Start Jupyter Lab
jupyter lab

# Navigate to samples/04/ and create new notebook
# Choose Python 3 kernel
```

### أفضل الممارسات لتنظيم الدفاتر

#### تنظيم الخلايا

```python
# Cell 1: Imports and Setup
import os
import sys
import chainlit as cl
from openai import OpenAI
from foundry_local import FoundryLocalManager

print("✅ Libraries imported successfully")
```

```python
# Cell 2: Configuration and Client Setup
class FoundryClientManager:
    def __init__(self, model_name="phi-4-mini"):
        self.model_name = model_name
        self.client = None
        
    def initialize_client(self):
        # Client initialization logic
        pass

# Initialize and test
client_manager = FoundryClientManager()
result = client_manager.initialize_client()
print(f"Client initialized: {result}")
```

### أمثلة تفاعلية وتمارين

#### التمرين 1: اختبار تكوين العميل

```python
# Test different configuration methods
configurations = [
    {"method": "foundry_sdk", "model": "phi-4-mini"},
    {"method": "manual", "base_url": "http://localhost:51211", "model": "qwen2.5-7b"},
]

for config in configurations:
    print(f"\n🧪 Testing {config['method']} configuration...")
    # Implementation here
    result = test_configuration(config)
    print(f"Result: {'✅ Success' if result['status'] == 'ok' else '❌ Failed'}")
```

#### التمرين 2: محاكاة استجابة متدفقة

```python
import asyncio

async def simulate_streaming_response(text, delay=0.1):
    """Simulate how streaming works in Chainlit."""
    print("🌊 Simulating streaming response...")
    
    for char in text:
        print(char, end='', flush=True)
        await asyncio.sleep(delay)
    
    print("\n✅ Streaming complete!")

# Test the simulation
sample_text = "This is how streaming responses work in Chainlit applications!"
await simulate_streaming_response(sample_text)
```

## الجزء 5: عرض استنتاج WebGPU داخل المتصفح

### نظرة عامة

يتيح WebGPU تشغيل نماذج الذكاء الاصطناعي مباشرة داخل المتصفح لتحقيق أقصى قدر من الخصوصية وتجربة بدون تثبيت. تُظهر هذه العينة تنفيذ ONNX Runtime Web مع WebGPU.

### الخطوة 1: التحقق من دعم WebGPU

**متطلبات المتصفح:**
- Chrome/Edge 113+ مع تمكين WebGPU
- تحقق: `chrome://gpu` → تأكيد حالة "WebGPU"
- تحقق برمجيًا: `if (!('gpu' in navigator)) { /* no WebGPU */ }`

### الخطوة 2: إنشاء عرض WebGPU

إنشاء دليل: `samples/04/webgpu-demo/`

**index.html:**
```html
<!doctype html>
<html>
<head>
    <meta charset="utf-8">
    <title>WebGPU + ONNX Runtime Demo</title>
    <script src="https://cdn.jsdelivr.net/npm/onnxruntime-web/dist/ort.webgpu.min.js"></script>
    <style>
        body { font-family: system-ui, sans-serif; margin: 2rem; }
        pre { background: #f5f5f5; padding: 1rem; overflow: auto; }
        .status { padding: 1rem; background: #e3f2fd; border-radius: 4px; }
    </style>
</head>
<body>
    <h1>🚀 WebGPU + Foundry Local Integration</h1>
    <div id="status" class="status">Initializing...</div>
    <pre id="output"></pre>
    <script type="module" src="./main.js"></script>
</body>
</html>
```

**main.js:**
```javascript
const statusEl = document.getElementById('status');
const outputEl = document.getElementById('output');

function log(msg) {
    outputEl.textContent += `${msg}\n`;
    console.log(msg);
}

(async () => {
    try {
        if (!('gpu' in navigator)) {
            statusEl.textContent = '❌ WebGPU not available';
            return;
        }
        
        statusEl.textContent = '🔍 WebGPU detected. Loading model...';
        
        // Use a small ONNX model for demo
        const modelUrl = 'https://huggingface.co/onnx/models/resolve/main/vision/classification/mnist-12/mnist-12.onnx';
        
        const session = await ort.InferenceSession.create(modelUrl, {
            executionProviders: ['webgpu']
        });
        
        log('✅ ONNX Runtime session created with WebGPU');
        log(`📊 Input names: ${session.inputNames.join(', ')}`);
        log(`📊 Output names: ${session.outputNames.join(', ')}`);
        
        // Create dummy input (MNIST expects 1x1x28x28)
        const inputData = new Float32Array(1 * 1 * 28 * 28).fill(0.1);
        const input = new ort.Tensor('float32', inputData, [1, 1, 28, 28]);
        
        const feeds = {};
        feeds[session.inputNames[0]] = input;
        
        const results = await session.run(feeds);
        const output = results[session.outputNames[0]];
        
        // Find prediction (argmax)
        let maxIdx = 0;
        for (let i = 1; i < output.data.length; i++) {
            if (output.data[i] > output.data[maxIdx]) maxIdx = i;
        }
        
        statusEl.textContent = '✅ WebGPU inference complete!';
        log(`🎯 Predicted class: ${maxIdx}`);
        log(`📈 Confidence scores: [${Array.from(output.data).map(x => x.toFixed(3)).join(', ')}]`);
        
    } catch (error) {
        statusEl.textContent = `❌ Error: ${error.message}`;
        log(`Error: ${error.message}`);
        console.error(error);
    }
})();
```

### الخطوة 3: تشغيل العرض

```cmd
# Create demo directory
mkdir samples\04\webgpu-demo
cd samples\04\webgpu-demo

# Save HTML and JS files, then serve
python -m http.server 5173

# Open browser to http://localhost:5173
```

## الجزء 6: تكامل Open WebUI

### نظرة عامة

يوفر Open WebUI واجهة احترافية مشابهة لـ ChatGPT تتصل بـ Foundry Local عبر API متوافق مع OpenAI.

### الخطوة 1: المتطلبات الأساسية

```cmd
# Verify Foundry Local is running
foundry service status

# Start a model
foundry model run phi-4-mini

# Confirm API endpoint is accessible
curl http://localhost:51211/v1/models
```

### الخطوة 2: إعداد Docker (موصى به)

```cmd
# Pull Open WebUI image
docker pull ghcr.io/open-webui/open-webui:main

# Run with Foundry Local connection
docker run -d --name open-webui -p 3000:8080 ^
  -e OPENAI_API_BASE_URL=http://host.docker.internal:51211/v1 ^
  -e OPENAI_API_KEY=foundry-local-key ^
  -v open-webui-data:/app/backend/data ^
  ghcr.io/open-webui/open-webui:main
```

**ملاحظة:** `host.docker.internal` يسمح لحاويات Docker بالوصول إلى الجهاز المضيف على Windows.

### الخطوة 3: التكوين

1. **فتح المتصفح:** انتقل إلى `http://localhost:3000`
2. **الإعداد الأولي:** إنشاء حساب مسؤول
3. **تكوين النموذج:**
   - الإعدادات → النماذج → OpenAI API  
   - عنوان URL الأساسي: `http://host.docker.internal:51211/v1`
   - مفتاح API: `foundry-local-key` (أي قيمة تعمل)
4. **اختبار الاتصال:** يجب أن تظهر النماذج في القائمة المنسدلة

### استكشاف الأخطاء وإصلاحها

**المشاكل الشائعة:**

1. **رفض الاتصال:**
   ```cmd
   # Check Foundry Local status
   foundry service ps
   netstat -ano | findstr :51211
   ```

2. **عدم ظهور النماذج:**
   - تحقق من تحميل النموذج: `foundry model list`
   - تحقق من استجابة API: `curl http://localhost:51211/v1/models`
   - إعادة تشغيل حاوية Open WebUI

## الجزء 7: اعتبارات نشر الإنتاج

### تكوين البيئة

**إعداد التطوير:**
```cmd
# Development with auto-reload and debugging
chainlit run samples\04\app.py -w --port 8080 --debug
```

**نشر الإنتاج:**
```cmd
# Production mode with optimizations
chainlit run samples\04\app.py --host 0.0.0.0 --port 8080 --no-cache
```

### مشاكل المنافذ الشائعة وحلولها

**منع تعارض منفذ 51211:**
```cmd
# Check what's using Foundry Local port
netstat -ano | findstr :51211

# Use different port for Chainlit
chainlit run samples\04\app.py -w --port 8080
```

### مراقبة الأداء

**تنفيذ فحص الصحة:**
```python
@cl.on_chat_start
async def health_check():
    try:
        # Test model availability
        response = client.chat.completions.create(
            model=model_name,
            messages=[{"role": "user", "content": "test"}],
            max_tokens=1
        )
        return {"status": "healthy", "model": model_name}
    except Exception as e:
        return {"status": "unhealthy", "error": str(e)}
```

## الملخص

غطت الجلسة 4 بناء تطبيقات Chainlit جاهزة للإنتاج للذكاء الاصطناعي الحواري. تعلمت عن:

- ✅ **إطار عمل Chainlit**: واجهة حديثة ودعم البث لتطبيقات الدردشة
- ✅ **تكامل Foundry Local**: استخدام SDK وأنماط التكوين  
- ✅ **استنتاج WebGPU**: ذكاء اصطناعي داخل المتصفح لتحقيق أقصى قدر من الخصوصية
- ✅ **إعداد Open WebUI**: نشر واجهة دردشة احترافية
- ✅ **أنماط الإنتاج**: معالجة الأخطاء، المراقبة، والتوسع

تُظهر العينة 04 أفضل الممارسات لبناء واجهات دردشة قوية تستفيد من نماذج الذكاء الاصطناعي المحلية عبر Microsoft Foundry Local مع توفير تجربة مستخدم ممتازة.

## المراجع

- **[العينة 04: تطبيق Chainlit](samples/04/README.md)**: تطبيق كامل مع الوثائق
- **[دفتر Chainlit التعليمي](samples/04/chainlit_app.ipynb)**: مواد تعليمية تفاعلية
- **[وثائق Foundry Local](https://learn.microsoft.com/azure/ai-foundry/foundry-local/)**: وثائق المنصة الكاملة
- **[وثائق Chainlit](https://docs.chainlit.io/)**: وثائق الإطار الرسمية
- **[دليل تكامل Open WebUI](https://github.com/microsoft/foundry-local/blob/main/docs/tutorials/chat-application-with-open-web-ui.md)**: البرنامج التعليمي الرسمي

---

**إخلاء المسؤولية**:  
تم ترجمة هذا المستند باستخدام خدمة الترجمة بالذكاء الاصطناعي [Co-op Translator](https://github.com/Azure/co-op-translator). بينما نسعى لتحقيق الدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو معلومات غير دقيقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر الرسمي. للحصول على معلومات حاسمة، يُوصى بالاستعانة بترجمة بشرية احترافية. نحن غير مسؤولين عن أي سوء فهم أو تفسيرات خاطئة ناتجة عن استخدام هذه الترجمة.