# शुरुआती लोगों के लिए EdgeAI - कार्यशाला

> **स्थानीय हार्डवेयर पर उत्पादन-तैयार Edge AI एप्लिकेशन बनाने के लिए व्यावहारिक मार्गदर्शन**
>
> Microsoft Foundry Local के साथ स्थानीय AI तैनाती में महारत हासिल करें, पहले चैट कंप्लीशन से लेकर मल्टी-एजेंट ऑर्केस्ट्रेशन तक 6 प्रगतिशील सत्रों में।

---

## 🎯 परिचय

**EdgeAI for Beginners Workshop** में आपका स्वागत है - यह आपके लिए एक व्यावहारिक, हाथों-हाथ मार्गदर्शिका है जो आपको स्थानीय हार्डवेयर पर पूरी तरह से चलने वाले बुद्धिमान एप्लिकेशन बनाने में मदद करती है। यह कार्यशाला Microsoft Foundry Local और Small Language Models (SLMs) का उपयोग करके सैद्धांतिक Edge AI अवधारणाओं को वास्तविक दुनिया के कौशल में बदल देती है।

### यह कार्यशाला क्यों?

**Edge AI क्रांति आ चुकी है**

दुनिया भर में संगठन तीन महत्वपूर्ण कारणों से क्लाउड-निर्भर AI से Edge कंप्यूटिंग की ओर बढ़ रहे हैं:

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

**लेकिन Edge AI अलग है**

स्थानीय स्तर पर AI चलाने के लिए नए कौशल की आवश्यकता होती है:
- संसाधन सीमाओं के लिए मॉडल चयन और अनुकूलन
- स्थानीय सेवा प्रबंधन और हार्डवेयर एक्सेलेरेशन
- छोटे मॉडलों के लिए प्रॉम्प्ट इंजीनियरिंग
- Edge डिवाइसों के लिए उत्पादन तैनाती पैटर्न

**यह कार्यशाला आपको ये कौशल प्रदान करती है**

6 केंद्रित सत्रों (~3 घंटे कुल) में, आप "Hello World" से लेकर उत्पादन-तैयार मल्टी-एजेंट सिस्टम तैनात करने तक प्रगति करेंगे - सब कुछ आपके मशीन पर स्थानीय रूप से चल रहा होगा।

---

## 📚 सीखने के उद्देश्य

इस कार्यशाला को पूरा करके, आप निम्नलिखित करने में सक्षम होंगे:

### मुख्य दक्षताएँ
1. **स्थानीय AI सेवाओं को तैनात और प्रबंधित करें**
   - Microsoft Foundry Local को इंस्टॉल और कॉन्फ़िगर करें
   - Edge तैनाती के लिए उपयुक्त मॉडल का चयन करें
   - मॉडल जीवनचक्र प्रबंधन (डाउनलोड, लोड, कैश)
   - संसाधन उपयोग की निगरानी करें और प्रदर्शन को अनुकूलित करें

2. **AI-संचालित एप्लिकेशन बनाएं**
   - स्थानीय रूप से OpenAI-संगत चैट कंप्लीशन लागू करें
   - Small Language Models के लिए प्रभावी प्रॉम्प्ट डिज़ाइन करें
   - बेहतर UX के लिए स्ट्रीमिंग प्रतिक्रियाओं को संभालें
   - स्थानीय मॉडलों को मौजूदा एप्लिकेशन में एकीकृत करें

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

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

5. **मल्टी-एजेंट सिस्टम का ऑर्केस्ट्रेशन करें**
   - विभिन्न कार्यों के लिए विशेष एजेंट डिज़ाइन करें
   - एजेंट मेमोरी और संदर्भ प्रबंधन लागू करें
   - जटिल वर्कफ़्लो में एजेंटों का समन्वय करें
   - कई मॉडलों में अनुरोधों को बुद्धिमानी से रूट करें

6. **उत्पादन-तैयार समाधान तैनात करें**
   - त्रुटि हैंडलिंग और पुनः प्रयास लॉजिक लागू करें
   - टोकन उपयोग और सिस्टम संसाधनों की निगरानी करें
   - मॉडल-एज़-टूल्स पैटर्न के साथ स्केलेबल आर्किटेक्चर बनाएं
   - Edge से हाइब्रिड (Edge + क्लाउड) तक माइग्रेशन पथ की योजना बनाएं

---

## 🎓 सीखने के परिणाम

### आप क्या बनाएंगे

इस कार्यशाला के अंत तक, आप निम्नलिखित बनाएंगे:

| सत्र | डिलीवरबल | प्रदर्शित कौशल |
|------|-----------|----------------|
| **1** | स्ट्रीमिंग के साथ चैट एप्लिकेशन | सेवा सेटअप, बुनियादी कंप्लीशन, स्ट्रीमिंग UX |
| **2** | मूल्यांकन के साथ RAG सिस्टम | एम्बेडिंग, सेमांटिक सर्च, गुणवत्ता मेट्रिक्स |
| **3** | मल्टी-मॉडल बेंचमार्क सूट | प्रदर्शन मापन, मॉडल तुलना |
| **4** | SLM बनाम LLM तुलनात्मक उपकरण | ट्रेडऑफ विश्लेषण, अनुकूलन रणनीतियाँ |
| **5** | मल्टी-एजेंट ऑर्केस्ट्रेटर | एजेंट डिज़ाइन, मेमोरी प्रबंधन, समन्वय |
| **6** | बुद्धिमान रूटिंग सिस्टम | इरादा पहचान, मॉडल चयन, स्केलेबिलिटी |

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

| कौशल स्तर | सत्र 1-2 | सत्र 3-4 | सत्र 5-6 |
|------------|----------|----------|----------|
| **शुरुआती** | ✅ सेटअप और मूल बातें | ⚠️ चुनौतीपूर्ण | ❌ बहुत उन्नत |
| **मध्यम स्तर** | ✅ त्वरित समीक्षा | ✅ मुख्य सीखना | ⚠️ खिंचाव लक्ष्य |
| **उन्नत** | ✅ आसानी से पूरा करें | ✅ परिष्करण | ✅ उत्पादन पैटर्न |

### करियर-तैयार कौशल

**इस कार्यशाला के बाद, आप तैयार होंगे:**

✅ **गोपनीयता-प्रथम एप्लिकेशन बनाएं**
- स्वास्थ्य सेवा एप्लिकेशन जो स्थानीय रूप से PHI/PII को संभालते हैं
- अनुपालन आवश्यकताओं के साथ वित्तीय सेवाएँ
- डेटा संप्रभुता आवश्यकताओं के साथ सरकारी सिस्टम

✅ **Edge वातावरण के लिए अनुकूलित करें**
- सीमित संसाधनों वाले IoT डिवाइस
- ऑफलाइन-प्रथम मोबाइल एप्लिकेशन
- कम विलंबता वाले रीयल-टाइम सिस्टम

✅ **बुद्धिमान आर्किटेक्चर डिज़ाइन करें**
- जटिल वर्कफ़्लो के लिए मल्टी-एजेंट सिस्टम
- हाइब्रिड Edge-क्लाउड तैनाती
- लागत-अनुकूलित AI इंफ्रास्ट्रक्चर

✅ **Edge AI पहल का नेतृत्व करें**
- परियोजनाओं के लिए Edge AI व्यवहार्यता का मूल्यांकन करें
- उपयुक्त मॉडल और फ्रेमवर्क का चयन करें
- स्केलेबल स्थानीय AI समाधान डिज़ाइन करें

---

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

### सत्र अवलोकन (6 सत्र × 30 मिनट = 3 घंटे)

| सत्र | विषय | फोकस | अवधि |
|------|------|-------|-------|
| **1** | Foundry Local के साथ शुरुआत | इंस्टॉल, सत्यापन, पहला कंप्लीशन | 30 मिनट |
| **2** | RAG के साथ AI समाधान बनाना | प्रॉम्प्ट इंजीनियरिंग, एम्बेडिंग, मूल्यांकन | 30 मिनट |
| **3** | ओपन सोर्स मॉडल | मॉडल खोज, बेंचमार्किंग, चयन | 30 मिनट |
| **4** | अत्याधुनिक मॉडल | SLM बनाम LLM, अनुकूलन, फ्रेमवर्क | 30 मिनट |
| **5** | AI-संचालित एजेंट | एजेंट डिज़ाइन, ऑर्केस्ट्रेशन, मेमोरी | 30 मिनट |
| **6** | मॉडल-एज़-टूल्स | रूटिंग, चेनिंग, स्केलिंग रणनीतियाँ | 30 मिनट |

---

## 🚀 त्वरित शुरुआत

### आवश्यकताएँ

**सिस्टम आवश्यकताएँ:**
- **OS**: Windows 10/11, macOS 11+, या Linux (Ubuntu 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. 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
```

#### 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?"
```

**✅ सफलता!** आपको 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. 🚀 विस्तार: कस्टम रूटिंग लॉजिक और हाइब्रिड तैनाती बनाएं

---

## कार्यशाला सत्र पैक (केंद्रित 30‑मिनट लैब्स)

यदि आप संक्षिप्त 6-सत्र कार्यशाला प्रारूप का पालन कर रहे हैं, तो इन समर्पित गाइडों का उपयोग करें (प्रत्येक व्यापक मॉड्यूल दस्तावेज़ों के साथ मेल खाता है):

| कार्यशाला सत्र | गाइड | मुख्य फोकस |
|----------------|------|------------|
| 1 | [Session01-GettingStartedFoundryLocal](./Session01-GettingStartedFoundryLocal.md) | इंस्टॉल, सत्यापन, phi & GPT-OSS-20B चलाना, एक्सेलेरेशन |
| 2 | [Session02-BuildAISolutionsRAG](./Session02-BuildAISolutionsRAG.md) | प्रॉम्प्ट इंजीनियरिंग, RAG पैटर्न, CSV और दस्तावेज़ ग्राउंडिंग, माइग्रेशन |
| 3 | [Session03-OpenSourceModels](./Session03-OpenSourceModels.md) | Hugging Face इंटीग्रेशन, बेंचमार्किंग, मॉडल चयन |
| 4 | [Session04-CuttingEdgeModels](./Session04-CuttingEdgeModels.md) | SLM बनाम LLM, WebGPU, Chainlit RAG, ONNX एक्सेलेरेशन |
| 5 | [Session05-AIPoweredAgents](./Session05-AIPoweredAgents.md) | एजेंट भूमिकाएँ, मेमोरी, टूल्स, ऑर्केस्ट्रेशन |
| 6 | [Session06-ModelsAsTools](./Session06-ModelsAsTools.md) | रूटिंग, चेनिंग, Azure के लिए स्केलिंग पथ |

प्रत्येक सत्र फ़ाइल में शामिल हैं: सारांश, सीखने के उद्देश्य, 30 मिनट का डेमो फ्लो, स्टार्टर प्रोजेक्ट, सत्यापन चेकलिस्ट, समस्या निवारण, और आधिकारिक 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
```

| सत्र | स्क्रिप्ट(s) | विवरण |
|------|-------------|--------|
| 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` साझा करते हैं जो प्रदान करता है:

* कैश्ड `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 टूल्स (टास्क मैनेजर / `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` | `# प्रत्येक उपनाम के लिए मैनेजर का उपयोग करें या ज्ञात सूची बनाए रखें` | 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 -->