|
|
<!--
|
|
|
CO_OP_TRANSLATOR_METADATA:
|
|
|
{
|
|
|
"original_hash": "46d665af66e51524598af34a42b9b663",
|
|
|
"translation_date": "2025-10-24T19:24:51+00:00",
|
|
|
"source_file": "9-chat-project/README.md",
|
|
|
"language_code": "sw"
|
|
|
}
|
|
|
-->
|
|
|
# Jinsi ya Kujenga Msaidizi wa Mazungumzo kwa Kutumia AI
|
|
|
|
|
|
Unakumbuka kwenye Star Trek jinsi wafanyakazi walivyokuwa wakiongea na kompyuta ya meli, wakiuliza maswali magumu na kupata majibu ya kina? Kile kilichoonekana kama hadithi ya kisayansi katika miaka ya 1960 sasa ni kitu unachoweza kujenga kwa kutumia teknolojia za mtandao unazozijua tayari.
|
|
|
|
|
|
Katika somo hili, tutatengeneza msaidizi wa mazungumzo wa AI kwa kutumia HTML, CSS, JavaScript, na muunganisho wa nyuma. Utajifunza jinsi ujuzi ule ule unaojifunza unaweza kuunganishwa na huduma za AI zenye uwezo wa kuelewa muktadha na kutoa majibu yenye maana.
|
|
|
|
|
|
Fikiria AI kama kuwa na ufikiaji wa maktaba kubwa ambayo si tu inapata taarifa bali pia inazichanganya kuwa majibu yanayofaa kulingana na maswali yako maalum. Badala ya kutafuta kupitia maelfu ya kurasa, unapata majibu ya moja kwa moja na ya muktadha.
|
|
|
|
|
|
Muunganisho unafanyika kupitia teknolojia za mtandao zinazofanya kazi pamoja. HTML inaunda kiolesura cha mazungumzo, CSS inashughulikia muundo wa kuona, JavaScript inasimamia mwingiliano wa mtumiaji, na API ya nyuma inaunganisha kila kitu na huduma za AI. Ni sawa na jinsi sehemu tofauti za orchestra zinavyofanya kazi pamoja kuunda symphony.
|
|
|
|
|
|
Kimsingi tunajenga daraja kati ya mawasiliano ya kawaida ya binadamu na usindikaji wa mashine. Utajifunza utekelezaji wa kiufundi wa muunganisho wa huduma za AI na mifumo ya muundo inayofanya mwingiliano kuwa wa kawaida.
|
|
|
|
|
|
Mwisho wa somo hili, muunganisho wa AI hautahisi kama mchakato wa ajabu bali kama API nyingine unayoweza kufanya kazi nayo. Utaelewa mifumo ya msingi inayowezesha programu kama ChatGPT na Claude, kwa kutumia kanuni zile zile za maendeleo ya mtandao unazojifunza.
|
|
|
|
|
|
Hivi ndivyo mradi wako wa mwisho utakavyoonekana:
|
|
|
|
|
|
|
|
|
|
|
|
## Kuelewa AI: Kutoka Siri hadi Ustadi
|
|
|
|
|
|
Kabla ya kuingia kwenye msimbo, hebu tuelewe tunachofanya kazi nacho. Ikiwa umewahi kutumia API, unajua muundo wa msingi: tuma ombi, pokea jibu.
|
|
|
|
|
|
API za AI zinafuata muundo sawa, lakini badala ya kupata data iliyohifadhiwa kutoka kwenye hifadhidata, zinazalisha majibu mapya kulingana na mifumo iliyojifunza kutoka kwa maandishi mengi. Fikiria kama tofauti kati ya mfumo wa katalogi ya maktaba na mtaalamu wa maktaba anayejua kuchanganya taarifa kutoka vyanzo mbalimbali.
|
|
|
|
|
|
### "Generative AI" ni Nini Haswa?
|
|
|
|
|
|
Fikiria jinsi Jiwe la Rosetta lilivyowezesha wasomi kuelewa hieroglyphics za Misri kwa kutafuta mifumo kati ya lugha zinazojulikana na zisizojulikana. Miundo ya AI inafanya kazi kwa njia sawa – inatafuta mifumo katika maandishi mengi ili kuelewa jinsi lugha inavyofanya kazi, kisha kutumia mifumo hiyo kutoa majibu yanayofaa kwa maswali mapya.
|
|
|
|
|
|
**Hebu niweke wazi kwa kulinganisha rahisi:**
|
|
|
- **Hifadhidata ya jadi**: Kama kuuliza cheti chako cha kuzaliwa – unapata hati ile ile kila wakati
|
|
|
- **Injini ya utafutaji**: Kama kuuliza mtaalamu wa maktaba kutafuta vitabu kuhusu paka – wanakuonyesha kilichopo
|
|
|
- **Generative AI**: Kama kuuliza rafiki mwenye ujuzi kuhusu paka – wanakuambia mambo ya kuvutia kwa maneno yao wenyewe, kulingana na unachotaka kujua
|
|
|
|
|
|
```mermaid
|
|
|
graph LR
|
|
|
A[Your Question] --> B[AI Model]
|
|
|
B --> C[Pattern Recognition]
|
|
|
C --> D[Content Generation]
|
|
|
D --> E[Contextual Response]
|
|
|
|
|
|
F[Training Data<br/>Books, Articles, Web] --> B
|
|
|
```
|
|
|
|
|
|
### Jinsi Miundo ya AI Inavyojifunza (Toleo Rahisi)
|
|
|
|
|
|
Miundo ya AI hujifunza kupitia kufichuliwa na seti kubwa za data zinazojumuisha maandishi kutoka vitabu, makala, na mazungumzo. Kupitia mchakato huu, inatambua mifumo katika:
|
|
|
- Jinsi mawazo yanavyopangwa katika mawasiliano ya maandishi
|
|
|
- Maneno yanayojitokeza pamoja mara kwa mara
|
|
|
- Jinsi mazungumzo yanavyotiririka kawaida
|
|
|
- Tofauti za muktadha kati ya mawasiliano rasmi na yasiyo rasmi
|
|
|
|
|
|
**Ni sawa na jinsi wanajiolojia wanavyotafsiri lugha za kale**: wanachambua maelfu ya mifano ili kuelewa sarufi, msamiati, na muktadha wa kitamaduni, hatimaye kuwa na uwezo wa kutafsiri maandishi mapya kwa kutumia mifumo iliyojifunza.
|
|
|
|
|
|
### Kwa Nini Miundo ya GitHub?
|
|
|
|
|
|
Tunatumia Miundo ya GitHub kwa sababu ya sababu ya kiutendaji – inatupa ufikiaji wa AI ya kiwango cha biashara bila kulazimika kuanzisha miundombinu yetu ya AI (ambayo, kwa hakika, hutaki kufanya sasa hivi!). Fikiria kama kutumia API ya hali ya hewa badala ya kujaribu kutabiri hali ya hewa mwenyewe kwa kuanzisha vituo vya hali ya hewa kila mahali.
|
|
|
|
|
|
Ni kimsingi "AI-kama-Huduma," na sehemu bora? Ni bure kuanza, kwa hivyo unaweza kujaribu bila kuwa na wasiwasi kuhusu gharama kubwa.
|
|
|
|
|
|
```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
|
|
|
```
|
|
|
|
|
|
Tutatumia Miundo ya GitHub kwa muunganisho wetu wa nyuma, ambayo hutoa ufikiaji wa uwezo wa AI wa kiwango cha kitaalamu kupitia kiolesura kinachofaa kwa watengenezaji. [GitHub Models Playground](https://github.com/marketplace/models/azure-openai/gpt-4o-mini/playground) inatumika kama mazingira ya majaribio ambapo unaweza kujaribu miundo tofauti ya AI na kuelewa uwezo wake kabla ya kuitekeleza kwenye msimbo.
|
|
|
|
|
|
|
|
|
|
|
|
**Hivi ndivyo uwanja wa majaribio unavyofaa:**
|
|
|
- **Jaribu** miundo tofauti ya AI kama GPT-4o-mini, Claude, na nyinginezo (bure kabisa!)
|
|
|
- **Pima** mawazo yako na maelekezo kabla ya kuandika msimbo wowote
|
|
|
- **Pata** vipande vya msimbo vilivyotayarishwa kwa lugha yako ya programu unayoipenda
|
|
|
- **Rekebisha** mipangilio kama kiwango cha ubunifu na urefu wa majibu ili kuona jinsi yanavyoathiri matokeo
|
|
|
|
|
|
Baada ya kucheza kidogo, bonyeza tu kichupo cha "Code" na uchague lugha yako ya programu ili kupata msimbo wa utekelezaji utakaohitaji.
|
|
|
|
|
|
|
|
|
|
|
|
## Kuweka Muunganisho wa Nyuma wa Python
|
|
|
|
|
|
Sasa hebu tutekeleze muunganisho wa AI kwa kutumia Python. Python ni bora kwa programu za AI kwa sababu ya sintaksia yake rahisi na maktaba zenye nguvu. Tutaanza na msimbo kutoka uwanja wa majaribio wa Miundo ya GitHub kisha kuubadilisha kuwa kazi inayoweza kutumika tena na inayofaa kwa uzalishaji.
|
|
|
|
|
|
### Kuelewa Utekelezaji wa Msingi
|
|
|
|
|
|
Unapochukua msimbo wa Python kutoka uwanja wa majaribio, utapata kitu kinachoonekana kama hiki. Usijali ikiwa inaonekana kuwa nyingi mwanzoni – hebu tuipitie kipande kwa kipande:
|
|
|
|
|
|
```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)
|
|
|
```
|
|
|
|
|
|
**Hivi ndivyo kinachotokea kwenye msimbo huu:**
|
|
|
- **Tunajumuisha** zana tunazohitaji: `os` kwa kusoma vigezo vya mazingira na `OpenAI` kwa kuzungumza na AI
|
|
|
- **Tunasanidi** mteja wa OpenAI kuelekeza kwenye seva za AI za GitHub badala ya OpenAI moja kwa moja
|
|
|
- **Tunathibitisha** kwa kutumia tokeni maalum ya GitHub (zaidi kuhusu hilo baadaye!)
|
|
|
- **Tunapanga** mazungumzo yetu na "roles" tofauti – fikiria kama kuweka mandhari ya mchezo wa kuigiza
|
|
|
- **Tunatuma** ombi letu kwa AI na baadhi ya vigezo vya kurekebisha
|
|
|
- **Tunatoa** maandishi halisi ya majibu kutoka kwa data yote inayorudi
|
|
|
|
|
|
### Kuelewa Majukumu ya Ujumbe: Mfumo wa Mazungumzo ya AI
|
|
|
|
|
|
Mazungumzo ya AI hutumia muundo maalum na "roles" tofauti zinazotumikia madhumuni maalum:
|
|
|
|
|
|
```python
|
|
|
messages=[
|
|
|
{
|
|
|
"role": "system",
|
|
|
"content": "You are a helpful assistant who explains things simply."
|
|
|
},
|
|
|
{
|
|
|
"role": "user",
|
|
|
"content": "What is machine learning?"
|
|
|
}
|
|
|
]
|
|
|
```
|
|
|
|
|
|
**Fikiria kama kuongoza mchezo wa kuigiza:**
|
|
|
- **System role**: Kama maelekezo ya jukwaa kwa mwigizaji – inamwambia AI jinsi ya kujiendesha, tabia gani kuwa nayo, na jinsi ya kujibu
|
|
|
- **User role**: Swali halisi au ujumbe kutoka kwa mtu anayetumia programu yako
|
|
|
- **Assistant role**: Jibu la AI (hili hutumika katika historia ya mazungumzo lakini halitumwi)
|
|
|
|
|
|
**Mfano wa maisha halisi**: Fikiria unamtambulisha rafiki kwa mtu kwenye sherehe:
|
|
|
- **Ujumbe wa mfumo**: "Huyu ni rafiki yangu Sarah, yeye ni daktari mzuri katika kuelezea dhana za matibabu kwa njia rahisi"
|
|
|
- **Ujumbe wa mtumiaji**: "Unaweza kuelezea jinsi chanjo zinavyofanya kazi?"
|
|
|
- **Jibu la msaidizi**: Sarah anajibu kama daktari rafiki, si kama wakili au mpishi
|
|
|
|
|
|
### Kuelewa Vigezo vya AI: Kurekebisha Tabia ya Majibu
|
|
|
|
|
|
Vigezo vya nambari katika miito ya API ya AI vinadhibiti jinsi modeli inavyotoa majibu. Mipangilio hii inakuruhusu kurekebisha tabia ya AI kwa matumizi tofauti:
|
|
|
|
|
|
#### Temperature (0.0 hadi 2.0): Kidhibiti Ubunifu
|
|
|
|
|
|
**Kazi yake**: Hudhibiti jinsi majibu ya AI yatakavyokuwa ya ubunifu au yanayotarajiwa.
|
|
|
|
|
|
**Fikiria kama kiwango cha ubunifu cha mpiga jazz:**
|
|
|
- **Temperature = 0.1**: Kucheza melodi ile ile kila wakati (inayotarajiwa sana)
|
|
|
- **Temperature = 0.7**: Kuongeza tofauti za ladha huku ikibaki kutambulika (ubunifu wa wastani)
|
|
|
- **Temperature = 1.5**: Jazz ya majaribio kamili na mabadiliko yasiyotarajiwa (isiyotabirika sana)
|
|
|
|
|
|
```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 hadi 4096+): Kidhibiti Urefu wa Majibu
|
|
|
|
|
|
**Kazi yake**: Huweka kikomo cha jinsi majibu ya AI yanavyoweza kuwa marefu.
|
|
|
|
|
|
**Fikiria tokeni kama maneno kwa takriban** (karibu tokeni 1 = maneno 0.75 kwa Kiingereza):
|
|
|
- **max_tokens=50**: Fupi na tamu (kama ujumbe wa maandishi)
|
|
|
- **max_tokens=500**: Aya moja au mbili nzuri
|
|
|
- **max_tokens=2000**: Maelezo ya kina na mifano
|
|
|
|
|
|
```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 hadi 1.0): Kidhibiti Umakini
|
|
|
|
|
|
**Kazi yake**: Hudhibiti jinsi AI inavyobaki makini kwenye majibu yanayowezekana zaidi.
|
|
|
|
|
|
**Fikiria AI kuwa na msamiati mkubwa, uliopangwa kulingana na uwezekano wa kila neno:**
|
|
|
- **top_p=0.1**: Inazingatia maneno 10% ya juu zaidi yanayowezekana (makini sana)
|
|
|
- **top_p=0.9**: Inazingatia 90% ya maneno yanayowezekana (ubunifu zaidi)
|
|
|
- **top_p=1.0**: Inazingatia kila kitu (tofauti kubwa)
|
|
|
|
|
|
**Kwa mfano**: Ukisema "Anga kwa kawaida ni..."
|
|
|
- **Top_p ya chini**: Karibu hakika itasema "bluu"
|
|
|
- **Top_p ya juu**: Inaweza kusema "bluu", "mawingu", "kubwa", "inabadilika", "nzuri", n.k.
|
|
|
|
|
|
### Kuweka Yote Pamoja: Mchanganyiko wa Vigezo kwa Matumizi Tofauti
|
|
|
|
|
|
```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
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**Kuelewa kwa nini vigezo hivi ni muhimu**: Programu tofauti zinahitaji aina tofauti za majibu. Boti ya huduma kwa wateja inapaswa kuwa thabiti na ya ukweli (temperature ya chini), wakati msaidizi wa uandishi wa ubunifu anapaswa kuwa wa kufikiria na wa tofauti (temperature ya juu). Kuelewa vigezo hivi kunakupa udhibiti wa tabia na mtindo wa majibu ya AI yako.
|
|
|
**Hii ndiyo sababu FastAPI ni bora kwa kile tunachojenga:**
|
|
|
- **Async kwa default**: Inaweza kushughulikia maombi mengi ya AI kwa wakati mmoja bila kukwama
|
|
|
- **Nyaraka za kiotomatiki**: Tembelea `/docs` na upate ukurasa mzuri wa nyaraka za API unaoweza kuingiliana bila malipo
|
|
|
- **Uthibitishaji wa ndani**: Hukamata makosa kabla hayajasababisha matatizo
|
|
|
- **Haraka sana**: Mojawapo ya mifumo ya Python yenye kasi zaidi
|
|
|
- **Python ya kisasa**: Inatumia vipengele vyote vya hivi karibuni na bora vya Python
|
|
|
|
|
|
**Na hii ndiyo sababu tunahitaji backend kabisa:**
|
|
|
|
|
|
**Usalama**: API key yako ya AI ni kama nywila – ukiiweka kwenye JavaScript ya frontend, mtu yeyote anayepitia msimbo wa tovuti yako anaweza kuiba na kutumia mikopo yako ya AI. Backend inahifadhi hati nyeti salama.
|
|
|
|
|
|
**Kudhibiti Kiwango cha Maombi**: Backend inakuruhusu kudhibiti mara ngapi watumiaji wanaweza kufanya maombi, kutekeleza uthibitishaji wa watumiaji, na kuongeza ufuatiliaji wa matumizi.
|
|
|
|
|
|
**Usindikaji wa Data**: Unaweza kutaka kuhifadhi mazungumzo, kuchuja maudhui yasiyofaa, au kuunganisha huduma nyingi za AI. Backend ndiyo mahali mantiki hii inapoishi.
|
|
|
|
|
|
**Muundo unafanana na mfano wa mteja-server:**
|
|
|
- **Frontend**: Safu ya kiolesura cha mtumiaji kwa mwingiliano
|
|
|
- **Backend API**: Safu ya usindikaji wa maombi na uelekezaji
|
|
|
- **Huduma ya AI**: Hesabu ya nje na kizazi cha majibu
|
|
|
- **Vigezo vya Mazingira**: Usanidi salama na uhifadhi wa hati
|
|
|
|
|
|
### Kuelewa Mtiririko wa Maombi na Majibu
|
|
|
|
|
|
Hebu tufuate kinachotokea mtumiaji anapotuma ujumbe:
|
|
|
|
|
|
```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<br/>Adds system prompt
|
|
|
API->>AI: Sends formatted request
|
|
|
AI->>API: Returns AI response
|
|
|
Note over API: Processes response<br/>Logs conversation
|
|
|
API->>Frontend: {"response": "Hello! How can I help?"}
|
|
|
Frontend->>User: Displays AI message
|
|
|
```
|
|
|
|
|
|
**Kuelewa kila hatua:**
|
|
|
1. **Mwingiliano wa mtumiaji**: Mtu anaandika kwenye kiolesura cha mazungumzo
|
|
|
2. **Usindikaji wa frontend**: JavaScript inakamata pembejeo na kuunda kama JSON
|
|
|
3. **Uthibitishaji wa API**: FastAPI inathibitisha kiotomatiki ombi kwa kutumia mifano ya Pydantic
|
|
|
4. **Muunganisho wa AI**: Backend inaongeza muktadha (mfano wa mfumo) na kuita huduma ya AI
|
|
|
5. **Usimamizi wa majibu**: API inapokea majibu ya AI na inaweza kuyabadilisha ikiwa inahitajika
|
|
|
6. **Onyesho la frontend**: JavaScript inaonyesha majibu kwenye kiolesura cha mazungumzo
|
|
|
|
|
|
### Kuelewa Muundo wa API
|
|
|
|
|
|
```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?"}
|
|
|
```
|
|
|
|
|
|
### Kuunda Programu ya FastAPI
|
|
|
|
|
|
Hebu tujenge API yetu hatua kwa hatua. Unda faili inayoitwa `api.py` na msimbo wa FastAPI ufuatao:
|
|
|
|
|
|
```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)
|
|
|
```
|
|
|
|
|
|
**Kuelewa utekelezaji wa FastAPI:**
|
|
|
- **Inaleta** FastAPI kwa utendakazi wa mfumo wa wavuti wa kisasa na Pydantic kwa uthibitishaji wa data
|
|
|
- **Inaunda** nyaraka za API kiotomatiki (zinapatikana kwenye `/docs` wakati seva inapoendesha)
|
|
|
- **Inawezesha** middleware ya CORS kuruhusu maombi ya frontend kutoka asili tofauti
|
|
|
- **Inafafanua** mifano ya Pydantic kwa uthibitishaji wa maombi/majibu kiotomatiki na nyaraka
|
|
|
- **Inatumia** endpoints za async kwa utendaji bora na maombi ya wakati mmoja
|
|
|
- **Inatekeleza** nambari sahihi za hali ya HTTP na usimamizi wa makosa kwa HTTPException
|
|
|
- **Inajumuisha** ufuatiliaji uliopangwa kwa ufuatiliaji na urekebishaji wa makosa
|
|
|
- **Inatoa** endpoint ya ukaguzi wa afya kwa ufuatiliaji wa hali ya huduma
|
|
|
|
|
|
**Faida kuu za FastAPI ikilinganishwa na mifumo ya jadi:**
|
|
|
- **Uthibitishaji wa kiotomatiki**: Mifano ya Pydantic inahakikisha uadilifu wa data kabla ya usindikaji
|
|
|
- **Nyaraka za kiingiliana**: Tembelea `/docs` kwa nyaraka za API zinazotengenezwa kiotomatiki na zinazoweza kujaribiwa
|
|
|
- **Usalama wa aina**: Maelezo ya aina ya Python yanazuia makosa ya wakati wa kukimbia na kuboresha ubora wa msimbo
|
|
|
- **Msaada wa async**: Kushughulikia maombi mengi ya AI kwa wakati mmoja bila kuzuia
|
|
|
- **Utendaji**: Usindikaji wa maombi kwa kasi zaidi kwa programu za wakati halisi
|
|
|
|
|
|
### Kuelewa CORS: Mlinzi wa Usalama wa Wavuti
|
|
|
|
|
|
CORS (Cross-Origin Resource Sharing) ni kama mlinzi wa usalama katika jengo ambaye hukagua ikiwa wageni wanaruhusiwa kuingia. Hebu tuelewe kwa nini hili ni muhimu na jinsi linavyoathiri programu yako.
|
|
|
|
|
|
#### CORS ni nini na Kwa Nini Lipo?
|
|
|
|
|
|
**Tatizo**: Fikiria ikiwa tovuti yoyote ingeweza kufanya maombi kwa tovuti ya benki yako kwa niaba yako bila ruhusa yako. Hilo lingekuwa janga la usalama! Vivinjari vinazuia hili kwa default kupitia "Sera ya Asili Moja."
|
|
|
|
|
|
**Sera ya Asili Moja**: Vivinjari huruhusu kurasa za wavuti kufanya maombi tu kwa kikoa, bandari, na itifaki sawa walizopakiwa kutoka.
|
|
|
|
|
|
**Mfano wa ulimwengu halisi**: Ni kama usalama wa jengo la ghorofa – ni wakazi tu (asili sawa) wanaweza kufikia jengo kwa default. Ikiwa unataka kumruhusu rafiki (asili tofauti) kutembelea, unahitaji kumwambia mlinzi wa usalama waziwazi kuwa ni sawa.
|
|
|
|
|
|
#### CORS katika Mazingira Yako ya Maendeleo
|
|
|
|
|
|
Wakati wa maendeleo, frontend yako na backend yako zinaendesha kwenye bandari tofauti:
|
|
|
- Frontend: `http://localhost:3000` (au file:// ikiwa unafungua HTML moja kwa moja)
|
|
|
- Backend: `http://localhost:5000`
|
|
|
|
|
|
Hizi zinachukuliwa kuwa "asili tofauti" hata kama ziko kwenye kompyuta moja!
|
|
|
|
|
|
```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"
|
|
|
```
|
|
|
|
|
|
**Kile usanidi wa CORS unachofanya kwa vitendo:**
|
|
|
- **Huongeza** vichwa maalum vya HTTP kwa majibu ya API yanayoambia vivinjari "ombi hili la asili tofauti linaruhusiwa"
|
|
|
- **Hushughulikia** maombi ya "preflight" (vivinjari wakati mwingine hukagua ruhusa kabla ya kutuma ombi halisi)
|
|
|
- **Huzuia** kosa la "kuzuia na sera ya CORS" katika koni ya kivinjari chako
|
|
|
|
|
|
#### Usalama wa CORS: Maendeleo dhidi ya Uzalishaji
|
|
|
|
|
|
```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"])
|
|
|
```
|
|
|
|
|
|
**Kwa nini hili ni muhimu**: Katika maendeleo, `CORS(app)` ni kama kuacha mlango wako wazi – rahisi lakini si salama. Katika uzalishaji, unataka kubainisha ni tovuti gani hasa zinaweza kuzungumza na API yako.
|
|
|
|
|
|
#### Matukio ya Kawaida ya CORS na Suluhisho
|
|
|
|
|
|
| Hali | Tatizo | Suluhisho |
|
|
|
|------|--------|----------|
|
|
|
| **Maendeleo ya Kawaida** | Frontend haiwezi kufikia backend | Ongeza CORSMiddleware kwa FastAPI |
|
|
|
| **GitHub Pages + Heroku** | Frontend iliyotumwa haiwezi kufikia API | Ongeza URL ya GitHub Pages yako kwa asili za CORS |
|
|
|
| **Kikoa Maalum** | Makosa ya CORS katika uzalishaji | Sasisha asili za CORS ili zilingane na kikoa chako |
|
|
|
| **Programu ya Simu** | Programu haiwezi kufikia API ya wavuti | Ongeza kikoa cha programu yako au tumia `*` kwa uangalifu |
|
|
|
|
|
|
**Kidokezo cha kitaalamu**: Unaweza kuangalia vichwa vya CORS katika Zana za Wasanidi wa kivinjari chako chini ya kichupo cha Mtandao. Tafuta vichwa kama `Access-Control-Allow-Origin` katika majibu.
|
|
|
|
|
|
### Usimamizi wa Makosa na Uthibitishaji
|
|
|
|
|
|
Angalia jinsi API yetu inavyoshirikisha usimamizi sahihi wa makosa:
|
|
|
|
|
|
```python
|
|
|
# Validate that we received a message
|
|
|
if not message:
|
|
|
return jsonify({"error": "Message field is required"}), 400
|
|
|
```
|
|
|
|
|
|
**Kanuni kuu za uthibitishaji:**
|
|
|
- **Hukagua** uwanja unaohitajika kabla ya kusindika maombi
|
|
|
- **Hurejesha** ujumbe wa makosa wenye maana katika muundo wa JSON
|
|
|
- **Hutumia** nambari sahihi za hali ya HTTP (400 kwa maombi mabaya)
|
|
|
- **Hutoa** maoni wazi kusaidia wasanidi wa frontend kurekebisha masuala
|
|
|
|
|
|
## Kuweka na Kuendesha Backend Yako
|
|
|
|
|
|
Sasa kwa kuwa tuna muunganisho wetu wa AI na seva ya FastAPI tayari, hebu tuanze kila kitu. Mchakato wa usanidi unahusisha kusakinisha utegemezi wa Python, kusanidi vigezo vya mazingira, na kuanzisha seva yako ya maendeleo.
|
|
|
|
|
|
### Usanidi wa Mazingira ya Python
|
|
|
|
|
|
Hebu tusanidi mazingira yako ya maendeleo ya Python. Mazingira ya kawaida ni kama mbinu ya mradi wa Manhattan – kila mradi unapata nafasi yake ya pekee na zana maalum na utegemezi, kuzuia migongano kati ya miradi tofauti.
|
|
|
|
|
|
```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
|
|
|
```
|
|
|
|
|
|
**Kile tulichofanya:**
|
|
|
- **Tumeunda** Bubble yetu ya Python ambapo tunaweza kusakinisha vifurushi bila kuathiri chochote kingine
|
|
|
- **Tumeiwezesha** ili terminal yetu ijue kutumia mazingira haya maalum
|
|
|
- **Tumesakinisha** vitu muhimu: OpenAI kwa uchawi wa AI, FastAPI kwa API yetu ya wavuti, Uvicorn kuendesha, na python-dotenv kwa usimamizi salama wa siri
|
|
|
|
|
|
**Utegemezi muhimu umeelezwa:**
|
|
|
- **FastAPI**: Mfumo wa wavuti wa kisasa, wa haraka na nyaraka za API kiotomatiki
|
|
|
- **Uvicorn**: Seva ya ASGI yenye kasi inayoweza kuendesha programu za FastAPI
|
|
|
- **OpenAI**: Maktaba rasmi kwa GitHub Models na muunganisho wa API ya OpenAI
|
|
|
- **python-dotenv**: Upakiaji salama wa vigezo vya mazingira kutoka kwa faili za .env
|
|
|
|
|
|
### Usanidi wa Mazingira: Kuhifadhi Siri Salama
|
|
|
|
|
|
Kabla ya kuanza API yetu, tunahitaji kuzungumzia mojawapo ya masomo muhimu zaidi katika maendeleo ya wavuti: jinsi ya kuhifadhi siri zako salama. Vigezo vya mazingira ni kama chumba cha usalama ambacho programu yako pekee inaweza kufikia.
|
|
|
|
|
|
#### Vigezo vya Mazingira ni Nini?
|
|
|
|
|
|
**Fikiria vigezo vya mazingira kama sanduku la usalama** – unaweka vitu vyako vya thamani humo, na ni wewe tu (na programu yako) unayeweza kufungua. Badala ya kuandika taarifa nyeti moja kwa moja kwenye msimbo wako (ambapo kila mtu anaweza kuiona), unaihifadhi salama katika mazingira.
|
|
|
|
|
|
**Hii ndiyo tofauti:**
|
|
|
- **Njia mbaya**: Kuandika nywila yako kwenye karatasi ya kunata na kuiweka kwenye skrini yako
|
|
|
- **Njia sahihi**: Kuhifadhi nywila yako katika meneja wa nywila salama ambao ni wewe tu unayeweza kufikia
|
|
|
|
|
|
#### Kwa Nini Vigezo vya Mazingira ni Muhimu
|
|
|
|
|
|
```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"
|
|
|
)
|
|
|
```
|
|
|
|
|
|
**Kinachotokea unapoweka siri moja kwa moja kwenye msimbo:**
|
|
|
1. **Ufunuo wa udhibiti wa toleo**: Mtu yeyote mwenye ufikiaji wa hifadhi yako ya Git anaona API key yako
|
|
|
2. **Hifadhi za umma**: Ukisukuma kwenye GitHub, key yako inaonekana kwa mtandao mzima
|
|
|
3. **Kushiriki timu**: Wasanidi wengine wanaofanya kazi kwenye mradi wako wanapata ufikiaji wa API key yako ya kibinafsi
|
|
|
4. **Uvunjaji wa usalama**: Ikiwa mtu ataiba API key yako, anaweza kutumia mikopo yako ya AI
|
|
|
|
|
|
#### Kuunda Faili Yako ya Mazingira
|
|
|
|
|
|
Unda faili `.env` katika saraka ya backend yako. Faili hii huhifadhi siri zako kwa ndani:
|
|
|
|
|
|
```bash
|
|
|
# .env file - This should NEVER be committed to Git
|
|
|
GITHUB_TOKEN=your_github_personal_access_token_here
|
|
|
FASTAPI_DEBUG=True
|
|
|
ENVIRONMENT=development
|
|
|
```
|
|
|
|
|
|
**Kuelewa faili ya .env:**
|
|
|
- **Siri moja kwa kila mstari** katika muundo wa `KEY=value`
|
|
|
- **Hakuna nafasi** karibu na alama ya usawa
|
|
|
- **Hakuna nukuu** zinazohitajika karibu na maadili (kawaida)
|
|
|
- **Maoni** huanza na `#`
|
|
|
|
|
|
#### Kuunda Tokeni Yako ya Ufikiaji wa Kibinafsi ya GitHub
|
|
|
|
|
|
Tokeni yako ya GitHub ni kama nywila maalum inayotoa ruhusa kwa programu yako kutumia huduma za AI za GitHub:
|
|
|
|
|
|
**Hatua kwa hatua kuunda tokeni:**
|
|
|
1. **Nenda kwa Mipangilio ya GitHub** → Mipangilio ya msanidi programu → Tokeni za ufikiaji wa kibinafsi → Tokeni (classic)
|
|
|
2. **Bonyeza "Generate new token (classic)"**
|
|
|
3. **Weka muda wa kuisha** (siku 30 kwa majaribio, muda mrefu kwa uzalishaji)
|
|
|
4. **Chagua maeneo**: Angalia "repo" na ruhusa nyingine unazohitaji
|
|
|
5. **Tengeneza tokeni** na nakili mara moja (huwezi kuiona tena!)
|
|
|
6. **Bandika kwenye faili yako ya .env**
|
|
|
|
|
|
```bash
|
|
|
# Example of what your token looks like (this is fake!)
|
|
|
GITHUB_TOKEN=ghp_1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R
|
|
|
```
|
|
|
|
|
|
#### Kupakia Vigezo vya Mazingira katika Python
|
|
|
|
|
|
```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"
|
|
|
)
|
|
|
```
|
|
|
|
|
|
**Kile msimbo huu unafanya:**
|
|
|
- **Unapakia** faili yako ya .env na kufanya vigezo kupatikana kwa Python
|
|
|
- **Hukagua** ikiwa tokeni inayohitajika ipo (usimamizi mzuri wa makosa!)
|
|
|
- **Inainua** kosa wazi ikiwa tokeni haipo
|
|
|
- **Inatumia** tokeni kwa usalama bila kuifunua kwenye msimbo
|
|
|
|
|
|
#### Usalama wa Git: Faili ya .gitignore
|
|
|
|
|
|
Faili yako ya `.gitignore` inaambia Git ni faili zipi zisizo na haja ya kufuatiliwa au kupakiwa:
|
|
|
|
|
|
```bash
|
|
|
# .gitignore - Add these lines
|
|
|
.env
|
|
|
*.env
|
|
|
.env.local
|
|
|
.env.production
|
|
|
__pycache__/
|
|
|
venv/
|
|
|
.vscode/
|
|
|
```
|
|
|
|
|
|
**Kwa nini hili ni muhimu**: Mara tu unapoongeza `.env` kwa `.gitignore`, Git itapuuza faili yako ya mazingira, kuzuia wewe kupakia siri zako kwa GitHub kwa bahati mbaya.
|
|
|
|
|
|
#### Mazingira Tofauti, Siri Tofauti
|
|
|
|
|
|
Programu za kitaalamu hutumia API key tofauti kwa mazingira tofauti:
|
|
|
|
|
|
```bash
|
|
|
# .env.development
|
|
|
GITHUB_TOKEN=your_development_token
|
|
|
DEBUG=True
|
|
|
|
|
|
# .env.production
|
|
|
GITHUB_TOKEN=your_production_token
|
|
|
DEBUG=False
|
|
|
```
|
|
|
|
|
|
**Kwa nini hili ni muhimu**: Hutaki majaribio yako ya maendeleo yaathiri kiwango chako cha matumizi ya AI ya uzalishaji, na unataka viwango tofauti vya usalama kwa mazingira tofauti.
|
|
|
|
|
|
### Kuanzisha Seva Yako ya Maendeleo: Kuleta FastAPI Yako Hai
|
|
|
|
|
|
Sasa ni wakati wa kusisimua – kuanzisha seva yako ya maendeleo ya FastAPI na kuona muunganisho wako wa AI ukifanya kazi! FastAPI inatumia Uvicorn, seva ya ASGI yenye kasi iliyoundwa mahsusi kwa programu za Python za async.
|
|
|
|
|
|
#### Kuelewa Mchakato wa Kuanzisha Seva ya FastAPI
|
|
|
|
|
|
```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
|
|
|
```
|
|
|
|
|
|
Unapoendesha amri hii, haya ndiyo yanayotokea nyuma ya pazia:
|
|
|
|
|
|
**1. Python inapakua programu yako ya FastAPI**:
|
|
|
- Inaleta maktaba zote zinazohitajika (FastAPI, Pydantic, OpenAI, nk.)
|
|
|
- Inapakia vigezo vya mazingira kutoka kwa faili yako ya `.env`
|
|
|
- Inaunda mfano wa programu ya FastAPI na nyaraka za kiotomatiki
|
|
|
|
|
|
**2. Uvicorn inasanidi seva ya ASGI**:
|
|
|
- Inaunganisha na bandari ya 5000 na uwezo wa kushughulikia maombi ya async
|
|
|
- Inasanidi uelekezaji wa maombi na uthibitishaji wa kiotomatiki
|
|
|
- Inawezesha upakiaji wa haraka kwa maendeleo (kuanzisha upya mabadiliko ya faili)
|
|
|
- Inazalisha nyaraka za API zinazoweza kuingiliana
|
|
|
|
|
|
**3. Seva inaanza kusikiliza**:
|
|
|
- Terminal yako inaonyesha: `INFO: Uvicorn running on http://0.0.0.0:5000`
|
|
|
- Seva inaweza kushughulikia maombi mengi ya AI kwa wakati mmoja
|
|
|
- API yako iko tayari na nyaraka za kiotomatiki kwenye `http://localhost:5000/docs`
|
|
|
|
|
|
#### Kile Unachopaswa Kuona Wakati Kila Kitu Kinafanya Kazi
|
|
|
|
|
|
```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.
|
|
|
```
|
|
|
|
|
|
**Kuelewa matokeo ya FastAPI:**
|
|
|
- **Itatazama mabadiliko**: Upakiaji wa kiotomatiki umewezeshwa kwa maendeleo
|
|
|
- **Uvicorn inaendesha**: Seva ya ASGI yenye utendaji wa juu iko hai
|
|
|
- **Mchakato wa upakiaji upya umeanza**: Mfuatiliaji wa faili kwa kuanzisha upya kiotomatiki
|
|
|
- **Kuanzisha programu kumekamilika**: Programu ya FastAPI imeanzishwa kwa mafanikio
|
|
|
- **Nyaraka za kiingiliana zinapatikana**: Tembelea `/docs` kwa nyaraka za API kiotomatiki
|
|
|
|
|
|
#### Kujaribu FastAPI Yako: Njia Nyingi Zenye Nguvu
|
|
|
|
|
|
FastAPI inatoa njia kadhaa rahisi za kujaribu API yako, ikiwa ni pamoja na nyaraka za kiotomatiki zinazoweza kuingiliana:
|
|
|
|
|
|
**Njia ya 1: Nyaraka za API Zinazoweza Kuingiliana (Inapendekezwa)**
|
|
|
1. Fungua kivinjari chako na nenda kwa `http://localhost:5000/docs`
|
|
|
2. Utaona Swagger UI na endpoints zako zote zikiwa zimeandikwa
|
|
|
3. Bonyeza kwenye `/hello` → "Jaribu" → Weka ujumbe wa majaribio → "Tekeleza"
|
|
|
4. Tazama majibu moja kwa moja
|
|
|
```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)
|
|
|
```
|
|
|
|
|
|
#### Kutatua Masuala ya Kawaida ya Kuanza
|
|
|
|
|
|
| Ujumbe wa Kosa | Maana Yake | Jinsi ya Kurekebisha |
|
|
|
|----------------|------------|-----------------------|
|
|
|
| `ModuleNotFoundError: No module named 'fastapi'` | FastAPI haijasakinishwa | Run `pip install fastapi uvicorn` katika mazingira yako ya virtual |
|
|
|
| `ModuleNotFoundError: No module named 'uvicorn'` | ASGI server haijasakinishwa | Run `pip install uvicorn` katika mazingira yako ya virtual |
|
|
|
| `KeyError: 'GITHUB_TOKEN'` | Kigezo cha mazingira hakijapatikana | Angalia faili yako ya `.env` na wito wa `load_dotenv()` |
|
|
|
| `Address already in use` | Bandari 5000 inatumika | Zima michakato mingine inayotumia bandari 5000 au badilisha bandari |
|
|
|
| `ValidationError` | Data ya ombi haifanani na modeli ya Pydantic | Hakikisha muundo wa ombi lako unalingana na schema inayotarajiwa |
|
|
|
| `HTTPException 422` | Kitu kisichoweza kusindika | Uthibitishaji wa ombi umeshindwa, angalia `/docs` kwa muundo sahihi |
|
|
|
| `OpenAI API error` | Uthibitishaji wa huduma ya AI umeshindwa | Hakikisha token yako ya GitHub ni sahihi na ina ruhusa zinazofaa |
|
|
|
|
|
|
#### Mazoea Bora ya Maendeleo
|
|
|
|
|
|
**Hot Reloading**: FastAPI na Uvicorn hutoa upakiaji wa moja kwa moja unapohifadhi mabadiliko kwenye faili zako za Python. Hii inamaanisha unaweza kurekebisha msimbo wako na kujaribu mara moja bila kuanzisha tena kwa mikono.
|
|
|
|
|
|
```python
|
|
|
# Enable hot reloading explicitly
|
|
|
if __name__ == "__main__":
|
|
|
app.run(host="0.0.0.0", port=5000, debug=True) # debug=True enables hot reload
|
|
|
```
|
|
|
|
|
|
**Kuweka kumbukumbu kwa Maendeleo**: Ongeza kumbukumbu ili kuelewa kinachoendelea:
|
|
|
|
|
|
```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
|
|
|
```
|
|
|
|
|
|
**Kwa nini kuweka kumbukumbu kunasaidia**: Wakati wa maendeleo, unaweza kuona hasa ni maombi gani yanayoingia, ni nini AI inajibu, na wapi makosa yanatokea. Hii inafanya utatuzi kuwa wa haraka zaidi.
|
|
|
|
|
|
### Kuseti kwa GitHub Codespaces: Maendeleo ya Wingu Rahisi
|
|
|
|
|
|
GitHub Codespaces ni kama kuwa na kompyuta yenye nguvu ya maendeleo kwenye wingu ambayo unaweza kufikia kutoka kwa kivinjari chochote. Ikiwa unafanya kazi katika Codespaces, kuna hatua kadhaa za ziada za kufanya backend yako ipatikane kwa frontend yako.
|
|
|
|
|
|
#### Kuelewa Mtandao wa Codespaces
|
|
|
|
|
|
Katika mazingira ya maendeleo ya ndani, kila kitu kinaendeshwa kwenye kompyuta moja:
|
|
|
- Backend: `http://localhost:5000`
|
|
|
- Frontend: `http://localhost:3000` (au file://)
|
|
|
|
|
|
Katika Codespaces, mazingira yako ya maendeleo yanaendeshwa kwenye seva za GitHub, kwa hivyo "localhost" ina maana tofauti. GitHub huunda URLs za umma kwa huduma zako kiotomatiki, lakini unahitaji kuzisanidi ipasavyo.
|
|
|
|
|
|
#### Hatua kwa Hatua ya Usanidi wa Codespaces
|
|
|
|
|
|
**1. Anzisha seva yako ya backend**:
|
|
|
```bash
|
|
|
cd backend
|
|
|
python api.py
|
|
|
```
|
|
|
|
|
|
Utaona ujumbe wa kawaida wa kuanza wa FastAPI/Uvicorn, lakini tambua kuwa inaendeshwa ndani ya mazingira ya Codespace.
|
|
|
|
|
|
**2. Sanidi mwonekano wa bandari**:
|
|
|
- Tafuta tabo ya "Ports" kwenye paneli ya chini ya VS Code
|
|
|
- Tafuta bandari 5000 kwenye orodha
|
|
|
- Bonyeza kulia kwenye bandari 5000
|
|
|
- Chagua "Port Visibility" → "Public"
|
|
|
|
|
|
**Kwa nini kuifanya iwe ya umma?** Kwa kawaida, bandari za Codespace ni za kibinafsi (zinapatikana tu kwako). Kuzifanya za umma kunaruhusu frontend yako (ambayo inaendeshwa kwenye kivinjari) kuwasiliana na backend yako.
|
|
|
|
|
|
**3. Pata URL yako ya umma**:
|
|
|
Baada ya kufanya bandari iwe ya umma, utaona URL kama:
|
|
|
```
|
|
|
https://your-codespace-name-5000.app.github.dev
|
|
|
```
|
|
|
|
|
|
**4. Sasisha usanidi wa frontend yako**:
|
|
|
```javascript
|
|
|
// In your frontend app.js, update the BASE_URL:
|
|
|
this.BASE_URL = "https://your-codespace-name-5000.app.github.dev";
|
|
|
```
|
|
|
|
|
|
#### Kuelewa URLs za Codespace
|
|
|
|
|
|
URLs za Codespace zinafuata muundo unaotabirika:
|
|
|
```
|
|
|
https://[codespace-name]-[port].app.github.dev
|
|
|
```
|
|
|
|
|
|
**Kuvunja hii:**
|
|
|
- `codespace-name`: Kitambulisho cha kipekee cha Codespace yako (kwa kawaida kinajumuisha jina lako la mtumiaji)
|
|
|
- `port`: Namba ya bandari ambayo huduma yako inaendeshwa (5000 kwa programu yetu ya FastAPI)
|
|
|
- `app.github.dev`: Kikoa cha GitHub kwa programu za Codespace
|
|
|
|
|
|
#### Kujaribu Usanidi wa Codespace Yako
|
|
|
|
|
|
**1. Jaribu backend moja kwa moja**:
|
|
|
Fungua URL yako ya umma kwenye tabo mpya ya kivinjari. Unapaswa kuona:
|
|
|
```
|
|
|
Welcome to the AI Chat API. Send POST requests to /hello with JSON payload containing 'message' field.
|
|
|
```
|
|
|
|
|
|
**2. Jaribu na zana za msanidi wa kivinjari**:
|
|
|
```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 Maendeleo ya Ndani
|
|
|
|
|
|
| Kipengele | Maendeleo ya Ndani | GitHub Codespaces |
|
|
|
|-----------|--------------------|-------------------|
|
|
|
| **Muda wa Usanidi** | Mrefu (sakinisha Python, utegemezi) | Papo hapo (mazingira yaliyosanidiwa awali) |
|
|
|
| **Ufikiaji wa URL** | `http://localhost:5000` | `https://xyz-5000.app.github.dev` |
|
|
|
| **Usanidi wa Bandari** | Kiotomatiki | Mwongozo (fanya bandari ziwe za umma) |
|
|
|
| **Uhifadhi wa Faili** | Kompyuta ya ndani | Hifadhi ya GitHub |
|
|
|
| **Ushirikiano** | Ngumu kushiriki mazingira | Rahisi kushiriki kiungo cha Codespace |
|
|
|
| **Utegemezi wa Mtandao** | Kwa simu za API za AI pekee | Inahitajika kwa kila kitu |
|
|
|
|
|
|
#### Vidokezo vya Maendeleo ya Codespace
|
|
|
|
|
|
**Vigezo vya Mazingira katika Codespaces**:
|
|
|
Faili yako ya `.env` inafanya kazi kwa njia sawa katika Codespaces, lakini unaweza pia kuweka vigezo vya mazingira moja kwa moja katika Codespace:
|
|
|
|
|
|
```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
|
|
|
```
|
|
|
|
|
|
**Usimamizi wa Bandari**:
|
|
|
- Codespaces hugundua kiotomatiki wakati programu yako inaanza kusikiliza kwenye bandari
|
|
|
- Unaweza kupeleka bandari nyingi kwa wakati mmoja (inasaidia ikiwa utaongeza hifadhidata baadaye)
|
|
|
- Bandari zinabaki kupatikana mradi Codespace yako inaendelea
|
|
|
|
|
|
**Mtiririko wa Kazi wa Maendeleo**:
|
|
|
1. Fanya mabadiliko ya msimbo katika VS Code
|
|
|
2. FastAPI inajipakia upya kiotomatiki (shukrani kwa hali ya upakiaji upya ya Uvicorn)
|
|
|
3. Jaribu mabadiliko mara moja kupitia URL ya umma
|
|
|
4. Fanya commit na push unapokuwa tayari
|
|
|
|
|
|
> 💡 **Kidokezo cha Pro**: Weka alama URL yako ya backend ya Codespace wakati wa maendeleo. Kwa kuwa majina ya Codespace ni thabiti, URL haitabadilika mradi unatumia Codespace ile ile.
|
|
|
|
|
|
## Kuunda Kiolesura cha Gumzo cha Frontend: Ambapo Binadamu Hukutana na AI
|
|
|
|
|
|
Sasa tutajenga kiolesura cha mtumiaji – sehemu inayodhibiti jinsi watu wanavyowasiliana na msaidizi wako wa AI. Kama muundo wa kiolesura cha awali cha iPhone, tunazingatia kufanya teknolojia ngumu iwe rahisi na ya asili kutumia.
|
|
|
|
|
|
### Kuelewa Usanifu wa Kisasa wa Frontend
|
|
|
|
|
|
Kiolesura chetu cha gumzo kitakuwa kile tunachokiita "Single Page Application" au SPA. Badala ya mbinu ya zamani ambapo kila bonyeza inasababisha ukurasa mpya kupakiwa, programu yetu inasasisha kwa urahisi na mara moja:
|
|
|
|
|
|
**Tovuti za zamani**: Kama kusoma kitabu cha karatasi – unageuza kurasa mpya kabisa
|
|
|
**Programu yetu ya gumzo**: Kama kutumia simu yako – kila kitu kinatiririka na kusasishwa bila shida
|
|
|
|
|
|
```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]
|
|
|
```
|
|
|
|
|
|
### Nguzo Tatu za Maendeleo ya Frontend
|
|
|
|
|
|
Kila programu ya frontend – kutoka tovuti rahisi hadi programu ngumu kama Discord au Slack – inajengwa juu ya teknolojia tatu za msingi. Fikiria kama msingi wa kila kitu unachokiona na kuingiliana nacho kwenye wavuti:
|
|
|
|
|
|
**HTML (Muundo)**: Hii ni msingi wako
|
|
|
- Inaamua ni vipengele gani vinavyokuwepo (vifungo, maeneo ya maandishi, vyombo)
|
|
|
- Inatoa maana kwa maudhui (hii ni kichwa, hii ni fomu, nk.)
|
|
|
- Inaunda muundo wa msingi ambao kila kitu kingine kinajengwa juu yake
|
|
|
|
|
|
**CSS (Uwasilishaji)**: Hii ni mbunifu wako wa ndani
|
|
|
- Inafanya kila kitu kionekane kizuri (rangi, fonti, mipangilio)
|
|
|
- Inashughulikia saizi tofauti za skrini (simu vs laptop vs tablet)
|
|
|
- Inaunda michoro laini na maoni ya kuona
|
|
|
|
|
|
**JavaScript (Tabia)**: Hii ni akili yako
|
|
|
- Inajibu kile watumiaji wanachofanya (kubofya, kuandika, kusogeza)
|
|
|
- Inazungumza na backend yako na kusasisha ukurasa
|
|
|
- Inafanya kila kitu kiwe cha kuingiliana na cha nguvu
|
|
|
|
|
|
**Fikiria kama muundo wa usanifu:**
|
|
|
- **HTML**: Mchoro wa muundo (kufafanua nafasi na uhusiano)
|
|
|
- **CSS**: Muundo wa uzuri na mazingira (mtindo wa kuona na uzoefu wa mtumiaji)
|
|
|
- **JavaScript**: Mifumo ya mitambo (utendaji na mwingiliano)
|
|
|
|
|
|
### Kwa nini Usanifu wa Kisasa wa JavaScript Unahitajika
|
|
|
|
|
|
Programu yetu ya gumzo itatumia mifumo ya kisasa ya JavaScript ambayo utaona katika programu za kitaalamu. Kuelewa dhana hizi kutakusaidia unapokua kama msanidi programu:
|
|
|
|
|
|
**Usanifu wa Msingi wa Darasa**: Tutapanga msimbo wetu katika madarasa, ambayo ni kama kuunda michoro ya vitu
|
|
|
**Async/Await**: Njia ya kisasa ya kushughulikia shughuli zinazochukua muda (kama simu za API)
|
|
|
**Programu Inayoendeshwa na Matukio**: Programu yetu inajibu vitendo vya mtumiaji (kubofya, kubonyeza funguo) badala ya kuendesha katika mzunguko
|
|
|
**Manipulation ya DOM**: Kusasisha maudhui ya ukurasa wa wavuti kwa nguvu kulingana na mwingiliano wa mtumiaji na majibu ya API
|
|
|
|
|
|
### Usanidi wa Muundo wa Mradi
|
|
|
|
|
|
Unda saraka ya frontend na muundo huu uliopangwa:
|
|
|
|
|
|
```text
|
|
|
frontend/
|
|
|
├── index.html # Main HTML structure
|
|
|
├── app.js # JavaScript functionality
|
|
|
└── styles.css # Visual styling
|
|
|
```
|
|
|
|
|
|
**Kuelewa usanifu:**
|
|
|
- **Inatenganisha** masuala kati ya muundo (HTML), tabia (JavaScript), na uwasilishaji (CSS)
|
|
|
- **Inadumisha** muundo rahisi wa faili ambao ni rahisi kuvinjari na kurekebisha
|
|
|
- **Inafuata** mazoea bora ya maendeleo ya wavuti kwa shirika na usimamizi
|
|
|
|
|
|
### Kujenga Msingi wa HTML: Muundo wa Semantiki kwa Ufikiaji
|
|
|
|
|
|
Hebu tuanze na muundo wa HTML. Maendeleo ya kisasa ya wavuti yanasisitiza "HTML ya semantiki" – kutumia vipengele vya HTML vinavyoelezea waziwazi kusudi lao, si tu muonekano wao. Hii inafanya programu yako ipatikane kwa wasomaji wa skrini, injini za utafutaji, na zana zingine.
|
|
|
|
|
|
**Kwa nini HTML ya semantiki ni muhimu**: Fikiria kuelezea programu yako ya gumzo kwa mtu kupitia simu. Ungeweza kusema "kuna kichwa na kichwa, eneo kuu ambapo mazungumzo yanaonekana, na fomu chini kwa kuandika ujumbe." HTML ya semantiki hutumia vipengele vinavyolingana na maelezo haya ya asili.
|
|
|
|
|
|
Unda `index.html` na markup hii iliyopangwa kwa uangalifu:
|
|
|
|
|
|
```html
|
|
|
<!DOCTYPE html>
|
|
|
<html lang="en">
|
|
|
<head>
|
|
|
<meta charset="UTF-8">
|
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
|
<title>AI Chat Assistant</title>
|
|
|
<link rel="stylesheet" href="styles.css">
|
|
|
</head>
|
|
|
<body>
|
|
|
<div class="chat-container">
|
|
|
<header class="chat-header">
|
|
|
<h1>AI Chat Assistant</h1>
|
|
|
<p>Ask me anything!</p>
|
|
|
</header>
|
|
|
|
|
|
<main class="chat-messages" id="messages" role="log" aria-live="polite">
|
|
|
<!-- Messages will be dynamically added here -->
|
|
|
</main>
|
|
|
|
|
|
<form class="chat-form" id="chatForm">
|
|
|
<div class="input-group">
|
|
|
<input
|
|
|
type="text"
|
|
|
id="messageInput"
|
|
|
placeholder="Type your message here..."
|
|
|
required
|
|
|
aria-label="Chat message input"
|
|
|
>
|
|
|
<button type="submit" id="sendBtn" aria-label="Send message">
|
|
|
Send
|
|
|
</button>
|
|
|
</div>
|
|
|
</form>
|
|
|
</div>
|
|
|
<script src="app.js"></script>
|
|
|
</body>
|
|
|
</html>
|
|
|
```
|
|
|
|
|
|
**Kuelewa kila kipengele cha HTML na kusudi lake:**
|
|
|
|
|
|
#### Muundo wa Hati
|
|
|
- **`<!DOCTYPE html>`**: Inaambia kivinjari hii ni HTML5 ya kisasa
|
|
|
- **`<html lang="en">`**: Inataja lugha ya ukurasa kwa wasomaji wa skrini na zana za tafsiri
|
|
|
- **`<meta charset="UTF-8">`**: Inahakikisha usimbaji sahihi wa herufi kwa maandishi ya kimataifa
|
|
|
- **`<meta name="viewport"...>`**: Inafanya ukurasa uweze kujibika kwa simu kwa kudhibiti zoom na kiwango
|
|
|
|
|
|
#### Vipengele vya Semantiki
|
|
|
- **`<header>`**: Inatambulisha wazi sehemu ya juu na kichwa na maelezo
|
|
|
- **`<main>`**: Inateua eneo kuu la maudhui (ambapo mazungumzo yanatokea)
|
|
|
- **`<form>`**: Sahihi semantiki kwa pembejeo ya mtumiaji, inawezesha urambazaji sahihi wa kibodi
|
|
|
|
|
|
#### Vipengele vya Ufikiaji
|
|
|
- **`role="log"`**: Inaambia wasomaji wa skrini eneo hili lina kumbukumbu ya mpangilio wa ujumbe
|
|
|
- **`aria-live="polite"`**: Inatangaza ujumbe mpya kwa wasomaji wa skrini bila kuingilia
|
|
|
- **`aria-label`**: Inatoa lebo za maelezo kwa vidhibiti vya fomu
|
|
|
- **`required`**: Kivinjari kinathibitisha kwamba watumiaji wanaingiza ujumbe kabla ya kutuma
|
|
|
|
|
|
#### Ujumuishaji wa CSS na JavaScript
|
|
|
- **`class` attributes**: Hutoa ndoano za mitindo kwa CSS (mfano, `chat-container`, `input-group`)
|
|
|
- **`id` attributes**: Inaruhusu JavaScript kupata na kudhibiti vipengele maalum
|
|
|
- **Mahali pa Script**: Faili ya JavaScript imepakizwa mwishoni ili HTML ipakizwe kwanza
|
|
|
|
|
|
**Kwa nini muundo huu unafanya kazi:**
|
|
|
- **Mtiririko wa kimantiki**: Kichwa → Maudhui kuu → Fomu ya pembejeo inalingana na mpangilio wa kusoma wa asili
|
|
|
- **Inapatikana kwa kibodi**: Watumiaji wanaweza kuzunguka vipengele vyote vya kuingiliana
|
|
|
- **Inafaa kwa wasomaji wa skrini**: Alama wazi na maelezo kwa watumiaji wenye ulemavu wa kuona
|
|
|
- **Inajibu kwa simu**: Lebo ya meta ya viewport inawezesha muundo unaojibika
|
|
|
- **Uboreshaji wa maendeleo**: Inafanya kazi hata kama CSS au JavaScript haijapakizwa
|
|
|
|
|
|
### Kuongeza JavaScript ya Kuingiliana: Mantiki ya Programu ya Kisasa ya Wavuti
|
|
|
|
|
|
Sasa hebu tujenge JavaScript inayofanya kiolesura chetu cha gumzo kiwe hai. Tutatumia mifumo ya kisasa ya JavaScript ambayo utakutana nayo katika maendeleo ya wavuti ya kitaalamu, ikiwa ni pamoja na madarasa ya ES6, async/await, na programu inayoendeshwa na matukio.
|
|
|
|
|
|
#### Kuelewa Usanifu wa Kisasa wa JavaScript
|
|
|
|
|
|
Badala ya kuandika msimbo wa utaratibu (mfululizo wa kazi zinazokimbia kwa mpangilio), tutaunda **usanifu wa msingi wa darasa**. Fikiria darasa kama mchoro wa kuunda vitu – kama vile mchoro wa mhandisi unaweza kutumika kujenga nyumba nyingi.
|
|
|
|
|
|
**Kwa nini kutumia madarasa kwa programu za wavuti?**
|
|
|
- **Shirika**: Utendaji wote unaohusiana umewekwa pamoja
|
|
|
- **Urejelezaji**: Unaweza kuunda matukio mengi ya gumzo kwenye ukurasa mmoja
|
|
|
- **Usimamizi**: Rahisi kutatua na kurekebisha vipengele maalum
|
|
|
- **Kiwango cha kitaalamu**: Muundo huu unatumika katika mifumo kama React, Vue, na Angular
|
|
|
|
|
|
Unda `app.js` na JavaScript hii ya kisasa, iliyopangwa vizuri:
|
|
|
|
|
|
```javascript
|
|
|
// app.js - Modern chat application logic
|
|
|
|
|
|
class ChatApp {
|
|
|
constructor() {
|
|
|
// Get references to DOM elements we'll need to manipulate
|
|
|
this.messages = document.getElementById("messages");
|
|
|
this.form = document.getElementById("chatForm");
|
|
|
this.input = document.getElementById("messageInput");
|
|
|
this.sendButton = document.getElementById("sendBtn");
|
|
|
|
|
|
// Configure your backend URL here
|
|
|
this.BASE_URL = "http://localhost:5000"; // Update this for your environment
|
|
|
this.API_ENDPOINT = `${this.BASE_URL}/hello`;
|
|
|
|
|
|
// Set up event listeners when the chat app is created
|
|
|
this.initializeEventListeners();
|
|
|
}
|
|
|
|
|
|
initializeEventListeners() {
|
|
|
// Listen for form submission (when user clicks Send or presses Enter)
|
|
|
this.form.addEventListener("submit", (e) => this.handleSubmit(e));
|
|
|
|
|
|
// Also listen for Enter key in the input field (better UX)
|
|
|
this.input.addEventListener("keypress", (e) => {
|
|
|
if (e.key === "Enter" && !e.shiftKey) {
|
|
|
e.preventDefault();
|
|
|
this.handleSubmit(e);
|
|
|
}
|
|
|
});
|
|
|
}
|
|
|
|
|
|
async handleSubmit(event) {
|
|
|
event.preventDefault(); // Prevent form from refreshing the page
|
|
|
|
|
|
const messageText = this.input.value.trim();
|
|
|
if (!messageText) return; // Don't send empty messages
|
|
|
|
|
|
// Provide user feedback that something is happening
|
|
|
this.setLoading(true);
|
|
|
|
|
|
// Add user message to chat immediately (optimistic UI)
|
|
|
this.appendMessage(messageText, "user");
|
|
|
|
|
|
// Clear input field so user can type next message
|
|
|
this.input.value = '';
|
|
|
|
|
|
try {
|
|
|
// Call the AI API and wait for response
|
|
|
const reply = await this.callAPI(messageText);
|
|
|
|
|
|
// Add AI response to chat
|
|
|
this.appendMessage(reply, "assistant");
|
|
|
} catch (error) {
|
|
|
console.error('API Error:', error);
|
|
|
this.appendMessage("Sorry, I'm having trouble connecting right now. Please try again.", "error");
|
|
|
} finally {
|
|
|
// Re-enable the interface regardless of success or failure
|
|
|
this.setLoading(false);
|
|
|
}
|
|
|
}
|
|
|
|
|
|
async callAPI(message) {
|
|
|
const response = await fetch(this.API_ENDPOINT, {
|
|
|
method: "POST",
|
|
|
headers: {
|
|
|
"Content-Type": "application/json"
|
|
|
},
|
|
|
body: JSON.stringify({ message })
|
|
|
});
|
|
|
|
|
|
if (!response.ok) {
|
|
|
throw new Error(`HTTP error! status: ${response.status}`);
|
|
|
}
|
|
|
|
|
|
const data = await response.json();
|
|
|
return data.response;
|
|
|
}
|
|
|
|
|
|
appendMessage(text, role) {
|
|
|
const messageElement = document.createElement("div");
|
|
|
messageElement.className = `message ${role}`;
|
|
|
messageElement.innerHTML = `
|
|
|
<div class="message-content">
|
|
|
<span class="message-text">${this.escapeHtml(text)}</span>
|
|
|
<span class="message-time">${new Date().toLocaleTimeString()}</span>
|
|
|
</div>
|
|
|
`;
|
|
|
|
|
|
this.messages.appendChild(messageElement);
|
|
|
this.scrollToBottom();
|
|
|
}
|
|
|
|
|
|
escapeHtml(text) {
|
|
|
const div = document.createElement('div');
|
|
|
div.textContent = text;
|
|
|
return div.innerHTML;
|
|
|
}
|
|
|
|
|
|
scrollToBottom() {
|
|
|
this.messages.scrollTop = this.messages.scrollHeight;
|
|
|
}
|
|
|
|
|
|
setLoading(isLoading) {
|
|
|
this.sendButton.disabled = isLoading;
|
|
|
this.input.disabled = isLoading;
|
|
|
this.sendButton.textContent = isLoading ? "Sending..." : "Send";
|
|
|
}
|
|
|
}
|
|
|
|
|
|
// Initialize the chat application when the page loads
|
|
|
document.addEventListener("DOMContentLoaded", () => {
|
|
|
new ChatApp();
|
|
|
});
|
|
|
```
|
|
|
|
|
|
#### Kuelewa Kila Dhana ya JavaScript
|
|
|
|
|
|
**Muundo wa Darasa la ES6**:
|
|
|
```javascript
|
|
|
class ChatApp {
|
|
|
constructor() {
|
|
|
// This runs when you create a new ChatApp instance
|
|
|
// It's like the "setup" function for your chat
|
|
|
}
|
|
|
|
|
|
methodName() {
|
|
|
// Methods are functions that belong to the class
|
|
|
// They can access class properties using "this"
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**Mfumo wa Async/Await**:
|
|
|
```javascript
|
|
|
// Old way (callback hell):
|
|
|
fetch(url)
|
|
|
.then(response => response.json())
|
|
|
.then(data => console.log(data))
|
|
|
.catch(error => console.error(error));
|
|
|
|
|
|
// Modern way (async/await):
|
|
|
try {
|
|
|
const response = await fetch(url);
|
|
|
const data = await response.json();
|
|
|
console.log(data);
|
|
|
} catch (error) {
|
|
|
console.error(error);
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**Programu Inayoendeshwa na Matukio**:
|
|
|
Badala ya kuangalia kila mara ikiwa kitu kimetokea, tunasikiliza matukio:
|
|
|
```javascript
|
|
|
// When form is submitted, run handleSubmit
|
|
|
this.form.addEventListener("submit", (e) => this.handleSubmit(e));
|
|
|
|
|
|
// When Enter key is pressed, also run handleSubmit
|
|
|
this.input.addEventListener("keypress", (e) => { /* ... */ });
|
|
|
```
|
|
|
|
|
|
**Manipulation ya DOM**:
|
|
|
```javascript
|
|
|
// Create new elements
|
|
|
const messageElement = document.createElement("div");
|
|
|
|
|
|
// Modify their properties
|
|
|
messageElement.className = "message user";
|
|
|
messageElement.innerHTML = "Hello world!";
|
|
|
|
|
|
// Add to the page
|
|
|
this.messages.appendChild(messageElement);
|
|
|
```
|
|
|
|
|
|
#### Usalama na Mazoea Bora
|
|
|
|
|
|
**Kuzuia XSS**:
|
|
|
```javascript
|
|
|
escapeHtml(text) {
|
|
|
const div = document.createElement('div');
|
|
|
div.textContent = text; // This automatically escapes HTML
|
|
|
return div.innerHTML;
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**Kwa nini hii ni muhimu**: Ikiwa mtumiaji anaandika `<script>alert('hack')</script>`, kazi hii inahakikisha inaonyeshwa kama maandishi badala ya kutekelezwa kama msimbo.
|
|
|
|
|
|
**Kushughulikia Makosa**:
|
|
|
```javascript
|
|
|
try {
|
|
|
const reply = await this.callAPI(messageText);
|
|
|
this.appendMessage(reply, "assistant");
|
|
|
} catch (error) {
|
|
|
// Show user-friendly error instead of breaking the app
|
|
|
this.appendMessage("Sorry, I'm having trouble...", "error");
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**Mazingatio ya Uzoefu wa Mtumiaji**:
|
|
|
- **UI ya Optimistic**: Ongeza ujumbe wa mtumiaji mara moja, usisubiri majibu ya seva
|
|
|
- **Hali za kupakia**: Lemaza vifungo na onyesha "Inatuma..." wakati wa kusubiri
|
|
|
- **Auto-scroll**: Weka ujumbe mpya zaidi unaoonekana
|
|
|
- **Uthibitishaji wa pembejeo**: Usitume ujumbe tupu
|
|
|
- **Njia za mkato za kibodi**: Funguo ya Enter inatuma ujumbe (kama programu halisi za gumzo)
|
|
|
|
|
|
#### Kuelewa Mtiririko wa Programu
|
|
|
|
|
|
1. **Ukurasa unapakizwa** → Tukio la `DOMContentLoaded` linatokea → `new ChatApp()` linaundwa
|
|
|
2. **Constructor inaendeshwa** → Inapata marejeleo ya vipengele vya DOM → Inasanidi wasikilizaji wa matukio
|
|
|
3. **Mtumiaji anaandika ujumbe** → Anabonyeza Enter au anabonyeza Tuma → `handleSubmit` inaendeshwa
|
|
|
4. **handleSubmit** → Inathibitisha pembejeo → Ina
|
|
|
Muundo huu unaweza kupanuka – unaweza kuongeza vipengele kama kuhariri ujumbe, kupakia faili, au nyuzi nyingi za mazungumzo bila kuandika upya muundo wa msingi.
|
|
|
|
|
|
### Kustaili Kiolesura Chako cha Gumzo
|
|
|
|
|
|
Sasa hebu tuunde kiolesura cha kisasa, kinachovutia kwa CSS. Staili nzuri hufanya programu yako ionekane ya kitaalamu na kuboresha uzoefu wa mtumiaji kwa ujumla. Tutatumia vipengele vya kisasa vya CSS kama Flexbox, CSS Grid, na mali maalum kwa muundo unaojibika na unaopatikana.
|
|
|
|
|
|
Unda `styles.css` na staili hizi za kina:
|
|
|
|
|
|
```css
|
|
|
/* styles.css - Modern chat interface styling */
|
|
|
|
|
|
:root {
|
|
|
--primary-color: #2563eb;
|
|
|
--secondary-color: #f1f5f9;
|
|
|
--user-color: #3b82f6;
|
|
|
--assistant-color: #6b7280;
|
|
|
--error-color: #ef4444;
|
|
|
--text-primary: #1e293b;
|
|
|
--text-secondary: #64748b;
|
|
|
--border-radius: 12px;
|
|
|
--shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
|
|
|
}
|
|
|
|
|
|
* {
|
|
|
margin: 0;
|
|
|
padding: 0;
|
|
|
box-sizing: border-box;
|
|
|
}
|
|
|
|
|
|
body {
|
|
|
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
|
|
|
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
|
|
|
min-height: 100vh;
|
|
|
display: flex;
|
|
|
align-items: center;
|
|
|
justify-content: center;
|
|
|
padding: 20px;
|
|
|
}
|
|
|
|
|
|
.chat-container {
|
|
|
width: 100%;
|
|
|
max-width: 800px;
|
|
|
height: 600px;
|
|
|
background: white;
|
|
|
border-radius: var(--border-radius);
|
|
|
box-shadow: var(--shadow);
|
|
|
display: flex;
|
|
|
flex-direction: column;
|
|
|
overflow: hidden;
|
|
|
}
|
|
|
|
|
|
.chat-header {
|
|
|
background: var(--primary-color);
|
|
|
color: white;
|
|
|
padding: 20px;
|
|
|
text-align: center;
|
|
|
}
|
|
|
|
|
|
.chat-header h1 {
|
|
|
font-size: 1.5rem;
|
|
|
margin-bottom: 5px;
|
|
|
}
|
|
|
|
|
|
.chat-header p {
|
|
|
opacity: 0.9;
|
|
|
font-size: 0.9rem;
|
|
|
}
|
|
|
|
|
|
.chat-messages {
|
|
|
flex: 1;
|
|
|
padding: 20px;
|
|
|
overflow-y: auto;
|
|
|
display: flex;
|
|
|
flex-direction: column;
|
|
|
gap: 15px;
|
|
|
background: var(--secondary-color);
|
|
|
}
|
|
|
|
|
|
.message {
|
|
|
display: flex;
|
|
|
max-width: 80%;
|
|
|
animation: slideIn 0.3s ease-out;
|
|
|
}
|
|
|
|
|
|
.message.user {
|
|
|
align-self: flex-end;
|
|
|
}
|
|
|
|
|
|
.message.user .message-content {
|
|
|
background: var(--user-color);
|
|
|
color: white;
|
|
|
border-radius: var(--border-radius) var(--border-radius) 4px var(--border-radius);
|
|
|
}
|
|
|
|
|
|
.message.assistant {
|
|
|
align-self: flex-start;
|
|
|
}
|
|
|
|
|
|
.message.assistant .message-content {
|
|
|
background: white;
|
|
|
color: var(--text-primary);
|
|
|
border-radius: var(--border-radius) var(--border-radius) var(--border-radius) 4px;
|
|
|
border: 1px solid #e2e8f0;
|
|
|
}
|
|
|
|
|
|
.message.error .message-content {
|
|
|
background: var(--error-color);
|
|
|
color: white;
|
|
|
border-radius: var(--border-radius);
|
|
|
}
|
|
|
|
|
|
.message-content {
|
|
|
padding: 12px 16px;
|
|
|
box-shadow: var(--shadow);
|
|
|
position: relative;
|
|
|
}
|
|
|
|
|
|
.message-text {
|
|
|
display: block;
|
|
|
line-height: 1.5;
|
|
|
word-wrap: break-word;
|
|
|
}
|
|
|
|
|
|
.message-time {
|
|
|
display: block;
|
|
|
font-size: 0.75rem;
|
|
|
opacity: 0.7;
|
|
|
margin-top: 5px;
|
|
|
}
|
|
|
|
|
|
.chat-form {
|
|
|
padding: 20px;
|
|
|
border-top: 1px solid #e2e8f0;
|
|
|
background: white;
|
|
|
}
|
|
|
|
|
|
.input-group {
|
|
|
display: flex;
|
|
|
gap: 10px;
|
|
|
align-items: center;
|
|
|
}
|
|
|
|
|
|
#messageInput {
|
|
|
flex: 1;
|
|
|
padding: 12px 16px;
|
|
|
border: 2px solid #e2e8f0;
|
|
|
border-radius: var(--border-radius);
|
|
|
font-size: 1rem;
|
|
|
outline: none;
|
|
|
transition: border-color 0.2s ease;
|
|
|
}
|
|
|
|
|
|
#messageInput:focus {
|
|
|
border-color: var(--primary-color);
|
|
|
}
|
|
|
|
|
|
#messageInput:disabled {
|
|
|
background: #f8fafc;
|
|
|
opacity: 0.6;
|
|
|
cursor: not-allowed;
|
|
|
}
|
|
|
|
|
|
#sendBtn {
|
|
|
padding: 12px 24px;
|
|
|
background: var(--primary-color);
|
|
|
color: white;
|
|
|
border: none;
|
|
|
border-radius: var(--border-radius);
|
|
|
font-size: 1rem;
|
|
|
font-weight: 600;
|
|
|
cursor: pointer;
|
|
|
transition: background-color 0.2s ease;
|
|
|
min-width: 80px;
|
|
|
}
|
|
|
|
|
|
#sendBtn:hover:not(:disabled) {
|
|
|
background: #1d4ed8;
|
|
|
}
|
|
|
|
|
|
#sendBtn:disabled {
|
|
|
background: #94a3b8;
|
|
|
cursor: not-allowed;
|
|
|
}
|
|
|
|
|
|
@keyframes slideIn {
|
|
|
from {
|
|
|
opacity: 0;
|
|
|
transform: translateY(10px);
|
|
|
}
|
|
|
to {
|
|
|
opacity: 1;
|
|
|
transform: translateY(0);
|
|
|
}
|
|
|
}
|
|
|
|
|
|
/* Responsive design for mobile devices */
|
|
|
@media (max-width: 768px) {
|
|
|
body {
|
|
|
padding: 10px;
|
|
|
}
|
|
|
|
|
|
.chat-container {
|
|
|
height: calc(100vh - 20px);
|
|
|
border-radius: 8px;
|
|
|
}
|
|
|
|
|
|
.message {
|
|
|
max-width: 90%;
|
|
|
}
|
|
|
|
|
|
.input-group {
|
|
|
flex-direction: column;
|
|
|
gap: 10px;
|
|
|
}
|
|
|
|
|
|
#messageInput {
|
|
|
width: 100%;
|
|
|
}
|
|
|
|
|
|
#sendBtn {
|
|
|
width: 100%;
|
|
|
}
|
|
|
}
|
|
|
|
|
|
/* Accessibility improvements */
|
|
|
@media (prefers-reduced-motion: reduce) {
|
|
|
.message {
|
|
|
animation: none;
|
|
|
}
|
|
|
|
|
|
* {
|
|
|
transition: none !important;
|
|
|
}
|
|
|
}
|
|
|
|
|
|
/* Dark mode support */
|
|
|
@media (prefers-color-scheme: dark) {
|
|
|
.chat-container {
|
|
|
background: #1e293b;
|
|
|
color: #f1f5f9;
|
|
|
}
|
|
|
|
|
|
.chat-messages {
|
|
|
background: #0f172a;
|
|
|
}
|
|
|
|
|
|
.message.assistant .message-content {
|
|
|
background: #334155;
|
|
|
color: #f1f5f9;
|
|
|
border-color: #475569;
|
|
|
}
|
|
|
|
|
|
.chat-form {
|
|
|
background: #1e293b;
|
|
|
border-color: #475569;
|
|
|
}
|
|
|
|
|
|
#messageInput {
|
|
|
background: #334155;
|
|
|
color: #f1f5f9;
|
|
|
border-color: #475569;
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**Kuelewa muundo wa CSS:**
|
|
|
- **Inatumia** mali maalum za CSS (variables) kwa mandhari thabiti na matengenezo rahisi
|
|
|
- **Inatekeleza** mpangilio wa Flexbox kwa muundo unaojibika na mpangilio sahihi
|
|
|
- **Inajumuisha** michoro laini kwa kuonekana kwa ujumbe bila kuvuruga
|
|
|
- **Inatoa** utofauti wa kuona kati ya ujumbe wa mtumiaji, majibu ya AI, na hali za makosa
|
|
|
- **Inasaidia** muundo unaojibika unaofanya kazi kwenye vifaa vya mezani na simu
|
|
|
- **Inazingatia** upatikanaji kwa mapendeleo ya mwendo uliopunguzwa na uwiano sahihi wa utofauti
|
|
|
- **Inatoa** msaada wa hali ya giza kulingana na mapendeleo ya mfumo wa mtumiaji
|
|
|
|
|
|
### Kuseti URL ya Backend Yako
|
|
|
|
|
|
Hatua ya mwisho ni kusasisha `BASE_URL` katika JavaScript yako ili ilingane na seva yako ya backend:
|
|
|
|
|
|
```javascript
|
|
|
// For local development
|
|
|
this.BASE_URL = "http://localhost:5000";
|
|
|
|
|
|
// For GitHub Codespaces (replace with your actual URL)
|
|
|
this.BASE_URL = "https://your-codespace-name-5000.app.github.dev";
|
|
|
```
|
|
|
|
|
|
**Kujua URL ya backend yako:**
|
|
|
- **Maendeleo ya ndani**: Tumia `http://localhost:5000` ikiwa unakimbia frontend na backend zote ndani
|
|
|
- **Codespaces**: Tafuta URL ya backend yako katika kichupo cha Ports baada ya kufanya bandari ya 5000 kuwa ya umma
|
|
|
- **Uzalishaji**: Badilisha na kikoa chako halisi unapoweka kwenye huduma ya mwenyeji
|
|
|
|
|
|
> 💡 **Kidokezo cha Kupima**: Unaweza kupima backend yako moja kwa moja kwa kutembelea URL ya mizizi kwenye kivinjari chako. Unapaswa kuona ujumbe wa kukaribisha kutoka kwa seva yako ya FastAPI.
|
|
|
|
|
|
## Kupima na Kuweka
|
|
|
|
|
|
Sasa kwa kuwa una vipengele vya frontend na backend vilivyojengwa, hebu tujaribu kila kitu kinafanya kazi pamoja na kuchunguza chaguo za kuweka ili kushiriki msaidizi wako wa gumzo na wengine.
|
|
|
|
|
|
### Mtiririko wa Kupima wa Ndani
|
|
|
|
|
|
Fuata hatua hizi kupima programu yako kamili:
|
|
|
|
|
|
```mermaid
|
|
|
graph TD
|
|
|
A[Start Backend Server] --> B[Configure Environment Variables]
|
|
|
B --> C[Test API Endpoints]
|
|
|
C --> D[Open Frontend in Browser]
|
|
|
D --> E[Test Chat Functionality]
|
|
|
E --> F[Debug Any Issues]
|
|
|
```
|
|
|
|
|
|
**Mchakato wa kupima hatua kwa hatua:**
|
|
|
|
|
|
1. **Anzisha seva yako ya backend**:
|
|
|
```bash
|
|
|
cd backend
|
|
|
source venv/bin/activate # or venv\Scripts\activate on Windows
|
|
|
python api.py
|
|
|
```
|
|
|
|
|
|
2. **Thibitisha API inafanya kazi**:
|
|
|
- Fungua `http://localhost:5000` kwenye kivinjari chako
|
|
|
- Unapaswa kuona ujumbe wa kukaribisha kutoka kwa seva yako ya FastAPI
|
|
|
|
|
|
3. **Fungua frontend yako**:
|
|
|
- Nenda kwenye saraka ya frontend yako
|
|
|
- Fungua `index.html` kwenye kivinjari chako cha wavuti
|
|
|
- Au tumia kiendelezi cha Live Server cha VS Code kwa uzoefu bora wa maendeleo
|
|
|
|
|
|
4. **Jaribu utendaji wa gumzo**:
|
|
|
- Andika ujumbe kwenye uwanja wa kuingiza
|
|
|
- Bonyeza "Tuma" au bonyeza Enter
|
|
|
- Thibitisha AI inajibu ipasavyo
|
|
|
- Angalia console ya kivinjari kwa makosa yoyote ya JavaScript
|
|
|
|
|
|
### Kutatua Masuala ya Kawaida
|
|
|
|
|
|
| Tatizo | Dalili | Suluhisho |
|
|
|
|--------|--------|-----------|
|
|
|
| **Hitilafu ya CORS** | Frontend haiwezi kufikia backend | Hakikisha FastAPI CORSMiddleware imewekwa vizuri |
|
|
|
| **Hitilafu ya API Key** | Majibu ya 401 Unauthorized | Angalia variable ya mazingira ya `GITHUB_TOKEN` |
|
|
|
| **Muunganisho Umekataliwa** | Hitilafu za mtandao kwenye frontend | Thibitisha URL ya backend na kwamba seva ya Flask inafanya kazi |
|
|
|
| **Hakuna Jibu la AI** | Majibu tupu au makosa | Angalia magogo ya backend kwa masuala ya API au uthibitishaji |
|
|
|
|
|
|
**Hatua za kawaida za kutatua matatizo:**
|
|
|
- **Angalia** Console ya Zana za Msanidi Programu wa kivinjari kwa makosa ya JavaScript
|
|
|
- **Thibitisha** kichupo cha Mtandao kinaonyesha maombi na majibu ya API yaliyofanikiwa
|
|
|
- **Pitia** matokeo ya terminal ya backend kwa makosa ya Python au masuala ya API
|
|
|
- **Thibitisha** variables za mazingira zimepakiwa vizuri na zinapatikana
|
|
|
|
|
|
## Changamoto ya Wakala wa GitHub Copilot 🚀
|
|
|
|
|
|
Tumia hali ya Wakala kukamilisha changamoto ifuatayo:
|
|
|
|
|
|
**Maelezo:** Boresha msaidizi wa gumzo kwa kuongeza historia ya mazungumzo na uhifadhi wa ujumbe. Changamoto hii itakusaidia kuelewa jinsi ya kudhibiti hali katika programu za gumzo na kutekeleza uhifadhi wa data kwa uzoefu bora wa mtumiaji.
|
|
|
|
|
|
**Kichocheo:** Badilisha programu ya gumzo ili kujumuisha historia ya mazungumzo inayodumu kati ya vikao. Ongeza utendaji wa kuhifadhi ujumbe wa gumzo kwenye uhifadhi wa ndani, onyesha historia ya mazungumzo wakati ukurasa unapopakia, na ujumuisha kitufe cha "Futa Historia". Pia tekeleza viashiria vya kuandika na timestamps za ujumbe ili kufanya uzoefu wa gumzo uwe wa kweli zaidi.
|
|
|
|
|
|
Jifunze zaidi kuhusu [hali ya wakala](https://code.visualstudio.com/blogs/2025/02/24/introducing-copilot-agent-mode) hapa.
|
|
|
|
|
|
## Kazi: Jenga Msaidizi Wako wa AI Binafsi
|
|
|
|
|
|
Sasa utaunda utekelezaji wako wa msaidizi wa AI. Badala ya kurudia tu msimbo wa mafunzo, hii ni fursa ya kutumia dhana huku ukijenga kitu kinachoakisi maslahi yako na matumizi yako.
|
|
|
|
|
|
### Mahitaji ya Mradi
|
|
|
|
|
|
Hebu tuweke mradi wako na muundo safi, uliopangwa:
|
|
|
|
|
|
```text
|
|
|
my-ai-assistant/
|
|
|
├── backend/
|
|
|
│ ├── api.py # Your FastAPI server
|
|
|
│ ├── llm.py # AI integration functions
|
|
|
│ ├── .env # Your secrets (keep this safe!)
|
|
|
│ └── requirements.txt # Python dependencies
|
|
|
├── frontend/
|
|
|
│ ├── index.html # Your chat interface
|
|
|
│ ├── app.js # The JavaScript magic
|
|
|
│ └── styles.css # Make it look amazing
|
|
|
└── README.md # Tell the world about your creation
|
|
|
```
|
|
|
|
|
|
### Kazi za Msingi za Utekelezaji
|
|
|
|
|
|
**Maendeleo ya Backend:**
|
|
|
- **Chukua** msimbo wetu wa FastAPI na uufanye wako
|
|
|
- **Unda** utu wa kipekee wa AI – labda msaidizi wa kupika mwenye msaada, mshirika wa uandishi wa ubunifu, au rafiki wa kujifunza?
|
|
|
- **Ongeza** utunzaji mzuri wa makosa ili programu yako isivunjike wakati mambo yanapokwenda vibaya
|
|
|
- **Andika** nyaraka wazi kwa yeyote anayetaka kuelewa jinsi API yako inavyofanya kazi
|
|
|
|
|
|
**Maendeleo ya Frontend:**
|
|
|
- **Jenga** kiolesura cha gumzo kinachohisi kuwa cha angavu na cha kukaribisha
|
|
|
- **Andika** JavaScript safi, ya kisasa ambayo ungejivunia kuonyesha kwa watengenezaji wengine
|
|
|
- **Buni** staili maalum zinazoakisi utu wa AI yako – za kufurahisha na za rangi? Safi na ndogo? Ni juu yako kabisa!
|
|
|
- **Hakikisha** inafanya kazi vizuri kwenye simu na kompyuta
|
|
|
|
|
|
**Mahitaji ya Kubinafsisha:**
|
|
|
- **Chagua** jina la kipekee na utu kwa msaidizi wako wa AI – labda kitu kinachoakisi maslahi yako au matatizo unayotaka kutatua
|
|
|
- **Binafsisha** muundo wa kuona ili ulingane na hali ya msaidizi wako
|
|
|
- **Andika** ujumbe wa kukaribisha wa kuvutia unaowafanya watu watake kuanza kuzungumza
|
|
|
- **Jaribu** msaidizi wako na aina tofauti za maswali ili kuona jinsi unavyojibu
|
|
|
|
|
|
### Mawazo ya Uboreshaji (Hiari)
|
|
|
|
|
|
Unataka kuchukua mradi wako hadi kiwango kingine? Hapa kuna mawazo ya kufurahisha ya kuchunguza:
|
|
|
|
|
|
| Kipengele | Maelezo | Ujuzi Utakaofanya Mazoezi |
|
|
|
|-----------|---------|--------------------------|
|
|
|
| **Historia ya Ujumbe** | Kumbuka mazungumzo hata baada ya upya wa ukurasa | Kufanya kazi na localStorage, kushughulikia JSON |
|
|
|
| **Viashiria vya Kuandika** | Onyesha "AI inaandika..." wakati wa kusubiri majibu | Michoro ya CSS, programu ya async |
|
|
|
| **Timestamps za Ujumbe** | Onyesha wakati kila ujumbe ulitumwa | Uundaji wa tarehe/muda, muundo wa UX |
|
|
|
| **Hamisha Gumzo** | Waruhusu watumiaji kupakua mazungumzo yao | Kushughulikia faili, usafirishaji wa data |
|
|
|
| **Kubadilisha Mandhari** | Kubadili hali ya mwanga/giza | Mali za CSS, mapendeleo ya mtumiaji |
|
|
|
| **Ingizo la Sauti** | Ongeza utendaji wa hotuba-kwa-maandishi | API za Wavuti, upatikanaji |
|
|
|
|
|
|
### Kupima na Nyaraka
|
|
|
|
|
|
**Uhakikisho wa Ubora:**
|
|
|
- **Jaribu** programu yako na aina mbalimbali za pembejeo na hali za ukingo
|
|
|
- **Thibitisha** muundo unaojibika unafanya kazi kwenye saizi tofauti za skrini
|
|
|
- **Angalia** upatikanaji kwa urambazaji wa kibodi na wasomaji wa skrini
|
|
|
- **Thibitisha** HTML na CSS kwa kufuata viwango
|
|
|
|
|
|
**Mahitaji ya Nyaraka:**
|
|
|
- **Andika** README.md inayoelezea mradi wako na jinsi ya kuendesha
|
|
|
- **Jumuisha** picha za skrini za kiolesura chako cha gumzo kikiwa kimefanya kazi
|
|
|
- **Andika** vipengele vyovyote vya kipekee au ubinafsishaji ulioongeza
|
|
|
- **Toa** maelekezo wazi ya usanidi kwa watengenezaji wengine
|
|
|
|
|
|
### Miongozo ya Uwasilishaji
|
|
|
|
|
|
**Vitu vya Mradi:**
|
|
|
1. Folda kamili ya mradi na msimbo wote wa chanzo
|
|
|
2. README.md yenye maelezo ya mradi na maelekezo ya usanidi
|
|
|
3. Picha za skrini zinazoonyesha msaidizi wako wa gumzo ukifanya kazi
|
|
|
4. Tafakari fupi juu ya kile ulichojifunza na changamoto ulizokutana nazo
|
|
|
|
|
|
**Vigezo vya Tathmini:**
|
|
|
- **Utendaji**: Je, msaidizi wa gumzo unafanya kazi kama inavyotarajiwa?
|
|
|
- **Ubora wa Msimbo**: Je, msimbo umeandaliwa vizuri, umeandikwa maoni, na unadumika?
|
|
|
- **Muundo**: Je, kiolesura ni cha kuvutia na rahisi kutumia?
|
|
|
- **Ubunifu**: Je, utekelezaji wako ni wa kipekee na wa kibinafsi kiasi gani?
|
|
|
- **Nyaraka**: Je, maelekezo ya usanidi ni wazi na kamili?
|
|
|
|
|
|
> 💡 **Kidokezo cha Mafanikio**: Anza na mahitaji ya msingi kwanza, kisha ongeza uboreshaji mara tu kila kitu kinapofanya kazi. Lenga kuunda uzoefu wa msingi uliosuguliwa kabla ya kuongeza vipengele vya hali ya juu.
|
|
|
|
|
|
## Suluhisho
|
|
|
|
|
|
[Suluhisho](./solution/README.md)
|
|
|
|
|
|
## Changamoto za Ziada
|
|
|
|
|
|
Uko tayari kuchukua msaidizi wako wa AI hadi kiwango kingine? Jaribu changamoto hizi za hali ya juu ambazo zitakufundisha zaidi kuhusu ujumuishaji wa AI na maendeleo ya wavuti.
|
|
|
|
|
|
### Kubinafsisha Utu
|
|
|
|
|
|
Uchawi halisi hutokea unapompa msaidizi wako wa AI utu wa kipekee. Jaribu vichocheo tofauti vya mfumo kuunda wasaidizi maalum:
|
|
|
|
|
|
**Mfano wa Msaidizi wa Kitaalamu:**
|
|
|
```python
|
|
|
call_llm(message, "You are a professional business consultant with 20 years of experience. Provide structured, actionable advice with specific steps and considerations.")
|
|
|
```
|
|
|
|
|
|
**Mfano wa Msaidizi wa Uandishi wa Ubunifu:**
|
|
|
```python
|
|
|
call_llm(message, "You are an enthusiastic creative writing coach. Help users develop their storytelling skills with imaginative prompts and constructive feedback.")
|
|
|
```
|
|
|
|
|
|
**Mfano wa Mshauri wa Kiufundi:**
|
|
|
```python
|
|
|
call_llm(message, "You are a patient senior developer who explains complex programming concepts using simple analogies and practical examples.")
|
|
|
```
|
|
|
|
|
|
### Uboreshaji wa Frontend
|
|
|
|
|
|
Badilisha kiolesura chako cha gumzo na uboreshaji huu wa kuona na wa kiutendaji:
|
|
|
|
|
|
**Vipengele vya CSS vya Juu:**
|
|
|
- **Tekeleza** michoro laini za ujumbe na mabadiliko
|
|
|
- **Ongeza** miundo maalum ya baluni za gumzo na maumbo ya CSS na gradients
|
|
|
- **Unda** michoro ya kiashiria cha kuandika kwa wakati AI "inawaza"
|
|
|
- **Buni** maoni ya emoji au mfumo wa ukadiriaji wa ujumbe
|
|
|
|
|
|
**Uboreshaji wa JavaScript:**
|
|
|
- **Ongeza** njia za mkato za kibodi (Ctrl+Enter kwa kutuma, Escape kufuta pembejeo)
|
|
|
- **Tekeleza** utendaji wa kutafuta na kuchuja ujumbe
|
|
|
- **Unda** kipengele cha kusafirisha mazungumzo (pakua kama maandishi au JSON)
|
|
|
- **Ongeza** uhifadhi wa kiotomatiki kwenye localStorage ili kuzuia kupoteza ujumbe
|
|
|
|
|
|
### Ujumuishaji wa AI wa Juu
|
|
|
|
|
|
**Utu Mbalimbali wa AI:**
|
|
|
- **Unda** menyu ya kushuka kubadili kati ya utu tofauti wa AI
|
|
|
- **Hifadhi** utu unaopendelewa na mtumiaji kwenye localStorage
|
|
|
- **Tekeleza** ubadilishaji wa muktadha unaodumisha mtiririko wa mazungumzo
|
|
|
|
|
|
**Vipengele vya Jibu la Smart:**
|
|
|
- **Ongeza** ufahamu wa muktadha wa mazungumzo (AI inakumbuka ujumbe wa awali)
|
|
|
- **Tekeleza** mapendekezo ya smart kulingana na mada ya mazungumzo
|
|
|
- **Unda** vifungo vya jibu la haraka kwa maswali ya kawaida
|
|
|
|
|
|
> 🎯 **Lengo la Kujifunza**: Changamoto hizi za ziada zinakusaidia kuelewa mifumo ya hali ya juu ya maendeleo ya wavuti na mbinu za ujumuishaji wa AI zinazotumika katika programu za uzalishaji.
|
|
|
|
|
|
## Muhtasari na Hatua Zifuatazo
|
|
|
|
|
|
Hongera! Umefanikiwa kujenga msaidizi kamili wa gumzo unaotumia AI kutoka mwanzo. Mradi huu umekupa uzoefu wa vitendo na teknolojia za kisasa za maendeleo ya wavuti na ujumuishaji wa AI – ujuzi ambao unazidi kuwa muhimu katika mazingira ya teknolojia ya leo.
|
|
|
|
|
|
### Uliyofanikiwa
|
|
|
|
|
|
Katika somo hili, umemudu teknolojia na dhana kadhaa muhimu:
|
|
|
|
|
|
**Maendeleo ya Backend:**
|
|
|
- **Umeunganisha** na GitHub Models API kwa utendaji wa AI
|
|
|
- **Umejenga** API ya RESTful kwa kutumia Flask na utunzaji sahihi wa makosa
|
|
|
- **Umetekeleza** uthibitishaji salama kwa kutumia variables za mazingira
|
|
|
- **Umesanidi** CORS kwa maombi ya asili tofauti kati ya frontend na backend
|
|
|
|
|
|
**Maendeleo ya Frontend:**
|
|
|
- **Umeunda** kiolesura cha gumzo kinachojibika kwa kutumia HTML ya kimantiki
|
|
|
- **Umetekeleza** JavaScript ya kisasa kwa async/await na muundo wa msingi wa darasa
|
|
|
- **Umebuni** kiolesura cha mtumiaji kinachovutia kwa CSS Grid, Flexbox, na michoro
|
|
|
- **Umeongeza** vipengele vya upatikanaji na kanuni za muundo unaojibika
|
|
|
|
|
|
**Ujumuishaji wa Full-Stack:**
|
|
|
- **Umeunganisha** frontend na backend kupitia maombi ya API ya HTTP
|
|
|
- **Umeshughulikia** mwingiliano wa mtumiaji wa wakati halisi na mtiririko wa data wa async
|
|
|
- **Umetekeleza** utunzaji wa makosa na maoni ya mtumiaji katika programu nzima
|
|
|
- **Umejaribu** mtiririko kamili wa programu kutoka pembejeo ya mtumiaji hadi jibu la AI
|
|
|
|
|
|
### Matokeo Muhimu ya Kujifunza
|
|
|
|
|
|
```mermaid
|
|
|
mindmap
|
|
|
root((AI Chat App Skills))
|
|
|
API Integration
|
|
|
Authentication
|
|
|
Error Handling
|
|
|
Async Programming
|
|
|
Web Development
|
|
|
HTML5 Semantics
|
|
|
Modern CSS
|
|
|
ES6+ JavaScript
|
|
|
User Experience
|
|
|
Responsive Design
|
|
|
Accessibility
|
|
|
Real-time Interaction
|
|
|
AI Understanding
|
|
|
Prompt Engineering
|
|
|
Model Parameters
|
|
|
Conversation Flow
|
|
|
```
|
|
|
|
|
|
Mradi huu umekutambulisha kwa misingi ya kujenga programu zinazotumia AI, ambayo inawakilisha mustakabali wa maendeleo ya wavuti. Sasa unaelewa jinsi ya kuunganisha uwezo wa AI katika programu za wavuti za jadi, kuunda uzoefu wa mtumiaji unaovutia ambao unahisi kuwa wa akili na unaojibika.
|
|
|
|
|
|
### Matumizi ya Kitaalamu
|
|
|
|
|
|
Ujuzi uliouendeleza katika somo hili unatumika moja kwa moja kwa kazi za kisasa za maendeleo ya programu:
|
|
|
|
|
|
- **Maendeleo ya wavuti ya full-stack** kwa kutumia mifumo ya kisasa na API
|
|
|
- **Ujumuishaji wa AI** katika programu za wavuti na programu za simu
|
|
|
- **Ubunifu na maendeleo ya API** kwa usanifu wa huduma ndogo
|
|
|
- **Maendeleo ya kiolesura cha mtumiaji** kwa kuzingatia upatikanaji na muundo unaojibika
|
|
|
- **Mazoezi ya DevOps** ikiwa ni pamoja na usanidi wa mazingira na uwekaji
|
|
|
|
|
|
### Kuendeleza Safari Yako ya Maendeleo ya AI
|
|
|
|
|
|
**Hatua Zifuatazo za Kujifunza:**
|
|
|
- **Chunguza** mifano ya AI ya hali ya juu zaidi na API (GPT-4, Claude, Gemini)
|
|
|
- **Jifunze** kuhusu mbinu za uhandisi wa kichocheo kwa majibu bora ya AI
|
|
|
- **Soma** muundo wa mazungumzo na kanuni za uzoefu wa mtumiaji wa chatbot
|
|
|
- **Chunguza** usalama wa AI, maadili, na mazoea ya maendeleo ya AI yenye uwajibikaji
|
|
|
- **Jenga** programu ngumu zaidi na kumbukumbu ya mazungumzo na ufahamu wa muktadha
|
|
|
|
|
|
**Mawazo ya Mradi wa Juu:**
|
|
|
- Vyumba vya gumzo vya watumiaji wengi na usimamizi wa AI
|
|
|
- Chatbots za huduma kwa wateja zinazotumia AI
|
|
|
- Wasaidizi wa kufundisha elimu na ujifunzaji wa kibinafsi
|
|
|
-
|
|
|
- **Kuelekeza bandari** kwa ajili ya kujaribu programu zako
|
|
|
|
|
|
**Kile Codespaces inatoa:**
|
|
|
- **Inaondoa** matatizo ya usanidi na mipangilio ya mazingira ya ndani
|
|
|
- **Inatoa** mazingira ya maendeleo yanayofanana kwenye vifaa tofauti
|
|
|
- **Inajumuisha** zana na viendelezi vilivyosanidiwa awali kwa ajili ya maendeleo ya wavuti
|
|
|
- **Inatoa** muunganisho wa moja kwa moja na GitHub kwa udhibiti wa toleo na ushirikiano
|
|
|
|
|
|
> 🚀 **Ushauri wa Wataalamu**: Codespaces ni bora kwa kujifunza na kuunda programu za AI kwa sababu inashughulikia usanidi wa mazingira magumu moja kwa moja, ikikuruhusu kuzingatia kujenga na kujifunza badala ya matatizo ya usanidi.
|
|
|
|
|
|
---
|
|
|
|
|
|
**Kanusho**:
|
|
|
Hati hii imetafsiriwa kwa kutumia huduma ya tafsiri ya AI [Co-op Translator](https://github.com/Azure/co-op-translator). Ingawa tunajitahidi kwa usahihi, tafadhali fahamu kuwa tafsiri za kiotomatiki zinaweza kuwa na makosa au kutokuwa sahihi. Hati ya asili katika lugha yake ya awali inapaswa kuzingatiwa kama chanzo cha mamlaka. Kwa taarifa muhimu, tafsiri ya kitaalamu ya binadamu inapendekezwa. Hatutawajibika kwa kutoelewana au tafsiri zisizo sahihi zinazotokana na matumizi ya tafsiri hii. |
