# EdgeAI за начинаещи - Работилница

> **Практически път за обучение за създаване на готови за производство Edge AI приложения**
>
> Усъвършенствайте локалното внедряване на AI с Microsoft Foundry Local, от първото завършване на чат до оркестрация на множество агенти в 6 прогресивни сесии.

---

## 🎯 Въведение

Добре дошли в **EdgeAI за начинаещи - Работилница** - вашето практическо ръководство за създаване на интелигентни приложения, които работят изцяло на локален хардуер. Тази работилница превръща теоретичните концепции на Edge AI в реални умения чрез прогресивно предизвикателни упражнения с Microsoft Foundry Local и Малки езикови модели (SLMs).

### Защо тази работилница?

**Революцията на 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-съвместими чат завършвания локално
   - Дизайн на ефективни промптове за Малки езикови модели
   - Работа с стрийминг отговори за по-добро потребителско изживяване
   - Интегриране на локални модели в съществуващи приложения

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** | Създаване на AI решения с RAG | Създаване на промптове, вграждания, оценка | 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 инстанс, можете да направите заявка към endpoint за модели:

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

Използване на уеб 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. Клониране на хранилище и инсталиране на зависимости

```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) | Многоетапна pipeline | ~60s |

### Jupyter Notebooks

Интерактивно изследване с обяснения и визуализации:

| Сесия | Notebook | Описание | Трудност |
|-------|----------|----------|----------|
| 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) | Оркестрация на pipeline | ⭐⭐⭐ Напреднал |

### Документация

Подробни ръководства и справки:

| Документ | Описание | Използвайте когато |
|----------|----------|---------------------|
| [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 pipeline с оценка
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 | [Session
| 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) или виртуална машина от 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 с метрики на ragas |
| 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 | `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 с въпроси, контексти и истински стойности, след което го конвертирайте в `Dataset` на Hugging Face.

## Приложение за точност на CLI команди

Работилницата умишлено използва само текущо документирани / стабилни CLI команди на Foundry Local.

### Препратки към стабилни команди

| Категория | Команда | Цел |
|-----------|---------|-----|
| Основни | `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 команди за телеметрия може да бъде интегрирано с минимални редакции на markdown файловете за сесии.

### Автоматична проверка на синтаксиса

Автоматичен проверител предотвратява повторното въвеждане на остарели CLI модели вътре в оградени кодови блокове на markdown файлове:

Скрипт: `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` се изпълнява при всяко push & PR.

Опционален hook за предварителен commit:
```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=[...])` (utility) | Помощните функции обработват първоначалното студено загряване на латентността |
| Измерване на латентност | `python -m session03.benchmark_oss_models` | `import benchmark_oss_models` (или нов скрипт за експорт) | Предпочитайте скрипт за последователни метрики |
| Спиране / разтоварване на модел | `foundry model unload <alias>` | (Не е изложено – рестартирайте услуга / процес) | Обикновено не е необходимо за работилницата |
| Получаване на използване на токени | (гледайте изхода) | `resp.usage.total_tokens` | Предоставено, ако бекендът връща обект за използване |

## Експорт на бенчмарк в Markdown

Използвайте скрипта `Workshop/scripts/export_benchmark_markdown.py`, за да стартирате нов бенчмарк (същата логика като `samples/session03/benchmark_oss_models.py`) и да генерирате таблица в Markdown, подходяща за 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` | Таблица в Markdown + насоки за интерпретация |
| `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 -->