# Construiește un Asistent de Chat cu AI
Îți amintești în Star Trek când echipajul purta conversații casual cu computerul navei, punând întrebări complexe și primind răspunsuri bine gândite? Ce părea a fi pură science fiction în anii '60 este acum ceva ce poți construi folosind tehnologiile web pe care deja le cunoști.
În această lecție, vom crea un asistent de chat AI folosind HTML, CSS, JavaScript și o integrare backend. Vei descoperi cum aceleași abilități pe care le-ai învățat pot conecta la servicii AI puternice care pot înțelege contextul și genera răspunsuri relevante.
Gândește-te la AI ca la accesul la o bibliotecă uriașă care nu doar găsește informații, ci și le sintetizează în răspunsuri coerente, adaptate întrebărilor tale specifice. În loc să cauți prin mii de pagini, primești răspunsuri directe și contextuale.
Integrarea are loc prin tehnologii web familiare care lucrează împreună. HTML creează interfața de chat, CSS gestionează designul vizual, JavaScript gestionează interacțiunile utilizatorului, iar un API backend conectează totul cu serviciile AI. Este similar cu modul în care diferitele secțiuni ale unei orchestre colaborează pentru a crea o simfonie.
Practic construim o punte între comunicarea naturală umană și procesarea automată. Vei învăța atât implementarea tehnică a integrării serviciilor AI, cât și modelele de design care fac interacțiunile să pară intuitive.
La finalul acestei lecții, integrarea AI va părea mai puțin un proces misterios și mai mult un API obișnuit cu care poți lucra. Vei înțelege modelele fundamentale care stau la baza aplicațiilor precum ChatGPT și Claude, folosind aceleași principii de dezvoltare web pe care le-ai studiat.
## ⚡ Ce Poți Face în Următoarele 5 Minute
**Traseu Rapid pentru Dezvoltatori Ocupați**
```mermaid
flowchart LR
A[⚡ 5 minute] --> B[Obține token GitHub]
B --> C[Testează teren de joacă AI]
C --> D[Copiază cod Python]
D --> E[Vezi răspunsurile AI]
```
- **Minutul 1**: Vizitează [GitHub Models Playground](https://github.com/marketplace/models/azure-openai/gpt-4o-mini/playground) și creează un token personal de acces
- **Minutul 2**: Testează interacțiunile AI direct în interfața playground-ului
- **Minutul 3**: Apasă pe fila "Code" și copiază snippet-ul Python
- **Minutul 4**: Rulează codul local cu tokenul tău: `GITHUB_TOKEN=tokenul_tău python test.py`
- **Minutul 5**: Vezi primul răspuns AI generat de codul tău
**Cod de Test Rapid**:
```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)
```
**De ce contează asta**: În 5 minute, vei experimenta magia interacțiunii programatice cu AI. Acesta reprezintă blocul fundamental care alimentează orice aplicație AI pe care o folosești.
Iată cum va arăta proiectul tău finalizat:
## 🗺️ Călătoria ta de învățare prin dezvoltarea aplicațiilor AI
```mermaid
journey
title De la Dezvoltare Web la Integrare AI
section Înțelegerea Bazelor AI
Descoperă conceptele de AI generativ: 4: You
Explorează platforma GitHub Models: 6: You
Stăpânește parametrii și prompturile AI: 8: You
section Integrare Backend
Construiește server API Python: 5: You
Implementează apeluri de funcții AI: 7: You
Gestionează operațiuni asincrone: 8: You
section Dezvoltare Frontend
Creează interfață de chat modernă: 6: You
Stăpânește interacțiunile în timp real: 8: You
Construiește experiență utilizator responsivă: 9: You
section Aplicare Profesională
Deplasează sistem AI complet: 7: You
Optimizează modele de performanță: 8: You
Creează aplicație gata de producție: 9: You
```
**Destinația călătoriei tale**: La finalul acestei lecții, vei fi construit o aplicație completă alimentată de AI folosind aceleași tehnologii și modele care stau la baza asistenților AI moderni precum ChatGPT, Claude și Google Bard.
## Înțelegerea AI: De la Mister la Măiestrie
Înainte să intrăm în cod, hai să înțelegem cu ce lucrăm. Dacă ai folosit API-uri anterior, știi modelul de bază: trimiți o cerere, primești un răspuns.
API-urile AI urmează o structură similară, dar în loc să recupereze date pre-stocate dintr-o bază de date, ele generează răspunsuri noi bazate pe tipare învățate dintr-o cantitate imensă de text. Gândește-te la diferența dintre un sistem de catalogare a bibliotecii și un bibliotecar priceput care poate sintetiza informații din surse multiple.
### Ce este cu adevărat "Generative AI"?
Gândește-te cum Piatra Rosetta a permis savanților să înțeleagă hieroglifele egiptene găsind tipare între limbile cunoscute și cele necunoscute. Modelele AI funcționează similar – găsesc tipare în cantități uriașe de text pentru a înțelege cum funcționează limbajul și apoi folosesc aceste tipare pentru a genera răspunsuri potrivite la întrebări noi.
**Hai să descompunem asta cu o comparație simplă:**
- **Bază de date tradițională**: Ca și cum ai cere certificatul de naștere – primești același document exact de fiecare dată
- **Motor de căutare**: Ca și cum ai cere unui bibliotecar să găsească cărți despre pisici – îți arată ce este disponibil
- **Generative AI**: Ca și cum ai întreba un prieten informat despre pisici – îți spune lucruri interesante cu propriile cuvinte, adaptate la ce vrei să știi
```mermaid
graph LR
A[Întrebarea Ta] --> B[Model AI]
B --> C[Recunoaștere de Tipare]
C --> D[Generare de Conținut]
D --> E[Răspuns Contextual]
F[Date de Antrenament Cărți, Articole, Web] --> B
```
### Cum învață modelele AI (Versiunea Simplă)
Modelele AI învață prin expunerea la seturi enorme de date care conțin text din cărți, articole și conversații. Prin acest proces identifică tipare în:
- Modul în care gândurile sunt structurate în comunicarea scrisă
- Care cuvinte apar frecvent împreună
- Cum decurg tipic conversațiile
- Diferențele contextuale între comunicarea formală și informală
**Este similar cu modul în care arheologii descifrează limbile antice**: analizează mii de exemple pentru a înțelege gramatica, vocabularul și contextul cultural, devenind în cele din urmă capabili să interpreteze texte noi folosind aceste tipare învățate.
### De ce GitHub Models?
Folosim GitHub Models dintr-un motiv foarte practic – ne oferă acces la AI de nivel enterprise fără să trebuiască să ne configurăm propria infrastructură AI (iar crede-mă, nu vrei asta acum!). Gândește-te la asta ca la folosirea unui API meteo în loc să încerci să prezici vremea singur punând stații meteo peste tot.
Este practic „AI ca Serviciu”, iar partea cea mai bună? Este gratuit să începi, așa că poți experimenta fără să-ți faci griji că vei face o factură mare.
```mermaid
graph LR
A[Interfață Chat Frontend] --> B[API-ul Tău Backend]
B --> C[API Modele GitHub]
C --> D[Procesare Model AI]
D --> C
C --> B
B --> A
```
Vom folosi GitHub Models pentru integrarea backend, care oferă acces la capacități AI profesionale printr-o interfață prietenoasă pentru dezvoltatori. [GitHub Models Playground](https://github.com/marketplace/models/azure-openai/gpt-4o-mini/playground) servește ca un mediu de testare unde poți experimenta diferite modele AI și să înțelegi capabilitățile lor înainte de a le implementa în cod.
## 🧠 Ecosistemul dezvoltării aplicațiilor AI
```mermaid
mindmap
root((Dezvoltarea AI))
Understanding AI
Modele Generative
Recunoaștere de Tipare
Generare de Conținut
Înțelegerea Contextului
Sinteza Răspunsurilor
Parametrii AI
Controlul Temperaturii
Limitele Tokenilor
Filtrarea Top-p
Indicații Sistem
Backend Architecture
Integrare API
Modele GitHub
Autentificare
Gestionarea Cererilor
Managementul Erorilor
Infrastructură Python
Framework FastAPI
Operațiuni Async
Securitatea Mediului
Configurare CORS
Frontend Experience
Interfață Chat
Actualizări în Timp Real
Istoric Mesaje
Feedback Utilizator
Stări de Încărcare
Tehnologii Web Moderne
Clase ES6
Async/Await
Manipulare DOM
Gestionare Evenimente
Professional Patterns
Practici Bune de Securitate
Managementul Tokenilor
Validarea Intrărilor
Prevenirea XSS
Limitele Erorilor
Pregătirea pentru Producție
Optimizarea Performanței
Design Responsiv
Accesibilitate
Strategii de Testare
```
**Principiu de bază**: dezvoltarea aplicațiilor AI combină abilități tradiționale de dezvoltare web cu integrarea serviciilor AI, creând aplicații inteligente care par naturale și responsive pentru utilizatori.
**Ce face playground-ul atât de util:**
- **Încearcă** diferite modele AI precum GPT-4o-mini, Claude și altele (toate gratuite!)
- **Testează** ideile și comenzile tale înainte să scrii cod
- **Obține** fragmente de cod gata de utilizare în limbajul tău preferat
- **Ajustează** setările precum nivelul de creativitate și lungimea răspunsului pentru a vedea cum influențează rezultatul
După ce te joci puțin, apasă pe fila „Code” și alege limbajul de programare pentru a obține codul de implementare de care ai nevoie.
## Configurarea Integrației Backend în Python
Acum să implementăm integrarea AI folosind Python. Python este excelent pentru aplicații AI datorită sintaxei simple și bibliotecilor puternice. Vom porni de la codul din playground-ul GitHub Models și apoi îl vom refactoriza într-o funcție reutilizabilă, gata pentru producție.
### Înțelegerea Implementării Bază
Când iei codul Python din playground, vei primi ceva asemănător cu asta. Nu te îngrijora dacă pare mult deodată – hai să-l parcurgem pas cu pas:
```python
"""Run this model in Python
> pip install openai
"""
import os
from openai import OpenAI
# Pentru a vă autentifica cu modelul, va trebui să generați un token de acces personal (PAT) în setările dvs. GitHub.
# Creați tokenul PAT urmând instrucțiunile de aici: 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)
```
**Ce se întâmplă în acest cod:**
- **Importăm** uneltele de care avem nevoie: `os` pentru citirea variabilelor de mediu și `OpenAI` pentru comunicarea cu AI
- **Configurăm** clientul OpenAI să folosească serverele AI GitHub în loc de OpenAI direct
- **Autentificăm** cu un token GitHub special (mai multe despre asta imediat!)
- **Structurăm** conversația cu diferite „roluri” – gândește-o ca setarea scenei pentru o piesă de teatru
- **Trimitem** cererea către AI cu câteva parametri de fine-tuning
- **Extragem** textul efectiv al răspunsului din toate datele primite înapoi
### Înțelegerea Rolurilor Mesajelor: Cadrul conversației AI
Conversațiile cu AI folosesc o structură specifică, cu diferite „roluri” care servesc scopuri distincte:
```python
messages=[
{
"role": "system",
"content": "You are a helpful assistant who explains things simply."
},
{
"role": "user",
"content": "What is machine learning?"
}
]
```
**Gândește-te ca și cum ai regiza o piesă de teatru:**
- **Rolul sistemului**: Ca indicațiile de regie pentru un actor – îi spune AI cum să se comporte, ce personalitate să aibă și cum să răspundă
- **Rolul utilizatorului**: Întrebarea sau mesajul real de la persoana care folosește aplicația ta
- **Rolul asistentului**: Răspunsul AI (nu îl trimiți, dar apare în istoricul conversației)
**Analogie din viața reală**: Imaginează-ți că prezinți un prieten cuiva la o petrecere:
- **Mesaj sistem**: „Aceasta este prietena mea Sarah, este doctor și este foarte bună la explicarea conceptelor medicale pe înțelesul tuturor”
- **Mesaj utilizator**: „Poți să-mi explici cum funcționează vaccinurile?”
- **Răspuns asistent**: Sarah răspunde ca un doctor prietenos, nu ca un avocat sau bucătar
### Înțelegerea parametrilor AI: Ajustarea comportamentului răspunsului
Parametrii numerici în apelurile API AI controlează modul în care modelul generează răspunsurile. Aceste setări îți permit să ajustezi comportamentul AI pentru diferite scenarii:
#### Temperature (0.0 până la 2.0): Butonul Creativității
**Ce face**: Controlează cât de creativ sau previzibil vor fi răspunsurile AI.
**Gândește-te ca la nivelul de improvizație al unui muzician de jazz:**
- **Temperature = 0.1**: Joacă aceeași melodie exactă de fiecare dată (foarte previzibil)
- **Temperature = 0.7**: Adaugă variante subtile, dar menține recunoașterea melodiei (creativitate echilibrată)
- **Temperature = 1.5**: Jazz experimental complet cu răsturnări neașteptate (foarte imprevizibil)
```python
# Răspunsuri foarte previzibile (bune pentru întrebări factuale)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "What is 2+2?"}],
temperature=0.1 # Va spune aproape întotdeauna „4”
)
# Răspunsuri creative (bune pentru brainstorming)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Write a creative story opening"}],
temperature=1.2 # Va genera povești unice, neașteptate
)
```
#### Max Tokens (1 până la 4096+): Controlul Lungimii Răspunsului
**Ce face**: Setează o limită pentru cât de lung poate fi răspunsul AI.
**Gândește-te la tokens ca fiind aproximativ echivalente cu cuvintele** (aprox. 1 token = 0.75 cuvinte în engleză):
- **max_tokens=50**: Scurt și la obiect (ca un mesaj text)
- **max_tokens=500**: Un paragraf sau două frumos structurate
- **max_tokens=2000**: O explicație detaliată cu exemple
```python
# Răspunsuri scurte și concise
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Explain JavaScript"}],
max_tokens=100 # Impune o explicație succintă
)
# Răspunsuri detaliate și cuprinzătoare
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Explain JavaScript"}],
max_tokens=1500 # Permite explicații detaliate cu exemple
)
```
#### Top_p (0.0 până la 1.0): Parametrul de Focalizare
**Ce face**: Controlează cât de concentrat rămâne AI pe răspunsurile cele mai probabile.
**Imaginează-ți AI având un vocabular uriaș, ordonat după cât de probabil este fiecare cuvânt:**
- **top_p=0.1**: Consideră doar top 10% cele mai probabile cuvinte (foarte concentrat)
- **top_p=0.9**: Consideră 90% din posibilele cuvinte (mai creativ)
- **top_p=1.0**: Consideră toate opțiunile (varietate maximă)
**De exemplu**: Dacă întrebi „Cerul este de obicei...”
- **top_p scăzut**: Practic spune „albastru”
- **top_p ridicat**: Poate spune „albastru”, „înnorat”, „imens”, „schimbător”, „frumos” etc.
### Punând Totul Cap la Cap: Combinații de parametri pentru diverse utilizări
```python
# Pentru răspunsuri factuale, consecvente (ca un bot de documentație)
factual_params = {
"temperature": 0.2,
"max_tokens": 300,
"top_p": 0.3
}
# Pentru asistență creativă la scris
creative_params = {
"temperature": 1.1,
"max_tokens": 1000,
"top_p": 0.9
}
# Pentru răspunsuri conversaționale, utile (echilibrate)
conversational_params = {
"temperature": 0.7,
"max_tokens": 500,
"top_p": 0.8
}
```
```mermaid
quadrantChart
title Matricea Optimizării Parametrilor AI
x-axis Creativitate Scăzută --> Creativitate Ridicată
y-axis Răspuns Scurt --> Răspuns Lung
quadrant-1 Conținut Creativ
quadrant-2 Analiză Detaliată
quadrant-3 Fapte Rapide
quadrant-4 AI Conversațional
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]
```
**De ce contează acești parametri**: Aplicațiile diferite au nevoie de tipuri diferite de răspunsuri. Un bot de serviciu clienți trebuie să fie consecvent și factual (temperature scăzut), în timp ce un asistent de scriere creativă trebuie să fie imaginativ și variat (temperature ridicat). Înțelegerea acestor parametri îți oferă control asupra personalității și stilului răspunsului 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))
```
**Înțelegerea acestei funcții îmbunătățite:**
- **Acceptă** doi parametri: promptul utilizatorului și un mesaj opțional al sistemului
- **Furnizează** un mesaj implicit al sistemului pentru comportamentul general al asistentului
- **Folosește** indicii de tip Python pentru o documentare mai bună a codului
- **Include** un docstring detaliat care explică scopul și parametrii funcției
- **Returnează** doar conținutul răspunsului, făcându-l ușor de folosit în API-ul nostru web
- **Menține** aceiași parametri model pentru un comportament AI consecvent
### Magia Prompturilor Sistem: Programarea Personalității AI
Dacă parametrii controlează cum gândește AI, prompturile sistem controlează cine crede AI că este. Asta este, sincer, una dintre cele mai tari părți ale lucrului cu AI – practic îi dai AI o personalitate completă, un nivel de expertiză și un stil de comunicare.
**Gândește-te la prompturile sistem ca la distribuirea actorilor pentru roluri diferite**: În loc să ai un asistent generic, poți crea experți specializați pentru situații diferite. Ai nevoie de un profesor răbdător? Un partener creativ de brainstorming? Un consilier de afaceri pragmatic? Schimbă promptul sistemului!
#### De ce sunt prompturile sistem atât de puternice
Partea fascinantă este că modelele AI au fost antrenate pe nenumărate conversații în care oamenii adoptă roluri și niveluri de expertiză diferite. Când dai AI un rol specific, este ca și cum ai apăsa un buton care activează toate aceste tipare învățate.
**Este ca metoda actoricească pentru AI**: Spune unui actor „ești un profesor înțelept și bătrân” și vei vedea cum își adaptează automat postura, vocabularul și manierele. AI face ceva foarte similar cu tiparele limbajului.
#### Crearea prompturilor eficiente pentru sistem: Arta și Știința
**Anatomia unui prompt sistem grozav:**
1. **Rol/Identitate**: Cine este AI?
2. **Expertiză**: Ce știe?
3. **Stil de comunicare**: Cum vorbește?
4. **Instrucțiuni specifice**: Pe ce să se concentreze?
```python
# ❌ Instructiv vag al sistemului
"You are helpful."
# ✅ Instructiv detaliat și eficient al sistemului
"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."
```
#### Exemple de prompturi sistem cu context
Să vedem cum diferitele prompturi sistem creează personalități AI complet diferite:
```python
# Exemplul 1: Profesorul Răbdător
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.
"""
# Exemplul 2: Colaboratorul Creativ
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.
"""
# Exemplul 3: Consilierul Strategic de Afaceri
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.
"""
```
#### Văzând prompturile sistem în acțiune
Hai să testăm aceeași întrebare cu prompturi sistem diferite pentru a vedea diferențele dramatice:
**Întrebare**: „Cum gestionez autentificarea utilizatorului în aplicația mea web?”
```python
# Cu promptul profesorului:
teacher_response = call_llm(
"How do I handle user authentication in my web app?",
teacher_prompt
)
# Răspuns tipic: "O întrebare grozavă! Haideți să descompunem autentificarea în pași simpli.
# Gândește-te la ea ca la un portar de club care verifică actele de identitate..."
# Cu promptul de afaceri:
business_response = call_llm(
"How do I handle user authentication in my web app?",
business_prompt
)
# Răspuns tipic: "Din perspectivă strategică, autentificarea este crucială pentru încrederea utilizatorilor
# și conformitatea cu reglementările. Permiteți-mi să conturez un cadru luând în considerare securitatea,
# experiența utilizatorului și scalabilitatea..."
```
#### Tehnici avansate pentru prompturi sistem
**1. Setarea contextului**: Oferă AI informații de fundal
```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. Formatul Outputului**: Spune AI-ului cum să structureze răspunsurile
```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. Setarea constrângerilor**: Definește ce NU trebuie să facă AI-ul
```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.
"""
```
#### De ce contează asta pentru asistentul tău de chat
Înțelegerea prompturilor de sistem îți oferă o putere incredibilă de a crea asistenți AI specializați:
- **Bot de servicii clienți**: Util, răbdător, conștient de politici
- **Tutor pentru învățare**: Încurajator, pas cu pas, verifică înțelegerea
- **Partener creativ**: Imaginativ, construiește idei, întreabă „ce-ar fi dacă?”
- **Expert tehnic**: Precise, detaliat, atent la securitate
**Ideea esențială**: Nu doar apelezi la o API AI – creezi o personalitate AI personalizată care servește cazului tău specific. Asta face ca aplicațiile AI moderne să pară adaptate și utile, nu generice.
### 🎯 Verificare pedagogică: Programarea personalității AI
**Pauză și reflecție**: Tocmai ai învățat să programezi personalități AI prin prompturi de sistem. Aceasta este o abilitate fundamentală în dezvoltarea aplicațiilor AI moderne.
**Autoevaluare rapidă**:
- Poți explica cum se deosebesc prompturile de sistem de mesajele obișnuite de utilizator?
- Care este diferența dintre parametrii temperature și top_p?
- Cum ai crea un prompt de sistem pentru un caz specific (de exemplu un tutor de programare)?
**Legătura cu lumea reală**: Tehnicile de prompt de sistem pe care le-ai învățat sunt folosite în toate aplicațiile principale AI - de la asistența de codare GitHub Copilot la interfața conversațională ChatGPT. Stăpânești aceleași modele folosite de echipele de produs AI din marile companii tech.
**Întrebare provocatoare**: Cum ai putea proiecta personalități AI diferite pentru tipuri diferite de utilizatori (începători vs experți)? Ia în considerare cum același model AI de bază ar putea deservi audiențe diferite prin ingineria prompturilor.
## Construirea Web API cu FastAPI: Centrul tău de comunicare AI de înaltă performanță
Acum să construim backend-ul care conectează frontend-ul tău la serviciile AI. Vom folosi FastAPI, un framework modern Python excelent pentru construcția API-urilor pentru aplicații AI.
FastAPI oferă mai multe avantaje pentru acest tip de proiect: suport async încorporat pentru gestionarea cererilor concurente, generare automată de documentație API și performanță excelentă. Serverul tău FastAPI acționează ca un intermediar ce primește cereri din frontend, comunică cu serviciile AI și returnează răspunsuri formatate.
### De ce FastAPI pentru aplicațiile AI?
Poate te întrebi: „Nu pot apela AI-ul direct din JavaScript-ul frontend-ului?” sau „De ce FastAPI în loc de Flask sau Django?” Întrebări bune!
**Iată de ce FastAPI este perfect pentru ce construim:**
- **Async implicit**: Poate gestiona mai multe cereri AI simultan fără blocaje
- **Documentație automată**: Vizitează `/docs` pentru o pagină frumoasă, interactivă, gratuită cu documentația API
- **Validare încorporată**: Depistează erori înainte să cauzeze probleme
- **Rapiditate fulgerătoare**: Unul dintre cele mai rapide framework-uri Python
- **Python modern**: Folosește toate funcționalitățile Python moderne și avansate
**Și de ce avem nevoie de un backend:**
**Securitate**: Cheia ta API AI este ca o parolă – dacă o pui în JavaScript-ul frontend, oricine vede codul sursă al site-ului tău o poate fura și folosi creditele tale AI. Backend-ul ține aceste date sensibile în siguranță.
**Limitarea ratelor și control**: Backend-ul îți permite să controlezi frecvența cererilor utilizatorilor, să implementezi autentificare și să adaugi logare pentru urmărirea utilizării.
**Procesarea datelor**: Poți dori să salvezi conversații, să filtrezi conținut inadecvat sau să combini mai multe servicii AI. Logica asta trăiește în backend.
**Arhitectura seamănă cu un model client-server:**
- **Frontend**: Strat de interfață utilizator pentru interacțiune
- **Backend API**: Strat de procesare și rutare cereri
- **Serviciu AI**: Calcul extern și generare răspuns
- **Variabile de mediu**: Configurare securizată și stocare credențiale
### Înțelegerea fluxului cerere-răspuns
Să urmărim ce se întâmplă când un utilizator trimite un mesaj:
```mermaid
sequenceDiagram
participant User as 👤 Utilizator
participant Frontend as 🌐 Frontend
participant API as 🔧 FastAPI Server
participant AI as 🤖 Serviciu AI
User->>Frontend: Tastează "Salut AI!"
Frontend->>API: POST /hello {"message": "Salut AI!"}
Note over API: Validează cererea Adaugă promptul sistemului
API->>AI: Trimite cererea formatată
AI->>API: Returnează răspunsul AI
Note over API: Procesează răspunsul Înregistrează conversația
API->>Frontend: {"response": "Salut! Cu ce te pot ajuta?"}
Frontend->>User: Afișează mesajul AI
```
**Înțelegerea fiecărui pas:**
1. **Interacțiunea utilizatorului**: Persoana tastează în interfața de chat
2. **Procesarea frontend**: JavaScript capturează inputul și îl formatează ca JSON
3. **Validarea API**: FastAPI validează cererea automat folosind modele Pydantic
4. **Integrarea AI**: Backend adaugă context (prompt de sistem) și apelează serviciul AI
5. **Gestionarea răspunsului**: API primește răspunsul AI și îl poate modifica dacă e nevoie
6. **Afișarea frontend**: JavaScript afișează răspunsul în interfața de chat
### Înțelegerea arhitecturii API
```mermaid
sequenceDiagram
participant Frontend
participant FastAPI
participant AI Function
participant GitHub Models
Frontend->>FastAPI: POST /hello {"message": "Salut AI!"}
FastAPI->>AI Function: call_llm(message, system_prompt)
AI Function->>GitHub Models: API request
GitHub Models->>AI Function: AI response
AI Function->>FastAPI: response text
FastAPI->>Frontend: {"response": "Salut! Cu ce te pot ajuta?"}
```
```mermaid
flowchart TD
A[Introducere Utilizator] --> B[Validare Frontend]
B --> C[Cerere POST HTTP]
C --> D[Router FastAPI]
D --> E[Validare Pydantic]
E --> F[Apeal Funcție AI]
F --> G[API Modele GitHub]
G --> H[Procesare Răspuns]
H --> I[Răspuns JSON]
I --> J[Actualizare Frontend]
subgraph "Strat de Securitate"
K[Middleware CORS]
L[Variabile de Mediu]
M[Gestionare Erori]
end
D --> K
F --> L
H --> M
```
### Crearea aplicației FastAPI
Să construim API-ul pas cu pas. Creează un fișier numit `api.py` cu următorul cod 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
# Configurează logarea
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
# Creează aplicația FastAPI
app = FastAPI(
title="AI Chat API",
description="A high-performance API for AI-powered chat applications",
version="1.0.0"
)
# Configurează CORS
app.add_middleware(
CORSMiddleware,
allow_origins=["*"], # Configurează corespunzător pentru producție
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
# Modele Pydantic pentru validarea cererii/răspunsului
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:
# Extrage și validează mesajul
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]}...")
# Apelează serviciul AI (notă: call_llm ar trebui să fie asincron pentru performanță mai bună)
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)
```
**Înțelegerea implementării FastAPI:**
- **Importă** FastAPI pentru funcționalitate modernă web și Pydantic pentru validarea datelor
- **Creează** documentație automată API (disponibilă la `/docs` la rulare server)
- **Activează** middleware CORS pentru a permite cereri frontend de la origini diferite
- **Definește** modele Pydantic pentru validare automată cereri/răspunsuri și documentație
- **Folosește** endpoint-uri async pentru performanță mai bună cu cereri concurente
- **Implementează** coduri HTTP corespunzătoare și gestionare erori cu HTTPException
- **Include** logare structurată pentru monitorizare și debugging
- **Oferă** endpoint pentru health check (verificare stare serviciu)
**Avantaje cheie FastAPI față de framework-urile tradiționale:**
- **Validare automată**: Modelele Pydantic asigură integritatea datelor înainte de procesare
- **Docuri interactive**: Vizitează `/docs` pentru documentație auto-generată și testabilă
- **Siguranță la tipuri**: Hint-urile Python previn erorile la runtime și îmbunătățesc calitatea codului
- **Suport async**: Gestionează cereri AI multiple simultan fără blocare
- **Performanță**: Procesare cereri semnificativ mai rapidă pentru aplicații realtime
### Înțelegerea CORS: Garda de securitate a webului
CORS (Cross-Origin Resource Sharing) este ca un paznic la o clădire care verifică dacă vizitatorii au voie să intre. Să înțelegem de ce contează și cum afectează aplicația ta.
#### Ce este CORS și de ce există?
**Problema**: Imaginează-ți că orice site web ar putea face cereri către site-ul băncii tale în numele tău, fără permisiune. Ar fi un coșmar de securitate! Browserele împiedică asta prin „Politica same-origin”.
**Politica same-origin**: Browserele permit paginilor web să facă cereri doar către aceeași domeniu, port și protocol de unde au fost încărcate.
**Analogie din lumea reală**: E ca securitatea unui bloc de apartamente – doar rezidenții (same origin) pot intra în clădire implicit. Dacă vrei să lași un prieten (origine diferită) să vină în vizită, trebuie să spui clar securității că e în regulă.
#### CORS în mediul tău de dezvoltare
În timpul dezvoltării, frontend-ul și backend-ul rulează pe porturi diferite:
- Frontend: `http://localhost:3000` (sau file:// dacă deschizi direct HTML)
- Backend: `http://localhost:5000`
Acestea sunt considerate „origini diferite” deși sunt pe același calculator!
```python
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI(__name__)
CORS(app) # Acest lucru indică browserelor: „Este în regulă ca alte origini să facă cereri către această API”
```
**Ce face configurarea CORS practic:**
- **Adaugă** headere HTTP speciale la răspunsurile API care spun browserelor „această cerere cross-origin este permisă”
- **Gestionează** cereri „preflight” (pentru că browserele uneori verifică permisiunile înainte de cererea reală)
- **Previne** eroarea enervantă „blocked by CORS policy” din consola browserului tău
#### Securitatea CORS: Dezvoltare vs Producție
```python
# 🚨 Dezvoltare: Permite TOATE originile (convenabil, dar nesigur)
CORS(app)
# ✅ Producție: Permite doar domeniul specific al frontend-ului tău
CORS(app, origins=["https://yourdomain.com", "https://www.yourdomain.com"])
# 🔒 Avansat: Origini diferite pentru medii diferite
if app.debug: # Mod dezvoltare
CORS(app, origins=["http://localhost:3000", "http://127.0.0.1:3000"])
else: # Mod producție
CORS(app, origins=["https://yourdomain.com"])
```
**De ce contează asta**: În dezvoltare, `CORS(app)` e ca și cum ai lăsa ușa din față descuiată – comod, dar nesigur. În producție, vrei să specifici exact ce website-uri pot să-ți acceseze API-ul.
#### Scenarii și soluții comune CORS
| Scenariu | Problemă | Soluție |
|--------------------|------------------------------|----------------------------------|
| **Dezvoltare locală** | Frontend nu poate ajunge la backend | Adaugă CORSMiddleware în FastAPI |
| **GitHub Pages + Heroku** | Frontendul deployat nu poate accesa API-ul | Adaugă URL-ul GitHub Pages la origini CORS |
| **Domeniu personalizat** | Erori CORS în producție | Actualizează origini CORS să corespundă domeniului tău |
| **Aplicație mobilă** | App nu poate accesa API-ul web | Adaugă domeniul aplicației sau folosește `*` cu prudență |
**Sfat profesionist**: Poți verifica headerele CORS în Developer Tools din browser, fila Network. Caută headere ca `Access-Control-Allow-Origin` în răspuns.
### Gestionarea erorilor și validarea
Observă cum API-ul nostru include gestionarea corectă a erorilor:
```python
# Verificați dacă am primit un mesaj
if not message:
return jsonify({"error": "Message field is required"}), 400
```
**Principii cheie de validare:**
- **Verifică** câmpurile obligatorii înainte de procesare
- **Returnează** mesaje de eroare relevante în format JSON
- **Folosește** coduri HTTP potrivite (400 pentru cereri greșite)
- **Oferă** feedback clar pentru a ajuta dezvoltatorii frontend să depaneze
## Configurarea și rularea backend-ului tău
Acum că avem integrarea AI și serverul FastAPI gata, să punem totul în funcțiune. Procesul implică instalarea dependențelor Python, configurarea variabilelor de mediu și pornirea serverului de dezvoltare.
### Configurarea mediului Python
Să-ți configurăm mediul de dezvoltare Python. Mediile virtuale sunt ca abordarea compartimentată a Proiectului Manhattan – fiecare proiect primește un spațiu izolat cu unelte și dependențe specifice, prevenind conflictele între proiecte.
```bash
# Navighează la directorul tău backend
cd backend
# Creează un mediu virtual (ca și cum ai crea o cameră curată pentru proiectul tău)
python -m venv venv
# Activează-l (Linux/Mac)
source ./venv/bin/activate
# Pe Windows, folosește:
# venv\Scripts\activate
# Instalează lucrurile bune
pip install openai fastapi uvicorn python-dotenv
```
**Ce am făcut tocmai:**
- **Am creat** propria noastră bulă Python unde putem instala pachete fără să afectăm altceva
- **Am activat** mediul ca terminalul să știe să-l folosească
- **Am instalat** esențialele: OpenAI pentru magie AI, FastAPI pentru API-ul web, Uvicorn să-l ruleze și python-dotenv pentru management securizat al secretelor
**Dependențe cheie explicate:**
- **FastAPI**: Framework web modern, rapid, cu documentație API automată
- **Uvicorn**: Server ASGI fulger pentru aplicații FastAPI
- **OpenAI**: Biblioteca oficială pentru modelele GitHub și integrarea OpenAI API
- **python-dotenv**: Încărcare sigură variabile de mediu din fișiere .env
### Configurarea mediului: Păstrează secretele în siguranță
Înainte să pornim API-ul, trebuie să discutăm unul dintre cele mai importante lecții din dezvoltarea web: cum să păstrezi secretele cu adevărat secrete. Variabilele de mediu sunt ca un seif securizat la care doar aplicația ta are acces.
#### Ce sunt variabilele de mediu?
**Gândește-te la variabilele de mediu ca la un seif de valori de siguranță** – pui acolo lucrurile valoroase și doar tu (și aplicația ta) ai cheia să le iei afară. În loc să pui informații sensibile direct în cod (unde oricine le poate vedea), le stochezi în mediu.
**Iată diferența:**
- **Modul greșit**: Scrii parola pe un bilet și o lipești pe monitor
- **Modul corect**: Ții parola într-un manager de parole securizat unde doar tu ai acces
#### De ce contează variabilele de mediu
```python
# 🚨 NU FACEȚI ASTA - Cheia API vizibilă pentru toată lumea
client = OpenAI(
api_key="ghp_1234567890abcdef...", # Oricine poate fura asta!
base_url="https://models.github.ai/inference"
)
# ✅ FACEȚI ASTA - Cheia API stocată în siguranță
client = OpenAI(
api_key=os.environ["GITHUB_TOKEN"], # Doar aplicația ta poate accesa asta
base_url="https://models.github.ai/inference"
)
```
**Ce se întâmplă când salvezi secrete în cod:**
1. **Expunere la controlul versiunilor**: Oricine are acces la repo-ul Git vede cheia ta API
2. **Repo-uri publice**: Dacă faci push pe GitHub, cheia ta devine vizibilă internetului întreg
3. **Partajare în echipă**: Dezvoltatorii care lucrează la proiect obțin cheia ta personală API
4. **Breach-uri de securitate**: Dacă cineva îți fură cheia API, poate folosi creditele tale AI
#### Configurarea fișierului de mediu
Creează un fișier `.env` în directorul backend. Acest fișier stochează local secretele tale:
```bash
# fișier .env - Acesta NU trebuie niciodată să fie comis în Git
GITHUB_TOKEN=your_github_personal_access_token_here
FASTAPI_DEBUG=True
ENVIRONMENT=development
```
**Înțelegerea fișierului .env:**
- **Un secret pe linie** în format `CHEIE=valoare`
- **Fără spații** în jurul semnului egal
- **Fără ghilimele** în jurul valorilor (de obicei)
- **Comentarii** încep cu `#`
#### Crearea tokenului tău personal GitHub
Tokenul tău GitHub este ca o parolă specială care dă aplicației tale permisiunea să folosească serviciile AI GitHub:
**Crearea tokenului pas cu pas:**
1. **Mergi în GitHub Settings** → Developer settings → Personal access tokens → Tokens (classic)
2. **Apasă „Generate new token (classic)”**
3. **Setează expirarea** (30 zile pentru testare, mai lung pentru producție)
4. **Selectează permisiunile**: Bifează „repo” și alte permisiuni necesare
5. **Generează tokenul** și copiază-l imediat (nu îl vei mai vedea!)
6. **Lipește-l în fișierul tău .env**
```bash
# Exemplu de cum arată token-ul tău (acesta este fals!)
GITHUB_TOKEN=ghp_1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R
```
#### Încărcarea variabilelor de mediu în Python
```python
import os
from dotenv import load_dotenv
# Încarcă variabilele de mediu din fișierul .env
load_dotenv()
# Acum le poți accesa în siguranță
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"
)
```
**Ce face acest cod:**
- **Încarcă** fișierul .env și face variabilele disponibile în Python
- **Verifică** dacă tokenul necesar există (gestionare bună a erorilor!)
- **Ridică** o eroare clară dacă lipsește tokenul
- **Folosește** tokenul în siguranță fără să-l expună în cod
#### Securitatea Git: Fișierul .gitignore
Fișierul tău `.gitignore` îi spune lui Git ce fișiere să nu urmărească sau să nu urce niciodată:
```bash
# .gitignore - Adaugă aceste linii
.env
*.env
.env.local
.env.production
__pycache__/
venv/
.vscode/
```
**De ce este crucial asta**: Odată ce adaugi `.env` în `.gitignore`, Git va ignora fișierul de mediu, prevenind urcarea accidentală a secretelor tale pe GitHub.
#### Medii diferite, secrete diferite
Aplicațiile profesionale folosesc chei API diferite pentru medii diferite:
```bash
# .env.development
GITHUB_TOKEN=your_development_token
DEBUG=True
# .env.production
GITHUB_TOKEN=your_production_token
DEBUG=False
```
**De ce contează asta**: Nu vrei ca experimentele tale de dezvoltare să afecteze cota de utilizare AI din producție și vrei niveluri de securitate diferite pentru fiecare mediu.
### Pornirea serverului tău de dezvoltare: Dând viață FastAPI-ului tău
Acum vine momentul palpitant – pornirea serverului de dezvoltare FastAPI și vizualizarea integrării AI în acțiune! FastAPI folosește Uvicorn, un server ASGI extrem de rapid, creat special pentru aplicații Python asincrone.
#### Înțelegerea procesului de pornire al serverului FastAPI
```bash
# Metoda 1: Execuție directă în Python (include reîncărcare automată)
python api.py
# Metoda 2: Utilizarea directă a Uvicorn (mai mult control)
uvicorn api:app --host 0.0.0.0 --port 5000 --reload
```
Când rulezi această comandă, iată ce se întâmplă în spate:
**1. Python încarcă aplicația ta FastAPI**:
- Importă toate bibliotecile necesare (FastAPI, Pydantic, OpenAI etc.)
- Încarcă variabilele de mediu din fișierul tău `.env`
- Creează instanța aplicației FastAPI cu documentație automată
**2. Uvicorn configurează serverul ASGI**:
- Se leagă de portul 5000 cu capabilități asincrone de gestionare a cererilor
- Configurează rutarea cererilor cu validare automată
- Activează reîncărcarea automată pentru dezvoltare (restart la modificarea fișierelor)
- Generează documentația API interactivă
**3. Serverul începe să asculte**:
- Terminalul tău afișează: `INFO: Uvicorn running on http://0.0.0.0:5000`
- Serverul poate gestiona multiple cereri AI concurente
- API-ul tău este gata cu documentație automată la `http://localhost:5000/docs`
#### Ce ar trebui să vezi când totul funcționează
```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.
```
**Înțelegerea output-ului FastAPI:**
- **Will watch for changes**: Reîncărcare automată activată pentru dezvoltare
- **Uvicorn running**: Server ASGI cu performanță înaltă este activ
- **Started reloader process**: Monitor de fișiere pentru restart automat
- **Application startup complete**: Aplicația FastAPI a fost inițializată cu succes
- **Interactive docs available**: Vizitează `/docs` pentru documentație API automată
#### Testarea FastAPI-ului tău: Mai multe metode puternice
FastAPI oferă mai multe metode convenabile pentru testarea API-ului, inclusiv documentație interactivă automată:
**Metoda 1: Documentația interactivă API (Recomandată)**
1. Deschide browserul și accesează `http://localhost:5000/docs`
2. Vei vedea Swagger UI cu toate endpoint-urile documentate
3. Apasă pe `/hello` → "Try it out" → Introdu un mesaj de test → "Execute"
4. Vezi răspunsul direct în browser cu format corect
**Metoda 2: Test simplu în browser**
1. Accesează `http://localhost:5000` pentru endpoint-ul rădăcină
2. Accesează `http://localhost:5000/health` pentru verificarea stării serverului
3. Aceasta confirmă că serverul FastAPI rulează corect
**Metoda 2: Test din linia de comandă (Avansat)**
```bash
# Testați cu curl (dacă este disponibil)
curl -X POST http://localhost:5000/hello \
-H "Content-Type: application/json" \
-d '{"message": "Hello AI!"}'
# Răspuns așteptat:
# {"response": "Salut! Sunt asistentul tău AI. Cu ce te pot ajuta astăzi?"}
```
**Metoda 3: Script de test Python**
```python
# test_api.py - Creează acest fișier pentru a testa API-ul tău
import requests
import json
# Testează punctul final al API-ului
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)
```
#### Remedierea Problemelor Comune la Pornire
| Mesaj de eroare | Ce înseamnă | Cum să remediezi |
|-----------------|-------------|------------------|
| `ModuleNotFoundError: No module named 'fastapi'` | FastAPI nu este instalat | Rulează `pip install fastapi uvicorn` în mediul tău virtual |
| `ModuleNotFoundError: No module named 'uvicorn'` | Serverul ASGI nu este instalat | Rulează `pip install uvicorn` în mediul tău virtual |
| `KeyError: 'GITHUB_TOKEN'` | Variabila de mediu nu a fost găsită | Verifică fișierul `.env` și apelul `load_dotenv()` |
| `Address already in use` | Portul 5000 este ocupat | Închide alte procese care folosesc portul 5000 sau schimbă portul |
| `ValidationError` | Datele trimise nu corespund modelului Pydantic | Verifică dacă formatul cererii corespunde schemei așteptate |
| `HTTPException 422` | Entitate neprocesabilă | Validarea cererii a eșuat, verifică `/docs` pentru format corect |
| `OpenAI API error` | Autentificarea serviciului AI a eșuat | Verifică dacă tokenul GitHub este corect și are permisiunile necesare |
#### Cele mai bune practici în dezvoltare
**Reîncărcare automată**: FastAPI cu Uvicorn oferă reîncărcare automată când salvezi modificări în fișierele Python. Asta înseamnă că poți modifica codul și testa imediat fără să restartezi manual.
```python
# Activează explicit reîncărcarea rapidă
if __name__ == "__main__":
app.run(host="0.0.0.0", port=5000, debug=True) # debug=True activează reîncărcarea rapidă
```
**Logging pentru dezvoltare**: Adaugă logare pentru a înțelege ce se întâmplă:
```python
import logging
# Configurați jurnalizarea
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
```
**De ce ajută logging-ul**: În timpul dezvoltării, poți vedea exact ce cereri vin, ce răspuns oferă AI și unde apar erori. Acest lucru face depanarea mult mai rapidă.
### Configurarea pentru GitHub Codespaces: Dezvoltare în cloud simplificată
GitHub Codespaces este ca un calculator puternic de dezvoltare în cloud, accesibil din orice browser. Dacă lucrezi în Codespaces, sunt câțiva pași suplimentari pentru a face backend-ul accesibil frontend-ului tău.
#### Înțelegerea rețelei în Codespaces
Într-un mediu local de dezvoltare, totul rulează pe același calculator:
- Backend: `http://localhost:5000`
- Frontend: `http://localhost:3000` (sau file://)
În Codespaces, mediul tău de dezvoltare rulează pe serverele GitHub, astfel "localhost" are un alt sens. GitHub creează automat URL-uri publice pentru serviciile tale, dar trebuie să le configurezi corect.
#### Configurarea pas cu pas în Codespaces
**1. Pornește serverul backend**:
```bash
cd backend
python api.py
```
Vei vedea mesajul clasic de pornire FastAPI/Uvicorn, dar observă că rulează în mediul Codespace.
**2. Configurează vizibilitatea portului**:
- Caută fila „Ports” în panoul de jos din VS Code
- Găsește portul 5000 în listă
- Click dreapta pe portul 5000
- Selectează „Port Visibility” → „Public”
**De ce să-l faci public?** Implicit, porturile Codespace sunt private (accesibile doar ție). Facând portul public, frontend-ul tău (care rulează în browser) poate comunica cu backend-ul.
**3. Obține URL-ul public**:
După ce portul este public, vei vedea un URL de forma:
```
https://your-codespace-name-5000.app.github.dev
```
**4. Actualizează configurația frontend-ului**:
```javascript
// În fișierul app.js din frontend-ul tău, actualizează BASE_URL-ul:
this.BASE_URL = "https://your-codespace-name-5000.app.github.dev";
```
#### Înțelegerea URL-urilor Codespace
URL-urile Codespace urmează un tipar predictibil:
```
https://[codespace-name]-[port].app.github.dev
```
**Detaliind:**
- `codespace-name`: Identificator unic pentru Codespace-ul tău (de obicei include numele tău de utilizator)
- `port`: Numărul portului pe care rulează serviciul tău (5000 pentru aplicația FastAPI)
- `app.github.dev`: Domeniul GitHub pentru aplicațiile Codespace
#### Testarea configurării Codespace-ului
**1. Testează backend-ul direct**:
Deschide URL-ul public într-un tab nou de browser. Ar trebui să vezi:
```
Welcome to the AI Chat API. Send POST requests to /hello with JSON payload containing 'message' field.
```
**2. Testează cu uneltele pentru dezvoltatori din browser**:
```javascript
// Deschide consola browserului și testează API-ul tău
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 versus dezvoltare locală
| Aspect | Dezvoltare locală | GitHub Codespaces |
|--------|-------------------|-------------------|
| **Timp de configurare** | Mai lung (instalare Python, dependențe) | Instant (mediu preconfigurat) |
| **Acces URL** | `http://localhost:5000` | `https://xyz-5000.app.github.dev` |
| **Configurare port** | Automată | Manuală (setează porturile publice) |
| **Persistența fișierelor** | Mașina locală | Repozitoriu GitHub |
| **Colaborare** | Dificil de distribuit mediul | Simplu de distribuit link Codespace |
| **Dependență de internet** | Doar pentru apeluri API AI | Necesită internet pentru tot |
#### Sfaturi pentru dezvoltare în Codespace
**Variabile de mediu în Codespaces**:
Fișierul tău `.env` funcționează la fel în Codespaces, dar poți seta și variabile de mediu direct în Codespace:
```bash
# Setează variabila de mediu pentru sesiunea curentă
export GITHUB_TOKEN="your_token_here"
# Sau adaugă în .bashrc pentru persistență
echo 'export GITHUB_TOKEN="your_token_here"' >> ~/.bashrc
```
**Gestionarea porturilor**:
- Codespaces detectează automat când aplicația începe să asculte pe un port
- Poți redirecționa simultan mai multe porturi (util dacă adaugi baze de date mai târziu)
- Porturile rămân accesibile cât timp Codespace-ul tău rulează
**Flux de lucru în dezvoltare**:
1. Fă modificări în cod în VS Code
2. FastAPI reîncarcă automat (mulțumită modului de reload al Uvicorn)
3. Testează modificările imediat prin URL-ul public
4. Commit și push când ești gata
> 💡 **Sfat Pro**: Adaugă bookmark URL-ului backend-ului tău Codespace în timpul dezvoltării. Numele Codespace-urilor sunt stabile, așa că URL-ul nu se schimbă cât timp folosești același Codespace.
## Crearea interfeței frontend de chat: Locul unde oamenii întâlnesc AI-ul
Acum vom construi interfața utilizatorului – partea care determină cum oamenii interacționează cu asistentul tău AI. Ca designul interfeței originale iPhone, ne concentrăm să facem tehnologia complexă să pară intuitivă și naturală la utilizare.
### Înțelegerea arhitecturii moderne de frontend
Interfața de chat va fi ceea ce numim o "Aplicație Single Page" sau SPA. În loc de abordarea veche unde fiecare click încarcă o pagină nouă, aplicația noastră se actualizează lin și instantaneu:
**Site-uri vechi**: Ca și cum ai citi o carte fizică – răsfoiești pagini complet noi
**Aplicația noastră de chat**: Ca și cum ai folosi telefonul – totul curge și se actualizează fără întreruperi
```mermaid
graph TD
A[Utilizatorul Tastează Mesajul] --> B[JavaScript Capturează Inputul]
B --> C[Validează & Formatează Datele]
C --> D[Trimite la API-ul Backend]
D --> E[Afișează Starea de Încărcare]
E --> F[Primește Răspunsul AI]
F --> G[Actualizează Interfața Chat-ului]
G --> H[Gata pentru Mesajul Următor]
```
```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 : manipulează
ChatApp --> FastAPI : trimite cereri
```
### Cele trei piloni ai dezvoltării frontend
Fiecare aplicație frontend – de la site-uri simple la aplicații complexe ca Discord sau Slack – se bazează pe trei tehnologii de bază. Gândește-le ca pe fundația a tot ce vezi și cu ce interacționezi pe web:
**HTML (Structură)**: Aceasta este fundația ta
- Decide ce elemente există (buton, zone de text, containere)
- Dă sens conținutului (acesta este un titlu, acesta este un formular etc.)
- Creează structura de bază pe care se construiește tot restul
**CSS (Prezentare)**: Acesta este designerul interior
- Face totul să arate frumos (culori, fonturi, layout-uri)
- Gestionează diferite mărimi de ecran (telefon vs laptop vs tabletă)
- Creează animații fluide și feedback vizual
**JavaScript (Comportament)**: Acesta este creierul
- Răspunde la ce face utilizatorul (clickuri, tastări, scroll)
- Comunică cu backend-ul și actualizează pagina
- Face totul interactiv și dinamic
**Gândește-te la asta ca la un design arhitectural:**
- **HTML**: Planul structural (definirea spațiilor și relațiilor)
- **CSS**: Designul estetic și de mediu (stil vizual și experiența utilizatorului)
- **JavaScript**: Sistemele mecanice (funcționalitate și interactivitate)
### De ce contează arhitectura JavaScript modernă
Aplicația noastră de chat va folosi pattern-uri moderne JavaScript pe care le vei întâlni în aplicații profesionale. Înțelegerea acestor concepte te va ajuta să crești ca dezvoltator:
**Arhitectură bazată pe clase**: Vom organiza codul în clase, ca și cum am crea tipare pentru obiecte
**Async/Await**: Mod modern de a gestiona operații care durează (cum sunt apelurile API)
**Programare bazată pe evenimente**: Aplicația răspunde la acțiunile utilizatorului (clickuri, apăsări de taste) în loc să ruleze continuu în buclă
**Manipularea DOM**: Actualizarea dinamică a conținutului paginii în funcție de interacțiunile utilizatorului și răspunsurile API-ului
### Configurarea structurii proiectului
Creează un director frontend cu următoarea structură organizată:
```text
frontend/
├── index.html # Main HTML structure
├── app.js # JavaScript functionality
└── styles.css # Visual styling
```
**Înțelegerea arhitecturii:**
- **Separă** preocupările între structură (HTML), comportament (JavaScript) și prezentare (CSS)
- **Menține** o structură de fișiere simplă, ușor de navigat și modificat
- **Urmărește** cele mai bune practici în dezvoltarea web pentru organizare și mentenanță
### Construirea fundației HTML: Structură semantică pentru accesibilitate
Să începem cu structura HTML. Dezvoltarea web modernă pune accent pe „HTML semantic” – folosirea elementelor HTML care descriu clar scopul lor, nu doar aspectul. Aceasta face aplicația ta accesibilă cititoarelor de ecran, motoarelor de căutare și altor unelte.
**De ce contează HTML semantic**: Imaginează-ți că descrii aplicația ta de chat cuiva la telefon. Ai spune „este un header cu titlul, o zonă principală unde apar conversațiile și un formular jos pentru tastarea mesajelor.” HTML semantic folosește elemente care corespund acestei descrieri naturale.
Creează `index.html` cu acest markup bine structurat:
```html
AI Chat Assistant
AI Chat Assistant
Ask me anything!
```
**Înțelegerea fiecărui element HTML și scopul său:**
#### Structura documentului
- **``**: Indică browser-ului că este HTML5 modern
- **``**: Specifică limba paginii pentru cititoarele de ecran și traducătoare
- **``**: Asigură codificarea corectă a caracterelor pentru texte internaționale
- **``**: Face pagina responsive pe mobil prin controlul zoom-ului și scalei
#### Elemente semantice
- **``**: Identifică clar secțiunea de sus cu titlul și descrierea
- **``**: Designarea zonei principale de conținut (unde se desfășoară conversațiile)
- **`