# EdgeAI pradedantiesiems - dirbtuvės

> **Praktinis mokymosi kelias kuriant gamybai paruoštas Edge AI programas**
>
> Įvaldykite vietinį AI diegimą su Microsoft Foundry Local, nuo pirmojo pokalbio užbaigimo iki daugiaveiksnių sistemų koordinavimo per 6 progresyvius užsiėmimus.

---

## 🎯 Įvadas

Sveiki atvykę į **EdgeAI pradedantiesiems dirbtuves** - praktinį vadovą, kaip kurti intelektualias programas, veikiančias tik vietinėje techninėje įrangoje. Šios dirbtuvės paverčia teorines Edge AI koncepcijas realiais įgūdžiais per palaipsniui sudėtingėjančius pratimus, naudojant Microsoft Foundry Local ir mažus kalbos modelius (SLM).

### Kodėl šios dirbtuvės?

**Edge AI revoliucija jau čia**

Organizacijos visame pasaulyje pereina nuo debesų priklausomų AI prie Edge kompiuterijos dėl trijų svarbių priežasčių:

1. **Privatumas ir atitiktis** - Apdorokite jautrius duomenis vietoje, be debesų perdavimo (HIPAA, GDPR, finansiniai reglamentai)
2. **Veikimas** - Pašalinkite tinklo vėlavimą (50-500ms vietoje vs 500-2000ms debesų kelionė)
3. **Išlaidų kontrolė** - Pašalinkite API mokesčius už žodžius ir mastelį be debesų išlaidų

**Tačiau Edge AI yra kitoks**

AI veikimas vietoje reikalauja naujų įgūdžių:
- Modelių pasirinkimas ir optimizavimas pagal išteklių apribojimus
- Vietinių paslaugų valdymas ir techninės įrangos pagreitinimas
- Užklausų kūrimas mažesniems modeliams
- Gamybos diegimo modeliai Edge įrenginiams

**Šios dirbtuvės suteiks šiuos įgūdžius**

Per 6 susitelkusius užsiėmimus (~3 valandos iš viso) jūs pereisite nuo "Hello World" iki gamybai paruoštų daugiaveiksnių sistemų diegimo - viskas veiks vietoje jūsų kompiuteryje.

---

## 📚 Mokymosi tikslai

Baigę šias dirbtuves, jūs galėsite:

### Pagrindiniai įgūdžiai
1. **Diegti ir valdyti vietines AI paslaugas**
   - Įdiegti ir konfigūruoti Microsoft Foundry Local
   - Pasirinkti tinkamus modelius Edge diegimui
   - Valdyti modelių gyvavimo ciklą (parsisiųsti, įkelti, talpinti)
   - Stebėti išteklių naudojimą ir optimizuoti veikimą

2. **Kurti AI pagrįstas programas**
   - Įgyvendinti OpenAI suderinamus pokalbių užbaigimus vietoje
   - Kurti efektyvias užklausas mažiems kalbos modeliams
   - Tvarkyti srautinį atsakymą geresniam naudotojo patyrimui
   - Integruoti vietinius modelius į esamas programas

3. **Kurti RAG (Retrieval Augmented Generation) sistemas**
   - Kurti semantinę paiešką su įterpimais
   - Pagrįsti LLM atsakymus specifinėmis žiniomis
   - Vertinti RAG kokybę pagal pramonės standartus
   - Mastelį nuo prototipo iki gamybos

4. **Optimizuoti modelio veikimą**
   - Testuoti kelis modelius jūsų naudojimo atveju
   - Matuoti vėlavimą, pralaidumą ir pirmojo žodžio laiką
   - Pasirinkti optimaliausius modelius pagal greičio/kokybės kompromisus
   - Lyginti SLM ir LLM kompromisus realiose situacijose

5. **Koordinuoti daugiaveiksnes sistemas**
   - Kurti specializuotus agentus skirtingoms užduotims
   - Įgyvendinti agentų atmintį ir konteksto valdymą
   - Koordinuoti agentus sudėtinguose darbo procesuose
   - Protingai nukreipti užklausas per kelis modelius

6. **Diegti gamybai paruoštus sprendimus**
   - Įgyvendinti klaidų tvarkymą ir pakartojimo logiką
   - Stebėti žodžių naudojimą ir sistemos išteklius
   - Kurti mastelio architektūras su modelio kaip įrankio modeliais
   - Planuoti migracijos kelius nuo Edge iki hibridinių (Edge + debesų)

---

## 🎓 Mokymosi rezultatai

### Ką sukursite

Baigę šias dirbtuves, jūs būsite sukūrę:

| Užsiėmimas | Rezultatas | Demonstruoti įgūdžiai |
|------------|------------|-----------------------|
| **1** | Pokalbių programa su srautu | Paslaugų nustatymas, pagrindiniai užbaigimai, srautinė UX |
| **2** | RAG sistema su vertinimu | Įterpimai, semantinė paieška, kokybės metrika |
| **3** | Daugiamodelių testavimo rinkinys | Veikimo matavimas, modelių palyginimas |
| **4** | SLM ir LLM palyginimo įrankis | Kompromisų analizė, optimizavimo strategijos |
| **5** | Daugiaveiksnių koordinavimo sistema | Agentų dizainas, atminties valdymas, koordinavimas |
| **6** | Protinga nukreipimo sistema | Ketinimų aptikimas, modelio pasirinkimas, mastelio galimybės |

### Kompetencijų matrica

| Įgūdžių lygis | Užsiėmimai 1-2 | Užsiėmimai 3-4 | Užsiėmimai 5-6 |
|---------------|---------------|---------------|---------------|
| **Pradedantysis** | ✅ Nustatymas ir pagrindai | ⚠️ Sudėtinga | ❌ Per sudėtinga |
| **Vidutinis** | ✅ Greita apžvalga | ✅ Pagrindinis mokymasis | ⚠️ Iššūkiai |
| **Pažengęs** | ✅ Lengvai pereinama | ✅ Tobulinimas | ✅ Gamybos modeliai |

### Karjerai paruošti įgūdžiai

**Po šių dirbtuvių jūs būsite pasiruošę:**

✅ **Kurti privatumo pirmumo programas**
- Sveikatos priežiūros programos, tvarkančios PHI/PII vietoje
- Finansinės paslaugos su atitikties reikalavimais
- Vyriausybės sistemos su duomenų suvereniteto poreikiais

✅ **Optimizuoti Edge aplinkoms**
- IoT įrenginiai su ribotais ištekliais
- Programos, veikiančios be interneto
- Mažo vėlavimo realaus laiko sistemos

✅ **Kurti intelektualias architektūras**
- Daugiaveiksnės sistemos sudėtingiems darbo procesams
- Hibridinės Edge-debesų diegimo sistemos
- Išlaidų optimizuota AI infrastruktūra

✅ **Vadovauti Edge AI iniciatyvoms**
- Vertinti Edge AI galimybes projektams
- Pasirinkti tinkamus modelius ir sistemas
- Kurti mastelio vietinius AI sprendimus

---

## 🗺️ Dirbtuvių struktūra

### Užsiėmimų apžvalga (6 užsiėmimai × 30 minučių = 3 valandos)

| Užsiėmimas | Tema | Dėmesys | Trukmė |
|------------|------|--------|-------|
| **1** | Pradžia su Foundry Local | Įdiegimas, patvirtinimas, pirmieji užbaigimai | 30 min |
| **2** | AI sprendimų kūrimas su RAG | Užklausų kūrimas, įterpimai, vertinimas | 30 min |
| **3** | Atvirojo kodo modeliai | Modelių atradimas, testavimas, pasirinkimas | 30 min |
| **4** | Pažangūs modeliai | SLM ir LLM, optimizavimas, sistemos | 30 min |
| **5** | AI pagrįsti agentai | Agentų dizainas, koordinavimas, atmintis | 30 min |
| **6** | Modeliai kaip įrankiai | Nukreipimas, grandinės, mastelio strategijos | 30 min |

---

## 🚀 Greitas startas

### Reikalavimai

**Sistemos reikalavimai:**
- **OS**: Windows 10/11, macOS 11+ arba Linux (Ubuntu 20.04+)
- **RAM**: Mažiausiai 8GB, rekomenduojama 16GB+
- **Saugykla**: 10GB+ laisvos vietos modeliams
- **CPU**: Modernus procesorius su AVX2 palaikymu
- **GPU** (neprivaloma): CUDA suderinamas arba Qualcomm NPU pagreitinimui

**Programinės įrangos reikalavimai:**
- **Python 3.8+** ([Parsisiųsti](https://www.python.org/downloads/))
- **Microsoft Foundry Local** ([Diegimo vadovas](../../../Workshop))
- **Git** ([Parsisiųsti](https://git-scm.com/downloads))
- **Visual Studio Code** (rekomenduojama) ([Parsisiųsti](https://code.visualstudio.com/))

### Nustatymas per 3 žingsnius

#### 1. Įdiegti Foundry Local

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

**macOS:**
```bash
brew tap microsoft/foundrylocal
brew install foundrylocal
```

**Patvirtinti diegimą:**
```bash
foundry --version
foundry service status
```

**Užtikrinti, kad Azure AI Foundry Local veikia su fiksuotu portu**

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

**Patvirtinti veikimą:**
```bash
# Check service status
foundry service status

# Test the endpoint
curl http://127.0.0.1:58123/v1/models
```
**Rasti galimus modelius**
Norėdami pamatyti, kurie modeliai yra prieinami jūsų Foundry Local instancijoje, galite užklausti modelių endpoint:

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

Naudojant Web Endpoint 

```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. Klonuoti saugyklą ir įdiegti priklausomybes

```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. Paleisti pirmąjį pavyzdį

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

**✅ Sėkmė!** Turėtumėte matyti srautinį atsakymą apie Edge AI.

---

## 📦 Dirbtuvių ištekliai

### Python pavyzdžiai

Progresyvūs praktiniai pavyzdžiai, demonstruojantys kiekvieną koncepciją:

| Užsiėmimas | Pavyzdys | Aprašymas | Paleidimo laikas |
|------------|----------|-----------|------------------|
| 1 | [`chat_bootstrap.py`](../../../Workshop/samples/session01/chat_bootstrap.py) | Pagrindinis ir srautinis pokalbis | ~30s |
| 2 | [`rag_pipeline.py`](../../../Workshop/samples/session02/rag_pipeline.py) | RAG su įterpimais | ~45s |
| 2 | [`rag_eval_ragas.py`](../../../Workshop/samples/session02/rag_eval_ragas.py) | RAG kokybės vertinimas | ~60s |
| 3 | [`benchmark_oss_models.py`](../../../Workshop/samples/session03/benchmark_oss_models.py) | Daugiamodelių testavimas | ~2-3m |
| 4 | [`model_compare.py`](../../../Workshop/samples/session04/model_compare.py) | SLM ir LLM palyginimas | ~45s |
| 5 | [`agents_orchestrator.py`](../../../Workshop/samples/session05/agents_orchestrator.py) | Daugiaveiksnių sistema | ~60s |
| 6 | [`models_router.py`](../../../Workshop/samples/session06/models_router.py) | Ketinimų pagrįstas nukreipimas | ~45s |
| 6 | [`models_pipeline.py`](../../../Workshop/samples/session06/models_pipeline.py) | Daugiapakopė grandinė | ~60s |

### Jupyter užrašų knygelės

Interaktyvus tyrinėjimas su paaiškinimais ir vizualizacijomis:

| Užsiėmimas | Užrašų knygelė | Aprašymas | Sudėtingumas |
|------------|---------------|-----------|-------------|
| 1 | [`session01_chat_bootstrap.ipynb`](./notebooks/session01_chat_bootstrap.ipynb) | Pokalbio pagrindai ir srautas | ⭐ Pradedantysis |
| 2 | [`session02_rag_pipeline.ipynb`](./notebooks/session02_rag_pipeline.ipynb) | RAG sistemos kūrimas | ⭐⭐ Vidutinis |
| 2 | [`session02_rag_eval_ragas.ipynb`](./notebooks/session02_rag_eval_ragas.ipynb) | RAG kokybės vertinimas | ⭐⭐ Vidutinis |
| 3 | [`session03_benchmark_oss_models.ipynb`](./notebooks/session03_benchmark_oss_models.ipynb) | Modelių testavimas | ⭐⭐ Vidutinis |
| 4 | [`session04_model_compare.ipynb`](./notebooks/session04_model_compare.ipynb) | Modelių palyginimas | ⭐⭐ Vidutinis |
| 5 | [`session05_agents_orchestrator.ipynb`](./notebooks/session05_agents_orchestrator.ipynb) | Agentų koordinavimas | ⭐⭐⭐ Pažengęs |
| 6 | [`session06_models_router.ipynb`](./notebooks/session06_models_router.ipynb) | Ketinimų nukreipimas | ⭐⭐⭐ Pažengęs |
| 6 | [`session06_models_pipeline.ipynb`](./notebooks/session06_models_pipeline.ipynb) | Grandinės koordinavimas | ⭐⭐⭐ Pažengęs |

### Dokumentacija

Išsamūs vadovai ir nuorodos:

| Dokumentas | Aprašymas | Naudoti kada |
|------------|-----------|-------------|
| [QUICK_START.md](./QUICK_START.md) | Greito nustatymo vadovas | Pradedant nuo nulio |
| [QUICK_REFERENCE.md](./QUICK_REFERENCE.md) | Komandų ir API atmintinė | Reikia greitų atsakymų |
| [FOUNDRY_SDK_QUICKREF.md](./FOUNDRY_SDK_QUICKREF.md) | SDK modeliai ir pavyzdžiai | Rašant kodą |
| [ENV_CONFIGURATION.md](./ENV_CONFIGURATION.md) | Aplinkos kintamųjų vadovas | Konfigūruojant pavyzdžius |
| [notebooks/TROUBLESHOOTING.md](./notebooks/TROUBLESHOOTING.md) | Dažnos problemos ir sprendimai | Trikčių šalinimas |

---

## 🎓 Mokymosi kelio rekomendacijos

### Pradedantiesiems (3-4 valandos)
1. ✅ Užsiėmimas 1: Pradžia (dėmesys nustatymui ir pagrindiniam pokalbiui)
2. ✅ Užsiėmimas 2: RAG pagrindai (pradžioje praleiskite vertinimą)
3. ✅ Užsiėmimas 3: Paprastas testavimas (tik 2 modeliai)
4. ⏭️ Praleiskite užsiėmimus 4-6 kol kas
5. 🔄 Grįžkite prie užsiėmimų 4-6 po pirmos programos sukūrimo

### Vidutiniams kūrėjams (3 valandos)
1. ⚡ Užsiėmimas 1: Greitas nustatymo patvirtinimas
2. ✅ Užsiėmimas 2: Pilnas RAG procesas su vertinimu
3. ✅ Užsiėmimas 3: Pilnas testavimo rinkinys
4. ✅ Užsiėmimas 4: Modelio optimizavimas
5. ✅ Užsiėmimai 5-6: Dėmesys architektūros modeliams

### Pažengusiems specialistams (2-3 valandos)
1. ⚡ Užsiėmimai 1-3: Greita apžvalga ir patvirtinimas
2. ✅ Užsiėmimas 4: Gilus optimizavimo tyrimas
3. ✅ Užsiėmimas 5: Daugiaveiksnių architektūra
4. ✅ Užsiėmimas 6: Gamybos modeliai ir mastelio galimybės
5. 🚀 Plėtra: Kurti individualią nukreipimo logiką ir hibridinius diegimus

---

## Dirbtuvių užsiėmimų paketas (koncentruoti 30 minučių užsiėmimai)

Jei sekate sutrumpintą 6 užsiėmimų dirbtuvių formatą, naudokite šiuos specialius vadovus (kiekvienas atitinka ir papildo platesnius modulių dokumentus aukščiau):

| Dirbtuvių užsiėmimas | Vadovas | Pagrindinis dėmesys |
|----------------------|---------|--------------------|
| 1 | [Session01-GettingStartedFoundryLocal](./Session01-GettingStartedFoundryLocal.md) | Įdiegimas, patvirtinimas, paleidimas phi & GPT-OSS-20B, pagreitinimas |
| 2 | [Session02-BuildAISolutionsRAG](./Session02-BuildAISolutionsRAG.md) | Užklaus
| 6 | [Session06-ModelsAsTools](./Session06-ModelsAsTools.md) | Maršrutizavimas, grandinės kūrimas, mastelio didinimas Azure |

Kiekviename sesijos faile yra: santrauka, mokymosi tikslai, 30 minučių demonstracijos eiga, pradinio projekto failai, patikros sąrašas, trikčių šalinimas ir nuorodos į oficialų Foundry Local Python SDK.

### Pavyzdiniai scenarijai

Įdiegti dirbtuvių priklausomybes (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
```

Jei Foundry Local paslauga vykdoma kitame (Windows) kompiuteryje ar VM iš macOS, eksportuokite galinį tašką:

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

| Sesija | Scenarijus (-ai) | Aprašymas |
|--------|------------------|-----------|
| 1 | `samples/session01/chat_bootstrap.py` | Paslaugos paleidimas ir pokalbių transliacija |
| 2 | `samples/session02/rag_pipeline.py` | Minimalus RAG (atminties įterpimai) |
|   | `samples/session02/rag_eval_ragas.py` | RAG vertinimas naudojant ragas metrikas |
| 3 | `samples/session03/benchmark_oss_models.py` | Daugelio modelių vėlinimo ir pralaidumo testavimas |
| 4 | `samples/session04/model_compare.py` | SLM ir LLM palyginimas (vėlinimas ir pavyzdiniai rezultatai) |
| 5 | `samples/session05/agents_orchestrator.py` | Dviejų agentų tyrimų → redakcijos procesas |
| 6 | `samples/session06/models_router.py` | Demonstracija pagal ketinimų maršrutizavimą |
|   | `samples/session06/models_pipeline.py` | Daugiapakopė planavimo/vykdymo/tobulinimo grandinė |

### Aplinkos kintamieji (bendri visiems pavyzdžiams)

| Kintamasis | Paskirtis | Pavyzdys |
|------------|-----------|----------|
| `FOUNDRY_LOCAL_ALIAS` | Numatytoji vieno modelio nuoroda paprastiems pavyzdžiams | `phi-4-mini` |
| `SLM_ALIAS` / `LLM_ALIAS` | Aiškus SLM ir didesnio modelio palyginimas | `phi-4-mini` / `gpt-oss-20b` |
| `BENCH_MODELS` | Modelių nuorodų sąrašas testavimui | `qwen2.5-0.5b,mistral-7b` |
| `BENCH_ROUNDS` | Testavimo pakartojimų skaičius kiekvienam modeliui | `3` |
| `BENCH_PROMPT` | Testavimui naudojamas raginimas | `Explain retrieval augmented generation briefly.` |
| `EMBED_MODEL` | Įterpimo modelis naudojant sentence-transformers | `sentence-transformers/all-MiniLM-L6-v2` |
| `RAG_QUESTION` | Testavimo užklausos pakeitimas RAG procesui | `Why use RAG with local inference?` |
| `AGENT_QUESTION` | Agentų proceso užklausos pakeitimas | `Explain why edge AI matters for compliance.` |
| `AGENT_MODEL_PRIMARY` | Modelio nuoroda tyrimų agentui | `phi-4-mini` |
| `AGENT_MODEL_EDITOR` | Modelio nuoroda redaktoriaus agentui (gali skirtis) | `gpt-oss-20b` |
| `SHOW_USAGE` | Kai `1`, rodo sunaudotų žetonų skaičių per užbaigimą | `1` |
| `RETRY_ON_FAIL` | Kai `1`, kartoja bandymą po laikino pokalbio klaidų | `1` |
| `RETRY_BACKOFF` | Sekundės laukimo prieš pakartojimą | `1.0` |

Jei kintamasis nenustatytas, scenarijai naudoja numatytas reikšmes. Vieno modelio demonstracijoms paprastai reikia tik `FOUNDRY_LOCAL_ALIAS`.

### Pagalbinis modulis

Visi pavyzdžiai dabar naudoja bendrą pagalbinį failą `samples/workshop_utils.py`, kuris teikia:

* Kešuotą `FoundryLocalManager` + OpenAI klientų kūrimą
* `chat_once()` pagalbinę funkciją su pasirinktiniais pakartojimais + naudojimo spausdinimu
* Paprastą žetonų naudojimo ataskaitą (aktyvuojama per `SHOW_USAGE=1`)

Tai sumažina dubliavimą ir pabrėžia geriausią praktiką efektyviam vietinių modelių valdymui.

## Pasirenkami patobulinimai (tarp sesijų)

| Tema | Patobulinimas | Sesijos | Aplinka / Jungiklis |
|------|---------------|---------|---------------------|
| Determinizmas | Fiksuota temperatūra + stabilūs raginimų rinkiniai | 1–6 | Nustatyti `temperature=0`, `top_p=1` |
| Žetonų naudojimo matomumas | Nuoseklus kaštų/efektyvumo mokymas | 1–6 | `SHOW_USAGE=1` |
| Pirmo žetono transliacija | Suvokiamo vėlinimo metrika | 1,3,4,6 | `BENCH_STREAM=1` (testavimas) |
| Atsparumas pakartojimui | Tvarko laikinas šalto paleidimo klaidas | Visos | `RETRY_ON_FAIL=1` + `RETRY_BACKOFF` |
| Daugiamodeliai agentai | Heterogeninė vaidmenų specializacija | 5 | `AGENT_MODEL_PRIMARY`, `AGENT_MODEL_EDITOR` |
| Adaptacinis maršrutizavimas | Ketinimų + kaštų euristika | 6 | Išplėsti maršrutizatorių su eskalavimo logika |
| Vektorinė atmintis | Ilgalaikė semantinė atmintis | 2,5,6 | Integruoti FAISS/Chroma įterpimo indeksą |
| Sekos eksportas | Auditas ir vertinimas | 2,5,6 | Pridėti JSON eilutes kiekvienam žingsniui |
| Kokybės rubrikos | Kokybinis stebėjimas | 3–6 | Antrinės vertinimo raginimai |
| Greiti testai | Greita prieš dirbtuves patikra | Visos | `python Workshop/tests/smoke.py` |

### Deterministinis greitas startas

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

Tikėtis stabilių žetonų skaičių per pakartotinius identiškus įvestis.

### RAG vertinimas (2 sesija)

Naudokite `rag_eval_ragas.py`, kad apskaičiuotumėte atsakymų aktualumą, patikimumą ir konteksto tikslumą mažame sintetiniame duomenų rinkinyje:

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

Išplėskite pateikdami didesnį JSONL su klausimais, kontekstais ir tikromis reikšmėmis, tada konvertuokite į Hugging Face `Dataset`.

## CLI komandų tikslumo priedas

Dirbtuvės sąmoningai naudoja tik šiuo metu dokumentuotas / stabilias Foundry Local CLI komandas.

### Naudojamos stabilios komandos

| Kategorija | Komanda | Paskirtis |
|------------|---------|----------|
| Pagrindinė | `foundry --version` | Rodo įdiegtą versiją |
| Paslauga | `foundry service start` | Paleidžia vietinę paslaugą (jei ne automatiškai) |
| Paslauga | `foundry service status` | Rodo paslaugos būseną |
| Modeliai | `foundry model list` | Rodo katalogą / galimus modelius |
| Modeliai | `foundry model download <alias>` | Atsisiunčia modelio svorius į kešą |
| Modeliai | `foundry model run <alias>` | Paleidžia (įkelia) modelį vietoje; derinama su `--prompt` vienkartiniam naudojimui |
| Modeliai | `foundry model unload <alias>` / `foundry model stop <alias>` | Iškelia modelį iš atminties (jei palaikoma) |
| Kešas | `foundry cache list` | Rodo kešuotus (atsisiųstus) modelius |

### Vienkartinio raginimo šablonas

Vietoj pasenusios `model chat` subkomandos naudokite:

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

Tai vykdo vieną raginimo/atsakymo ciklą ir tada išeina.

### Pašalinti / vengti šablonai

| Pasenę / nedokumentuoti | Pakeitimai / rekomendacijos |
|-------------------------|----------------------------|
| `foundry model chat <model> "..."` | `foundry model run <model> --prompt "..."` |
| `foundry model list --running` | Naudokite paprastą `foundry model list` + naujausią veiklą / žurnalus |
| `foundry model list --cached` | `foundry cache list` |
| `foundry model stats <model>` | Naudokite testavimo Python scenarijų + OS įrankius (Task Manager / `nvidia-smi`) |
| `foundry model benchmark ...` | `samples/session03/benchmark_oss_models.py` |

### Testavimas ir telemetrija

- Vėlinimas, p95, žetonai per sekundę: `samples/session03/benchmark_oss_models.py`
- Pirmo žetono vėlinimas (transliacija): nustatyti `BENCH_STREAM=1`
- Išteklių naudojimas: OS monitoriai (Task Manager, Activity Monitor, `nvidia-smi`).

Kai naujos CLI telemetrijos komandos stabilizuojasi, jas galima integruoti su minimaliomis sesijos failų redakcijomis.

### Automatinė linterio apsauga

Automatinis linteris neleidžia vėl įtraukti pasenusių CLI šablonų į kodu aptvertus markdown failus:

Scenarijus: `Workshop/scripts/lint_markdown_cli.py`

Pasenę šablonai blokuojami kodu aptvertuose blokuose.

Rekomenduojami pakeitimai:
| Pasenę | Pakeitimai |
|--------|-----------|
| `foundry model chat <a> "..."` | `foundry model run <a> --prompt "..."` |
| `model list --running` | `model list` |
| `model list --cached` | `cache list` |
| `model stats` | Testavimo scenarijus + sistemos įrankiai |
| `model benchmark` | `samples/session03/benchmark_oss_models.py` |
| `model list --available` | `model list` |

Vykdyti vietoje:
```powershell
python Workshop\scripts\lint_markdown_cli.py --verbose
```

GitHub veiksmas: `.github/workflows/markdown-cli-lint.yml` vykdomas kiekvieno įkėlimo ir PR metu.

Pasirenkamas prieš įsipareigojimą kabinamas kablys:
```bash
echo "python Workshop/scripts/lint_markdown_cli.py" > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
```

## Greita CLI → SDK migracijos lentelė

| Užduotis | CLI vienos eilutės komanda | SDK (Python) ekvivalentas | Pastabos |
|----------|----------------------------|---------------------------|---------|
| Paleisti modelį vieną kartą (raginimas) | `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 automatiškai paleidžia paslaugą ir kešavimą |
| Atsisiųsti (kešuoti) modelį | `foundry model download qwen2.5-0.5b` | `FoundryLocalManager("qwen2.5-0.5b")  # triggers download/load` | Valdytojas pasirenka geriausią variantą, jei nuoroda susijusi su keliais modeliais |
| Rodyti katalogą | `foundry model list` | `# use manager for each alias or maintain known list` | CLI agreguoja; SDK šiuo metu per nuorodą |
| Rodyti kešuotus modelius | `foundry cache list` | `manager.list_cached_models()` | Po valdytojo inicijavimo (bet kuri nuoroda) |
| Gauti galinio taško URL | (numanoma) | `manager.endpoint` | Naudojama OpenAI suderinamam klientui sukurti |
| Šildyti modelį | `foundry model run <alias>` tada pirmas raginimas | `chat_once(alias, messages=[...])` (pagalbinė funkcija) | Pagalbinės funkcijos tvarko pradinį šalto paleidimo vėlinimą |
| Matavimo vėlinimas | `python -m session03.benchmark_oss_models` | `import benchmark_oss_models` (arba naujas eksportavimo scenarijus) | Pirmenybė teikiama scenarijui dėl nuoseklių metrikų |
| Sustabdyti / iškelti modelį | `foundry model unload <alias>` | (Neatskleista – paleisti paslaugą / procesą iš naujo) | Paprastai nereikalinga dirbtuvių eigai |
| Gauti žetonų naudojimą | (žiūrėti išvestį) | `resp.usage.total_tokens` | Pateikiama, jei backend grąžina naudojimo objektą |

## Testavimo Markdown eksportas

Naudokite scenarijų `Workshop/scripts/export_benchmark_markdown.py`, kad paleistumėte naują testavimą (ta pati logika kaip `samples/session03/benchmark_oss_models.py`) ir sugeneruotumėte GitHub draugišką Markdown lentelę bei neapdorotą JSON.

### Pavyzdys

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

Sugeneruoti failai:
| Failas | Turinys |
|--------|---------|
| `benchmark_report.md` | Markdown lentelė + interpretacijos užuominos |
| `benchmark_report.json` | Neapdorotų metrikų masyvas (skirtumų / tendencijų stebėjimui) |

Nustatykite `BENCH_STREAM=1` aplinkoje, kad įtrauktumėte pirmo žetono vėlinimą, jei palaikoma.

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**Atsakomybės apribojimas**:  
Šis dokumentas buvo išverstas naudojant AI vertimo paslaugą [Co-op Translator](https://github.com/Azure/co-op-translator). Nors siekiame tikslumo, prašome atkreipti dėmesį, kad automatiniai vertimai gali turėti klaidų ar netikslumų. Originalus dokumentas jo gimtąja kalba turėtų būti laikomas autoritetingu šaltiniu. Kritinei informacijai rekomenduojama profesionali žmogaus vertimo paslauga. Mes neprisiimame atsakomybės už nesusipratimus ar neteisingus aiškinimus, atsiradusius naudojant šį vertimą.
<!-- CO-OP TRANSLATOR DISCLAIMER END -->