# EdgeAI ప్రారంభికులకు - వర్క్‌షాప్

> **ప్రొడక్షన్-రెడీ ఎడ్జ్ AI అప్లికేషన్లను నిర్మించడానికి హ్యాండ్స్-ఆన్ లెర్నింగ్ పాత్**
>
> Microsoft Foundry Local తో స్థానిక AI డిప్లాయ్‌మెంట్‌లో నైపుణ్యం సాధించండి, మొదటి చాట్ కంప్లీషన్ నుండి 6 ప్రోగ్రెసివ్ సెషన్లలో మల్టీ-ఏజెంట్ ఆర్కెస్ట్రేషన్ వరకు.

---

## 🎯 పరిచయం

**EdgeAI ప్రారంభికుల వర్క్‌షాప్** కు స్వాగతం - ఇది పూర్తిగా స్థానిక హార్డ్‌వేర్‌పై నడిచే తెలివైన అప్లికేషన్లను నిర్మించడానికి మీ ప్రాక్టికల్, హ్యాండ్స్-ఆన్ గైడ్. ఈ వర్క్‌షాప్ సిద్దాంత Edge AI కాన్సెప్ట్స్‌ను Microsoft Foundry Local మరియు Small Language Models (SLMs) ఉపయోగించి ప్రోగ్రెసివ్‌గా కష్టమైన వ్యాయామాల ద్వారా వాస్తవ ప్రపంచ నైపుణ్యాలుగా మార్చుతుంది.

### ఈ వర్క్‌షాప్ ఎందుకు?

**Edge AI విప్లవం ఇక్కడే ఉంది**

ప్రపంచవ్యాప్తంగా సంస్థలు క్లౌడ్ ఆధారిత AI నుండి ఎడ్జ్ కంప్యూటింగ్‌కి మూడు ముఖ్య కారణాల వల్ల మారుతున్నాయి:

1. **గోప్యత & అనుగుణత** - క్లౌడ్ ట్రాన్స్మిషన్ లేకుండా సున్నితమైన డేటాను స్థానికంగా ప్రాసెస్ చేయడం (HIPAA, GDPR, ఆర్థిక నియమాలు)
2. **పనితీరు** - నెట్‌వర్క్ లేటెన్సీ తొలగించడం (50-500ms స్థానిక vs 500-2000ms క్లౌడ్ రౌండ్-ట్రిప్)
3. **ఖర్చు నియంత్రణ** - ప్రతి టోకెన్ API ఖర్చులను తొలగించి క్లౌడ్ ఖర్చులు లేకుండా స్కేల్ చేయడం

**కానీ Edge AI వేరుగా ఉంటుంది**

AIని ఆన్-ప్రెమైసెస్ నడపడం కొత్త నైపుణ్యాలను అవసరం చేస్తుంది:
- వనరుల పరిమితులకు అనుగుణంగా మోడల్ ఎంపిక మరియు ఆప్టిమైజేషన్
- స్థానిక సర్వీస్ నిర్వహణ మరియు హార్డ్‌వేర్ యాక్సిలరేషన్
- చిన్న మోడల్స్ కోసం ప్రాంప్ట్ ఇంజనీరింగ్
- ఎడ్జ్ డివైసెస్ కోసం ప్రొడక్షన్ డిప్లాయ్‌మెంట్ ప్యాటర్న్స్

**ఈ వర్క్‌షాప్ ఆ నైపుణ్యాలను అందిస్తుంది**

6 ఫోకస్డ్ సెషన్లలో (~3 గంటలు మొత్తం), మీరు "హలో వరల్డ్" నుండి ప్రొడక్షన్-రెడీ మల్టీ-ఏజెంట్ సిస్టమ్స్‌ను స్థానికంగా మీ మెషీన్‌పై నడిపేలా డిప్లాయ్ చేయడం వరకు అభివృద్ధి చెందుతారు.

---

## 📚 నేర్చుకునే లక్ష్యాలు

ఈ వర్క్‌షాప్ పూర్తి చేసిన తర్వాత, మీరు చేయగలుగుతారు:

### ప్రాథమిక నైపుణ్యాలు
1. **స్థానిక AI సర్వీసులను డిప్లాయ్ చేసి నిర్వహించండి**
   - Microsoft Foundry Local ఇన్‌స్టాల్ చేసి కాన్ఫిగర్ చేయండి
   - ఎడ్జ్ డిప్లాయ్‌మెంట్ కోసం సరైన మోడల్స్ ఎంచుకోండి
   - మోడల్ లైఫ్‌సైకిల్ నిర్వహణ (డౌన్‌లోడ్, లోడ్, క్యాష్)
   - వనరు వినియోగాన్ని మానిటర్ చేసి పనితీరును ఆప్టిమైజ్ చేయండి

2. **AI-పవర్డ్ అప్లికేషన్లు నిర్మించండి**
   - OpenAI-అనుకూల చాట్ కంప్లీషన్లను స్థానికంగా అమలు చేయండి
   - చిన్న భాషా మోడల్స్ కోసం సమర్థవంతమైన ప్రాంప్ట్‌లు డిజైన్ చేయండి
   - మెరుగైన UX కోసం స్ట్రీమింగ్ ప్రతిస్పందనలను హ్యాండిల్ చేయండి
   - స్థానిక మోడల్స్‌ను ఉన్న అప్లికేషన్లలో ఇంటిగ్రేట్ చేయండి

3. **RAG (రిట్రీవల్ ఆగ్మెంటెడ్ జనరేషన్) సిస్టమ్స్ సృష్టించండి**
   - ఎంబెడ్డింగ్స్‌తో సెమాంటిక్ సెర్చ్ నిర్మించండి
   - LLM ప్రతిస్పందనలను డొమైన్-స్పెసిఫిక్ జ్ఞానంతో గ్రౌండ్ చేయండి
   - RAG నాణ్యతను ఇండస్ట్రీ-స్టాండర్డ్ మెట్రిక్స్‌తో అంచనా వేయండి
   - ప్రోటోటైప్ నుండి ప్రొడక్షన్ వరకు స్కేల్ చేయండి

4. **మోడల్ పనితీరును ఆప్టిమైజ్ చేయండి**
   - మీ ఉపయోగానికి అనుగుణంగా బహుళ మోడల్స్‌ను బెంచ్‌మార్క్ చేయండి
   - లేటెన్సీ, థ్రూపుట్, మొదటి టోకెన్ సమయాన్ని కొలవండి
   - వేగం/నాణ్యత ట్రేడ్-ఆఫ్స్ ఆధారంగా ఉత్తమ మోడల్స్ ఎంచుకోండి
   - వాస్తవ పరిస్థితుల్లో SLM vs LLM ట్రేడ్-ఆఫ్స్‌ను పోల్చండి

5. **మల్టీ-ఏజెంట్ సిస్టమ్స్‌ను ఆర్కెస్ట్రేట్ చేయండి**
   - వివిధ పనుల కోసం ప్రత్యేక ఏజెంట్లను డిజైన్ చేయండి
   - ఏజెంట్ మెమరీ మరియు కాంటెక్స్ట్ నిర్వహణను అమలు చేయండి
   - సంక్లిష్ట వర్క్‌ఫ్లోలలో ఏజెంట్లను సమన్వయపరచండి
   - బహుళ మోడల్స్ మధ్య తెలివైన రిక్వెస్ట్ రూటింగ్ చేయండి

6. **ప్రొడక్షన్-రెడీ సొల్యూషన్స్‌ను డిప్లాయ్ చేయండి**
   - ఎర్రర్ హ్యాండ్లింగ్ మరియు రిట్రై లాజిక్ అమలు చేయండి
   - టోకెన్ వినియోగం మరియు సిస్టమ్ వనరులను మానిటర్ చేయండి
   - మోడల్-అస్-టూల్స్ ప్యాటర్న్స్‌తో స్కేలబుల్ ఆర్కిటెక్చర్స్ నిర్మించండి
   - ఎడ్జ్ నుండి హైబ్రిడ్ (ఎడ్జ్ + క్లౌడ్)కి మైగ్రేషన్ మార్గాలను ప్లాన్ చేయండి

---

## 🎓 నేర్చుకున్న ఫలితాలు

### మీరు ఏమి నిర్మిస్తారు

ఈ వర్క్‌షాప్ ముగింపు వరకు, మీరు క్రింది వాటిని సృష్టిస్తారు:

| సెషన్ | డెలివరబుల్ | ప్రదర్శించిన నైపుణ్యాలు |
|---------|-------------|---------------------|
| **1** | స్ట్రీమింగ్‌తో చాట్ అప్లికేషన్ | సర్వీస్ సెటప్, ప్రాథమిక కంప్లీషన్లు, స్ట్రీమింగ్ UX |
| **2** | RAG సిస్టమ్‌తో అంచనా | ఎంబెడ్డింగ్స్, సెమాంటిక్ సెర్చ్, నాణ్యత మెట్రిక్స్ |
| **3** | మల్టీ-మోడల్ బెంచ్‌మార్క్ సూట్ | పనితీరు కొలత, మోడల్ పోలిక |
| **4** | SLM vs LLM కంపారేటర్ | ట్రేడ్-ఆఫ్ విశ్లేషణ, ఆప్టిమైజేషన్ వ్యూహాలు |
| **5** | మల్టీ-ఏజెంట్ ఆర్కెస్ట్రేటర్ | ఏజెంట్ డిజైన్, మెమరీ నిర్వహణ, సమన్వయం |
| **6** | తెలివైన రూటింగ్ సిస్టమ్ | ఉద్దేశ్య గుర్తింపు, మోడల్ ఎంపిక, స్కేలబిలిటీ |

### నైపుణ్యాల మ్యాట్రిక్స్

| నైపుణ్య స్థాయి | సెషన్ 1-2 | సెషన్ 3-4 | సెషన్ 5-6 |
|-------------|-------------|-------------|-------------|
| **ప్రారంభికుడు** | ✅ సెటప్ & ప్రాథమికాలు | ⚠️ కష్టమైనవి | ❌ చాలా అభివృద్ధి చెందినవి |
| **మధ్యస్థ** | ✅ త్వరిత సమీక్ష | ✅ ప్రాథమిక అభ్యాసం | ⚠️ విస్తరణ లక్ష్యాలు |
| **అధిక స్థాయి** | ✅ సులభంగా | ✅ మెరుగుదల | ✅ ప్రొడక్షన్ ప్యాటర్న్స్ |

### కెరీర్-రెడీ నైపుణ్యాలు

**ఈ వర్క్‌షాప్ తర్వాత, మీరు సిద్ధంగా ఉంటారు:**

✅ **గోప్యత-ముందస్తు అప్లికేషన్లు నిర్మించండి**
- స్థానికంగా PHI/PII నిర్వహించే ఆరోగ్య సంరక్షణ అప్లికేషన్లు
- అనుగుణత అవసరాలతో ఆర్థిక సేవలు
- డేటా సార్వభౌమత్వ అవసరాలతో ప్రభుత్వ వ్యవస్థలు

✅ **ఎడ్జ్ వాతావరణాలకు ఆప్టిమైజ్ చేయండి**
- పరిమిత వనరుల IoT పరికరాలు
- ఆఫ్‌లైన్-ముందస్తు మొబైల్ అప్లికేషన్లు
- తక్కువ లేటెన్సీ రియల్-టైమ్ సిస్టమ్స్

✅ **తెలివైన ఆర్కిటెక్చర్స్ డిజైన్ చేయండి**
- సంక్లిష్ట వర్క్‌ఫ్లోల కోసం మల్టీ-ఏజెంట్ సిస్టమ్స్
- హైబ్రిడ్ ఎడ్జ్-క్లౌడ్ డిప్లాయ్‌మెంట్లు
- ఖర్చు-ఆప్టిమైజ్డ్ AI ఇన్‌ఫ్రాస్ట్రక్చర్

✅ **ఎడ్జ్ AI ఇనిషియేటివ్స్‌ను నడిపించండి**
- ప్రాజెక్టుల కోసం ఎడ్జ్ AI సాధ్యమయినదా అని అంచనా వేయండి
- సరైన మోడల్స్ మరియు ఫ్రేమ్‌వర్క్‌లను ఎంచుకోండి
- స్కేలబుల్ స్థానిక AI సొల్యూషన్స్ ఆర్కిటెక్ట్ చేయండి

---

## 🗺️ వర్క్‌షాప్ నిర్మాణం

### సెషన్ అవలోకనం (6 సెషన్లు × 30 నిమిషాలు = 3 గంటలు)

| సెషన్ | విషయం | ఫోకస్ | వ్యవధి |
|---------|-------|-------|----------|
| **1** | Foundry Local తో ప్రారంభం | ఇన్‌స్టాల్, ధృవీకరణ, మొదటి కంప్లీషన్లు | 30 నిమిషాలు |
| **2** | RAG తో AI సొల్యూషన్స్ నిర్మాణం | ప్రాంప్ట్ ఇంజనీరింగ్, ఎంబెడ్డింగ్స్, అంచనా | 30 నిమిషాలు |
| **3** | ఓపెన్ సోర్స్ మోడల్స్ | మోడల్ కనుగొనడం, బెంచ్‌మార్కింగ్, ఎంపిక | 30 నిమిషాలు |
| **4** | కట్టింగ్ ఎడ్జ్ మోడల్స్ | SLM vs 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+** ([Download](https://www.python.org/downloads/))
- **Microsoft Foundry Local** ([Installation Guide](../../../Workshop))
- **Git** ([Download](https://git-scm.com/downloads))
- **Visual Studio Code** (సిఫార్సు) ([Download](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
# FoundryLocal ను పోర్ట్ 58123 (డిఫాల్ట్) ఉపయోగించడానికి సెట్ చేయండి
foundry service set --port 58123 --show

# లేదా వేరే పోర్ట్ ఉపయోగించండి
foundry service set --port 58000 --show
```

**పనిచేస్తుందో లేదో ధృవీకరించండి:**
```bash
# సేవ స్థితిని తనిఖీ చేయండి
foundry service status

# ఎండ్‌పాయింట్‌ను పరీక్షించండి
curl http://127.0.0.1:58123/v1/models
```
**లభ్యమయ్యే మోడల్స్ కనుగొనడం**
Foundry Local ఇన్‌స్టాన్స్‌లో ఏ మోడల్స్ అందుబాటులో ఉన్నాయో చూడటానికి, మీరు మోడల్స్ ఎండ్‌పాయింట్‌ను క్వెరీ చేయవచ్చు:

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

వెబ్ ఎండ్‌పాయింట్ ఉపయోగించడం

```bash
# విండోస్ పవర్‌షెల్
powershell -Command "Invoke-RestMethod -Uri 'http://127.0.0.1:58123/v1/models' -Method Get"

# లేదా కర్ల్ ఉపయోగించడం (ఉపలబ్ధి ఉంటే)
curl http://127.0.0.1:58123/v1/models
```

#### 2. రిపోజిటరీని క్లోన్ చేసి డిపెండెన్సీలను ఇన్‌స్టాల్ చేయండి

```bash
# రిపోజిటరీని క్లోన్ చేయండి
git clone https://github.com/microsoft/edgeai-for-beginners.git
cd edgeai-for-beginners/Workshop

# వర్చువల్ ఎన్విరాన్‌మెంట్ సృష్టించండి
python -m venv .venv

# వర్చువల్ ఎన్విరాన్‌మెంట్‌ను యాక్టివేట్ చేయండి
# విండోస్:
.\.venv\Scripts\activate
# మాక్‌ఓఎస్/లినక్స్:
source .venv/bin/activate

# డిపెండెన్సీలను ఇన్‌స్టాల్ చేయండి
pip install -r requirements.txt
```

#### 3. మీ మొదటి సాంపిల్‌ను రన్ చేయండి

```bash
# ఫౌండ్రీ లోకల్ ప్రారంభించి ఒక మోడల్ లోడ్ చేయండి
foundry model run phi-4-mini

# చాట్ బూట్‌స్ట్రాప్ నమూనాను నడపండి
cd samples
python -m session01.chat_bootstrap "What is edge AI?"
```

**✅ విజయవంతం!** మీరు ఎడ్జ్ 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 vs 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 సెకన్లు |

### జూపిటర్ నోట్‌బుక్స్

వివరణలు మరియు విజువలైజేషన్లతో ఇంటరాక్టివ్ అన్వేషణ:

| సెషన్ | నోట్‌బుక్ | వివరణ | కష్టం స్థాయి |
|---------|----------|-------------|------------|
| 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: Getting Started (సెటప్ మరియు ప్రాథమిక చాట్ పై ఫోకస్)
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 vs LLM, WebGPU, Chainlit RAG, ONNX యాక్సిలరేషన్ |
| 5 | [Session05-AIPoweredAgents](./Session05-AIPoweredAgents.md) | ఏజెంట్ పాత్రలు, మెమరీ, టూల్స్, ఆర్కెస్ట్రేషన్ |
| 6 | [Session06-ModelsAsTools](./Session06-ModelsAsTools.md) | రూటింగ్, చైనింగ్, ఆజ్యూర్‌కు స్కేలింగ్ పాత్ |

ప్రతి సెషన్ ఫైల్‌లో ఉంటాయి: సారాంశం, నేర్చుకునే లక్ష్యాలు, 30 నిమిషాల డెమో ఫ్లో, స్టార్టర్ ప్రాజెక్ట్, ధృవీకరణ చెక్లిస్ట్, సమస్య పరిష్కారం, మరియు అధికారిక Foundry Local Python SDK కు సూచనలు.

### నమూనా స్క్రిప్టులు

వర్క్‌షాప్ డిపెండెన్సీలను ఇన్‌స్టాల్ చేయండి (విండోస్):

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

macOS / లినక్స్:

```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 vs 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 vs పెద్ద మోడల్ తులన కోసం | `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>` | బెంచ్‌మార్క్ పైథాన్ స్క్రిప్ట్ + 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 టెలిమెట్రీ కమాండ్లు అప్‌స్ట్రీమ్‌లో స్థిరపడినప్పుడు, అవి సెషన్ మార్క్డౌన్‌లలో తక్కువ మార్పులతో చేర్చవచ్చు.

### ఆటోమేటెడ్ లింట్ గార్డ్

ఒక ఆటోమేటెడ్ లింటర్ మార్క్డౌన్ ఫైళ్లలోని fenced కోడ్ బ్లాక్స్ లో పాత 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 -->