# ایج اے آئی کے ابتدائی افراد کے لیے - ورکشاپ

> **پروڈکشن کے لیے تیار ایج اے آئی ایپلیکیشنز بنانے کا عملی راستہ**
>
> مائیکروسافٹ فاؤنڈری لوکل کے ساتھ مقامی اے آئی ڈیپلائمنٹ میں مہارت حاصل کریں، پہلے چیٹ کمپلیشن سے لے کر ملٹی ایجنٹ آرکیسٹریشن تک 6 ترقی پسند سیشنز میں۔

---

## 🎯 تعارف

**ایج اے آئی کے ابتدائی افراد کے لیے ورکشاپ** میں خوش آمدید - یہ آپ کی عملی، ہینڈز آن گائیڈ ہے جو آپ کو مقامی ہارڈویئر پر مکمل طور پر چلنے والی ذہین ایپلیکیشنز بنانے میں مدد فراہم کرتی ہے۔ یہ ورکشاپ نظریاتی ایج اے آئی تصورات کو حقیقی دنیا کی مہارتوں میں تبدیل کرتی ہے، جو مائیکروسافٹ فاؤنڈری لوکل اور اسمال لینگویج ماڈلز (SLMs) کے ذریعے ترقی پسند مشقوں کے ذریعے سکھائی جاتی ہیں۔

### یہ ورکشاپ کیوں؟

**ایج اے آئی کا انقلاب یہاں ہے**

دنیا بھر کی تنظیمیں تین اہم وجوہات کی بنا پر کلاؤڈ پر منحصر اے آئی سے ایج کمپیوٹنگ کی طرف منتقل ہو رہی ہیں:

1. **پرائیویسی اور کمپلائنس** - حساس ڈیٹا کو مقامی طور پر پروسیس کریں بغیر کلاؤڈ پر بھیجنے کے (HIPAA، GDPR، مالیاتی ضوابط)
2. **کارکردگی** - نیٹ ورک لیٹنسی کو ختم کریں (50-500ms مقامی بمقابلہ 500-2000ms کلاؤڈ راؤنڈ ٹرپ)
3. **لاگت کا کنٹرول** - فی ٹوکن API کے اخراجات کو ختم کریں اور کلاؤڈ کے اخراجات کے بغیر اسکیل کریں

**لیکن ایج اے آئی مختلف ہے**

آن پرائمسز اے آئی چلانے کے لیے نئی مہارتوں کی ضرورت ہوتی ہے:
- ماڈل کا انتخاب اور وسائل کی حدود کے لیے آپٹیمائزیشن
- مقامی سروس مینجمنٹ اور ہارڈویئر ایکسیلریشن
- چھوٹے ماڈلز کے لیے پرامپٹ انجینئرنگ
- ایج ڈیوائسز کے لیے پروڈکشن ڈیپلائمنٹ کے پیٹرنز

**یہ ورکشاپ وہ مہارتیں فراہم کرتی ہے**

6 مرکوز سیشنز (~3 گھنٹے کل) میں، آپ "ہیلو ورلڈ" سے پروڈکشن کے لیے تیار ملٹی ایجنٹ سسٹمز کی ڈیپلائمنٹ تک ترقی کریں گے - سب کچھ مقامی طور پر آپ کی مشین پر چل رہا ہوگا۔

---

## 📚 سیکھنے کے مقاصد

اس ورکشاپ کو مکمل کرنے کے بعد، آپ یہ کرنے کے قابل ہوں گے:

### بنیادی مہارتیں
1. **مقامی اے آئی سروسز کو ڈیپلائے اور مینج کریں**
   - مائیکروسافٹ فاؤنڈری لوکل انسٹال اور کنفیگر کریں
   - ایج ڈیپلائمنٹ کے لیے مناسب ماڈلز کا انتخاب کریں
   - ماڈل لائف سائیکل کو مینج کریں (ڈاؤن لوڈ، لوڈ، کیش)
   - وسائل کے استعمال کی نگرانی کریں اور کارکردگی کو بہتر بنائیں

2. **اے آئی سے چلنے والی ایپلیکیشنز بنائیں**
   - مقامی طور پر اوپن اے آئی کے مطابق چیٹ کمپلیشنز نافذ کریں
   - اسمال لینگویج ماڈلز کے لیے مؤثر پرامپٹس ڈیزائن کریں
   - بہتر یوزر ایکسپیرینس کے لیے اسٹریمنگ ریسپانسز کو ہینڈل کریں
   - مقامی ماڈلز کو موجودہ ایپلیکیشنز میں انٹیگریٹ کریں

3. **ریٹریول آگمینٹڈ جنریشن (RAG) سسٹمز بنائیں**
   - ایمبیڈنگز کے ساتھ سیمینٹک سرچ بنائیں
   - ایل ایل ایم ریسپانسز کو ڈومین مخصوص علم میں گراؤنڈ کریں
   - RAG کوالٹی کو انڈسٹری اسٹینڈرڈ میٹرکس کے ساتھ ایویلیوایٹ کریں
   - پروٹوٹائپ سے پروڈکشن تک اسکیل کریں

4. **ماڈل کی کارکردگی کو بہتر بنائیں**
   - اپنے استعمال کے کیس کے لیے متعدد ماڈلز کا بینچ مارک کریں
   - لیٹنسی، تھروپٹ، اور فرسٹ ٹوکن ٹائم کو ماپیں
   - اسپیڈ/کوالٹی ٹریڈ آفز کی بنیاد پر بہترین ماڈلز کا انتخاب کریں
   - حقیقی منظرناموں میں SLM بمقابلہ LLM ٹریڈ آفز کا موازنہ کریں

5. **ملٹی ایجنٹ سسٹمز کو آرکیسٹریٹ کریں**
   - مختلف کاموں کے لیے اسپیشلائزڈ ایجنٹس ڈیزائن کریں
   - ایجنٹ میموری اور کانٹیکسٹ مینجمنٹ نافذ کریں
   - پیچیدہ ورک فلو میں ایجنٹس کو کوآرڈینیٹ کریں
   - متعدد ماڈلز کے درمیان درخواستوں کو ذہانت سے روٹ کریں

6. **پروڈکشن کے لیے تیار حل ڈیپلائے کریں**
   - ایرر ہینڈلنگ اور ری ٹرائی لاجک نافذ کریں
   - ٹوکن کے استعمال اور سسٹم وسائل کی نگرانی کریں
   - ماڈل-ایز-ٹولز پیٹرنز کے ساتھ اسکیل ایبل آرکیٹیکچرز بنائیں
   - ایج سے ہائبرڈ (ایج + کلاؤڈ) تک مائیگریشن کے راستے کی منصوبہ بندی کریں

---

## 🎓 سیکھنے کے نتائج

### آپ کیا بنائیں گے

ورکشاپ کے اختتام تک، آپ نے یہ تخلیق کیا ہوگا:

| سیشن | ڈیلیورایبل | مظاہرہ شدہ مہارتیں |
|------|------------|--------------------|
| **1** | اسٹریمنگ کے ساتھ چیٹ ایپلیکیشن | سروس سیٹ اپ، بنیادی کمپلیشنز، اسٹریمنگ UX |
| **2** | RAG سسٹم کے ساتھ ایویلیوایشن | ایمبیڈنگز، سیمینٹک سرچ، کوالٹی میٹرکس |
| **3** | ملٹی ماڈل بینچ مارک سوٹ | کارکردگی کی پیمائش، ماڈل کا موازنہ |
| **4** | SLM بمقابلہ LLM کمپیریٹر | ٹریڈ آف تجزیہ، آپٹیمائزیشن حکمت عملی |
| **5** | ملٹی ایجنٹ آرکیسٹریٹر | ایجنٹ ڈیزائن، میموری مینجمنٹ، کوآرڈینیشن |
| **6** | ذہین روٹنگ سسٹم | انٹینٹ ڈیٹیکشن، ماڈل کا انتخاب، اسکیل ایبلٹی |

### مہارتوں کا میٹرکس

| مہارت کی سطح | سیشن 1-2 | سیشن 3-4 | سیشن 5-6 |
|--------------|----------|----------|----------|
| **ابتدائی** | ✅ سیٹ اپ اور بنیادی باتیں | ⚠️ چیلنجنگ | ❌ بہت زیادہ مشکل |
| **درمیانی** | ✅ جلدی جائزہ | ✅ بنیادی سیکھنا | ⚠️ اسٹریچ گولز |
| **ماہر** | ✅ آسانی سے مکمل کریں | ✅ بہتری | ✅ پروڈکشن پیٹرنز |

### کیریئر کے لیے تیار مہارتیں

**اس ورکشاپ کے بعد، آپ تیار ہوں گے:**

✅ **پرائیویسی-فرسٹ ایپلیکیشنز بنائیں**
- صحت کی دیکھ بھال کی ایپس جو مقامی طور پر PHI/PII کو ہینڈل کرتی ہیں
- مالیاتی خدمات جو کمپلائنس کی ضروریات کو پورا کرتی ہیں
- حکومتی نظام جو ڈیٹا کی خودمختاری کی ضروریات کو پورا کرتے ہیں

✅ **ایج ماحول کے لیے آپٹیمائز کریں**
- محدود وسائل والے IoT ڈیوائسز
- آف لائن-فرسٹ موبائل ایپلیکیشنز
- کم لیٹنسی والے ریئل ٹائم سسٹمز

✅ **ذہین آرکیٹیکچرز ڈیزائن کریں**
- پیچیدہ ورک فلو کے لیے ملٹی ایجنٹ سسٹمز
- ہائبرڈ ایج-کلاؤڈ ڈیپلائمنٹس
- لاگت کے لحاظ سے آپٹیمائزڈ اے آئی انفراسٹرکچر

✅ **ایج اے آئی اقدامات کی قیادت کریں**
- پروجیکٹس کے لیے ایج اے آئی کی فزیبلٹی کا جائزہ لیں
- مناسب ماڈلز اور فریم ورک کا انتخاب کریں
- اسکیل ایبل مقامی اے آئی حل آرکیٹیکٹ کریں

---

## 🗺️ ورکشاپ کا ڈھانچہ

### سیشن کا جائزہ (6 سیشنز × 30 منٹ = 3 گھنٹے)

| سیشن | موضوع | فوکس | دورانیہ |
|------|-------|------|---------|
| **1** | فاؤنڈری لوکل کے ساتھ شروعات | انسٹال، ویلیڈیٹ، پہلا کمپلیشن | 30 منٹ |
| **2** | RAG کے ساتھ اے آئی حل بنانا | پرامپٹ انجینئرنگ، ایمبیڈنگز، ایویلیوایشن | 30 منٹ |
| **3** | اوپن سورس ماڈلز | ماڈل ڈسکوری، بینچ مارکنگ، انتخاب | 30 منٹ |
| **4** | جدید ماڈلز | SLM بمقابلہ LLM، آپٹیمائزیشن، فریم ورک | 30 منٹ |
| **5** | اے آئی سے چلنے والے ایجنٹس | ایجنٹ ڈیزائن، آرکیسٹریشن، میموری | 30 منٹ |
| **6** | ماڈلز بطور ٹولز | روٹنگ، چیننگ، اسکیلنگ حکمت عملی | 30 منٹ |

---

## 🚀 جلدی شروع کریں

### ضروریات

**سسٹم کی ضروریات:**
- **OS**: ونڈوز 10/11، میک او ایس 11+، یا لینکس (اوبنٹو 20.04+)
- **RAM**: کم از کم 8GB، 16GB+ تجویز کردہ
- **اسٹوریج**: ماڈلز کے لیے 10GB+ خالی جگہ
- **CPU**: جدید پروسیسر AVX2 سپورٹ کے ساتھ
- **GPU** (اختیاری): CUDA-کمپیٹیبل یا Qualcomm NPU ایکسیلریشن کے لیے

**سافٹ ویئر کی ضروریات:**
- **Python 3.8+** ([ڈاؤن لوڈ کریں](https://www.python.org/downloads/))
- **Microsoft Foundry Local** ([انسٹالیشن گائیڈ](../../../Workshop))
- **Git** ([ڈاؤن لوڈ کریں](https://git-scm.com/downloads))
- **Visual Studio Code** (تجویز کردہ) ([ڈاؤن لوڈ کریں](https://code.visualstudio.com/))

### 3 مراحل میں سیٹ اپ

#### 1. فاؤنڈری لوکل انسٹال کریں

**ونڈوز:**
```powershell
winget install Microsoft.FoundryLocal
```

**میک او ایس:**
```bash
brew tap microsoft/foundrylocal
brew install foundrylocal
```

**انسٹالیشن کی تصدیق کریں:**
```bash
foundry --version
foundry service status
```

**یقینی بنائیں کہ Azure AI Foundry Local ایک مقررہ پورٹ کے ساتھ چل رہا ہے**

```bash
# Set FoundryLocal to use port 58123 (default)
foundry service set --port 58123 --show

# Or use a different port
foundry service set --port 58000 --show
```

**تصدیق کریں کہ یہ کام کر رہا ہے:**
```bash
# Check service status
foundry service status

# Test the endpoint
curl http://127.0.0.1:58123/v1/models
```
**دستیاب ماڈلز تلاش کرنا**
اپنے فاؤنڈری لوکل انسٹینس میں دستیاب ماڈلز دیکھنے کے لیے، آپ ماڈلز اینڈ پوائنٹ کو کوئری کر سکتے ہیں:

```bash
# cmd/bash/powershell
foundry model list
```

ویب اینڈ پوائنٹ استعمال کرتے ہوئے 

```bash
# Windows PowerShell
powershell -Command "Invoke-RestMethod -Uri 'http://127.0.0.1:58123/v1/models' -Method Get"

# Or using curl (if available)
curl http://127.0.0.1:58123/v1/models
```

#### 2. ریپوزٹری کلون کریں اور ڈیپینڈنسیز انسٹال کریں

```bash
# Clone repository
git clone https://github.com/microsoft/edgeai-for-beginners.git
cd edgeai-for-beginners/Workshop

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# Windows:
.\.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt
```

#### 3. اپنا پہلا نمونہ چلائیں

```bash
# Start Foundry Local and load a model
foundry model run phi-4-mini

# Run the chat bootstrap sample
cd samples
python -m session01.chat_bootstrap "What is edge AI?"
```

**✅ کامیابی!** آپ کو ایج اے آئی کے بارے میں اسٹریمنگ ریسپانس نظر آنا چاہیے۔

---

## 📦 ورکشاپ کے وسائل

### Python نمونے

ہر تصور کو ظاہر کرنے والے ترقی پسند ہینڈز آن مثالیں:

| سیشن | نمونہ | وضاحت | چلانے کا وقت |
|------|-------|-------|-------------|
| 1 | [`chat_bootstrap.py`](../../../Workshop/samples/session01/chat_bootstrap.py) | بنیادی اور اسٹریمنگ چیٹ | ~30 سیکنڈ |
| 2 | [`rag_pipeline.py`](../../../Workshop/samples/session02/rag_pipeline.py) | ایمبیڈنگز کے ساتھ RAG | ~45 سیکنڈ |
| 2 | [`rag_eval_ragas.py`](../../../Workshop/samples/session02/rag_eval_ragas.py) | RAG کوالٹی ایویلیوایشن | ~60 سیکنڈ |
| 3 | [`benchmark_oss_models.py`](../../../Workshop/samples/session03/benchmark_oss_models.py) | ملٹی ماڈل بینچ مارکنگ | ~2-3 منٹ |
| 4 | [`model_compare.py`](../../../Workshop/samples/session04/model_compare.py) | SLM بمقابلہ LLM موازنہ | ~45 سیکنڈ |
| 5 | [`agents_orchestrator.py`](../../../Workshop/samples/session05/agents_orchestrator.py) | ملٹی ایجنٹ سسٹم | ~60 سیکنڈ |
| 6 | [`models_router.py`](../../../Workshop/samples/session06/models_router.py) | انٹینٹ پر مبنی روٹنگ | ~45 سیکنڈ |
| 6 | [`models_pipeline.py`](../../../Workshop/samples/session06/models_pipeline.py) | ملٹی اسٹیپ پائپ لائن | ~60 سیکنڈ |

### Jupyter نوٹ بکس

وضاحتوں اور بصریات کے ساتھ انٹرایکٹو ایکسپلوریشن:

| سیشن | نوٹ بک | وضاحت | مشکل |
|------|--------|-------|------|
| 1 | [`session01_chat_bootstrap.ipynb`](./notebooks/session01_chat_bootstrap.ipynb) | چیٹ کی بنیادی باتیں اور اسٹریمنگ | ⭐ ابتدائی |
| 2 | [`session02_rag_pipeline.ipynb`](./notebooks/session02_rag_pipeline.ipynb) | RAG سسٹم بنائیں | ⭐⭐ درمیانی |
| 2 | [`session02_rag_eval_ragas.ipynb`](./notebooks/session02_rag_eval_ragas.ipynb) | RAG کوالٹی ایویلیوایٹ کریں | ⭐⭐ درمیانی |
| 3 | [`session03_benchmark_oss_models.ipynb`](./notebooks/session03_benchmark_oss_models.ipynb) | ماڈل بینچ مارکنگ | ⭐⭐ درمیانی |
| 4 | [`session04_model_compare.ipynb`](./notebooks/session04_model_compare.ipynb) | ماڈل کا موازنہ | ⭐⭐ درمیانی |
| 5 | [`session05_agents_orchestrator.ipynb`](./notebooks/session05_agents_orchestrator.ipynb) | ایجنٹ آرکیسٹریشن | ⭐⭐⭐ ماہر |
| 6 | [`session06_models_router.ipynb`](./notebooks/session06_models_router.ipynb) | انٹینٹ روٹنگ | ⭐⭐⭐ ماہر |
| 6 | [`session06_models_pipeline.ipynb`](./notebooks/session06_models_pipeline.ipynb) | پائپ لائن آرکیسٹریشن | ⭐⭐⭐ ماہر |

### دستاویزات

جامع گائیڈز اور حوالہ جات:

| دستاویز | وضاحت | استعمال کب کریں |
|---------|-------|----------------|
| [QUICK_START.md](./QUICK_START.md) | فاسٹ ٹریک سیٹ اپ گائیڈ | شروع سے شروع کرتے وقت |
| [QUICK_REFERENCE.md](./QUICK_REFERENCE.md) | کمانڈ اور API چیٹ شیٹ | فوری جوابات کی ضرورت ہو |
| [FOUNDRY_SDK_QUICKREF.md](./FOUNDRY_SDK_QUICKREF.md) | SDK پیٹرنز اور مثالیں | کوڈ لکھتے وقت |
| [ENV_CONFIGURATION.md](./ENV_CONFIGURATION.md) | ماحولیات متغیر گائیڈ | نمونوں کو کنفیگر کرتے وقت |
| [notebooks/TROUBLESHOOTING.md](./notebooks/TROUBLESHOOTING.md) | عام مسائل اور حل | مسائل کو ڈیبگ کرتے وقت |

---

## 🎓 سیکھنے کے راستے کی سفارشات

### ابتدائی افراد کے لیے (3-4 گھنٹے)
1. ✅ سیشن 1: شروعات (سیٹ اپ اور بنیادی چیٹ پر توجہ دیں)
2. ✅ سیشن 2: RAG کی بنیادی باتیں (ابتدائی طور پر ایویلیوایشن کو چھوڑ دیں)
3. ✅ سیشن 3: سادہ بینچ مارکنگ (صرف 2 ماڈلز)
4. ⏭️ سیشنز 4-6 کو فی الحال چھوڑ دیں
5. 🔄 پہلے ایپلیکیشن بنانے کے بعد سیشنز 4-6 پر واپس آئیں

### درمیانی ڈویلپرز کے لیے (3 گھنٹے)
1. ⚡ سیشن 1: جلدی سیٹ اپ کی تصدیق
2. ✅ سیشن 2: مکمل RAG پائپ لائن ایویلیوایشن کے ساتھ
3. ✅ سیشن 3: مکمل بینچ مارکنگ سوٹ
4. ✅ سیشن 4: ماڈل آپٹیمائزیشن
5. ✅ سیشنز 5-6: آرکیٹیکچر پیٹرنز پر توجہ دیں

### ماہرین کے لیے (2-3 گھنٹے)
1. ⚡ سیشنز 1-3: جلدی جائزہ اور تصدیق
2. ✅ سیشن 4: آپٹیمائزیشن کی گہرائی میں جانا
3. ✅ سیشن 5: ملٹی ایجنٹ آرکیٹیکچر
4. ✅ سیشن 6: پروڈکشن پیٹرنز اور اسکیلنگ
5. 🚀 توسیع: کسٹم روٹنگ لاجک اور ہائبرڈ ڈیپلائمن
| 6 | [Session06-ModelsAsTools](./Session06-ModelsAsTools.md) | روٹنگ، چیننگ، اسکیلنگ کا راستہ Azure تک |

ہر سیشن فائل میں شامل ہے: خلاصہ، سیکھنے کے مقاصد، 30 منٹ کا ڈیمو فلو، اسٹارٹر پروجیکٹ، ویلیڈیشن چیک لسٹ، ٹربل شوٹنگ، اور Foundry Local Python SDK کے آفیشل حوالہ جات۔

### نمونہ اسکرپٹس

ورکشاپ کی ضروریات انسٹال کریں (ونڈوز):

```powershell
cd Workshop
py -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
```

macOS / Linux:

```bash
cd Workshop
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

اگر Foundry Local سروس کو macOS سے مختلف (ونڈوز) مشین یا VM پر چلایا جا رہا ہو، تو اینڈ پوائنٹ ایکسپورٹ کریں:

```bash
export FOUNDRY_LOCAL_ENDPOINT=http://<windows-host>:5273/v1
```

| سیشن | اسکرپٹ(س) | تفصیل |
|---------|-----------|-------------|
| 1 | `samples/session01/chat_bootstrap.py` | بوٹ اسٹریپ سروس اور اسٹریمنگ چیٹ |
| 2 | `samples/session02/rag_pipeline.py` | کم سے کم RAG (ان-میموری ایمبیڈنگز) |
|   | `samples/session02/rag_eval_ragas.py` | RAG کی تشخیص ragas میٹرکس کے ساتھ |
| 3 | `samples/session03/benchmark_oss_models.py` | ملٹی ماڈل لیٹنسی اور تھروپٹ بینچ مارکنگ |
| 4 | `samples/session04/model_compare.py` | SLM بمقابلہ LLM موازنہ (لیٹنسی اور نمونہ آؤٹ پٹ) |
| 5 | `samples/session05/agents_orchestrator.py` | دو ایجنٹ تحقیق → ایڈیٹوریل پائپ لائن |
| 6 | `samples/session06/models_router.py` | ارادے پر مبنی روٹنگ ڈیمو |
|   | `samples/session06/models_pipeline.py` | ملٹی اسٹیپ پلان/ایگزیکیوٹ/ریفائن چین |

### ماحول کے متغیرات (نمونہ جات کے درمیان عام)

| متغیر | مقصد | مثال |
|----------|---------|---------|
| `FOUNDRY_LOCAL_ALIAS` | بنیادی نمونہ جات کے لیے ڈیفالٹ سنگل ماڈل عرف | `phi-4-mini` |
| `SLM_ALIAS` / `LLM_ALIAS` | واضح SLM بمقابلہ بڑے ماڈل کے لیے موازنہ | `phi-4-mini` / `gpt-oss-20b` |
| `BENCH_MODELS` | بینچ مارک کے لیے عرف کی کاما فہرست | `qwen2.5-0.5b,mistral-7b` |
| `BENCH_ROUNDS` | ہر ماڈل کے لیے بینچ مارک دہرانے کی تعداد | `3` |
| `BENCH_PROMPT` | بینچ مارکنگ میں استعمال ہونے والا پرامپٹ | `Explain retrieval augmented generation briefly.` |
| `EMBED_MODEL` | جملہ-ٹرانسفارمرز ایمبیڈنگ ماڈل | `sentence-transformers/all-MiniLM-L6-v2` |
| `RAG_QUESTION` | RAG پائپ لائن کے لیے ٹیسٹ سوال کو اووررائیڈ کریں | `Why use RAG with local inference?` |
| `AGENT_QUESTION` | ایجنٹس پائپ لائن سوال کو اووررائیڈ کریں | `Explain why edge AI matters for compliance.` |
| `AGENT_MODEL_PRIMARY` | تحقیق ایجنٹ کے لیے ماڈل عرف | `phi-4-mini` |
| `AGENT_MODEL_EDITOR` | ایڈیٹر ایجنٹ کے لیے ماڈل عرف (مختلف ہو سکتا ہے) | `gpt-oss-20b` |
| `SHOW_USAGE` | جب `1` ہو، ہر تکمیل پر ٹوکن استعمال پرنٹ کرتا ہے | `1` |
| `RETRY_ON_FAIL` | جب `1` ہو، عارضی چیٹ غلطیوں پر ایک بار دوبارہ کوشش کریں | `1` |
| `RETRY_BACKOFF` | دوبارہ کوشش سے پہلے انتظار کرنے کے سیکنڈز | `1.0` |

اگر کوئی متغیر سیٹ نہ ہو، تو اسکرپٹس معقول ڈیفالٹس پر واپس آ جاتے ہیں۔ سنگل ماڈل ڈیمو کے لیے آپ کو عام طور پر صرف `FOUNDRY_LOCAL_ALIAS` کی ضرورت ہوتی ہے۔

### یوٹیلیٹی ماڈیول

تمام نمونہ جات اب ایک مددگار `samples/workshop_utils.py` شیئر کرتے ہیں جو فراہم کرتا ہے:

* کیشڈ `FoundryLocalManager` + OpenAI کلائنٹ تخلیق
* `chat_once()` مددگار اختیاری دوبارہ کوشش + استعمال پرنٹنگ کے ساتھ
* سادہ ٹوکن استعمال رپورٹنگ (فعال کریں `SHOW_USAGE=1` کے ذریعے)

یہ نقل کو کم کرتا ہے اور مقامی ماڈل آرکیسٹریشن کے لیے بہترین طریقوں کو اجاگر کرتا ہے۔

## اختیاری بہتریاں (کراس-سیشن)

| تھیم | بہتری | سیشنز | ماحول / ٹوگل |
|-------|-------------|----------|--------------|
| تعین | مقررہ درجہ حرارت + مستحکم پرامپٹ سیٹ | 1–6 | `temperature=0`, `top_p=1` سیٹ کریں |
| ٹوکن استعمال کی مرئیت | مستقل لاگت/کارکردگی کی تعلیم | 1–6 | `SHOW_USAGE=1` |
| اسٹریمنگ پہلا ٹوکن | محسوس شدہ لیٹنسی میٹرک | 1,3,4,6 | `BENCH_STREAM=1` (بینچ مارک) |
| دوبارہ کوشش کی لچک | عارضی کولڈ-اسٹارٹ کو ہینڈل کرتا ہے | تمام | `RETRY_ON_FAIL=1` + `RETRY_BACKOFF` |
| ملٹی-ماڈل ایجنٹس | مختلف کردار کی مہارت | 5 | `AGENT_MODEL_PRIMARY`, `AGENT_MODEL_EDITOR` |
| موافقت پذیر روٹنگ | ارادے + لاگت کے اصول | 6 | روٹر کو اسکیلیشن منطق کے ساتھ بڑھائیں |
| ویکٹر میموری | طویل مدتی معنوی یادداشت | 2,5,6 | FAISS/Chroma ایمبیڈنگ انڈیکس کو ضم کریں |
| ٹریس ایکسپورٹ | آڈٹنگ اور تشخیص | 2,5,6 | ہر قدم پر JSON لائنز شامل کریں |
| معیار کے اصول | معیاری ٹریکنگ | 3–6 | ثانوی اسکورنگ پرامپٹس |
| اسموک ٹیسٹ | ورکشاپ سے پہلے کی فوری توثیق | تمام | `python Workshop/tests/smoke.py` |

### تعیناتی فوری آغاز

```powershell
set FOUNDRY_LOCAL_ALIAS=phi-4-mini
set SHOW_USAGE=1
python Workshop\tests\smoke.py
```

متوقع مستحکم ٹوکن گنتی بار بار ایک جیسے ان پٹس پر۔

### RAG تشخیص (سیشن 2)

جواب کی مطابقت، وفاداری، اور سیاق و سباق کی درستگی کو ایک چھوٹے مصنوعی ڈیٹا سیٹ پر حساب کرنے کے لیے `rag_eval_ragas.py` استعمال کریں:

```powershell
cd Workshop/samples
python -m session02.rag_eval_ragas
```

بڑے JSONL سوالات، سیاق و سباق، اور گراؤنڈ ٹروتھ فراہم کر کے توسیع کریں، پھر انہیں Hugging Face `Dataset` میں تبدیل کریں۔

## CLI کمانڈ درستگی ضمیمہ

ورکشاپ جان بوجھ کر صرف موجودہ دستاویزی / مستحکم Foundry Local CLI کمانڈز استعمال کرتی ہے۔

### مستحکم حوالہ کمانڈز

| زمرہ | کمانڈ | مقصد |
|----------|---------|---------|
| کور | `foundry --version` | انسٹال شدہ ورژن دکھائیں |
| سروس | `foundry service start` | مقامی سروس شروع کریں (اگر خودکار نہ ہو) |
| سروس | `foundry service status` | سروس کی حیثیت دکھائیں |
| ماڈلز | `foundry model list` | کیٹلاگ / دستیاب ماڈلز کی فہرست |
| ماڈلز | `foundry model download <alias>` | ماڈل ویٹس کو کیش میں ڈاؤن لوڈ کریں |
| ماڈلز | `foundry model run <alias>` | ایک ماڈل کو مقامی طور پر لانچ کریں؛ ایک شاٹ کے لیے `--prompt` کے ساتھ ملائیں |
| ماڈلز | `foundry model unload <alias>` / `foundry model stop <alias>` | ماڈل کو میموری سے ان لوڈ کریں (اگر سپورٹ ہو) |
| کیش | `foundry cache list` | کیشڈ (ڈاؤن لوڈ شدہ) ماڈلز کی فہرست |

### ایک شاٹ پرامپٹ پیٹرن

ایک پرانی `model chat` سب کمانڈ کے بجائے، استعمال کریں:

```powershell
foundry model run <alias> --prompt "Your question here"
```

یہ ایک واحد پرامپٹ/جواب سائیکل کو انجام دیتا ہے پھر باہر نکلتا ہے۔

### ہٹائے گئے / گریز کیے گئے پیٹرنز

| پرانی / غیر دستاویزی | متبادل / رہنمائی |
|---------------------------|------------------------|
| `foundry model chat <model> "..."` | `foundry model run <model> --prompt "..."` |
| `foundry model list --running` | سادہ `foundry model list` + حالیہ سرگرمی / لاگز استعمال کریں |
| `foundry model list --cached` | `foundry cache list` |
| `foundry model stats <model>` | بینچ مارک Python اسکرپٹ + OS ٹولز (ٹاسک مینیجر / `nvidia-smi`) استعمال کریں |
| `foundry model benchmark ...` | `samples/session03/benchmark_oss_models.py` |

### بینچ مارکنگ اور ٹیلیمیٹری

- لیٹنسی، p95، ٹوکنز/سیکنڈ: `samples/session03/benchmark_oss_models.py`
- پہلا ٹوکن لیٹنسی (اسٹریمنگ): `BENCH_STREAM=1` سیٹ کریں
- وسائل کا استعمال: OS مانیٹرز (ٹاسک مینیجر، ایکٹیویٹی مانیٹر، `nvidia-smi`).

جیسے ہی نئے CLI ٹیلیمیٹری کمانڈز اپ اسٹریم مستحکم ہوں گے، انہیں سیشن مارک ڈاؤنز میں کم سے کم ترمیم کے ساتھ شامل کیا جا سکتا ہے۔

### خودکار لنٹ گارڈ

ایک خودکار لنٹر پرانی CLI پیٹرنز کو مارک ڈاؤن فائلز کے کوڈ بلاکس کے اندر دوبارہ متعارف کرانے سے روکتا ہے:

اسکرپٹ: `Workshop/scripts/lint_markdown_cli.py`

کوڈ فینسز کے اندر پرانی پیٹرنز بلاک کیے جاتے ہیں۔

تجویز کردہ متبادل:
| پرانی | متبادل |
|------------|-------------|
| `foundry model chat <a> "..."` | `foundry model run <a> --prompt "..."` |
| `model list --running` | `model list` |
| `model list --cached` | `cache list` |
| `model stats` | بینچ مارک اسکرپٹ + سسٹم ٹولز |
| `model benchmark` | `samples/session03/benchmark_oss_models.py` |
| `model list --available` | `model list` |

مقامی طور پر چلائیں:
```powershell
python Workshop\scripts\lint_markdown_cli.py --verbose
```

GitHub ایکشن: `.github/workflows/markdown-cli-lint.yml` ہر پش اور PR پر چلتا ہے۔

اختیاری پری-کمیٹ ہک:
```bash
echo "python Workshop/scripts/lint_markdown_cli.py" > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
```

## فوری CLI → SDK مائیگریشن ٹیبل

| کام | CLI ون لائنر | SDK (Python) مساوی | نوٹس |
|------|---------------|-------------------------|-------|
| ایک ماڈل کو ایک بار چلائیں (پرامپٹ) | `foundry model run phi-4-mini --prompt "Hello"` | `manager=FoundryLocalManager("phi-4-mini"); client=OpenAI(base_url=manager.endpoint, api_key=manager.api_key or "not-needed"); client.chat.completions.create(model=manager.get_model_info("phi-4-mini").id, messages=[{"role":"user","content":"Hello"}])` | SDK سروس اور کیشنگ کو خود بخود بوٹ اسٹریپ کرتا ہے |
| ماڈل ڈاؤن لوڈ (کیش) کریں | `foundry model download qwen2.5-0.5b` | `FoundryLocalManager("qwen2.5-0.5b")  # triggers download/load` | مینیجر بہترین ویریئنٹ کو منتخب کرتا ہے اگر عرف متعدد بلڈز پر میپ کرتا ہے |
| کیٹلاگ کی فہرست | `foundry model list` | `# use manager for each alias or maintain known list` | CLI مجموعی ہے؛ SDK فی عرف انسٹینسیشن |
| کیشڈ ماڈلز کی فہرست | `foundry cache list` | `manager.list_cached_models()` | مینیجر انیشیٹ کے بعد (کسی بھی عرف) |
| اینڈ پوائنٹ URL حاصل کریں | (غیر واضح) | `manager.endpoint` | OpenAI-مطابقت پذیر کلائنٹ بنانے کے لیے استعمال ہوتا ہے |
| ایک ماڈل کو گرم کریں | `foundry model run <alias>` پھر پہلا پرامپٹ | `chat_once(alias, messages=[...])` (یوٹیلیٹی) | یوٹیلیٹیز ابتدائی کولڈ لیٹنسی وارم اپ کو ہینڈل کرتی ہیں |
| لیٹنسی کی پیمائش کریں | `python -m session03.benchmark_oss_models` | `import benchmark_oss_models` (یا نیا ایکسپورٹر اسکرپٹ) | مستقل میٹرکس کے لیے اسکرپٹ کو ترجیح دیں |
| ماڈل کو روکیں / ان لوڈ کریں | `foundry model unload <alias>` | (ظاہر نہیں – سروس / پروسیس کو دوبارہ شروع کریں) | ورکشاپ فلو کے لیے عام طور پر ضروری نہیں |
| ٹوکن استعمال حاصل کریں | (آؤٹ پٹ دیکھیں) | `resp.usage.total_tokens` | فراہم کیا گیا اگر بیک اینڈ استعمال آبجیکٹ واپس کرے |

## بینچ مارک مارک ڈاؤن ایکسپورٹ

اسکرپٹ `Workshop/scripts/export_benchmark_markdown.py` استعمال کریں تاکہ تازہ بینچ مارک چلایا جا سکے (اسی منطق جیسے `samples/session03/benchmark_oss_models.py`) اور ایک GitHub-دوستانہ مارک ڈاؤن ٹیبل اور خام JSON جاری کریں۔

### مثال

```powershell
python Workshop\scripts\export_benchmark_markdown.py --models "qwen2.5-0.5b,mistral-7b" --prompt "Explain retrieval augmented generation briefly." --rounds 3 --output benchmark_report.md
```

پیدا شدہ فائلیں:
| فائل | مواد |
|------|----------|
| `benchmark_report.md` | مارک ڈاؤن ٹیبل + تشریحی اشارے |
| `benchmark_report.json` | خام میٹرکس صف (فرق / رجحان ٹریکنگ کے لیے) |

ماحول میں `BENCH_STREAM=1` سیٹ کریں تاکہ پہلے ٹوکن لیٹنسی شامل ہو اگر سپورٹ ہو۔

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**ڈسکلیمر**:  
یہ دستاویز AI ترجمہ سروس [Co-op Translator](https://github.com/Azure/co-op-translator) کا استعمال کرتے ہوئے ترجمہ کی گئی ہے۔ ہم درستگی کے لیے کوشش کرتے ہیں، لیکن براہ کرم آگاہ رہیں کہ خودکار ترجمے میں غلطیاں یا غیر درستیاں ہو سکتی ہیں۔ اصل دستاویز کو اس کی اصل زبان میں مستند ذریعہ سمجھا جانا چاہیے۔ اہم معلومات کے لیے، پیشہ ور انسانی ترجمہ کی سفارش کی جاتی ہے۔ ہم اس ترجمے کے استعمال سے پیدا ہونے والی کسی بھی غلط فہمی یا غلط تشریح کے ذمہ دار نہیں ہیں۔
<!-- CO-OP TRANSLATOR DISCLAIMER END -->