# Vytvořte chat asistenta s AI
Pamatujete, jak v Star Treku posádka nenuceně mluvila s počítačem lodi, kladla mu složité otázky a dostávala promyšlené odpovědi? To, co v 60. letech vypadalo jako čistá science fiction, je dnes něco, co můžete vytvořit pomocí webových technologií, které už znáte.
V této lekci vytvoříme AI chat asistenta pomocí HTML, CSS, JavaScriptu a nějaké backendové integrace. Objevíte, jak ty samé dovednosti, které se učíte, mohou spojit s výkonnými AI službami, které dokážou rozumět kontextu a generovat smysluplné odpovědi.
Představte si AI jako přístup k obrovské knihovně, která nejenže najde informace, ale také je syntetizuje do koherentních odpovědí přizpůsobených vašim konkrétním otázkám. Místo prohledávání tisíců stránek dostanete přímé, kontextuální odpovědi.
Integrace probíhá přes známé webové technologie, které spolupracují. HTML vytváří rozhraní chatu, CSS se stará o vizuální design, JavaScript řídí uživatelské interakce a backendové API spojuje vše s AI službami. Je to podobné jako různé sekce orchestru, které společně vytvářejí symfonii.
V podstatě stavíme most mezi přirozenou lidskou komunikací a strojovým zpracováním. Naučíte se jak technickou implementaci integrace AI služeb, tak i návrhové vzory, které činí interakce intuitivními.
Na konci této lekce vám integrace AI bude připadat méně jako záhadný proces a spíše jako další API, se kterým můžete pracovat. Pochopíte základní vzory, které pohánějí aplikace jako ChatGPT a Claude, za použití stejných principů webového vývoje, které se učíte.
## ⚡ Co můžete udělat během příštích 5 minut
**Rychlý start pro zaneprázdněné vývojáře**
```mermaid
flowchart LR
A[⚡ 5 minut] --> B[Získat GitHub token]
B --> C[Testovat AI hřiště]
C --> D[Zkopírovat Python kód]
D --> E[Zobrazit odpovědi AI]
```
- **Minuta 1**: Navštivte [GitHub Models Playground](https://github.com/marketplace/models/azure-openai/gpt-4o-mini/playground) a vytvořte osobní přístupový token
- **Minuta 2**: Otestujte AI interakce přímo v rozhraní playgroundu
- **Minuta 3**: Klikněte na záložku "Code" a zkopírujte Python ukázku
- **Minuta 4**: Spusťte kód lokálně s vaším tokenem: `GITHUB_TOKEN=your_token python test.py`
- **Minuta 5**: Sledujte, jak se vygeneruje vaše první AI odpověď z vlastního kódu
**Rychlý 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)
```
**Proč je to důležité**: Za 5 minut zažijete kouzlo programové AI interakce. To představuje základní stavební prvek, který pohání každou AI aplikaci, kterou používáte.
Takto bude vypadat váš hotový projekt:
## 🗺️ Vaše cesta za vývojem AI aplikací
```mermaid
journey
title Od webového vývoje k AI integraci
section Porozumění základům AI
Objevte koncepty generativní AI: 4: You
Prozkoumejte platformu GitHub Models: 6: You
Ovládněte parametry a výzvy AI: 8: You
section Integrace backendu
Vytvořte Python API server: 5: You
Implementujte volání AI funkcí: 7: You
Zpracovávejte asynchronní operace: 8: You
section Vývoj frontendu
Vytvořte moderní chatovací rozhraní: 6: You
Ovládněte interakce v reálném čase: 8: You
Vytvořte responzivní uživatelskou zkušenost: 9: You
section Profesionální aplikace
Nasazení kompletního AI systému: 7: You
Optimalizujte vzory výkonu: 8: You
Vytvořte aplikaci připravenou pro produkci: 9: You
```
**Cíl vaší cesty**: Na konci této lekce budete mít vytvořenou kompletní aplikaci s podporou AI, která používá stejné technologie a vzory, jež pohánějí moderní AI asistenty jako ChatGPT, Claude a Google Bard.
## Pochopení AI: Od záhady k mistrovství
Než se ponoříme do kódu, pojďme si vysvětlit, s čím pracujeme. Pokud jste dříve používali API, znáte základní vzor: pošlete požadavek, obdržíte odpověď.
AI API fungují podobně, ale místo získávání předem uložených dat z databáze generují nové odpovědi na základě vzorů naučených z obrovského množství textů. Představte si to jako rozdíl mezi knihovní katalogovou službou a znalým knihovníkem, který dokáže syntetizovat informace z různých zdrojů.
### Co je vlastně "Generativní AI"?
Představte si, jak Rosettská deska umožnila vědcům porozumět egyptským hieroglyfům tím, že našla vzory mezi známými a neznámými jazyky. AI modely fungují podobně – hledají vzory v obrovských množstvích textu, aby pochopily, jak jazyk funguje, a pak tyto vzory používají k vytváření vhodných odpovědí na nové otázky.
**Tady je jednoduché srovnání:**
- **Tradiční databáze**: Jako kdybyste žádali o svůj rodný list – pokaždé dostanete stejný dokument
- **Vyhledávač**: Jako poradit se s knihovníkem o knihách o kočkách – ukáže vám, co je k dispozici
- **Generativní AI**: Jako zeptat se znalého přítele na kočky – řekne vám zajímavé věci svými slovy, přizpůsobené tomu, co chcete vědět
```mermaid
graph LR
A[Vaše otázka] --> B[AI model]
B --> C[Rozpoznávání vzorů]
C --> D[Generování obsahu]
D --> E[Kontextová odpověď]
F[Tréninková data Knihy, články, web] --> B
```
### Jak se AI modely učí (jednoduchá verze)
AI modely se učí díky expozici obrovským datasetům obsahujícím texty z knih, článků a rozhovorů. Během tohoto procesu identifikují vzory v:
- Jak jsou myšlenky strukturované v psané komunikaci
- Která slova se často objevují společně
- Jak typicky probíhají rozhovory
- Kontextuální rozdíly mezi formální a neformální komunikací
**Je to podobné jako archeologové, kteří rozlušťují starověké jazyky**: analyzují tisíce příkladů, aby pochopili gramatiku, slovní zásobu a kulturní kontext, až se nakonec naučí interpretovat nové texty pomocí těchto vzorů.
### Proč GitHub Models?
Používáme GitHub Models z praktického důvodu – umožňuje nám přístup k AI na úrovni podniku bez nutnosti nastavovat vlastní AI infrastrukturu (a věřte, teď to rozhodně nechcete dělat!). Je to jako používat počasovou API místo pokusu předpovídat počasí sami zaváděním stanic všude.
Je to v podstatě "AI jako služba" a nejlepší na tom je, že začít je zdarma, takže můžete experimentovat bez obav z vysokých nákladů.
```mermaid
graph LR
A[Frontend Chat UI] --> B[Váš Backend API]
B --> C[GitHub Modely API]
C --> D[Zpracování AI Modelu]
D --> C
C --> B
B --> A
```
Použijeme GitHub Models pro naši backendovou integraci, která poskytuje přístup k profesionálním AI schopnostem přes vývojářsky přívětivé rozhraní. [GitHub Models Playground](https://github.com/marketplace/models/azure-openai/gpt-4o-mini/playground) slouží jako testovací prostředí, kde můžete experimentovat s různými AI modely a pochopit jejich schopnosti před implementací do kódu.
## 🧠 Ekosystém vývoje AI aplikací
```mermaid
mindmap
root((Vývoj AI))
Understanding AI
Generative Models
Rozpoznávání vzorů
Generování obsahu
Porozumění kontextu
Syntéza odpovědí
AI Parameters
Řízení teploty
Limity tokenů
Filtrování Top-p
Systémové výzvy
Backend Architecture
API Integration
Modely GitHubu
Autentizace
Zpracování požadavků
Správa chyb
Python Infrastructure
Rámec FastAPI
Asynchronní operace
Ochrana prostředí
Konfigurace CORS
Frontend Experience
Chat Interface
Aktualizace v reálném čase
Historie zpráv
Zpětná vazba uživatelů
Stav načítání
Modern Web Tech
Třídy ES6
Async/Await
Manipulace s DOM
Zpracování událostí
Professional Patterns
Security Best Practices
Správa tokenů
Validace vstupů
Prevence XSS
Hraniční kontroly chyb
Production Readiness
Optimalizace výkonu
Responzivní design
Přístupnost
Testovací strategie
```
**Základní princip**: Vývoj AI aplikací kombinuje tradiční webové dovednosti s integrací AI služeb, vytvářející inteligentní aplikace, které působí přirozeně a reagují na uživatele.
**Co dělá playground tak užitečným:**
- **Vyzkoušejte** různé AI modely jako GPT-4o-mini, Claude a další (vše zdarma!)
- **Otestujte** své nápady a prompt předtím, než začnete psát kód
- **Získejte** připravené ukázky kódu ve svém oblíbeném programovacím jazyce
- **Nastavte** parametry jako úroveň kreativity a délku odpovědi a pozorujte dopad na výstup
Jakmile si trochu pohrajete, stačí kliknout na záložku "Code" a vybrat programovací jazyk, abyste získali implementační kód, který budete potřebovat.
## Nastavení Python backendové integrace
Nyní implementujeme AI integraci za pomoci Pythonu. Python je skvělý pro AI aplikace díky své jednoduché syntaxi a silným knihovnám. Začneme kódem z playgroundu GitHub Models a pak jej přepracujeme do znovupoužitelné, produkčně připravené funkce.
### Pochopení základní implementace
Když z playgroundu stáhnete Python kód, dostanete něco, co vypadá takto. Nebojte se, pokud to ze začátku působí složitě – pojďme si to rozebrat kousek po kousku:
```python
"""Run this model in Python
> pip install openai
"""
import os
from openai import OpenAI
# Pro autentizaci u modelu budete muset v nastavení GitHubu vygenerovat osobní přístupový token (PAT).
# Vytvořte svůj PAT token podle pokynů zde: 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)
```
**Co se v kódu děje:**
- **Importujeme** nástroje, které potřebujeme: `os` pro čtení proměnných prostředí a `OpenAI` pro komunikaci s AI
- **Nastavujeme** klienta OpenAI, aby směřoval na AI servery GitHubu místo přímo na OpenAI
- **Autentizujeme** se pomocí speciálního GitHub tokenu (více o tom za chvíli!)
- **Strukturalizujeme** náš rozhovor s různými "rolemi" – představte si to jako nastavení scény pro divadelní hru
- **Posíláme** náš požadavek AI s nějakými doladěnými parametry
- **Vytahujeme** skutečný text odpovědi ze všech dat, která se vrátí
### Pochopení rolí zpráv: rámec AI konverzace
AI konverzace používají specifickou strukturu s různými "rolemi", které mají určité účely:
```python
messages=[
{
"role": "system",
"content": "You are a helpful assistant who explains things simply."
},
{
"role": "user",
"content": "What is machine learning?"
}
]
```
**Představte si to jako režii hry:**
- **Role systému**: Jako režijní pokyny pro herce – říká AI, jak se chovat, jakou mít osobnost a jak odpovídat
- **Role uživatele**: Skutečná otázka nebo zpráva od osoby, která vaši aplikaci používá
- **Role asistenta**: AI odpověď (tu neodesíláte, ale objevuje se v historii konverzace)
**Analogie z reálného života**: Představte si, že představujete kamaráda na večírku:
- **Systémová zpráva**: „Tohle je moje kamarádka Sarah, je doktorka, která výborně vysvětluje lékařské pojmy jednoduše“
- **Uživatelská zpráva**: „Můžeš mi vysvětlit, jak fungují vakcíny?“
- **Asistentova odpověď**: Sarah odpovídá jako přátelská doktorka, ne jako právník nebo kuchař
### Pochopení AI parametrů: doladění chování odpovědi
Číselné parametry v AI API volání řídí, jak model generuje odpovědi. Tato nastavení vám umožňují přizpůsobit chování AI pro různé účely:
#### Teplota (0.0 až 2.0): Regulátor kreativity
**Co dělá**: Řídí, jak kreativní nebo předvídatelné budou odpovědi AI.
**Představte si to jako úroveň improvizace jazzového hudebníka:**
- **Teplota = 0,1**: Hraje úplně stejnou melodii pokaždé (velmi předvídatelné)
- **Teplota = 0,7**: Přidává pár vhodných variací, ale stále je rozpoznatelný (vyvážená kreativita)
- **Teplota = 1,5**: Plně experimentální jazz s neočekávanými obraty (velmi nepředvídatelné)
```python
# Velmi předvídatelné odpovědi (dobré pro faktické otázky)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "What is 2+2?"}],
temperature=0.1 # Téměř vždy odpoví „4“
)
# Kreativní odpovědi (dobré pro brainstorming)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Write a creative story opening"}],
temperature=1.2 # Vygeneruje jedinečné, nečekané příběhy
)
```
#### Max Tokens (1 až 4096+): Kontrola délky odpovědi
**Co dělá**: Nastavuje limit, jak dlouhá může být odpověď AI.
**Tokeny jsou zhruba ekvivalentní slovům** (asi 1 token = 0,75 slov v angličtině):
- **max_tokens=50**: Krátké a výstižné (jako SMS)
- **max_tokens=500**: Pěkný odstavec nebo dva
- **max_tokens=2000**: Podrobné vysvětlení s příklady
```python
# Krátké, výstižné odpovědi
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Explain JavaScript"}],
max_tokens=100 # Nutí k stručnému vysvětlení
)
# Podrobné, komplexní odpovědi
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Explain JavaScript"}],
max_tokens=1500 # Umožňuje podrobné vysvětlení s příklady
)
```
#### Top_p (0,0 až 1,0): Parametr zaměření
**Co dělá**: Řídí, jak moc se AI soustředí na nejpravděpodobnější odpovědi.
**Představte si AI, která má obrovskou slovní zásobu seřazenou podle pravděpodobnosti slov:**
- **top_p=0,1**: Zvažuje jen nejpravděpodobnějších 10 % slov (velmi zaměřené)
- **top_p=0,9**: Zahrnuje 90 % možných slov (více kreativní)
- **top_p=1,0**: Zahrnuje všechna slova (maximální rozmanitost)
**Například**: Pokud se zeptáte „Obloha je obvykle…“
- **Nízké top_p**: Řekne téměř jistě „modrá“
- **Vysoké top_p**: Může říct „modrá“, „zamračená“, „rozlehlá“, „měnící se“, „krásná“ atd.
### Shrnutí: Kombinace parametrů pro různé případy použití
```python
# Pro faktické, konzistentní odpovědi (jako dokumentační bot)
factual_params = {
"temperature": 0.2,
"max_tokens": 300,
"top_p": 0.3
}
# Pro pomoc s kreativním psaním
creative_params = {
"temperature": 1.1,
"max_tokens": 1000,
"top_p": 0.9
}
# Pro konverzační, užitečné odpovědi (vyvážené)
conversational_params = {
"temperature": 0.7,
"max_tokens": 500,
"top_p": 0.8
}
```
```mermaid
quadrantChart
title Matice optimalizace parametrů AI
x-axis Nízká kreativita --> Vysoká kreativita
y-axis Krátká odpověď --> Dlouhá odpověď
quadrant-1 Kreativní obsah
quadrant-2 Detailní analýza
quadrant-3 Rychlá fakta
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]
```
**Proč jsou tyto parametry důležité**: Různé aplikace potřebují různé typy odpovědí. Zákaznický servis by měl být konzistentní a faktický (nízká teplota), zatímco kreativní pomocník pro psaní by měl být imaginativní a různorodý (vysoká teplota). Porozumění těmto parametrům vám dává kontrolu nad osobností AI a stylem odpovědí.
```
**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))
```
**Co tato vylepšená funkce dělá:**
- **Přijímá** dva parametry: prompt uživatele a volitelnou systémovou zprávu
- **Poskytuje** výchozí systémovou zprávu pro obecné chování asistenta
- **Používá** správné typové nápovědy v Pythonu pro lepší dokumentaci kódu
- **Obsahuje** detailní docstring vysvětlující účel a parametry funkce
- **Vrací** jen obsah odpovědi, aby se snadno používala v našem webovém API
- **Zachovává** stejné parametry modelu pro konzistentní chování AI
### Kouzlo systémových promptů: programování osobnosti AI
Pokud parametry řídí, jak AI přemýšlí, systémové prompty řídí, kdo AI „myslí“, že je. To je upřímně jedna z nejsilnějších částí práce s AI – v podstatě dáváte AI kompletní osobnost, úroveň odbornosti a způsob komunikace.
**Představte si systémové prompty jako herecký casting různých rolí**: Místo jednoho obecného asistenta můžete vytvořit specializované experty pro různé situace. Potřebujete trpělivého učitele? Kreativního brainstormingového partnera? Rigorózního obchodního poradce? Stačí změnit systémový prompt!
#### Proč jsou systémové prompty tak silné
Zajímavé je, že AI modely byly trénovány na nespočtu konverzací, kde lidé zaujímají různé role a úrovně odbornosti. Když AI dáte konkrétní roli, je to jako přepnout vypínač, který aktivuje všechny ty naučené vzory.
**Je to jako method acting pro AI**: Řekněte herci „jsi moudrý starý profesor“ a sledujte, jak automaticky upraví držení těla, slovník a chování. AI dělá něco velmi podobného s jazykovými vzory.
#### Jak vytvořit efektivní systémové prompty: umění a věda
**Anatomie skvělého systémového promptu:**
1. **Role/identita**: Kdo AI je?
2. **Odbornost**: Co zná?
3. **Styl komunikace**: Jak mluví?
4. **Konkrétní instrukce**: Na co se má zaměřit?
```python
# ❌ Nejasný systémový pokyn
"You are helpful."
# ✅ Podrobný, efektivní systémový pokyn
"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."
```
#### Příklady systémových promptů s kontextem
Podívejme se, jak různé systémové prompty vytvoří naprosto odlišné osobnosti AI:
```python
# Příklad 1: Trpělivý učitel
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.
"""
# Příklad 2: Kreativní 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.
"""
# Příklad 3: Strategický obchodní poradce
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.
"""
```
#### Systémové prompty v akci
Otestujme stejnou otázku s různými systémovými prompty a uvidíme dramatické rozdíly:
**Otázka**: „Jak řeším uživatelskou autentifikaci v mé webové aplikaci?“
```python
# S pokynem učitele:
teacher_response = call_llm(
"How do I handle user authentication in my web app?",
teacher_prompt
)
# Typická odpověď: "Skvělá otázka! Rozdělme autentizaci na jednoduché kroky.
# Představte si to jako výběrčího v nočním klubu kontrolujícího průkazy totožnosti..."
# S obchodním pokynem:
business_response = call_llm(
"How do I handle user authentication in my web app?",
business_prompt
)
# Typická odpověď: "Z strategického hlediska je autentizace zásadní pro důvěru uživatele
# a dodržování předpisů. Nastíním rámec zohledňující bezpečnost,
# uživatelský zážitek a škálovatelnost..."
```
#### Pokročilé techniky systémových promptů
**1. Nastavení kontextu**: Dejte AI pozadí informace
```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átování výstupu**: Řekněte AI, jak strukturovat odpovědi
```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. Nastavení omezení**: Definujte, co by AI NEMĚLA dělat
```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.
"""
```
#### Proč je to důležité pro vašeho chat asistenta
Pochopení systémových promptů vám dává neuvěřitelnou sílu vytvořit specializované AI asistenty:
- **Bot zákaznické podpory**: Užitečný, trpělivý, se znalostí pravidel
- **Výukový tutor**: Povzbuzující, krok za krokem, kontroluje pochopení
- **Kreativní partner**: Nápaditý, rozvíjí myšlenky, ptá se "co kdyby?"
- **Technický expert**: Přesný, detailní, dbá na bezpečnost
**Hlavní poznatek**: Nejste jen volající AI API – vytváříte vlastní AI osobnost, která slouží vašemu konkrétnímu případu použití. To je důvod, proč moderní AI aplikace působí šité na míru a užitečné, nikoli obecné.
### 🎯 Pedagogická kontrola: Programování AI osobnosti
**Zastavte se a zamyslete**: Právě jste se naučili programovat AI osobnosti pomocí systémových promptů. To je základní dovednost v moderním vývoji AI aplikací.
**Rychlé sebehodnocení**:
- Dokážete vysvětlit, čím se systémové prompty liší od běžných uživatelských zpráv?
- Jaký je rozdíl mezi parametry temperature a top_p?
- Jak byste vytvořili systémový prompt pro konkrétní případ použití (například tutor kódování)?
**Spojení s reálným světem**: Techniky systémových promptů, které jste se naučili, se používají v každé velké AI aplikaci – od GitHub Copilota až po konverzační rozhraní ChatGPT. Ovládáte stejné postupy, jaké používají AI týmy ve velkých technologických firmách.
**Výzva**: Jak byste navrhli různé AI osobnosti pro různé typy uživatelů (začátečník vs expert)? Zvažte, jak jeden základní AI model může díky prompt engineeringu sloužit různým cílovým skupinám.
## Vytvoření Web API pomocí FastAPI: Vaše výkonné AI komunikační centrum
Nyní postavme backend, který propojí frontend s AI službami. Použijeme FastAPI, moderní Python framework, který vyniká ve tvorbě API pro AI aplikace.
FastAPI nabízí několik výhod pro tento typ projektu: vestavěná asynchronní podpora pro zpracování více požadavků současně, automatická generace dokumentace API a výborný výkon. Váš FastAPI server funguje jako prostředník, který přijímá požadavky z frontendu, komunikuje s AI službami a vrací naformátované odpovědi.
### Proč FastAPI pro AI aplikace?
Možná přemýšlíte: „Nemohu AI volat přímo z JavaScriptu frontendu?“ nebo „Proč FastAPI místo Flasku nebo Djangoinu?“ Skvělé otázky!
**Důvody, proč je FastAPI ideální pro to, co stavíme:**
- **Asynchronní jako výchozí**: Zvládne najednou vyřizovat více AI požadavků bez zaseknutí
- **Automatická dokumentace**: Navštivte `/docs` a získáte krásnou, interaktivní dokumentaci API zdarma
- **Vestavěná validace**: Odhalí chyby dřív, než způsobí problémy
- **Bleskově rychlý**: Jeden z nejrychlejších Python frameworků
- **Moderní Python**: Využívá nejnovější a nejlepší Python funkce
**Proč vůbec potřebujeme backend:**
**Bezpečnost**: Váš AI API klíč je jako heslo – pokud ho vložíte do frontendového JavaScriptu, kdokoli, kdo uvidí zdrojový kód vašich webových stránek, ho může ukrást a zneužít vaše AI kredity. Backend uchovává citlivé údaje v bezpečí.
**Omezení a kontrola**: Backend vám umožní kontrolovat, jak často mohou uživatelé posílat požadavky, implementovat autentizaci uživatelů a přidávat logování pro sledování využití.
**Zpracování dat**: Můžete chtít ukládat konverzace, filtrovat nevhodný obsah nebo kombinovat více AI služeb. Logika to všechno probíhá na backendu.
**Architektura připomíná model klient-server:**
- **Frontend**: Vrstva uživatelského rozhraní pro interakci
- **Backend API**: Vrstva zpracování a směrování požadavků
- **AI služba**: Externí výpočty a generování odpovědí
- **Proměnné prostředí**: Bezpečné uložení konfigurace a přístupových údajů
### Pochopení toku požadavku a odpovědi
Pojďme sledovat, co se děje, když uživatel odešle zprávu:
```mermaid
sequenceDiagram
participant User as 👤 Uživateli
participant Frontend as 🌐 Frontend
participant API as 🔧 FastAPI Server
participant AI as 🤖 AI služba
User->>Frontend: Zadává "Ahoj AI!"
Frontend->>API: POST /hello {"message": "Ahoj AI!"}
Note over API: Ověřuje požadavek Přidává systémovou výzvu
API->>AI: Odesílá formátovaný požadavek
AI->>API: Vrací odpověď AI
Note over API: Zpracovává odpověď Loguje konverzaci
API->>Frontend: {"response": "Ahoj! Jak vám mohu pomoci?"}
Frontend->>User: Zobrazuje zprávu AI
```
**Porozumění jednotlivým krokům:**
1. **Interakce uživatele**: Osoba zadává text do chatovacího rozhraní
2. **Zpracování frontendu**: JavaScript zachytí vstup a naformátuje ho jako JSON
3. **Validace API**: FastAPI automaticky ověří požadavek pomocí Pydantic modelů
4. **Integrace AI**: Backend přidá kontext (systémový prompt) a zavolá AI službu
5. **Zpracování odpovědi**: API přijme odpověď AI a může ji upravit podle potřeby
6. **Zobrazení ve frontendu**: JavaScript zobrazí odpověď v chatovacím rozhraní
### Porozumění architektuře 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! Jak vám mohu pomoci?"}
```
```mermaid
flowchart TD
A[Uživatelský vstup] --> B[Validace na frontend]
B --> C[HTTP POST požadavek]
C --> D[FastAPI router]
D --> E[Validace Pydantic]
E --> F[Volání funkce AI]
F --> G[GitHub Models API]
G --> H[Zpracování odpovědi]
H --> I[JSON odpověď]
I --> J[Aktualizace frontendu]
subgraph "Bezpečnostní vrstva"
K[CORS middleware]
L[Proměnné prostředí]
M[Zpracování chyb]
end
D --> K
F --> L
H --> M
```
### Vytvoření aplikace FastAPI
Postupně si vytvoříme API. Vytvořte soubor `api.py` s tímto FastAPI kódem:
```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
# Nastavit protokolování
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
# Vytvořit FastAPI aplikaci
app = FastAPI(
title="AI Chat API",
description="A high-performance API for AI-powered chat applications",
version="1.0.0"
)
# Nastavit CORS
app.add_middleware(
CORSMiddleware,
allow_origins=["*"], # Nastavit vhodně pro produkci
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
# Pydantic modely pro validaci požadavků/odpovědí
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:
# Vyextrahovat a ověřit zprá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]}...")
# Zavolat AI službu (poznámka: call_llm by měla být asynchronní pro 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)
```
**Porozumění implementaci FastAPI:**
- **Importuje** FastAPI pro moderní webové framework funkce a Pydantic pro validaci dat
- **Vytváří** automatickou dokumentaci API (dostupnou na `/docs` při běhu serveru)
- **Aktivuje** CORS middleware pro povolení požadavků z různých zdrojů frontendu
- **Definuje** Pydantic modely pro automatickou validaci požadavků/odpovědí a dokumentaci
- **Používá** asynchronní endpointy pro lepší výkon při paralelním zpracování požadavků
- **Implementuje** správné HTTP status kódy a zpracování chyb s HTTPException
- **Zahrnuje** strukturované logování pro monitoring a ladění
- **Poskytuje** health check endpoint pro sledování stavu služby
**Klíčové výhody FastAPI oproti tradičním frameworkům:**
- **Automatická validace**: Pydantic modely garantují integritu dat před zpracováním
- **Interaktivní dokumentace**: Na `/docs` naleznete auto-generovanou testovatelnou dokumentaci API
- **Typová bezpečnost**: Python typové anotace zabraňují runtime chybám a zvyšují kvalitu kódu
- **Asynchronní podpora**: Zpracuje více AI požadavků najednou bez blokování
- **Výkon**: Výrazně rychlejší zpracování požadavků pro aplikace v reálném čase
### Porozumění CORS: Bezpečnostní stráž webu
CORS (Cross-Origin Resource Sharing) je jako bezpečnostní hlídač u budovy, který kontroluje, jestli návštěvníci smí vstoupit. Pojďme pochopit, proč je to důležité a jak to ovlivňuje vaši aplikaci.
#### Co je CORS a proč existuje?
**Problém**: Představte si, že by jakákoli webová stránka mohla bez vašeho svolení posílat požadavky na váš bankovní web. To by byla bezpečnostní noční můra! Prohlížeče to ve výchozím nastavení zabraňují pomocí „Same-Origin Policy.“
**Same-Origin Policy**: Prohlížeče dovolují webovým stránkám posílat požadavky pouze na stejnou doménu, port a protokol, ze kterých byly načteny.
**Analogie ze života**: Je to jako bezpečnostní služba v bytovém domě – jen obyvatelé (stejný origin) mají přístup do budovy. Pokud chcete pustit přítele (jiný origin), musíte o tom hlídače výslovně informovat.
#### CORS ve vašem vývojovém prostředí
Během vývoje běží frontend a backend na různých portech:
- Frontend: `http://localhost:3000` (nebo file:// při přímém otevření HTML)
- Backend: `http://localhost:5000`
I když jsou na stejném počítači, považují se za „různé originy“!
```python
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI(__name__)
CORS(app) # Toto říká prohlížečům: „Je v pořádku, aby jiné zdroje prováděly požadavky na toto API“
```
**Co konfigurace CORS v praxi dělá:**
- **Přidává** speciální HTTP hlavičky do odpovědí API, které říkají prohlížeči „tomu je tento cross-origin požadavek povolen“
- **Zpracovává** „preflight“ požadavky (prohlížeče někdy ověřují oprávnění před odesláním skutečného požadavku)
- **Zabraňuje** nechvalně známé chybě „blocked by CORS policy“ v konzoli prohlížeče
#### CORS bezpečnost: Vývoj vs produkce
```python
# 🚨 Vývoj: Povolit VŠECHNY zdroje (praktické, ale nebezpečné)
CORS(app)
# ✅ Produkce: Povolit pouze vaši konkrétní doménu frontend
CORS(app, origins=["https://yourdomain.com", "https://www.yourdomain.com"])
# 🔒 Pokročilé: Různé zdroje pro různá prostředí
if app.debug: # Režim vývoje
CORS(app, origins=["http://localhost:3000", "http://127.0.0.1:3000"])
else: # Produkční režim
CORS(app, origins=["https://yourdomain.com"])
```
**Proč je to důležité**: Ve vývoji je `CORS(app)` jako mít otevřené dveře – pohodlné, ale nezabezpečené. V produkci chcete přesně definovat, které weby mohou vaše API používat.
#### Běžné scénáře CORS a řešení
| Scénář | Problém | Řešení |
|--------------------|---------------------------|----------------------------------|
| **Lokální vývoj** | Frontend nedosáhne backend| Přidat CORSMiddleware do FastAPI |
| **GitHub Pages + Heroku** | Nasazený frontend nemůže volat API | Přidat URL GitHub Pages do CORS |
| **Vlastní doména** | CORS chyby v produkci | Aktualizovat CORS origins dle domény |
| **Mobilní aplikace**| Aplikace nemá přístup k webovému API | Přidat doménu aplikace nebo použít `*` opatrně |
**Tip na závěr**: V DevTools v záložce Síť můžete zkontrolovat CORS hlavičky v odpovědích. Hledejte např. `Access-Control-Allow-Origin`.
### Zpracování chyb a validace
Všimněte si, že naše API obsahuje správné zpracování chyb:
```python
# Ověřte, že jsme obdrželi zprávu
if not message:
return jsonify({"error": "Message field is required"}), 400
```
**Klíčové principy validace:**
- **Kontroluje** požadovaná pole před zpracováním požadavku
- **Vrací** smysluplné chybové zprávy v JSON formátu
- **Používá** správné HTTP status kódy (400 pro špatné požadavky)
- **Poskytuje** jasnou zpětnou vazbu, která pomůže frontendovým vývojářům s laděním
## Nastavení a spuštění vašeho backendu
Nyní, když máme připravenou integraci AI a FastAPI server, pojďme vše spustit. Nastavení zahrnuje instalaci Python závislostí, konfiguraci proměnných prostředí a spuštění vývojového serveru.
### Nastavení Python prostředí
Nastavíme si Python vývojové prostředí. Virtuální prostředí jsou jako Manhattan Project – každý projekt má svůj izolovaný prostor s konkrétními nástroji a závislostmi, aby se vzájemně nerušily.
```bash
# Přejděte do vašeho backendového adresáře
cd backend
# Vytvořte virtuální prostředí (jako vytvoření čisté místnosti pro váš projekt)
python -m venv venv
# Aktivujte ho (Linux/Mac)
source ./venv/bin/activate
# Na Windows použijte:
# venv\Scripts\activate
# Nainstalujte dobré věci
pip install openai fastapi uvicorn python-dotenv
```
**Co jsme právě udělali:**
- **Vytvořili** vlastní izolovanou bublinu Pythonu, kde můžeme instalovat balíčky bez ovlivnění ostatních projektů
- **Aktivovali** ji, aby terminál věděl, že má používat toto specifické prostředí
- **Nainstalovali** základní balíčky: OpenAI pro AI magii, FastAPI pro webové API, Uvicorn pro spuštění serveru a python-dotenv pro bezpečné načítání tajemství
**Vysvětlení klíčových závislostí:**
- **FastAPI**: Moderní, rychlý webový framework s automatickou dokumentací API
- **Uvicorn**: Bleskově rychlý ASGI server pro běh FastAPI aplikací
- **OpenAI**: Oficiální knihovna pro GitHub Modely a integraci OpenAI API
- **python-dotenv**: Bezpečné načítání proměnných prostředí ze souborů .env
### Konfigurace prostředí: Jak udržet tajemství v bezpečí
Než spustíme API, pojďme si říct jedno z nejdůležitějších pravidel webového vývoje: jak udržet svoje tajemství skutečně tajemstvími. Proměnné prostředí jsou jako bezpečnostní schránka, ke které má přístup jen vaše aplikace.
#### Co jsou proměnné prostředí?
**Představte si proměnné prostředí jako bezpečný trezor** – uložíte do něj cennosti a pouze vy (a vaše aplikace) máte klíč, jak je vyjmout. Místo aby citlivé údaje byly přímo v kódu (který vidí doslova každý), ukládají se bezpečně v prostředí.
**Rozdíl je:**
- **Špatný způsob**: Heslo napsané na lepícím papírku přilepeném na monitoru
- **Správný způsob**: Heslo uložené v bezpečném správci hesel, ke kterému máte přístup jen vy
#### Proč jsou proměnné prostředí důležité
```python
# 🚨 NIKDY TO NEDĚLEJTE - API klíč je viditelný pro všechny
client = OpenAI(
api_key="ghp_1234567890abcdef...", # Každý ho může ukrást!
base_url="https://models.github.ai/inference"
)
# ✅ DĚLEJTE TO TAKTO - API klíč je ukládán bezpečně
client = OpenAI(
api_key=os.environ["GITHUB_TOKEN"], # Přístup má jen vaše aplikace
base_url="https://models.github.ai/inference"
)
```
**Co se stane, když máte tajemství napevno vložená v kódu:**
1. **Vystavení v verzovacím systému**: Každý s přístupem ke Git repozitáři vidí váš API klíč
2. **Veřejné repozitáře**: Když to nahrajete na GitHub, váš klíč je viditelný celému internetu
3. **Sdílení v týmu**: Další vývojáři projektu získají přístup k vašemu osobnímu API klíči
4. **Bezpečnostní rizika**: Pokud někdo ukradne váš API klíč, může vyčerpat vaše AI kredity
#### Vytvoření vašeho konfiguračního souboru .env
V backendovém adresáři vytvořte soubor `.env`. Tento soubor lokalně ukládá vaše tajemství:
```bash
# Soubor .env - Tento by NEMĚL být nikdy přidán do Git
GITHUB_TOKEN=your_github_personal_access_token_here
FASTAPI_DEBUG=True
ENVIRONMENT=development
```
**Jak funguje soubor .env:**
- **Jedno tajemství na řádek** v podobě `KEY=value`
- **Bez mezer** okolo rovnítka
- **Nemusíte používat uvozovky** kolem hodnot (většinou)
- **Komentáře** začínají znakem `#`
#### Vytvoření osobního přístupového tokenu pro GitHub
Váš GitHub token je jako speciální heslo, které dává aplikaci oprávnění používat GitHub AI služby:
**Postup vytvoření tokenu:**
1. **Přejděte na GitHub Nastavení** → Developer settings → Personal access tokens → Tokens (classic)
2. **Klikněte na "Generate new token (classic)"**
3. **Nastavte expiraci** (30 dní pro testování, delší pro produkci)
4. **Vyberte oprávnění**: Zaškrtněte „repo“ a další potřebná práva
5. **Vygenerujte token** a okamžitě ho zkopírujte (už ho jednou neuvidíte!)
6. **Vložte ho do souboru .env**
```bash
# Příklad toho, jak váš token vypadá (tohle je falešné!)
GITHUB_TOKEN=ghp_1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R
```
#### Načítání proměnných prostředí v Pythonu
```python
import os
from dotenv import load_dotenv
# Načíst proměnné prostředí ze souboru .env
load_dotenv()
# Nyní k nim můžete bezpečně přistupovat
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"
)
```
**Co tento kód dělá:**
- **Načte** váš `.env` soubor a zpřístupní proměnné Pythonu
- **Kontroluje**, zda je token dostupný (dobrá praxe pro ošetření chyb)
- **Vyhodí** jasnou chybu, pokud token chybí
- **Používá** token bezpečně, aniž by ho vystavoval v kódu
#### Bezpečnost Git: Soubor .gitignore
Soubor `.gitignore` říká Gitu, které soubory nikdy nesledovat nebo nahrávat:
```bash
# .gitignore - Přidejte tyto řádky
.env
*.env
.env.local
.env.production
__pycache__/
venv/
.vscode/
```
**Proč je to klíčové**: Jakmile přidáte `.env` do `.gitignore`, Git tento soubor ignoruje a vyhnete se tak nechtěnému nahrání tajemství na GitHub.
#### Různá prostředí, různá tajemství
Profesionální aplikace používají různé API klíče pro různá prostředí:
```bash
# .env.vyvoj
GITHUB_TOKEN=your_development_token
DEBUG=True
# .env.produkce
GITHUB_TOKEN=your_production_token
DEBUG=False
```
**Proč je to důležité**: Nechcete, aby vaše testování ovlivnilo kvótu AI v produkci a chcete mít různou úroveň zabezpečení podle prostředí.
### Spuštění vývojového serveru: Oživení vašeho FastAPI
Teď přichází vzrušující okamžik – spuštění vašeho FastAPI vývojového serveru a sledování, jak vaše AI integrace ožívá! FastAPI používá Uvicorn, bleskurychlý ASGI server, který je speciálně navržen pro asynchronní Python aplikace.
#### Pochopení procesu spuštění FastAPI serveru
```bash
# Metoda 1: Přímé spuštění Pythonu (zahrnuje automatické znovunačtení)
python api.py
# Metoda 2: Použití Uvicorn přímo (více kontroly)
uvicorn api:app --host 0.0.0.0 --port 5000 --reload
```
Když spustíte tento příkaz, děje se za scénou následující:
**1. Python načte vaši FastAPI aplikaci**:
- Importuje všechny požadované knihovny (FastAPI, Pydantic, OpenAI atd.)
- Načte proměnné prostředí z vašeho souboru `.env`
- Vytvoří instanci FastAPI aplikace s automatickou dokumentací
**2. Uvicorn konfiguruje ASGI server**:
- Naváže spojení na portu 5000 s asynchronními schopnostmi zpracování požadavků
- Nastaví směrování požadavků s automatickou validací
- Povolení hot reload pro vývoj (restartuje při změně souborů)
- Generuje interaktivní API dokumentaci
**3. Server začne naslouchat**:
- Ve vašem terminálu se zobrazí: `INFO: Uvicorn running on http://0.0.0.0:5000`
- Server dokáže obsluhovat více současných AI požadavků
- Vaše API je připravené s automatickou dokumentací na `http://localhost:5000/docs`
#### Co byste měli vidět, když vše 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.
```
**Pochopení výstupu FastAPI:**
- **Will watch for changes**: Automatické přenačítání povoleno pro vývoj
- **Uvicorn running**: Vysokovýkonný ASGI server je aktivní
- **Started reloader process**: Sledovač souborů pro automatické restarty
- **Application startup complete**: FastAPI aplikace úspěšně inicializována
- **Interactive docs available**: Navštivte `/docs` pro automatickou API dokumentaci
#### Testování vašeho FastAPI: Více výkonných metod
FastAPI nabízí několik pohodlných způsobů, jak otestovat vaše API, včetně automatické interaktivní dokumentace:
**Metoda 1: Interaktivní API dokumentace (doporučeno)**
1. Otevřete prohlížeč a přejděte na `http://localhost:5000/docs`
2. Uvidíte Swagger UI se všemi zdokumentovanými endpointy
3. Klikněte na `/hello` → "Try it out" → Zadejte testovací zprávu → "Execute"
4. Odpověď uvidíte přímo v prohlížeči s odpovídajícím formátováním
**Metoda 2: Základní test v prohlížeči**
1. Přejděte na `http://localhost:5000` pro kořenový endpoint
2. Přejděte na `http://localhost:5000/health` pro kontrolu stavu serveru
3. Tím potvrdíte, že váš FastAPI server správně běží
**Metoda 2: Test z příkazové řádky (pokročilé)**
```bash
# Test s curl (pokud je dostupný)
curl -X POST http://localhost:5000/hello \
-H "Content-Type: application/json" \
-d '{"message": "Hello AI!"}'
# Očekávaná odpověď:
# {"response": "Ahoj! Jsem váš AI asistent. Jak vám mohu dnes pomoci?"}
```
**Metoda 3: Python testovací skript**
```python
# test_api.py - Vytvořte tento soubor pro testování vaší API
import requests
import json
# Otestujte API endpoint
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)
```
#### Řešení běžných problémů při startu
| Chybová zpráva | Co to znamená | Jak to opravit |
|---------------|---------------|------------|
| `ModuleNotFoundError: No module named 'fastapi'` | FastAPI není nainstalováno | Spusťte `pip install fastapi uvicorn` ve vašem virtuálním prostředí |
| `ModuleNotFoundError: No module named 'uvicorn'` | ASGI server není nainstalován | Spusťte `pip install uvicorn` ve vašem virtuálním prostředí |
| `KeyError: 'GITHUB_TOKEN'` | Proměnná prostředí nenalezena | Zkontrolujte váš `.env` soubor a volání `load_dotenv()` |
| `Address already in use` | Port 5000 je obsazen | Ukončete jiné procesy používající port 5000 nebo změňte port |
| `ValidationError` | Data požadavku neodpovídají Pydantic modelu | Zkontrolujte, zda formát požadavku odpovídá očekávanému schématu |
| `HTTPException 422` | Nezpracovatelná entita | Validace požadavku selhala, zkontrolujte `/docs` pro správný formát |
| `OpenAI API error` | Selhání autentizace AI služby | Ověřte, zda je váš GitHub token správný a má příslušná oprávnění |
#### Nejlepší postupy pro vývoj
**Hot Reloading**: FastAPI s Uvicorn poskytuje automatické přenačítání při ukládání změn do Python souborů. To znamená, že můžete upravovat kód a okamžitě testovat bez nutnosti manuálního restartu.
```python
# Explicitně povolit horké načítání
if __name__ == "__main__":
app.run(host="0.0.0.0", port=5000, debug=True) # debug=True povoluje horké načítání
```
**Logging pro vývoj**: Přidejte logování, abyste pochopili, co se děje:
```python
import logging
# Nastavit protokolování
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
```
**Proč logování pomáhá**: Během vývoje přesně vidíte, jaké požadavky přicházejí, jak AI odpovídá a kde se vyskytují chyby. To výrazně urychluje debugování.
### Konfigurace pro GitHub Codespaces: Cloudový vývoj snadno
GitHub Codespaces je jako mít výkonný vývojový počítač v cloudu, ke kterému máte přístup z jakéhokoliv prohlížeče. Pokud pracujete v Codespaces, je potřeba udělat pár dalších kroků, aby byl váš backend přístupný z frontendu.
#### Pochopení síťování v Codespaces
V lokálním vývojovém prostředí vše běží na stejném počítači:
- Backend: `http://localhost:5000`
- Frontend: `http://localhost:3000` (nebo file://)
V Codespaces běží vaše vývojové prostředí na serverech GitHubu, takže "localhost" znamená něco jiného. GitHub automaticky vytváří veřejné URL pro vaše služby, ale musíte je správně nakonfigurovat.
#### Konfigurace Codespaces krok za krokem
**1. Spusťte svůj backend server**:
```bash
cd backend
python api.py
```
Uvidíte známou zprávu o spuštění FastAPI/Uvicorn, ale běží to uvnitř Codespace prostředí.
**2. Nastavte viditelnost portu**:
- Najděte záložku "Ports" ve spodním panelu VS Code
- Najděte port 5000 v seznamu
- Klikněte pravým tlačítkem na port 5000
- Vyberte "Port Visibility" → "Public"
**Proč jej zpřístupnit veřejně?** Ve výchozím nastavení jsou porty v Codespaces soukromé (přístupné jen vám). Umožněním veřejného přístupu váš frontend (běžící v prohlížeči) může komunikovat s backendem.
**3. Získejte své veřejné URL**:
Po zpřístupnění portu uvidíte URL jako:
```
https://your-codespace-name-5000.app.github.dev
```
**4. Aktualizujte konfiguraci frontendu**:
```javascript
// Ve vašem frontendovém souboru app.js aktualizujte BASE_URL:
this.BASE_URL = "https://your-codespace-name-5000.app.github.dev";
```
#### Pochopení Codespace URL
URL v Codespaces mají předvídatelný vzor:
```
https://[codespace-name]-[port].app.github.dev
```
**Vysvětlení:**
- `codespace-name`: unikátní identifikátor vašeho Codespace (obvykle obsahuje vaše uživatelské jméno)
- `port`: číslo portu, na kterém vaše služba běží (5000 pro naši FastAPI aplikaci)
- `app.github.dev`: doména GitHubu pro Codespace aplikace
#### Testování nastavení Codespaces
**1. Otestujte backend přímo**:
Otevřete své veřejné URL v nové záložce prohlížeče. Měli byste vidět:
```
Welcome to the AI Chat API. Send POST requests to /hello with JSON payload containing 'message' field.
```
**2. Testujte s nástroji pro vývojáře v prohlížeči**:
```javascript
// Otevřete konzoli prohlížeče a otestujte své 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ální vývoj
| Aspekt | Lokální vývoj | GitHub Codespaces |
|--------|--------------|-------------------|
| **Čas na nastavení** | Delší (instalace Pythonu, závislostí) | Okamžitý (přednastavené prostředí) |
| **Přístupová URL** | `http://localhost:5000` | `https://xyz-5000.app.github.dev` |
| **Nastavení portu** | Automatické | Manuální (zpřístupnit porty) |
| **Perzistence souborů** | Lokální počítač | GitHub repository |
| **Spolupráce** | Obtížné sdílet prostředí | Snadné sdílení odkazu na Codespace |
| **Závislost na internetu** | Pouze pro AI API volání | Nutná pro vše |
#### Tipy pro vývoj v Codespaces
**Proměnné prostředí v Codespaces**:
Váš `.env` soubor funguje stejně v Codespaces, ale můžete proměnné prostředí nastavit také přímo v Codespace:
```bash
# Nastavit proměnnou prostředí pro aktuální relaci
export GITHUB_TOKEN="your_token_here"
# Nebo přidat do vašeho .bashrc pro trvalost
echo 'export GITHUB_TOKEN="your_token_here"' >> ~/.bashrc
```
**Správa portů**:
- Codespaces automaticky rozpozná, když vaše aplikace začne naslouchat na portu
- Můžete současně přeposílat více portů (užitečné, pokud přidáte databázi)
- Porty zůstávají přístupné, dokud váš Codespace běží
**Vývojový pracovní postup**:
1. Provádějte změny kódu ve VS Code
2. FastAPI se automaticky přenačítá (díky Uvicorn reload módu)
3. Ihned testujte změny přes veřejné URL
4. Commitujte a pushujte, až jste připraveni
> 💡 **Užitečný tip**: Při vývoji si přidejte záložku na backend URL Codespace. Jelikož názvy Codespace jsou stabilní, URL se nebude měnit, pokud používáte stejný Codespace.
## Vytvoření chatovacího rozhraní frontendu: Kde se potkávají lidé a AI
Teď vybudujeme uživatelské rozhraní – tu část, která určuje, jak lidé komunikují s vaším AI asistentem. Stejně jako design původního rozhraní iPhonu, zaměřujeme se na to, aby složitá technologie působila intuitivně a přirozeně.
### Pochopení moderní frontend architektury
Naše chatovací rozhraní bude to, co nazýváme „Single Page Application“ nebo SPA. Místo staromódního přístupu, kdy každé kliknutí načítá novou stránku, naše aplikace se aktualizuje plynule a okamžitě:
**Staré weby**: Jako čtení fyzické knihy – listujete po úplně nových stránkách
**Naše chatovací aplikace**: Jako používání telefonu – všechno plyne a aktualizuje se bez přerušení
```mermaid
graph TD
A[Uživatel napíše zprávu] --> B[JavaScript zachytí vstup]
B --> C[Ověření a formátování dat]
C --> D[Odeslat na backendové API]
D --> E[Zobrazit stav načítání]
E --> F[Obdržet odpověď AI]
F --> G[Aktualizovat rozhraní chatu]
G --> H[Připraveno na další zprá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 : odesílá požadavky
```
### Tři pilíře frontend vývoje
Každá frontend aplikace – od jednoduchých webů až po složité aplikace jako Discord nebo Slack – stojí na třech základních technologiích. Představte si je jako základ všeho, co vidíte a s čím interagujete na webu:
**HTML (Struktura)**: To je váš základ
- Určuje, jaké prvky existují (tlačítka, textová pole, kontejnery)
- Dává obsahu význam (tohle je nadpis, tohle je formulář atd.)
- Vytváří základní strukturu, na které vše ostatní staví
**CSS (Prezentace)**: To je váš interiérový designér
- Dělá všechno krásným (barvy, fonty, rozvržení)
- Zpracovává různé velikosti obrazovek (mobil, notebook, tablet)
- Vytváří plynulé animace a vizuální zpětnou vazbu
**JavaScript (Chování)**: To je váš mozek
- Reaguje na uživatelské akce (kliknutí, psaní, rolování)
- Komunikuje s backendem a aktualizuje stránku
- Dělá vše interaktivním a dynamickým
**Představte si to jako architektonický návrh:**
- **HTML**: Stavební plán (definice prostor a vztahů)
- **CSS**: Estetický a environmentální design (vizuální styl a uživatelský zážitek)
- **JavaScript**: Mechanické systémy (funkčnost a interaktivita)
### Proč záleží na moderní architektuře JavaScriptu
Naše chatovací aplikace bude používat moderní JavaScriptové vzory, které uvidíte i v profesionálních aplikacích. Pochopení těchto konceptů vám pomůže růst jako vývojáři:
**Architektura založená na třídách**: Organizujeme náš kód do tříd, což je jako vytváření plánů pro objekty
**Async/Await**: Moderní způsob, jak řešit operace, které trvají déle (např. API volání)
**Programování řízené událostmi**: Aplikace reaguje na uživatelské akce (kliknutí, stisky kláves), místo aby běžela v nekonečné smyčce
**Manipulace s DOM**: Dynamicky aktualizuje obsah webové stránky na základě interakcí uživatele a odpovědí API
### Nastavení struktury projektu
Vytvořte složku frontend s touto uspořádanou strukturou:
```text
frontend/
├── index.html # Main HTML structure
├── app.js # JavaScript functionality
└── styles.css # Visual styling
```
**Pochopení architektury:**
- **Odděluje** starosti mezi strukturou (HTML), chováním (JavaScript) a prezentací (CSS)
- **Udržuje** jednoduchou strukturu souborů, která se snadno naviguje a upravuje
- **Následuje** nejlepší webové vývojové praktiky pro organizaci a udržovatelnost
### Budování HTML základu: Semantická struktura pro přístupnost
Začneme strukturou HTML. Moderní webový vývoj klade důraz na „semantické HTML“ – používaní HTML prvků, které jasně popisují svůj účel, ne jen vzhled. To dělá vaši aplikaci přístupnou pro čtečky obrazovky, vyhledávače a další nástroje.
**Proč je semantické HTML důležité**: Představte si, že popisujete svou chatovací aplikaci někomu po telefonu. Řeknete „je tam hlavička s titulkem, hlavní oblast, kde jsou konverzace, a formulář dole pro psaní zpráv.“ Semantické HTML používá prvky, které odpovídají tomuto přirozenému popisu.
Vytvořte `index.html` s touto promyšleně strukturovanou značkovací strukturou:
```html
AI Chat Assistant
AI Chat Assistant
Ask me anything!
```
**Pochopení jednotlivých HTML prvků a jejich účelu:**
#### Struktura dokumentu
- **``**: Říká prohlížeči, že se jedná o moderní HTML5
- **``**: Určuje jazyk stránky pro čtečky a překladače
- **``**: Zajišťuje správné kódování znaků pro mezinárodní text
- **``**: Umožňuje responzivní zobrazení na mobilech kontroloí zoom a velikost
#### Semantické prvky
- **``**: Jasně identifikuje horní část s titulkem a popisem
- **``**: Vyhrazuje hlavní oblast obsahu (kde probíhají konverzace)
- **`