# Vytvorte chat asistenta s AI
Pamätáte si Star Trek, keď posádka voľne komunikovala s počítačom lode, pýtala sa zložité otázky a dostávala premyslené odpovede? To, čo v 60. rokoch vyzeralo ako čistá sci-fi, je dnes niečo, čo môžete vytvoriť pomocou webových technológií, ktoré už poznáte.
V tejto lekcii vytvoríme AI chat asistenta pomocou HTML, CSS, JavaScriptu a určitej backendovej integrácie. Objavíte, ako rovnaké zručnosti, ktoré sa učíte, môžu byť prepojené s výkonnými AI službami, ktoré rozumejú kontextu a generujú zmysluplné odpovede.
Myslite na AI ako na prístup k obrovskej knižnici, ktorá nielenže nájde informácie, ale aj ich syntetizuje do koherentných odpovedí prispôsobených vašim konkrétnym otázkam. Namiesto prehľadávania tisícok strán dostanete priame, kontextové odpovede.
Integrácia prebieha cez známe webové technológie pracujúce spolu. HTML vytvára chatové rozhranie, CSS rieši vizuálny dizajn, JavaScript spravuje interakcie používateľa a backendové API spája všetko s AI službami. Je to podobné, ako keď rôzne sekcie orchestra spolupracujú na vytvorení symfónie.
V podstate budujeme most medzi prirodzenou ľudskou komunikáciou a strojovým spracovaním. Naučíte sa technickú implementáciu integrácie AI služieb aj návrhové vzory, ktoré robia interakcie intuitívnymi.
Na konci tejto lekcie bude integrácia AI pôsobiť menej tajomne a viac ako ďalšie API, s ktorým môžete pracovať. Pochopíte základné vzory, ktoré poháňajú aplikácie ako ChatGPT a Claude, za použitia rovnakých webových vývojárskych princípov, ktoré sa učíte.
## ⚡ Čo môžete spraviť za nasledujúcich 5 minút
**Rýchla cesta pre zaneprázdnených vývojárov**
```mermaid
flowchart LR
A[⚡ 5 minút] --> B[Získajte GitHub token]
B --> C[Otestujte AI ihrisko]
C --> D[Skopírujte Python kód]
D --> E[Zobrazte odpovede AI]
```
- **Minúta 1**: Navštívte [GitHub Models Playground](https://github.com/marketplace/models/azure-openai/gpt-4o-mini/playground) a vytvorte si osobný prístupový token
- **Minúta 2**: Testujte AI interakcie priamo v rozhraní playgroundu
- **Minúta 3**: Kliknite na záložku "Code" a skopírujte pythonovský útržok
- **Minúta 4**: Spustite kód lokálne so svojím tokenom: `GITHUB_TOKEN=your_token python test.py`
- **Minúta 5**: Sledujte, ako vaša prvá AI odpoveď vzniká z vášho vlastného kódu
**Rýchly testovací kód**:
```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)
```
**Prečo je to dôležité**: Za 5 minút zažijete kúzlo programovej AI interakcie. Toto reprezentuje základný stavebný blok, ktorý poháňa každú AI aplikáciu, ktorú používate.
Takto bude vyzerať váš hotový projekt:
## 🗺️ Vaša cesta učenia sa vývoja AI aplikácií
```mermaid
journey
title Od webového vývoja po integráciu AI
section Porozumenie základom AI
Objavte koncepty generatívnej AI: 4: You
Preskúmajte platformu GitHub Models: 6: You
Ovládnite parametre a prompt AI: 8: You
section Integrácia backendu
Vytvorte Python API server: 5: You
Implementujte volania funkcií AI: 7: You
Spravujte asynchrónne operácie: 8: You
section Vývoj frontend
Vytvorte moderné chatové rozhranie: 6: You
Ovládnite interakcie v reálnom čase: 8: You
Vytvorte responzívny používateľský zážitok: 9: You
section Profesionálna aplikácia
Nasadzujte kompletný AI systém: 7: You
Optimalizujte výkonnostné vzory: 8: You
Vytvorte aplikáciu pripravenú na produkciu: 9: You
```
**Cieľ vašej cesty**: Na konci tejto lekcie ste vytvorili kompletnú AI poháňanú aplikáciu pomocou tých istých technológií a vzorov, ktoré poháňajú moderných AI asistentov ako ChatGPT, Claude a Google Bard.
## Pochopenie AI: Od záhady k majstrovstvu
Predtým, než sa pustíme do kódu, poďme pochopiť, s čím pracujeme. Ak ste už použili API, poznáte základný vzor: pošlite požiadavku, príjmite odpoveď.
AI API fungujú podobne, ale namiesto vyhľadávania v databáze generujú nové odpovede na základe vzorov naučených z obrovského množstva textu. Predstavte si to ako rozdiel medzi knižničným katalógom a znalým knihovníkom, ktorý vie syntetizovať informácie z viacerých zdrojov.
### Čo je vlastne "Generatívna AI"?
Zvažujte, ako Rosettská doska umožnila vedcom porozumieť egyptským hieroglyfom tým, že našla vzory medzi známymi a neznámymi jazykmi. AI modely pracujú podobne – nachádzajú vzory v enormnom množstve textu, aby pochopili, ako jazyk funguje, a potom používajú tieto vzory na generovanie vhodných odpovedí na nové otázky.
**Rozoberme si to na jednoduchom porovnaní:**
- **Tradičná databáza**: Ako keď si žiadate rodný list – získate vždy ten istý presný dokument
- **Vyhľadávač**: Ako keď žiadate knihovníka nájsť knihy o mačkách – ukáže vám, čo je dostupné
- **Generatívna AI**: Ako keď sa pýtate znalého priateľa na mačky – povie vám zaujímavé veci svojimi slovami, prispôsobené tomu, čo chcete vedieť
```mermaid
graph LR
A[Vaša otázka] --> B[AI Model]
B --> C[Rozpoznávanie vzorov]
C --> D[Generovanie obsahu]
D --> E[Kontextuálna odpoveď]
F[Tréningové dáta Knihy, články, web] --> B
```
### Ako sa AI modely učia (jednoduchá verzia)
AI modely sa učia vystavením obrovským datasetom obsahujúcim texty z kníh, článkov a rozhovorov. Počas tohto procesu identifikujú vzory v:
- Štruktúre myšlienok v písanej komunikácii
- Ktoré slová sa často vyskytujú spolu
- Ako plynú bežné konverzácie
- Kontextových rozdieloch medzi formálnou a neformálnou komunikáciou
**Je to podobné ako keď archeológovia dešifrujú staroveké jazyky**: analyzujú tisícky príkladov, aby pochopili gramatiku, slovnú zásobu a kultúrny kontext, a nakoniec sú schopní interpretovať nové texty pomocou naučených vzorov.
### Prečo GitHub Models?
Používame GitHub Models z praktického dôvodu – poskytuje nám prístup k podnikovej úrovni AI bez potreby zriaďovať vlastnú AI infraštruktúru (verím, že to teraz nechcete robiť!). Predstavte si to ako používanie API pre počasie namiesto pokusu predpovedať počasie sami zriadením počasia všade.
Je to v podstate "AI ako služba" a najlepšie na tom je, že začať je zadarmo, takže môžete experimentovať bez obáv o vysoké náklady.
```mermaid
graph LR
A[Frontend Chat UI] --> B[Vaše Backend API]
B --> C[GitHub Models API]
C --> D[Spracovanie AI modelu]
D --> C
C --> B
B --> A
```
Budeme používať GitHub Models pre našu backendovú integráciu, ktorá poskytuje prístup k profesionálnym AI schopnostiam cez vývojársky priateľské rozhranie. [GitHub Models Playground](https://github.com/marketplace/models/azure-openai/gpt-4o-mini/playground) slúži ako testovacie prostredie, kde môžete experimentovať s rôznymi AI modelmi a pochopiť ich schopnosti pred implementáciou v kóde.
## 🧠 Ekosystém vývoja AI aplikácií
```mermaid
mindmap
root((Vývoj AI))
Understanding AI
Generative Models
Rozpoznávanie vzorov
Generovanie obsahu
Pochopenie kontextu
Syntéza odpovedí
AI Parameters
Riadenie teploty
Limity tokenov
Top-p filtrovanie
Systémové prompt-y
Backend Architecture
API Integration
GitHub modely
Autentifikácia
Spracovanie požiadaviek
Správa chýb
Python Infrastructure
FastAPI rámec
Asynchrónne operácie
Bezpečnosť prostredia
Konfigurácia CORS
Frontend Experience
Chat Interface
Aktualizácie v reálnom čase
História správ
Spätná väzba užívateľa
Stav načítania
Modern Web Tech
ES6 triedy
Async/Await
Manipulácia s DOM
Spracovanie udalostí
Professional Patterns
Security Best Practices
Správa tokenov
Validácia vstupu
Prevencia XSS
Chybové hranice
Production Readiness
Optimalizácia výkonu
Responzívny dizajn
Prístupnosť
Testovacie stratégie
```
**Základný princíp**: Vývoj AI aplikácií kombinuje tradičné webové vývojárske zručnosti s integráciou AI služieb, čím vytvára inteligentné aplikácie, ktoré pôsobia prirodzene a reagujú na používateľov.
**Čo robí playground tak užitočným:**
- **Vyskúšajte** rôzne AI modely ako GPT-4o-mini, Claude a ďalšie (všetky zadarmo!)
- **Testujte** svoje nápady a vstupy pred písaním kódu
- **Získajte** hotové kódy vo vašom obľúbenom programovacom jazyku
- **Ladte** nastavenia ako úroveň kreativity a dĺžka odpovede a sledujte ich vplyv na výstup
Keď si trošku pohrajete, stačí kliknúť na záložku "Code" a vybrať programovací jazyk, aby ste získali implementačný kód, ktorý budete potrebovať.
## Nastavenie backendovej integrácie v Pythone
Teraz implementujeme integráciu AI pomocou Pythonu. Python je výborný pre AI aplikácie vďaka svojej jednoduchej syntaxe a výkonným knižniciam. Začneme so kódom z GitHub Models playground a potom ho preformulujeme do znovu použiteľnej, produkčne pripravenej funkcie.
### Pochopenie základnej implementácie
Keď si stiahnete Python kód z playgroundu, dostanete niečo takéto. Nebojte sa, ak sa vám to na začiatok zdá veľa – pozrieme si to krok za krokom:
```python
"""Run this model in Python
> pip install openai
"""
import os
from openai import OpenAI
# Na overenie pomocou modelu budete potrebovať vytvoriť osobný prístupový token (PAT) vo vašich nastaveniach GitHubu.
# Vytvorte si svoj PAT token podľa pokynov tu: 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)
```
**Čo sa v tomto kóde deje:**
- **Importujeme** nástroje, ktoré potrebujeme: `os` pre čítanie premenných prostredia a `OpenAI` na komunikáciu s AI
- **Nastavujeme** klienta OpenAI, aby smeroval na GitHub AI servery namiesto priamo na OpenAI
- **Autentifikujeme sa** špeciálnym GitHub tokenom (viac o tom o chvíľu!)
- **Štruktúrujeme** našu konverzáciu s rôznymi "rolami" – predstavte si to ako nastavenie scény pre divadlo
- **Posielame** požiadavku AI s niektorými ladenými parametrami
- **Vyťahujeme** skutočný text odpovede zo všetkých prijatých dát
### Pochopenie rolí správ: Rámec AI konverzácie
AI konverzácie používajú špecifickú štruktúru s rôznymi "rolami", ktoré majú rôzne účely:
```python
messages=[
{
"role": "system",
"content": "You are a helpful assistant who explains things simply."
},
{
"role": "user",
"content": "What is machine learning?"
}
]
```
**Predstavte si to ako režisérsku réžiu:**
- **Systémová rola**: Ako režijné poznámky pre herca – hovorí AI, ako sa má správať, akú má mať osobnosť a ako odpovedať
- **Používateľská rola**: Skutočná otázka alebo správa od osoby používajúcej vašu aplikáciu
- **Asistentova rola**: AI odpoveď (tú neodosielate, ale zobrazuje sa v histórii konverzácie)
**Analógia z reálneho sveta**: Predstavte si, že predstavujete priateľa niekomu na párty:
- **Systémová správa**: "Toto je moja priateľka Sarah, je lekárka, ktorá skvele vysvetľuje lekárske koncepty jednoduchým spôsobom"
- **Používateľská správa**: "Môžeš mi vysvetliť, ako fungujú vakcíny?"
- **Asistentova odpoveď**: Sarah odpovedá ako priateľská lekárka, nie ako právnička alebo kuchár
### Pochopenie AI parametrov: Ladenie správania odpovede
Číselné parametre v AI API volaniach riadia, ako model generuje odpovede. Tieto nastavenia umožňujú upraviť správanie AI pre rôzne použitia:
#### Temperaturu (0.0 až 2.0): Regulátor kreativity
**Čo robí**: Riadi, ako kreatívne alebo predvídateľné budú odpovede AI.
**Predstavte si to ako mieru improvizácie jazzového hudobníka:**
- **Temperatúra = 0.1**: Hrá presne tú istú melódiu zakaždým (veľmi predvídateľné)
- **Temperatúra = 0.7**: Pridáva chutné variácie, pričom zostáva rozpoznateľný (vyvážená kreativita)
- **Temperatúra = 1.5**: Plná experimentálna jazzová hra s nečakanými obratmi (veľmi nepredvídateľné)
```python
# Veľmi predvídateľné odpovede (dobré pre faktické otázky)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "What is 2+2?"}],
temperature=0.1 # Takmer vždy povie "4"
)
# Kreatívne odpovede (dobré na brainstorming)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Write a creative story opening"}],
temperature=1.2 # Vygeneruje jedinečné, nečakané príbehy
)
```
#### Max Tokens (1 až 4096+): Regulátor dĺžky odpovede
**Čo robí**: Určuje limit, ako dlhá môže byť odpoveď AI.
**Predstavte si tokeny ako približne ekvivalent slov** (asi 1 token = 0,75 slova v angličtine):
- **max_tokens=50**: Krátke a výstižné (ako SMS)
- **max_tokens=500**: Pekný odstavec alebo dva
- **max_tokens=2000**: Detailné vysvetlenie s príkladmi
```python
# Krátke, výstižné odpovede
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Explain JavaScript"}],
max_tokens=100 # Vyžaduje stručné vysvetlenie
)
# Podrobné, komplexné odpovede
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Explain JavaScript"}],
max_tokens=1500 # Umožňuje podrobné vysvetlenia s príkladmi
)
```
#### Top_p (0.0 až 1.0): Parameter zamerania
**Čo robí**: Riadi, ako veľmi sa AI drží pravdepodobných odpovedí.
**Predstavte si AI s obrovskou slovnou zásobou zoradenou podľa pravdepodobnosti použitia slov:**
- **top_p=0.1**: Zohľadňuje iba najlepších 10 % pravdepodobných slov (veľmi zamerané)
- **top_p=0.9**: Zohľadňuje 90 % možných slov (kreatívnejšie)
- **top_p=1.0**: Zohľadňuje všetky slová (maximálna rozmanitosť)
**Napríklad**: Ak sa pýtate "Obloha je zvyčajne..."
- **Nízke top_p**: Skoro určite "modrá"
- **Vysoké top_p**: Môže povedať "modrá", "zamračená", "rozľahlá", "mení sa", "krásna" atď.
### Dáme to dokopy: Kombinácie parametrov pre rôzne prípady použitia
```python
# Pre faktické, konzistentné odpovede (ako dokumentačný bot)
factual_params = {
"temperature": 0.2,
"max_tokens": 300,
"top_p": 0.3
}
# Pre pomoc pri tvorivom písaní
creative_params = {
"temperature": 1.1,
"max_tokens": 1000,
"top_p": 0.9
}
# Pre konverzačné, užitočné odpovede (vyvážené)
conversational_params = {
"temperature": 0.7,
"max_tokens": 500,
"top_p": 0.8
}
```
```mermaid
quadrantChart
title Matica optimalizácie parametrov AI
x-axis Nízka kreativita --> Vysoká kreativita
y-axis Krátka odozva --> Dlhá odozva
quadrant-1 Kreatívny obsah
quadrant-2 Podrobná analýza
quadrant-3 Rýchle fakty
quadrant-4 Konverzačná AI
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]
```
**Prečo tieto parametre záležia**: Rôzne aplikácie potrebujú rôzne typy odpovedí. Zákaznícky servis bot by mal byť konzistentný a faktický (nízka teplota), zatiaľ čo kreatívny asistent písania by mal byť nápaditý a rozmanitý (vysoká teplota). Pochopenie týchto parametrov vám dáva kontrolu nad osobnosťou a štýlom odpovedí 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))
```
**Pochopenie tejto vylepšenej funkcie:**
- **Prijíma** dva parametre: požiadavku používateľa a voliteľnú systémovú správu
- **Poskytuje** predvolenú systémovú správu pre všeobecné správanie asistenta
- **Používa** správne typové anotácie Pythonu pre lepšiu dokumentáciu kódu
- **Obsahuje** detailný docstring vysvetľujúci účel a parametre funkcie
- **Vracia** iba obsah odpovede, čo uľahčuje použitie v našom webovom API
- **Udržiava** rovnaké modelové parametre pre konzistentné správanie AI
### Magia systémových promptov: Programovanie osobnosti AI
Ak parametre riadia, ako AI premýšľa, systémové prompty riadia, kým AI myslí, že je. Toto je úprimne jedna z najzaujímavejších častí práce s AI – v podstate dávate AI kompletnú osobnosť, úroveň odbornosti a komunikačný štýl.
**Myslite na systémové prompty ako na obsadzovanie hercov do rôznych rolí**: Namiesto jednej generickej asistentky môžete vytvoriť špecializovaných expertov pre rôzne situácie. Potrebujete trpezlivého učiteľa? Kreatívneho brainstorming partnera? Rezolútneho obchodného poradcu? Stačí zmeniť systémový prompt!
#### Prečo sú systémové prompty také silné
Tu je fascinujúca časť: AI modely boli trénované na nespočítateľných konverzáciách, kde ľudia prijímajú rôzne roly a úrovne odbornosti. Keď dáte AI špecifickú rolu, je to ako prepnutie spínača, ktorý aktivuje všetky naučené vzory.
**Je to ako metóda herectva pre AI**: Povedzte hercovi "ste múdry starý profesor" a sledujte, ako automaticky prispôsobí držanie tela, slovnú zásobu a spôsoby. AI robí niečo pozoruhodne podobné s jazykovými vzormi.
#### Tvorba efektívnych systémových promptov: umenie a veda
**Anatómia skvelého systémového promptu:**
1. **Rola/Identita**: Kto je AI?
2. **Odbornosť**: Čo vie?
3. **Komunikačný štýl**: Ako hovorí?
4. **Konkrétne inštrukcie**: Na čo sa má zamerať?
```python
# ❌ Nejasný systémový príkaz
"You are helpful."
# ✅ Detailný, efektívny systémový príkaz
"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."
```
#### Príklady systémových promptov s kontextom
Pozrime sa, ako rôzne systémové prompty vytvárajú úplne odlišné osobnosti AI:
```python
# Príklad 1: Trpezlivý učiteľ
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.
"""
# Príklad 2: Kreatívny spolupracovník
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.
"""
# Príklad 3: Strategický obchodný poradca
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.
"""
```
#### Ako systémové prompty fungujú v akcii
Otestujme tú istú otázku s rôznymi systémovými promptmi a sledujme dramatické rozdiely:
**Otázka**: "Ako riešim autentifikáciu používateľov vo svojej webovej aplikácii?"
```python
# S otázkou od učiteľa:
teacher_response = call_llm(
"How do I handle user authentication in my web app?",
teacher_prompt
)
# Typická odpoveď: "Skvelá otázka! Poďme si rozobrať autentifikáciu na jednoduché kroky.
# Predstavte si to ako vrátnika v nočnom klube, ktorý kontroluje občianske preukazy..."
# S otázkou z podnikateľského prostredia:
business_response = call_llm(
"How do I handle user authentication in my web app?",
business_prompt
)
# Typická odpoveď: "Z strategického hľadiska je autentifikácia kľúčová pre dôveru používateľov
# a dodržiavanie predpisov. Nechajte ma načrtnúť rámec, ktorý zohľadňuje bezpečnosť,
# používateľskú skúsenosť a škálovateľnosť..."
```
#### Pokročilé techniky systémových promptov
**1. Nastavenie kontextu**: Poskytnite AI základné informácie
```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. Formátovanie výstupu**: Povedzte AI, ako štruktúrovať odpovede
```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. Nastavenie obmedzení**: Definujte, čo AI NESMIE robiť
```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.
"""
```
#### Prečo je to dôležité pre váš chatovací asistent
Pochopenie systémových promptov vám dáva neuveriteľnú moc vytvárať špecializovaných AI asistentov:
- **Chatbot zákazníckej podpory**: Užitočný, trpezlivý, oboznámený s pravidlami
- **Učebný lektor**: Povzbudzujúci, krok za krokom, overuje porozumenie
- **Tvorivý partner**: Fantazijný, stavia na nápadoch, pýta sa „čo keby?"
- **Technický expert**: Presný, detailný, so zameraním na bezpečnosť
**Kľúčový poznatok**: Nevoláte iba AI API – vytvárate vlastnú AI osobnosť, ktorá slúži vášmu konkrétnemu prípadu použitia. Práve to spôsobuje, že moderné AI aplikácie pôsobia prispôsobene a užitočne namiesto obecne.
### 🎯 Pedagogické zhodnotenie: Programovanie AI osobnosti
**Zastavte sa a zamyslite sa**: Práve ste sa naučili programovať AI osobnosti cez systémové prompty. Toto je základná zručnosť v modernom vývoji AI aplikácií.
**Rýchle sebahodnotenie**:
- Viete vysvetliť, čím sa systémové prompty líšia od bežných používateľských správ?
- Aký je rozdiel medzi parametrami temperature a top_p?
- Ako by ste vytvorili systémový prompt pre konkrétny prípad použitia (napr. koderského lektora)?
**Spojenie s reálnym svetom**: Techniky systémových promptov, ktoré ste sa naučili, sú používané v každej hlavnej AI aplikácii – od GitHub Copilot pomoci pri kódovaní až po konverzačné rozhranie ChatGPT. Ovládate rovnaké vzory, ktoré využívajú AI tímy v popredných technologických firmách.
**Výzva**: Ako by ste navrhli rôzne AI osobnosti pre rôzne typy používateľov (začiatočník vs expert)? Zvážte, ako môže ten istý základný AI model slúžiť rôznym publikám cez inžinierstvo promptov.
## Budovanie Web API s FastAPI: Vaše výkonné AI komunikačné centrum
Teraz si postavme backend, ktorý prepája váš frontend s AI službami. Použijeme FastAPI, moderný Python framework, ktorý exceluje vo vývoji API pre AI aplikácie.
FastAPI ponúka niekoľko výhod pre tento typ projektu: vstavaná podpora asynchrónnosti pre spracovanie paralelných požiadaviek, automatické generovanie dokumentácie API a vynikajúci výkon. Váš FastAPI server slúži ako sprostredkovateľ, ktorý prijíma požiadavky z frontendu, komunikuje s AI službami a vráti naformátované odpovede.
### Prečo FastAPI pre AI aplikácie?
Možno sa pýtate: „Nemôžem volať AI priamo z môjho frontend JavaScriptu?“ alebo „Prečo FastAPI namiesto Flask alebo Django?“ Skvelé otázky!
**Tu je dôvod, prečo je FastAPI ideálny pre to, čo stavame:**
- **Asynchrónny štandardne**: Vie súčasne spracovávať viac AI požiadaviek bez zaseknutia
- **Automatická dokumentácia**: Navštívte `/docs` a získate krásnu, interaktívnu API dokumentáciu zadarmo
- **Vstavaná validácia**: Odhalí chyby ešte pred ich spracovaním
- **Bleskovo rýchly**: Jeden z najrýchlejších Python frameworkov
- **Moderný Python**: Využíva všetky najnovšie Python funkcie
**A prečo vôbec potrebujeme backend:**
**Bezpečnosť**: Váš AI API kľúč je ako heslo – ak ho uložíte do frontend JavaScriptu, ktokoľvek, kto prezrie zdrojový kód vašej stránky, si ho môže ukradnúť a použiť vaše AI kredity. Backend udržiava citlivé údaje v bezpečí.
**Limitovanie počtu požiadaviek a kontrola**: Backend umožňuje kontrolovať, ako často môžu používatelia posielať požiadavky, implementovať autentifikáciu používateľov a pridávať logovanie na sledovanie používania.
**Spracovanie dát**: Môžete chcieť ukladať rozhovory, filtrovať nevhodný obsah alebo kombinovať viac AI služieb. Toto všetko beží na backendovej logike.
**Architektúra pripomína klient-server model:**
- **Frontend**: Vrstva používateľského rozhrania
- **Backend API**: Vrstva na spracovanie a smerovanie požiadaviek
- **AI služba**: Externý výpočtový zdroj a generátor odpovedí
- **Premenné prostredia**: Bezpečné ukladanie konfigurácie a údajov
### Pochopenie toku požiadavka a odpovede
Pozrime sa, čo sa stane, keď používateľ odošle správu:
```mermaid
sequenceDiagram
participant User as 👤 Používateľ
participant Frontend as 🌐 Frontend
participant API as 🔧 FastAPI Server
participant AI as 🤖 AI služba
User->>Frontend: Zadáva "Ahoj AI!"
Frontend->>API: POST /hello {"message": "Ahoj AI!"}
Note over API: Overuje požiadavku Pridáva systémový prompt
API->>AI: Posiela naformátovanú požiadavku
AI->>API: Vracia odpoveď AI
Note over API: Spracováva odpoveď Zaznamenáva konverzáciu
API->>Frontend: {"response": "Ahoj! Ako vám môžem pomôcť?"}
Frontend->>User: Zobrazuje správu AI
```
**Pochopenie každého kroku:**
1. **Interakcia používateľa**: Osoba zadá text do chatu
2. **Spracovanie frontendom**: JavaScript zachytí vstup a naformátuje ho do JSONu
3. **Validácia API**: FastAPI automaticky overí požiadavku pomocou Pydantic modelov
4. **Integrácia AI**: Backend pridá kontext (systémový prompt) a zavolá AI službu
5. **Spracovanie odpovede**: API prijme odpoveď od AI a môže ju upraviť podľa potreby
6. **Zobrazenie vo frontende**: JavaScript ukáže odpoveď v chatovom rozhraní
### Pochopenie architektúry API
```mermaid
sequenceDiagram
participant Frontend
participant FastAPI
participant AI Function
participant GitHub Models
Frontend->>FastAPI: POST /hello {"message": "Ahoj 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": "Ahoj! Ako vám môžem pomôcť?"}
```
```mermaid
flowchart TD
A[Zadanie používateľa] --> B[Frontend Validácia]
B --> C[HTTP POST Žiadosť]
C --> D[FastAPI Router]
D --> E[Pydantic Validácia]
E --> F[Volanie AI Funkcie]
F --> G[GitHub Models API]
G --> H[Spracovanie Odpovede]
H --> I[JSON Odpoveď]
I --> J[Aktualizácia Frontendu]
subgraph "Bezpečnostná Vrstva"
K[CORS Middleware]
L[Premenné Prostredia]
M[Spracovanie Chýb]
end
D --> K
F --> L
H --> M
```
### Vytvorenie FastAPI aplikácie
Postupne si vytvorme API. Vytvorte súbor `api.py` s nasledujúcim FastAPI kódom:
```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
# Konfigurácia logovania
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
# Vytvorte aplikáciu FastAPI
app = FastAPI(
title="AI Chat API",
description="A high-performance API for AI-powered chat applications",
version="1.0.0"
)
# Konfigurácia CORS
app.add_middleware(
CORSMiddleware,
allow_origins=["*"], # Konfigurujte vhodne pre produkciu
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
# Pydantic modely na validáciu požiadaviek/odpovedí
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:
# Extrahujte a overte správu
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]}...")
# Zavolajte AI službu (poznámka: call_llm by mala byť asynchrónna pre lepší výkon)
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)
```
**Pochopenie implementácie FastAPI:**
- **Importuje** FastAPI pre modernú webovú funkcionalitu a Pydantic pre validáciu dát
- **Vytvára** automatickú dokumentáciu API (dostupnú na `/docs` počas behu servera)
- **Povoľuje** CORS middleware, ktorý umožňuje požiadavky frontendu z iných zdrojov
- **Definuje** Pydantic modely pre automatickú validáciu požiadaviek/odpovedí a dokumentáciu
- **Používa** asynchrónne endpointy pre lepší výkon pri súbežných požiadavkách
- **Implementuje** správne HTTP status kódy a spracovanie chýb pomocou HTTPException
- **Zahŕňa** štruktúrované logovanie pre monitorovanie a ladenie
- **Poskytuje** health check endpoint pre monitorovanie stavu služby
**Kľúčové výhody FastAPI oproti tradičným frameworkom:**
- **Automatická validácia**: Pydantic modely zabezpečujú integritu dát pred ich spracovaním
- **Interaktívna dokumentácia**: Navštívte `/docs` pre auto-generovanú a testovateľnú API dokumentáciu
- **Typová bezpečnosť**: Python typové anotácie zabraňujú runtime chybám a zvyšujú kvalitu kódu
- **Podpora asynchrónnosti**: Spracovanie viacerých AI požiadaviek súčasne bez blokovania
- **Výkon**: Výrazne rýchlejšie spracovanie požiadaviek vhodné pre realtime aplikácie
### Pochopenie CORS: Ochranca bezpečnosti webu
CORS (Cross-Origin Resource Sharing) je ako ochranca na budove, ktorý kontroluje, či návštevníci môžu vstúpiť. Pozrime sa, prečo je to dôležité a ako to ovplyvňuje vašu aplikáciu.
#### Čo je CORS a prečo existuje?
**Problém**: Predstavte si, že by ktorákoľvek webstránka mohla robiť požiadavky na váš bankový web bez vášho súhlasu. To by bola bezpečnostná nočná mora! Browsery to predvolene zakazujú cez „Same-Origin Policy“.
**Same-Origin Policy**: Browsery povoľujú webstránkam robiť požiadavky len na rovnakú doménu, port a protokol, z ktorého boli načítané.
**Analógia z reálneho sveta**: Je to ako bezpečnostná služba v obytnom dome – predvolene môžu vstúpiť len obyvatelia (rovnaký origin). Ak chcete pustiť návštevu (iný origin), musíte ochranku explicitne upozorniť.
#### CORS vo vašom vývojovom prostredí
Počas vývoja váš frontend a backend bežia na rôznych portoch:
- Frontend: `http://localhost:3000` (alebo file:// ak otvárate HTML priamo)
- Backend: `http://localhost:5000`
Prehliadače ich teda považujú za „různe originy“, hoci sú na tom istom počítači!
```python
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI(__name__)
CORS(app) # Toto hovorí prehliadačom: "Je v poriadku, ak iné pôvody robia požiadavky na toto API"
```
**Čo CORS konfigurácia robí v praxi:**
- **Pridáva** špeciálne HTTP hlavičky do odpovedí API, ktoré prehliadaču hovoria „táto cross-origin požiadavka je povolená“
- **Spracováva** „preflight“ požiadavky (browsere niekedy najprv kontrolujú povolenia pred skutočnou požiadavkou)
- **Zabraňuje** nepríjemnej chybe „blocked by CORS policy“ vo vašej konzole prehliadača
#### CORS bezpečnosť: vývoj vs produkcia
```python
# 🚨 Vývoj: Povoliť VŠETKY pôvody (pohodlné, ale nebezpečné)
CORS(app)
# ✅ Produkcia: Povoliť iba konkrétnu doménu frontendu
CORS(app, origins=["https://yourdomain.com", "https://www.yourdomain.com"])
# 🔒 Pokročilé: Rôzne pôvody pre rôzne prostredia
if app.debug: # Režim vývoja
CORS(app, origins=["http://localhost:3000", "http://127.0.0.1:3000"])
else: # Režim produkcie
CORS(app, origins=["https://yourdomain.com"])
```
**Prečo je to dôležité**: Vo vývoji je `CORS(app)` ako nechať dvere otvorené – pohodlné, ale nie bezpečné. V produkcii chcete presne určiť, ktoré webstránky môžu komunikovať s vašim API.
#### Bežné scenáre a riešenia CORS
| Scenár | Problém | Riešenie |
|----------|---------|----------|
| **Lokálny vývoj** | Frontend nedosiahne backend | Pridajte CORSMiddleware do FastAPI |
| **GitHub Pages + Heroku** | Nasadený frontend nepristupuje k API | Pridajte URL GitHub Pages do CORS origins |
| **Vlastná doména** | CORS chyby v produkcii | Aktualizujte CORS origins podľa vašej domény |
| **Mobilná aplikácia** | Aplikácia nedosiahne webové API | Pridajte doménu aplikácie alebo opatrne použite `*` |
**Tip**: Môžete kontrolovať CORS hlavičky v Nástrojoch pre vývojárov vášho prehliadača v záložke Sieť. Hľadajte hlavičky ako `Access-Control-Allow-Origin` v odpovedi.
### Spracovanie chýb a validácia
Všimnite si, že naše API obsahuje správne spracovanie chýb:
```python
# Overiť, či sme prijali správu
if not message:
return jsonify({"error": "Message field is required"}), 400
```
**Kľúčové princípy validácie:**
- **Overuje** povinné polia ešte pred spracovaním požiadavky
- **Vracia** zmysluplné chybové správy v JSON formáte
- **Používa** správne HTTP status kódy (napr. 400 pre zlé požiadavky)
- **Poskytuje** jasnú spätnú väzbu, ktorá pomáha frontend vývojárom chyby odstrániť
## Nastavenie a spustenie vášho backendu
Teraz, keď máme AI integráciu a FastAPI server pripravené, poďme všetko spustiť. Proces nastavenia zahŕňa inštaláciu Python závislostí, konfiguráciu premenných prostredia a spustenie vývojového servera.
### Nastavenie Python prostredia
Nastavme si Python vývojové prostredie. Virtuálne prostredia sú ako Manhattan Project – každý projekt dostane vlastné izolované miesto so špecifickými nástrojmi a závislosťami, aby sa predišlo konfliktom medzi projektmi.
```bash
# Prejdite do svojho backend adresára
cd backend
# Vytvorte virtuálne prostredie (ako vytvorenie čistej miestnosti pre váš projekt)
python -m venv venv
# Aktivujte ho (Linux/Mac)
source ./venv/bin/activate
# Na Windows použite:
# venv\Scripts\activate
# Nainštalujte potrebné veci
pip install openai fastapi uvicorn python-dotenv
```
**Čo sme práve urobili:**
- **Vytvorili** vlastný malý Python bublinu, kde môžeme inštalovať balíčky bez ovplyvnenia ostatných projektov
- **Aktivovali** ju, aby náš terminál vedel používať toto konkrétne prostredie
- **Inštalovali** základné knižnice: OpenAI pre AI zázraky, FastAPI pre naše webové API, Uvicorn na spustenie servera, a python-dotenv pre bezpečné spravovanie tajomstiev
**Vysvetlenie hlavných závislostí:**
- **FastAPI**: Moderný, rýchly webový framework s automatickou dokumentáciou API
- **Uvicorn**: Bleskurýchly ASGI server spúšťajúci FastAPI aplikácie
- **OpenAI**: Oficiálna knižnica pre GitHub modely a integráciu OpenAI API
- **python-dotenv**: Bezpečné načítavanie premenných prostredia z .env súborov
### Konfigurácia prostredia: Ako udržať tajomstvá v bezpečí
Predtým, než spustíme API, musíme si povedať jedno z najdôležitejších pravidiel webového vývoja: ako naozaj držať vaše tajomstvá tajnými. Premenné prostredia sú ako bezpečný trezor, ku ktorému má prístup iba vaša aplikácia.
#### Čo sú premenné prostredia?
**Predstavte si ich ako bezpečnostnú schránku** – vložíte tam svoje cennosti a len vy (a vaša aplikácia) máte kľúč. Namiesto písania citlivých údajov priamo v kóde (kde ich môže každý vidieť), ich bezpečne ukladáte do prostredia.
**Rozdiel je tento:**
- **Zlý prístup**: Napísať si heslo na lístok a prilepiť ho na monitor
- **Správny prístup**: Uchovávať heslo v bezpečnom manažéri hesiel, ku ktorému máte prístup len vy
#### Prečo sú premenné prostredia dôležité
```python
# 🚨 NIKDY TO NEROBTE - API kľúč viditeľný pre všetkých
client = OpenAI(
api_key="ghp_1234567890abcdef...", # Každý ho môže ukradnúť!
base_url="https://models.github.ai/inference"
)
# ✅ ROBTE TO - API kľúč bezpečne uložený
client = OpenAI(
api_key=os.environ["GITHUB_TOKEN"], # K tomu má prístup iba vaša aplikácia
base_url="https://models.github.ai/inference"
)
```
**Čo sa stane, ak natvrdo zadáte tajomstvá do kódu:**
1. **Expozícia v riadení verzií**: Každý s prístupom ku Git repozitáru vidí váš API kľúč
2. **Verejné repozitáre**: Ak ho pushnete na GitHub, kľúč je viditeľný pre celý internet
3. **Zdieľanie s tímom**: Iní vývojári získajú prístup k vášmu osobnému API kľúču
4. **Bezpečnostné incidenty**: Ak niekto ukradne váš API kľúč, môže míňať vaše AI kredity
#### Nastavenie súboru prostredia
Vytvorte `.env` súbor v adresári backendu. Tento súbor bezpečne uloží vaše tajomstvá lokálne:
```bash
# .env súbor - Tento by sa NIKDY nemal commitovať do Gitu
GITHUB_TOKEN=your_github_personal_access_token_here
FASTAPI_DEBUG=True
ENVIRONMENT=development
```
**Ako funguje súbor .env:**
- **Jeden kľúč a jedna hodnota na riadok** vo formáte `KEY=value`
- **Bez medzier** okolo rovná sa
- **Zväčša bez úvodzoviek** okolo hodnôt
- **Komentáre** začínajú znakom `#`
#### Vytvorenie osobného prístupového tokenu GitHub
Váš GitHub token je špeciálne heslo, ktoré umožňuje vašej aplikácii používať AI služby GitHubu:
**Postupný návod na vytvorenie tokenu:**
1. **Prejdite do GitHub nastavení** → Developer settings → Personal access tokens → Tokens (classic)
2. **Kliknite na "Generate new token (classic)"**
3. **Nastavte platnosť** (30 dní na testovanie, dlhšie pre produkciu)
4. **Vyberte oprávnenia**: Zaškrtnite „repo“ a ďalšie, ktoré potrebujete
5. **Vygenerujte token** a hneď si ho skopírujte (už ho neuvidíte!)
6. **Vložte ho do vášho .env súboru**
```bash
# Príklad toho, ako vyzerá váš token (toto je falošné!)
GITHUB_TOKEN=ghp_1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R
```
#### Načítanie premenných prostredia v Pythone
```python
import os
from dotenv import load_dotenv
# Načítajte premenné prostredia zo súboru .env
load_dotenv()
# Teraz k nim môžete bezpečne pristupovať
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"
)
```
**Čo tento kód robí:**
- **Načíta** váš .env súbor a sprístupní premenné Pythonu
- **Skontroluje**, či požadovaný token existuje (dobré spracovanie chýb!)
- **Vyrukuje** s jasnou chybou, ak chýba token
- **Bezpečne používa** token bez jeho zverejnenia v kóde
#### Git bezpečnosť: Súbor .gitignore
Váš `.gitignore` súbor hovorí Gitu, ktoré súbory nikdy nesledovať alebo nahrávať:
```bash
# .gitignore - Pridajte tieto riadky
.env
*.env
.env.local
.env.production
__pycache__/
venv/
.vscode/
```
**Prečo je to kľúčové**: Keď pridáte `.env` do `.gitignore`, Git ignoruje váš .env súbor, čím zabraňuje náhodnému uploadu tajomstiev na GitHub.
#### Rôzne prostredia, rôzne tajomstvá
Profesionálne aplikácie používajú rozdielne API kľúče pre rôzne prostredia:
```bash
# .env.vývoj
GITHUB_TOKEN=your_development_token
DEBUG=True
# .env.produkcia
GITHUB_TOKEN=your_production_token
DEBUG=False
```
**Prečo to má význam**: Nechcete, aby vaše vývojové experimenty ovplyvnili produkčnú AI kvótu a chcete rôzne bezpečnostné úrovne pre rôzne prostredia.
### Spustenie vývojového servera: Oživenie vášho FastAPI
Teraz prichádza vzrušujúci moment – spustenie vývojového servera FastAPI a sledovanie, ako vaša AI integrácia ožíva! FastAPI používa Uvicorn, bleskovo rýchly ASGI server, ktorý je špeciálne navrhnutý pre asynchrónne Python aplikácie.
#### Pochopenie procesu spustenia servera FastAPI
```bash
# Metóda 1: Priame vykonanie v Pythone (zahŕňa automatické obnovenie)
python api.py
# Metóda 2: Priame použitie Uvicornu (viac kontroly)
uvicorn api:app --host 0.0.0.0 --port 5000 --reload
```
Keď spustíte tento príkaz, za scénou sa deje toto:
**1. Python načíta vašu FastAPI aplikáciu**:
- Importuje všetky požadované knižnice (FastAPI, Pydantic, OpenAI atď.)
- Načíta premenné prostredia z vášho `.env` súboru
- Vytvorí inštanciu FastAPI aplikácie s automatickou dokumentáciou
**2. Uvicorn konfiguruje ASGI server**:
- Pripája sa na port 5000 s asynchrónnym spracovaním požiadaviek
- Nastaví smerovanie požiadaviek s automatickou validáciou
- Povolenie hot reload pre vývoj (reštart pri zmene súborov)
- Generuje interaktívnu API dokumentáciu
**3. Server začne počúvať**:
- Vo vašom termináli sa zobrazí: `INFO: Uvicorn running on http://0.0.0.0:5000`
- Server zvládne viacero súčasných AI požiadaviek
- Vaše API je pripravené s automatickou dokumentáciou na `http://localhost:5000/docs`
#### Čo by ste mali vidieť, keď všetko funguje
```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.
```
**Pochopenie výstupu FastAPI:**
- **Bude sledovať zmeny**: Auto-reload povolený pre vývoj
- **Uvicorn beží**: Výkonný ASGI server je aktívny
- **Spustený proces reloadera**: Sledovač súborov pre automatické reštarty
- **Spustenie aplikácie dokončené**: FastAPI app úspešne inicializovaná
- **Interaktívna dokumentácia dostupná**: Navštívte `/docs` pre automatickú API dokumentáciu
#### Testovanie FastAPI: Viaceré výkonné prístupy
FastAPI poskytuje niekoľko pohodlných spôsobov, ako otestovať vaše API, vrátane automatickej interaktívnej dokumentácie:
**Metóda 1: Interaktívna API dokumentácia (odporúčaná)**
1. Otvorte prehliadač a choďte na `http://localhost:5000/docs`
2. Uvidíte Swagger UI so všetkými zdokumentovanými koncovými bodmi
3. Kliknite na `/hello` → "Try it out" → Zadajte testovaciu správu → "Execute"
4. Odpoveď uvidíte priamo v prehliadači s správnym formátovaním
**Metóda 2: Základný test v prehliadači**
1. Choďte na `http://localhost:5000` pre koreňový endpoint
2. Choďte na `http://localhost:5000/health` pre kontrolu stavu servera
3. Týmto potvrdíte, že váš FastAPI server funguje správne
**Metóda 2: Test z príkazového riadku (pokročilé)**
```bash
# Testujte s curl (ak je k dispozícii)
curl -X POST http://localhost:5000/hello \
-H "Content-Type: application/json" \
-d '{"message": "Hello AI!"}'
# Očakávaná odpoveď:
# {"response": "Ahoj! Som tvoj AI asistent. Ako ti môžem dnes pomôcť?"}
```
**Metóda 3: Python testovací skript**
```python
# test_api.py - Vytvorte tento súbor na otestovanie vášho API
import requests
import json
# Otestujte API koncový bod
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)
```
#### Riešenie bežných problémov so spustením
| Chybové hlásenie | Čo to znamená | Ako to opraviť |
|------------------|---------------|---------------|
| `ModuleNotFoundError: No module named 'fastapi'` | FastAPI nie je nainštalované | Spustite `pip install fastapi uvicorn` vo vašom virtuálnom prostredí |
| `ModuleNotFoundError: No module named 'uvicorn'` | ASGI server nie je nainštalovaný | Spustite `pip install uvicorn` vo vašom virtuálnom prostredí |
| `KeyError: 'GITHUB_TOKEN'` | Premenná prostredia chýba | Skontrolujte svoj `.env` súbor a volanie `load_dotenv()` |
| `Address already in use` | Port 5000 je obsadený | Ukončite iné procesy používajúce port 5000 alebo zmeňte port |
| `ValidationError` | Dáta požiadavky nezodpovedajú Pydantic modelu | Skontrolujte, či formát požiadavky zodpovedá očakávanej schéme |
| `HTTPException 422` | Entita sa nedá spracovať | Validácia požiadavky zlyhala, skontrolujte správny formát v `/docs` |
| `OpenAI API error` | Overenie AI služby zlyhalo | Overte, či váš GitHub token je správny a má potrebné oprávnenia |
#### Najlepšie praktiky pre vývoj
**Hot Reloading**: FastAPI s Uvicorn umožňuje automatický reload pri uložení zmien v Python súboroch. To znamená, že môžete meniť kód a okamžite testovať bez manuálneho reštartu.
```python
# Explicitne povoliť horúce preťaženie
if __name__ == "__main__":
app.run(host="0.0.0.0", port=5000, debug=True) # debug=True povoľuje horúce preťaženie
```
**Logging pre vývoj**: Pridajte logovanie, aby ste rozumeli tomu, čo sa deje:
```python
import logging
# Nastaviť protokolovanie
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
```
**Prečo je logging užitočný**: Počas vývoja presne vidíte, aké požiadavky prichádzajú, aké odpovede AI vracia a kde sa vyskytli chyby. To urýchľuje ladenie.
### Konfigurácia pre GitHub Codespaces: Cloudový vývoj jednoducho
GitHub Codespaces je ako mať výkonný vývojový počítač v cloude, ku ktorému pristupujete z ľubovoľného prehliadača. Ak pracujete v Codespaces, je potrebné vykonať niekoľko ďalších krokov, aby bol váš backend prístupný fronendovej časti.
#### Pochopenie sieťovania v Codespaces
V lokálnom vývojovom prostredí všetko beží na rovnakom počítači:
- Backend: `http://localhost:5000`
- Frontend: `http://localhost:3000` (alebo file://)
V Codespaces vaše prostredie beží na serveroch GitHubu, preto "localhost" znamená niečo iné. GitHub automaticky vytvára verejné URL pre vaše služby, ale musíte ich správne nakonfigurovať.
#### Konfigurácia Codespaces krok za krokom
**1. Spustite svoj backend server**:
```bash
cd backend
python api.py
```
Uvidíte známe spúšťacie hlásenie FastAPI/Uvicorn, ale všimnite si, že beží vo vnútri prostredia Codespace.
**2. Konfigurujte viditeľnosť portu**:
- Nájdite kartu "Ports" v spodnom paneli VS Code
- Nájdite port 5000 v zozname
- Kliknite pravým tlačidlom na port 5000
- Vyberte "Port Visibility" → "Public"
**Prečo ho sprístupniť?** Štandardne sú porty v Codespace súkromné (prístupné len vám). Verejný port umožní, aby sa váš frontend (bežiaci v prehliadači) mohol spojiť s backendom.
**3. Získajte verejnú URL adresu**:
Po sprístupnení portu uvidíte URL podobné tejto:
```
https://your-codespace-name-5000.app.github.dev
```
**4. Aktualizujte konfiguráciu frontendu**:
```javascript
// Vo vašom frontend app.js aktualizujte BASE_URL:
this.BASE_URL = "https://your-codespace-name-5000.app.github.dev";
```
#### Pochopenie URL adries Codespace
URL adresy v Codespace majú predvídateľný vzor:
```
https://[codespace-name]-[port].app.github.dev
```
**Rozdelenie:**
- `codespace-name`: Jedinečný identifikátor vášho Codespace (často obsahuje vaše používateľské meno)
- `port`: Číslo portu, na ktorom beží služba (5000 pre našu FastAPI aplikáciu)
- `app.github.dev`: Doména GitHubu pre aplikácie Codespace
#### Testovanie nastavenia Codespace
**1. Otestujte backend priamo**:
Otvorte vašu verejnú URL v novom prehliadači. Mali by ste vidieť:
```
Welcome to the AI Chat API. Send POST requests to /hello with JSON payload containing 'message' field.
```
**2. Testujte pomocou developerských nástrojov prehliadača**:
```javascript
// Otvorte konzolu prehliadača a otestujte svoje API
fetch('https://your-codespace-name-5000.app.github.dev/hello', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({message: 'Hello from Codespaces!'})
})
.then(response => response.json())
.then(data => console.log(data));
```
#### Codespaces vs lokálny vývoj
| Aspekt | Lokálny vývoj | GitHub Codespaces |
|--------|--------------|-------------------|
| **Čas nastavenia** | Dlhší (inštalácia Pythonu, závislostí) | Okamžitý (predkonfigurované prostredie) |
| **Prístup k URL** | `http://localhost:5000` | `https://xyz-5000.app.github.dev` |
| **Konfigurácia portov** | Automatická | Manuálna (sprístupniť porty) |
| **Ukladanie súborov** | Lokálny počítač | GitHub repozitár |
| **Spolupráca** | Ťažké zdieľať prostredie | Ľahké zdieľať odkaz na Codespace |
| **Závislosť od internetu** | Len pre AI API volania | Nutná pre všetko |
#### Tipy pre vývoj v Codespaces
**Premenné prostredia v Codespaces**:
Váš `.env` súbor funguje rovnako v Codespaces, ale premenné prostredia môžete nastaviť aj priamo v Codespace:
```bash
# Nastavte premennú prostredia pre aktuálnu reláciu
export GITHUB_TOKEN="your_token_here"
# Alebo pridajte do vášho .bashrc pre trvalosť
echo 'export GITHUB_TOKEN="your_token_here"' >> ~/.bashrc
```
**Správa portov**:
- Codespaces automaticky rozpozná, keď aplikácia začne počúvať na porte
- Môžete presmerovať viacero portov súčasne (užitočné pri pridávaní databázy)
- Porty zostanú prístupné, kým váš Codespace beží
**Vývojový pracovný tok**:
1. Robte zmeny v kóde vo VS Code
2. FastAPI sa automaticky preloží (vďaka reload módu Uvicornu)
3. Okamžite testujte zmeny cez verejnú URL
4. Po ukončení uložte zmeny a pushnite
> 💡 **Tip**: Počas vývoja si uložte záložku s URL adresou backendu v Codespace. Pretože názvy Codespace sú stabilné, táto URL sa nezmení, pokiaľ používate ten istý Codespace.
## Vytvorenie frontendového chatového rozhrania: Kde sa stretávajú ľudia s AI
Teraz postavíme používateľské rozhranie – časť, ktorá určuje, ako ľudia interagujú s vaším AI asistentom. Podobne ako dizajn pôvodného iPhonu, kladieme dôraz na to, aby bola zložitá technológia intuitívna a prirodzená na používanie.
### Pochopenie modernej frontend architektúry
Naše chatové rozhranie bude to, čomu hovoríme "Single Page Application" alebo SPA. Namiesto starého modelu, kde každé kliknutie načítavalo novú stránku, naša appka sa aktualizuje plynulo a okamžite:
**Staré weby**: Ako čítanie fyzickej knihy – listujete celými novými stránkami
**Náš chat**: Ako používanie telefónu – všetko plynie a aktualizuje sa hladko a bez prerušenia
```mermaid
graph TD
A[Používateľ napíše správu] --> B[JavaScript zachytí vstup]
B --> C[Overiť a naformátovať dáta]
C --> D[Odoslať do backend API]
D --> E[Zobraziť stav načítania]
E --> F[Prijať odpoveď AI]
F --> G[Aktualizovať chat rozhranie]
G --> H[Pripravené na ďalšiu správu]
```
```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 : manipuluje
ChatApp --> FastAPI : posiela požiadavky
```
### Tri piliere frontendového vývoja
Každá frontendová aplikácia – od jednoduchých stránok až po zložité appky ako Discord alebo Slack – je postavená na troch základných technológiách. Považujte ich za základ všetkého, čo na webe vidíte a s čím interagujete:
**HTML (Štruktúra)**: To je váš základ
- Určuje, ktoré prvky existujú (tlačidlá, textové polia, kontajnery)
- Dáva význam obsahu (toto je hlavička, toto je formulár, atď.)
- Vytvára základnú štruktúru, na ktorú sa stavia všetko ostatné
**CSS (Prezentácia)**: To je váš interiérový dizajnér
- Robí všetko pekným (farby, fonty, rozloženia)
- Zabezpečuje responzívnosť na rôznych zariadeniach (mobil, notebook, tablet)
- Vytvára plynulé animácie a vizuálnu spätnú väzbu
**JavaScript (Správanie)**: To je váš mozog
- Reaguje na akcie používateľov (kliknutia, písanie, rolovanie)
- Komunikuje s backendom a aktualizuje stránku
- Robí všetko interaktívnym a dynamickým
**Predstavte si to ako architektonický dizajn:**
- **HTML**: Štrukturálny plán (definovanie priestorov a vzťahov)
- **CSS**: Estetický a environmentálny dizajn (vizuálny štýl a používateľský zážitok)
- **JavaScript**: Mechanické systémy (funkcionalita a interaktivita)
### Prečo je dôležitá moderná JavaScript architektúra
Naša chatová aplikácia bude používať moderné JavaScriptové vzory, ktoré uvidíte v profesionálnych aplikáciách. Pochopenie týchto konceptov vám pomôže ako developerovi rásť:
**Architektúra založená na triedach**: Organizujeme kód do tried, čo je ako vytváranie plánov pre objekty
**Async/Await**: Moderný spôsob spracovania operácií trvajúcich nejaký čas (napríklad volania API)
**Programovanie riadené udalosťami**: Aplikácia reaguje na používateľské akcie (kliknutia, stlačenia kláves) namiesto stáleho cyklu
**Manipulácia s DOM**: Dynamická aktualizácia obsahu stránky podľa používateľských akcií a odpovedí API
### Nastavenie projektovej štruktúry
Vytvorte frontendový adresár s touto organizovanou štruktúrou:
```text
frontend/
├── index.html # Main HTML structure
├── app.js # JavaScript functionality
└── styles.css # Visual styling
```
**Pochopenie architektúry:**
- **Oddelzuje** zodpovednosti medzi štruktúru (HTML), správanie (JavaScript) a prezentáciu (CSS)
- **Udržiava** jednoduchú štruktúru súborov, ktorú je ľahké prehliadať a meniť
- **Nasleduje** najlepšie webové praktiky pre organizáciu a údržbu
### Budovanie HTML základu: Semantická štruktúra pre prístupnosť
Začnime s HTML štruktúrou. Moderný webový vývoj zdôrazňuje "semantický HTML" – používanie HTML elementov, ktoré jasne opisujú svoj účel, nie len vzhľad. To robí vašu aplikáciu prístupnou pre čítačky obrazovky, vyhľadávače a iné nástroje.
**Prečo je semantický HTML dôležitý**: Predstavte si, že opisujete svoju chatovú appku niekomu cez telefón. Povedali by ste: "je tam hlavička s titulom, hlavná plocha, kde prebiehajú konverzácie, a formulár v spodnej časti, kde sa píšu správy." Semantický HTML používa elementy, ktoré zodpovedajú tomuto prirodzenému opisu.
Vytvorte `index.html` s touto premyslenou štruktúrou:
```html
AI Chat Assistant
AI Chat Assistant
Ask me anything!
```
**Pochopenie jednotlivých HTML prvkov a ich účelu:**
#### Štruktúra dokumentu
- **``**: Oznamuje prehliadaču, že ide o moderný HTML5 dokument
- **``**: Určuje jazyk stránky pre čítačky obrazovky a preklady
- **``**: Zaisťuje správne kódovanie znakov pre medzinárodný text
- **``**: Umožňuje responzívny dizajn pre mobily riadením zoomu a mierky
#### Semantické elementy
- **``**: Jasne označuje hornú časť s titulom a popisom
- **``**: Určuje primárnu obsahovú časť (kde sa zobrazujú konverzácie)
- **`