localizeflow[bot]
9f4fafece3
|
1 month ago | |
|---|---|---|
| .. | ||
| solution | 4 months ago | |
| README.md | 1 month ago | |
README.md
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
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 ș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:
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
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
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<br/>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.
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 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
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:
"""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:
ospentru citirea variabilelor de mediu șiOpenAIpentru 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:
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)
# 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
# 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
# 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
}
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:
- Rol/Identitate: Cine este AI?
- Expertiză: Ce știe?
- Stil de comunicare: Cum vorbește?
- Instrucțiuni specifice: Pe ce să se concentreze?
# ❌ 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:
# 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?”
# 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
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
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
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ă
/docspentru 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:
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<br/>Adaugă promptul sistemului
API->>AI: Trimite cererea formatată
AI->>API: Returnează răspunsul AI
Note over API: Procesează răspunsul<br/>Înregistrează conversația
API->>Frontend: {"response": "Salut! Cu ce te pot ajuta?"}
Frontend->>User: Afișează mesajul AI
Înțelegerea fiecărui pas:
- Interacțiunea utilizatorului: Persoana tastează în interfața de chat
- Procesarea frontend: JavaScript capturează inputul și îl formatează ca JSON
- Validarea API: FastAPI validează cererea automat folosind modele Pydantic
- Integrarea AI: Backend adaugă context (prompt de sistem) și apelează serviciul AI
- Gestionarea răspunsului: API primește răspunsul AI și îl poate modifica dacă e nevoie
- Afișarea frontend: JavaScript afișează răspunsul în interfața de chat
Înțelegerea arhitecturii API
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?"}
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:
# 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
/docsla 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ă
/docspentru 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!
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
# 🚨 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:
# 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.
# 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
# 🚨 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:
- Expunere la controlul versiunilor: Oricine are acces la repo-ul Git vede cheia ta API
- Repo-uri publice: Dacă faci push pe GitHub, cheia ta devine vizibilă internetului întreg
- Partajare în echipă: Dezvoltatorii care lucrează la proiect obțin cheia ta personală API
- 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:
# 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:
- Mergi în GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
- Apasă „Generate new token (classic)”
- Setează expirarea (30 zile pentru testare, mai lung pentru producție)
- Selectează permisiunile: Bifează „repo” și alte permisiuni necesare
- Generează tokenul și copiază-l imediat (nu îl vei mai vedea!)
- Lipește-l în fișierul tău .env
# Exemplu de cum arată token-ul tău (acesta este fals!)
GITHUB_TOKEN=ghp_1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R
Încărcarea variabilelor de mediu în 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ă:
# .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:
# .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
# 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ă
$ 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ă
/docspentru 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ă)
- Deschide browserul și accesează
http://localhost:5000/docs - Vei vedea Swagger UI cu toate endpoint-urile documentate
- Apasă pe
/hello→ "Try it out" → Introdu un mesaj de test → "Execute" - Vezi răspunsul direct în browser cu format corect
Metoda 2: Test simplu în browser
- Accesează
http://localhost:5000pentru endpoint-ul rădăcină - Accesează
http://localhost:5000/healthpentru verificarea stării serverului - Aceasta confirmă că serverul FastAPI rulează corect
Metoda 2: Test din linia de comandă (Avansat)
# 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
# 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.
# 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ă:
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:
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:
// Î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:
// 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:
# 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:
- Fă modificări în cod în VS Code
- FastAPI reîncarcă automat (mulțumită modului de reload al Uvicorn)
- Testează modificările imediat prin URL-ul public
- 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
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]
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ă:
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:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>AI Chat Assistant</title>
<link rel="stylesheet" href="styles.css">
</head>
<body>
<div class="chat-container">
<header class="chat-header">
<h1>AI Chat Assistant</h1>
<p>Ask me anything!</p>
</header>
<main class="chat-messages" id="messages" role="log" aria-live="polite">
<!-- Messages will be dynamically added here -->
</main>
<form class="chat-form" id="chatForm">
<div class="input-group">
<input
type="text"
id="messageInput"
placeholder="Type your message here..."
required
aria-label="Chat message input"
>
<button type="submit" id="sendBtn" aria-label="Send message">
Send
</button>
</div>
</form>
</div>
<script src="app.js"></script>
</body>
</html>
Înțelegerea fiecărui element HTML și scopul său:
Structura documentului
<!DOCTYPE html>: Indică browser-ului că este HTML5 modern<html lang="en">: Specifică limba paginii pentru cititoarele de ecran și traducătoare<meta charset="UTF-8">: Asigură codificarea corectă a caracterelor pentru texte internaționale<meta name="viewport"...>: Face pagina responsive pe mobil prin controlul zoom-ului și scalei
Elemente semantice
<header>: Identifică clar secțiunea de sus cu titlul și descrierea<main>: Designarea zonei principale de conținut (unde se desfășoară conversațiile)<form>: Corect din punct de vedere semantic pentru introducerea utilizatorului, permite navigare corectă cu tastatura
Caracteristici pentru accesibilitate
role="log": Semnalează cititoarelor de ecran că această zonă conține un jurnal cronologic al mesajeloraria-live="polite": Anunță cititoarele de ecran despre mesaje noi fără a întrerupearia-label: Oferă etichete descriptive controalelor formularuluirequired: Browser-ul validează că utilizatorul a introdus un mesaj înainte de a trimite
Integrarea CSS și JavaScript
- Atributele
class: Oferă puncte de stilizare pentru CSS (ex.chat-container,input-group) - Atributele
id: Permite JavaScript-ului să găsească și să manipuleze elemente specifice - Plasarea scriptului: Fișierul JavaScript este încărcat la final pentru a permite încărcarea întâi a HTML-ului
De ce funcționează această structură:
- Flux logic: Header → Conținut principal → Formular de input corespunde ordinii naturale de citire
- Accesibil cu tastatura: Utilizatorii pot naviga cu tabul printre toate elementele interactive
- Prietenos cu cititoarele de ecran: Repere clare și descrieri pentru utilizatorii cu deficiențe de vedere
- Responsive pe mobil: Meta tag-ul viewport permite design responsive
- Îmbunătățire progresivă: Funcționează chiar dacă CSS sau JavaScript nu se încarcă
Adăugarea JavaScript-ului interactiv: Logica aplicației web moderne
Acum să construim JavaScript-ul care aduce interfața noastră de chat la viață. Vom folosi modele moderne de JavaScript pe care le vei întâlni în dezvoltarea web profesională, inclusiv clase ES6, async/await și programare orientată pe evenimente.
Înțelegerea Arhitecturii Moderne JavaScript
În loc să scriem cod procedural (o serie de funcții care rulează în ordine), vom crea o arhitectură bazată pe clase. Gândește-te la o clasă ca la un plan pentru crearea obiectelor – la fel cum un plan al unui arhitect poate fi folosit pentru a construi mai multe case.
De ce să folosim clase pentru aplicații web?
- Organizare: Toate funcționalitățile legate sunt grupate împreună
- Reutilizare: Poți crea mai multe instanțe de chat pe aceeași pagină
- Mentenabilitate: Mai ușor de depanat și modificat funcții specifice
- Standard profesional: Acest model este folosit în framework-uri precum React, Vue și Angular
Creează app.js cu acest JavaScript modern, bine structurat:
// app.js - Logica aplicației moderne de chat
class ChatApp {
constructor() {
// Obține referințe către elementele DOM pe care trebuie să le manipulăm
this.messages = document.getElementById("messages");
this.form = document.getElementById("chatForm");
this.input = document.getElementById("messageInput");
this.sendButton = document.getElementById("sendBtn");
// Configurează aici URL-ul backend-ului tău
this.BASE_URL = "http://localhost:5000"; // Actualizează asta pentru mediul tău
this.API_ENDPOINT = `${this.BASE_URL}/hello`;
// Configurează ascultătorii de evenimente când aplicația de chat este creată
this.initializeEventListeners();
}
initializeEventListeners() {
// Ascultă trimiterea formularului (când utilizatorul apasă Trimite sau Enter)
this.form.addEventListener("submit", (e) => this.handleSubmit(e));
// Ascultă și tasta Enter în câmpul de introducere (UX mai bun)
this.input.addEventListener("keypress", (e) => {
if (e.key === "Enter" && !e.shiftKey) {
e.preventDefault();
this.handleSubmit(e);
}
});
}
async handleSubmit(event) {
event.preventDefault(); // Previne reîncărcarea paginii la trimiterea formularului
const messageText = this.input.value.trim();
if (!messageText) return; // Nu trimite mesaje goale
// Oferă feedback utilizatorului că ceva se întâmplă
this.setLoading(true);
// Adaugă imediat mesajul utilizatorului în chat (UI optimist)
this.appendMessage(messageText, "user");
// Golește câmpul de introducere pentru ca utilizatorul să poată scrie următorul mesaj
this.input.value = '';
try {
// Apelează API-ul AI și așteaptă răspunsul
const reply = await this.callAPI(messageText);
// Adaugă răspunsul AI în chat
this.appendMessage(reply, "assistant");
} catch (error) {
console.error('API Error:', error);
this.appendMessage("Sorry, I'm having trouble connecting right now. Please try again.", "error");
} finally {
// Reactivează interfața indiferent dacă a avut succes sau nu
this.setLoading(false);
}
}
async callAPI(message) {
const response = await fetch(this.API_ENDPOINT, {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify({ message })
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const data = await response.json();
return data.response;
}
appendMessage(text, role) {
const messageElement = document.createElement("div");
messageElement.className = `message ${role}`;
messageElement.innerHTML = `
<div class="message-content">
<span class="message-text">${this.escapeHtml(text)}</span>
<span class="message-time">${new Date().toLocaleTimeString()}</span>
</div>
`;
this.messages.appendChild(messageElement);
this.scrollToBottom();
}
escapeHtml(text) {
const div = document.createElement('div');
div.textContent = text;
return div.innerHTML;
}
scrollToBottom() {
this.messages.scrollTop = this.messages.scrollHeight;
}
setLoading(isLoading) {
this.sendButton.disabled = isLoading;
this.input.disabled = isLoading;
this.sendButton.textContent = isLoading ? "Sending..." : "Send";
}
}
// Inițializează aplicația de chat când pagina se încarcă
document.addEventListener("DOMContentLoaded", () => {
new ChatApp();
});
Înțelegerea fiecărui concept JavaScript
Structura clasei ES6:
class ChatApp {
constructor() {
// Aceasta rulează când creezi o nouă instanță ChatApp
// Este ca funcția "setup" pentru chat-ul tău
}
methodName() {
// Metodele sunt funcții care aparțin clasei
// Ele pot accesa proprietățile clasei folosind "this"
}
}
Modelul Async/Await:
// Mod vechi (iadul callback-urilor):
fetch(url)
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error(error));
// Mod modern (async/await):
try {
const response = await fetch(url);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
Programare orientată pe evenimente: În loc să verificăm constant dacă ceva s-a întâmplat, noi „ascultăm” evenimente:
// Când formularul este trimis, execută handleSubmit
this.form.addEventListener("submit", (e) => this.handleSubmit(e));
// Când este apăsat tasta Enter, execută de asemenea handleSubmit
this.input.addEventListener("keypress", (e) => { /* ... */ });
Manipularea DOM:
// Creează elemente noi
const messageElement = document.createElement("div");
// Modifică proprietățile acestora
messageElement.className = "message user";
messageElement.innerHTML = "Hello world!";
// Adaugă pe pagină
this.messages.appendChild(messageElement);
Securitate și bune practici
Prevenirea XSS:
escapeHtml(text) {
const div = document.createElement('div');
div.textContent = text; // Acesta escapează automat HTML-ul
return div.innerHTML;
}
De ce este important: Dacă un utilizator scrie <script>alert('hack')</script>, această funcție asigură că se afișează ca text și nu se execută ca și cod.
Gestionarea erorilor:
try {
const reply = await this.callAPI(messageText);
this.appendMessage(reply, "assistant");
} catch (error) {
// Afișați un mesaj de eroare prietenos utilizatorului în loc să întrerupeți aplicația
this.appendMessage("Sorry, I'm having trouble...", "error");
}
Considerații privind experiența utilizatorului:
- Interfață optimistă: Adaugă mesajul utilizatorului imediat, nu aștepta răspunsul serverului
- Stări de încărcare: Dezactivează butoanele și arată „Se trimite...” în timp ce aștepți
- Auto-derulare: Menține cele mai noi mesaje vizibile
- Validarea inputului: Nu trimite mesaje goale
- Scurtături de tastatură: Tasta Enter trimite mesajele (ca în aplicațiile reale de chat)
Înțelegerea Fluxului Aplicației
- Se încarcă pagina → se declanșează evenimentul
DOMContentLoaded→ se creeazănew ChatApp() - Se execută constructorul → Obține referințe la elemente DOM → Setează ascultători de evenimente
- Utilizatorul scrie mesaj → Apasă Enter sau dă click pe Trimite → Se execută
handleSubmit - handleSubmit → Validarea inputului → Se afișează starea de încărcare → Apelează API-ul
- API răspunde → Adaugă mesajul AI în chat → Re-activează interfața
- Pregătit pentru următorul mesaj → Utilizatorul poate continua conversația
Această arhitectură este scalabilă – poți adăuga cu ușurință funcții precum editarea mesajelor, încărcarea de fișiere sau fire multiple de conversații fără să rescrii structura de bază.
🎯 Verificare pedagogică: Arhitectură frontend modernă
Înțelegerea arhitecturii: Ai implementat o aplicație completă single-page folosind modele moderne de JavaScript. Aceasta reprezintă dezvoltarea frontend la nivel profesional.
Concepte cheie stăpânite:
- Arhitectura clasei ES6: Structură de cod organizată și ușor de întreținut
- Modele Async/Await: Programare asincronă modernă
- Programare orientată pe evenimente: Design UI reactiv
- Bune practici de securitate: Prevenirea XSS și validarea inputului
Conexiune cu industrie: Modelele pe care le-ai învățat (arhitectură bazată pe clase, operații asincrone, manipulare DOM) stau la baza framework-urilor moderne ca React, Vue și Angular. Construiești cu același gândire arhitecturală folosită în aplicațiile din producție.
Întrebare de reflecție: Cum ai extinde această aplicație de chat pentru a suporta conversații multiple sau autentificarea utilizatorului? Gândește-te la schimbările arhitecturale necesare și cum ar evolua structura clasei.
Stilizarea interfeței tale de chat
Acum să creăm o interfață de chat modernă, plăcută vizual, cu CSS. Stilizarea bună face aplicația să pară profesională și îmbunătățește experiența generală a utilizatorului. Vom folosi funcții CSS moderne precum Flexbox, CSS Grid și proprietăți personalizate pentru un design responsiv și accesibil.
Creează styles.css cu aceste stiluri cuprinzătoare:
/* styles.css - Modern chat interface styling */
:root {
--primary-color: #2563eb;
--secondary-color: #f1f5f9;
--user-color: #3b82f6;
--assistant-color: #6b7280;
--error-color: #ef4444;
--text-primary: #1e293b;
--text-secondary: #64748b;
--border-radius: 12px;
--shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
}
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
min-height: 100vh;
display: flex;
align-items: center;
justify-content: center;
padding: 20px;
}
.chat-container {
width: 100%;
max-width: 800px;
height: 600px;
background: white;
border-radius: var(--border-radius);
box-shadow: var(--shadow);
display: flex;
flex-direction: column;
overflow: hidden;
}
.chat-header {
background: var(--primary-color);
color: white;
padding: 20px;
text-align: center;
}
.chat-header h1 {
font-size: 1.5rem;
margin-bottom: 5px;
}
.chat-header p {
opacity: 0.9;
font-size: 0.9rem;
}
.chat-messages {
flex: 1;
padding: 20px;
overflow-y: auto;
display: flex;
flex-direction: column;
gap: 15px;
background: var(--secondary-color);
}
.message {
display: flex;
max-width: 80%;
animation: slideIn 0.3s ease-out;
}
.message.user {
align-self: flex-end;
}
.message.user .message-content {
background: var(--user-color);
color: white;
border-radius: var(--border-radius) var(--border-radius) 4px var(--border-radius);
}
.message.assistant {
align-self: flex-start;
}
.message.assistant .message-content {
background: white;
color: var(--text-primary);
border-radius: var(--border-radius) var(--border-radius) var(--border-radius) 4px;
border: 1px solid #e2e8f0;
}
.message.error .message-content {
background: var(--error-color);
color: white;
border-radius: var(--border-radius);
}
.message-content {
padding: 12px 16px;
box-shadow: var(--shadow);
position: relative;
}
.message-text {
display: block;
line-height: 1.5;
word-wrap: break-word;
}
.message-time {
display: block;
font-size: 0.75rem;
opacity: 0.7;
margin-top: 5px;
}
.chat-form {
padding: 20px;
border-top: 1px solid #e2e8f0;
background: white;
}
.input-group {
display: flex;
gap: 10px;
align-items: center;
}
#messageInput {
flex: 1;
padding: 12px 16px;
border: 2px solid #e2e8f0;
border-radius: var(--border-radius);
font-size: 1rem;
outline: none;
transition: border-color 0.2s ease;
}
#messageInput:focus {
border-color: var(--primary-color);
}
#messageInput:disabled {
background: #f8fafc;
opacity: 0.6;
cursor: not-allowed;
}
#sendBtn {
padding: 12px 24px;
background: var(--primary-color);
color: white;
border: none;
border-radius: var(--border-radius);
font-size: 1rem;
font-weight: 600;
cursor: pointer;
transition: background-color 0.2s ease;
min-width: 80px;
}
#sendBtn:hover:not(:disabled) {
background: #1d4ed8;
}
#sendBtn:disabled {
background: #94a3b8;
cursor: not-allowed;
}
@keyframes slideIn {
from {
opacity: 0;
transform: translateY(10px);
}
to {
opacity: 1;
transform: translateY(0);
}
}
/* Responsive design for mobile devices */
@media (max-width: 768px) {
body {
padding: 10px;
}
.chat-container {
height: calc(100vh - 20px);
border-radius: 8px;
}
.message {
max-width: 90%;
}
.input-group {
flex-direction: column;
gap: 10px;
}
#messageInput {
width: 100%;
}
#sendBtn {
width: 100%;
}
}
/* Accessibility improvements */
@media (prefers-reduced-motion: reduce) {
.message {
animation: none;
}
* {
transition: none !important;
}
}
/* Dark mode support */
@media (prefers-color-scheme: dark) {
.chat-container {
background: #1e293b;
color: #f1f5f9;
}
.chat-messages {
background: #0f172a;
}
.message.assistant .message-content {
background: #334155;
color: #f1f5f9;
border-color: #475569;
}
.chat-form {
background: #1e293b;
border-color: #475569;
}
#messageInput {
background: #334155;
color: #f1f5f9;
border-color: #475569;
}
}
Înțelegerea arhitecturii CSS:
- Folosește proprietăți personalizate CSS (variabile) pentru temă consistentă și întreținere ușoară
- Implementează layout Flexbox pentru design responsiv și aliniere corectă
- Include animații fluide pentru apariția mesajelor fără a distrage atenția
- Oferă distincție vizuală între mesajele utilizatorului, răspunsurile AI și stările de eroare
- Susține design responsiv care funcționează atât pe desktop cât și pe dispozitive mobile
- Ia în considerare accesibilitatea cu preferințe de reducere a mișcării și rate de contrast adecvate
- Oferă suport pentru mod întunecat bazat pe preferințele sistemului utilizatorului
Configurarea URL-ului backend-ului tău
Ultimul pas este actualizarea BASE_URL în JavaScript-ul tău pentru a corespunde serverului backend:
// Pentru dezvoltare locală
this.BASE_URL = "http://localhost:5000";
// Pentru GitHub Codespaces (înlocuiți cu URL-ul dvs. real)
this.BASE_URL = "https://your-codespace-name-5000.app.github.dev";
Determinarea URL-ului backend:
- Dezvoltare locală: Folosește
http://localhost:5000dacă rulezi frontend și backend local - Codespaces: Găsește URL-ul backend în fila Ports după ce faci portul 5000 public
- Producție: Înlocuiește cu domeniul tău real când faci deploy pe un serviciu de găzduire
💡 Sfat pentru testare: Poți testa backend-ul direct accesând URL-ul rădăcină în browser. Vei vedea mesajul de bun venit de la serverul FastAPI.
Testare și Implementare
Acum că ai componentele frontend și backend construite, să testăm dacă totul funcționează împreună și să explorăm opțiunile de implementare pentru a-ți împărtăși asistentul de chat cu alții.
Fluxul de testare locală
Urmează acești pași pentru a testa aplicația completă:
graph TD
A[Pornește Serverul Backend] --> B[Configurează Variabilele de Mediu]
B --> C[Testează Endpoint-urile API]
C --> D[Deschide Frontend-ul în Browser]
D --> E[Testează Funcționalitatea Chat-ului]
E --> F[Depanează Orice Probleme]
Procesul pas cu pas pentru testare:
-
Pornește serverul backend:
cd backend source venv/bin/activate # sau venv\Scripts\activate pe Windows python api.py -
Verifică dacă API-ul funcționează:
- Deschide
http://localhost:5000în browser - Ar trebui să vezi mesajul de bun venit de la serverul FastAPI
- Deschide
-
Deschide frontend-ul:
- Mergi în directorul frontend
- Deschide
index.htmlîn browser-ul tău web - Sau folosește extensia Live Server din VS Code pentru o experiență mai bună de dezvoltare
-
Testează funcționalitatea chat-ului:
- Scrie un mesaj în câmpul de input
- Apasă „Trimite” sau Enter
- Verifică dacă AI-ul răspunde corespunzător
- Verifică consola browser-ului pentru eventuale erori JavaScript
Depanarea problemelor comune
| Problemă | Simptome | Soluție |
|---|---|---|
| Eroare CORS | Frontend-ul nu poate accesa backend-ul | Asigură-te că FastAPI CORSMiddleware este configurat corect |
| Eroare Cheie API | Răspunsuri 401 Unauthorized | Verifică variabila de mediu GITHUB_TOKEN |
| Conexiune Refuzată | Erori de rețea în frontend | Verifică URL-ul backend și dacă serverul Flask este pornit |
| Nu există răspuns AI | Răspunsuri goale sau erori | Verifică jurnalele backendului pentru probleme de cotă API sau autentificare |
Pași comuni pentru depanare:
- Verifică Consola de instrumente dezvoltator din browser pentru erori JavaScript
- Confirmă fila Network arată solicitări și răspunsuri API reușite
- Revizuiește output-ul terminalului backend pentru erori Python sau probleme API
- Verifică dacă variabilele de mediu sunt încărcate și accesibile corect
📈 Cronologia ta de masterizare a dezvoltării aplicațiilor AI
timeline
title Călătoria completă de dezvoltare a aplicației AI
section Bazele AI
Înțelegerea AI Generativ
: Înțelege conceptele de recunoaștere a tiparelor
: Stăpânește controlul parametrilor AI
: Învață tehnici de inginerie a prompturilor
Integrarea modelelor GitHub
: Navighează pe platformele de servicii AI
: Gestionează autentificarea în siguranță
: Optimizează parametrii modelului
section Dezvoltare Backend
Arhitectura API Python
: Construiește aplicații FastAPI
: Implementează operațiuni asincrone
: Creează endpointuri sigure
Integrarea serviciilor AI
: Conectează-te la API-uri AI externe
: Gestionează limitarea ratei
: Implementează limite de eroare
section Măiestria Frontend
Modele moderne JavaScript
: Stăpânește arhitectura clasei ES6
: Implementează fluxuri async/await
: Construiește interfețe responsive
Experiența utilizatorului în timp real
: Creează interfețe dinamice de chat
: Gestionează stările de încărcare
: Optimizează interacțiunile utilizatorului
section Pregătirea pentru producție
Securitate și performanță
: Implementează gestionarea securizată a token-urilor
: Previne vulnerabilitățile XSS
: Optimizează performanța API-ului
Implementare profesională
: Construiește arhitecturi scalabile
: Creează cod ușor de întreținut
: Documentează procesele de dezvoltare
🎓 Prag de absolvire: Ai construit cu succes o aplicație completă alimentată de AI folosind aceleași tehnologii și modele arhitecturale care stau la baza asistenților AI moderni. Aceste abilități reprezintă intersecția dintre dezvoltarea web tradițională și integrarea de ultimă generație a AI-ului.
🔄 Capacități la nivel următor:
- Pregătit să explorezi framework-uri AI avansate (LangChain, LangGraph)
- Pregătit să construiești aplicații AI multi-modale (text, imagine, voce)
- Echipează-te pentru implementarea bazelor de date vectoriale și sisteme de recuperare
- Fundamentul pus pentru machine learning și fine-tuning de modele AI
Provocarea Agent GitHub Copilot 🚀
Folosește modul Agent pentru a îndeplini următoarea provocare:
Descriere: Îmbunătățește asistentul de chat adăugând istoric al conversațiilor și persistență a mesajelor. Această provocare te va ajuta să înțelegi cum să gestionezi starea în aplicațiile de chat și să implementezi stocarea datelor pentru o experiență mai bună a utilizatorului.
Prompt: Modifică aplicația de chat pentru a include istoricul conversațiilor care persistă între sesiuni. Adaugă funcționalitatea de a salva mesajele de chat în local storage, afișarea istoricului conversației la încărcarea paginii și un buton „Șterge Istoricul”. Implementează, de asemenea, indicatori de tastare și timestamp-uri ale mesajelor pentru o experiență de chat mai realistă.
Află mai multe despre modul agent aici.
Tema: Construiește-ți propriul asistent AI personal
Acum vei crea propria implementare a unui asistent AI. În loc să replici codul tutorialului, aceasta este o oportunitate să aplici conceptele construind ceva care să reflecte interesele și cazurile tale de utilizare.
Cerințe pentru proiect
Să-ți organizăm proiectul cu o structură curată și clară:
my-ai-assistant/
├── backend/
│ ├── api.py # Your FastAPI server
│ ├── llm.py # AI integration functions
│ ├── .env # Your secrets (keep this safe!)
│ └── requirements.txt # Python dependencies
├── frontend/
│ ├── index.html # Your chat interface
│ ├── app.js # The JavaScript magic
│ └── styles.css # Make it look amazing
└── README.md # Tell the world about your creation
Sarcini de implementare de bază
Dezvoltare backend:
- Ia codul nostru FastAPI și fă-l al tău
- Creează o personalitate AI unică – poate un asistent de gătit, un partener creativ de scris sau un coleg de studiu?
- Adaugă gestionare solidă a erorilor pentru ca aplicația să nu se oprească la probleme
- Scrie documentație clară pentru oricine vrea să înțeleagă cum funcționează API-ul tău
Dezvoltare frontend:
- Construiește o interfață de chat intuitivă și prietenoasă
- Scrie JavaScript curat, modern, de care să fii mândru în fața altor dezvoltatori
- Desenează un stil personalizat care reflectă personalitatea AI-ului tău – jucăuș și colorat? Curat și minimalist? Alegerea este a ta!
- Asigură-te că funcționează bine atât pe telefoane, cât și pe computere
Cerințe de personalizare:
- Alege un nume și o personalitate unică pentru asistentul tău AI – poate ceva care reflectă interesele tale sau problemele pe care vrei să le rezolvi
- Personalizează designul vizual pentru a se potrivi vibe-ului asistentului tău
- Scrie un mesaj de bun venit convingător care să invite oamenii să înceapă să converseze
- Testează asistentul cu diferite tipuri de întrebări să vezi cum răspunde
Idei de îmbunătățire (Opțional)
Vrei să-ți duci proiectul la nivelul următor? Iată câteva idei distractive de explorat:
| Funcționalitate | Descriere | Abilitățile pe care le vei exersa |
|---|---|---|
| Istoricul mesajelor | Păstrează conversațiile chiar și după refresh-ul paginii | Lucrul cu localStorage, gestionarea JSON |
| Indicatori de tastare | Arată „AI tastează...” în timp ce aștepți răspunsurile | Animații CSS, programare asincronă |
| Timestamp-uri mesaje | Afișează când a fost trimis fiecare mesaj | Formatare dată/oră, design UX |
| Export chat | Permite utilizatorilor să descarce conversația | Gestionarea fișierelor, export de date |
| Comutare temă | Trecere între mod lumină/întunecat | Variabile CSS, preferințe utilizator |
| Input vocal | Adaugă funcționalitate speech-to-text | API-uri web, accesibilitate |
Testare și documentație
Asigurarea calității:
- Testează aplicația cu diferite tipuri de input și situații-limită
- Verifică că designul responsiv funcționează pe dimensiuni diferite de ecran
- Testare accesibilitate cu navigare prin tastatură și cititoare de ecran
- Validarea HTML și CSS pentru respectarea standardelor
Cerințe pentru documentație:
- Scrie un README.md care să explice proiectul și cum se rulează
- Include capturi de ecran ale interfeței tale de chat în acțiune
- Documentează orice funcționalități unice sau personalizări adăugate
- Oferă instrucțiuni clare de setup pentru alți dezvoltatori
Ghid de predare
Livrabile proiect:
- Folderul complet al proiectului cu tot codul sursă
- README.md cu descrierea proiectului și instrucțiuni de setup
- Capturi de ecran care demonstrează asistentul tău de chat în acțiune
- O scurtă reflecție despre ce ai învățat și ce provocări ai întâmpinat
Criterii de evaluare:
- Funcționalitate: Asistentul de chat funcționează conform așteptărilor?
- Calitatea codului: Codul este bine organizat, comentat și ușor de întreținut?
- Design: Interfața este atractivă vizual și ușor de utilizat?
- Creativitate: Cât de unică și personalizată este implementarea ta?
- Documentație: Instrucțiunile de setup sunt clare și complete?
💡 Sfat de succes: Începe cu cerințele de bază, apoi adaugă îmbunătățiri după ce totul funcționează. Concentrează-te pe o experiență de bază bine finisată înainte de a adăuga funcții avansate.
Soluție
Provocări bonus
Pregătit să-ți duci asistentul AI la următorul nivel? Încearcă aceste provocări avansate care vor aprofunda înțelegerea ta asupra integrării AI și dezvoltării web.
Personalizarea personalității
Magia adevărată apare atunci când dai asistentului tău AI o personalitate unică. Experimentează cu diferite prompturi de sistem pentru a crea asistenți specializați:
Exemplu asistent profesional:
call_llm(message, "You are a professional business consultant with 20 years of experience. Provide structured, actionable advice with specific steps and considerations.")
Exemplu ajutor scriere creativă:
call_llm(message, "You are an enthusiastic creative writing coach. Help users develop their storytelling skills with imaginative prompts and constructive feedback.")
Exemplu mentor tehnic:
call_llm(message, "You are a patient senior developer who explains complex programming concepts using simple analogies and practical examples.")
Îmbunătățiri frontend
Transformă-ți interfața de chat cu aceste îmbunătățiri vizuale și funcționale:
Funcții CSS avansate:
- Implementează animații și tranziții fluide pentru mesaje
- Adaugă design-uri personalizate pentru bulele de chat cu forme CSS și gradienturi
- Creează o animație indicator de tastare pentru când AI-ul „gândește”
- Proiectează reacții cu emoji sau sistem de evaluare a mesajelor
Îmbunătățiri JavaScript:
- Adaugă scurtături de tastatură (Ctrl+Enter pentru trimitere, Escape pentru ștergere input)
- Implementează căutare și filtrare mesaje
- Creează funcție de export conversație (descărcare ca text sau JSON)
- Adaugă auto-salvare în localStorage pentru a preveni pierderea mesajelor
Integrare AI avansată
Multiple personalități AI:
- Creează un dropdown pentru a schimba între diferite personalități AI
- Salvează personalitatea preferată a utilizatorului în localStorage
- Implementează comutare de context care să păstreze fluxul conversației
Funcții inteligente de răspuns:
- Adaugă conștiență de context al conversației (AI își amintește mesajele anterioare)
- Implementează sugestii inteligente bazate pe subiectul conversației
- Creează butoane de răspuns rapid pentru întrebări frecvente
🎯 Obiectiv de învățare: Aceste provocări bonus te ajută să înțelegi modele avansate de dezvoltare web și tehnici de integrare AI utilizate în aplicații de producție.
Rezumat și Pașii Următori
Felicitări! Ai construit cu succes un asistent complet de chat alimentat de AI de la zero. Acest proiect ți-a oferit experiență practică cu tehnologii moderne de dezvoltare web și integrare AI – abilități din ce în ce mai valoroase în peisajul tehnologic actual.
Ce ai realizat
Pe parcursul acestei lecții, ai stăpânit mai multe tehnologii și concepte cheie:
Dezvoltare Backend:
- Integrat cu GitHub Models API pentru funcționalitate AI
- Construit un API RESTful folosind Flask cu gestionare corectă a erorilor
- Implementat autentificare securizată folosind variabile de mediu
- Configurat CORS pentru cereri cross-origin între frontend și backend
Dezvoltare Frontend:
- Creat o interfață de chat responsivă folosind HTML semantic
- Implementat JavaScript modern cu async/await și arhitectură bazată pe clase
- Conceput o interfață atractivă cu CSS Grid, Flexbox și animații
- Adăugat funcționalități de accesibilitate și principii de design responsiv
Integrare Full-Stack:
- Conectat frontend și backend prin apeluri API HTTP
- Gestionat interacțiuni în timp real și flux de date asincron
- Implementat gestionarea erorilor și feedback către utilizator pe parcursul aplicației
- Testat fluxul complet al aplicației de la inputul utilizatorului la răspunsul AI
Rezultate Cheie ale Învățării
mindmap
root((Abilități Aplicație Chat AI))
API Integration
Authentication
Error Handling
Async Programming
Web Development
Semantică HTML5
CSS Modern
JavaScript ES6+
User Experience
Design Responsiv
Accesibilitate
Interacțiune în Timp Real
AI Understanding
Inginerie Prompturi
Parametri Model
Flux Conversație
Acest proiect ți-a introdus fundamentele construirii aplicațiilor alimentate de AI, care reprezintă viitorul dezvoltării web. Acum înțelegi cum să integrezi capabilități AI în aplicații web tradiționale, creând experiențe utilizator captivante, care par inteligente și reactive.
Aplicații Profesionale
Competențele dezvoltate în această lecție sunt aplicabile direct în cariere moderne de dezvoltare software:
- Dezvoltare web full-stack folosind framework-uri și API-uri moderne
- Integrare AI în aplicații web și mobile
- Proiectarea și dezvoltarea API-urilor pentru arhitecturi microservicii
- Dezvoltare interfață utilizator cu accent pe accesibilitate și design responsiv
- Practici DevOps incluzând configurarea mediului și implementarea
Continuarea Călătoriei Tale în Dezvoltarea AI
Următorii Pași de Învățare:
- Explorează modele și API-uri AI mai avansate (GPT-4, Claude, Gemini)
- Învață despre tehnici de inginerie a prompturilor pentru răspunsuri AI mai bune
- Studiază designul conversațional și principiile experienței utilizator chatbot
- Investigă siguranța AI, etica și practicile responsabile de dezvoltare AI
- Construiește aplicații mai complexe cu memorie a conversațiilor și conștientizare de context
Idei Avansate de Proiect:
- Camere de chat multi-utilizatori cu moderare AI
- Chatbot-uri de servicii clienți alimentate de AI
- Asistenți educaționali cu învățare personalizată
- Colaboratori creativi pentru scriere cu diferite personalități AI
- Asistenți pentru documentație tehnică dedicată dezvoltatorilor
Începe cu GitHub Codespaces
Vrei să încerci acest proiect într-un mediu de dezvoltare în cloud? GitHub Codespaces oferă o configurație completă de dezvoltare în browserul tău, perfectă pentru experimentarea cu aplicații AI fără cerințe locale de instalare.
Configurarea Mediului tău de Dezvoltare
Pasul 1: Creează din șablon
- Navighează la depozitul Web Dev For Beginners
- Apasă pe „Use this template” în colțul din dreapta sus (asigură-te că ești logat în GitHub)
Pasul 2: Pornește Codespaces
- Deschide depozitul proaspăt creat
- Apasă pe butonul verde „Code” și selectează „Codespaces”
- Alege „Create codespace on main” pentru a începe mediul de dezvoltare
Pasul 3: Configurarea Mediului Odată ce Codespace-ul tău este gata, vei avea acces la:
- Instrumente preinstalate precum Python, Node.js și toate instrumentele necesare dezvoltării
- Interfață VS Code cu extensii pentru dezvoltare web
- Acces terminal pentru rularea serverelor backend și frontend
- Redirecționare porturi pentru testarea aplicațiilor tale
Ce oferă Codespaces:
- Elimină problemele de configurare și instalare locală
- Furnizează un mediu de dezvoltare consistent pe diverse dispozitive
- Include instrumente și extensii preconfigurate pentru dezvoltare web
- Oferă integrare perfectă cu GitHub pentru controlul versiunilor și colaborare
🚀 Sfat Pro: Codespaces este ideal pentru învățare și prototipare de aplicații AI deoarece gestionează automat toată configurarea complexă a mediului, lăsându-te să te concentrezi pe construire și învățare, nu pe depanare de configurare.
Declinare de responsabilitate: Acest document a fost tradus folosind serviciul de traducere AI Co-op Translator. Deși ne străduim să asigurăm acuratețea, vă rugăm să rețineți că traducerile automate pot conține erori sau inexactități. Documentul original în limba sa nativă trebuie considerat sursa autorizată. Pentru informații critice, se recomandă traducerea profesională realizată de un traducător uman. Nu ne asumăm responsabilitatea pentru eventualele neînțelegeri sau interpretări greșite rezultate din utilizarea acestei traduceri.