# Създайте чат асистент с изкуствен интелект
Спомняте ли си в Star Trek, когато екипажът спокойно разговаряше с компютъра на кораба, задавайки му сложни въпроси и получавайки обмислени отговори? Това, което в 60-те години на миналия век изглеждаше като чиста научна фантастика, сега е нещо, което можете да изградите, използвайки уеб технологии, които вече познавате.
В този урок ще създадем чат асистент с изкуствен интелект, използвайки HTML, CSS, JavaScript и някаква бекенд интеграция. Ще откриете как същите умения, които сте научили, могат да се свържат с мощни AI услуги, които разбират контекста и генерират смислени отговори.
Помислете за AI като достъп до огромна библиотека, която не само може да намери информация, но и да я синтезира в последователни отговори, пригодени към вашите конкретни въпроси. Вместо да търсите сред хиляди страници, получавате директни, контекстуални отговори.
Интеграцията става чрез познати уеб технологии, които работят заедно. HTML създава интерфейса за чат, CSS се грижи за визуалния дизайн, JavaScript управлява потребителските взаимодействия, а бекенд API свързва всичко с AI услугите. Това е подобно на начина, по който различни секции на оркестъра работят заедно, за да създадат симфония.
По същността си ние изграждаме мост между естествената човешка комуникация и машинната обработка. Ще научите както техническата реализация на интеграцията с AI услуги, така и дизайнерските модели, които правят взаимодействията интуитивни.
Към края на този урок, интеграцията с AI ще ви се струва по-малко като мистериозен процес и повече като още един API, с който можете да работите. Ще разберете основните модели, които захранват приложения като ChatGPT и Claude, използвайки същите принципи за уеб разработка, които вече знаете.
## ⚡ Какво можете да направите през следващите 5 минути
**Бърз старт за заети разработчици**
```mermaid
flowchart LR
A[⚡ 5 минути] --> B[Вземи GitHub токен]
B --> C[Тествай AI площадка]
C --> D[Копирай Python код]
D --> E[Виж AI отговори]
```
- **Минута 1**: Посетете [GitHub Models Playground](https://github.com/marketplace/models/azure-openai/gpt-4o-mini/playground) и създайте личен токен за достъп
- **Минута 2**: Тествайте AI взаимодействия директно в интерфейса на playground
- **Минута 3**: Кликнете на таба „Code“ и копирайте Python кода
- **Минута 4**: Стартирайте кода локално с вашия токен: `GITHUB_TOKEN=your_token python test.py`
- **Минута 5**: Гледайте как първият AI отговор се генерира от вашия код
**Бърз тестов код**:
```python
import os
from openai import OpenAI
client = OpenAI(
base_url="https://models.github.ai/inference",
api_key="your_token_here"
)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Hello AI!"}],
model="openai/gpt-4o-mini"
)
print(response.choices[0].message.content)
```
**Защо е важно**: За 5 минути ще изпитате магията на програмируемото AI взаимодействие. Това представлява основната градивна единица, която задвижва всяко AI приложение, което използвате.
Ето как ще изглежда завършеният ви проект:
## 🗺️ Вашето пътешествие в развитието на AI приложения
```mermaid
journey
title От Уеб Разработка до Интеграция на ИИ
section Разбиране на Основите на ИИ
Открийте концепции за генеративен ИИ: 4: You
Изследвайте платформата GitHub Models: 6: You
Овладейте параметрите и подканите за ИИ: 8: You
section Интеграция на Backend
Изградете Python API сървър: 5: You
Реализирайте извиквания на функции за ИИ: 7: You
Управлявайте асинхронни операции: 8: You
section Frontend Разработка
Създайте модерен интерфейс за чат: 6: You
Овладейте интеракции в реално време: 8: You
Изградете адаптивно потребителско изживяване: 9: You
section Професионално Приложение
Деплойвайте цялостна ИИ система: 7: You
Оптимизирайте модели на производителност: 8: You
Създайте приложение готово за продукция: 9: You
```
**Крайната ви цел**: Към края на този урок ще сте изградили пълноценно AI захранвано приложение, използвайки същите технологии и модели, които задвижват модерни AI асистенти като ChatGPT, Claude и Google Bard.
## Разбиране на AI: От мистерия към майсторство
Преди да пристъпим към кода, нека разберем с какво работим. Ако сте използвали API-та преди, знаете основния модел: изпращате заявка, получавате отговор.
AI API-тата следват подобна структура, но вместо да извличат предварително съхранени данни от база, те генерират нови отговори въз основа на модели, научени от огромни количества текст. Помислете за това като разликата между библиотечна каталог система и знаещ библиотекар, който може да синтезира информация от няколко източника.
### Какво всъщност е "Генеративен AI"?
Помислете как Розетският камък позволи на учените да разберат египетските йероглифни писмена, намирайки модели между известен и неизвестен език. AI моделите работят по подобен начин – те намират модели в огромни количества текст, за да разберат как работи езикът, след което използват тези модели, за да генерират подходящи отговори на нови въпроси.
**Нека го обясня с прост пример:**
- **Традиционна база данни**: Като да поискате акт за раждане – получавате точно същия документ всеки път
- **Търсачка**: Като да поискате от библиотекар книги за котки – те ви показват наличното
- **Генеративен AI**: Като да попитате знаещ приятел за котки – той ви разказва интересни неща с свои думи, съобразени с това, което искате да знаете
```mermaid
graph LR
A[Вашият Въпрос] --> B[AI Модел]
B --> C[Разпознаване на Шаблони]
C --> D[Генериране на Съдържание]
D --> E[Контекстуален Отговор]
F[Обучаващи Данни Книги, Статии, Уеб] --> B
```
### Как се обучават AI модели (опростена версия)
AI моделите се обучават чрез излагане на огромни бази данни, съдържащи текст от книги, статии и разговори. Чрез този процес те идентифицират модели в:
- Как мислите се структурират в писмена комуникация
- Кои думи често се появяват заедно
- Как обикновено протичат разговорите
- Контекстуалните разлики между формална и неформална комуникация
**Това е подобно на това как археолозите дешифрират древни езици**: те анализират хиляди примери, за да разберат граматика, речник и културен контекст, и в крайна сметка могат да разчитат нови текстове, използвайки тези научени модели.
### Защо GitHub Models?
Използваме GitHub Models по една много практична причина – те ни дават достъп до AI на корпоративно ниво, без да се налага да изграждаме собствена AI инфраструктура (което, повярвайте ми, не искате да правите сега!). Помислете за това като използването на API за времето, вместо да се опитвате сами да предсказвате времето, като поставяте метеостанции навсякъде.
Всъщност това е "AI като услуга" и най-хубавото? Получавате безплатен старт, така че можете да експериментирате без да се притеснявате за големи сметки.
```mermaid
graph LR
A[Потребителски интерфейс за чат] --> B[Вашият бекенд API]
B --> C[GitHub API за модели]
C --> D[Обработка на AI модел]
D --> C
C --> B
B --> A
```
Ще използваме GitHub Models за нашата бекенд интеграция, която предоставя достъп до професионални AI възможности чрез приятелски настроен към разработчиците интерфейс. [GitHub Models Playground](https://github.com/marketplace/models/azure-openai/gpt-4o-mini/playground) служи като тестова среда, където можете да експериментирате с различни AI модели и да разберете техните възможности, преди да ги имплементирате в кода.
## 🧠 Екосистема за разработка на AI приложения
```mermaid
mindmap
root((Развитие на изкуствен интелект))
Understanding AI
Generative Models
Разпознаване на модели
Генериране на съдържание
Разбиране на контекста
Синтез на отговори
AI Parameters
Контрол на температурата
Ограничения на токените
Филтриране Top-p
Системни подкани
Backend Architecture
API Integration
GitHub Модели
Удостоверяване
Обработка на заявки
Управление на грешки
Python Infrastructure
FastAPI Framework
Асинхронни операции
Сигурност на средата
Конфигурация на CORS
Frontend Experience
Chat Interface
Актуализации в реално време
История на съобщенията
Обратна връзка от потребители
Състояния на зареждане
Modern Web Tech
ES6 Класове
Async/Await
Манипулация на DOM
Обработка на събития
Professional Patterns
Security Best Practices
Управление на токени
Валидиране на входни данни
Предотвратяване на XSS
Граници на грешки
Production Readiness
Оптимизация на производителността
Адаптивен дизайн
Достъпност
Стратегии за тестване
```
**Основен принцип**: Разработката на AI приложения комбинира традиционни умения за уеб разработка с интеграция на AI услуги, създавайки интелигентни приложения, които се усещат естествени и отзивчиви за потребителите.
**Ето какво прави playground толкова полезен:**
- **Пробвайте** различни AI модели като GPT-4o-mini, Claude и други (всички безплатни!)
- **Тествайте** идеите и подканите си преди да напишете какъвто и да е код
- **Вземете** готови кодови фрагменти на вашия любим програмния език
- **Настройте** параметри като ниво на креативност и дължина на отговорите, за да видите как влияят на резултата
След като се поиграете малко, просто кликнете на таб „Code“ и изберете езика си за програмиране, за да получите кода, който ще ви трябва.
## Настройване на Python бекенд интеграция
Сега нека имплементираме AI интеграцията с Python. Python е отличен за AI приложения заради простия синтаксис и мощните библиотеки. Ще започнем с кода от GitHub Models playground и после ще го пренапишем във функция, готова за използване в производство.
### Разбиране на базовата имплементация
Когато вземете Python кода от playground, ще получите нещо такова. Не се притеснявайте, ако изглежда много на пръв поглед – нека го разгледаме на части:
```python
"""Run this model in Python
> pip install openai
"""
import os
from openai import OpenAI
# За да се удостоверите с модела, ще трябва да генерирате личен достъп токен (PAT) в настройките на вашия GitHub.
# Създайте вашия PAT токен, като следвате инструкциите тук: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
client = OpenAI(
base_url="https://models.github.ai/inference",
api_key=os.environ["GITHUB_TOKEN"],
)
response = client.chat.completions.create(
messages=[
{
"role": "system",
"content": "",
},
{
"role": "user",
"content": "What is the capital of France?",
}
],
model="openai/gpt-4o-mini",
temperature=1,
max_tokens=4096,
top_p=1
)
print(response.choices[0].message.content)
```
**Ето какво се случва в този код:**
- **Импортираме** необходимите инструменти: `os` за четене на променливи на средата и `OpenAI` за общуване с AI
- **Настройваме** клиента OpenAI да сочи към AI сървърите на GitHub, а не директно към OpenAI
- **Авторизираме** се с особен GitHub токен (повече за това след малко!)
- **Структурираме** разговора с различни "роли" – помислете за това като за сцена в театрална постановка
- **Изпращаме** заявка към AI с някои фини настройки
- **Извличаме** фактическото текстово съдържание на отговора от всички данни, които получаваме
### Разбиране на ролевите съобщения: AI рамка за разговори
AI разговорите използват специфична структура с различни „роли“, всяка изпълнява различна функция:
```python
messages=[
{
"role": "system",
"content": "You are a helpful assistant who explains things simply."
},
{
"role": "user",
"content": "What is machine learning?"
}
]
```
**Помислете за това като за режисура на пиеса:**
- **Роля на системата**: Като инструкции за актьор – казва на AI как да се държи, каква личност да има и как да отговаря
- **Роля на потребителя**: Истинският въпрос или съобщение от човека, който използва вашето приложение
- **Роля на асистента**: Отговорът на AI (вие не го изпращате, но той се появява в историята на разговора)
**Аналогия от реалния свят**: Представете си, че представяте приятел на някого на парти:
- **Системно съобщение**: „Това е моята приятелка Сара, тя е доктор и обяснява медицински понятия по разбираем начин“
- **Потребителско съобщение**: „Можеш ли да обясниш как работят ваксините?“
- **Отговор на асистента**: Сара отговаря като приятелски настроен доктор, а не като адвокат или готвач
### Разбиране на AI параметри: Фина настройка на поведението на отговорите
Числовите параметри в AI API повикванията контролират начина, по който моделът генерира отговори. Тези настройки ви позволяват да настройвате поведението на AI за различни случаи на използване:
#### Температура (0.0 до 2.0): Регулатор на креативността
**Какво прави**: Контролира колко креативни или предсказуеми ще бъдат отговорите на AI.
**Помислете за това като за ниво на импровизация на джаз музикант:**
- **Температура = 0.1**: Свири една и съща мелодия всеки път (много предсказуемо)
- **Температура = 0.7**: Добавя леки вариации, като остава разпознаваем (балансирана креативност)
- **Температура = 1.5**: Пълен експериментален джаз с неочаквани завои (много непредсказуемо)
```python
# Много предсказуеми отговори (добри за фактически въпроси)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "What is 2+2?"}],
temperature=0.1 # Почти винаги ще каже "4"
)
# Креативни отговори (добри за мозъчна атака)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Write a creative story opening"}],
temperature=1.2 # Ще създава уникални, неочаквани истории
)
```
#### Максимален брой токени (1 до 4096+): Контролер на дължина на отговора
**Какво прави**: Задава лимит за дължината на отговора на AI.
**Мислете за токени като приблизително равни на думи** (около 1 токен = 0.75 думи на английски):
- **max_tokens=50**: Кратко и точно (като текстово съобщение)
- **max_tokens=500**: Прекрасен параграф или два
- **max_tokens=2000**: Подробно обяснение с примери
```python
# Кратки, сбити отговори
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Explain JavaScript"}],
max_tokens=100 # Насърчава кратко обяснение
)
# Подробни, изчерпателни отговори
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Explain JavaScript"}],
max_tokens=1500 # Позволява подробни обяснения с примери
)
```
#### Top_p (0.0 до 1.0): Параметър за фокусиране
**Какво прави**: Контролира колко много AI остава фокусиран върху най-вероятните отговори.
**Представете си, че AI има огромен речник, подреден по вероятност за всяка дума:**
- **top_p=0.1**: Взема предвид само най-вероятните 10% думи (много фокусирано)
- **top_p=0.9**: Взема предвид 90% от възможните думи (по-креативно)
- **top_p=1.0**: Взема предвид всички думи (максимално разнообразие)
**Например**: Ако попитате "Небето обикновено е..."
- **Ниско top_p**: Почти винаги казва "синьо"
- **Високо top_p**: Може да каже „синьо“, „облачно“, „безкрайно“, „променящо се“, „красиво“ и т.н.
### Обединяване: Комбинации от параметри за различни приложения
```python
# За фактически, последователни отговори (като бот за документация)
factual_params = {
"temperature": 0.2,
"max_tokens": 300,
"top_p": 0.3
}
# За помощ при креативно писане
creative_params = {
"temperature": 1.1,
"max_tokens": 1000,
"top_p": 0.9
}
# За разговорни, полезни отговори (балансирани)
conversational_params = {
"temperature": 0.7,
"max_tokens": 500,
"top_p": 0.8
}
```
```mermaid
quadrantChart
title Матрица за оптимизация на параметрите на AI
x-axis Ниска креативност --> Висока креативност
y-axis Кратък отговор --> Дълъг отговор
quadrant-1 Креативно съдържание
quadrant-2 Подробен анализ
quadrant-3 Бързи факти
quadrant-4 Разговорен AI
Documentation Bot: [0.2, 0.3]
Customer Service: [0.4, 0.4]
General Assistant: [0.7, 0.5]
Creative Writer: [0.9, 0.9]
Brainstorming Tool: [0.8, 0.8]
```
**Защо тези параметри са важни**: Различните приложения изискват различни типове отговори. Бот за обслужване на клиенти трябва да е последователен и фактологичен (ниска температура), докато асистент за креативно писане трябва да бъде въображаем и разнообразен (висока температура). Разбирането на тези параметри ви дава контрол над личността и стила на отговорите на AI.
```
**Here's what's happening in this code:**
- **We import** the tools we need: `os` for reading environment variables and `OpenAI` for talking to the AI
- **We set up** the OpenAI client to point to GitHub's AI servers instead of OpenAI directly
- **We authenticate** using a special GitHub token (more on that in a minute!)
- **We structure** our conversation with different "roles" – think of it like setting the scene for a play
- **We send** our request to the AI with some fine-tuning parameters
- **We extract** the actual response text from all the data that comes back
> 🔐 **Security Note**: Never hardcode API keys in your source code! Always use environment variables to store sensitive credentials like your `GITHUB_TOKEN`.
### Creating a Reusable AI Function
Let's refactor this code into a clean, reusable function that we can easily integrate into our web application:
```python
import asyncio
from openai import AsyncOpenAI
# Use AsyncOpenAI for better performance
client = AsyncOpenAI(
base_url="https://models.github.ai/inference",
api_key=os.environ["GITHUB_TOKEN"],
)
async def call_llm_async(prompt: str, system_message: str = "You are a helpful assistant."):
"""
Sends a prompt to the AI model asynchronously and returns the response.
Args:
prompt: The user's question or message
system_message: Instructions that define the AI's behavior and personality
Returns:
str: The AI's response to the prompt
"""
try:
response = await client.chat.completions.create(
messages=[
{
"role": "system",
"content": system_message,
},
{
"role": "user",
"content": prompt,
}
],
model="openai/gpt-4o-mini",
temperature=1,
max_tokens=4096,
top_p=1
)
return response.choices[0].message.content
except Exception as e:
logger.error(f"AI API error: {str(e)}")
return "I'm sorry, I'm having trouble processing your request right now."
# Backward compatibility function for synchronous calls
def call_llm(prompt: str, system_message: str = "You are a helpful assistant."):
"""Synchronous wrapper for async AI calls."""
return asyncio.run(call_llm_async(prompt, system_message))
```
**Защо да разберете тази подобрена функция:**
- **Приема** два параметъра: подканата на потребителя и опционално системно съобщение
- **Предоставя** системно съобщение по подразбиране за общо поведение на асистента
- **Използва** правилни Python типови подсказки за по-добра документация
- **Включва** детайлно docstring, обясняващ целта и параметрите на функцията
- **Връща** само съдържанието на отговора, което е лесно за използване в уеб API
- **Поддържа** същите параметри на модела за последователно поведение на AI
### Магията на системните промпти: Програмиране на личността на AI
Ако параметрите контролират начина, по който AI мисли, системните промпти контролират кой AI вярва, че е. Това честно казано е една от най-готините части при работа с AI – давате на AI пълна личност, ниво на експертиза и комуникационен стил.
**Помислете за системните промпти като кастинг на различни актьори за различни роли**: Вместо един общ асистент, можете да създадете специализирани експерти за различни ситуации. Търсите търпелив учител? Креативен партньор за мозъчна атака? Бизнес консултант без излишни приказки? Просто сменяте системния промпт!
#### Защо системните промпти са толкова мощни
Ето интересната част: AI моделите са обучавани на безброй разговори, в които хората приемат различни роли и нива на експертиза. Когато дадете на AI конкретна роля, това е като да превключите ключ, който активира всички тези научени модели.
**Това е като метод актьорско изпълнение за AI**: Кажете на актьор „ти си мъдър стар професор“ и вижте как автоматично променя стойката, речника и маниерите си. AI прави нещо удивително подобно с езиковите модели.
#### Създаване на ефективни системни промпти: Изкуство и наука
**Съставът на страхотен системен промпт:**
1. **Роля/Идентичност**: Кой е AI?
2. **Експертиза**: Какво знае?
3. **Комуникационен стил**: Как говори?
4. **Конкретни инструкции**: На какво да се съсредоточи?
```python
# ❌ Неясна системна подсказка
"You are helpful."
# ✅ Подробна, ефективна системна подсказка
"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."
```
#### Примери за системни промпти с контекст
Нека видим как различни системни промпти създават напълно различни AI личности:
```python
# Пример 1: Търпеливият учител
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.
"""
# Пример 2: Креативният сътрудник
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.
"""
# Пример 3: Стратегическият бизнес съветник
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.
"""
```
#### Виждане на системните промпти в действие
Нека тестваме един и същ въпрос с различни системни промпти, за да видим драматичните разлики:
**Въпрос**: „Как да осъществя автентикация на потребители в моето уеб приложение?“
```python
# С подсказка от учител:
teacher_response = call_llm(
"How do I handle user authentication in my web app?",
teacher_prompt
)
# Типичен отговор: "Страхотен въпрос! Нека разгледаме удостоверяването на прости стъпки.
# Представи си го като бодигард на нощен клуб, който проверява личните карти..."
# С бизнес подсказка:
business_response = call_llm(
"How do I handle user authentication in my web app?",
business_prompt
)
# Типичен отговор: "От стратегическа гледна точка, удостоверяването е ключово за доверието на потребителите
# и спазването на регулаторните изисквания. Нека изложа рамка, която взема предвид сигурността,
# потребителския опит и мащабируемостта..."
```
#### Разширени техники за системни промпти
**1. Настройка на контекст**: Дайте на AI фонова информация
```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. Форматиране на изхода**: Кажете на ИИ как да структурира отговорите
```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. Задаване на ограничения**: Определете какво ИИ не трябва да прави
```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.
"""
```
#### Защо това е важно за вашия чат асистент
Разбирането на системните подкани ви дава невероятна сила да създавате специализирани ИИ асистенти:
- **Бот за обслужване на клиенти**: Полезен, търпелив, запознат с политиките
- **Учебен наставник**: Насърчаващ, поетапен, проверяващ разбирането
- **Креативен партньор**: Въображаем, изграждащ върху идеи, задаващ „а какво ако?“
- **Технически експерт**: Прецизен, детайлен, ориентиран към сигурността
**Ключовото прозрение**: Вие не просто извиквате ИИ API – създавате персоналност на ИИ, която обслужва конкретния ви случай на употреба. Това прави модерните ИИ приложения да изглеждат персонализирани и полезни, а не обобщени.
### 🎯 Педагогическа проверка: Програмиране на ИИ личност
**Пауза и размисъл**: Току-що научихте как се програмират ИИ личности чрез системни подкани. Това е фундаментално умение в развитието на съвременни ИИ приложения.
**Бърза самооценка**:
- Можете ли да обясните как системните подкани се различават от обикновените потребителски съобщения?
- Каква е разликата между параметрите temperature и top_p?
- Как бихте създали системна подкана за конкретен случай на употреба (напр. за наставник по програмиране)?
**Връзка с реалния свят**: Техниките с системни подкани, които сте научили, се използват във всяко голямо ИИ приложение - от помощта в кода на GitHub Copilot до разговорния интерфейс на ChatGPT. Вие овладявате същите модели, използвани от екипите за ИИ продукти в големите технологични компании.
**Предизвикателен въпрос**: Как бихте проектирали различни ИИ личности за различни типове потребители (начинаещи срещу експерти)? Помислете как един и същ основен ИИ модел може да обслужва различна аудитория чрез инженеринг на подкани.
## Създаване на Web API с FastAPI: Вашият високоефективен комуникационен център за ИИ
Сега нека изградим бекенда, който свързва фронтенда ви с ИИ услугите. Ще използваме FastAPI – модерен Python framework, който е експерт в създаването на API-та за ИИ приложения.
FastAPI предлага няколко предимства за този тип проекти: вградена async поддръжка за обработка на паралелни заявки, автоматично генериране на API документация и отлична производителност. Вашият FastAPI сървър действа като посредник, който получава заявки от фронтенда, комуникира с ИИ услугите и връща форматирани отговори.
### Защо FastAPI за ИИ приложения?
Може би си мислите: „Не мога ли просто да викам ИИ директно от фронтенд JavaScript?“ или „Защо FastAPI вместо Flask или Django?“ Отлични въпроси!
**Ето защо FastAPI е перфектен за това, което строим:**
- **Async по подразбиране**: Може да борави с множество ИИ заявки едновременно без да блокира
- **Автоматична документация**: Посетете `/docs` и получете красива, интерактивна API документация безплатно
- **Вградена валидация**: Хваща грешки преди да причинят проблеми
- **Молниеносно бърз**: Един от най-бързите Python фреймуърци
- **Модерен Python**: Използва всички нови и най-добри Python функции
**И ето защо ни трябва бекенд изобщо:**
**Сигурност**: Вашият AI API ключ е като парола – ако го сложите във фронтенд JavaScript, всеки, който гледа сорса на вашия сайт, може да го открадне и да използва кредитите ви. Бекендът пази чувствителните данни сигурно.
**Ограничаване на честота и контрол**: Бекендът ви позволява да контролирате колко често потребителите могат да правят заявки, да реализирате автентикация и да добавяте логиране за проследяване на използването.
**Обработка на данни**: Може да искате да запазвате разговорите, да филтрирате неподходящо съдържание или да съчетавате няколко ИИ услуги. Тази логика живее в бекенда.
**Архитектурата прилича на модел клиент-сървър:**
- **Фронтенд**: Потребителски интерфейс за взаимодействие
- **Бекенд API**: Слой за обработка и маршрутизиране на заявки
- **ИИ услуга**: Външно изчисление и генериране на отговори
- **Променливи на средата**: Сигурно конфигуриране и съхранение на креденшъли
### Разбиране на потока заявка-отговор
Нека проследим какво се случва, когато потребител изпрати съобщение:
```mermaid
sequenceDiagram
participant User as 👤 Потребител
participant Frontend as 🌐 Фронтенд
participant API as 🔧 FastAPI Сървър
participant AI as 🤖 AI Услуга
User->>Frontend: Въвежда "Здравей AI!"
Frontend->>API: POST /hello {"message": "Здравей AI!"}
Note over API: Проверява заявката Добавя системно подканяне
API->>AI: Изпраща форматирана заявка
AI->>API: Връща AI отговор
Note over API: Обработва отговора Записва разговора
API->>Frontend: {"response": "Здравей! Как мога да помогна?"}
Frontend->>User: Показва AI съобщение
```
**Разбиране на всяка стъпка:**
1. **Потребителско взаимодействие**: Човек пише в чат интерфейса
2. **Обработка във фронтенда**: JavaScript улавя входа и го форматира като JSON
3. **Валидация на API**: FastAPI автоматично валидира заявката чрез Pydantic модели
4. **Интеграция с ИИ**: Бекендът добавя контекст (системна подкана) и вика ИИ услугата
5. **Обработка на отговора**: API получава отговор от ИИ и може да го модифицира при нужда
6. **Показване на фронтенда**: JavaScript показва отговора в чат интерфейса
### Разбиране на API архитектурата
```mermaid
sequenceDiagram
participant Frontend
participant FastAPI
participant AI Function
participant GitHub Models
Frontend->>FastAPI: POST /hello {"message": "Здравей 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": "Здравей! Как мога да помогна?"}
```
```mermaid
flowchart TD
A[Потребителски вход] --> B[Валидиране на фронтенда]
B --> C[HTTP POST заявка]
C --> D[FastAPI рутер]
D --> E[Валидиране с Pydantic]
E --> F[Извикване на AI функция]
F --> G[GitHub Models API]
G --> H[Обработка на отговора]
H --> I[JSON отговор]
I --> J[Обновяване на фронтенда]
subgraph "Сигурност слой"
K[CORS middleware]
L[Променливи на средата]
M[Обработка на грешки]
end
D --> K
F --> L
H --> M
```
### Създаване на FastAPI приложението
Нека създадем нашето API стъпка по стъпка. Създайте файл с име `api.py` със следния FastAPI код:
```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
# Конфигуриране на логване
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
# Създаване на FastAPI приложение
app = FastAPI(
title="AI Chat API",
description="A high-performance API for AI-powered chat applications",
version="1.0.0"
)
# Конфигуриране на CORS
app.add_middleware(
CORSMiddleware,
allow_origins=["*"], # Конфигуриране подходящо за продукция
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
# Pydantic модели за валидация на заявки/отговори
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:
# Извличане и валидация на съобщение
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]}...")
# Извикване на AI услуга (забележка: call_llm трябва да бъде асинхронен за по-добра производителност)
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:**
- **Импортира** FastAPI за функционалност на модерен уеб фреймуърк и Pydantic за валидация на данни
- **Създава** автоматична API документация (достъпна на `/docs` при стартиране на сървъра)
- **Активира** CORS middleware за позволяване на фронтенд заявки от различни източници
- **Дефинира** Pydantic модели за автоматична валидация на заявки/отговори и документация
- **Използва** async endpoints за по-добра производителност при паралелни заявки
- **Прилага** подходящи HTTP статус кодове и обработка на грешки с HTTPException
- **Включва** структурирано логиране за мониторинг и отстраняване на грешки
- **Предлага** животозастрахователен endpoint за проверка на статус на услугата
**Ключови предимства на FastAPI пред традиционните фреймуърци:**
- **Автоматична валидация**: Pydantic моделите гарантират цялост на данните преди обработка
- **Интерактивна документация**: Посетете `/docs` за авто-генерирана, тестируема API документация
- **Типова сигурност**: Python type hints предотвратяват runtime грешки и подобряват качеството на кода
- **Async поддръжка**: Обработка на множество ИИ заявки едновременно без блокиране
- **Производителност**: Значително по-бърза обработка на заявки за приложения в реално време
### Разбиране на CORS: Пазачът на сигурността в уеба
CORS (Cross-Origin Resource Sharing) е като охрана на сграда, която проверява дали посетителите имат разрешение да влязат. Нека разберем защо това е важно и как влияе на вашето приложение.
#### Какво е CORS и защо съществува?
**Проблемът**: Представете си, че който и да е сайт може да прави заявки към сайта на вашата банка от ваше име без вашето разрешение. Това щеше да е кошмар за сигурността! Браузърите по подразбиране предотвратяват това чрез "Same-Origin Policy."
**Same-Origin Policy**: Браузърите позволяват на уеб страници да правят заявки само към същия домейн, порт и протокол, от който са заредени.
**Аналогия от реалния свят**: Това е като охраната на апартаментна сграда – само жителите (същия origin) имат достъп по подразбиране. Ако искате да допуснете приятел (различен origin), трябва явно да уведомите охраната, че е добре дошъл.
#### CORS във вашата развойна среда
По време на разработка, вашият фронтенд и бекенд работят на различни портове:
- Фронтенд: `http://localhost:3000` (или file:// ако отваряте HTML директно)
- Бекенд: `http://localhost:5000`
Тези адреси се считат за „различни origin-и“, дори и да са на един и същ компютър!
```python
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI(__name__)
CORS(app) # Това казва на браузърите: "Разрешено е други източници да правят заявки към това API"
```
**Какво прави CORS конфигурацията на практика:**
- **Добавя** специални HTTP хедъри към API отговорите, които казват на браузърите „това междудоменно заявка е разрешена“
- **Обработва** „предварителни заявки“ (браузърите понякога проверяват разрешенията преди да изпратят истинската заявка)
- **Предотвратява** досадната грешка „blocked by CORS policy“ в конзолата на браузъра
#### CORS сигурност: Разработка срещу продукция
```python
# 🚨 Разработка: Позволява ВСИЧКИ източници (удобно, но несигурно)
CORS(app)
# ✅ Производство: Позволявайте само вашия конкретен фронтенд домейн
CORS(app, origins=["https://yourdomain.com", "https://www.yourdomain.com"])
# 🔒 Разширено: Различни източници за различни среди
if app.debug: # Режим на разработка
CORS(app, origins=["http://localhost:3000", "http://127.0.0.1:3000"])
else: # Режим на производство
CORS(app, origins=["https://yourdomain.com"])
```
**Защо това е важно**: В разработка `CORS(app)` е като да оставите входната си врата отключена – удобно, но несигурно. В продукция трябва да уточните точно кои сайтове могат да комуникират с вашето API.
#### Чести CORS сценарии и решения
| Сценарий | Проблем | Решение |
|-----------------------|---------------------------|-------------------------------|
| **Локална разработка** | Фронтенд не може да достигне бекенд | Добавяне на CORSMiddleware в FastAPI |
| **GitHub Pages + Heroku** | Деплойнат фронтенд не може да достигне API | Добавяне на URL на GitHub Pages в CORS origins |
| **Персонален домейн** | CORS грешки в продукция | Актуализиране на CORS origins да съвпадат с домейна ви |
| **Мобилно приложение** | Приложението не може да достигне уеб API | Добавяне на домейна на приложението или внимателна употреба на `*` |
**Профи съвет**: Можете да проверите CORS хедърите в Developer Tools на браузъра си в раздела Network. Търсете хедъри като `Access-Control-Allow-Origin` в отговорите.
### Обработка на грешки и валидация
Обърнете внимание как API-то ни включва правилна обработка на грешки:
```python
# Проверете дали сме получили съобщение
if not message:
return jsonify({"error": "Message field is required"}), 400
```
**Ключови принципи при валидация:**
- **Проверява** за задължителни полета преди обработка на заявки
- **Връща** смислени съобщения за грешки във формат JSON
- **Използва** подходящи HTTP статус кодове (400 за грешни заявки)
- **Осигурява** ясна обратна връзка, която помага на фронтенд разработчиците да отстраняват проблеми
## Настройване и стартиране на вашия бекенд
Сега, когато имаме интеграция с ИИ и FastAPI сървър, нека пуснем всичко. Процесът на настройка включва инсталиране на Python зависимости, конфигуриране на променливи на средата и стартиране на сървъра за разработка.
### Настройване на Python среда
Нека настроим вашата Python среда за разработка. Виртуалните среди са като разделения подход в Манхатънския проект – всеки проект получава собствено изолирано пространство със специфични инструменти и зависимости, предотвратявайки конфликти между проектите.
```bash
# Навигирайте до вашата бекенд директория
cd backend
# Създайте виртуална среда (като създаване на чиста стая за вашия проект)
python -m venv venv
# Активирайте я (Linux/Mac)
source ./venv/bin/activate
# В Windows използвайте:
# venv\Scripts\activate
# Инсталирайте добрите неща
pip install openai fastapi uvicorn python-dotenv
```
**Какво току-що направихме:**
- **Създадохме** нашия малък python балон, в който можем да инсталираме пакети без да засягаме нищо друго
- **Активирахме** го, за да знае терминалът да използва точно тази среда
- **Инсталирахме** основните: OpenAI за ИИ магия, FastAPI за нашия web API, Uvicorn за реалното му стартиране и python-dotenv за сигурно управление на тайни
**Обяснение на ключовите зависимости:**
- **FastAPI**: Модерен, бърз уеб фреймуърк с автоматична API документация
- **Uvicorn**: Светкавично бърз ASGI сървър за стартиране на FastAPI приложения
- **OpenAI**: Официална библиотека за интеграция с GitHub модели и OpenAI API
- **python-dotenv**: Сигурно зареждане на променливи на средата от .env файлове
### Конфигуриране на средата: Как да пазим тайните си
Преди да стартираме API-то, трябва да говорим за един от най-важните уроци в уеб разработката: как да пазим тайните си наистина тайни. Променливите на средата са като сигурно хранилище, до което само вашето приложение има достъп.
#### Какво са променливите на средата?
**Помислете за променливите на средата като за сейфова каса** – слагате ценните си неща там и само вие (и приложението ви) имате ключа да ги извадите. Вместо да пишете чувствителна информация направо в кода си (където буквално всеки може да я види), съхранявате я безопасно в средата.
**Ето разликата:**
- **Грешният начин**: Да напишете паролата си на лепящ лист и да я залепите на монитора си
- **Правилният начин**: Да държите паролата си в сигурен мениджър за пароли, до който имате достъп само вие
#### Защо променливите на средата са важни
```python
# 🚨 НИКОГА НЕ ПРАВЕТЕ ТОВА - API ключ видим за всички
client = OpenAI(
api_key="ghp_1234567890abcdef...", # Всеки може да го открадне!
base_url="https://models.github.ai/inference"
)
# ✅ ПРАВЕТЕ ТОВА - API ключът е запазен сигурно
client = OpenAI(
api_key=os.environ["GITHUB_TOKEN"], # Само вашето приложение може да има достъп до него
base_url="https://models.github.ai/inference"
)
```
**Какво се случва, когато вградите тайните директно:**
1. **Излагане при версионен контрол**: Всеки с достъп до репозитория ви вижда вашия API ключ
2. **Публични репозитории**: Ако качите в GitHub, ключът ви става видим за цялата интернет общност
3. **Споделяне в екип**: Други разработчици в проекта получават достъп до вашия личен API ключ
4. **Нарушения на сигурността**: Ако някой открадне вашия API ключ, може да използва вашите ИИ кредити
#### Създаване на вашия файл за среда
Създайте .env файл в директорията на бекенда. Този файл съхранява вашите тайни локално:
```bash
# .env файл - Това НЕ трябва да се комитва в Git
GITHUB_TOKEN=your_github_personal_access_token_here
FASTAPI_DEBUG=True
ENVIRONMENT=development
```
**Разбиране на .env файла:**
- **Една тайна на ред** във формат `KEY=value`
- **Без интервали** около знака за равно
- **Обикновено без кавички** около стойностите
- **Коментари** започват с `#`
#### Създаване на ваш токен за достъп до GitHub
Вашият GitHub токен е като специална парола, която дава на приложението ви разрешение да използва GitHub AI услуги:
**Стъпка по стъпка за създаване на токен:**
1. **Отидете в GitHub Settings** → Developer settings → Personal access tokens → Tokens (classic)
2. **Кликнете на „Generate new token (classic)“**
3. **Задайте срок на валидност** (30 дни за тест, по-дълго за продукция)
4. **Изберете обхвати**: Отметнете "repo" и всякакви други нужни разрешения
5. **Генерирайте токена** и го копирайте веднага (след това няма да го видите отново!)
6. **Поставете го в .env файла си**
```bash
# Пример за това как изглежда вашият токен (това е фалшиво!)
GITHUB_TOKEN=ghp_1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R
```
#### Зареждане на променливи на средата в Python
```python
import os
from dotenv import load_dotenv
# Заредете променливи на средата от .env файла
load_dotenv()
# Сега можете да имате достъп до тях безопасно
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"
)
```
**Какво прави този код:**
- **Зарежда** вашия .env файл и прави променливите достъпни в Python
- **Проверява** дали изискуемият токен съществува (добра обработка на грешки!)
- **Хвърля** ясна грешка, ако токенът липсва
- **Използва** токена сигурно, без да го излага в кода
#### Git сигурност: Файлът .gitignore
Вашият `.gitignore` файл казва на Git кои файлове никога да не следи или качва:
```bash
# .gitignore - Добавете тези редове
.env
*.env
.env.local
.env.production
__pycache__/
venv/
.vscode/
```
**Защо това е решаващо**: След като добавите `.env` към `.gitignore`, Git ще игнорира файла ви за среда, което предотвратява случайно качване на тайни в GitHub.
#### Различни среди, различни тайни
Професионалните приложения използват различни API ключове за различни среди:
```bash
# .env.разработка
GITHUB_TOKEN=your_development_token
DEBUG=True
# .env.производство
GITHUB_TOKEN=your_production_token
DEBUG=False
```
**Защо това е важно**: Не искате експериментите ви в разработка да влияят на квотата ви за продукция, и искате различни нива на сигурност за различните среди.
### Стартиране на вашия сървър за разработка: Дайте живот на FastAPI приложението си
Сега идва вълнуващият момент – стартирането на вашия FastAPI сървър за разработка и виждането на вашата AI интеграция оживяваща! FastAPI използва Uvicorn, светкавично бърз ASGI сървър, който е специално проектиран за асинхронни Python приложения.
#### Разбиране на процеса по стартиране на FastAPI сървъра
```bash
# Метод 1: Директно изпълнение на Python (включва авто-презареждане)
python api.py
# Метод 2: Използване на Uvicorn директно (повече контрол)
uvicorn api:app --host 0.0.0.0 --port 5000 --reload
```
Когато изпълните тази команда, ето какво се случва зад кулисите:
**1. Python зарежда вашето FastAPI приложение**:
- Импортира всички необходими библиотеки (FastAPI, Pydantic, OpenAI и др.)
- Зарежда променливите на средата от вашия `.env` файл
- Създава FastAPI инстанция на приложението с автоматична документация
**2. Uvicorn конфигурира ASGI сървъра**:
- Свързва се към порт 5000 с асинхронни възможности за обработка на заявки
- Настройва маршрутизацията на заявките с автоматична валидация
- Позволява hot reload за разработка (рестартиране при промени във файлове)
- Генерира интерактивна API документация
**3. Сървърът започва да слуша**:
- Вашият терминал показва: `INFO: Uvicorn running on http://0.0.0.0:5000`
- Сървърът може да обработва множество паралелни AI заявки
- Вашият API е готов с автоматична документация на `http://localhost:5000/docs`
#### Какво трябва да видите, когато всичко работи
```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:**
- **Will watch for changes**: Автоматично презареждане включено за разработка
- **Uvicorn running**: Активен е високопроизводителен ASGI сървър
- **Started reloader process**: Файл-монитор за автоматични рестартирания
- **Application startup complete**: FastAPI приложението е успешно инициализирано
- **Interactive docs available**: Посетете `/docs` за автоматична API документация
#### Тестване на FastAPI: Множество мощни подходи
FastAPI предлага няколко удобни начина да тествате вашия API, включително автоматична интерактивна документация:
**Метод 1: Интерактивна API документация (Препоръчително)**
1. Отворете браузъра и отидете на `http://localhost:5000/docs`
2. Ще видите Swagger UI с документирани всички ваши крайни точки
3. Кликнете на `/hello` → "Try it out" → Въведете тестово съобщение → "Execute"
4. Вижте отговора директно в браузъра с правилно форматиране
**Метод 2: Основен тест в браузъра**
1. Отидете на `http://localhost:5000` за коренната крайна точка
2. Отидете на `http://localhost:5000/health`, за да проверите състоянието на сървъра
3. Това потвърждава, че FastAPI сървърът работи правилно
**Метод 2: Тестване от командния ред (За напреднали)**
```bash
# Тест с curl (ако е наличен)
curl -X POST http://localhost:5000/hello \
-H "Content-Type: application/json" \
-d '{"message": "Hello AI!"}'
# Очакван отговор:
# {"response": "Здравейте! Аз съм вашият AI асистент. Как мога да ви помогна днес?"}
```
**Метод 3: Python тестов скрипт**
```python
# test_api.py - Създайте този файл, за да тествате вашия API
import requests
import json
# Тествайте API крайната точка
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)
```
#### Отстраняване на често срещани проблеми при стартиране
| Съобщение за грешка | Какво означава | Как да го оправите |
|---------------------|----------------|--------------------|
| `ModuleNotFoundError: No module named 'fastapi'` | FastAPI не е инсталиран | Изпълнете `pip install fastapi uvicorn` във вашата виртуална среда |
| `ModuleNotFoundError: No module named 'uvicorn'` | ASGI сървър не е инсталиран | Изпълнете `pip install uvicorn` във вашата виртуална среда |
| `KeyError: 'GITHUB_TOKEN'` | Не е намерена променлива на средата | Проверете вашия `.env` файл и извикването на `load_dotenv()` |
| `Address already in use` | Порт 5000 вече е зает | Убийте други процеси, използващи порт 5000, или променете порта |
| `ValidationError` | Данните в заявката не съответстват на Pydantic модела | Проверете дали форматът на заявката съответства на очакваната схема |
| `HTTPException 422` | Невъзможно да се обработи ентитито | Провалена валидация на заявката, проверете `/docs` за правилния формат |
| `OpenAI API error` | Провалена автентикация на AI услугата | Проверете дали GitHub токенът е коректен и има правилни разрешения |
#### Най-добри практики за разработка
**Hot Reloading**: FastAPI с Uvicorn осигурява автоматично презареждане при запис на промените във вашите Python файлове. Това означава, че може да модифицирате кода и веднага да тествате без ръчно рестартиране.
```python
# Ярко активиране на горещото презареждане
if __name__ == "__main__":
app.run(host="0.0.0.0", port=5000, debug=True) # debug=True активира горещото презареждане
```
**Логване за разработка**: Добавете логване, за да разберете какво се случва:
```python
import 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
```
**Защо логването помага**: По време на разработка можете да видите точно какви заявки идват, какво отговаря AI и къде възникват грешки. Това ускорява отстраняването на проблеми значително.
### Конфигуриране за GitHub Codespaces: Лесна разработка в облака
GitHub Codespaces е като да имате мощен развоен компютър в облака, до който можете да достъпите от всеки браузър. Ако работите в Codespaces, има няколко допълнителни стъпки, за да направите бекенда си достъпен за фронтенда.
#### Разбиране на мрежовата архитектура в Codespaces
В локална развойна среда всичко се изпълнява на един и същ компютър:
- Бекенд: `http://localhost:5000`
- Фронтенд: `http://localhost:3000` (или file:// URL)
В Codespaces вашата развойна среда се изпълнява на сървърите на GitHub, така че "localhost" има различно значение. GitHub автоматично създава публични URL адреси за вашите услуги, но вие трябва да ги конфигурирате правилно.
#### Стъпка по стъпка конфигурация на Codespaces
**1. Стартирайте бекенд сървъра си**:
```bash
cd backend
python api.py
```
Ще видите познатото съобщение за стартиране на FastAPI/Uvicorn, но забележете, че той работи в средата на Codespace.
**2. Конфигурирайте видимостта на порта**:
- Намерете таба "Ports" в долния панел на VS Code
- Открийте порт 5000 в списъка
- Кликнете с десен бутон върху порт 5000
- Изберете "Port Visibility" → "Public"
**Защо да го направите публичен?** По подразбиране портовете в Codespace са частни (достъпни само за вас). Правейки ги публични, позволявате на вашия фронтенд (който се изпълнява в браузъра) да комуникира с бекенда.
**3. Вземете своя публичен URL:**
След като направите порта публичен, ще видите URL адрес като:
```
https://your-codespace-name-5000.app.github.dev
```
**4. Обновете конфигурацията на фронтенда:**
```javascript
// Във вашия frontend app.js, обновете BASE_URL:
this.BASE_URL = "https://your-codespace-name-5000.app.github.dev";
```
#### Разбиране на Codespace URL адресите
Codespace URL адресите следват предсказуем модел:
```
https://[codespace-name]-[port].app.github.dev
```
**Обяснение на отделните части:**
- `codespace-name`: Уникален идентификатор за вашия Codespace (обикновено включва вашето потребителско име)
- `port`: Номерът на порта, на който работи услугата ви (5000 за нашето FastAPI приложение)
- `app.github.dev`: Домейнът на GitHub за Codespace приложения
#### Тестване на Codespace конфигурацията
**1. Тествайте бекенда директно**:
Отворете публичния си URL в нов браузър раздел. Трябва да видите:
```
Welcome to the AI Chat API. Send POST requests to /hello with JSON payload containing 'message' field.
```
**2. Тествайте с инструменти за разработчици на браузъра**:
```javascript
// Отворете конзолата на браузъра и тествайте вашето 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 срещу локална разработка
| Аспект | Локална разработка | GitHub Codespaces |
|--------|-------------------|-------------------|
| **Време за настройка** | По-дълго (инсталиране на Python, зависимости) | Мигновено (предварително конфигурирана среда) |
| **Достъп до URL** | `http://localhost:5000` | `https://xyz-5000.app.github.dev` |
| **Конфигуриране на порт** | Автоматично | Ръчно (правене на портове публични) |
| **Запазване на файлове** | Локална машина | GitHub хранилище |
| **Сътрудничество** | Трудно за споделяне на среда | Лесно споделяне на линк за Codespace |
| **Зависимост от интернет** | Само за AI API повиквания | Задължително за всичко |
#### Съвети за разработка в Codespace
**Променливи на средата в Codespaces**:
Вашият `.env` файл работи по същия начин в Codespaces, но също така можете да задавате променливи на средата директно в Codespace:
```bash
# Задайте променлива на средата за текущата сесия
export GITHUB_TOKEN="your_token_here"
# Или я добавете в .bashrc за постоянно запазване
echo 'export GITHUB_TOKEN="your_token_here"' >> ~/.bashrc
```
**Управление на портовете**:
- Codespaces автоматично открива, когато приложението ви започне да слуша на порт
- Можете да пренасочвате множество портове едновременно (полезно, ако добавите база данни по-късно)
- Портовете остават достъпни, докато Codespace е активен
**Работен процес за разработка**:
1. Правите промени в кода във VS Code
2. FastAPI се презарежда автоматично (благодарение на режим reload на Uvicorn)
3. Тествате промените веднага чрез публичния URL
4. Комитвате и пускате промените, когато сте готови
> 💡 **Полезен съвет**: Запазете закладка на бекенд URL адреса на вашия Codespace по време на разработката. Тъй като имената на Codespace са стабилни, URL няма да се променя докато използвате същия Codespace.
## Създаване на фронтенд чат интерфейс: Където хората срещат AI
Сега ще изградим потребителския интерфейс – частта, която определя как хората взаимодействат с вашия AI асистент. Подобно на дизайна на оригиналния интерфейс на iPhone, ние се фокусираме върху правенето на сложната технология интуитивна и естествена за използване.
### Разбиране на модерната фронтенд архитектура
Нашият чат интерфейс ще бъде това, което наричаме „едностранично приложение“ или SPA. Вместо старомодния подход, където всеки клик зарежда нова страница, нашето приложение се обновява плавно и мигновено:
**Старите уебсайтове**: Като четене на физическа книга – прелиствате към изцяло нова страница
**Нашето чат приложение**: Като използване на телефона ви – всичко тече и се обновява без прекъсване
```mermaid
graph TD
A[Потребителят въвежда съобщение] --> B[JavaScript улавя входа]
B --> C[Провери и форматирай данните]
C --> D[Изпрати към Backend API]
D --> E[Показване на състояние на зареждане]
E --> F[Получаване на AI отговор]
F --> G[Обновяване на чат интерфейса]
G --> H[Готово за следващото съобщение]
```
```mermaid
classDiagram
class ChatApp {
+messages: HTMLElement
+form: HTMLElement
+input: HTMLElement
+sendButton: HTMLElement
+BASE_URL: string
+API_ENDPOINT: string
+constructor()
+initializeEventListeners()
+handleSubmit(event)
+callAPI(message)
+appendMessage(text, role)
+escapeHtml(text)
+scrollToBottom()
+setLoading(isLoading)
}
ChatApp --> DOM : манипулира
ChatApp --> FastAPI : изпраща заявки
```
### Трите стълба на фронтенд разработката
Всяко фронтенд приложение – от прости уебсайтове до сложни приложения като Discord или Slack – е изградено върху три основни технологии. Мислете за тях като основата на всичко, което виждате и с което взаимодействате в мрежата:
**HTML (Структура)**: Това е вашата основа
- Определя кои елементи съществуват (бутон, текстово поле, контейнери)
- Дава смисъл на съдържанието (това е заглавие, това е форма и т.н.)
- Създава базовата структура, върху която всичко останало се гради
**CSS (Презентация)**: Това е вашият вътрешен дизайнер
- Прави всичко красиво (цветове, шрифтове, оформления)
- Управлява различни размери на екрана (телефон, лаптоп, таблет)
- Създава плавни анимации и визуална обратна връзка
**JavaScript (Поведение)**: Това е вашият мозък
- Реагира на действията на потребителите (клик, писане, скрол)
- Комуникира с бекенда и обновява страницата
- Прави всичко интерактивно и динамично
**Мислете за това като архитектурен дизайн:**
- **HTML**: Структурният план (определящ пространства и връзки)
- **CSS**: Естетичният и околен дизайн (визуален стил и потребителско изживяване)
- **JavaScript**: Механичните системи (функционалност и интерактивност)
### Защо съвременната JavaScript архитектура е важна
Нашето чат приложение ще използва съвременни JavaScript модели, които ще срещнете в професионални приложения. Разбирането им ще ви помогне да се развивате като разработчик:
**Архитектура, базирана на класове**: Ще организираме кода си в класове, което е като създаване на чертежи за обекти
**Async/Await**: Модерен начин за работа с операции, които отнемат време (например API повиквания)
**Събитийно-ориентирано програмиране**: Нашето приложение отговаря на потребителски действия (клик, натискане на клавиш), а не работи в цикъл
**Манипулиране на DOM**: Динамично обновяване на съдържанието на страницата според взаимодействията и отговорите на API
### Настройка на структурата на проекта
Създайте директория за фронтенд със следната организирана структура:
```text
frontend/
├── index.html # Main HTML structure
├── app.js # JavaScript functionality
└── styles.css # Visual styling
```
**Разбиране на архитектурата:**
- **Разделя** отговорностите между структура (HTML), поведение (JavaScript) и презентация (CSS)
- **Поддържа** проста файлова структура, лесна за навигация и модификация
- **Следва** добрите практики за организация и поддръжка при уеб разработката
### Създаване на HTML основата: Семантична структура за достъпност
Нека започнем със структурата на HTML. Модерната уеб разработка залага на „семантичен HTML“ – използване на HTML елементи, които ясно описват предназначението си, а не само външния вид. Това прави приложението ви достъпно за екранни четци, търсачки и други инструменти.
**Защо семантичният HTML е важен**: Представете си, че описвате чат приложението си на някого по телефона. Ще кажете "има хедър с заглавиe, основна зона където се появяват разговорите и форма в долната част за писане на съобщения." Семантичният HTML използва елементи, които отговарят на това естествено описание.
Създайте `index.html` с тази обмислена структура на маркиране:
```html
AI Chat Assistant
AI Chat Assistant
Ask me anything!
```
**Разбиране на всеки HTML елемент и неговата цел:**
#### Структура на документа
- **``**: Казва на браузъра, че това е модерен HTML5
- **``**: Определя езика на страницата за екранни четци и инструменти за превод
- **``**: Осигурява правилно кодиране на знаците за международен текст
- **``**: Прави страницата мобилно адаптивна чрез контрол на мащаба и увеличението
#### Семантични елементи
- **``**: Ясно посочва горната секция с заглавието и описанието
- **``**: Определя основната област със съдържание (където се случват разговорите)
- **`