# 🚀 Модуль 1: Основы Microsoft Foundry Toolkit

[![Duration](https://img.shields.io/badge/Duration-15%20minutes-blue.svg)]()
[![Difficulty](https://img.shields.io/badge/Difficulty-Beginner-green.svg)]()
[![Prerequisites](https://img.shields.io/badge/Prerequisites-VS%20Code-orange.svg)]()

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

К концу этого модуля вы сможете:
- ✅ Установить и настроить расширение Microsoft Foundry Toolkit для VS Code
- ✅ Навигировать по каталогу моделей и понимать различные источники моделей
- ✅ Использовать Playground для тестирования и экспериментов с моделями
- ✅ Создавать кастомных AI-агентов с помощью Agent Builder
- ✅ Сравнивать производительность моделей у разных провайдеров
- ✅ Применять лучшие практики по созданию подсказок (prompt engineering)

## 🧠 Введение в Microsoft Foundry Toolkit

**Расширение Microsoft Foundry Toolkit для VS Code** — это основной продукт Microsoft, который превращает VS Code в комплексную среду разработки AI. Оно сокращает разрыв между исследованием AI и практической разработкой, делая генеративный AI доступным для разработчиков с любым уровнем навыков.

### 🌟 Ключевые возможности

| Функция | Описание | Случай использования |
|---------|-------------|----------|
| **🗂️ Каталог моделей** | Доступ к более чем 100 моделям от GitHub, ONNX, OpenAI, Anthropic, Google | Поиск и выбор моделей |
| **🔌 Поддержка BYOM** | Интеграция своих моделей (локальных или удалённых) | Развёртывание кастомных моделей |
| **🎮 Интерактивный Playground** | Тестирование моделей в реальном времени с чат-интерфейсом | Быстрое прототипирование и тестирование |
| **📎 Мультимодальная поддержка** | Работа с текстом, изображениями и вложениями | Сложные AI-приложения |
| **⚡ Пакетная обработка** | Запуск нескольких подсказок одновременно | Эффективные рабочие процессы тестирования |
| **📊 Оценка моделей** | Встроенные метрики (F1, релевантность, сходство, когерентность) | Оценка производительности |

### 🎯 Почему важно Microsoft Foundry Toolkit

- **🚀 Ускоренная разработка**: от идеи до прототипа за минуты
- **🔄 Унифицированный рабочий процесс**: один интерфейс для множества AI-провайдеров
- **🧪 Простые эксперименты**: сравнивайте модели без сложных настроек
- **📈 Готовность к продакшену**: плавный переход от прототипа к развертыванию

## 🛠️ Требования и настройка

### 📦 Установка расширения Microsoft Foundry Toolkit

**Шаг 1: Доступ к магазину расширений**
1. Откройте Visual Studio Code
2. Перейдите в раздел Extensions (`Ctrl+Shift+X` или `Cmd+Shift+X`)
3. Найдите "Microsoft Foundry Toolkit"

**Шаг 2: Выбор версии**
- **🟢 Релиз**: рекомендуется для использования в продакшене
- **🔶 Предварительная версия**: ранний доступ к новым функциям

**Шаг 3: Установка и активация**

![Microsoft Foundry Toolkit Extension](../../../../translated_images/ru/aitkext.d28945a03eed003c.webp)

### ✅ Чек-лист для проверки
- [ ] Иконка Microsoft Foundry Toolkit отображается в боковой панели VS Code
- [ ] Расширение включено и активировано
- [ ] Нет ошибок установки в панели вывода

## 🧪 Практическое задание 1: Изучение моделей GitHub

**🎯 Цель**: Освоить каталог моделей и протестировать первую AI-модель

### 📊 Шаг 1: Навигация по каталогу моделей

Каталог моделей — это ваш вход в экосистему AI. Он объединяет модели от разных провайдеров, упрощая поиск и сравнение.

**🔍 Руководство по навигации:**

Нажмите на **MODELS - Catalog** в боковой панели Microsoft Foundry Toolkit

![Model Catalog](../../../../translated_images/ru/aimodel.263ed2be013d8fb0.webp)

**💡 Советы**: Ищите модели с конкретными возможностями, которые соответствуют вашему случаю использования (например, генерация кода, творческое письмо, анализ).

**⚠️ Важно**: модели, размещённые на GitHub (GitHub Models), бесплатны для использования, но имеют ограничения по количеству запросов и токенов. Чтобы получить доступ к моделям вне GitHub (например, внешним моделям через Azure AI или другие эндпоинты), потребуется указать соответствующий API-ключ или данные аутентификации.

### 🚀 Шаг 2: Добавление и настройка первой модели

**Стратегия выбора моделей:**
- **GPT-4.1**: лучше всего подходит для сложного рассуждения и анализа
- **Phi-4-mini**: лёгкая, быстрая модель для простых задач

**🔧 Процесс настройки:**
1. Выберите **OpenAI GPT-4.1** из каталога
2. Нажмите **Add to My Models** — модель будет зарегистрирована для использования
3. Выберите **Try in Playground** для запуска среды тестирования
4. Подождите инициализации модели (первоначальная настройка может занять некоторое время)

![Playground Setup](../../../../translated_images/ru/playground.dd6f5141344878ca.webp)

**⚙️ Параметры модели:**
- **Temperature**: регулирует креативность (0 = детерминированный, 1 = творческий)
- **Max Tokens**: максимальная длина ответа
- **Top-p**: ядерная выборка для разнообразия ответов

### 🎯 Шаг 3: Освоение интерфейса Playground

Playground — ваша лаборатория для экспериментов с AI. Вот как максимально эффективно её использовать:

**🎨 Лучшие практики prompt engineering:**
1. **Будьте конкретны**: чёткие, подробные инструкции дают лучшие результаты
2. **Добавляйте контекст**: включайте релевантную предысторию
3. **Используйте примеры**: показывайте модели, что вы хотите с помощью примеров
4. **Итерации**: улучшайте подсказки на основе первых результатов

**🧪 Тестовые сценарии:**
```markdown
# Example 1: Code Generation
"Write a Python function that calculates the factorial of a number using recursion. Include error handling and docstrings."

# Example 2: Creative Writing
"Write a professional email to a client explaining a project delay, maintaining a positive tone while being transparent about challenges."

# Example 3: Data Analysis
"Analyze this sales data and provide insights: [paste your data]. Focus on trends, anomalies, and actionable recommendations."
```

![Testing Results](../../../../translated_images/ru/result.1dfcf211fb359cf6.webp)

### 🏆 Сложное задание: сравнение производительности моделей

**🎯 Цель**: сравнить разные модели при одинаковых подсказках, чтобы понять их сильные стороны

**📋 Инструкции:**
1. Добавьте в рабочее пространство **Phi-4-mini**
2. Используйте одинаковую подсказку для GPT-4.1 и Phi-4-mini

![set](../../../../translated_images/ru/set.88132df189ecde2c.webp)

3. Сравните качество ответов, скорость и точность
4. Задокументируйте результаты в разделе с отчетами

![Model Comparison](../../../../translated_images/ru/compare.97746cd0f9074955.webp)

**💡 Ключевые моменты для анализа:**
- Когда использовать LLM против SLM
- Соотношение цены и производительности
- Специализированные возможности разных моделей

## 🤖 Практическое задание 2: Создание кастомных агентов с Agent Builder

**🎯 Цель**: создать специализированных AI-агентов под конкретные задачи и рабочие процессы

### 🏗️ Шаг 1: Понимание Agent Builder

Agent Builder — это ключевая фишка Microsoft Foundry Toolkit. Здесь вы создаёте целевые AI-ассистенты, которые объединяют мощь больших языковых моделей с кастомными инструкциями, специальными параметрами и узкоспециализированными знаниями.

**🧠 Компоненты архитектуры агента:**
- **Core Model**: базовая LLM (GPT-4, Groks, Phi и др.)
- **Системная подсказка**: задаёт личность и поведение агента
- **Параметры**: оптимизированные настройки для лучшей работы
- **Интеграция инструментов**: подключение к внешним API и MCP-сервисам
- **Память**: контекст беседы и сохранение сессий

![Agent Builder Interface](../../../../translated_images/ru/agentbuilder.25895b2d2f8c02e7.webp)

### ⚙️ Шаг 2: Глубокое погружение в конфигурацию агента

**🎨 Создание эффективных системных подсказок:**
```markdown
# Template Structure:
## Role Definition
You are a [specific role] with expertise in [domain].

## Capabilities
- List specific abilities
- Define scope of knowledge
- Clarify limitations

## Behavior Guidelines
- Response style (formal, casual, technical)
- Output format preferences
- Error handling approach

## Examples
Provide 2-3 examples of ideal interactions
```

*Разумеется, вы также можете использовать Generate System Prompt, чтобы AI помог вам сгенерировать и оптимизировать подсказки*

**🔧 Оптимизация параметров:**
| Параметр | Рекомендуемый диапазон | Случай использования |
|-----------|------------------|----------|
| **Temperature** | 0.1-0.3 | Технические/фактические ответы |
| **Temperature** | 0.7-0.9 | Творческие/мозговые штурмы |
| **Max Tokens** | 500-1000 | Краткие ответы |
| **Max Tokens** | 2000-4000 | Детальные объяснения |

### 🐍 Шаг 3: Практическое задание — агент по программированию на Python

**🎯 Задача**: создать специализированного помощника по Python

**📋 Этапы настройки:**

1. **Выбор модели**: выберите **Claude 3.5 Sonnet** (отлично подходит для кода)

2. **Дизайн системной подсказки**:
```markdown
# Python Programming Expert Agent

## Role
You are a senior Python developer with 10+ years of experience. You excel at writing clean, efficient, and well-documented Python code.

## Capabilities
- Write production-ready Python code
- Debug complex issues
- Explain code concepts clearly
- Suggest best practices and optimizations
- Provide complete working examples

## Response Format
- Always include docstrings
- Add inline comments for complex logic
- Suggest testing approaches
- Mention relevant libraries when applicable

## Code Quality Standards
- Follow PEP 8 style guidelines
- Use type hints where appropriate
- Handle exceptions gracefully
- Write readable, maintainable code
```

3. **Настройка параметров**:
   - Temperature: 0.2 (для консистентного и надёжного кода)
   - Max Tokens: 2000 (подробные объяснения)
   - Top-p: 0.9 (сбалансированная креативность)

![Python Agent Configuration](../../../../translated_images/ru/pythonagent.5e51b406401c165f.webp)

### 🧪 Шаг 4: Тестирование вашего Python-агента

**Тестовые сценарии:**
1. **Базовая функция**: «Создать функцию для поиска простых чисел»
2. **Сложный алгоритм**: «Реализовать бинарное дерево поиска с методами вставки, удаления и поиска»
3. **Реальная задача**: «Создать веб-скрейпер, который обрабатывает ограничение по частоте запросов и повторные попытки»
4. **Отладка**: «Исправить этот код [вставьте проблемный код]»

**🏆 Критерии успеха:**
- ✅ Код выполняется без ошибок
- ✅ Включена корректная документация
- ✅ Следование лучшим практикам Python
- ✅ Понятные объяснения
- ✅ Предложения по улучшению

## 🎓 Итоги Модуля 1 и дальнейшие шаги

### 📊 Проверка знаний

Проверьте себя:
- [ ] Можете ли вы объяснить различия между моделями в каталоге?
- [ ] Удалось ли вам создать и протестировать кастомного агента?
- [ ] Понимаете ли вы, как оптимизировать параметры для различных задач?
- [ ] Можете ли вы создавать эффективные системные подсказки?

### 📚 Дополнительные ресурсы

- **Документация Microsoft Foundry Toolkit**: [Официальная документация Microsoft](https://github.com/microsoft/vscode-ai-toolkit)
- **Руководство по созданию подсказок**: [Лучшие практики](https://platform.openai.com/docs/guides/prompt-engineering)
- **Модели в Microsoft Foundry Toolkit**: [Модели в разработке](https://github.com/microsoft/vscode-ai-toolkit/blob/main/doc/models.md)

**🎉 Поздравляем!** Вы освоили основы Microsoft Foundry Toolkit и готовы создавать более сложные AI-приложения!

### 🔜 Продолжить к следующему модулю

Готовы к более продвинутым возможностям? Перейдите к **[Модулю 2: Основы MCP с Microsoft Foundry Toolkit](../lab2/README.md)**, где вы узнаете, как:
- Подключать агентов к внешним инструментам с помощью Model Context Protocol (MCP)
- Создавать агентов для автоматизации браузера с Playwright
- Интегрировать MCP-серверы с вашими агентами Microsoft Foundry Toolkit
- Усиливать агентов с помощью внешних данных и возможностей

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**Отказ от ответственности**:
Этот документ был переведен с использованием сервиса машинного перевода [Co-op Translator](https://github.com/Azure/co-op-translator). Несмотря на наши усилия по обеспечению точности, имейте в виду, что автоматический перевод может содержать ошибки или неточности. Оригинальный документ на его исходном языке следует считать авторитетным источником. Для получения критически важной информации рекомендуется обратиться к профессиональному человеческому переводу. Мы не несем ответственности за любые недоразумения или неправильные толкования, возникшие в результате использования этого перевода.
<!-- CO-OP TRANSLATOR DISCLAIMER END -->