PhiCookBook / el

# AGENTS.md

## Επισκόπηση Έργου

Το PhiCookBook είναι ένα ολοκληρωμένο αποθετήριο συνταγών που περιέχει πρακτικά παραδείγματα, μαθήματα και τεκμηρίωση για τη δουλειά με την οικογένεια Small Language Models (SLMs) της Microsoft Phi. Το αποθετήριο επιδεικνύει διάφορες περιπτώσεις χρήσης, συμπεριλαμβανομένης της εκτέλεσης συμπερασμάτων, της βελτιστοποίησης, της κβαντοποίησης, των υλοποιήσεων 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/** - Δείγματα εφαρμογών end-to-end
- **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 Scripts (`.py`)** - Αυτόνομα παραδείγματα Python
- **C# Projects (`.csproj`, `.sln`)** - Εφαρμογές και δείγματα .NET
- **JavaScript (`.js`, `package.json`)** - Παραδείγματα για web και Node.js
- **Markdown (`.md`)** - Τεκμηρίωση και οδηγοί

## Χρήση Παραδειγμάτων

### Εκτέλεση Jupyter Notebooks

Τα περισσότερα παραδείγματα παρέχονται ως Jupyter notebooks:
```bash
pip install jupyter notebook
jupyter notebook  # Ανοίγει το περιβάλλον του προγράμματος περιήγησης
# Πλοηγηθείτε στο επιθυμητό αρχείο .ipynb
```


### Εκτέλεση Python Scripts

```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  # Ανάπτυξη με ζεστή επαναφόρτωση
```


## Δοκιμές

Αυτό το αποθετήριο περιέχει δείγματα κώδικα και μαθήματα αντί για παραδοσιακό λογισμικό με unit tests. Η επικύρωση συνήθως γίνεται:

1. **Εκτέλεση των παραδειγμάτων** - Κάθε παράδειγμα πρέπει να τρέχει χωρίς σφάλματα
2. **Επαλήθευση αποτελεσμάτων** - Έλεγχος ότι οι απαντήσεις μοντέλου είναι κατάλληλες
3. **Ακολουθώντας τα μαθήματα** - Οι οδηγοί βήμα-βήμα πρέπει να λειτουργούν όπως τεκμηριώνονται

**Συνηθισμένη προσέγγιση επικύρωσης:**
- Δοκιμή εκτέλεσης παραδειγμάτων στο στοχευόμενο περιβάλλον
- Επαλήθευση ότι οι εξαρτήσεις εγκαθίστανται σωστά
- Έλεγχος ότι τα μοντέλα κατεβάζονται/φορτώνονται επιτυχώς
- Επιβεβαίωση ότι η αναμενόμενη συμπεριφορά συμφωνεί με την τεκμηρίωση

## Στυλ Κώδικα και Συμβάσεις

### Γενικές Οδηγίες

- Τα παραδείγματα πρέπει να είναι καθαρά, σχολιασμένα και εκπαιδευτικά
- Ακολουθήστε τις προδιαγραφές της κάθε γλώσσας (PEP 8 για Python, πρότυπα C# για .NET)
- Κρατήστε τα παραδείγματα εστιασμένα στην επίδειξη των δυνατοτήτων των μοντέλων Phi
- Συμπεριλάβετε σχόλια που εξηγούν βασικές έννοιες και παραμέτρους μοντέλων

### Πρότυπα Τεκμηρίωσης

**Μορφοποίηση URL:**
- Χρησιμοποιήστε τη μορφή `[text](../../url)` χωρίς περιττά κενά
- Σχετικοί σύνδεσμοι: Χρησιμοποιήστε `./` για τρέχον κατάλογο, `../` για γονικό
- Αποφύγετε τοπικές διευθύνσεις σε URLs (μην χρησιμοποιείτε `/en-us/`, `/en/`)

**Εικόνες:**
- Αποθηκεύστε όλες τις εικόνες στον κατάλογο `/imgs/`
- Χρησιμοποιήστε περιγραφικά ονόματα με αγγλικούς χαρακτήρες, αριθμούς και παύλες
- Παράδειγμα: `phi-3-architecture.png`

**Αρχεία Markdown:**
- Αναφέρετε πραγματικά παραδείγματα λειτουργικού κώδικα στον κατάλογο `/code/`
- Διατηρείτε συγχρονισμένη την τεκμηρίωση με τις αλλαγές στον κώδικα
- Χρησιμοποιήστε το emoji 📓 για να σημειώσετε Jupyter notebooks στο README

### Οργάνωση Αρχείων

- Παραδείγματα κώδικα στο `/code/` οργανωμένα ανά θέμα/χαρακτηριστικό
- Η τεκμηρίωση στο `/md/` αντικατοπτρίζει τη δομή του κώδικα όπου εφαρμόζεται
- Κρατήστε σχετικές αρχεία (notebooks, scripts, ρυθμίσεις) μαζί σε υποφακέλους

## Οδηγίες για Pull Requests

### Πριν την Υποβολή

1. **Φτιάξτε fork** του αποθετηρίου στον λογαριασμό σας
2. **Ξεχωριστά PR ανά τύπο:**
   - Διορθώσεις σφαλμάτων σε ένα PR
   - Ενημερώσεις τεκμηρίωσης σε άλλο
   - Νέα παραδείγματα σε ξεχωριστά PR
   - Διορθώσεις τυπογραφικών μπορούν να συνδυαστούν

3. **Διαχείριση συγκρούσεων συγχώνευσης:**
   - Ενημερώστε τοπικά τον κλάδο `main` πριν κάνετε αλλαγές
   - Συγχρονιστείτε συχνά με το upstream

4. **PR για μεταφράσεις:**
   - Πρέπει να περιλαμβάνει μεταφράσεις σε ΟΛΑ τα αρχεία του φακέλου
   - Διατηρήστε συνεπή δομή με την αρχική γλώσσα

### Απαραίτητοι Έλεγχοι

Τα PR εκτελούν αυτόματα workflows GitHub για επικύρωση:

1. **Έλεγχος σχετικών μονοπατιών** - Όλοι οι εσωτερικοί σύνδεσμοι πρέπει να λειτουργούν
   - Δοκιμάστε τους συνδέσμους τοπικά: Ctrl+Click στο VS Code
   - Χρησιμοποιήστε προτάσεις μονοπατιών από το VS Code (`./` ή `../`)

2. **Έλεγχος τοπικού μέρους URL** - Τα web URLs δεν πρέπει να έχουν locale για χώρα
   - Αφαιρέστε `/en-us/`, `/en/` ή άλλα γλωσσικά κωδικά
   - Χρησιμοποιήστε γενικά διεθνή URLs

3. **Έλεγχος κατεστραμμένων URL** - Όλα τα URLs πρέπει να επιστρέφουν status 200
   - Επαληθεύστε ότι οι σύνδεσμοι είναι προσβάσιμοι πριν την υποβολή
   - Σημείωση: Κάποιες αποτυχίες μπορεί να οφείλονται σε περιορισμούς δικτύου

### Μορφή Τίτλου PR

```
[component] Brief description
```

Παραδείγματα:
- `[docs] Προσθήκη μαθήματος inference Phi-4`
- `[code] Διόρθωση παραδείγματος ενσωμάτωσης ONNX Runtime`
- `[translation] Προσθήκη ιαπωνικής μετάφρασης για οδηγούς εισαγωγής`

## Συνηθισμένα Αναπτυξιακά Μοτίβα

### Χρήση Μοντέλων Phi

**Φόρτωση Μοντέλου:**
- Τα παραδείγματα χρησιμοποιούν διάφορα πλαίσια: Transformers, ONNX Runtime, MLX, OpenVINO
- Τα μοντέλα συνήθως κατεβάζονται από Hugging Face, Azure ή GitHub Models
- Ελέγξτε τη συμβατότητα μοντέλου με το υλικό σας (CPU, GPU, NPU)

**Μοτίβα Συμπερασμάτων:**
- Δημιουργία κειμένου: Τα περισσότερα παραδείγματα χρησιμοποιούν παραλλαγές chat/instruct
- Όραση: Phi-3-vision και Phi-4-multimodal για κατανόηση εικόνας
- Ήχος: Phi-4-multimodal υποστηρίζει ηχητικές εισόδους
- Συλλογισμός: Παραλλαγές Phi-4-reasoning για εξελιγμένα καθήκοντα συλλογισμού

### Σημειώσεις για Πλατφόρμες

**Microsoft Foundry:**
- Απαιτεί συνδρομή Azure και API κλειδιά
- Δείτε `/md/02.QuickStart/AzureAIFoundry_QuickStart.md`

**GitHub Models:**
- Διαθέσιμο δωρεάν επίπεδο για δοκιμές
- Δείτε `/md/02.QuickStart/GitHubModel_QuickStart.md`

**Τοπική Εκτέλεση:**
- ONNX Runtime: Πολυπλατφορμική, βελτιστοποιημένη εκτέλεση
- Ollama: Εύκολη τοπική διαχείριση μοντέλων (προρυθμισμένο στο dev container)
- Apple MLX: Βελτιστοποιημένο για Apple Silicon

## Αντιμετώπιση Προβλημάτων

### Συνηθισμένα Θέματα

**Θέματα Μνήμης:**
- Τα μοντέλα Phi απαιτούν σημαντική RAM (ειδικά όραση/πολυτροπικά παραλλαγές)
- Χρησιμοποιήστε κβαντισμένα μοντέλα για περιβάλλοντα με περιορισμένους πόρους
- Δείτε `/md/01.Introduction/04/QuantifyingPhi.md`

**Σύγκρουση Εξαρτήσεων:**
- Τα παραδείγματα Python μπορεί να απαιτούν συγκεκριμένες εκδόσεις
- Χρησιμοποιήστε εικονικά περιβάλλοντα για κάθε παράδειγμα
- Ελέγξτε τα ξεχωριστά αρχεία `requirements.txt`

**Αποτυχία Λήψης Μοντέλου:**
- Μεγάλα μοντέλα μπορεί να έχουν timeout σε αργές συνδέσεις
- Σκεφτείτε τη χρήση cloud περιβαλλόντων (Codespaces, Azure)
- Ελέγξτε την cache Hugging Face: `~/.cache/huggingface/`

**Θέματα Έργου .NET:**
- Βεβαιωθείτε ότι έχετε εγκαταστήσει το .NET 8.0 SDK
- Χρησιμοποιήστε `dotnet restore` πριν το build
- Ορισμένα έργα έχουν ρυθμίσεις για CUDA (Debug_Cuda)

**JavaScript/Web Παραδείγματα:**
- Χρησιμοποιήστε Node.js 18+ για συμβατότητα
- Καθαρίστε `node_modules` και επανεγκαταστήστε αν υπάρχουν προβλήματα
- Ελέγξτε την κονσόλα browser για θέματα συμβατότητας WebGPU

### Λήψη Βοήθειας

- **Discord:** Εγγραφείτε στο Microsoft Foundry Community Discord
- **GitHub Issues:** Αναφέρετε σφάλματα και προβλήματα στο αποθετήριο
- **GitHub Discussions:** Κάντε ερωτήσεις και μοιραστείτε γνώση

## Πρόσθετο Πλαίσιο

### Υπεύθυνη Τεχνητή Νοημοσύνη

Όλη η χρήση μοντέλων Phi πρέπει να ακολουθεί τις αρχές Υπεύθυνης ΤΝ της Microsoft:
- Δικαιοσύνη, αξιοπιστία, ασφάλεια
- Ιδιωτικότητα και ασφάλεια  
- Συμπερίληψη, διαφάνεια, λογοδοσία
- Χρησιμοποιήστε Azure AI Content Safety για εφαρμογές παραγωγής
- Δείτε `/md/01.Introduction/01/01.AISafety.md`

### Μεταφράσεις

- Υποστηρίζονται 50+ γλώσσες μέσω αυτοματοποιημένης ενέργειας GitHub
- Μεταφράσεις στον κατάλογο `/translations/`
- Διατηρείται από το συνεργατικό workflow μεταφραστή
- Μην επεξεργάζεστε χειροκίνητα μεταφρασμένα αρχεία (παράγονται αυτόματα)

### Συμμετοχή

- Ακολουθήστε τις οδηγίες στο `CONTRIBUTING.md`
- Συμφωνείστε με τη Συμφωνία Άδειας Συνεισφοράς (CLA)
- Τηρείτε τον Κώδικα Συμπεριφοράς Ανοιχτού Κώδικα της Microsoft
- Κρατήστε την ασφάλεια και τα διαπιστευτήρια έξω από τις δεσμεύσεις

### Υποστήριξη Πολλών Γλωσσών

Αυτό είναι ένα πολυγλωσσικό αποθετήριο με παραδείγματα σε:
- **Python** - Ροές εργασίας ML/AI, Jupyter notebooks, βελτιστοποίηση
- **C#/.NET** - Επιχειρησιακές εφαρμογές, ενσωμάτωση ONNX Runtime
- **JavaScript** - Web-based AI, συμπεράσματα browser με WebGPU

Επιλέξτε τη γλώσσα που ταιριάζει καλύτερα στη χρήση και τον στόχο ανάπτυξής σας.

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**Αποποίηση ευθυνών**:  
Αυτό το έγγραφο έχει μεταφραστεί χρησιμοποιώντας την υπηρεσία αυτόματης μετάφρασης AI [Co-op Translator](https://github.com/Azure/co-op-translator). Παρόλο που επιδιώκουμε την ακρίβεια, παρακαλούμε να έχετε υπόψη ότι οι αυτοματοποιημένες μεταφράσεις ενδέχεται να περιέχουν λάθη ή ανακρίβειες. Το πρωτότυπο έγγραφο στη μητρική του γλώσσα πρέπει να θεωρείται η αυθεντική πηγή. Για κρίσιμες πληροφορίες, συνιστάται επαγγελματική μετάφραση από άνθρωπο. Δεν φέρουμε καμία ευθύνη για τυχόν παρανοήσεις ή λανθασμένες ερμηνείες που προκύπτουν από τη χρήση αυτής της μετάφρασης.
<!-- CO-OP TRANSLATOR DISCLAIMER END -->