generative-ai-for-beginners / ru

# AGENTS.md

## Обзор проекта

Этот репозиторий содержит комплексный учебный курс из 21 урока, обучающий основам генеративного ИИ и разработке приложений. Курс предназначен для начинающих и охватывает всё — от базовых понятий до создания приложений, готовых к производству.

**Ключевые технологии:**
- Python 3.9+ с библиотеками: `openai`, `python-dotenv`, `tiktoken`, `azure-ai-inference`, `pandas`, `numpy`, `matplotlib`
- TypeScript/JavaScript с Node.js и библиотеками: `openai` (Azure OpenAI через v1 эндпоинт + Responses API), `@azure-rest/ai-inference` (Microsoft Foundry Models)
- Azure OpenAI Service, OpenAI API и Microsoft Foundry Models (GitHub Models выводятся из эксплуатации к концу июля 2026)
- Jupyter Notebooks для интерактивного обучения
- Dev Containers для единообразной среды разработки

**Структура репозитория:**
- 21 каталог с уроками, пронумерованными от 00 до 21, содержащими README, примеры кода и задания
- Многочисленные реализации: Python, TypeScript, а иногда примеры на .NET
- Каталог переводов с версиями на более чем 40 языках
- Централизованная конфигурация через файл `.env` (используйте `.env.copy` в качестве шаблона)

## Команды установки

### Первоначальная настройка репозитория

```bash
# Клонируйте репозиторий
git clone https://github.com/microsoft/generative-ai-for-beginners.git
cd generative-ai-for-beginners

# Скопируйте шаблон окружения
cp .env.copy .env
# Отредактируйте .env с вашими API ключами и конечными точками
```

### Настройка окружения Python

```bash
# Создать виртуальное окружение
python3 -m venv venv

# Активировать виртуальное окружение
# На macOS/Linux:
source venv/bin/activate
# На Windows:
venv\Scripts\activate

# Установить зависимости
pip install -r requirements.txt
```

### Настройка Node.js/TypeScript

```bash
# Установите зависимости на уровне корня (для инструментов документации)
npm install

# Для отдельных примеров TypeScript из уроков перейдите к конкретному уроку:
cd 06-text-generation-apps/typescript/recipe-app
npm install
```

### Настройка Dev Container (рекомендуется)

Репозиторий включает конфигурацию `.devcontainer` для GitHub Codespaces или VS Code Dev Containers:

1. Откройте репозиторий в GitHub Codespaces или VS Code с расширением Dev Containers
2. Dev Container автоматически:
   - Устанавливает зависимости Python из `requirements.txt`
   - Запускает скрипт post-create (`.devcontainer/post-create.sh`)
   - Настраивает ядро Jupyter

## Рабочий процесс разработки

### Переменные окружения

Все уроки, требующие доступ к API, используют переменные окружения, определённые в `.env`:

- `OPENAI_API_KEY` - для OpenAI API
- `AZURE_OPENAI_API_KEY` - для Azure OpenAI в Microsoft Foundry (Azure OpenAI Service теперь часть Microsoft Foundry: https://ai.azure.com)
- `AZURE_OPENAI_ENDPOINT` - URL эндпоинта Azure OpenAI (эндпоинт ресурса Foundry)
- `AZURE_OPENAI_DEPLOYMENT` - имя деплоймента модели для чат-комплишнов (по умолчанию для курса: `gpt-5-mini`)
- `AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT` - имя деплоймента модели для эмбеддингов (по умолчанию курса: `text-embedding-3-small`)
- `AZURE_OPENAI_API_VERSION` - версия API (по умолчанию: `2024-10-21`)
- `HUGGING_FACE_API_KEY` - для моделей Hugging Face
- `AZURE_INFERENCE_ENDPOINT` - эндпоинт Microsoft Foundry Models (мульти-провайдер каталог моделей)
- `AZURE_INFERENCE_CREDENTIAL` - ключ API Microsoft Foundry Models (заменяет устаревающий `GITHUB_TOKEN`)
- `AZURE_INFERENCE_CHAT_MODEL` - модель без механизмов рассуждений (например, `Llama-3.3-70B-Instruct`), используемая в примерах с `temperature`, поскольку у моделей с рассуждениями нет контроля семплирования

### Конвенции моделирования (важно)

- **Модель чата по умолчанию — `gpt-5-mini`** — актуальная, не устаревшая **модель рассуждений**. С 2026 года старые "мини"-модели с поддержкой температуры (`gpt-4o-mini`, `gpt-4.1-mini`) *устаревают*, так что в курсе стандартизируемся на семействе GPT-5.
- **Модели рассуждений не поддерживают `temperature` и `top_p`**, используют `max_output_tokens` (Responses API) / `max_completion_tokens` (чат-комплишны) вместо `max_tokens`. Не добавляйте `temperature`/`top_p`/`max_tokens` в примерах, вызывающих `gpt-5-mini`.
- **Для демонстрации `temperature`** примеры используют модель **Llama** (`Llama-3.3-70B-Instruct`) через эндпоинт Microsoft Foundry Models (`AZURE_INFERENCE_CHAT_MODEL`). Управляйте моделями рассуждений с помощью prompt engineering и контроля рассуждений, а не регуляторов семплирования.
- **Тонкая настройка (урок 18)** сохраняет `gpt-4.1-mini`: GPT-5 поддерживает только обучение с подкреплением (RFT), а не супервизированную тонкую настройку (SFT), показанную в уроке.
- Уроки 20 (Mistral) и 21 (Meta) сохраняют `temperature`/`max_tokens`, так как они ориентированы на модели Mistral/Llama, которые это поддерживают.

### Запуск примеров на Python

```bash
# Перейдите в каталог урока
cd 06-text-generation-apps/python

# Запустите скрипт на Python
python aoai-app.py
```

### Запуск примеров на TypeScript

```bash
# Перейти в каталог приложения TypeScript
cd 06-text-generation-apps/typescript/recipe-app

# Собрать код TypeScript
npm run build

# Запустить приложение
npm start
```

### Запуск Jupyter Notebooks

```bash
# Запустите Jupyter в корневой папке репозитория
jupyter notebook

# Или используйте VS Code с расширением Jupyter
```

### Работа с разными типами уроков

- **Уроки типа "Learn"**: фокус на документации README.md и концепциях
- **Уроки типа "Build"**: содержат рабочие примеры кода на Python и TypeScript
- Каждый урок имеет README.md с теорией, разбором кода и ссылками на видео

## Руководство по стилю кода

### Python

- Используйте `python-dotenv` для управления переменными окружения
- Импортируйте библиотеку `openai` для взаимодействия с API
- Используйте `pylint` для проверки качества (некоторые примеры содержат `# pylint: disable=all` для простоты)
- Следуйте конвенциям именования PEP 8
- Храните учётные данные API в файле `.env`, никогда не в коде

### TypeScript

- Используйте пакет `dotenv` для переменных окружения
- Конфигурация TypeScript в `tsconfig.json` для каждого приложения
- Используйте пакет `openai` для Azure OpenAI (клиент указывает на эндпоинт `/openai/v1/` и вызывает `client.responses.create`); используйте `@azure-rest/ai-inference` для Microsoft Foundry Models
- Используйте `nodemon` для разработки с авто-перезагрузкой
- Сначала сборка: `npm run build`, затем запуск: `npm start`

### Общие конвенции

- Держите примеры кода простыми и обучающими
- Включайте комментарии, объясняющие ключевые концепции
- Код каждого урока должен быть автономным и запускаемым
- Используйте единообразное именование: префикс `aoai-` для Azure OpenAI, `oai-` для OpenAI API, `githubmodels-` для Microsoft Foundry Models (наследованный префикс от эпохи GitHub Models)

## Руководство по документации

### Стиль Markdown

- Все URL должны быть оформлены в виде `[текст](../../url)` без лишних пробелов
- Относительные ссылки должны начинаться с `./` или `../`
- Все ссылки на домены Microsoft должны содержать ID отслеживания: `?WT.mc_id=academic-105485-koreyst`
- Избегайте локалей, специфичных для страны, в URL (избегайте `/en-us/`)
- Изображения храните в папке `./images` с описательными именами
- Используйте в названиях файлов английские буквы, цифры и дефисы

### Поддержка переводов

- Репозиторий поддерживает более 40 языков с помощью автоматизированных GitHub Actions
- Переводы хранятся в каталоге `translations/`
- Не отправляйте частичные переводы
- Машинные переводы не принимаются
- Переведённые изображения хранятся в каталоге `translated_images/`

## Тестирование и проверка

### Проверки перед отправкой

Этот репозиторий использует GitHub Actions для проверки. Перед отправкой PR:

1. **Проверьте Markdown ссылки**:
   ```bash
   # Рабочий процесс validate-markdown.yml проверяет:
   # - Неверные относительные пути
   # - Отсутствие идентификаторов отслеживания в путях
   # - Отсутствие идентификаторов отслеживания в URL
   # - URL с локалью страны
   # - Неверные внешние URL
   ```

2. **Ручное тестирование**:
   - Тестируйте примеры на Python: активируйте venv и запускайте скрипты
   - Тестируйте примеры на TypeScript: `npm install`, `npm run build`, `npm start`
   - Проверьте правильность настройки переменных окружения
   - Убедитесь, что ключи API работают с примерами кода

3. **Примеры кода**:
   - Убедитесь, что весь код запускается без ошибок
   - Тестируйте с Azure OpenAI и OpenAI API, если применимо
   - Проверьте работу примеров с Microsoft Foundry Models там, где поддерживается

### Отсутствие автоматизированных тестов

Это образовательный репозиторий, сосредоточенный на учебных материалах и примерах. Здесь нет юнит-тестов или интеграционных тестов. Проверка основана на:
- Ручном тестировании примеров кода
- GitHub Actions для проверки Markdown
- Общественном обзоре учебного контента

## Руководство по Pull Request

### Перед отправкой

1. Тестируйте изменения кода и в Python, и в TypeScript, когда это применимо
2. Запустите проверку Markdown (автоматически при PR)
3. Убедитесь, что в Microsoft URL есть ID отслеживания
4. Проверьте корректность относительных ссылок
5. Проверьте правильность ссылок на изображения

### Формат заголовка PR

- Используйте описательные заголовки: `[Lesson 06] Исправление опечатки в примере Python` или `Обновление README для урока 08`
- Ссылайтесь на номера задач при необходимости: `Fixes #123`

### Описание PR

- Объясните, что и почему изменилось
- Добавьте ссылки на связанные задачи
- Для изменений кода укажите, какие примеры были протестированы
- Для PR с переводами включите все файлы для полного перевода

### Требования к участию

- Подпишите Microsoft CLA (автоматически при первом PR)
- Форкните репозиторий в свой аккаунт перед изменениями
- Один PR на одно логическое изменение (не объединяйте разные исправления)
- По возможности делайте PR чёткими и маленькими

## Частые процессы

### Добавление нового примера кода

1. Перейдите в нужный каталог урока
2. Создайте пример в подкаталоге `python/` или `typescript/`
3. Следуйте соглашениям именования: `{provider}-{example-name}.{py|ts|js}`
4. Тестируйте с реальными учётными данными API
5. Задокументируйте новые переменные окружения в README урока

### Обновление документации

1. Отредактируйте README.md в каталоге урока
2. Следуйте руководству по Markdown (ID отслеживания, относительные ссылки)
3. Обновление переводов выполняется GitHub Actions (не редактируйте вручную)
4. Проверьте, что все ссылки корректны

### Работа с Dev Containers

1. Репозиторий содержит файл `.devcontainer/devcontainer.json`
2. Скрипт post-create автоматически устанавливает зависимости Python
3. Преднастроены расширения для Python и Jupyter
4. Среда основана на `mcr.microsoft.com/devcontainers/universal:2.11.2`

## Развёртывание и публикация

Это обучающий репозиторий — процесса развёртывания нет. Курс используется через:

1. **GitHub репозиторий**: прямой доступ к коду и документации
2. **GitHub Codespaces**: мгновенная среда разработки с предустановленной настройкой
3. **Microsoft Learn**: контент может быть размещён на официальной образовательной платформе
4. **docsify**: сайт документации, построенный из Markdown (см. `docsifytopdf.js` и `package.json`)

### Создание сайта документации

```bash
# Создать PDF из документации (если необходимо)
npm run convert
```

## Устранение неполадок

### Распространённые проблемы

**Ошибки импорта Python**:
- Убедитесь, что виртуальное окружение активировано
- Выполните `pip install -r requirements.txt`
- Проверьте, что версия Python 3.9+

**Ошибки сборки TypeScript**:
- Выполните `npm install` в каталоге конкретного приложения
- Проверьте совместимость версии Node.js
- Очистите `node_modules` и переустановите при необходимости

**Ошибки аутентификации API**:
- Проверьте наличие и корректность файла `.env`
- Удостоверьтесь, что ключи API действительны и не просрочены
- Проверьте правильность URL эндпоинтов для вашего региона

**Отсутствуют переменные окружения**:
- Скопируйте `.env.copy` в `.env`
- Заполните все необходимые значения для текущего урока
- Перезапустите приложение после обновления `.env`

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

- [Руководство по настройке курса](./00-course-setup/README.md?WT.mc_id=academic-105485-koreyst)
- [Руководство по участию в проекте](./CONTRIBUTING.md)
- [Кодекс поведения](./CODE_OF_CONDUCT.md)
- [Политика безопасности](./SECURITY.md)
- [Azure AI Discord](https://aka.ms/genai-discord?WT.mc_id=academic-105485-koreyst)
- [Коллекция продвинутых примеров кода](https://aka.ms/genai-beg-code?WT.mc_id=academic-105485-koreyst)

## Особые примечания по проекту

- Это **образовательный репозиторий**, ориентированный на обучение, а не на производственный код
- Примеры намеренно просты и ориентированы на объяснение концепций
- Качество кода сбалансировано с ясностью обучения
- Каждый урок автономен и может быть выполнен независимо
- Репозиторий поддерживает несколько провайдеров API: Azure OpenAI, OpenAI, Microsoft Foundry Models и офлайн провайдеры, такие как Foundry Local и Ollama
- Контент многоязычен с автоматизированными рабочими процессами перевода
- Активное сообщество в Discord для вопросов и поддержки

---

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