# Rakenna keskusteluavustaja tekoälyn avulla
Muistatko Star Trekistä, kun miehistö keskusteli rennosti aluksen tietokoneen kanssa, esitti monimutkaisia kysymyksiä ja sai harkittuja vastauksia? Se, mikä vaikutti 1960-luvulla puhtaalta tieteiskirjallisuudelta, on nyt jotain, jonka voit rakentaa käyttämällä jo tuntemiasi verkkoteknologioita.
Tässä oppitunnissa luomme tekoälyyn perustuvan keskusteluavustajan käyttäen HTML:ää, CSS:ää, JavaScriptiä ja hieman taustapalveluiden integrointia. Huomaat, kuinka samat taidot, joita olet oppinut, voivat yhdistyä tehokkaisiin tekoälypalveluihin, jotka ymmärtävät kontekstin ja tuottavat merkityksellisiä vastauksia.
Ajattele tekoälyä kuin valtavaa kirjastoa, joka ei ainoastaan löydä tietoa, vaan myös muotoilee sen yhtenäisiksi vastauksiksi, jotka on räätälöity juuri sinun kysymyksiisi. Sen sijaan, että etsisit tuhansien sivujen joukosta, saat suoria ja kontekstuaalisia vastauksia.
Integrointi tapahtuu tuttujen verkkoteknologioiden avulla. HTML luo keskustelukäyttöliittymän, CSS huolehtii visuaalisesta suunnittelusta, JavaScript hallitsee käyttäjän vuorovaikutusta, ja taustapalvelun API yhdistää kaiken tekoälypalveluihin. Se on kuin orkesterin eri osat, jotka yhdessä luovat sinfonian.
Rakennamme pohjimmiltaan sillan luonnollisen ihmisten välisen viestinnän ja koneellisen käsittelyn välille. Opit sekä tekoälypalveluiden teknisen toteutuksen että suunnittelumallit, jotka tekevät vuorovaikutuksesta intuitiivista.
Oppitunnin lopussa tekoälyn integrointi tuntuu vähemmän mystiseltä prosessilta ja enemmän kuin mikä tahansa API, jonka kanssa voit työskennellä. Ymmärrät perustavanlaatuiset mallit, jotka tukevat sovelluksia, kuten ChatGPT ja Claude, käyttäen samoja verkkokehityksen periaatteita, joita olet oppinut.
Tältä valmis projektisi näyttää:
## Tekoälyn ymmärtäminen: mysteeristä mestariksi
Ennen kuin sukellamme koodiin, ymmärretään, mitä olemme tekemässä. Jos olet käyttänyt API:ta aiemmin, tiedät peruskaavan: lähetä pyyntö, vastaanota vastaus.
Tekoäly-API:t noudattavat samanlaista rakennetta, mutta sen sijaan, että ne hakisivat ennalta tallennettuja tietoja tietokannasta, ne tuottavat uusia vastauksia perustuen valtavista tekstimääristä opittuihin malleihin. Ajattele sitä kuin eroa kirjastoluettelon ja asiantuntevan kirjastonhoitajan välillä, joka osaa yhdistellä tietoa useista lähteistä.
### Mitä "Generatiivinen tekoäly" oikeastaan on?
Ajattele, kuinka Rosettan kivi auttoi tutkijoita ymmärtämään egyptiläisiä hieroglyfejä löytämällä kuvioita tunnettujen ja tuntemattomien kielten välillä. Tekoälymallit toimivat samalla tavalla – ne löytävät kuvioita valtavista tekstimääristä ymmärtääkseen, miten kieli toimii, ja käyttävät näitä kuvioita tuottaakseen sopivia vastauksia uusiin kysymyksiin.
**Selitän tämän yksinkertaisella vertauksella:**
- **Perinteinen tietokanta**: Kuten pyytäisit syntymätodistustasi – saat aina saman dokumentin
- **Hakukone**: Kuten pyytäisit kirjastonhoitajaa etsimään kirjoja kissoista – hän näyttää, mitä on saatavilla
- **Generatiivinen tekoäly**: Kuten kysyisit asiantuntevalta ystävältä kissoista – hän kertoo mielenkiintoisia asioita omilla sanoillaan, räätälöitynä tarpeisiisi
```mermaid
graph LR
A[Your Question] --> B[AI Model]
B --> C[Pattern Recognition]
C --> D[Content Generation]
D --> E[Contextual Response]
F[Training Data Books, Articles, Web] --> B
```
### Miten tekoälymallit oppivat (yksinkertaistettu versio)
Tekoälymallit oppivat altistumalla valtaville tekstiaineistoille, jotka sisältävät kirjoja, artikkeleita ja keskusteluja. Tämän prosessin kautta ne tunnistavat kuvioita, kuten:
- Kuinka ajatuksia jäsennetään kirjallisessa viestinnässä
- Mitkä sanat esiintyvät usein yhdessä
- Kuinka keskustelut yleensä etenevät
- Eroja muodollisen ja epämuodollisen viestinnän välillä
**Se on kuin arkeologit tulkitsevat muinaisia kieliä**: he analysoivat tuhansia esimerkkejä ymmärtääkseen kieliopin, sanaston ja kulttuurisen kontekstin, ja lopulta pystyvät tulkitsemaan uusia tekstejä oppimiensa kuvioiden avulla.
### Miksi GitHub Models?
Käytämme GitHub Models -palvelua melko käytännöllisestä syystä – se antaa meille pääsyn yritystason tekoälyyn ilman, että meidän tarvitsee pystyttää omaa tekoälyinfrastruktuuria (mikä, usko pois, ei ole jotain, mitä haluaisit tehdä juuri nyt!). Se on käytännössä "tekoäly palveluna", ja parasta? Aloittaminen on ilmaista, joten voit kokeilla ilman huolta suurista kustannuksista.
```mermaid
graph LR
A[Frontend Chat UI] --> B[Your Backend API]
B --> C[GitHub Models API]
C --> D[AI Model Processing]
D --> C
C --> B
B --> A
```
Käytämme GitHub Models -palvelua taustaintegraatioon, joka tarjoaa pääsyn ammattitason tekoälyominaisuuksiin kehittäjäystävällisen käyttöliittymän kautta. [GitHub Models Playground](https://github.com/marketplace/models/azure-openai/gpt-4o-mini/playground) toimii testausympäristönä, jossa voit kokeilla eri tekoälymalleja ja ymmärtää niiden ominaisuuksia ennen niiden toteuttamista koodissa.
**Miksi tämä testausympäristö on niin hyödyllinen:**
- **Kokeile** eri tekoälymalleja, kuten GPT-4o-mini, Claude ja muita (kaikki ilmaisia!)
- **Testaa** ideoitasi ja kysymyksiäsi ennen koodin kirjoittamista
- **Hanki** valmiita koodinpätkiä suosikkiohjelmointikielelläsi
- **Säädä** asetuksia, kuten luovuustasoa ja vastausten pituutta, nähdäksesi niiden vaikutukset
Kun olet kokeillut hieman, klikkaa vain "Code"-välilehteä ja valitse ohjelmointikielesi saadaksesi tarvittavan toteutuskoodin.
## Python-taustaintegraation asettaminen
Nyt toteutamme tekoälyintegraation Pythonilla. Python on erinomainen valinta tekoälysovelluksille sen yksinkertaisen syntaksin ja tehokkaiden kirjastojen ansiosta. Aloitamme GitHub Models -testausympäristön koodista ja muokkaamme sen uudelleenkäytettäväksi, tuotantovalmiiksi funktioksi.
### Perustoteutuksen ymmärtäminen
Kun otat Python-koodin testausympäristöstä, saat jotain tämän näköistä. Älä huoli, jos se vaikuttaa aluksi monimutkaiselta – käydään se läpi pala palalta:
```python
"""Run this model in Python
> pip install openai
"""
import os
from openai import OpenAI
# To authenticate with the model you will need to generate a personal access token (PAT) in your GitHub settings.
# Create your PAT token by following instructions here: 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"],
)
```python
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)
```
**Mitä tässä koodissa tapahtuu:**
- **Tuomme** tarvittavat työkalut: `os` ympäristömuuttujien lukemiseen ja `OpenAI` tekoälyn kanssa kommunikointiin
- **Asetamme** OpenAI-asiakasohjelman osoittamaan GitHubin tekoälypalvelimille suoraan OpenAI:n sijaan
- **Autentikoimme** erityisellä GitHub-tunnuksella (lisätietoa tästä myöhemmin!)
- **Rakennamme** keskustelun eri "rooleilla" – ajattele sitä kuin näytelmän lavastamista
- **Lähetämme** pyyntömme tekoälylle hienosäätöparametreilla
- **Poimimme** varsinaisen vastaustekstin kaikista palautetuista tiedoista
### Viestiroolien ymmärtäminen: Tekoälykeskustelun kehys
Tekoälykeskustelut käyttävät tiettyä rakennetta, jossa eri "rooleilla" on omat tarkoituksensa:
```python
messages=[
{
"role": "system",
"content": "You are a helpful assistant who explains things simply."
},
{
"role": "user",
"content": "What is machine learning?"
}
]
```
**Ajattele sitä kuin näytelmän ohjaamista:**
- **Järjestelmän rooli**: Kuten näyttämöohjeet näyttelijälle – se kertoo tekoälylle, miten käyttäytyä, millainen persoonallisuus sillä on ja miten vastata
- **Käyttäjän rooli**: Varsinainen kysymys tai viesti sovelluksen käyttäjältä
- **Avustajan rooli**: Tekoälyn vastaus (tätä ei lähetetä, mutta se näkyy keskusteluhistoriassa)
**Esimerkki tosielämästä**: Kuvittele, että esittelet ystäväsi jollekin juhlissa:
- **Järjestelmäviesti**: "Tämä on ystäväni Sarah, hän on lääkäri, joka osaa selittää lääketieteellisiä käsitteitä yksinkertaisesti"
- **Käyttäjäviesti**: "Voitko selittää, miten rokotteet toimivat?"
- **Avustajan vastaus**: Sarah vastaa ystävällisenä lääkärinä, ei lakimiehenä tai kokkina
### Tekoälyparametrien ymmärtäminen: Vastauskäyttäytymisen hienosäätö
Tekoäly-API-kutsujen numeeriset parametrit ohjaavat, miten malli tuottaa vastauksia. Näiden asetusten avulla voit säätää tekoälyn käyttäytymistä eri käyttötarkoituksiin:
#### Lämpötila (0.0–2.0): Luovuuden säätö
**Mitä se tekee**: Säätelee, kuinka luovia tai ennustettavia tekoälyn vastaukset ovat.
**Ajattele sitä kuin jazz-muusikon improvisaatiotasoa:**
- **Lämpötila = 0.1**: Soittaa täsmälleen saman melodian joka kerta (erittäin ennustettava)
- **Lämpötila = 0.7**: Lisää hieman tyylikkäitä variaatioita pysyen tunnistettavana (tasapainoinen luovuus)
- **Lämpötila = 1.5**: Täysi kokeellinen jazz odottamattomilla käänteillä (erittäin arvaamaton)
```python
# Very predictable responses (good for factual questions)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "What is 2+2?"}],
temperature=0.1 # Will almost always say "4"
)
# Creative responses (good for brainstorming)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Write a creative story opening"}],
temperature=1.2 # Will generate unique, unexpected stories
)
```
#### Max Tokens (1–4096+): Vastausten pituuden hallinta
**Mitä se tekee**: Asettaa rajan sille, kuinka pitkä tekoälyn vastaus voi olla.
**Ajattele tokeneita suunnilleen sanoina** (noin 1 token = 0.75 sanaa englanniksi):
- **max_tokens=50**: Lyhyt ja ytimekäs (kuten tekstiviesti)
- **max_tokens=500**: Mukava kappale tai kaksi
- **max_tokens=2000**: Yksityiskohtainen selitys esimerkkien kera
```python
# Short, concise answers
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Explain JavaScript"}],
max_tokens=100 # Forces a brief explanation
)
# Detailed, comprehensive answers
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Explain JavaScript"}],
max_tokens=1500 # Allows for detailed explanations with examples
)
```
#### Top_p (0.0–1.0): Keskittymisparametri
**Mitä se tekee**: Säätelee, kuinka keskittynyt tekoäly pysyy todennäköisimmissä vastauksissa.
**Kuvittele tekoälyllä olevan valtava sanavarasto, joka on järjestetty sanojen todennäköisyyden mukaan:**
- **top_p=0.1**: Huomioi vain 10 % todennäköisimmistä sanoista (erittäin keskittynyt)
- **top_p=0.9**: Huomioi 90 % mahdollisista sanoista (luovempi)
- **top_p=1.0**: Huomioi kaiken (maksimaalinen vaihtelu)
**Esimerkiksi**: Jos kysyt "Taivas on yleensä..."
- **Matala top_p**: Sanoo melko varmasti "sininen"
- **Korkea top_p**: Saattaa sanoa "sininen", "pilvinen", "laaja", "muuttuva", "kaunis" jne.
### Kaiken yhdistäminen: Parametrien yhdistelmät eri käyttötarkoituksiin
```python
# For factual, consistent answers (like a documentation bot)
factual_params = {
"temperature": 0.2,
"max_tokens": 300,
"top_p": 0.3
}
# For creative writing assistance
creative_params = {
"temperature": 1.1,
"max_tokens": 1000,
"top_p": 0.9
}
# For conversational, helpful responses (balanced)
conversational_params = {
"temperature": 0.7,
"max_tokens": 500,
"top_p": 0.8
}
```
**Miksi nämä parametrit ovat tärkeitä**: Eri sovellukset tarvitsevat erilaisia vastauksia. Asiakaspalvelubotin tulisi olla johdonmukainen ja faktapohjainen (matala lämpötila), kun taas luova kirjoitusavustaja tulisi olla mielikuvituksellinen ja vaihteleva (korkea lämpötila). Näiden parametrien ymmärtäminen antaa sinulle hallinnan tekoälyn persoonallisuudesta ja vastaustyylistä.
```
**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))
```
**Tämän parannetun funktion ymmärtäminen:**
- **Hyväksyy** kaksi parametria: käyttäjän kysymyksen ja valinnaisen järjestelmäviestin
- **Tarjoaa** oletusjärjestelmäviestin yleiseen avustajakäyttäytymiseen
- **Käyttää** oikeita Python-tyyppivihjeitä paremman koodidokumentaation vuoksi
- **Palauttaa** vain vastaussisällön, mikä tekee siitä helppokäyttöisen verkkosovellusrajapinnassamme
- **Säilyttää** samat malliparametrit johdonmukaisen tekoälykäyttäytymisen varmistamiseksi
### Järjestelmäviestien taika: Tekoälyn persoonallisuuden ohjelmointi
Jos parametrit ohjaavat, miten tekoäly ajattelee, järjestelmäviestit ohjaavat, kuka tekoäly ajattelee olevansa. Tämä on rehellisesti yksi siisteimmistä asioista tekoälyn kanssa työskentelyssä – annat tekoälylle kokonaisen persoonallisuuden, asiantuntijuustason ja viestintätyylin.
**Ajattele järjestelmäviestejä kuin eri näyttelijöiden roolittamista eri rooleihin**: Sen sijaan, että sinulla olisi yksi geneerinen avustaja, voit luoda erikoistuneita asiantuntijoita eri tilanteisiin. Tarvitsetko kärsivällisen opettajan? Luovan ideointikumppanin? Jämäkän liikeneuvonantajan? Vaihda vain järjestelmäviesti!
#### Miksi järjestelmäviestit ovat niin voimakkaita
Tässä on kiehtova osa: Tekoälymallit on koulutettu lukemattomilla keskusteluilla, joissa ihmiset omaksuvat eri rooleja ja asiantuntijuustasoja. Kun annat tekoälylle tietyn roolin, se on kuin kytkisit päälle kaikki nuo opitut kuviot.
**Se on kuin metodinäyttelijätyöskentely tekoälylle**: Kerro näyttelijälle "olet viisas vanha professori" ja katso, kuinka hän automaattisesti säätää ryhtiään, sanastoaan ja eleitään. Tekoäly tekee jotain hämmästyttävän samanlaista kielellisten kuvioiden kanssa.
#### Tehokkaiden järjestelmäviestien luominen: Taide ja tiede
**Erinomaisen järjestelmäviestin anatomia:**
1. **Rooli/identiteetti**: Kuka tekoäly on?
2. **Asiantuntijuus**: Mitä se tietää?
3. **Viestintätyyli**: Miten se puhuu?
4. **Tarkat ohjeet**: Mihin sen pitäisi keskittyä?
```python
# ❌ Vague system prompt
"You are helpful."
# ✅ Detailed, effective system prompt
"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."
```
#### Järjestelmäviestiesimerkit kontekstilla
Katsotaan, kuinka erilaiset järjestelmäviestit luovat täysin erilaisia tekoälypersoonallisuuksia:
```python
# Example 1: The Patient Teacher
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.
"""
# Example 2: The Creative Collaborator
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.
"""
# Example 3: The Strategic Business Advisor
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.
"""
```
#### Järjestelmäviestien toiminnan näkeminen käytännössä
Testataan samaa kysymystä eri järjestelmäviesteillä ja katsotaan dramaattiset erot:
**Kysymys**: "Kuinka käsittelen käyttäjän tunnistautumisen verkkosovelluksessani?"
```python
# With teacher prompt:
teacher_response = call_llm(
"How do I handle user authentication in my web app?",
teacher_prompt
)
# Typical response: "Great question! Let's break authentication down into simple steps.
# Think of it like a nightclub bouncer checking IDs..."
# With business prompt:
business_response = call_llm(
"How do I handle user authentication in my web app?",
business_prompt
)
# Typical response: "From a strategic perspective, authentication is crucial for user
# trust and regulatory compliance. Let me outline a framework considering security,
# user experience, and scalability..."
```
#### Kehittyneet järjestelmäviestitekniikat
**1. Kontekstin asettaminen**: Anna tekoälylle taustatietoa
```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. Tulostusmuotoilu**: Kerro tekoälylle, miten vastaukset tulisi jäsentää
```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. Rajoitusten asettaminen**: Määrittele, mitä tekoäly EI saa tehdä
```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.
"""
```
#### Miksi tämä on tärkeää keskusteluavustajallesi
Järjestelmäviestien ymmärtäminen antaa sinulle uskomattoman voiman luoda erikoistuneita tekoälyavustajia:
- **Asiakaspalvelubotti**: Avulias, kärsivällinen, politiikkatietoinen
- **Oppimistutor**: Kannustava, vaiheittainen, tarkistaa ymmärryksen
- **Luova kumppani**: Mielikuvituksellinen, kehittää ideoita, kysyy "mitä jos?"
**Tässä syyt, miksi FastAPI sopii täydellisesti siihen, mitä olemme rakentamassa:**
- **Asynkroninen oletuksena**: Käsittelee useita AI-pyyntöjä samanaikaisesti ilman jumiutumista
- **Automaattiset dokumentit**: Käy osoitteessa `/docs` ja saat kauniin, interaktiivisen API-dokumentaation ilmaiseksi
- **Sisäänrakennettu validointi**: Havaitsee virheet ennen kuin ne aiheuttavat ongelmia
- **Salaman nopea**: Yksi nopeimmista Python-kehyksistä
- **Moderni Python**: Hyödyntää kaikkia uusimpia ja parhaita Python-ominaisuuksia
**Ja tässä syyt, miksi tarvitsemme backendin ylipäätään:**
**Turvallisuus**: AI API-avaimesi on kuin salasana – jos laitat sen frontendin JavaScriptiin, kuka tahansa, joka katsoo verkkosivustosi lähdekoodia, voi varastaa sen ja käyttää AI-krediittejäsi. Backend pitää arkaluontoiset tunnukset turvassa.
**Käyttörajoitukset ja hallinta**: Backend antaa mahdollisuuden hallita, kuinka usein käyttäjät voivat tehdä pyyntöjä, toteuttaa käyttäjätunnistuksen ja lisätä lokitiedot käyttöä varten.
**Datan käsittely**: Saatat haluta tallentaa keskusteluja, suodattaa sopimatonta sisältöä tai yhdistää useita AI-palveluita. Backend on paikka, jossa tämä logiikka sijaitsee.
**Arkkitehtuuri muistuttaa asiakas-palvelin-mallia:**
- **Frontend**: Käyttöliittymäkerros vuorovaikutusta varten
- **Backend API**: Pyyntöjen käsittely- ja reitityskerros
- **AI-palvelu**: Ulkoinen laskenta ja vastausten generointi
- **Ympäristömuuttujat**: Turvallinen konfiguraatio ja tunnusten säilytys
### Pyyntö-vastausprosessin ymmärtäminen
Käydään läpi, mitä tapahtuu, kun käyttäjä lähettää viestin:
```mermaid
sequenceDiagram
participant User as 👤 User
participant Frontend as 🌐 Frontend
participant API as 🔧 FastAPI Server
participant AI as 🤖 AI Service
User->>Frontend: Types "Hello AI!"
Frontend->>API: POST /hello {"message": "Hello AI!"}
Note over API: Validates request Adds system prompt
API->>AI: Sends formatted request
AI->>API: Returns AI response
Note over API: Processes response Logs conversation
API->>Frontend: {"response": "Hello! How can I help?"}
Frontend->>User: Displays AI message
```
**Jokaisen vaiheen ymmärtäminen:**
1. **Käyttäjän vuorovaikutus**: Henkilö kirjoittaa chat-käyttöliittymään
2. **Frontendin käsittely**: JavaScript tallentaa syötteen ja muotoilee sen JSON-muotoon
3. **API-validointi**: FastAPI validoi pyynnön automaattisesti Pydantic-mallien avulla
4. **AI-integraatio**: Backend lisää kontekstin (järjestelmäkehotteen) ja kutsuu AI-palvelua
5. **Vastauksen käsittely**: API vastaanottaa AI:n vastauksen ja voi muokata sitä tarvittaessa
6. **Frontendin näyttö**: JavaScript näyttää vastauksen chat-käyttöliittymässä
### API-arkkitehtuurin ymmärtäminen
```mermaid
sequenceDiagram
participant Frontend
participant FastAPI
participant AI Function
participant GitHub Models
Frontend->>FastAPI: POST /hello {"message": "Hello 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": "Hello! How can I help?"}
```
### FastAPI-sovelluksen luominen
Rakennetaan API vaihe vaiheelta. Luo tiedosto nimeltä `api.py` seuraavalla FastAPI-koodilla:
```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
# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
# Create FastAPI application
app = FastAPI(
title="AI Chat API",
description="A high-performance API for AI-powered chat applications",
version="1.0.0"
)
# Configure CORS
app.add_middleware(
CORSMiddleware,
allow_origins=["*"], # Configure appropriately for production
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
# Pydantic models for request/response validation
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:
# Extract and validate message
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]}...")
# Call AI service (note: call_llm should be made async for better performance)
ai_response = await call_llm_async(message, "You are a helpful and friendly assistant.")
logger.info("AI response generated successfully")
return ChatResponse(response=ai_response)
except HTTPException:
raise
except Exception as e:
logger.error(f"Error processing chat message: {str(e)}")
raise HTTPException(status_code=500, detail="Internal server error")
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=5000, reload=True)
```
**FastAPI-toteutuksen ymmärtäminen:**
- **Tuodaan** FastAPI modernin web-kehyksen toiminnallisuutta varten ja Pydantic datan validointiin
- **Luodaan** automaattinen API-dokumentaatio (saatavilla osoitteessa `/docs`, kun palvelin käynnistyy)
- **Mahdollistetaan** CORS-väliohjelmisto, jotta frontend-pyynnöt eri alkuperistä sallitaan
- **Määritellään** Pydantic-mallit automaattista pyyntö/vastausvalidointia ja dokumentaatiota varten
- **Käytetään** asynkronisia päätepisteitä paremman suorituskyvyn saavuttamiseksi samanaikaisilla pyynnöillä
- **Toteutetaan** oikeat HTTP-tilakoodit ja virheenkäsittely HTTPExceptionin avulla
- **Sisällytetään** rakenteellinen lokitus seurantaa ja virheenkorjausta varten
- **Tarjotaan** terveystarkistuspäätepiste palvelun tilan seurantaan
**FastAPI:n keskeiset edut perinteisiin kehyksiin verrattuna:**
- **Automaattinen validointi**: Pydantic-mallit varmistavat datan eheyden ennen käsittelyä
- **Interaktiiviset dokumentit**: Käy osoitteessa `/docs` saadaksesi automaattisesti luodun, testattavan API-dokumentaation
- **Tyyppiturvallisuus**: Python-tyyppivihjeet estävät ajonaikaiset virheet ja parantavat koodin laatua
- **Asynkroninen tuki**: Käsittelee useita AI-pyyntöjä samanaikaisesti ilman estymistä
- **Suorituskyky**: Merkittävästi nopeampi pyyntöjen käsittely reaaliaikaisissa sovelluksissa
### CORS: Verkon turvallisuusvahti
CORS (Cross-Origin Resource Sharing) on kuin rakennuksen turvavahti, joka tarkistaa, saavatko vierailijat tulla sisään. Ymmärretään, miksi tämä on tärkeää ja miten se vaikuttaa sovellukseesi.
#### Mikä CORS on ja miksi se on olemassa?
**Ongelma**: Kuvittele, että mikä tahansa verkkosivusto voisi tehdä pyyntöjä pankkisi verkkosivustolle puolestasi ilman lupaasi. Se olisi turvallisuuskatastrofi! Selaimet estävät tämän oletuksena "Same-Origin Policy" -käytännön avulla.
**Same-Origin Policy**: Selaimet sallivat verkkosivujen tehdä pyyntöjä vain samaan domainiin, porttiin ja protokollaan, josta ne ladattiin.
**Todellinen analogia**: Se on kuin kerrostalon turvallisuus – vain asukkaat (sama alkuperä) voivat päästä rakennukseen oletuksena. Jos haluat ystävän (eri alkuperä) vierailevan, sinun täytyy kertoa turvavahdille, että se on ok.
#### CORS kehitysympäristössäsi
Kehityksen aikana frontend ja backend toimivat eri porteissa:
- Frontend: `http://localhost:3000` (tai file:// jos avaat HTML:n suoraan)
- Backend: `http://localhost:5000`
Nämä katsotaan "eri alkuperiksi", vaikka ne ovat samalla tietokoneella!
```python
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI(__name__)
CORS(app) # This tells browsers: "It's okay for other origins to make requests to this API"
```
**Mitä CORS-konfiguraatio käytännössä tekee:**
- **Lisää** erityisiä HTTP-otsikoita API-vastauksiin, jotka kertovat selaimille "tämä eri alkuperän pyyntö on sallittu"
- **Käsittelee** "preflight"-pyyntöjä (selaimet tarkistavat joskus oikeudet ennen varsinaista pyyntöä)
- **Estää** pelätyn "blocked by CORS policy" -virheen selaimen konsolissa
#### CORS-turvallisuus: Kehitys vs tuotanto
```python
# 🚨 Development: Allows ALL origins (convenient but insecure)
CORS(app)
# ✅ Production: Only allow your specific frontend domain
CORS(app, origins=["https://yourdomain.com", "https://www.yourdomain.com"])
# 🔒 Advanced: Different origins for different environments
if app.debug: # Development mode
CORS(app, origins=["http://localhost:3000", "http://127.0.0.1:3000"])
else: # Production mode
CORS(app, origins=["https://yourdomain.com"])
```
**Miksi tämä on tärkeää**: Kehityksessä `CORS(app)` on kuin jättäisit etuoven lukitsematta – kätevää mutta ei turvallista. Tuotannossa haluat määrittää tarkasti, mitkä verkkosivustot voivat kommunikoida API:si kanssa.
#### Yleiset CORS-tilanteet ja ratkaisut
| Tilanne | Ongelma | Ratkaisu |
|---------|---------|----------|
| **Paikallinen kehitys** | Frontend ei pääse backendiin | Lisää CORSMiddleware FastAPI:hen |
| **GitHub Pages + Heroku** | Julkaistu frontend ei pääse API:hin | Lisää GitHub Pages -URL CORS-alkuperiin |
| **Oma domain** | CORS-virheet tuotannossa | Päivitä CORS-alkuperät vastaamaan domainiasi |
| **Mobiilisovellus** | Sovellus ei pääse web-API:hin | Lisää sovelluksesi domain tai käytä `*` varovasti |
**Vinkki**: Voit tarkistaa CORS-otsikot selaimesi Developer Tools -työkalussa Verkko-välilehdellä. Etsi otsikoita kuten `Access-Control-Allow-Origin` vastauksesta.
### Virheenkäsittely ja validointi
Huomaa, kuinka API sisältää asianmukaisen virheenkäsittelyn:
```python
# Validate that we received a message
if not message:
return jsonify({"error": "Message field is required"}), 400
```
**Keskeiset validointiperiaatteet:**
- **Tarkistaa** vaaditut kentät ennen pyyntöjen käsittelyä
- **Palauttaa** merkitykselliset virheilmoitukset JSON-muodossa
- **Käyttää** asianmukaisia HTTP-tilakoodeja (400 virheellisille pyynnöille)
- **Tarjoaa** selkeää palautetta, joka auttaa frontend-kehittäjiä virheenkorjauksessa
## Backendin asennus ja käynnistys
Nyt kun AI-integraatio ja FastAPI-palvelin ovat valmiita, käynnistetään kaikki. Asennusprosessi sisältää Python-riippuvuuksien asentamisen, ympäristömuuttujien konfiguroinnin ja kehityspalvelimen käynnistämisen.
### Python-ympäristön asennus
Asennetaan Python-kehitysympäristösi. Virtuaaliympäristöt ovat kuin Manhattan-projektin eriytetty lähestymistapa – jokaisella projektilla on oma eristetty tila, jossa on tietyt työkalut ja riippuvuudet, mikä estää ristiriidat eri projektien välillä.
```bash
# Navigate to your backend directory
cd backend
# Create a virtual environment (like creating a clean room for your project)
python -m venv venv
# Activate it (Linux/Mac)
source ./venv/bin/activate
# On Windows, use:
# venv\Scripts\activate
# Install the good stuff
pip install openai fastapi uvicorn python-dotenv
```
**Mitä juuri teimme:**
- **Luoimme** oman pienen Python-kuplan, jossa voimme asentaa paketteja vaikuttamatta mihinkään muuhun
- **Aktivoimme** sen, jotta terminaali tietää käyttää tätä tiettyä ympäristöä
- **Asensimme** olennaiset: OpenAI AI-taikuutta varten, FastAPI web-API:lle, Uvicorn sen ajamiseen ja python-dotenv turvalliseen salaisuuksien hallintaan
**Keskeiset riippuvuudet selitettynä:**
- **FastAPI**: Moderni, nopea web-kehys automaattisella API-dokumentaatiolla
- **Uvicorn**: Salaman nopea ASGI-palvelin, joka ajaa FastAPI-sovelluksia
- **OpenAI**: Virallinen kirjasto GitHub-malleille ja OpenAI API -integraatiolle
- **python-dotenv**: Turvallinen ympäristömuuttujien lataus .env-tiedostoista
### Ympäristön konfigurointi: Salaisuuksien pitäminen turvassa
Ennen kuin käynnistämme API:n, meidän täytyy puhua yhdestä tärkeimmästä verkkokehityksen oppitunnista: kuinka pitää salaisuudet oikeasti salassa. Ympäristömuuttujat ovat kuin turvallinen holvi, johon vain sovelluksesi pääsee käsiksi.
#### Mitä ympäristömuuttujat ovat?
**Ajattele ympäristömuuttujia kuin tallelokeroa** – laitat arvokkaan tavarasi sinne, ja vain sinä (ja sovelluksesi) pääset siihen käsiksi. Sen sijaan, että kirjoittaisit arkaluontoista tietoa suoraan koodiin (jossa kirjaimellisesti kuka tahansa voi nähdä sen), säilytät sen turvallisesti ympäristössä.
**Tässä ero:**
- **Väärä tapa**: Kirjoitat salasanasi muistilapulle ja laitat sen näyttöön
- **Oikea tapa**: Säilytät salasanasi turvallisessa salasananhallinnassa, johon vain sinulla on pääsy
#### Miksi ympäristömuuttujat ovat tärkeitä
```python
# 🚨 NEVER DO THIS - API key visible to everyone
client = OpenAI(
api_key="ghp_1234567890abcdef...", # Anyone can steal this!
base_url="https://models.github.ai/inference"
)
# ✅ DO THIS - API key stored securely
client = OpenAI(
api_key=os.environ["GITHUB_TOKEN"], # Only your app can access this
base_url="https://models.github.ai/inference"
)
```
**Mitä tapahtuu, kun kovakoodaat salaisuudet:**
1. **Versionhallinnan paljastuminen**: Kuka tahansa, jolla on pääsy Git-repositorioon, näkee API-avaimesi
2. **Julkiset repositoriot**: Jos työnnät GitHubiin, avain näkyy koko internetille
3. **Tiimin jakaminen**: Muut kehittäjät, jotka työskentelevät projektissasi, saavat pääsyn henkilökohtaiseen API-avainesi
4. **Turvallisuusmurrot**: Jos joku varastaa API-avaimesi, hän voi käyttää AI-krediittejäsi
#### Ympäristötiedoston asettaminen
Luo `.env`-tiedosto backend-hakemistoosi. Tämä tiedosto tallentaa salaisuutesi paikallisesti:
```bash
# .env file - This should NEVER be committed to Git
GITHUB_TOKEN=your_github_personal_access_token_here
FASTAPI_DEBUG=True
ENVIRONMENT=development
```
**.env-tiedoston ymmärtäminen:**
- **Yksi salaisuus per rivi** muodossa `KEY=value`
- **Ei välilyöntejä** yhtäläisyysmerkin ympärillä
- **Ei lainausmerkkejä** arvojen ympärillä (yleensä)
- **Kommentit** alkavat `#`
#### GitHubin henkilökohtaisen käyttöoikeustunnuksen luominen
GitHub-tunnuksesi on kuin erityinen salasana, joka antaa sovelluksellesi luvan käyttää GitHubin AI-palveluita:
**Vaiheittainen tunnuksen luominen:**
1. **Mene GitHub-asetuksiin** → Kehittäjäasetukset → Henkilökohtaiset käyttöoikeustunnukset → Tunnukset (klassinen)
2. **Klikkaa "Luo uusi tunnus (klassinen)"**
3. **Aseta vanhenemisaika** (30 päivää testaukseen, pidempi tuotantoon)
4. **Valitse laajuudet**: Valitse "repo" ja muut tarvittavat oikeudet
5. **Luo tunnus** ja kopioi se heti (et voi nähdä sitä uudelleen!)
6. **Liitä .env-tiedostoosi**
```bash
# Example of what your token looks like (this is fake!)
GITHUB_TOKEN=ghp_1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R
```
#### Ympäristömuuttujien lataaminen Pythonissa
```python
import os
from dotenv import load_dotenv
# Load environment variables from .env file
load_dotenv()
# Now you can access them securely
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"
)
```
**Mitä tämä koodi tekee:**
- **Lataa** .env-tiedostosi ja tekee muuttujat saatavilla Pythonille
- **Tarkistaa**, onko vaadittu tunnus olemassa (hyvä virheenkäsittely!)
- **Nostaa** selkeän virheen, jos tunnus puuttuu
- **Käyttää** tunnusta turvallisesti paljastamatta sitä koodissa
#### Git-turvallisuus: .gitignore-tiedosto
`.gitignore`-tiedostosi kertoo Gitille, mitkä tiedostot ei koskaan tule seurata tai ladata:
```bash
# .gitignore - Add these lines
.env
*.env
.env.local
.env.production
__pycache__/
venv/
.vscode/
```
**Miksi tämä on ratkaisevaa**: Kun lisäät `.env`-tiedoston `.gitignore`-tiedostoon, Git ohittaa ympäristötiedostosi, estäen sinua vahingossa lataamasta salaisuuksiasi GitHubiin.
#### Eri ympäristöt, eri salaisuudet
Ammattilaisohjelmat käyttävät eri API-avaimia eri ympäristöihin:
```bash
# .env.development
GITHUB_TOKEN=your_development_token
DEBUG=True
# .env.production
GITHUB_TOKEN=your_production_token
DEBUG=False
```
**Miksi tämä on tärkeää**: Et halua, että kehityskokeilusi vaikuttavat tuotannon AI-käyttökiintiöön, ja haluat eri turvallisuustasot eri ympäristöille.
### Kehityspalvelimen käynnistäminen: FastAPI eloon
Nyt tulee jännittävä hetki – käynnistetään FastAPI-kehityspalvelin ja nähdään AI-integraatio toiminnassa! FastAPI käyttää Uvicornia, salaman nopeaa ASGI-palvelinta, joka on erityisesti suunniteltu asynkronisille Python-sovelluksille.
#### FastAPI-palvelimen käynnistysprosessin ymmärtäminen
```bash
# Method 1: Direct Python execution (includes auto-reload)
python api.py
# Method 2: Using Uvicorn directly (more control)
uvicorn api:app --host 0.0.0.0 --port 5000 --reload
```
Kun suoritat tämän komennon, seuraavat asiat tapahtuvat kulissien takana:
**1. Python lataa FastAPI-sovelluksesi**:
- Tuo kaikki tarvittavat kirjastot (FastAPI, Pydantic, OpenAI jne.)
- Lataa ympäristömuuttujat `.env`-tiedostostasi
- Luo FastAPI-sovellusinstanssi automaattisella dokumentaatiolla
**2. Uvicorn konfiguroi ASGI-palvelimen**:
- Sitoutuu porttiin 5000 asynkronisten pyyntöjen käsittelyominaisuuksilla
- Asettaa pyyntöjen reitityksen automaattisella validoinnilla
- Mahdollistaa kuuman latauksen kehitystä varten (käynnistyy uudelleen tiedostomuutoksissa)
- Generoi interaktiivisen API-dokumentaation
**3. Palvelin alkaa kuunnella**:
- Terminaalisi näyttää: `INFO: Uvicorn running on http://0.0.0.0:5000`
- Palvelin voi käsitellä useita samanaikaisia AI-pyyntöjä
- API on valmis automaattisilla dokumenteilla osoitteessa `http://localhost:5000/docs`
#### Mitä sinun pitäisi nähdä, kun kaikki toimii
```bash
$ python api.py
INFO: Will watch for changes in these directories: ['/your/project/path']
INFO: Uvicorn running on http://0.0.0.0:5000 (Press CTRL+C to quit)
INFO: Started reloader process [12345] using WatchFiles
INFO: Started server process [12346]
INFO: Waiting for application startup.
INFO: Application startup complete.
```
**FastAPI:n tuloksen ymmärtäminen:**
- **Tarkkailee muutoksia**: Automaattinen uudelleenlataus käytössä kehitystä varten
- **Uvicorn käynnissä**: Suorituskykyinen ASGI-palvelin on aktiivinen
- **Käynnisti uudelleenlatausprosessin**: Tiedostojen tarkkailija automaattisia uudelleenkäynnistyksiä varten
- **Sovelluksen käynnistys valmis**: FastAPI-sovellus alustettu onnistuneesti
- **Interaktiiviset dokumentit saatavilla**: Käy `/docs
```python
# test_api.py - Create this file to test your API
import requests
import json
# Test the 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)
```
#### Yleiset käynnistysongelmat ja niiden ratkaisu
| Virheilmoitus | Mitä se tarkoittaa | Kuinka korjata |
|---------------|--------------------|----------------|
| `ModuleNotFoundError: No module named 'fastapi'` | FastAPI ei ole asennettu | Suorita `pip install fastapi uvicorn` virtuaaliympäristössäsi |
| `ModuleNotFoundError: No module named 'uvicorn'` | ASGI-palvelin ei ole asennettu | Suorita `pip install uvicorn` virtuaaliympäristössäsi |
| `KeyError: 'GITHUB_TOKEN'` | Ympäristömuuttujaa ei löydy | Tarkista `.env`-tiedosto ja `load_dotenv()`-kutsu |
| `Address already in use` | Portti 5000 on varattu | Lopeta muut prosessit, jotka käyttävät porttia 5000, tai vaihda portti |
| `ValidationError` | Pyynnön data ei vastaa Pydantic-mallia | Varmista, että pyyntösi formaatti vastaa odotettua skeemaa |
| `HTTPException 422` | Käsittelemätön entiteetti | Pyynnön validointi epäonnistui, tarkista `/docs` oikea formaatti |
| `OpenAI API error` | AI-palvelun autentikointi epäonnistui | Varmista, että GitHub-tokenisi on oikein ja sillä on tarvittavat oikeudet |
#### Kehityksen parhaat käytännöt
**Automaattinen uudelleenlataus**: FastAPI ja Uvicorn tarjoavat automaattisen uudelleenlatauksen, kun tallennat muutoksia Python-tiedostoihisi. Tämä tarkoittaa, että voit muokata koodiasi ja testata välittömästi ilman manuaalista uudelleenkäynnistystä.
```python
# Enable hot reloading explicitly
if __name__ == "__main__":
app.run(host="0.0.0.0", port=5000, debug=True) # debug=True enables hot reload
```
**Lokitus kehitystä varten**: Lisää lokitus ymmärtääksesi, mitä tapahtuu:
```python
import logging
# Set up logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
@app.route("/hello", methods=["POST"])
def hello():
data = request.get_json()
message = data.get("message", "")
logger.info(f"Received message: {message}")
if not message:
logger.warning("Empty message received")
return jsonify({"error": "Message field is required"}), 400
try:
response = call_llm(message, "You are a helpful and friendly assistant.")
logger.info(f"AI response generated successfully")
return jsonify({"response": response})
except Exception as e:
logger.error(f"AI API error: {str(e)}")
return jsonify({"error": "AI service temporarily unavailable"}), 500
```
**Miksi lokitus auttaa**: Kehityksen aikana näet tarkalleen, millaisia pyyntöjä tulee, mitä AI vastaa ja missä virheet tapahtuvat. Tämä nopeuttaa virheiden korjaamista huomattavasti.
### GitHub Codespacesin konfigurointi: Pilvipohjainen kehitys helposti
GitHub Codespaces on kuin tehokas kehitystietokone pilvessä, johon pääset käsiksi mistä tahansa selaimesta. Jos työskentelet Codespacesissa, on muutama lisävaihe, jotta taustajärjestelmäsi on käytettävissä käyttöliittymästäsi.
#### Codespacesin verkon ymmärtäminen
Paikallisessa kehitysympäristössä kaikki toimii samalla tietokoneella:
- Taustajärjestelmä: `http://localhost:5000`
- Käyttöliittymä: `http://localhost:3000` (tai file://)
Codespacesissa kehitysympäristösi toimii GitHubin palvelimilla, joten "localhost" tarkoittaa jotain muuta. GitHub luo automaattisesti julkisia URL-osoitteita palveluillesi, mutta sinun täytyy konfiguroida ne oikein.
#### Codespaces-konfiguroinnin vaiheet
**1. Käynnistä taustajärjestelmäsi**:
```bash
cd backend
python api.py
```
Näet tutun FastAPI/Uvicorn-käynnistysviestin, mutta huomaat sen toimivan Codespaces-ympäristössä.
**2. Konfiguroi portin näkyvyys**:
- Etsi "Ports"-välilehti VS Coden alareunasta
- Etsi portti 5000 listasta
- Napsauta porttia 5000 oikealla
- Valitse "Port Visibility" → "Public"
**Miksi tehdä portti julkiseksi?** Oletuksena Codespaces-portit ovat yksityisiä (vain sinulle käytettävissä). Julkiseksi tekeminen mahdollistaa käyttöliittymän (joka toimii selaimessa) kommunikoinnin taustajärjestelmän kanssa.
**3. Hanki julkinen URL-osoitteesi**:
Kun portti on tehty julkiseksi, näet URL-osoitteen, joka näyttää tältä:
```
https://your-codespace-name-5000.app.github.dev
```
**4. Päivitä käyttöliittymän konfiguraatio**:
```javascript
// In your frontend app.js, update the BASE_URL:
this.BASE_URL = "https://your-codespace-name-5000.app.github.dev";
```
#### Codespaces-URL-osoitteiden ymmärtäminen
Codespaces-URL-osoitteet noudattavat ennustettavaa kaavaa:
```
https://[codespace-name]-[port].app.github.dev
```
**Tämän kaavan osat:**
- `codespace-name`: Codespacesin yksilöllinen tunniste (sisältää yleensä käyttäjänimesi)
- `port`: Porttinumero, jossa palvelusi toimii (5000 FastAPI-sovelluksellemme)
- `app.github.dev`: GitHubin domain Codespaces-sovelluksille
#### Codespaces-asetusten testaaminen
**1. Testaa taustajärjestelmää suoraan**:
Avaa julkinen URL-osoitteesi uudessa selaimen välilehdessä. Sinun pitäisi nähdä:
```
Welcome to the AI Chat API. Send POST requests to /hello with JSON payload containing 'message' field.
```
**2. Testaa selaimen kehitystyökaluilla**:
```javascript
// Open browser console and test your 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 paikallinen kehitys
| Ominaisuus | Paikallinen kehitys | GitHub Codespaces |
|------------|---------------------|-------------------|
| **Asennusaika** | Pidempi (Pythonin ja riippuvuuksien asennus) | Välitön (esikonfiguroitu ympäristö) |
| **URL-osoitteen käyttö** | `http://localhost:5000` | `https://xyz-5000.app.github.dev` |
| **Porttien konfigurointi** | Automaattinen | Manuaalinen (tee portit julkisiksi) |
| **Tiedostojen pysyvyys** | Paikallinen kone | GitHub-repositorio |
| **Yhteistyö** | Vaikea jakaa ympäristöä | Helppo jakaa Codespaces-linkki |
| **Internet-riippuvuus** | Vain AI-API-kutsuille | Tarvitaan kaikkeen |
#### Codespaces-kehitysvinkit
**Ympäristömuuttujat Codespacesissa**:
`.env`-tiedostosi toimii samalla tavalla Codespacesissa, mutta voit myös asettaa ympäristömuuttujia suoraan Codespacesissa:
```bash
# Set environment variable for the current session
export GITHUB_TOKEN="your_token_here"
# Or add to your .bashrc for persistence
echo 'export GITHUB_TOKEN="your_token_here"' >> ~/.bashrc
```
**Porttien hallinta**:
- Codespaces havaitsee automaattisesti, kun sovelluksesi alkaa kuunnella porttia
- Voit ohjata useita portteja samanaikaisesti (hyödyllistä, jos lisäät myöhemmin tietokannan)
- Portit pysyvät käytettävissä niin kauan kuin Codespacesisi on käynnissä
**Kehitystyönkulku**:
1. Tee koodimuutoksia VS Codessa
2. FastAPI lataa automaattisesti uudelleen (kiitos Uvicornin reload-tilan)
3. Testaa muutokset välittömästi julkisen URL-osoitteen kautta
4. Tee commit ja push, kun olet valmis
> 💡 **Vinkki**: Lisää Codespaces-taustajärjestelmän URL-osoite kirjanmerkkeihin kehityksen aikana. Koska Codespaces-nimet ovat vakaita, URL-osoite ei muutu niin kauan kuin käytät samaa Codespacesia.
## Käyttöliittymän rakentaminen: Missä ihmiset kohtaavat tekoälyn
Nyt rakennamme käyttöliittymän – osan, joka määrittää, miten ihmiset ovat vuorovaikutuksessa tekoälyavustajasi kanssa. Kuten alkuperäisen iPhonen käyttöliittymän suunnittelussa, keskitymme tekemään monimutkaisesta teknologiasta intuitiivista ja helppokäyttöistä.
### Modernin käyttöliittymäarkkitehtuurin ymmärtäminen
Keskustelukäyttöliittymämme on niin sanottu "Single Page Application" eli SPA. Sen sijaan, että jokainen klikkaus lataisi uuden sivun, sovelluksemme päivittyy sujuvasti ja välittömästi:
**Vanhat verkkosivut**: Kuten fyysisen kirjan lukeminen – käännät kokonaan uusia sivuja
**Keskustelusovelluksemme**: Kuten puhelimen käyttö – kaikki virtaa ja päivittyy saumattomasti
```mermaid
graph TD
A[User Types Message] --> B[JavaScript Captures Input]
B --> C[Validate & Format Data]
C --> D[Send to Backend API]
D --> E[Display Loading State]
E --> F[Receive AI Response]
F --> G[Update Chat Interface]
G --> H[Ready for Next Message]
```
### Käyttöliittymäkehityksen kolme peruspilaria
Jokainen käyttöliittymäsovellus – yksinkertaisista verkkosivuista monimutkaisiin sovelluksiin kuten Discord tai Slack – rakentuu kolmen ydinteknologian varaan. Ajattele niitä perustana kaikelle, mitä näet ja miten olet vuorovaikutuksessa verkossa:
**HTML (Rakenne)**: Tämä on perusta
- Määrittää, mitkä elementit ovat olemassa (painikkeet, tekstikentät, säiliöt)
- Antaa sisällölle merkityksen (tämä on otsikko, tämä on lomake jne.)
- Luo perusrakenteen, jonka päälle kaikki muu rakentuu
**CSS (Ulkoasu)**: Tämä on sisustussuunnittelijasi
- Saa kaiken näyttämään kauniilta (värit, fontit, asettelut)
- Mukautuu eri näyttökokoihin (puhelin vs. kannettava vs. tabletti)
- Luo sulavia animaatioita ja visuaalisia palautteita
**JavaScript (Käyttäytyminen)**: Tämä on aivot
- Reagoi käyttäjän toimintaan (klikkaukset, kirjoittaminen, vieritys)
- Kommunikoi taustajärjestelmän kanssa ja päivittää sivua
- Tekee kaikesta interaktiivista ja dynaamista
**Ajattele sitä kuin arkkitehtuurisuunnittelua:**
- **HTML**: Rakenteellinen suunnitelma (tilojen ja suhteiden määrittely)
- **CSS**: Esteettinen ja ympäristön suunnittelu (visuaalinen tyyli ja käyttökokemus)
- **JavaScript**: Mekaaniset järjestelmät (toiminnallisuus ja interaktiivisuus)
### Miksi moderni JavaScript-arkkitehtuuri on tärkeää
Keskustelusovelluksemme käyttää moderneja JavaScript-malleja, joita näet ammattilaisohjelmistoissa. Näiden käsitteiden ymmärtäminen auttaa sinua kehittymään ohjelmoijana:
**Luokkapohjainen arkkitehtuuri**: Järjestämme koodimme luokkiin, mikä on kuin luoda piirustuksia objekteille
**Async/Await**: Moderni tapa käsitellä aikaa vieviä operaatioita (kuten API-kutsuja)
**Tapahtumapohjainen ohjelmointi**: Sovelluksemme reagoi käyttäjän toimintaan (klikkaukset, näppäinten painallukset) sen sijaan, että se pyörisi silmukassa
**DOM-manipulaatio**: Päivittää verkkosivun sisältöä dynaamisesti käyttäjän toiminnan ja API-vastausten perusteella
### Projektirakenteen luominen
Luo käyttöliittymälle hakemisto, jossa on seuraava järjestelmä:
```text
frontend/
├── index.html # Main HTML structure
├── app.js # JavaScript functionality
└── styles.css # Visual styling
```
**Arkkitehtuurin ymmärtäminen:**
- **Erottaa** rakenteen (HTML), käyttäytymisen (JavaScript) ja ulkoasun (CSS)
- **Ylläpitää** yksinkertaista tiedostorakennetta, jota on helppo navigoida ja muokata
- **Noudattaa** verkkokehityksen parhaita käytäntöjä järjestämisen ja ylläpidon osalta
### HTML-perustan rakentaminen: Semanttinen rakenne saavutettavuuden vuoksi
Aloitetaan HTML-rakenteesta. Moderni verkkokehitys korostaa "semanttista HTML:ää" – HTML-elementtien käyttöä, jotka kuvaavat selkeästi tarkoituksensa, eivät vain ulkonäköään. Tämä tekee sovelluksestasi saavutettavan ruudunlukijoille, hakukoneille ja muille työkaluille.
**Miksi semanttinen HTML on tärkeää**: Kuvittele, että kuvailet keskustelusovellustasi jollekin puhelimessa. Sanoisit "siellä on otsikko, pääalue, jossa keskustelut näkyvät, ja lomake alareunassa viestien kirjoittamista varten." Semanttinen HTML käyttää elementtejä, jotka vastaavat tätä luonnollista kuvausta.
Luo `index.html` tällä huolellisesti rakennetulla merkinnällä:
```html
AI Chat Assistant
AI Chat Assistant
Ask me anything!
```
**Jokaisen HTML-elementin tarkoituksen ymmärtäminen:**
#### Dokumentin rakenne
- **``**: Ilmoittaa selaimelle, että kyseessä on moderni HTML5
- **``**: Määrittää sivun kielen ruudunlukijoille ja käännöstyökaluille
- **``**: Varmistaa oikean merkistökoodauksen kansainväliselle tekstille
- **``**: Tekee sivusta mobiiliystävällisen hallitsemalla zoomausta ja skaalausta
#### Semanttiset elementit
- **``**: Tunnistaa selkeästi yläosan otsikolla ja kuvauksella
- **``**: Määrittää pääsisältöalueen (missä keskustelut tapahtuvat)
- **`