# EdgeAI नवशिक्यांसाठी - कार्यशाळा

> **स्थानीय हार्डवेअरवर उत्पादन-तयार Edge AI अनुप्रयोग तयार करण्यासाठी हाताळण्यायोग्य शिक्षण मार्ग**
>
> Microsoft Foundry Local च्या मदतीने, पहिल्या चॅट पूर्णतेपासून मल्टी-एजंट ऑर्केस्ट्रेशनपर्यंत 6 प्रगत सत्रांमध्ये स्थानिक AI तैनातीमध्ये प्रावीण्य मिळवा.

---

## 🎯 परिचय

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

### ही कार्यशाळा का?

**Edge AI क्रांती सुरू झाली आहे**

जगभरातील संस्था तीन महत्त्वाच्या कारणांसाठी क्लाउड-आधारित AI वरून Edge Computing कडे वळत आहेत:

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 + Cloud) प्रवास मार्ग योजना करा

---

## 🎓 शिक्षण परिणाम

### तुम्ही काय तयार कराल

कार्यशाळा संपेपर्यंत, तुम्ही खालील तयार केले असेल:

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

### कौशल्य स्तर मॅट्रिक्स

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

### करिअर-तयार कौशल्ये

**या कार्यशाळेनंतर, तुम्ही तयार असाल:**

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

✅ **Edge वातावरणासाठी ऑप्टिमाइझ करा**
- मर्यादित संसाधनांसह IoT उपकरणे
- ऑफलाइन-प्रथम मोबाइल अनुप्रयोग
- कमी विलंब असलेली रिअल-टाइम प्रणाली

✅ **बुद्धिमान आर्किटेक्चर डिझाइन करा**
- जटिल वर्कफ्लोसाठी मल्टी-एजंट सिस्टम
- हायब्रिड Edge-Cloud तैनाती
- खर्च-ऑप्टिमाइझ 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) | मूलभूत आणि स्ट्रीमिंग चॅट | ~30s |
| 2 | [`rag_pipeline.py`](../../../Workshop/samples/session02/rag_pipeline.py) | एम्बेडिंगसह RAG | ~45s |
| 2 | [`rag_eval_ragas.py`](../../../Workshop/samples/session02/rag_eval_ragas.py) | RAG गुणवत्ता मूल्यांकन | ~60s |
| 3 | [`benchmark_oss_models.py`](../../../Workshop/samples/session03/benchmark_oss_models.py) | मल्टी-मॉडेल बेंचमार्किंग | ~2-3m |
| 4 | [`model_compare.py`](../../../Workshop/samples/session04/model_compare.py) | SLM विरुद्ध LLM तुलना | ~45s |
| 5 | [`agents_orchestrator.py`](../../../Workshop/samples/session05/agents_orchestrator.py) | मल्टी-एजंट प्रणाली | ~60s |
| 6 | [`models_router.py`](../../../Workshop/samples/session06/models_router.py) | हेतू-आधारित रूटिंग | ~45s |
| 6 | [`models_pipeline.py`](../../../Workshop/samples/session06/models_pipeline.py) | मल्टी-स्टेप पाइपलाइन | ~60s |

### Jupyter Notebooks

स्पष्टीकरणे आणि व्हिज्युअलायझेशनसह परस्पर अन्वेषण:

| सत्र | नोटबुक | वर्णन | अडचण |
|------|--------|-------|-------|
| 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) | प्रॉ
| 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 सेवा वेगळ्या (Windows) मशीन किंवा VM वर macOS वर चालवत असाल, तर एंडपॉइंट एक्सपोर्ट करा:

```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` शेअर करतात जो प्रदान करतो:

* कॅश्ड `FoundryLocalManager` + OpenAI क्लायंट निर्मिती
* `chat_once()` हेल्पर वैकल्पिक रीट्राय + वापर प्रिंटिंगसह
* सोपी टोकन वापर अहवाल (सक्षम करा `SHOW_USAGE=1` द्वारे)

यामुळे डुप्लिकेशन कमी होते आणि स्थानिक मॉडेल ऑर्केस्ट्रेशनसाठी सर्वोत्तम पद्धती ठळकपणे दर्शवतात.

## पर्यायी सुधारणा (क्रॉस-सत्र)

| थीम | सुधारणा | सत्र | Env / Toggle |
|-----|---------|------|--------------|
| निर्धारकता | निश्चित तापमान + स्थिर प्रॉम्प्ट सेट्स | 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` | `# प्रत्येक उपनामासाठी व्यवस्थापक वापरा किंवा ज्ञात यादी राखा` | 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 -->