generative-ai-for-beginners / uk

# AGENTS.md

## Огляд проєкту

Цей репозиторій містить комплексну програму з 21 уроку, що навчає основам Генеративного ШІ та розробки застосунків. Курс розрахований на початківців і охоплює все від базових концепцій до створення готових до виробництва застосунків.

**Ключові технології:**
- Python 3.9+ із бібліотеками: `openai`, `python-dotenv`, `tiktoken`, `azure-ai-inference`, `pandas`, `numpy`, `matplotlib`
- TypeScript/JavaScript з Node.js та бібліотеками: `openai` (Azure OpenAI через v1 endpoint + 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
# Встановіть залежності на рівні root (для інструментів документації)
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` - назва розгортання моделі embeddings (стандарт курсу: `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 старіші моделі "mini" з підтримкою температури (`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 підтримує лише reinforcement fine-tuning (RFT), а не наведене там supervised fine-tuning (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 (направляйте клієнт на endpoint `/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 мають включати ідентифікатор відстеження: `?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 перевіряє:
   # - Несправні відносні шляхи
   # - Відсутні ID відстеження на шляхах
   # - Відсутні ID відстеження на 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. Переконайтеся, що всі URL Microsoft мають ідентифікатори відстеження
4. Перевірте валідність відносних посилань
5. Переконайтеся, що зображення правильно включені

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

- Використовуйте описові заголовки: `[Lesson 06] Виправлення помилки в прикладі Python` або `Оновлення README для уроку 08`
- Вказуйте номера issue, якщо є: `Fixes #123`

### Опис PR

- Поясніть, що було змінено і чому
- Додайте посилання на пов’язані issue
- Для змін коду вкажіть, які приклади були протестовані
- Для перекладів включайте усі файли для повного перекладу

### Вимоги до внесків

- Підпишіть 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 (ідентифікатори відстеження, відносні посилання)
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 ключі дійсні та не протерміновані
- Перевірте правильність endpoint 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 -->