generative-ai-for-beginners / bg

# AGENTS.md

## Преглед на проекта

Това хранилище съдържа обширна учебна програма от 21 урока, която преподава основите на Генеративния AI и разработката на приложения. Курсът е предназначен за начинаещи и обхваща всичко от базови концепции до изграждане на приложения готови за продукция.

**Ключови технологии:**
- 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 модели)
- Azure OpenAI Service, OpenAI API и Microsoft Foundry модели (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`
   - Стартира скрипт след създаване (`.devcontainer/post-create.sh`)
   - Конфигурира Jupyter kernel

## Работен процес на разработката

### Променливи на средата

Всички уроци, изискващи достъп до 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 endpoint (endpoint на Foundry ресурса)
- `AZURE_OPENAI_DEPLOYMENT` - Име на deployment за чат модел (по подразбиране за курса: `gpt-5-mini`)
- `AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT` - Име на deployment за ембединг модел (по подразбиране за курса: `text-embedding-3-small`)
- `AZURE_OPENAI_API_VERSION` - Версия на API (по подразбиране: `2024-10-21`)
- `HUGGING_FACE_API_KEY` - За Hugging Face модели
- `AZURE_INFERENCE_ENDPOINT` - Endpoint на Microsoft Foundry Models (много-провайдърски каталог модели)
- `AZURE_INFERENCE_CREDENTIAL` - API ключ на Microsoft Foundry Models (замества прекратения `GITHUB_TOKEN`)
- `AZURE_INFERENCE_CHAT_MODEL` - Модел без reasoning (например `Llama-3.3-70B-Instruct`), използван в примери с `temperature`, тъй като reasoning моделите не поддържат контрол на семплирането

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

- **По подразбиране чат модел е `gpt-5-mini`** - актуален, неотхвърлен **reasoning** модел. Към 2026 по-старите mini модели с температурно управление (`gpt-4o-mini`, `gpt-4.1-mini`) се *оттеглят*, затова учебната програма стандартизира върху семейство GPT-5.
- **Reasoning моделите отказват `temperature` и `top_p`**, и използват `max_output_tokens` (Responses API) / `max_completion_tokens` (chat completions) вместо `max_tokens`. Не добавяйте `temperature`/`top_p`/`max_tokens` към примери, които използват `gpt-5-mini`.
- **За демонстрация на `temperature`**, в примерите се използва **Llama** модел (`Llama-3.3-70B-Instruct`) чрез Microsoft Foundry Models endpoint (`AZURE_INFERENCE_CHAT_MODEL`). За контрол на reasoning модели използвайте prompt engineering + reasoning контроли, а не настройки за семплиране.
- **Файн-тюнинг (урок 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
```

### Работа с различни видове уроци

- **Уроци за "Научаване"**: Фокус върху документацията README.md и концепции
- **Уроци за "Изграждане"**: Включват работещи примери с код на 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/` endpoint и използвайте `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 адреси трябва да са във формат `[text](../../url)` без допълнителни интервали
- Относителните връзки трябва да започват с `./` или `../`
- Всички връзки към Microsoft домейни трябва да включват tracking ID: `?WT.mc_id=academic-105485-koreyst`
- Без локали специфични за държави в URL (избягвайте `/en-us/`)
- Изображенията се съхраняват в папка `./images` с описателни имена
- Използвайте английски символи, цифри и тирета в имената на файловете

### Поддръжка на преводи

- Хранилището поддържа 40+ езика чрез автоматизирани GitHub Actions
- Преводите се съхраняват в директория `translations/`
- Не изпращайте частични преводи
- Машинните преводи не се приемат
- Преведените изображения се съхраняват в директория `translated_images/`

## Тестване и валидация

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

Това хранилище използва GitHub Actions за валидация. Преди да изпратите Pull Request:

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 там, където са поддържани

### Няма автоматизирани тестове

Това е образователно хранилище, фокусирано върху уроци и примери. Няма налични unit тестове или интеграционни тестове за изпълнение. Валидацията е основно:
- Ръчно тестване на примерите
- GitHub Actions за проверка на Markdown
- Общностна проверка на образователното съдържание

## Насоки за Pull Request

### Преди подаване

1. Тествайте промените в код и на Python, и на TypeScript, ако е приложимо
2. Стартирайте проверка на Markdown (задейства се автоматично при PR)
3. Уверете се, че tracking ID-та са налични на всички Microsoft URL адреси
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 насоките (tracking ID, относителни връзки)
3. Преводите се обновяват автоматично чрез GitHub Actions (не редактирайте ръчно)
4. Тествайте дали всички връзки са валидни

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

1. Хранилището включва `.devcontainer/devcontainer.json`
2. Скриптът след създаване автоматично инсталира 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 адресите на endpoint-ите са правилни за вашия регион

**Липсващи променливи на средата**:
- Копирайте `.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 -->
**Отказ от отговорност**:
Този документ е преведен с помощта на AI преводачески услуга [Co-op Translator](https://github.com/Azure/co-op-translator). Въпреки че се стремим към точност, моля имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за каквито и да е недоразумения или неправилни тълкувания, произтичащи от използването на този превод.
<!-- CO-OP TRANSLATOR DISCLAIMER END -->