# EdgeAI का लागि शुरुवातकर्ता - कार्यशाला

> **स्थानीय हार्डवेयरमा चल्ने उत्पादन-तयार एज एआई अनुप्रयोगहरू निर्माण गर्नको लागि व्यावहारिक सिकाइ मार्ग**
>
> Microsoft Foundry Local को साथ स्थानीय एआई परिनियोजनमा मास्टर गर्नुहोस्, पहिलो च्याट कम्प्लिशनदेखि बहु-एजेन्ट समन्वयसम्म ६ प्रगतिशील सत्रहरूमा।

---

## 🎯 परिचय

**एज एआईका शुरुवातकर्ताहरूको कार्यशालामा स्वागत छ** - स्थानीय हार्डवेयरमा पूर्ण रूपमा चल्ने बुद्धिमान अनुप्रयोगहरू निर्माण गर्नको लागि तपाईंको व्यावहारिक, हात-मा आधारित मार्गदर्शन। यो कार्यशालाले Microsoft Foundry Local र साना भाषा मोडेलहरू (SLMs) प्रयोग गरेर क्रमिक चुनौतीपूर्ण अभ्यासहरू मार्फत सैद्धान्तिक एज एआई अवधारणाहरूलाई वास्तविक संसारको सीपमा रूपान्तरण गर्दछ।

### किन यो कार्यशाला?

**एज एआई क्रान्ति यहाँ छ**

विश्वभरका संगठनहरू तीन महत्वपूर्ण कारणहरूको लागि क्लाउड-निर्भर एआईबाट एज कम्प्युटिङमा सर्दैछन्:

1. **गोपनीयता र अनुपालन** - संवेदनशील डाटा स्थानीय रूपमा प्रक्रिया गर्नुहोस् क्लाउड ट्रान्समिशन बिना (HIPAA, GDPR, वित्तीय नियमहरू)
2. **प्रदर्शन** - नेटवर्क विलम्बता हटाउनुहोस् (५०-५००ms स्थानीय बनाम ५००-२०००ms क्लाउड राउन्ड-ट्रिप)
3. **खर्च नियन्त्रण** - प्रति-टोकन API लागत हटाउनुहोस् र क्लाउड खर्च बिना स्केल गर्नुहोस्

**तर एज एआई फरक छ**

स्थानीय रूपमा एआई चलाउन नयाँ सीपहरूको आवश्यकता पर्छ:
- स्रोत सीमाहरूको लागि मोडेल चयन र अनुकूलन
- स्थानीय सेवा व्यवस्थापन र हार्डवेयर एक्सेलेरेशन
- साना मोडेलहरूको लागि प्रम्प्ट इन्जिनियरिङ
- एज उपकरणहरूको लागि उत्पादन परिनियोजन ढाँचाहरू

**यो कार्यशालाले ती सीपहरू प्रदान गर्दछ**

६ केन्द्रित सत्रहरू (~३ घण्टा कुल), तपाईं "हेलो वर्ल्ड" बाट उत्पादन-तयार बहु-एजेन्ट प्रणालीहरू परिनियोजन गर्न प्रगति गर्नुहुनेछ - सबै स्थानीय रूपमा तपाईंको मेसिनमा चल्दै।

---

## 📚 सिकाइ उद्देश्यहरू

यो कार्यशाला पूरा गरेर, तपाईं सक्षम हुनुहुनेछ:

### मुख्य दक्षताहरू
1. **स्थानीय एआई सेवाहरू परिनियोजन र व्यवस्थापन गर्नुहोस्**
   - Microsoft Foundry Local स्थापना र कन्फिगर गर्नुहोस्
   - एज परिनियोजनको लागि उपयुक्त मोडेलहरू चयन गर्नुहोस्
   - मोडेल जीवनचक्र व्यवस्थापन गर्नुहोस् (डाउनलोड, लोड, क्यास)
   - स्रोत उपयोगको निगरानी गर्नुहोस् र प्रदर्शन अनुकूलन गर्नुहोस्

2. **एआई-संचालित अनुप्रयोगहरू निर्माण गर्नुहोस्**
   - स्थानीय रूपमा OpenAI-संगत च्याट कम्प्लिशनहरू कार्यान्वयन गर्नुहोस्
   - साना भाषा मोडेलहरूको लागि प्रभावकारी प्रम्प्टहरू डिजाइन गर्नुहोस्
   - राम्रो UX को लागि स्ट्रिमिङ प्रतिक्रियाहरू ह्यान्डल गर्नुहोस्
   - स्थानीय मोडेलहरूलाई विद्यमान अनुप्रयोगहरूमा एकीकृत गर्नुहोस्

3. **RAG (Retrieval Augmented Generation) प्रणालीहरू सिर्जना गर्नुहोस्**
   - एम्बेडिङको साथ सेम्यान्टिक खोज निर्माण गर्नुहोस्
   - LLM प्रतिक्रियाहरूलाई डोमेन-विशिष्ट ज्ञानमा आधार बनाउनुहोस्
   - उद्योग-मानक मेट्रिक्सको साथ RAG गुणस्तर मूल्यांकन गर्नुहोस्
   - प्रोटोटाइपबाट उत्पादनमा स्केल गर्नुहोस्

4. **मोडेल प्रदर्शन अनुकूलन गर्नुहोस्**
   - तपाईंको प्रयोग केसको लागि धेरै मोडेलहरूको बेंचमार्क गर्नुहोस्
   - विलम्बता, थ्रूपुट, र पहिलो-टोकन समय मापन गर्नुहोस्
   - गति/गुणस्तर व्यापार-अफहरूमा आधारित उपयुक्त मोडेलहरू चयन गर्नुहोस्
   - वास्तविक परिदृश्यहरूमा SLM बनाम LLM व्यापार-अफहरूको तुलना गर्नुहोस्

5. **बहु-एजेन्ट प्रणालीहरू समन्वय गर्नुहोस्**
   - विभिन्न कार्यहरूको लागि विशेष एजेन्टहरू डिजाइन गर्नुहोस्
   - एजेन्ट मेमोरी र सन्दर्भ व्यवस्थापन कार्यान्वयन गर्नुहोस्
   - जटिल कार्यप्रवाहहरूमा एजेन्टहरू समन्वय गर्नुहोस्
   - धेरै मोडेलहरूमा अनुरोधहरू बुद्धिमानीपूर्वक रुट गर्नुहोस्

6. **उत्पादन-तयार समाधानहरू परिनियोजन गर्नुहोस्**
   - त्रुटि ह्यान्डलिङ र पुन: प्रयास तर्क कार्यान्वयन गर्नुहोस्
   - टोकन उपयोग र प्रणाली स्रोतहरूको निगरानी गर्नुहोस्
   - मोडेल-को-टूल्स ढाँचाहरूको साथ स्केलेबल आर्किटेक्चरहरू निर्माण गर्नुहोस्
   - एजबाट हाइब्रिड (एज + क्लाउड) मा माइग्रेशन मार्गहरू योजना गर्नुहोस्

---

## 🎓 सिकाइ परिणामहरू

### तपाईंले के निर्माण गर्नुहुनेछ

यो कार्यशाला समाप्त गर्दा, तपाईंले निम्न निर्माण गर्नुभएको हुनेछ:

| सत्र | डेलिभरेबल | प्रदर्शन गरिएको सीपहरू |
|------|------------|-------------------------|
| **१** | स्ट्रिमिङको साथ च्याट अनुप्रयोग | सेवा सेटअप, आधारभूत कम्प्लिशनहरू, स्ट्रिमिङ UX |
| **२** | मूल्यांकनको साथ RAG प्रणाली | एम्बेडिङ, सेम्यान्टिक खोज, गुणस्तर मेट्रिक्स |
| **३** | बहु-मोडेल बेंचमार्क सुइट | प्रदर्शन मापन, मोडेल तुलना |
| **४** | SLM बनाम LLM तुलना | व्यापार-अफ विश्लेषण, अनुकूलन रणनीतिहरू |
| **५** | बहु-एजेन्ट समन्वयकर्ता | एजेन्ट डिजाइन, मेमोरी व्यवस्थापन, समन्वय |
| **६** | बुद्धिमान रुटिङ प्रणाली | उद्देश्य पत्ता लगाउने, मोडेल चयन, स्केलेबिलिटी |

### दक्षता म्याट्रिक्स

| सीप स्तर | सत्र १-२ | सत्र ३-४ | सत्र ५-६ |
|-----------|-----------|-----------|-----------|
| **शुरुवातकर्ता** | ✅ सेटअप र आधारभूत | ⚠️ चुनौतीपूर्ण | ❌ धेरै उन्नत |
| **मध्यम स्तर** | ✅ छिटो समीक्षा | ✅ मुख्य सिकाइ | ⚠️ स्ट्रेच लक्ष्यहरू |
| **उन्नत** | ✅ सजिलै पार गर्नुहोस् | ✅ परिष्करण | ✅ उत्पादन ढाँचाहरू |

### करियर-तयार सीपहरू

**यो कार्यशाला पछि, तपाईं तयार हुनुहुनेछ:**

✅ **गोपनीयता-प्रथम अनुप्रयोगहरू निर्माण गर्नुहोस्**
- PHI/PII स्थानीय रूपमा ह्यान्डल गर्ने स्वास्थ्य सेवा अनुप्रयोगहरू
- अनुपालन आवश्यकताहरूको साथ वित्तीय सेवाहरू
- डाटा सार्वभौमिकता आवश्यकताहरूको साथ सरकारी प्रणालीहरू

✅ **एज वातावरणहरूको लागि अनुकूलन गर्नुहोस्**
- सीमित स्रोतहरू भएका IoT उपकरणहरू
- अफलाइन-प्रथम मोबाइल अनुप्रयोगहरू
- कम-विलम्बता वास्तविक-समय प्रणालीहरू

✅ **बुद्धिमान आर्किटेक्चरहरू डिजाइन गर्नुहोस्**
- जटिल कार्यप्रवाहहरूको लागि बहु-एजेन्ट प्रणालीहरू
- हाइब्रिड एज-क्लाउड परिनियोजनहरू
- लागत-अप्टिमाइज्ड एआई पूर्वाधार

✅ **एज एआई पहलहरू नेतृत्व गर्नुहोस्**
- परियोजनाहरूको लागि एज एआई सम्भाव्यता मूल्यांकन गर्नुहोस्
- उपयुक्त मोडेलहरू र फ्रेमवर्कहरू चयन गर्नुहोस्
- स्केलेबल स्थानीय एआई समाधानहरू आर्किटेक्ट गर्नुहोस्

---

## 🗺️ कार्यशाला संरचना

### सत्र अवलोकन (६ सत्र × ३० मिनेट = ३ घण्टा)

| सत्र | विषय | फोकस | अवधि |
|------|------|-------|-------|
| **१** | Foundry Local को साथ सुरु गर्दै | स्थापना, मान्यकरण, पहिलो कम्प्लिशनहरू | ३० मिनेट |
| **२** | RAG को साथ एआई समाधानहरू निर्माण गर्दै | प्रम्प्ट इन्जिनियरिङ, एम्बेडिङ, मूल्यांकन | ३० मिनेट |
| **३** | ओपन सोर्स मोडेलहरू | मोडेल खोज, बेंचमार्किङ, चयन | ३० मिनेट |
| **४** | अत्याधुनिक मोडेलहरू | SLM बनाम LLM, अनुकूलन, फ्रेमवर्कहरू | ३० मिनेट |
| **५** | एआई-संचालित एजेन्टहरू | एजेन्ट डिजाइन, समन्वय, मेमोरी | ३० मिनेट |
| **६** | टूलको रूपमा मोडेलहरू | रुटिङ, चेनिङ, स्केलिङ रणनीतिहरू | ३० मिनेट |

---

## 🚀 छिटो सुरु

### पूर्वापेक्षाहरू

**सिस्टम आवश्यकताहरू:**
- **OS**: Windows 10/11, macOS 11+, वा Linux (Ubuntu 20.04+)
- **RAM**: न्यूनतम ८GB, १६GB+ सिफारिस गरिएको
- **स्टोरेज**: मोडेलहरूको लागि १०GB+ खाली ठाउँ
- **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/))

### ३ चरणमा सेटअप

#### १. Foundry Local स्थापना गर्नुहोस्

**Windows:**
```powershell
winget install Microsoft.FoundryLocal
```

**macOS:**
```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
```
**उपलब्ध मोडेलहरू फेला पार्दै**
तपाईंको Foundry Local इन्स्ट्यान्समा उपलब्ध मोडेलहरू हेर्नको लागि, तपाईं मोडेल्स एन्डप्वाइन्ट सोध्न सक्नुहुन्छ:

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

#### २. रिपोजिटरी क्लोन गर्नुहोस् र निर्भरता स्थापना गर्नुहोस्

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

#### ३. तपाईंको पहिलो नमूना चलाउनुहोस्

```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 नमूनाहरू

प्रत्येक अवधारणालाई प्रदर्शन गर्ने प्रगतिशील हात-मा आधारित उदाहरणहरू:

| सत्र | नमूना | विवरण | चलाउने समय |
|------|-------|--------|-------------|
| १ | [`chat_bootstrap.py`](../../../Workshop/samples/session01/chat_bootstrap.py) | आधारभूत र स्ट्रिमिङ च्याट | ~३० सेकेन्ड |
| २ | [`rag_pipeline.py`](../../../Workshop/samples/session02/rag_pipeline.py) | एम्बेडिङको साथ RAG | ~४५ सेकेन्ड |
| २ | [`rag_eval_ragas.py`](../../../Workshop/samples/session02/rag_eval_ragas.py) | RAG गुणस्तर मूल्यांकन | ~६० सेकेन्ड |
| ३ | [`benchmark_oss_models.py`](../../../Workshop/samples/session03/benchmark_oss_models.py) | बहु-मोडेल बेंचमार्किङ | ~२-३ मिनेट |
| ४ | [`model_compare.py`](../../../Workshop/samples/session04/model_compare.py) | SLM बनाम LLM तुलना | ~४५ सेकेन्ड |
| ५ | [`agents_orchestrator.py`](../../../Workshop/samples/session05/agents_orchestrator.py) | बहु-एजेन्ट प्रणाली | ~६० सेकेन्ड |
| ६ | [`models_router.py`](../../../Workshop/samples/session06/models_router.py) | उद्देश्य-आधारित रुटिङ | ~४५ सेकेन्ड |
| ६ | [`models_pipeline.py`](../../../Workshop/samples/session06/models_pipeline.py) | बहु-चरण पाइपलाइन | ~६० सेकेन्ड |

### Jupyter नोटबुकहरू

व्याख्या र दृश्यहरूको साथ अन्तरक्रियात्मक अन्वेषण:

| सत्र | नोटबुक | विवरण | कठिनाई |
|------|--------|--------|---------|
| १ | [`session01_chat_bootstrap.ipynb`](./notebooks/session01_chat_bootstrap.ipynb) | च्याट आधारभूत र स्ट्रिमिङ | ⭐ शुरुवातकर्ता |
| २ | [`session02_rag_pipeline.ipynb`](./notebooks/session02_rag_pipeline.ipynb) | RAG प्रणाली निर्माण गर्नुहोस् | ⭐⭐ मध्यम |
| २ | [`session02_rag_eval_ragas.ipynb`](./notebooks/session02_rag_eval_ragas.ipynb) | RAG गुणस्तर मूल्यांकन गर्नुहोस् | ⭐⭐ मध्यम |
| ३ | [`session03_benchmark_oss_models.ipynb`](./notebooks/session03_benchmark_oss_models.ipynb) | मोडेल बेंचमार्किङ | ⭐⭐ मध्यम |
| ४ | [`session04_model_compare.ipynb`](./notebooks/session04_model_compare.ipynb) | मोडेल तुलना | ⭐⭐ मध्यम |
| ५ | [`session05_agents_orchestrator.ipynb`](./notebooks/session05_agents_orchestrator.ipynb) | एजेन्ट समन्वय | ⭐⭐⭐ उन्नत |
| ६ | [`session06_models_router.ipynb`](./notebooks/session06_models_router.ipynb) | उद्देश्य रुटिङ | ⭐⭐⭐ उन्नत |
| ६ | [`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) | सामान्य समस्याहरू र समाधानहरू | समस्या समाधान गर्दै |

---

## 🎓 सिकाइ मार्ग सिफारिसहरू

### शुरुवातकर्ताहरूको लागि (३-४ घण्टा)
1. ✅ सत्र १: सुरु गर्दै (सेटअप र आधारभूत च्याटमा ध्यान केन्द्रित गर्नुहोस्)
2. ✅ सत्र २: RAG आधारभूत (सुरुमा मूल्यांकन छोड्नुहोस्)
3. ✅ सत्र ३: सरल बेंचमार्किङ (मात्र २ मोडेलहरू)
4. ⏭️ सत्र ४-६ हाललाई छोड्नुहोस्
5. 🔄 पहिलो अनुप्रयोग निर्माण गरेपछि सत्र ४-६ मा फर्कनुहोस्

### मध्यम स्तरका विकासकर्ताहरूको लागि (३ घण्टा)
1. ⚡ सत्र १: छिटो सेटअप मान्यकरण
2. ✅ सत्र २: मूल्यांकनको साथ पूर्ण RAG पाइपलाइन
3. ✅ सत्र ३: पूर्ण बेंचमार्किङ सुइट
4. ✅ सत्र ४: मोडेल अनुकूलन
5. ✅ सत्र ५-६: आर्किटेक्चर ढाँचाहरूमा ध्यान केन्द्रित गर्नुहोस्

### उन्नत अभ्यासकर्ताहरूको लागि (२-३ घण्टा)
1. ⚡ सत्र १-३: छिटो समीक्षा र मान्यकरण
2. ✅ सत्र ४: अनुकूलन गहिरो अध्ययन
3. ✅ सत्र ५: बहु-एजेन्ट आर्किटेक्चर
4. ✅ सत्र ६: उत्पादन ढाँचाहरू र स्केलिङ
5. 🚀 विस्तार गर्नुहोस्: कस्टम रुटिङ तर्क र हाइब्रिड परिनियोजनहरू निर्माण गर्नुहोस्

---

## कार्यशाला सत्र प्याक (केन्द्रित ३०-मिनेट प्रयोगशालाहरू)

यदि तपाईं संक्षिप्त ६-सत्र कार्यशाला ढाँचालाई पछ्याउँदै हुनुहुन्छ भने, यी समर्पित मार्गदर्शनहरू प्रयोग गर्नुहोस् (प्रत्येकले माथिका व्यापक मोड्युल दस्तावेजहरूलाई नक्सा गर्दछ र पूरक बनाउँछ):

| कार्यशाला सत्र | मार्गदर्शन | मुख्य फोकस |
|----------------|------------|-------------|
| १ | [Session01-GettingStartedFoundryLocal](./Session01-GettingStartedFoundryLocal.md) | स्थापना, मान्यकरण, phi & GPT-OSS-20B चलाउनुहोस्, एक्सेलेरेशन |
| २ | [Session02-BuildAISolutionsRAG](./Session02-BuildAISolutionsRAG.md) | प्रम्प्ट इन्जिनियरिङ, RAG ढाँचाहरू, CSV & दस्तावेज ग्राउन्डिङ, माइग्रेशन |
| ३ | [Session03-OpenSourceModels](./Session03-OpenSourceModels.md) | Hugging Face एकीकरण, बेंचमार्किङ
| 6 | [Session06-ModelsAsTools](./Session06-ModelsAsTools.md) | Azureमा राउटिङ, चेनिङ, स्केलिङको बाटो |

प्रत्येक सेसन फाइलमा समावेश छ: सारांश, सिकाइ उद्देश्यहरू, ३०-मिनेटको डेमो फ्लो, स्टार्ट प्रोजेक्ट, भ्यालिडेसन चेकलिस्ट, समस्या समाधान, र आधिकारिक Foundry Local Python SDKको सन्दर्भहरू।

### नमूना स्क्रिप्टहरू

वर्कशप निर्भरता स्थापना गर्नुहोस् (Windows):

```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बाट फरक (Windows) मेसिन वा 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 मूल्याङ्कन रागास मेट्रिक्ससँग |
| 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` प्रयोग गर्छन् जसले प्रदान गर्दछ:

* Cached `FoundryLocalManager` + OpenAI क्लाइन्ट सिर्जना
* `chat_once()` सहायक वैकल्पिक पुन: प्रयास + प्रयोग प्रिन्टिङको साथ
* सरल टोकन प्रयोग रिपोर्टिङ (सक्षम गर्नुहोस् `SHOW_USAGE=1` मार्फत)

यसले दोहोर्याइ घटाउँछ र स्थानीय मोडेलको कुशल व्यवस्थापनका लागि उत्कृष्ट अभ्यासहरूलाई उजागर गर्दछ।

## वैकल्पिक सुधारहरू (क्रस-सेसन)

| विषय | सुधार | सेसनहरू | Env / टगल |
|------|-------|---------|-----------|
| निर्धारण | स्थिर तापमान + स्थिर प्रम्प्ट सेटहरू | 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 उपकरणहरू (Task Manager / `nvidia-smi`) प्रयोग गर्नुहोस् |
| `foundry model benchmark ...` | `samples/session03/benchmark_oss_models.py` |

### बेंचमार्किङ र टेलिमेट्री

- लेटेंसी, p95, टोकन/सेक: `samples/session03/benchmark_oss_models.py`
- पहिलो-टोकन लेटेंसी (स्ट्रिमिङ): `BENCH_STREAM=1` सेट गर्नुहोस्
- स्रोत प्रयोग: OS मोनिटरहरू (Task Manager, Activity Monitor, `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 Action: `.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 -->