# Δημιουργήστε έναν Βοηθό Συνομιλίας με AI
Θυμάστε στο Star Trek όταν το πλήρωμα συζητούσε άνετα με τον υπολογιστή του διαστημοπλοίου, κάνοντάς του σύνθετες ερωτήσεις και λαμβάνοντας στοχαστικές απαντήσεις; Αυτό που φαινόταν ως καθαρή επιστημονική φαντασία τη δεκαετία του 1960 είναι τώρα κάτι που μπορείτε να δημιουργήσετε χρησιμοποιώντας τεχνολογίες web που ήδη γνωρίζετε.
Σε αυτό το μάθημα, θα δημιουργήσουμε έναν βοηθό συνομιλίας AI χρησιμοποιώντας HTML, CSS, JavaScript και κάποια ολοκλήρωση με το backend. Θα ανακαλύψετε πώς οι ίδιες δεξιότητες που έχετε μάθει μπορούν να συνδεθούν με ισχυρές υπηρεσίες AI που κατανοούν το πλαίσιο και δημιουργούν ουσιαστικές απαντήσεις.
Σκεφτείτε το AI σαν να έχετε πρόσβαση σε μια τεράστια βιβλιοθήκη που όχι μόνο μπορεί να βρει πληροφορίες αλλά και να τις συνθέσει σε συνεκτικές απαντήσεις προσαρμοσμένες στις συγκεκριμένες ερωτήσεις σας. Αντί να ψάχνετε μέσα σε χιλιάδες σελίδες, λαμβάνετε άμεσες, συμφραζόμενες απαντήσεις.
Η ολοκλήρωση συμβαίνει μέσα από γνωστές τεχνολογίες web που συνεργάζονται. Το HTML δημιουργεί το περιβάλλον συνομιλίας, το CSS χειρίζεται τον οπτικό σχεδιασμό, το JavaScript διαχειρίζεται τις αλληλεπιδράσεις των χρηστών και ένα backend API συνδέει όλα με τις υπηρεσίες AI. Είναι παρόμοιο με το πώς διαφορετικά τμήματα μιας ορχήστρας συνεργάζονται για να δημιουργήσουν μια συμφωνία.
Ουσιαστικά, χτίζουμε μια γέφυρα μεταξύ της φυσικής ανθρώπινης επικοινωνίας και της επεξεργασίας μηχανής. Θα μάθετε τόσο την τεχνική υλοποίηση της ολοκλήρωσης των υπηρεσιών AI όσο και τα σχέδια σχεδίασης που κάνουν τις αλληλεπιδράσεις να φαίνονται διαισθητικές.
Στο τέλος αυτού του μαθήματος, η ολοκλήρωση AI θα σας φανεί λιγότερο σαν ένα μυστηριώδες διαδικασία και περισσότερο σαν ένα ακόμη API με το οποίο μπορείτε να δουλέψετε. Θα κατανοήσετε τα βασικά πρότυπα που τροφοδοτούν εφαρμογές όπως το ChatGPT και το Claude, χρησιμοποιώντας τις ίδιες αρχές ανάπτυξης web που έχετε μάθει.
## ⚡ Τι Μπορείτε να Κάνετε στα Επόμενα 5 Λεπτά
**Γρήγορος Οδηγός Εκκίνησης για Απασχολημένους Προγραμματιστές**
```mermaid
flowchart LR
A[⚡ 5 λεπτά] --> B[Λήψη διακριτικού GitHub]
B --> C[Δοκιμή παιδικής χαράς AI]
C --> D[Αντιγραφή κώδικα Python]
D --> E[Προβολή απαντήσεων AI]
```
- **Λεπτό 1**: Επισκεφτείτε το [GitHub Models Playground](https://github.com/marketplace/models/azure-openai/gpt-4o-mini/playground) και δημιουργήστε ένα προσωπικό access token
- **Λεπτό 2**: Δοκιμάστε τις αλληλεπιδράσεις AI απευθείας στο περιβάλλον playground
- **Λεπτό 3**: Κάντε κλικ στην καρτέλα "Code" και αντιγράψτε το απόσπασμα Python
- **Λεπτό 4**: Εκτελέστε τον κώδικα τοπικά με το token σας: `GITHUB_TOKEN=your_token python test.py`
- **Λεπτό 5**: Δείτε την πρώτη σας απάντηση AI να δημιουργείται από τον δικό σας κώδικα
**Γρήγορος Κώδικας Δοκιμής**:
```python
import os
from openai import OpenAI
client = OpenAI(
base_url="https://models.github.ai/inference",
api_key="your_token_here"
)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Hello AI!"}],
model="openai/gpt-4o-mini"
)
print(response.choices[0].message.content)
```
**Γιατί Έχει Σημασία**: Σε 5 λεπτά, θα ζήσετε τη μαγεία της προγραμματισμένης αλληλεπίδρασης με AI. Αυτό αντιπροσωπεύει το θεμελιώδες δομικό στοιχείο που τροφοδοτεί κάθε εφαρμογή AI που χρησιμοποιείτε.
Δείτε πώς θα μοιάζει το τελικό σας έργο:
## 🗺️ Το Ταξίδι Μάθησής σας Μέσα από την Ανάπτυξη Εφαρμογών AI
```mermaid
journey
title Από την Ανάπτυξη Ιστού στην Ενσωμάτωση AI
section Κατανόηση Θεμελίων AI
Ανακαλύψτε τις έννοιες του γενετικού AI: 4: You
Εξερευνήστε την πλατφόρμα GitHub Models: 6: You
Εξοικειωθείτε με παραμέτρους και εντολές AI: 8: You
section Ενσωμάτωση Backend
Δημιουργήστε διακομιστή API Python: 5: You
Υλοποιήστε κλήσεις λειτουργιών AI: 7: You
Διαχειριστείτε ασύγχρονες λειτουργίες: 8: You
section Ανάπτυξη Frontend
Δημιουργήστε σύγχρονη διεπαφή συνομιλίας: 6: You
Εξοικειωθείτε με αλληλεπιδράσεις σε πραγματικό χρόνο: 8: You
Δημιουργήστε ανταποκριτική εμπειρία χρήστη: 9: You
section Επαγγελματική Εφαρμογή
Αναπτύξτε ολοκληρωμένο σύστημα AI: 7: You
Βελτιστοποιήστε πρότυπα απόδοσης: 8: You
Δημιουργήστε εφαρμογή έτοιμη για παραγωγή: 9: You
```
**Ο Προορισμός του Ταξιδιού σας**: Στο τέλος αυτού του μαθήματος, θα έχετε δημιουργήσει μια πλήρη εφαρμογή με ισχύ AI χρησιμοποιώντας τις ίδιες τεχνολογίες και πρότυπα που χρησιμοποιούν σύγχρονοι βοηθοί AI όπως το ChatGPT, το Claude και το Google Bard.
## Κατανόηση του AI: Από το Μυστήριο στην Κα_master_ία
Πριν βουτήξουμε στον κώδικα, ας καταλάβουμε με τι δουλεύουμε. Αν έχετε χρησιμοποιήσει APIs πριν, ξέρετε το βασικό πρότυπο: στέλνεις ένα αίτημα, λαμβάνεις μια απάντηση.
Τα AI APIs ακολουθούν παρόμοια δομή, αλλά αντί να ανακτούν προ-αποθηκευμένα δεδομένα από μια βάση δεδομένων, παράγουν νέες απαντήσεις βασισμένες σε πρότυπα που έμαθαν από τεράστιες ποσότητες κειμένων. Σκεφτείτε το σαν τη διαφορά ανάμεσα σε ένα σύστημα καταλόγου βιβλιοθήκης και έναν γνώστη βιβλιοθηκάριο που μπορεί να συνθέσει πληροφορίες από πολλαπλές πηγές.
### Τι Είναι Πραγματικά το "Γενετικό AI";
Σκεφτείτε πώς η Ροζέτα πέτρα επέτρεψε στους μελετητές να κατανοήσουν τα αιγυπτιακά ιερογλυφικά βρίσκοντας πρότυπα ανάμεσα σε γνωστές και άγνωστες γλώσσες. Τα μοντέλα AI λειτουργούν παρόμοια – βρίσκουν πρότυπα σε τεράστιες ποσότητες κειμένου για να καταλάβουν πώς λειτουργεί η γλώσσα, και στη συνέχεια χρησιμοποιούν αυτά τα πρότυπα για να δημιουργήσουν κατάλληλες απαντήσεις σε νέες ερωτήσεις.
**Ας το αναλύσουμε με μια απλή σύγκριση:**
- **Παραδοσιακή βάση δεδομένων**: Σαν να ζητάτε το πιστοποιητικό γέννησής σας – παίρνετε ακριβώς το ίδιο έγγραφο κάθε φορά
- **Μηχανή αναζήτησης**: Σαν να ζητάτε από έναν βιβλιοθηκάριο να βρει βιβλία για γάτες – σας δείχνει τι είναι διαθέσιμο
- **Γενετικό AI**: Σαν να ρωτάτε έναν γνώστη φίλο για τις γάτες – σας λέει ενδιαφέροντα πράγματα με δικά του λόγια, προσαρμοσμένα σε ό,τι θέλετε να μάθετε
```mermaid
graph LR
A[Η Ερώτησή Σας] --> B[Μοντέλο ΤΝ]
B --> C[Αναγνώριση Προτύπων]
C --> D[Δημιουργία Περιεχομένου]
D --> E[Αντίδραση σε Πλαίσιο]
F[Δεδομένα Εκπαίδευσης Βιβλία, Άρθρα, Ιστός] --> B
```
### Πώς Μάθαινουν τα Μοντέλα AI (Η Απλή Έκδοση)
Τα μοντέλα AI μαθαίνουν μέσα από έκθεση σε τεράστια σύνολα δεδομένων που περιέχουν κείμενα από βιβλία, άρθρα και συνομιλίες. Μέσα από αυτή τη διαδικασία, εντοπίζουν πρότυπα σε:
- Πώς είναι δομημένες οι σκέψεις στην γραπτή επικοινωνία
- Ποια λέξη εμφανίζονται συνήθως μαζί
- Πώς κυλάει συνήθως η συνομιλία
- Συμφραζόμενες διαφορές ανάμεσα σε επίσημη και ανεπίσημη επικοινωνία
**Είναι παρόμοιο με το πώς οι αρχαιολόγοι αποκωδικοποιούν αρχαίες γλώσσες**: αναλύουν χιλιάδες παραδείγματα για να κατανοήσουν γραμματική, λεξιλόγιο και πολιτισμικό πλαίσιο, και τελικά μπορούν να ερμηνεύουν νέα κείμενα χρησιμοποιώντας αυτά τα μάθημα πρότυπα.
### Γιατί GitHub Models;
Χρησιμοποιούμε το GitHub Models για έναν αρκετά πρακτικό λόγο – μας δίνει πρόσβαση σε επίπεδο enterprise AI χωρίς να χρειαστεί να στήσουμε τη δική μας υποδομή AI (που, εμπιστευθείτε με, δεν θέλετε να κάνετε τώρα!). Σκεφτείτε το σαν να χρησιμοποιείτε ένα API καιρού αντί να προσπαθείτε να προβλέψετε τον καιρό μόνοι σας στήνοντας μετεωρολογικούς σταθμούς παντού.
Είναι ουσιαστικά "AI-ως-Υπηρεσία", και το καλύτερο; Είναι δωρεάν για να ξεκινήσετε, έτσι μπορείτε να πειραματιστείτε χωρίς να ανησυχείτε για υπέρογκους λογαριασμούς.
```mermaid
graph LR
A[Διεπαφή Συνομιλίας Frontend] --> B[Το Backend API σας]
B --> C[GitHub Models API]
C --> D[Επεξεργασία Μοντέλου ΤΝ]
D --> C
C --> B
B --> A
```
Θα χρησιμοποιήσουμε το GitHub Models για την ολοκλήρωση backend μας, που παρέχει πρόσβαση σε επαγγελματικής ποιότητας δυνατότητες AI μέσω ενός φιλικού προς τον προγραμματιστή περιβάλλοντος. Το [GitHub Models Playground](https://github.com/marketplace/models/azure-openai/gpt-4o-mini/playground) χρησιμεύει ως περιβάλλον δοκιμών όπου μπορείτε να πειραματιστείτε με διαφορετικά μοντέλα AI και να κατανοήσετε τις δυνατότητές τους πριν τα εφαρμόσετε στον κώδικα.
## 🧠 Οικοσύστημα Ανάπτυξης Εφαρμογών AI
```mermaid
mindmap
root((Ανάπτυξη Τεχνητής Νοημοσύνης))
Understanding AI
Generative Models
Αναγνώριση Προτύπων
Δημιουργία Περιεχομένου
Κατανόηση Πλαισίου
Σύνθεση Απαντήσεων
AI Parameters
Έλεγχος Θερμοκρασίας
Όρια Token
Φιλτράρισμα Top-p
Εντολές Συστήματος
Backend Architecture
API Integration
Μοντέλα GitHub
Πιστοποίηση
Διαχείριση Αιτήσεων
Διαχείριση Σφαλμάτων
Python Infrastructure
Πλαίσιο FastAPI
Ασύγχρονες Ενέργειες
Ασφάλεια Περιβάλλοντος
Διαμόρφωση CORS
Frontend Experience
Chat Interface
Ενημερώσεις σε Πραγματικό Χρόνο
Ιστορικό Μηνυμάτων
Ανατροφοδότηση Χρήστη
Καταστάσεις Φόρτωσης
Modern Web Tech
Κλάσεις ES6
Async/Await
Διαχείριση DOM
Διαχείριση Γεγονότων
Professional Patterns
Security Best Practices
Διαχείριση Token
Επικύρωση Εισόδου
Πρόληψη XSS
Όρια Σφαλμάτων
Production Readiness
Βελτιστοποίηση Απόδοσης
Ανταποκρινόμενος Σχεδιασμός
Προσβασιμότητα
Στρατηγικές Δοκιμών
```
**Κεντρική Αρχή**: Η ανάπτυξη εφαρμογών AI συνδυάζει τις παραδοσιακές δεξιότητες ανάπτυξης web με την ολοκλήρωση υπηρεσιών AI, δημιουργώντας έξυπνες εφαρμογές που φαίνονται φυσικές και ανταποκρίνονται στους χρήστες.
**Τι κάνει το playground τόσο χρήσιμο:**
- **Δοκιμάστε** διαφορετικά μοντέλα AI όπως GPT-4o-mini, Claude και άλλα (όλα δωρεάν!)
- **Ελέγξτε** τις ιδέες και τις προτροπές σας πριν γράψετε κώδικα
- **Πάρτε** έτοιμα αποσπάσματα κώδικα στη γλώσσα προγραμματισμού που προτιμάτε
- **Ρυθμίστε** επιλογές όπως το επίπεδο δημιουργικότητας και το μήκος της απάντησης για να δείτε πώς επηρεάζουν την έξοδο
Μόλις παίξετε λίγο, απλώς επιλέξτε την καρτέλα "Code" και διαλέξτε τη γλώσσα προγραμματισμού σας για να πάρετε τον κώδικα υλοποίησης που χρειάζεστε.
## Ρύθμιση της Ολοκλήρωσης Backend με Python
Τώρα ας υλοποιήσουμε το AI μέσω Python. Η Python είναι εξαιρετική για εφαρμογές AI λόγω της απλής σύνταξης και των ισχυρών βιβλιοθηκών της. Θα ξεκινήσουμε με τον κώδικα από το GitHub Models playground και μετά θα τον αναδιαρθρώσουμε σε μια επαναχρησιμοποιήσιμη, έτοιμη για παραγωγή συνάρτηση.
### Κατανόηση της Βασικής Υλοποίησης
Όταν πάρετε τον Python κώδικα από το playground, θα δείτε κάτι που μοιάζει με αυτό. Μην ανησυχείτε αν φαίνεται πολύ στην αρχή – ας το δούμε βήμα προς βήμα:
```python
"""Run this model in Python
> pip install openai
"""
import os
from openai import OpenAI
# Για να αυθεντικοποιηθείτε με το μοντέλο, θα πρέπει να δημιουργήσετε ένα προσωπικό διακριτικό πρόσβασης (PAT) στις ρυθμίσεις του GitHub σας.
# Δημιουργήστε το PAT σας ακολουθώντας τις οδηγίες εδώ: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
client = OpenAI(
base_url="https://models.github.ai/inference",
api_key=os.environ["GITHUB_TOKEN"],
)
response = client.chat.completions.create(
messages=[
{
"role": "system",
"content": "",
},
{
"role": "user",
"content": "What is the capital of France?",
}
],
model="openai/gpt-4o-mini",
temperature=1,
max_tokens=4096,
top_p=1
)
print(response.choices[0].message.content)
```
**Τι συμβαίνει σε αυτόν τον κώδικα:**
- **Εισάγουμε** τα εργαλεία που χρειαζόμαστε: `os` για ανάγνωση μεταβλητών περιβάλλοντος και `OpenAI` για συνομιλία με το AI
- **Ρυθμίζουμε** τον πελάτη OpenAI να δείχνει στους AI servers του GitHub αντί για τους OpenAI απευθείας
- **Επαληθεύουμε** με ένα ειδικό GitHub token (περισσότερα σε λίγο!)
- **Δομούμε** τη συνομιλία μας με διαφορετικούς "ρόλους" – σκεφτείτε το σαν το στήσιμο του σκηνικού για μια παράσταση
- **Στέλνουμε** το αίτημά μας στο AI με κάποιες παραμέτρους fine-tuning
- **Εξάγουμε** το πραγματικό κείμενο της απάντησης από όλα τα δεδομένα που επιστρέφονται
### Κατανόηση των Ρόλων Μηνυμάτων: Το Πλαίσιο Συνομιλίας AI
Οι συνομιλίες AI χρησιμοποιούν μια συγκεκριμένη δομή με διαφορετικούς "ρόλους" που εξυπηρετούν διακριτούς σκοπούς:
```python
messages=[
{
"role": "system",
"content": "You are a helpful assistant who explains things simply."
},
{
"role": "user",
"content": "What is machine learning?"
}
]
```
**Σκεφτείτε το σαν να σκηνοθετείτε μια παράσταση:**
- **Ρόλος συστήματος**: Σαν οδηγίες σκηνής για έναν ηθοποιό – λέει στο AI πώς να συμπεριφέρεται, τι προσωπικότητα να έχει και πώς να απαντά
- **Ρόλος χρήστη**: Η πραγματική ερώτηση ή μήνυμα από τον χρήστη της εφαρμογής σας
- **Ρόλος βοηθού**: Η απάντηση του AI (δεν την στέλνετε εσείς, αλλά εμφανίζεται στο ιστορικό συνομιλίας)
**Παραδειγματική αναλογία**: Φανταστείτε ότι συστήνετε έναν φίλο σε κάποιον σε ένα πάρτι:
- **Μήνυμα συστήματος**: "Αυτή είναι η φίλη μου η Σάρα, είναι γιατρός που εξηγεί ιατρικά θέματα με απλούς όρους"
- **Μήνυμα χρήστη**: "Μπορείς να εξηγήσεις πώς λειτουργούν τα εμβόλια;"
- **Απάντηση βοηθού**: Η Σάρα απαντά σαν φιλικός γιατρός, όχι σαν δικηγόρος ή σεφ
### Κατανόηση των Παραμέτρων AI: Ρύθμιση της Συμπεριφοράς Απαντήσεων
Οι αριθμητικές παράμετροι στις κλήσεις API AI ελέγχουν πώς το μοντέλο παράγει απαντήσεις. Αυτές οι ρυθμίσεις σας επιτρέπουν να προσαρμόσετε τη συμπεριφορά του AI για διαφορετικές χρήσεις:
#### Θερμοκρασία (0.0 έως 2.0): Ο Δρομολογητής Δημιουργικότητας
**Τι κάνει**: Ελέγχει πόσο δημιουργικές ή προβλέψιμες θα είναι οι απαντήσεις του AI.
**Σκεφτείτε το σαν το επίπεδο αυτοσχεδιασμού ενός μουσικού τζαζ:**
- **Θερμοκρασία = 0.1**: Παίζει την ίδια μελωδία κάθε φορά (πολύ προβλέψιμο)
- **Θερμοκρασία = 0.7**: Προσθέτει κάποιες γευστικές παραλλαγές ενώ παραμένει αναγνωρίσιμο (ισορροπημένη δημιουργικότητα)
- **Θερμοκρασία = 1.5**: Πλήρης πειραματικός τζαζ με απρόβλεπτες στροφές (πολύ απρόβλεπτο)
```python
# Πολύ προβλέψιμες απαντήσεις (καλές για ερωτήσεις με πραγματικά δεδομένα)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "What is 2+2?"}],
temperature=0.1 # Σχεδόν πάντα θα λέει "4"
)
# Δημιουργικές απαντήσεις (καλές για καταιγισμό ιδεών)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Write a creative story opening"}],
temperature=1.2 # Θα δημιουργήσει μοναδικές, απρόβλεπτες ιστορίες
)
```
#### Μέγιστοι Κωδικοί (1 έως 4096+): Ο Ελεγκτής Μήκους Απάντησης
**Τι κάνει**: Ορίζει ένα όριο στο πόσο μεγάλη μπορεί να είναι η απάντηση του AI.
**Σκεφτείτε τους κωδικούς ως περίπου ισοδύναμους με λέξεις** (περίπου 1 κωδικός = 0.75 λέξεις στα αγγλικά):
- **max_tokens=50**: Σύντομο και γλυκό (σαν ένα μήνυμα κειμένου)
- **max_tokens=500**: Μια ωραία παράγραφος ή δύο
- **max_tokens=2000**: Μια λεπτομερής εξήγηση με παραδείγματα
```python
# Σύντομες, περιεκτικές απαντήσεις
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Explain JavaScript"}],
max_tokens=100 # Επιβάλλει σύντομη εξήγηση
)
# Λεπτομερείς, ολοκληρωμένες απαντήσεις
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Explain JavaScript"}],
max_tokens=1500 # Επιτρέπει λεπτομερείς εξηγήσεις με παραδείγματα
)
```
#### Top_p (0.0 έως 1.0): Η Παράμετρος Εστίασης
**Τι κάνει**: Ελέγχει πόσο εστιασμένο μένει το AI στις πιο πιθανές απαντήσεις.
**Φανταστείτε το AI να έχει ένα τεράστιο λεξιλόγιο, ταξινομημένο με βάση το πόσο πιθανή είναι κάθε λέξη:**
- **top_p=0.1**: Λαμβάνει υπόψη μόνο το κορυφαίο 10% των πιο πιθανών λέξεων (πολύ εστιασμένο)
- **top_p=0.9**: Λαμβάνει υπόψη το 90% των πιθανών λέξεων (περισσότερη δημιουργικότητα)
- **top_p=1.0**: Λαμβάνει υπόψη τα πάντα (μέγιστη ποικιλία)
**Για παράδειγμα**: Αν ρωτήσετε "Ο ουρανός συνήθως είναι..."
- **Χαμηλό top_p**: Πιθανότατα θα πει "γαλάζιος"
- **Υψηλό top_p**: Μπορεί να πει "γαλάζιος", "συννεφιασμένος", "τεράστιος", "μεταβαλλόμενος", "όμορφος" κλπ.
### Συνδυάζοντας Όλα: Συνδυασμοί Παραμέτρων για Διάφορες Χρήσεις
```python
# Για ακριβείς, συνεπείς απαντήσεις (όπως ένας bot τεκμηρίωσης)
factual_params = {
"temperature": 0.2,
"max_tokens": 300,
"top_p": 0.3
}
# Για βοήθεια στη δημιουργική γραφή
creative_params = {
"temperature": 1.1,
"max_tokens": 1000,
"top_p": 0.9
}
# Για συνομιλητικές, βοηθητικές απαντήσεις (ισορροπημένες)
conversational_params = {
"temperature": 0.7,
"max_tokens": 500,
"top_p": 0.8
}
```
```mermaid
quadrantChart
title Πίνακας Βελτιστοποίησης Παραμέτρων ΤΝ
x-axis Χαμηλή Δημιουργικότητα --> Υψηλή Δημιουργικότητα
y-axis Σύντομη Απόκριση --> Μακρά Απόκριση
quadrant-1 Δημιουργικό Περιεχόμενο
quadrant-2 Λεπτομερής Ανάλυση
quadrant-3 Γρήγορα Στοιχεία
quadrant-4 Συνομιλητική ΤΝ
Documentation Bot: [0.2, 0.3]
Customer Service: [0.4, 0.4]
General Assistant: [0.7, 0.5]
Creative Writer: [0.9, 0.9]
Brainstorming Tool: [0.8, 0.8]
```
**Κατανόηση γιατί αυτές οι παράμετροι έχουν σημασία**: Διάφορες εφαρμογές χρειάζονται διαφορετικού τύπου απαντήσεις. Ένα bot εξυπηρέτησης πελατών πρέπει να είναι συνεπές και τεκμηριωμένο (χαμηλή θερμοκρασία), ενώ ένας βοηθός δημιουργικής γραφής πρέπει να είναι φανταστικός και ποικίλος (υψηλή θερμοκρασία). Η κατανόηση αυτών των παραμέτρων σας δίνει έλεγχο στην προσωπικότητα και το στυλ απάντησης του AI σας.
```
**Here's what's happening in this code:**
- **We import** the tools we need: `os` for reading environment variables and `OpenAI` for talking to the AI
- **We set up** the OpenAI client to point to GitHub's AI servers instead of OpenAI directly
- **We authenticate** using a special GitHub token (more on that in a minute!)
- **We structure** our conversation with different "roles" – think of it like setting the scene for a play
- **We send** our request to the AI with some fine-tuning parameters
- **We extract** the actual response text from all the data that comes back
> 🔐 **Security Note**: Never hardcode API keys in your source code! Always use environment variables to store sensitive credentials like your `GITHUB_TOKEN`.
### Creating a Reusable AI Function
Let's refactor this code into a clean, reusable function that we can easily integrate into our web application:
```python
import asyncio
from openai import AsyncOpenAI
# Use AsyncOpenAI for better performance
client = AsyncOpenAI(
base_url="https://models.github.ai/inference",
api_key=os.environ["GITHUB_TOKEN"],
)
async def call_llm_async(prompt: str, system_message: str = "You are a helpful assistant."):
"""
Sends a prompt to the AI model asynchronously and returns the response.
Args:
prompt: The user's question or message
system_message: Instructions that define the AI's behavior and personality
Returns:
str: The AI's response to the prompt
"""
try:
response = await client.chat.completions.create(
messages=[
{
"role": "system",
"content": system_message,
},
{
"role": "user",
"content": prompt,
}
],
model="openai/gpt-4o-mini",
temperature=1,
max_tokens=4096,
top_p=1
)
return response.choices[0].message.content
except Exception as e:
logger.error(f"AI API error: {str(e)}")
return "I'm sorry, I'm having trouble processing your request right now."
# Backward compatibility function for synchronous calls
def call_llm(prompt: str, system_message: str = "You are a helpful assistant."):
"""Synchronous wrapper for async AI calls."""
return asyncio.run(call_llm_async(prompt, system_message))
```
**Κατανόηση αυτής της βελτιωμένης συνάρτησης:**
- **Αποδέχεται** δύο παραμέτρους: την προτροπή του χρήστη και ένα προαιρετικό μήνυμα συστήματος
- **Παρέχει** ένα προεπιλεγμένο μήνυμα συστήματος για γενική συμπεριφορά βοηθού
- **Χρησιμοποιεί** κατάλληλα τύπους Python για καλύτερη τεκμηρίωση κώδικα
- **Περιλαμβάνει** λεπτομερή docstring που εξηγεί τον σκοπό και τις παραμέτρους της συνάρτησης
- **Επιστρέφει** μόνο το περιεχόμενο της απάντησης, καθιστώντας την εύκολη στη χρήση στο web API μας
- **Διατηρεί** τις ίδιες παραμέτρους μοντέλου για συνεπή συμπεριφορά AI
### Η Μαγεία των System Prompts: Προγραμματισμός Προσωπικότητας AI
Αν οι παράμετροι ελέγχουν πώς "σκέφτεται" το AI, τα system prompts ελέγχουν ποιος νομίζει ότι είναι το AI. Αυτή είναι ειλικρινά μια από τις πιο συναρπαστικές πτυχές της εργασίας με AI – δίνετε στο AI μια ολοκληρωμένη προσωπικότητα, επίπεδο εξειδίκευσης και στυλ επικοινωνίας.
**Σκεφτείτε τα system prompts σαν να κάνετε κάστινγκ διαφορετικών ηθοποιών για διαφορετικούς ρόλους**: Αντί να έχετε έναν γενικό βοηθό, μπορείτε να δημιουργήσετε ειδικούς εμπειρογνώμονες για διαφορετικές καταστάσεις. Θέλετε έναν υπομονετικό δάσκαλο; Έναν δημιουργικό συνεργάτη ιδεών; Έναν σοβαρό επιχειρηματικό σύμβουλο; Απλά αλλάξτε το system prompt!
#### Γιατί τα System Prompts Είναι Τόσο Ισχυρά
Εδώ είναι το ενδιαφέρον: τα μοντέλα AI έχουν εκπαιδευτεί σε αμέτρητες συνομιλίες όπου οι άνθρωποι υιοθετούν διαφορετικούς ρόλους και επίπεδα εξειδίκευσης. Όταν δίνετε στο AI έναν συγκεκριμένο ρόλο, είναι σαν να ανάβετε έναν διακόπτη που ενεργοποιεί όλα αυτά τα μάθημα πρότυπα.
**Είναι σαν method acting για AI**: Πείτε σε έναν ηθοποιό "είσαι ένας σοφός γέρος καθηγητής" και δείτε πώς αλλάζει αυτόματα η στάση, το λεξιλόγιο και οι κινήσεις του. Το AI κάνει κάτι εξαιρετικά παρόμοιο με τα γλωσσικά πρότυπα.
#### Σύνταξη Αποτελεσματικών System Prompts: Η Τέχνη και η Επιστήμη
**Η δομή ενός εξαιρετικού system prompt:**
1. **Ρόλος / Ταυτότητα**: Ποιος είναι το AI;
2. **Εξειδίκευση**: Τι γνωρίζει;
3. **Στυλ επικοινωνίας**: Πώς μιλάει;
4. **Συγκεκριμένες οδηγίες**: Σε τι πρέπει να εστιάσει;
```python
# ❌ Ασαφής προτροπή συστήματος
"You are helpful."
# ✅ Λεπτομερής, αποτελεσματική προτροπή συστήματος
"You are Dr. Sarah Chen, a senior software engineer with 15 years of experience at major tech companies. You explain programming concepts using real-world analogies and always provide practical examples. You're patient with beginners and enthusiastic about helping them understand complex topics."
```
#### Παραδείγματα System Prompts με Πλαίσιο
Ας δούμε πώς διαφορετικά system prompts δημιουργούν εντελώς διαφορετικές προσωπικότητες AI:
```python
# Παράδειγμα 1: Ο Υπομονετικός Δάσκαλος
teacher_prompt = """
You are an experienced programming instructor who has taught thousands of students.
You break down complex concepts into simple steps, use analogies from everyday life,
and always check if the student understands before moving on. You're encouraging
and never make students feel bad for not knowing something.
"""
# Παράδειγμα 2: Ο Δημιουργικός Συνεργάτης
creative_prompt = """
You are a creative writing partner who loves brainstorming wild ideas. You're
enthusiastic, imaginative, and always build on the user's ideas rather than
replacing them. You ask thought-provoking questions to spark creativity and
offer unexpected perspectives that make stories more interesting.
"""
# Παράδειγμα 3: Ο Στρατηγικός Σύμβουλος Επιχειρήσεων
business_prompt = """
You are a strategic business consultant with an MBA and 20 years of experience
helping startups scale. You think in frameworks, provide structured advice,
and always consider both short-term tactics and long-term strategy. You ask
probing questions to understand the full business context before giving advice.
"""
```
#### Βλέποντας τα System Prompts σε Δράση
Ας δοκιμάσουμε την ίδια ερώτηση με διαφορετικά system prompts για να δούμε τις δραματικές διαφορές:
**Ερώτηση**: "Πώς διαχειρίζομαι τον έλεγχο ταυτότητας χρήστη στην web εφαρμογή μου;"
```python
# Με προτροπή του δασκάλου:
teacher_response = call_llm(
"How do I handle user authentication in my web app?",
teacher_prompt
)
# Τυπική απάντηση: "Υπέροχη ερώτηση! Ας χωρίσουμε την αυθεντικοποίηση σε απλά βήματα.
# Σκέψου το σαν έναν πορτιέρη νυχτερινού μαγαζιού που ελέγχει ταυτότητες..."
# Με προτροπή επιχείρησης:
business_response = call_llm(
"How do I handle user authentication in my web app?",
business_prompt
)
# Τυπική απάντηση: "Από στρατηγική άποψη, η αυθεντικοποίηση είναι κρίσιμη για την εμπιστοσύνη των χρηστών
# και τη συμμόρφωση με τους κανονισμούς. Ας περιγράψω ένα πλαίσιο λαμβάνοντας υπόψη την ασφάλεια,
# την εμπειρία χρήστη και την επεκτασιμότητα..."
```
#### Προχωρημένες Τεχνικές System Prompt
**1. Ορισμός Πλαισίου**: Δώστε στο AI πληροφορίες υποβάθρου
```python
system_prompt = """
You are helping a junior developer who just started their first job at a startup.
They know basic HTML/CSS/JavaScript but are new to backend development and databases.
Be encouraging and explain things step-by-step without being condescending.
"""
```
**2. Μορφοποίηση Εξόδου**: Πείτε στην AI πώς να δομήσει τις απαντήσεις
```python
system_prompt = """
You are a technical mentor. Always structure your responses as:
1. Quick Answer (1-2 sentences)
2. Detailed Explanation
3. Code Example
4. Common Pitfalls to Avoid
5. Next Steps for Learning
"""
```
**3. Ορισμός Περιορισμών**: Ορίστε τι δεν πρέπει να κάνει η AI
```python
system_prompt = """
You are a coding tutor focused on teaching best practices. Never write complete
solutions for the user - instead, guide them with hints and questions so they
learn by doing. Always explain the 'why' behind coding decisions.
"""
```
#### Γιατί Αυτό Έχει Σημασία για τον Βοηθό Συνομιλίας σας
Η κατανόηση των συστημικών εντολών σας δίνει απίστευτη δύναμη να δημιουργήσετε εξειδικευμένους βοηθούς AI:
- **Ρομπότ εξυπηρέτησης πελατών**: Βοηθητικό, υπομονετικό, με επίγνωση πολιτικής
- **Δάσκαλος μάθησης**: Ενθαρρυντικός, βήμα προς βήμα, ελέγχει την κατανόηση
- **Δημιουργικός συνεργάτης**: Φανταστικός, χτίζει πάνω σε ιδέες, ρωτά “τι θα γινόταν αν;”
- **Τεχνικός εμπειρογνώμονας**: Ακριβής, λεπτομερής, με επίγνωση ασφάλειας
**Το βασικό συμπέρασμα**: Δεν καλείτε απλώς ένα API AI – δημιουργείτε μια εξατομικευμένη προσωπικότητα AI που εξυπηρετεί την συγκεκριμένη χρήση σας. Αυτό είναι που κάνει τις σύγχρονες εφαρμογές AI να είναι προσαρμοσμένες και χρήσιμες αντί για γενικές.
### 🎯 Παιδαγωγικός Έλεγχος: Προγραμματισμός Προσωπικότητας AI
**Κάντε παύση και σκεφτείτε**: Μόλις μάθατε να προγραμματίζετε προσωπικότητες AI μέσω συστημικών εντολών. Αυτή είναι μια θεμελιώδης δεξιότητα στην ανάπτυξη σύγχρονων εφαρμογών AI.
**Γρήγορη αυτοαξιολόγηση**:
- Μπορείτε να εξηγήσετε πώς διαφέρουν οι συστημικές εντολές από τα κανονικά μηνύματα χρήστη;
- Ποια είναι η διαφορά μεταξύ των παραμέτρων temperature και top_p;
- Πώς θα δημιουργούσατε μια συστημική εντολή για μια συγκεκριμένη χρήση (πχ δάσκαλος προγραμματισμού);
**Σύνδεση με πραγματικό κόσμο**: Οι τεχνικές συστημικών εντολών που μάθατε χρησιμοποιούνται σε κάθε σημαντική εφαρμογή AI – από τη βοήθεια κωδικοποίησης του GitHub Copilot έως τη διεπαφή συνομιλίας του ChatGPT. Μαθαίνετε τα ίδια πρότυπα που χρησιμοποιούν οι ομάδες προϊόντων AI σε μεγάλες τεχνολογικές εταιρείες.
**Ερώτηση πρόκλησης**: Πώς θα σχεδιάζατε διαφορετικές προσωπικότητες AI για διαφορετικούς τύπους χρηστών (αρχάριος vs ειδικός); Σκεφτείτε πώς το ίδιο μοντέλο AI μπορεί να εξυπηρετήσει διαφορετικά ακροατήρια μέσω της μηχανικής εντολών.
## Δημιουργία του Web API με FastAPI: Το Κέντρο Υψηλής Απόδοσης Επικοινωνίας με AI
Τώρα ας φτιάξουμε το backend που συνδέει το frontend σας με τις υπηρεσίες AI. Θα χρησιμοποιήσουμε το FastAPI, ένα σύγχρονο πλαίσιο Python που διαπρέπει στη δημιουργία APIs για εφαρμογές AI.
Το FastAPI προσφέρει αρκετά πλεονεκτήματα για αυτό τον τύπο έργου: ενσωματωμένη υποστήριξη async για ταυτόχρονες αιτήσεις, αυτόματη δημιουργία τεκμηρίωσης API και εξαιρετική απόδοση. Ο διακομιστής FastAPI λειτουργεί ως ενδιάμεσος που λαμβάνει αιτήσεις από το frontend, επικοινωνεί με τις υπηρεσίες AI και επιστρέφει μορφοποιημένες απαντήσεις.
### Γιατί FastAPI για Εφαρμογές AI;
Μπορεί να αναρωτιέστε: «Δεν μπορώ απλά να καλέσω την AI απευθείας από το JavaScript του frontend μου;» ή «Γιατί FastAPI αντί για Flask ή Django;» Εξαιρετικές ερωτήσεις!
**Ιδού γιατί το FastAPI είναι ιδανικό για αυτό που χτίζουμε:**
- **Async από προεπιλογή**: Μπορεί να διαχειρίζεται πολλαπλές αιτήσεις AI ταυτόχρονα χωρίς να κολλάει
- **Αυτόματη τεκμηρίωση**: Επισκεφτείτε το `/docs` και δείτε όμορφη, διαδραστική τεκμηρίωση API δωρεάν
- **Ενσωματωμένη επικύρωση**: Ανιχνεύει σφάλματα πριν προκαλέσουν προβλήματα
- **Αστραπιαία ταχύτητα**: Ένα από τα ταχύτερα πλαίσια Python εκεί έξω
- **Σύγχρονο Python**: Χρησιμοποιεί όλες τις πιο πρόσφατες και κορυφαίες δυνατότητες της Python
**Και γιατί χρειαζόμαστε καθόλου backend:**
**Ασφάλεια**: Το κλειδί του API AI είναι σαν κωδικός πρόσβασης – αν το βάλετε στο JavaScript του frontend, όποιος δει τον κώδικα της σελίδας σας μπορεί να το κλέψει και να χρησιμοποιήσει τα credits AI σας. Το backend κρατάει τα ευαίσθητα διαπιστευτήρια ασφαλή.
**Περιορισμός Ρυθμού & Έλεγχος**: Το backend σας επιτρέπει να ελέγχετε πόσες φορές οι χρήστες μπορούν να κάνουν αιτήσεις, να εφαρμόζετε πιστοποίηση χρήστη και να προσθέτετε καταγραφή για παρακολούθηση χρήσης.
**Επεξεργασία Δεδομένων**: Μπορεί να θέλετε να αποθηκεύετε συνομιλίες, να φιλτράρετε ακατάλληλο περιεχόμενο ή να συνδυάζετε πολλές υπηρεσίες AI. Το backend είναι το μέρος που ζει αυτή η λογική.
**Η αρχιτεκτονική μοιάζει με μοντέλο πελάτη-διακομιστή:**
- **Frontend**: Επίπεδο διεπαφής χρήστη για αλληλεπίδραση
- **Backend API**: Επίπεδο επεξεργασίας και δρομολόγησης αιτήσεων
- **Υπηρεσία AI**: Εξωτερικός υπολογισμός και παραγωγή απαντήσεων
- **Μεταβλητές Περιβάλλοντος**: Ασφαλής ρύθμιση και αποθήκευση διαπιστευτηρίων
### Κατανόηση της Ροής Αίτησης-Απόκρισης
Ας ακολουθήσουμε τι συμβαίνει όταν ένας χρήστης στέλνει μήνυμα:
```mermaid
sequenceDiagram
participant User as 👤 Χρήστης
participant Frontend as 🌐 Εμπρόσθιο
participant API as 🔧 FastAPI Διακομιστής
participant AI as 🤖 Υπηρεσία AI
User->>Frontend: Πληκτρολογεί "Γειά σου AI!"
Frontend->>API: POST /hello {"message": "Γειά σου AI!"}
Note over API: Επικυρώνει το αίτημα Προσθέτει προτροπή συστήματος
API->>AI: Στέλνει μορφοποιημένο αίτημα
AI->>API: Επιστρέφει απάντηση AI
Note over API: Επεξεργάζεται την απάντηση Καταγράφει τη συνομιλία
API->>Frontend: {"response": "Γειά! Πώς μπορώ να βοηθήσω;"}
Frontend->>User: Εμφανίζει μήνυμα AI
```
**Κατανόηση κάθε βήματος:**
1. **Αλληλεπίδραση χρήστη**: Ο χρήστης πληκτρολογεί στη διεπαφή συνομιλίας
2. **Επεξεργασία frontend**: Το JavaScript καταγράφει την είσοδο και τη μορφοποιεί σε JSON
3. **Επικύρωση API**: Το FastAPI επικυρώνει αυτόματα το αίτημα με χρήση μοντέλων Pydantic
4. **Ενσωμάτωση AI**: Το backend προσθέτει το πλαίσιο (συστημική εντολή) και καλεί την υπηρεσία AI
5. **Διαχείριση απάντησης**: Το API λαμβάνει απάντηση AI και την τροποποιεί εάν χρειάζεται
6. **Εμφάνιση frontend**: Το JavaScript εμφανίζει την απάντηση στη διεπαφή συνομιλίας
### Κατανόηση της Αρχιτεκτονικής API
```mermaid
sequenceDiagram
participant Frontend
participant FastAPI
participant AI Function
participant GitHub Models
Frontend->>FastAPI: POST /hello {"message": "Γεια σου AI!"}
FastAPI->>AI Function: call_llm(message, system_prompt)
AI Function->>GitHub Models: API αίτηση
GitHub Models->>AI Function: απάντηση AI
AI Function->>FastAPI: κείμενο απάντησης
FastAPI->>Frontend: {"response": "Γεια! Πώς μπορώ να βοηθήσω;"}
```
```mermaid
flowchart TD
A[Είσοδος Χρήστη] --> B[Επικύρωση Frontend]
B --> C[HTTP POST Αίτημα]
C --> D[FastAPI Δρομολογητής]
D --> E[Επικύρωση Pydantic]
E --> F[Κλήση Λειτουργίας AI]
F --> G[GitHub Models API]
G --> H[Επεξεργασία Απόκρισης]
H --> I[Απόκριση JSON]
I --> J[Ενημέρωση Frontend]
subgraph "Επίπεδο Ασφαλείας"
K[Middleware CORS]
L[Μεταβλητές Περιβάλλοντος]
M[Διαχείριση Σφαλμάτων]
end
D --> K
F --> L
H --> M
```
### Δημιουργία της Εφαρμογής FastAPI
Ας χτίσουμε το API βήμα-βήμα. Δημιουργήστε ένα αρχείο με όνομα `api.py` με τον ακόλουθο κώδικα FastAPI:
```python
# api.py
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel
from llm import call_llm
import logging
# Διαμόρφωση καταγραφής
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
# Δημιουργία εφαρμογής FastAPI
app = FastAPI(
title="AI Chat API",
description="A high-performance API for AI-powered chat applications",
version="1.0.0"
)
# Διαμόρφωση CORS
app.add_middleware(
CORSMiddleware,
allow_origins=["*"], # Διαμόρφωση κατάλληλη για παραγωγή
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
# Μοντέλα Pydantic για επικύρωση αιτήσεων/απαντήσεων
class ChatMessage(BaseModel):
message: str
class ChatResponse(BaseModel):
response: str
@app.get("/")
async def root():
"""Root endpoint providing API information."""
return {
"message": "Welcome to the AI Chat API",
"docs": "/docs",
"health": "/health"
}
@app.get("/health")
async def health_check():
"""Health check endpoint."""
return {"status": "healthy", "service": "ai-chat-api"}
@app.post("/hello", response_model=ChatResponse)
async def chat_endpoint(chat_message: ChatMessage):
"""Main chat endpoint that processes messages and returns AI responses."""
try:
# Εξαγωγή και επικύρωση μηνύματος
message = chat_message.message.strip()
if not message:
raise HTTPException(status_code=400, detail="Message cannot be empty")
logger.info(f"Processing message: {message[:50]}...")
# Κλήση υπηρεσίας AI (σημείωση: το call_llm θα πρέπει να γίνει ασύγχρονο για καλύτερη απόδοση)
ai_response = await call_llm_async(message, "You are a helpful and friendly assistant.")
logger.info("AI response generated successfully")
return ChatResponse(response=ai_response)
except HTTPException:
raise
except Exception as e:
logger.error(f"Error processing chat message: {str(e)}")
raise HTTPException(status_code=500, detail="Internal server error")
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=5000, reload=True)
```
**Κατανόηση της υλοποίησης FastAPI:**
- **Εισαγωγές** FastAPI για λειτουργικότητα σύγχρονου web framework και Pydantic για επικύρωση δεδομένων
- **Δημιουργεί** αυτόματη τεκμηρίωση API (διαθέσιμη στο `/docs` όταν τρέχει ο διακομιστής)
- **Ενεργοποιεί** CORS middleware για να επιτρέπει αιτήσεις frontend από διαφορετικές προελεύσεις
- **Ορίζει** μοντέλα Pydantic για αυτόματη επικύρωση αιτήσεων/απαντήσεων και τεκμηρίωση
- **Χρησιμοποιεί** ασύγχρονες τελικές σημεία για καλύτερη απόδοση με ταυτόχρονες αιτήσεις
- **Υλοποιεί** κατάλληλους κωδικούς κατάστασης HTTP και διαχείριση σφαλμάτων με HTTPException
- **Περιλαμβάνει** δομημένη καταγραφή για παρακολούθηση και αποσφαλμάτωση
- **Παρέχει** τελικό σημείο ελέγχου υγείας για παρακολούθηση κατάστασης υπηρεσίας
**Κύρια πλεονεκτήματα FastAPI έναντι παραδοσιακών πλαισίων:**
- **Αυτόματη επικύρωση**: Τα μοντέλα Pydantic εξασφαλίζουν την ακεραιότητα των δεδομένων πριν την επεξεργασία
- **Διαδραστική τεκμηρίωση**: Επισκεφτείτε `/docs` για αυτόματα παραγόμενη, δοκιμάσιμη τεκμηρίωση API
- **Ασφάλεια τύπων**: Οι σημειώσεις τύπων Python αποτρέπουν σφάλματα χρόνου εκτέλεσης και βελτιώνουν την ποιότητα κώδικα
- **Υποστήριξη async**: Διαχειριστείτε πολλαπλές αιτήσεις AI ταυτόχρονα χωρίς μπλοκάρισμα
- **Απόδοση**: Σημαντικά γρηγορότερη επεξεργασία αιτήσεων για εφαρμογές πραγματικού χρόνου
### Κατανόηση του CORS: Ο Φύλακας Ασφαλείας του Web
Το CORS (Cross-Origin Resource Sharing) είναι σαν τον φύλακα ασφαλείας σε ένα κτίριο που ελέγχει αν οι επισκέπτες έχουν δικαίωμα να μπουν. Ας κατανοήσουμε γιατί έχει σημασία και πώς επηρεάζει την εφαρμογή σας.
#### Τι είναι το CORS και γιατί υπάρχει;
**Το πρόβλημα**: Φανταστείτε αν οποιοσδήποτε ιστότοπος μπορούσε να κάνει αιτήσεις στην τράπεζά σας εξ ονόματός σας χωρίς την άδειά σας. Αυτό θα ήταν εφιάλτης ασφάλειας! Οι περιηγητές το αποτρέπουν αυτό από προεπιλογή μέσω της «Πολιτικής Ίδιας Προέλευσης».
**Πολιτική Ίδιας Προέλευσης**: Οι περιηγητές επιτρέπουν σε ιστοσελίδες να κάνουν αιτήσεις μόνο προς τον ίδιο τομέα, θύρα και πρωτόκολλο από όπου φορτώθηκαν.
**Πραγματική αναλογία**: Είναι σαν το κτίριο να έχει φύλακα – μόνο οι κάτοικοι (ίδια προέλευση) μπορούν να μπουν. Αν θέλετε να αφήσετε έναν φίλο (διαφορετική προέλευση) να επισκεφθεί, πρέπει να το πείτε ρητά στη φύλαξη.
#### Το CORS στο Περιβάλλον Ανάπτυξης σας
Κατά την ανάπτυξη, το frontend και το backend τρέχουν σε διαφορετικές θύρες:
- Frontend: `http://localhost:3000` (ή file:// αν ανοίξετε απευθείας HTML)
- Backend: `http://localhost:5000`
Αυτά θεωρούνται «διαφορετικές προελεύσεις» ακόμη κι αν είναι στον ίδιο υπολογιστή!
```python
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI(__name__)
CORS(app) # Αυτό λέει στους περιηγητές: "Είναι εντάξει για άλλες προελεύσεις να κάνουν αιτήματα σε αυτό το API"
```
**Τι κάνει η ρύθμιση CORS στην πράξη:**
- **Προσθέτει** ειδικούς HTTP headers στις απαντήσεις API που λένε στους περιηγητές «η αίτηση από αυτή την προέλευση επιτρέπεται»
- **Διαχειρίζεται** αιτήσεις "προελέγχου" (οι περιηγητές ελέγχουν τα δικαιώματα πριν στείλουν την πραγματική αίτηση)
- **Αποτρέπει** το μισητό σφάλμα «απόρριψη από πολιτική CORS» στην κονσόλα του περιηγητή σας
#### Ασφάλεια CORS: Ανάπτυξη vs Παραγωγή
```python
# 🚨 Ανάπτυξη: Επιτρέπει ΟΛΕΣ τις προελεύσεις (βολικό αλλά ανασφαλές)
CORS(app)
# ✅ Παραγωγή: Επιτρέπεται μόνο ο συγκεκριμένος τομέας frontend σας
CORS(app, origins=["https://yourdomain.com", "https://www.yourdomain.com"])
# 🔒 Προχωρημένο: Διαφορετικές προελεύσεις για διαφορετικά περιβάλλοντα
if app.debug: # Λειτουργία ανάπτυξης
CORS(app, origins=["http://localhost:3000", "http://127.0.0.1:3000"])
else: # Λειτουργία παραγωγής
CORS(app, origins=["https://yourdomain.com"])
```
**Γιατί αυτό έχει σημασία**: Στην ανάπτυξη, το `CORS(app)` είναι σαν να αφήνετε την πόρτα του σπιτιού σας ξεκλείδωτη – βολικό αλλά όχι ασφαλές. Στην παραγωγή θέλετε να καθορίσετε ακριβώς ποιοι ιστότοποι μπορούν να μιλήσουν με το API σας.
#### Συνηθισμένα Σενάρια CORS και Λύσεις
| Σενάριο | Πρόβλημα | Λύση |
|----------|---------|----------|
| **Τοπική Ανάπτυξη** | Το frontend δεν μπορεί να προσεγγίσει το backend | Προσθήκη CORSMiddleware στο FastAPI |
| **GitHub Pages + Heroku** | Το αναπτυγμένο frontend δεν φτάνει στο API | Προσθήκη της διεύθυνσης GitHub Pages στα origins του CORS |
| **Προσαρμοσμένος Τομέας** | Σφάλματα CORS στην παραγωγή | Ενημέρωση των origins του CORS για να ταιριάζουν στον τομέα σας |
| **Κινητή Εφαρμογή** | Η εφαρμογή δεν φτάνει στο Web API | Προσθήκη του domain της εφαρμογής σας ή προσεκτική χρήση του `*` |
**Συμβουλή εμπειρογνώμονα**: Μπορείτε να δείτε τους headers CORS στα Εργαλεία Ανάπτυξης του περιηγητή σας στην καρτέλα Δίκτυο. Ψάξτε για headers όπως `Access-Control-Allow-Origin` στην απάντηση.
### Διαχείριση Σφαλμάτων και Επικύρωση
Παρατηρήστε πώς το API μας περιλαμβάνει σωστή διαχείριση σφαλμάτων:
```python
# Επαληθεύστε ότι λάβαμε ένα μήνυμα
if not message:
return jsonify({"error": "Message field is required"}), 400
```
**Κύρια αρχές επικύρωσης:**
- **Ελέγχει** για απαραίτητα πεδία πριν επεξεργαστεί αιτήσεις
- **Επιστρέφει** κατανοητά μηνύματα σφάλματος σε μορφή JSON
- **Χρησιμοποιεί** κατάλληλους κωδικούς κατάστασης HTTP (400 για κακές αιτήσεις)
- **Παρέχει** σαφή ανατροφοδότηση για να βοηθήσει τους frontend προγραμματιστές να αποσφαλματώσουν
## Ρύθμιση και Εκτέλεση του Backend σας
Τώρα που έχουμε την ενσωμάτωση AI και τον διακομιστή FastAPI έτοιμους, ας εκκινήσουμε τα πάντα. Η διαδικασία ρύθμισης περιλαμβάνει εγκατάσταση εξαρτήσεων Python, ρύθμιση μεταβλητών περιβάλλοντος και εκκίνηση του server ανάπτυξης σας.
### Ρύθμιση Περιβάλλοντος Python
Ας στήσουμε το περιβάλλον ανάπτυξης Python σας. Τα εικονικά περιβάλλοντα είναι σαν τη διαμερισματοποίηση του Manhattan Project – κάθε έργο αποκτά το δικό του απομονωμένο χώρο με συγκεκριμένα εργαλεία και εξαρτήσεις, αποφεύγοντας συγκρούσεις μεταξύ διαφορετικών έργων.
```bash
# Μεταβείτε στον κατάλογο του backend σας
cd backend
# Δημιουργήστε ένα εικονικό περιβάλλον (σαν να δημιουργείτε ένα καθαρό δωμάτιο για το έργο σας)
python -m venv venv
# Ενεργοποιήστε το (Linux/Mac)
source ./venv/bin/activate
# Στα Windows, χρησιμοποιήστε:
# venv\Scripts\activate
# Εγκαταστήστε τα καλά πράγματα
pip install openai fastapi uvicorn python-dotenv
```
**Τι μόλις κάναμε:**
- **Δημιουργήσαμε** τη δική μας μικρή φούσκα Python όπου μπορούμε να εγκαθιστούμε πακέτα χωρίς να επηρεάζουμε οτιδήποτε άλλο
- **Ενεργοποιήσαμε** αυτή τη φούσκα ώστε το τερματικό να γνωρίζει να τη χρησιμοποιεί
- **Εγκαταστήσαμε** τα απαραίτητα: OpenAI για AI μαγεία, FastAPI για το web API μας, Uvicorn για να το τρέξουμε και python-dotenv για ασφαλή διαχείριση μυστικών
**Εξηγούνται βασικές εξαρτήσεις:**
- **FastAPI**: Σύγχρονο, γρήγορο web framework με αυτόματη τεκμηρίωση API
- **Uvicorn**: Αστραπιαία γρήγορος server ASGI που τρέχει εφαρμογές FastAPI
- **OpenAI**: Επίσημη βιβλιοθήκη για μοντέλα GitHub και ενσωμάτωση OpenAI API
- **python-dotenv**: Ασφαλές φορτωμα μεταβλητών περιβάλλοντος από αρχεία .env
### Διαμόρφωση Περιβάλλοντος: Διατήρηση Μυστικών Ασφαλών
Πριν ξεκινήσουμε το API μας, πρέπει να μιλήσουμε για ένα από τα πιο σημαντικά μαθήματα στην ανάπτυξη web: πώς να κρατάτε τα μυστικά σας πραγματικά μυστικά. Οι μεταβλητές περιβάλλοντος είναι σαν ένα ασφαλές χρηματοκιβώτιο που μόνο η εφαρμογή σας έχει πρόσβαση.
#### Τι είναι οι Μεταβλητές Περιβάλλοντος;
**Σκεφτείτε τις μεταβλητές περιβάλλοντος ως ένα θησαυροφυλάκιο ασφαλείας** – βάζετε τα πολύτιμα πράγματα εκεί, και μόνο εσείς (και η εφαρμογή σας) έχετε το κλειδί να τα βγάλετε. Αντί να γράφετε ευαίσθητες πληροφορίες απευθείας στον κώδικά σας (όπου κυριολεκτικά ο καθένας μπορεί να τις δει) τις αποθηκεύετε με ασφάλεια στο περιβάλλον.
**Να η διαφορά:**
- **Ο λάθος τρόπος**: Να γράφετε τον κωδικό σας σε χαρτάκι και να τον κολλάτε στην οθόνη σας
- **Ο σωστός τρόπος**: Να κρατάτε τον κωδικό σε διαχειριστή κωδικών που μόνο εσείς μπορείτε να ανοίξετε
#### Γιατί έχουν σημασία οι Μεταβλητές Περιβάλλοντος
```python
# 🚨 ΠΟΤΕ ΜΗΝ ΤΟ ΚΑΝΕΤΕ ΑΥΤΟ - Κλειδί API ορατό σε όλους
client = OpenAI(
api_key="ghp_1234567890abcdef...", # Ο καθένας μπορεί να το κλέψει!
base_url="https://models.github.ai/inference"
)
# ✅ ΚΑΝΤΕ ΑΥΤΟ - Κλειδί API αποθηκευμένο με ασφάλεια
client = OpenAI(
api_key=os.environ["GITHUB_TOKEN"], # Μόνο η εφαρμογή σας μπορεί να έχει πρόσβαση σε αυτό
base_url="https://models.github.ai/inference"
)
```
**Τι συμβαίνει αν βάζετε μυστικά σκληρά κωδικοποιημένα:**
1. **Έκθεση σε έλεγχο έκδοσης**: Όποιος έχει πρόσβαση στο αποθετήριο Git βλέπει το API key σας
2. **Δημόσια αποθετήρια**: Αν σπρώξετε κώδικα στο GitHub, το κλειδί σας είναι ορατό στο διαδίκτυο
3. **Κοινοτική χρήση**: Άλλοι προγραμματιστές που δουλεύουν στο έργο σας έχουν πρόσβαση στο προσωπικό σας API key
4. **Παραβιάσεις ασφάλειας**: Αν κλέψουν το API key σας, μπορούν να χρησιμοποιήσουν τα credits AI σας
#### Ρύθμιση του Αρχείου Περιβάλλοντος σας
Δημιουργήστε ένα αρχείο `.env` στο φάκελο backend σας. Αυτό το αρχείο αποθηκεύει τα μυστικά σας τοπικά:
```bash
# Αρχείο .env - Αυτό δεν πρέπει ΠΟΤΕ να δεσμευτεί στο Git
GITHUB_TOKEN=your_github_personal_access_token_here
FASTAPI_DEBUG=True
ENVIRONMENT=development
```
**Κατανόηση αρχείου .env:**
- **Ένα μυστικό ανά γραμμή** σε μορφή `KEY=value`
- **Χωρίς κενά** γύρω από το σύμβολο ίσον
- **Χωρίς εισαγωγικά** γύρω από τις τιμές (συνήθως)
- **Σχόλια** ξεκινούν με `#`
#### Δημιουργία του Προσωπικού Access Token του GitHub
Το token GitHub σας είναι σαν ειδικός κωδικός που δίνει στην εφαρμογή σας δικαίωμα να χρησιμοποιεί τις υπηρεσίες AI του GitHub:
**Βήμα προς βήμα δημιουργία token:**
1. **Πηγαίνετε στις Ρυθμίσεις GitHub** → Ρυθμίσεις προγραμματιστή → Προσωπικά access tokens → Tokens (classic)
2. **Κάντε κλικ στο "Generate new token (classic)"**
3. **Ορίστε λήξη** (30 μέρες για δοκιμές, μεγαλύτερο για παραγωγή)
4. **Επιλέξτε scopes**: Επιλέξτε "repo" και όποια άλλα δικαιώματα χρειάζεστε
5. **Δημιουργήστε token** και αντιγράψτε το αμέσως (δεν μπορείτε να το δείτε ξανά!)
6. **Επικολλήστε το στο αρχείο .env σας**
```bash
# Παράδειγμα του πώς μοιάζει το token σας (αυτό είναι ψεύτικο!)
GITHUB_TOKEN=ghp_1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R
```
#### Φόρτωση Μεταβλητών Περιβάλλοντος στην Python
```python
import os
from dotenv import load_dotenv
# Φόρτωση μεταβλητών περιβάλλοντος από το αρχείο .env
load_dotenv()
# Τώρα μπορείτε να έχετε πρόσβαση σε αυτές με ασφάλεια
api_key = os.environ.get("GITHUB_TOKEN")
if not api_key:
raise ValueError("GITHUB_TOKEN not found in environment variables!")
client = OpenAI(
api_key=api_key,
base_url="https://models.github.ai/inference"
)
```
**Τι κάνει αυτός ο κώδικας:**
- **Φορτώνει** το αρχείο .env και κάνει τις μεταβλητές διαθέσιμες στην Python
- **Ελέγχει** αν υπάρχει το απαιτούμενο token (καλή διαχείριση σφαλμάτων!)
- **Σημαίνει** σαφές σφάλμα αν λείπει το token
- **Χρησιμοποιεί** το token με ασφάλεια χωρίς να το εκθέτει στον κώδικα
#### Ασφάλεια Git: Το αρχείο .gitignore
Το `.gitignore` λέει στο Git ποια αρχεία δεν πρέπει ποτέ να παρακολουθεί ή να ανεβάζει:
```bash
# .gitignore - Προσθέστε αυτές τις γραμμές
.env
*.env
.env.local
.env.production
__pycache__/
venv/
.vscode/
```
**Γιατί αυτό είναι κρίσιμο**: Μόλις προσθέσετε το `.env` στο `.gitignore`, το Git θα αγνοήσει το αρχείο περιβάλλοντος, αποτρέποντας το ακούσιο ανέβασμα των μυστικών σας στο GitHub.
#### Διαφορετικά Περιβάλλοντα, Διάφορα Μυστικά
Επαγγελματικές εφαρμογές χρησιμοποιούν διαφορετικά κλειδιά API για διαφορετικά περιβάλλοντα:
```bash
# .env.ανάπτυξη
GITHUB_TOKEN=your_development_token
DEBUG=True
# .env.παραγωγή
GITHUB_TOKEN=your_production_token
DEBUG=False
```
**Γιατί έχει σημασία αυτό**: Δεν θέλετε τα πειράματά σας στην ανάπτυξη να επηρεάζουν το όριο χρήσης AI παραγωγής, και θέλετε διαφορετικά επίπεδα ασφάλειας για διαφορετικά περιβάλλοντα.
### Εκκίνηση του Server Ανάπτυξής σας: Φέρνοντας στη Ζωή το FastAPI σας
Τώρα έρχεται η συναρπαστική στιγμή – να ξεκινήσετε τον διακομιστή ανάπτυξης FastAPI και να δείτε την ενσωμάτωση AI να ζωντανεύει! Το FastAPI χρησιμοποιεί τον Uvicorn, έναν εξαιρετικά γρήγορο ASGI διακομιστή που έχει σχεδιαστεί ειδικά για ασύγχρονες εφαρμογές Python.
#### Κατανόηση της διαδικασίας εκκίνησης του διακομιστή FastAPI
```bash
# Μέθοδος 1: Άμεση εκτέλεση Python (περιλαμβάνει αυτόματη επαναφόρτωση)
python api.py
# Μέθοδος 2: Χρήση Uvicorn απευθείας (περισσότερος έλεγχος)
uvicorn api:app --host 0.0.0.0 --port 5000 --reload
```
Όταν εκτελείτε αυτήν την εντολή, αυτό συμβαίνει στα παρασκήνια:
**1. Η Python φορτώνει την εφαρμογή FastAPI σας**:
- Εισάγει όλες τις απαιτούμενες βιβλιοθήκες (FastAPI, Pydantic, OpenAI κ.ά.)
- Φορτώνει τις μεταβλητές περιβάλλοντος από το αρχείο `.env`
- Δημιουργεί το στιγμιότυπο της εφαρμογής FastAPI με αυτόματη τεκμηρίωση
**2. Ο Uvicorn ρυθμίζει τον ASGI διακομιστή**:
- Δεσμεύεται στην θύρα 5000 με δυνατότητες ασύγχρονης διαχείρισης αιτήσεων
- Ορίζει δρομολόγηση αιτήσεων με αυτόματη επικύρωση
- Ενεργοποιεί το hot reload για ανάπτυξη (επανεκκινήσεις σε αλλαγές αρχείων)
- Δημιουργεί διαδραστική τεκμηρίωση API
**3. Ο διακομιστής αρχίζει να ακούει**:
- Το τερματικό σας εμφανίζει: `INFO: Uvicorn running on http://0.0.0.0:5000`
- Ο διακομιστής μπορεί να χειριστεί πολλαπλές ταυτόχρονες αιτήσεις AI
- Το API σας είναι έτοιμο με αυτόματη τεκμηρίωση στο `http://localhost:5000/docs`
#### Τι πρέπει να δείτε όταν όλα λειτουργούν
```bash
$ python api.py
INFO: Will watch for changes in these directories: ['/your/project/path']
INFO: Uvicorn running on http://0.0.0.0:5000 (Press CTRL+C to quit)
INFO: Started reloader process [12345] using WatchFiles
INFO: Started server process [12346]
INFO: Waiting for application startup.
INFO: Application startup complete.
```
**Κατανόηση της εξόδου FastAPI:**
- **Will watch for changes**: Ενεργοποιημένο το auto-reload για ανάπτυξη
- **Uvicorn running**: Ο υψηλής απόδοσης ASGI διακομιστής είναι ενεργός
- **Started reloader process**: Παρακολούθηση αρχείων για αυτόματες επανεκκινήσεις
- **Application startup complete**: Η εφαρμογή FastAPI ξεκίνησε επιτυχώς
- **Interactive docs available**: Επισκεφθείτε το `/docs` για αυτόματη τεκμηρίωση API
#### Δοκιμή του FastAPI σας: Πολλαπλοί Ισχυροί Τρόποι
Το FastAPI παρέχει διάφορους βολικούς τρόπους για να δοκιμάσετε το API σας, συμπεριλαμβανομένης της αυτόματης διαδραστικής τεκμηρίωσης:
**Μέθοδος 1: Διαδραστική Τεκμηρίωση API (Συνιστάται)**
1. Ανοίξτε τον περιηγητή σας και μεταβείτε στο `http://localhost:5000/docs`
2. Θα δείτε το Swagger UI με όλα τα σημεία πρόσβασης τεκμηριωμένα
3. Κάντε κλικ στο `/hello` → "Try it out" → Εισάγετε ένα μήνυμα δοκιμής → "Execute"
4. Δείτε την απάντηση απευθείας στον περιηγητή με σωστή μορφοποίηση
**Μέθοδος 2: Βασική δοκιμή από τον περιηγητή**
1. Μεταβείτε στο `http://localhost:5000` για το βασικό endpoint
2. Μεταβείτε στο `http://localhost:5000/health` για έλεγχο υγείας διακομιστή
3. Αυτό επιβεβαιώνει ότι ο διακομιστής FastAPI λειτουργεί σωστά
**Μέθοδος 2: Δοκιμή από τη γραμμή εντολών (Προχωρημένη)**
```bash
# Δοκιμή με curl (αν είναι διαθέσιμο)
curl -X POST http://localhost:5000/hello \
-H "Content-Type: application/json" \
-d '{"message": "Hello AI!"}'
# Αναμενόμενη απάντηση:
# {"response": "Γεια! Είμαι ο βοηθός AI σας. Πώς μπορώ να σας βοηθήσω σήμερα;"}
```
**Μέθοδος 3: Σενάριο δοκιμής Python**
```python
# test_api.py - Δημιουργήστε αυτό το αρχείο για να δοκιμάσετε το API σας
import requests
import json
# Δοκιμάστε το endpoint του API
url = "http://localhost:5000/hello"
data = {"message": "Tell me a joke about programming"}
response = requests.post(url, json=data)
if response.status_code == 200:
result = response.json()
print("AI Response:", result['response'])
else:
print("Error:", response.status_code, response.text)
```
#### Επίλυση Συνηθισμένων Προβλημάτων Εκκίνησης
| Μήνυμα Σφάλματος | Τι Σημαίνει | Πώς να το Διορθώσετε |
|------------------|-------------|----------------------|
| `ModuleNotFoundError: No module named 'fastapi'` | Το FastAPI δεν είναι εγκατεστημένο | Εκτελέστε `pip install fastapi uvicorn` στο virtual environment σας |
| `ModuleNotFoundError: No module named 'uvicorn'` | Ο ASGI διακομιστής δεν είναι εγκατεστημένος | Εκτελέστε `pip install uvicorn` στο virtual environment σας |
| `KeyError: 'GITHUB_TOKEN'` | Η μεταβλητή περιβάλλοντος δεν βρέθηκε | Ελέγξτε το `.env` αρχείο σας και την κλήση `load_dotenv()` |
| `Address already in use` | Η θύρα 5000 είναι κατειλημμένη | Τερματίστε άλλες διεργασίες που χρησιμοποιούν τη θύρα 5000 ή αλλάξτε τη θύρα |
| `ValidationError` | Τα δεδομένα αιτήματος δεν ταιριάζουν με το μοντέλο Pydantic | Ελέγξτε ότι η μορφή αιτήματος ταιριάζει με το αναμενόμενο σχήμα |
| `HTTPException 422` | Μη επεξεργάσιμη οντότητα | Η επικύρωση του αιτήματος απέτυχε, δείτε το `/docs` για σωστή μορφή |
| `OpenAI API error` | Αποτυχία πιστοποίησης υπηρεσίας AI | Επαληθεύστε ότι το GitHub token σας είναι σωστό και έχει τις απαραίτητες άδειες |
#### Καλύτερες Πρακτικές Ανάπτυξης
**Hot Reloading**: Το FastAPI με Uvicorn παρέχει αυτόματη επανεκκίνηση όταν αποθηκεύετε αλλαγές στα αρχεία Python. Αυτό σημαίνει ότι μπορείτε να τροποποιείτε τον κώδικα και να δοκιμάζετε αμέσως χωρίς χειροκίνητη επανεκκίνηση.
```python
# Ενεργοποίηση της ζεστής επαναφόρτωσης ρητά
if __name__ == "__main__":
app.run(host="0.0.0.0", port=5000, debug=True) # debug=True ενεργοποιεί τη ζεστή επαναφόρτωση
```
**Καταγραφή για την Ανάπτυξη**: Προσθέστε καταγραφές για να κατανοείτε τι συμβαίνει:
```python
import logging
# Ρυθμίστε την καταγραφή
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
@app.route("/hello", methods=["POST"])
def hello():
data = request.get_json()
message = data.get("message", "")
logger.info(f"Received message: {message}")
if not message:
logger.warning("Empty message received")
return jsonify({"error": "Message field is required"}), 400
try:
response = call_llm(message, "You are a helpful and friendly assistant.")
logger.info(f"AI response generated successfully")
return jsonify({"response": response})
except Exception as e:
logger.error(f"AI API error: {str(e)}")
return jsonify({"error": "AI service temporarily unavailable"}), 500
```
**Γιατί βοηθά η καταγραφή**: Κατά την ανάπτυξη, μπορείτε να δείτε ακριβώς ποιες αιτήσεις έρχονται, τι απαντά το AI και πού εμφανίζονται σφάλματα. Αυτό καθιστά τον εντοπισμό σφαλμάτων πολύ πιο γρήγορο.
### Ρύθμιση για GitHub Codespaces: Ανάπτυξη στο Cloud με Εύκολο Τρόπο
Το GitHub Codespaces είναι σαν να έχετε έναν ισχυρό υπολογιστή ανάπτυξης στο cloud που μπορείτε να προσπελάσετε από οποιονδήποτε περιηγητή. Αν εργάζεστε σε Codespaces, υπάρχουν μερικά πρόσθετα βήματα για να κάνετε το backend σας προσβάσιμο στο frontend σας.
#### Κατανόηση Δικτύωσης στα Codespaces
Σε ένα τοπικό περιβάλλον ανάπτυξης, όλα τρέχουν στον ίδιο υπολογιστή:
- Backend: `http://localhost:5000`
- Frontend: `http://localhost:3000` (ή file://)
Στα Codespaces, το περιβάλλον ανάπτυξής σας τρέχει στους servers του GitHub, οπότε το "localhost" έχει διαφορετική έννοια. Το GitHub δημιουργεί αυτόματα δημόσια URLs για τις υπηρεσίες σας, αλλά πρέπει να τις ρυθμίσετε σωστά.
#### Βήμα-βήμα Ρύθμιση Codespaces
**1. Εκκινήστε τον backend διακομιστή σας**:
```bash
cd backend
python api.py
```
Θα δείτε το γνώριμο μήνυμα εκκίνησης FastAPI/Uvicorn, αλλά σημειώστε ότι τρέχει μέσα στο περιβάλλον Codespace.
**2. Ρυθμίστε την ορατότητα της θύρας**:
- Βρείτε την καρτέλα "Ports" στο κάτω πάνελ του VS Code
- Βρείτε τη θύρα 5000 στη λίστα
- Δεξί κλικ στη θύρα 5000
- Επιλέξτε "Port Visibility" → "Public"
**Γιατί να το κάνετε δημόσιο;** Από προεπιλογή, οι θύρες στο Codespace είναι ιδιωτικές (προσβάσιμες μόνο από εσάς). Δημόσιο επιτρέπει στο frontend (που τρέχει στον περιηγητή) να επικοινωνεί με το backend.
**3. Πάρτε το δημόσιο URL σας**:
Μετά τη δημόσια ρύθμιση θύρας, θα δείτε ένα URL όπως:
```
https://your-codespace-name-5000.app.github.dev
```
**4. Ενημερώστε τη ρύθμιση του frontend**:
```javascript
// Στο frontend app.js σας, ενημερώστε το BASE_URL:
this.BASE_URL = "https://your-codespace-name-5000.app.github.dev";
```
#### Κατανόηση των URLs του Codespace
Τα URLs του Codespace ακολουθούν ένα προβλέψιμο μοτίβο:
```
https://[codespace-name]-[port].app.github.dev
```
**Ανάλυση:**
- `codespace-name`: Ένας μοναδικός αναγνωριστικός για το Codespace σας (συνήθως περιλαμβάνει το όνομα χρήστη)
- `port`: Αριθμός θύρας όπου τρέχει η υπηρεσία σας (5000 για την εφαρμογή FastAPI)
- `app.github.dev`: Ο τομέας του GitHub για εφαρμογές Codespace
#### Δοκιμή της Ρύθμισης Codespace
**1. Δοκιμάστε το backend απευθείας**:
Ανοίξτε το δημόσιο URL σε νέα καρτέλα περιηγητή. Θα δείτε:
```
Welcome to the AI Chat API. Send POST requests to /hello with JSON payload containing 'message' field.
```
**2. Δοκιμάστε με εργαλεία προγραμματιστή στον περιηγητή**:
```javascript
// Ανοίξτε την κονσόλα του προγράμματος περιήγησης και δοκιμάστε το API σας
fetch('https://your-codespace-name-5000.app.github.dev/hello', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({message: 'Hello from Codespaces!'})
})
.then(response => response.json())
.then(data => console.log(data));
```
#### Codespaces vs Τοπική Ανάπτυξη
| Παράμετρος | Τοπική Ανάπτυξη | GitHub Codespaces |
|------------|-----------------|-------------------|
| **Χρόνος Ρύθμισης** | Μεγαλύτερος (εγκατάσταση Python, εξαρτήσεων) | Άμεση (προρυθμισμένο περιβάλλον) |
| **Πρόσβαση URL** | `http://localhost:5000` | `https://xyz-5000.app.github.dev` |
| **Διαμόρφωση Θύρας** | Αυτόματη | Χειροκίνητη (δημόσιοι θύρες) |
| **Διατήρηση Αρχείων** | Τοπικός υπολογιστής | Αποθετήριο GitHub |
| **Συνεργασία** | Δύσκολο να μοιραστείτε περιβάλλον | Εύκολο να μοιραστείτε σύνδεσμο Codespace |
| **Εξάρτηση από Διαδίκτυο** | Μόνο για κλήσεις AI API | Απαιτείται για τα πάντα |
#### Συμβουλές Ανάπτυξης Codespace
**Μεταβλητές Περιβάλλοντος στα Codespaces**:
Το αρχείο `.env` λειτουργεί όπως και στο τοπικό, αλλά μπορείτε επίσης να ορίσετε μεταβλητές περιβάλλοντος απευθείας στο Codespace:
```bash
# Ορίστε μεταβλητή περιβάλλοντος για την τρέχουσα συνεδρία
export GITHUB_TOKEN="your_token_here"
# Ή προσθέστε στο .bashrc σας για μόνιμη διατήρηση
echo 'export GITHUB_TOKEN="your_token_here"' >> ~/.bashrc
```
**Διαχείριση Θυρών**:
- Τα Codespaces ανιχνεύουν αυτόματα όταν η εφαρμογή αρχίζει να ακούει σε μια θύρα
- Μπορείτε να προωθήσετε πολλαπλές θύρες ταυτόχρονα (χρήσιμο αν προσθέσετε βάση δεδομένων αργότερα)
- Οι θύρες παραμένουν προσβάσιμες όσο το Codespace τρέχει
**Ροή Εργασίας Ανάπτυξης**:
1. Κάντε αλλαγές στον κώδικα στο VS Code
2. Το FastAPI επανφορτώνει αυτόματα (χάρη στη λειτουργία reload του Uvicorn)
3. Δοκιμάστε τις αλλαγές άμεσα μέσω του δημόσιου URL
4. Κάντε commit και push όταν είστε έτοιμοι
> 💡 **Συμβουλή Επαγγελματία**: Κρατήστε στα αγαπημένα το URL του backend στο Codespace κατά την ανάπτυξη. Επειδή τα ονόματα Codespace είναι σταθερά, το URL δεν αλλάζει όσο χρησιμοποιείτε το ίδιο Codespace.
## Δημιουργία της Εμπρόσθιας Εφαρμογής Συνομιλίας: Όπου οι Άνθρωποι Συναντούν το AI
Τώρα θα κατασκευάσουμε το περιβάλλον χρήστη – το μέρος που καθορίζει πώς οι άνθρωποι αλληλεπιδρούν με τον βοηθό AI σας. Όπως ο σχεδιασμός της αρχικής διεπαφής iPhone, εστιάζουμε στο να κάνουμε την πολύπλοκη τεχνολογία να φαίνεται διαισθητική και φυσική στη χρήση.
### Κατανόηση της Σύγχρονης Αρχιτεκτονικής Frontend
Η διεπαφή συνομιλίας μας θα είναι αυτό που ονομάζουμε "Εφαρμογή Μίας Σελίδας" ή SPA. Αντί για την παλιά μέθοδο όπου κάθε κλικ φορτώνει νέα σελίδα, η εφαρμογή μας ενημερώνει ομαλά και άμεσα:
**Παλιά ιστοσελίδα**: Όπως το να διαβάζεις ένα φυσικό βιβλίο – γυρίζεις σε εντελώς νέες σελίδες
**Η εφαρμογή συνομιλίας μας**: Όπως το να χρησιμοποιείς το τηλέφωνό σου – όλα ρέουν και ενημερώνονται χωρίς διακοπή
```mermaid
graph TD
A[Ο Χρήστης Πληκτρολογεί Μήνυμα] --> B[Η JavaScript Καταγράφει την Είσοδο]
B --> C[Επικύρωση & Μορφοποίηση Δεδομένων]
C --> D[Αποστολή στο Backend API]
D --> E[Εμφάνιση Κατάστασης Φόρτωσης]
E --> F[Λήψη Απάντησης AI]
F --> G[Ενημέρωση Διεπαφής Συνομιλίας]
G --> H[Έτοιμο για Επόμενο Μήνυμα]
```
```mermaid
classDiagram
class ChatApp {
+messages: HTMLElement
+form: HTMLElement
+input: HTMLElement
+sendButton: HTMLElement
+BASE_URL: string
+API_ENDPOINT: string
+constructor()
+initializeEventListeners()
+handleSubmit(event)
+callAPI(message)
+appendMessage(text, role)
+escapeHtml(text)
+scrollToBottom()
+setLoading(isLoading)
}
ChatApp --> DOM : χειρίζεται
ChatApp --> FastAPI : στέλνει αιτήματα
```
### Οι Τρεις Πυλώνες της Ανάπτυξης Frontend
Κάθε εφαρμογή frontend – από απλές ιστοσελίδες μέχρι πολύπλοκες εφαρμογές όπως το Discord ή Slack – βασίζεται σε τρεις βασικές τεχνολογίες. Σκεφτείτε τες ως τη βάση για ό,τι βλέπετε και με το οποίο αλληλεπιδράτε στο διαδίκτυο:
**HTML (Δομή)**: Είναι το θεμέλιο σας
- Αποφασίζει ποια στοιχεία υπάρχουν (κουμπιά, περιοχές κειμένου, κοντέινερ)
- Δίνει νόημα στο περιεχόμενο (αυτό είναι κεφαλίδα, αυτό είναι φόρμα, κλπ.)
- Δημιουργεί τη βασική δομή πάνω στην οποία χτίζεται τα πάντα
**CSS (Παρουσίαση)**: Είναι ο εσωτερικός σχεδιαστής
- Κάνει όλα να φαίνονται όμορφα (χρώματα, γραμματοσειρές, διατάξεις)
- Διαχειρίζεται διαφορετικά μεγέθη οθονών (τηλέφωνο, λάπτοπ, τάμπλετ)
- Δημιουργεί ομαλές κινήσεις και οπτικά εφέ
**JavaScript (Συμπεριφορά)**: Είναι ο εγκέφαλος
- Ανταποκρίνεται σε ενέργειες χρηστών (κλικ, πληκτρολόγηση, κύλιση)
- Επικοινωνεί με το backend και ενημερώνει τη σελίδα
- Κάνει τα πάντα διαδραστικά και δυναμικά
**Σκεφτείτε το σαν αρχιτεκτονικό σχέδιο:**
- **HTML**: Το δομικό σχέδιο (ορίζει χώρους και σχέσεις)
- **CSS**: Ο αισθητικός και περιβαλλοντικός σχεδιασμός (οπτικό στυλ και εμπειρία χρήστη)
- **JavaScript**: Τα μηχανικά συστήματα (λειτουργικότητα και διαδραστικότητα)
### Γιατί έχει Σημασία η Σύγχρονη Αρχιτεκτονική JavaScript
Η εφαρμογή συνομιλίας μας θα χρησιμοποιήσει σύγχρονα μοτίβα JavaScript που βλέπετε σε επαγγελματικές εφαρμογές. Η κατανόηση αυτών των εννοιών θα σας βοηθήσει καθώς θα εξελίσσεστε ως προγραμματιστής:
**Αρχιτεκτονική με Κλάσεις**: Θα οργανώσουμε τον κώδικά μας σε κλάσεις, που είναι σαν να δημιουργούμε σχέδια αντικειμένων
**Async/Await**: Σύγχρονος τρόπος για χειρισμό λειτουργιών που παίρνουν χρόνο (π.χ. κλήσεις API)
**Προγραμματισμός με Βάση τα Γεγονότα**: Η εφαρμογή μας ανταποκρίνεται σε ενέργειες χρηστών (κλικ, πατήματα πλήκτρων) αντί να τρέχει σε βρόχο
**Διαχείριση DOM**: Δυναμική ενημέρωση του περιεχομένου της σελίδας βάσει αλληλεπιδράσεων χρηστών και απαντήσεων API
### Δομή Έργου
Δημιουργήστε έναν φάκελο frontend με την παρακάτω οργανωμένη δομή:
```text
frontend/
├── index.html # Main HTML structure
├── app.js # JavaScript functionality
└── styles.css # Visual styling
```
**Κατανόηση της αρχιτεκτονικής:**
- **Διαχωρίζει** τις ανησυχίες μεταξύ δομής (HTML), συμπεριφοράς (JavaScript) και παρουσίασης (CSS)
- **Διατηρεί** μια απλή δομή φακέλων που είναι εύκολη στην πλοήγηση και τροποποίηση
- **Ακολουθεί** βέλτιστες πρακτικές web ανάπτυξης για οργάνωση και ευκολία συντήρησης
### Κατασκευή της Βάσης HTML: Σημασιολογική Δομή για Προσβασιμότητα
Ας ξεκινήσουμε με τη δομή HTML. Η σύγχρονη ανάπτυξη web δίνει έμφαση στο "σημασιολογικό HTML" – τη χρήση HTML στοιχείων που περιγράφουν καθαρά τον σκοπό τους, όχι απλώς την εμφάνισή τους. Αυτό κάνει την εφαρμογή σας προσβάσιμη σε αναγνώστες οθόνης, μηχανές αναζήτησης και άλλα εργαλεία.
**Γιατί έχει σημασία το σημασιολογικό HTML**: Φανταστείτε πως περιγράφετε την εφαρμογή συνομιλίας σας σε κάποιον τηλεφωνικά. Θα λέγατε "υπάρχει μια κεφαλίδα με τίτλο, μια κύρια περιοχή όπου εμφανίζονται οι συνομιλίες, και μια φόρμα στο κάτω μέρος για να γράφεις μηνύματα." Το σημασιολογικό HTML χρησιμοποιεί στοιχεία που ταιριάζουν σε αυτήν την φυσική περιγραφή.
Δημιουργήστε το `index.html` με αυτήν την προσεκτικά δομημένη σήμανση:
```html
AI Chat Assistant
AI Chat Assistant
Ask me anything!
```
**Κατανόηση κάθε HTML στοιχείου και του σκοπού του:**
#### Δομή Εγγράφου
- **``**: Ενημερώνει τον περιηγητή ότι πρόκειται για σύγχρονο HTML5
- **``**: Καθορίζει τη γλώσσα της σελίδας για αναγνώστες οθόνης και εργαλεία μετάφρασης
- **``**: Εξασφαλίζει σωστή κωδικοποίηση χαρακτήρων για διεθνές κείμενο
- **``**: Κάνει τη σελίδα φιλική για κινητές συσκευές ελέγχοντας το zoom και το μέγεθος
#### Σημασιολογικά Στοιχεία
- **``**: Ταυτοποιεί σαφώς το πάνω μέρος με τίτλο και περιγραφή
- **``**: Προορίζεται για το κύριο περιεχόμενο (εκεί που συμβαίνουν οι συνομιλίες)
- **`