PhiCookBook / sr

# AGENTS.md

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

PhiCookBook је свеобухватан репозиторијум куварица који садржи практичне примере, туторијале и документацију за рад са Microsoft-овом Phi породицом малих језичких модела (SLM). Репозиторијум демонстрира разне случајеве употребе укључујући инференцију, фино подешавање, квантовање, имплементације RAG-а и мултимодалне апликације на различитим платформама и оквирима.

**Кључне технологије:**
- **Језици:** Python, C#/.NET, JavaScript/Node.js
- **Оквири:** ONNX Runtime, PyTorch, Transformers, MLX, OpenVINO, Semantic Kernel
- **Платформе:** Microsoft Foundry, GitHub Models, Hugging Face, Ollama
- **Типови модела:** Phi-3, Phi-3.5, Phi-4 (текст, визија, мултимодалне, варијанте за разлоговање)

**Структура репозиторијума:**
- `/code/` - Радни код и пример имплементација
- `/md/` - Детаљна документација, туторијали и водичи  
- `/translations/` - Преводи на више језика (50+ језика преко аутоматизованог процеса)
- `/.devcontainer/` - Конфигурација дев контејнера (Python 3.12 са Ollama)

## Подешавање развојног окружења

### Коришћење GitHub Codespaces или Dev Containers (препоручено)

1. Отворите у GitHub Codespaces (најбрже):
   - Кликните на ознаку "Open in GitHub Codespaces" у README
   - Контейнер се аутоматски конфигурише са Python 3.12 и Ollama Phi-3

2. Отворите у VS Code Dev Containers:
   - Користите ознаку "Open in Dev Containers" из README
   - Контейнер захтева минимум 16GB меморије на хосту

### Локално подешавање

**Претходни услови:**
- Python 3.12 или новији
- .NET 8.0 SDK (за C# примере)
- Node.js 18+ и npm (за JavaScript примере)
- Препоручено минимум 16GB RAM

**Инсталација:**
```bash
git clone https://github.com/microsoft/PhiCookBook.git
cd PhiCookBook
```

**За Python примере:**
Уђите у директоријуме са примерима и инсталирајте зависности:
```bash
cd code/<example-directory>
pip install -r requirements.txt  # ако постоји requirements.txt
```

**За .NET примере:**
```bash
cd md/04.HOL/dotnet/src
dotnet restore LabsPhi.sln
dotnet build LabsPhi.sln
```

**За JavaScript/Web примере:**
```bash
cd code/08.RAG/rag_webgpu_chat
npm install
npm run dev  # Покрени сервер за развој
npm run build  # Креирај за продукцију
```

## Организација репозиторијума

### Код примери (`/code/`)

- **01.Introduce/** - Основни уводи и почетни узорци
- **03.Finetuning/** и **04.Finetuning/** - Примери фино подешавања са разним методама
- **03.Inference/** - Примери инференције на различитом хардверу (AIPC, MLX)
- **06.E2E/** - Узроци апликација крај-до-краја
- **07.Lab/** - Лабораторијске/експерименталне имплементације
- **08.RAG/** - Узроци Retrieval-Augmented Generation
- **09.UpdateSamples/** - Најновији ажурирани узорци

### Документација (`/md/`)

- **01.Introduction/** - Уводни водичи, подешавање окружења, водичи за платформу
- **02.Application/** - Примери апликација по типу (Текст, Код, Визија, Аудио итд.)
- **02.QuickStart/** - Брзи почетак за Microsoft Foundry и GitHub Models
- **03.FineTuning/** - Документација и туторијали за фино подешавање
- **04.HOL/** - Практичне лабораторије (укључујући .NET примере)

### Формати фајлова

- **Jupyter notebooks (`.ipynb`)** - Интерактивни Python туторијали означени 📓 у README
- **Python скрипте (`.py`)** - Самостални Python примери
- **C# пројекти (`.csproj`, `.sln`)** - .NET апликације и узорци
- **JavaScript (`.js`, `package.json`)** - Веб и Node.js примери
- **Markdown (`.md`)** - Документација и водичи

## Рад са примерима

### Покретање Jupyter ноутбука

Већина примера доступна као Jupyter ноутбуци:
```bash
pip install jupyter notebook
jupyter notebook  # Отвара интерфејс прегледача
# Идите до жељене .ipynb датотеке
```

### Покретање Python скрипти

```bash
cd code/<example-directory>
pip install -r requirements.txt
python <script-name>.py
```

### Покретање .NET примера

```bash
cd md/04.HOL/dotnet/src/<project-name>
dotnet run
```

Или примените комплетно решење:
```bash
cd md/04.HOL/dotnet/src
dotnet run --project <project-name>
```

### Покретање JavaScript/Web примера

```bash
cd code/08.RAG/rag_webgpu_chat
npm install
npm run dev  # Развој са хотрелоад-ом
```

## Тестирање

Овај репозиторијум садржи пример кодове и туторијале уместо традиционалног софтверског пројекта са јединичним тестовима. Валидација се обично врши кроз:

1. **Покретање примера** - Сваки пример треба да се изврши без грешака
2. **Провера излаза** - Проверите да одговори модела одговарају очекивањима
3. **Праћење туторијала** - Водичи треба да функционишу како је описано

**Уобичајени приступ валидацији:**
- Тестирање покретања примера у циљаном окружењу
- Верификација исправне инсталације зависности
- Провера да ли се модели успешно скидају/учитавају
- Потврда да очекивано понашање одговара документацији

## Стил кода и конвенције

### Општа упутства

- Примери треба да буду јасни, добро коментарисани и едукативни
- Пратите језичке конвенције (PEP 8 за Python, C# стандарде за .NET)
- Примери треба да буду фокусирани на демонстрирање специфичних могућности Phi модела
- Укључите коментаре који објашњавају кључне концепте и параметре специфичне за модел

### Стандарди за документацију

**Форматирање URL-ова:**
- Користите формат `[text](../../url)` без додатних размака
- Релативне везе: користите `./` за тренутни директоријум, `../` за родитељски
- Без специфичних локала у URL-овима (избегавајте `/en-us/`, `/en/`)

**Слике:**
- Све слике смештати у директоријум `/imgs/`
- Користити описна имена са енглеским знацима, бројевима и цртицама
- Пример: `phi-3-architecture.png`

**Markdown фајлови:**
- Реферисање стварних радних примера у директоријуму `/code/`
- Документација треба да буде синхронизована са променама кода
- Користите 📓 емоџи за означавање Jupyter notebook линкова у README

### Организација фајлова

- Код примери у `/code/` организовани по темама/функцијама
- Документација у `/md/` прати структуру кода кад год је применљиво
- Одржавајте повезане фајлове (ноутбукови, скрипте, конфигурације) заједно у поддиректоријумима

## Упутства за Pull Request

### Пре слања

1. **Форкујте репозиторијум** у свој налог
2. **Одвојите PR-ове по типу:**
   - Поправке грешака у једном PR-у
   - Ажурирања документације у другом
   - Нови примери у посебним PR-овима
   - Поправке типографских грешака могу бити комбиноване

3. **Решавање конфликата приликом спајања:**
   - Ажурирајте свој локални `main` пре измена
   - Учестало синхронизујте са upstream

4. **PR-ови за превод:**
   - Морају садржати преводе за СВЕ фајлове у фасцикли
   - Одржавајте структуру конзистентну са оригиналом

### Обавезне провере

PR-ови аутоматски покрећу GitHub радне токове за валидацију:

1. **Валидација релативних путева** - Све унутрашње везе морају радити
   - Тестирајте линкове локално: Ctrl+Click у VS Code
   - Користите предложене путеве из VS Code (`./` или `../`)

2. **Провера URL локала** - Web URL-ови не смеју садржати локалне ознаке земаља
   - Уклоните `/en-us/`, `/en/` или друге језичке шифре
   - Користите опште међународне URL-ове

3. **Провера нерадних URL-ова** - Сви URL-ови морају враћати статус 200
   - Проверите да су линкови доступни пре слања
   - Напомена: неки неуспеси могу бити узроковани мрежним ограничењима

### Формат наслова PR-а

```
[component] Brief description
```

Примери:
- `[docs] Add Phi-4 inference tutorial`
- `[code] Fix ONNX Runtime integration example`
- `[translation] Add Japanese translation for intro guides`

## Уобичајени модели развоја

### Рад са Phi моделима

**Учитавање модела:**
- Примери користе разне оквире: Transformers, ONNX Runtime, MLX, OpenVINO
- Модели се обично скидају са Hugging Face, Azure или GitHub Models
- Проверите компатибилност модела са вашим хардвером (CPU, GPU, NPU)

**Обрасци инференције:**
- Генерација текста: већина примера користи чат/инструкт варијанте
- Визија: Phi-3-vision и Phi-4-мултимодал за разумевање слика
- Аудио: Phi-4-мултимодал подржава аудио уносе
- Разлоговање: Phi-4-reasoning варијанте за напредне задатке разлоговања

### Напомене специфичне за платформу

**Microsoft Foundry:**
- Захтева Azure претплату и API кључеве
- Види `/md/02.QuickStart/AzureAIFoundry_QuickStart.md`

**GitHub Models:**
- Бесплатни ниво доступан за тестирање
- Види `/md/02.QuickStart/GitHubModel_QuickStart.md`

**Локална инференција:**
- ONNX Runtime: крос-платформска, оптимизована инференција
- Ollama: једноставно локално управљање моделима (пред-конфигурисан у дев контејнеру)
- Apple MLX: оптимизован за Apple Silicon

## Решавање проблема

### Уобичајени проблеми

**Проблеми са меморијом:**
- Phi модели захтевају значајан RAM (посебно визијски/мултимодални)
- Користите квантоване моделе у окружењима са ограниченим ресурсима
- Види `/md/01.Introduction/04/QuantifyingPhi.md`

**Конфликти зависности:**
- Python примери могу имати специфичне захтеве за верзије
- Користите виртуелна окружења за сваки пример
- Проверите појединачне фајлове `requirements.txt`

**Проблеми приликом скидања модела:**
- Велики модели могу имати временско ограничење на спорим конекцијама
- Размислите о коришћењу облачних окружења (Codespaces, Azure)
- Проверите Hugging Face кеш: `~/.cache/huggingface/`

**Проблеми са .NET пројектима:**
- Осигурајте да је инсталиран .NET 8.0 SDK
- Користите `dotnet restore` пре изградње
- Неки пројекти имају CUDA-специфичне конфигурације (Debug_Cuda)

**JavaScript/Web примери:**
- Користите Node.js 18+ ради компатибилности
- Обришите `node_modules` и поново инсталирајте ако проблеми трају
- Проверите конзолу прегледача због проблема са WebGPU

### Где тражити помоћ

- **Discord:** Придружите се Microsoft Foundry Community Discord-у
- **GitHub Issues:** Пријавите грешке и проблеме у репозиторијуму
- **GitHub Discussions:** Постављајте питања и делите знање

## Додатни контекст

### Одговорни AI

Свака употреба Phi модела треба да прати Microsoft-ове принципе одговорног AI:
- Правичност, поузданост, безбедност
- Приватност и безбедност  
- Инклузивност, транспарентност, одговорност
- Користите Azure AI Content Safety за продукцијске апликације
- Види `/md/01.Introduction/01/01.AISafety.md`

### Преводи

- Подржано 50+ језика преко аутоматизованог GitHub Action-а
- Преводи у директоријуму `/translations/`
- Одржава их co-op-translator workflow
- Не уређујте преведене фајлове ручно (аутоматски генерисани)

### Допринос

- Пратите упутства у `CONTRIBUTING.md`
- Прихватите Уговор о лиценци за допринос (CLA)
- Поштујте Microsoft Open Source Code of Conduct
- Чувајте безбедност и креденцијале ван комита

### Подршка више језика

Ово је полиглот репозиторијум са примерима у:
- **Python** - ML/AI радни токови, Jupyter ноутбуци, фино подешавање
- **C#/.NET** - Предузетничке апликације, интеграција ONNX Runtime
- **JavaScript** - Веб AI и преобраз инференција кроз WebGPU

Одаберите језик који најбоље одговара вашем случају употребе и циљној платформи.

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**Одрицање**:  
Овај документ је преведен коришћењем AI услуге за превод [Co-op Translator](https://github.com/Azure/co-op-translator). Иако се трудимо да обезбедимо тачност, имајте у виду да аутоматски преводи могу садржати грешке или нетачности. Оригинални документ на његовом изворном језику треба сматрати ауторитетним извором. За критичне информације препоручује се професионални људски превод. Нисмо одговорни за било каква недоразумевања или погрешне интерпретације које могу проистећи из употребе овог превода.
<!-- CO-OP TRANSLATOR DISCLAIMER END -->