# EdgeAI для начинающих - мастер-класс

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

---

## 🎯 Введение

Добро пожаловать на **EdgeAI для начинающих** — ваш практический гид по созданию интеллектуальных приложений, которые полностью работают на локальном оборудовании. Этот мастер-класс превращает теоретические концепции Edge AI в реальные навыки через постепенно усложняющиеся упражнения с использованием Microsoft Foundry Local и Small Language Models (SLMs).

### Почему этот мастер-класс?

**Революция Edge AI уже здесь**

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

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

**Но Edge AI отличается**

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

**Этот мастер-класс даст вам эти навыки**

За 6 сфокусированных сессий (~3 часа) вы пройдете путь от "Hello World" до развертывания готовых к производству мультиагентных систем — все локально на вашем устройстве.

---

## 📚 Цели обучения

После завершения мастер-класса вы сможете:

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

2. **Создавать приложения на основе ИИ**
   - Реализовать локальные завершения чатов, совместимые с OpenAI
   - Разрабатывать эффективные запросы для Small Language Models
   - Обрабатывать потоковые ответы для улучшения UX
   - Интегрировать локальные модели в существующие приложения

3. **Создавать системы RAG (Retrieval Augmented Generation)**
   - Реализовать семантический поиск с использованием эмбеддингов
   - Привязывать ответы 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 с ограниченными ресурсами
- Мобильные приложения с приоритетом оффлайн-режима
- Системы реального времени с низкой задержкой

✅ **Проектировать интеллектуальные архитектуры**
- Мультиагентные системы для сложных рабочих процессов
- Гибридные развертывания периферия-облако
- Оптимизированная инфраструктура ИИ

✅ **Возглавлять инициативы Edge AI**
- Оценивать целесообразность Edge AI для проектов
- Выбирать подходящие модели и фреймворки
- Проектировать масштабируемые локальные решения ИИ

---

## 🗺️ Структура мастер-класса

### Обзор сессий (6 сессий × 30 минут = 3 часа)

| Сессия | Тема | Фокус | Длительность |
|--------|------|-------|--------------|
| **1** | Начало работы с Foundry Local | Установка, проверка, первые завершения | 30 мин |
| **2** | Создание решений ИИ с RAG | Инженерия запросов, эмбеддинги, оценка | 30 мин |
| **3** | Модели с открытым исходным кодом | Поиск моделей, тестирование, выбор | 30 мин |
| **4** | Передовые модели | SLM vs LLM, оптимизация, фреймворки | 30 мин |
| **5** | Агенты на основе ИИ | Дизайн агентов, оркестрация, память | 30 мин |
| **6** | Модели как инструменты | Маршрутизация, цепочки, стратегии масштабирования | 30 мин |

---

## 🚀 Быстрый старт

### Предварительные требования

**Системные требования:**
- **ОС**: Windows 10/11, macOS 11+ или Linux (Ubuntu 20.04+)
- **ОЗУ**: минимум 8 ГБ, рекомендуется 16 ГБ+
- **Хранилище**: минимум 10 ГБ свободного места для моделей
- **ЦП**: современный процессор с поддержкой AVX2
- **ГП** (опционально): совместимый с 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
```

Использование веб-эндпоинта 

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

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

| Сессия | 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) | Оркестрация конвейера | ⭐⭐⭐ Продвинутый |

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

Полные руководства и справочные материалы:

| Документ | Описание | Использовать, когда |
|---------|----------|----------------------|
| [QUICK_START.md](./QUICK_START.md) | Руководство по быстрому старту | Начало с нуля |
| [QUICK_REFERENCE.md](./QUICK_REFERENCE.md) | Справочник команд и API | Нужны быстрые ответы |
| [FOUNDRY_SDK_QUICKREF.md](./FOUNDRY_SDK_QUICKREF.md) | Шаблоны и примеры SDK | Написание кода |
| [ENV_CONFIGURATION.md](./ENV_CONFIGURATION.md) | Руководство по переменным окружения | Настройка примеров |
| [notebooks/TROUBLESHOOTING.md](./notebooks/TROUBLESHOOTING.md) | Частые проблемы и их решения | Отладка проблем |

---

## 🎓 Рекомендации по пути обучения

### Для начинающих (3-4 часа)
1. ✅ Сессия 1: Начало работы (фокус на настройке и базовом чате)
2. ✅ Сессия 2: Основы RAG (пока пропустите оценку)
3. ✅ Сессия 3: Простое тестирование (только 2 модели)
4. ⏭️ Пока пропустите сессии 4-6
5. 🔄 Вернитесь к сессиям 4-6 после создания первого приложения

### Для разработчиков среднего уровня (3 часа)
1. ⚡ Сессия 1: Быстрая проверка настройки
2. ✅ Сессия 2: Полный конвейер RAG с оценкой
3. ✅ Сессия 3: Полный набор тестов
4. ✅ Сессия 4: Оптимизация моделей
5. ✅ Сессии 5-6: Фокус на архитектурных шаблонах

### Для продвинутых специалистов (2-3 часа)
1. ⚡ Сессии 1-3: Быстрый обзор и проверка
2. ✅ Сессия 4: Углубленная оптимизация
3. ✅ Сессия 5: Архитектура мультиагентных систем
4. ✅ Сессия 6: Шаблоны для производства и масштабирования
5. 🚀 Расширение: Создание пользовательской логики маршрутизации и гибридных развертываний

---

## Пакет сессий мастер-класса (сфокусированные 30‑минутные лаборатории)

Если вы следуете сокращенному формату из 6 сессий, используйте эти специализированные руководства (каждое соответствует и дополняет более широкую документацию модулей выше):

| Сессия мастер-класса | Руководство | Основной фокус |
|-----------------------|------------|----------------|
| 1 | [Session01-GettingStartedFoundryLocal](./Session01-GettingStartedFoundryLocal.md) | Установка, проверка, запуск phi & GPT-OSS-20B, ускорение |
| 2 | [Session02-BuildAISolutionsRAG](./Session02-BuildAISolutionsRAG.md) | Инженерия запросов, шаблоны 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) | Маршрутизация, цепочки, масштабирование пути к 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

В воркшопе используются только документированные и стабильные команды 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>` | Используйте скрипт бенчмарка + инструменты ОС (Диспетчер задач / `nvidia-smi`) |
| `foundry model benchmark ...` | `samples/session03/benchmark_oss_models.py` |

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

- Задержка, p95, токены/сек: `samples/session03/benchmark_oss_models.py`
- Задержка первого токена (потоковая передача): установите `BENCH_STREAM=1`
- Использование ресурсов: мониторы ОС (Диспетчер задач, 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` запускается при каждом пуше и 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")  # запускает загрузку/загрузку` | Менеджер выбирает лучший вариант, если алиас соответствует нескольким сборкам |
| Список каталога | `foundry model list` | `# используйте менеджер для каждого алиаса или поддерживайте известный список` | CLI агрегирует; SDK пока по алиасам |
| Список кэшированных моделей | `foundry cache list` | `manager.list_cached_models()` | После инициализации менеджера (любой алиас) |
| Получить URL конечной точки | (неявно) | `manager.endpoint` | Используется для создания клиента, совместимого с OpenAI |
| Разогрев модели | `foundry model run <alias>` затем первый запрос | `chat_once(alias, messages=[...])` (утилита) | Утилиты обрабатывают начальную задержку холодного старта |
| Измерение задержки | `python -m session03.benchmark_oss_models` | `import benchmark_oss_models` (или новый скрипт экспорта) | Предпочтительно использовать скрипт для согласованных метрик |
| Остановить / выгрузить модель | `foundry model unload <alias>` | (Не реализовано – перезапустите сервис / процесс) | Обычно не требуется для воркшопа |
| Получить использование токенов | (просмотр вывода) | `resp.usage.total_tokens` | Предоставляется, если бэкенд возвращает объект использования |

## Экспорт бенчмарка в 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 -->