# EdgeAI для початківців - Воркшоп

> **Практичний навчальний шлях для створення готових до виробництва додатків Edge AI**
>
> Опановуйте локальне розгортання AI за допомогою Microsoft Foundry Local, від першого чату до оркестрації мультиагентних систем у 6 прогресивних сесіях.

---

## 🎯 Вступ

Ласкаво просимо до **Воркшопу EdgeAI для початківців** - вашого практичного посібника зі створення інтелектуальних додатків, які працюють виключно на локальному обладнанні. Цей воркшоп перетворює теоретичні концепції Edge AI у реальні навички через поступово складні вправи з використанням Microsoft Foundry Local та Малих мовних моделей (SLMs).

### Чому цей воркшоп?

**Революція Edge AI вже тут**

Організації по всьому світу переходять від залежності від хмарних технологій до обчислень на периферії з трьох ключових причин:

1. **Конфіденційність та відповідність вимогам** - Обробка конфіденційних даних локально без передачі в хмару (HIPAA, GDPR, фінансові регуляції)
2. **Продуктивність** - Усунення затримок мережі (50-500 мс локально проти 500-2000 мс хмарного обміну)
3. **Контроль витрат** - Усунення витрат на API за токен та масштабування без хмарних витрат

**Але Edge AI має свої особливості**

Запуск AI на локальних пристроях вимагає нових навичок:
- Вибір та оптимізація моделей для обмежених ресурсів
- Управління локальними сервісами та апаратним прискоренням
- Інженерія запитів для менших моделей
- Шаблони розгортання для пристроїв на периферії

**Цей воркшоп надає ці навички**

У 6 сфокусованих сесіях (~3 години загалом) ви пройдете шлях від "Hello World" до розгортання готових до виробництва мультиагентних систем - усе локально на вашому комп'ютері.

---

## 📚 Навчальні цілі

Після завершення воркшопу ви зможете:

### Основні компетенції
1. **Розгортати та управляти локальними AI сервісами**
   - Встановлювати та налаштовувати Microsoft Foundry Local
   - Вибирати відповідні моделі для розгортання на периферії
   - Управляти життєвим циклом моделей (завантаження, завантаження, кешування)
   - Моніторити використання ресурсів та оптимізувати продуктивність

2. **Створювати додатки на основі AI**
   - Реалізовувати локальні чат-комплети, сумісні з OpenAI
   - Розробляти ефективні запити для Малих мовних моделей
   - Обробляти потокові відповіді для покращення UX
   - Інтегрувати локальні моделі в існуючі додатки

3. **Створювати системи RAG (генерація з розширеним пошуком)**
   - Створювати семантичний пошук за допомогою векторів
   - Основа відповідей LLM на знаннях, специфічних для домену
   - Оцінювати якість RAG за галузевими стандартами
   - Масштабувати від прототипу до виробництва

4. **Оптимізувати продуктивність моделей**
   - Проводити тестування кількох моделей для вашого випадку використання
   - Вимірювати затримку, пропускну здатність та час першого токена
   - Вибирати оптимальні моделі на основі компромісу між швидкістю та якістю
   - Порівнювати SLM та LLM у реальних сценаріях

5. **Організовувати мультиагентні системи**
   - Розробляти спеціалізованих агентів для різних завдань
   - Реалізовувати пам'ять агентів та управління контекстом
   - Координувати агентів у складних робочих процесах
   - Інтелектуально розподіляти запити між кількома моделями

6. **Розгортати готові до виробництва рішення**
   - Реалізовувати обробку помилок та логіку повторних спроб
   - Моніторити використання токенів та системних ресурсів
   - Створювати масштабовані архітектури з використанням моделей як інструментів
   - Планувати шляхи міграції від периферії до гібридних рішень (периферія + хмара)

---

## 🎓 Результати навчання

### Що ви створите

До кінця воркшопу ви створите:

| Сесія | Результат | Продемонстровані навички |
|-------|-----------|--------------------------|
| **1** | Чат-додаток з потоковою передачею | Налаштування сервісу, базові комплети, UX потокової передачі |
| **2** | Система RAG з оцінкою | Вектори, семантичний пошук, метрики якості |
| **3** | Набір тестування багатьох моделей | Вимірювання продуктивності, порівняння моделей |
| **4** | Порівняння SLM та LLM | Аналіз компромісів, стратегії оптимізації |
| **5** | Мультиагентний оркестратор | Дизайн агентів, управління пам'яттю, координація |
| **6** | Інтелектуальна система маршрутизації | Визначення намірів, вибір моделі, масштабованість |

### Матриця компетенцій

| Рівень навичок | Сесія 1-2 | Сесія 3-4 | Сесія 5-6 |
|----------------|-----------|-----------|-----------|
| **Початківець** | ✅ Налаштування та основи | ⚠️ Складно | ❌ Занадто складно |
| **Середній рівень** | ✅ Швидкий огляд | ✅ Основне навчання | ⚠️ Цілі для розширення |
| **Просунутий рівень** | ✅ Легко пройти | ✅ Удосконалення | ✅ Шаблони для виробництва |

### Навички для кар'єри

**Після цього воркшопу ви будете готові:**

✅ **Створювати додатки з пріоритетом конфіденційності**
- Медичні додатки, які обробляють PHI/PII локально
- Фінансові сервіси з вимогами відповідності
- Урядові системи з потребами в суверенітеті даних

✅ **Оптимізувати для периферійних середовищ**
- IoT-пристрої з обмеженими ресурсами
- Мобільні додатки з офлайн-першим підходом
- Системи реального часу з низькою затримкою

✅ **Проектувати інтелектуальні архітектури**
- Мультиагентні системи для складних робочих процесів
- Гібридні розгортання периферія-хмара
- Оптимізована 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, ви можете зробити запит до кінцевої точки моделей:

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

Використання веб-інтерфейсу 

```bash
# Windows PowerShell
powershell -Command "Invoke-RestMethod -Uri 'http://127.0.0.1:58123/v1/models' -Method Get"

# Or using curl (if available)
curl http://127.0.0.1:58123/v1/models
```

#### 2. Клонування репозиторію та встановлення залежностей

```bash
# Clone repository
git clone https://github.com/microsoft/edgeai-for-beginners.git
cd edgeai-for-beginners/Workshop

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# Windows:
.\.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt
```

#### 3. Запустіть ваш перший приклад

```bash
# Start Foundry Local and load a model
foundry model run phi-4-mini

# Run the chat bootstrap sample
cd samples
python -m session01.chat_bootstrap "What is edge AI?"
```

**✅ Успіх!** Ви повинні побачити потокову відповідь про Edge AI.

---

## 📦 Ресурси воркшопу

### Приклади на Python

Поступові практичні приклади, що демонструють кожну концепцію:

| Сесія | Приклад | Опис | Час виконання |
|-------|--------|------|---------------|
| 1 | [`chat_bootstrap.py`](../../../Workshop/samples/session01/chat_bootstrap.py) | Базовий чат та потокова передача | ~30с |
| 2 | [`rag_pipeline.py`](../../../Workshop/samples/session02/rag_pipeline.py) | RAG з векторами | ~45с |
| 2 | [`rag_eval_ragas.py`](../../../Workshop/samples/session02/rag_eval_ragas.py) | Оцінка якості RAG | ~60с |
| 3 | [`benchmark_oss_models.py`](../../../Workshop/samples/session03/benchmark_oss_models.py) | Тестування багатьох моделей | ~2-3хв |
| 4 | [`model_compare.py`](../../../Workshop/samples/session04/model_compare.py) | Порівняння SLM та LLM | ~45с |
| 5 | [`agents_orchestrator.py`](../../../Workshop/samples/session05/agents_orchestrator.py) | Мультиагентна система | ~60с |
| 6 | [`models_router.py`](../../../Workshop/samples/session06/models_router.py) | Маршрутизація на основі намірів | ~45с |
| 6 | [`models_pipeline.py`](../../../Workshop/samples/session06/models_pipeline.py) | Багатокрокова конвеєрна система | ~60с |

### Jupyter 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-BuildAIS
| 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 за метриками 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 + інструменти ОС (Task Manager / `nvidia-smi`) |
| `foundry model benchmark ...` | `samples/session03/benchmark_oss_models.py` |

### Бенчмаркінг та телеметрія

- Затримка, p95, токени/сек: `samples/session03/benchmark_oss_models.py`
- Затримка першого токена (стрімінг): встановіть `BENCH_STREAM=1`
- Використання ресурсів: монітори ОС (Task Manager, Activity Monitor, `nvidia-smi`).

Як тільки нові команди телеметрії CLI стабілізуються, їх можна буде інтегрувати з мінімальними змінами до файлів сесій.

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

Автоматичний лінтер запобігає повторному введенню застарілих 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.

Опціональний pre-commit hook:
```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` | Надається, якщо бекенд повертає об'єкт використання |

## Експорт бенчмаркінгу в 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 -->
**Відмова від відповідальності**:  
Цей документ був перекладений за допомогою сервісу автоматичного перекладу [Co-op Translator](https://github.com/Azure/co-op-translator). Хоча ми прагнемо до точності, будь ласка, майте на увазі, що автоматичні переклади можуть містити помилки або неточності. Оригінальний документ на його рідній мові слід вважати авторитетним джерелом. Для критичної інформації рекомендується професійний людський переклад. Ми не несемо відповідальності за будь-які непорозуміння або неправильні тлумачення, що виникають внаслідок використання цього перекладу.
<!-- CO-OP TRANSLATOR DISCLAIMER END -->