localizeflow[bot]
6602ddcc6a
|
7 months ago | |
|---|---|---|
| .. | ||
| solution | 7 months ago | |
| README.md | 7 months ago | |
README.md
Създайте чат асистент с изкуствен интелект
Спомняте ли си в Star Trek, когато екипажът спокойно разговаряше с компютъра на кораба, задавайки му сложни въпроси и получавайки обмислени отговори? Това, което в 60-те години на миналия век изглеждаше като чиста научна фантастика, сега е нещо, което можете да изградите, използвайки уеб технологии, които вече познавате.
В този урок ще създадем чат асистент с изкуствен интелект, използвайки HTML, CSS, JavaScript и някаква бекенд интеграция. Ще откриете как същите умения, които сте научили, могат да се свържат с мощни AI услуги, които разбират контекста и генерират смислени отговори.
Помислете за AI като достъп до огромна библиотека, която не само може да намери информация, но и да я синтезира в последователни отговори, пригодени към вашите конкретни въпроси. Вместо да търсите сред хиляди страници, получавате директни, контекстуални отговори.
Интеграцията става чрез познати уеб технологии, които работят заедно. HTML създава интерфейса за чат, CSS се грижи за визуалния дизайн, JavaScript управлява потребителските взаимодействия, а бекенд API свързва всичко с AI услугите. Това е подобно на начина, по който различни секции на оркестъра работят заедно, за да създадат симфония.
По същността си ние изграждаме мост между естествената човешка комуникация и машинната обработка. Ще научите както техническата реализация на интеграцията с AI услуги, така и дизайнерските модели, които правят взаимодействията интуитивни.
Към края на този урок, интеграцията с AI ще ви се струва по-малко като мистериозен процес и повече като още един API, с който можете да работите. Ще разберете основните модели, които захранват приложения като ChatGPT и Claude, използвайки същите принципи за уеб разработка, които вече знаете.
⚡ Какво можете да направите през следващите 5 минути
Бърз старт за заети разработчици
flowchart LR
A[⚡ 5 минути] --> B[Вземи GitHub токен]
B --> C[Тествай AI площадка]
C --> D[Копирай Python код]
D --> E[Виж AI отговори]
- Минута 1: Посетете GitHub Models Playground и създайте личен токен за достъп
- Минута 2: Тествайте AI взаимодействия директно в интерфейса на playground
- Минута 3: Кликнете на таба „Code“ и копирайте Python кода
- Минута 4: Стартирайте кода локално с вашия токен:
GITHUB_TOKEN=your_token python test.py - Минута 5: Гледайте как първият AI отговор се генерира от вашия код
Бърз тестов код:
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 приложения
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: Като да попитате знаещ приятел за котки – той ви разказва интересни неща с свои думи, съобразени с това, което искате да знаете
graph LR
A[Вашият Въпрос] --> B[AI Модел]
B --> C[Разпознаване на Шаблони]
C --> D[Генериране на Съдържание]
D --> E[Контекстуален Отговор]
F[Обучаващи Данни<br/>Книги, Статии, Уеб] --> B
Как се обучават AI модели (опростена версия)
AI моделите се обучават чрез излагане на огромни бази данни, съдържащи текст от книги, статии и разговори. Чрез този процес те идентифицират модели в:
- Как мислите се структурират в писмена комуникация
- Кои думи често се появяват заедно
- Как обикновено протичат разговорите
- Контекстуалните разлики между формална и неформална комуникация
Това е подобно на това как археолозите дешифрират древни езици: те анализират хиляди примери, за да разберат граматика, речник и културен контекст, и в крайна сметка могат да разчитат нови текстове, използвайки тези научени модели.
Защо GitHub Models?
Използваме GitHub Models по една много практична причина – те ни дават достъп до AI на корпоративно ниво, без да се налага да изграждаме собствена AI инфраструктура (което, повярвайте ми, не искате да правите сега!). Помислете за това като използването на API за времето, вместо да се опитвате сами да предсказвате времето, като поставяте метеостанции навсякъде.
Всъщност това е "AI като услуга" и най-хубавото? Получавате безплатен старт, така че можете да експериментирате без да се притеснявате за големи сметки.
graph LR
A[Потребителски интерфейс за чат] --> B[Вашият бекенд API]
B --> C[GitHub API за модели]
C --> D[Обработка на AI модел]
D --> C
C --> B
B --> A
Ще използваме GitHub Models за нашата бекенд интеграция, която предоставя достъп до професионални AI възможности чрез приятелски настроен към разработчиците интерфейс. GitHub Models Playground служи като тестова среда, където можете да експериментирате с различни AI модели и да разберете техните възможности, преди да ги имплементирате в кода.
🧠 Екосистема за разработка на AI приложения
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, ще получите нещо такова. Не се притеснявайте, ако изглежда много на пръв поглед – нека го разгледаме на части:
"""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 разговорите използват специфична структура с различни „роли“, всяка изпълнява различна функция:
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: Пълен експериментален джаз с неочаквани завои (много непредсказуемо)
# Много предсказуеми отговори (добри за фактически въпроси)
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: Подробно обяснение с примери
# Кратки, сбити отговори
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: Може да каже „синьо“, „облачно“, „безкрайно“, „променящо се“, „красиво“ и т.н.
Обединяване: Комбинации от параметри за различни приложения
# За фактически, последователни отговори (като бот за документация)
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
}
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 прави нещо удивително подобно с езиковите модели.
Създаване на ефективни системни промпти: Изкуство и наука
Съставът на страхотен системен промпт:
- Роля/Идентичност: Кой е AI?
- Експертиза: Какво знае?
- Комуникационен стил: Как говори?
- Конкретни инструкции: На какво да се съсредоточи?
# ❌ Неясна системна подсказка
"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 личности:
# Пример 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.
"""
Виждане на системните промпти в действие
Нека тестваме един и същ въпрос с различни системни промпти, за да видим драматичните разлики:
Въпрос: „Как да осъществя автентикация на потребители в моето уеб приложение?“
# С подсказка от учител:
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 фонова информация
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. Форматиране на изхода: Кажете на ИИ как да структурира отговорите
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. Задаване на ограничения: Определете какво ИИ не трябва да прави
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: Слой за обработка и маршрутизиране на заявки
- ИИ услуга: Външно изчисление и генериране на отговори
- Променливи на средата: Сигурно конфигуриране и съхранение на креденшъли
Разбиране на потока заявка-отговор
Нека проследим какво се случва, когато потребител изпрати съобщение:
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: Проверява заявката<br/>Добавя системно подканяне
API->>AI: Изпраща форматирана заявка
AI->>API: Връща AI отговор
Note over API: Обработва отговора<br/>Записва разговора
API->>Frontend: {"response": "Здравей! Как мога да помогна?"}
Frontend->>User: Показва AI съобщение
Разбиране на всяка стъпка:
- Потребителско взаимодействие: Човек пише в чат интерфейса
- Обработка във фронтенда: JavaScript улавя входа и го форматира като JSON
- Валидация на API: FastAPI автоматично валидира заявката чрез Pydantic модели
- Интеграция с ИИ: Бекендът добавя контекст (системна подкана) и вика ИИ услугата
- Обработка на отговора: API получава отговор от ИИ и може да го модифицира при нужда
- Показване на фронтенда: JavaScript показва отговора в чат интерфейса
Разбиране на API архитектурата
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": "Здравей! Как мога да помогна?"}
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 код:
# 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-и“, дори и да са на един и същ компютър!
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI(__name__)
CORS(app) # Това казва на браузърите: "Разрешено е други източници да правят заявки към това API"
Какво прави CORS конфигурацията на практика:
- Добавя специални HTTP хедъри към API отговорите, които казват на браузърите „това междудоменно заявка е разрешена“
- Обработва „предварителни заявки“ (браузърите понякога проверяват разрешенията преди да изпратят истинската заявка)
- Предотвратява досадната грешка „blocked by CORS policy“ в конзолата на браузъра
CORS сигурност: Разработка срещу продукция
# 🚨 Разработка: Позволява ВСИЧКИ източници (удобно, но несигурно)
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-то ни включва правилна обработка на грешки:
# Проверете дали сме получили съобщение
if not message:
return jsonify({"error": "Message field is required"}), 400
Ключови принципи при валидация:
- Проверява за задължителни полета преди обработка на заявки
- Връща смислени съобщения за грешки във формат JSON
- Използва подходящи HTTP статус кодове (400 за грешни заявки)
- Осигурява ясна обратна връзка, която помага на фронтенд разработчиците да отстраняват проблеми
Настройване и стартиране на вашия бекенд
Сега, когато имаме интеграция с ИИ и FastAPI сървър, нека пуснем всичко. Процесът на настройка включва инсталиране на Python зависимости, конфигуриране на променливи на средата и стартиране на сървъра за разработка.
Настройване на Python среда
Нека настроим вашата Python среда за разработка. Виртуалните среди са като разделения подход в Манхатънския проект – всеки проект получава собствено изолирано пространство със специфични инструменти и зависимости, предотвратявайки конфликти между проектите.
# Навигирайте до вашата бекенд директория
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-то, трябва да говорим за един от най-важните уроци в уеб разработката: как да пазим тайните си наистина тайни. Променливите на средата са като сигурно хранилище, до което само вашето приложение има достъп.
Какво са променливите на средата?
Помислете за променливите на средата като за сейфова каса – слагате ценните си неща там и само вие (и приложението ви) имате ключа да ги извадите. Вместо да пишете чувствителна информация направо в кода си (където буквално всеки може да я види), съхранявате я безопасно в средата.
Ето разликата:
- Грешният начин: Да напишете паролата си на лепящ лист и да я залепите на монитора си
- Правилният начин: Да държите паролата си в сигурен мениджър за пароли, до който имате достъп само вие
Защо променливите на средата са важни
# 🚨 НИКОГА НЕ ПРАВЕТЕ ТОВА - 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"
)
Какво се случва, когато вградите тайните директно:
- Излагане при версионен контрол: Всеки с достъп до репозитория ви вижда вашия API ключ
- Публични репозитории: Ако качите в GitHub, ключът ви става видим за цялата интернет общност
- Споделяне в екип: Други разработчици в проекта получават достъп до вашия личен API ключ
- Нарушения на сигурността: Ако някой открадне вашия API ключ, може да използва вашите ИИ кредити
Създаване на вашия файл за среда
Създайте .env файл в директорията на бекенда. Този файл съхранява вашите тайни локално:
# .env файл - Това НЕ трябва да се комитва в Git
GITHUB_TOKEN=your_github_personal_access_token_here
FASTAPI_DEBUG=True
ENVIRONMENT=development
Разбиране на .env файла:
- Една тайна на ред във формат
KEY=value - Без интервали около знака за равно
- Обикновено без кавички около стойностите
- Коментари започват с
#
Създаване на ваш токен за достъп до GitHub
Вашият GitHub токен е като специална парола, която дава на приложението ви разрешение да използва GitHub AI услуги:
Стъпка по стъпка за създаване на токен:
- Отидете в GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
- Кликнете на „Generate new token (classic)“
- Задайте срок на валидност (30 дни за тест, по-дълго за продукция)
- Изберете обхвати: Отметнете "repo" и всякакви други нужни разрешения
- Генерирайте токена и го копирайте веднага (след това няма да го видите отново!)
- Поставете го в .env файла си
# Пример за това как изглежда вашият токен (това е фалшиво!)
GITHUB_TOKEN=ghp_1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R
Зареждане на променливи на средата в 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 кои файлове никога да не следи или качва:
# .gitignore - Добавете тези редове
.env
*.env
.env.local
.env.production
__pycache__/
venv/
.vscode/
Защо това е решаващо: След като добавите .env към .gitignore, Git ще игнорира файла ви за среда, което предотвратява случайно качване на тайни в GitHub.
Различни среди, различни тайни
Професионалните приложения използват различни API ключове за различни среди:
# .env.разработка
GITHUB_TOKEN=your_development_token
DEBUG=True
# .env.производство
GITHUB_TOKEN=your_production_token
DEBUG=False
Защо това е важно: Не искате експериментите ви в разработка да влияят на квотата ви за продукция, и искате различни нива на сигурност за различните среди.
Стартиране на вашия сървър за разработка: Дайте живот на FastAPI приложението си
Сега идва вълнуващият момент – стартирането на вашия FastAPI сървър за разработка и виждането на вашата AI интеграция оживяваща! FastAPI използва Uvicorn, светкавично бърз ASGI сървър, който е специално проектиран за асинхронни Python приложения.
Разбиране на процеса по стартиране на FastAPI сървъра
# Метод 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
Какво трябва да видите, когато всичко работи
$ 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 документация (Препоръчително)
- Отворете браузъра и отидете на
http://localhost:5000/docs - Ще видите Swagger UI с документирани всички ваши крайни точки
- Кликнете на
/hello→ "Try it out" → Въведете тестово съобщение → "Execute" - Вижте отговора директно в браузъра с правилно форматиране
Метод 2: Основен тест в браузъра
- Отидете на
http://localhost:5000за коренната крайна точка - Отидете на
http://localhost:5000/health, за да проверите състоянието на сървъра - Това потвърждава, че FastAPI сървърът работи правилно
Метод 2: Тестване от командния ред (За напреднали)
# Тест с curl (ако е наличен)
curl -X POST http://localhost:5000/hello \
-H "Content-Type: application/json" \
-d '{"message": "Hello AI!"}'
# Очакван отговор:
# {"response": "Здравейте! Аз съм вашият AI асистент. Как мога да ви помогна днес?"}
Метод 3: 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 файлове. Това означава, че може да модифицирате кода и веднага да тествате без ръчно рестартиране.
# Ярко активиране на горещото презареждане
if __name__ == "__main__":
app.run(host="0.0.0.0", port=5000, debug=True) # debug=True активира горещото презареждане
Логване за разработка: Добавете логване, за да разберете какво се случва:
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. Стартирайте бекенд сървъра си:
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. Обновете конфигурацията на фронтенда:
// Във вашия 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. Тествайте с инструменти за разработчици на браузъра:
// Отворете конзолата на браузъра и тествайте вашето 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:
# Задайте променлива на средата за текущата сесия
export GITHUB_TOKEN="your_token_here"
# Или я добавете в .bashrc за постоянно запазване
echo 'export GITHUB_TOKEN="your_token_here"' >> ~/.bashrc
Управление на портовете:
- Codespaces автоматично открива, когато приложението ви започне да слуша на порт
- Можете да пренасочвате множество портове едновременно (полезно, ако добавите база данни по-късно)
- Портовете остават достъпни, докато Codespace е активен
Работен процес за разработка:
- Правите промени в кода във VS Code
- FastAPI се презарежда автоматично (благодарение на режим reload на Uvicorn)
- Тествате промените веднага чрез публичния URL
- Комитвате и пускате промените, когато сте готови
💡 Полезен съвет: Запазете закладка на бекенд URL адреса на вашия Codespace по време на разработката. Тъй като имената на Codespace са стабилни, URL няма да се променя докато използвате същия Codespace.
Създаване на фронтенд чат интерфейс: Където хората срещат AI
Сега ще изградим потребителския интерфейс – частта, която определя как хората взаимодействат с вашия AI асистент. Подобно на дизайна на оригиналния интерфейс на iPhone, ние се фокусираме върху правенето на сложната технология интуитивна и естествена за използване.
Разбиране на модерната фронтенд архитектура
Нашият чат интерфейс ще бъде това, което наричаме „едностранично приложение“ или SPA. Вместо старомодния подход, където всеки клик зарежда нова страница, нашето приложение се обновява плавно и мигновено:
Старите уебсайтове: Като четене на физическа книга – прелиствате към изцяло нова страница
Нашето чат приложение: Като използване на телефона ви – всичко тече и се обновява без прекъсване
graph TD
A[Потребителят въвежда съобщение] --> B[JavaScript улавя входа]
B --> C[Провери и форматирай данните]
C --> D[Изпрати към Backend API]
D --> E[Показване на състояние на зареждане]
E --> F[Получаване на AI отговор]
F --> G[Обновяване на чат интерфейса]
G --> H[Готово за следващото съобщение]
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
Настройка на структурата на проекта
Създайте директория за фронтенд със следната организирана структура:
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 с тази обмислена структура на маркиране:
<!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>
Разбиране на всеки HTML елемент и неговата цел:
Структура на документа
<!DOCTYPE html>: Казва на браузъра, че това е модерен HTML5<html lang="en">: Определя езика на страницата за екранни четци и инструменти за превод<meta charset="UTF-8">: Осигурява правилно кодиране на знаците за международен текст<meta name="viewport"...>: Прави страницата мобилно адаптивна чрез контрол на мащаба и увеличението
Семантични елементи
<header>: Ясно посочва горната секция с заглавието и описанието<main>: Определя основната област със съдържание (където се случват разговорите)<form>: Семантично правилен за въвеждане от потребител, улеснява навигацията с клавиатура
Функции за достъпност
role="log": Казва на екранните четци, че тази зона съдържа хронологичен журнал на съобщениятаaria-live="polite": Обявява новите съобщения на екранните четци без прекъсванеaria-label: Предоставя описателни етикети за контролите на форматаrequired: Браузърът валидаира, че потребителят е въвел съобщение преди изпращане
Интеграция на CSS и JavaScript
classатрибути: Дават стилови маркери за CSS (напр.chat-container,input-group)idатрибути: Позволяват на JavaScript да намира и манипулира определени елементи- Поставяне на скриптовете: JavaScript файлът се зарежда накрая, така че HTML да се зареди първо
Защо тази структура работи:
- Логичен поток: Хедър → Основно съдържание → Форма за въвеждане отговаря на естествения ред на четене
- Достъпно с клавиатура: Потребителите могат да табулират през всички интерактивни елементи
- Удобно за екранни четци: Ясни ориентири и описания за хора с увреждания
- Мобилно адаптивно: Viewport meta тагът позволява адаптивен дизайн
- Прогресивно подобрение: Работи дори ако CSS или JavaScript не се заредят
Добавяне на интерактивен JavaScript: Логика за модерно уеб приложение
Сега нека да изградим JavaScript-а, който ще оживи нашия чат интерфейс. Ще използваме модерни JavaScript практики, които ще срещнете в професионалната уеб разработка, включително ES6 класове, async/await и програмиране, базирано на събития.
Разбиране на модерната JavaScript архитектура
Вместо да пишем процедурен код (ред функции, които се изпълняват една след друга), ще създадем архитектура на базата на класове. Помислете за клас като план за създаване на обекти – както архитектурен план може да се използва за построяване на множество къщи.
Защо да използваме класове за уеб приложения?
- Организация: Всичката свързана функционалност е групирана заедно
- Повторна употреба: Може да създадете множество чат инстанции на една страница
- Поддръжка: По-лесно е да се отстраняват грешки и да се модифицират специфични функции
- Професионален стандарт: Този модел се използва във фреймуъркове като React, Vue и Angular
Създайте app.js с този модерен, добре структуриран JavaScript:
// app.js - Логика на модерно чат приложение
class ChatApp {
constructor() {
// Вземете препратки към DOM елементите, които ще трябва да манипулираме
this.messages = document.getElementById("messages");
this.form = document.getElementById("chatForm");
this.input = document.getElementById("messageInput");
this.sendButton = document.getElementById("sendBtn");
// Конфигурирайте URL на бекенда тук
this.BASE_URL = "http://localhost:5000"; // Актуализирайте това според вашата среда
this.API_ENDPOINT = `${this.BASE_URL}/hello`;
// Настройте слушатели на събития, когато чат приложението се създаде
this.initializeEventListeners();
}
initializeEventListeners() {
// Слушайте за изпращане на формуляра (когато потребителят кликне Изпрати или натисне Enter)
this.form.addEventListener("submit", (e) => this.handleSubmit(e));
// Също така слушайте за клавиша Enter в полето за въвеждане (по-добро потребителско изживяване)
this.input.addEventListener("keypress", (e) => {
if (e.key === "Enter" && !e.shiftKey) {
e.preventDefault();
this.handleSubmit(e);
}
});
}
async handleSubmit(event) {
event.preventDefault(); // Предотвратете формулярът да презарежда страницата
const messageText = this.input.value.trim();
if (!messageText) return; // Не изпращайте празни съобщения
// Дайте обратна връзка на потребителя, че нещо се случва
this.setLoading(true);
// Добавете потребителското съобщение в чата веднага (оптимистичен UI)
this.appendMessage(messageText, "user");
// Изчистете полето за въвеждане, за да може потребителят да въведе следващото съобщение
this.input.value = '';
try {
// Извикайте AI API и изчакайте отговора
const reply = await this.callAPI(messageText);
// Добавете отговора на AI в чата
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 {
// Отново активирайте интерфейса независимо от успеха или неуспеха
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";
}
}
// Инициализирайте чат приложението при зареждане на страницата
document.addEventListener("DOMContentLoaded", () => {
new ChatApp();
});
Разбиране на всеки JavaScript концепт
ES6 структура на клас:
class ChatApp {
constructor() {
// Това се изпълнява, когато създавате нов екземпляр на ChatApp
// Това е като функцията "setup" за вашия чат
}
methodName() {
// Методите са функции, които принадлежат на класа
// Те могат да имат достъп до свойствата на класа, като използват "this"
}
}
Async/Await модел:
// Стар начин (callback ад):
fetch(url)
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error(error));
// Модерен начин (async/await):
try {
const response = await fetch(url);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
Програмиране, базирано на събития: Вместо непрекъснато да проверяваме дали нещо се е случило, ние „слушаме“ за събития:
// Когато формата бъде изпратена, изпълни handleSubmit
this.form.addEventListener("submit", (e) => this.handleSubmit(e));
// Когато се натисне клавиш Enter, също изпълни handleSubmit
this.input.addEventListener("keypress", (e) => { /* ... */ });
Манипулация на DOM:
// Създаване на нови елементи
const messageElement = document.createElement("div");
// Промяна на техните свойства
messageElement.className = "message user";
messageElement.innerHTML = "Hello world!";
// Добавяне към страницата
this.messages.appendChild(messageElement);
Сигурност и добри практики
Предотвратяване на XSS:
escapeHtml(text) {
const div = document.createElement('div');
div.textContent = text; // Това автоматично избягва HTML
return div.innerHTML;
}
Защо е важно: Ако потребител напише <script>alert('hack')</script>, тази функция гарантира, че то се показва като текст, а не изпълнява код.
Обработка на грешки:
try {
const reply = await this.callAPI(messageText);
this.appendMessage(reply, "assistant");
} catch (error) {
// Покажете удобна за потребителя грешка вместо да се срине приложението
this.appendMessage("Sorry, I'm having trouble...", "error");
}
Съображения за потребителския опит:
- Оптимистичен UI: Добавя съобщението веднага, не чака отговор от сървъра
- Състояния на зареждане: Деактивиране на бутоните и показване на „Изпращане...“ докато чакаме
- Автоматично превъртане: Показване на най-новите съобщения
- Валидиране на въвеждането: Не изпращайте празни съобщения
- Клавишни комбинации: Клавиш Enter изпраща съобщението (като истинските чат приложения)
Разбиране на потока на приложението
- Зареждане на страницата → сработва събитие
DOMContentLoaded→ създава сеnew ChatApp() - Изпълнение на конструктора → Взема DOM елементи → Настройва слушатели за събития
- Потребител въвежда съобщение → Натиска Enter или бутона Изпрати → изпълнява се
handleSubmit - handleSubmit → Валидира въведеното → Показва състояние на зареждане → Извиква API
- API отговаря → Добавя съобщение от AI към чата → Активира интерфейса отново
- Готово за следващо съобщение → Потребителят продължава да чатва
Тази архитектура е мащабируема – лесно можете да добавите функции като редактиране на съобщения, качване на файлове или множество разговори без да презаписвате основната структура.
🎯 Педагогическа проверка: Модерна фронтенд архитектура
Разбиране на архитектурата: Имплементирали сте пълно едностранично приложение с модерни JavaScript модели. Това представлява професионално фронтенд разработване.
Основни усвоени понятия:
- ES6 архитектура с класове: Организиран, поддържащ се код
- Async/Await модели: Модерно асинхронно програмиране
- Програмиране на базата на събития: Отзивчив дизайн на потребителския интерфейс
- Добри практики за сигурност: Предотвратяване на XSS и валидиране на въвеждането
Връзка с индустрията: Моделите, които сте научили (архитектура с класове, async операции, манипулация на DOM) са основата на модерни фреймуъркове като React, Vue и Angular. Вие изграждате с архитектурно мислене, използвано в продукционни приложения.
Рефлексия: Как бихте разширили това чат приложение, за да поддържа множество разговори или потребителска автентикация? Помислете за нужните архитектурни промени и как би се развила структурата на класовете.
Стилизиране на вашия чат интерфейс
Сега нека създадем модерен, визуално привлекателен чат интерфейс с CSS. Добрата стилизация прави приложението ви професионално и подобрява цялостното потребителско изживяване. Ще използваме модерни CSS функции като Flexbox, CSS Grid и потребителски свойства за отзивчив и достъпен дизайн.
Създайте styles.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;
}
}
Разбиране на CSS архитектурата:
- Използва CSS потребителски променливи (вариабли) за последователна тематика и лесна поддръжка
- Прилага Flexbox оформление за отзивчив дизайн и правилно подравняване
- Включва плавни анимации за появяване на съобщения без да разсейват
- Осигурява визуална разлика между потребителските съобщения, AI отговорите и състоянията на грешки
- Поддържа отзивчив дизайн както за настолни, така и за мобилни устройства
- Взема предвид достъпността с предпочитания за намалено движение и правилни съотношения на контраста
- Предлага поддръжка на тъмен режим, базиран на системните предпочитания на потребителя
Конфигуриране на URL за вашия бекенд
Последната стъпка е да актуализирате BASE_URL в JavaScript-а, за да съвпада с вашия бекенд сървър:
// За локална разработка
this.BASE_URL = "http://localhost:5000";
// За GitHub Codespaces (заменете с вашия реален URL)
this.BASE_URL = "https://your-codespace-name-5000.app.github.dev";
Определяне на URL за вашия бекенд:
- Локална разработка: Използвайте
http://localhost:5000, ако работите и фронтенд и бекенд локално - Codespaces: Намерете бекенд URL в таба с портове, след като направите порт 5000 публичен
- Продакшън: Заменете с реалния домейн, когато публикувате на хостинг услуга
💡 Съвет за тестване: Можете да тествате директно бекенда като посетите коренния URL в браузъра си. Трябва да видите приветственото съобщение от вашия FastAPI сървър.
Тестване и Деплоймънт
Сега, когато имате изградени и фронтенд, и бекенд компоненти, нека тестваш дали всичко работи заедно и разгледаме опции за публикуване, за да споделите чат асистента с други.
Работен поток за локално тестване
Следвайте тези стъпки, за да изпробвате цялото приложение:
graph TD
A[Стартиране на Backend сървър] --> B[Конфигуриране на променливи на средата]
B --> C[Тестване на API крайни точки]
C --> D[Отваряне на Frontend в браузър]
D --> E[Тестване на чат функционалност]
E --> F[Отстраняване на грешки]
Поетапен процес на тестване:
-
Стартирайте бекенд сървъра си:
cd backend source venv/bin/activate # или venv\Scripts\activate в Windows python api.py -
Проверете дали API работи:
- Отворете
http://localhost:5000в браузъра си - Трябва да видите приветственото съобщение от FastAPI сървъра
- Отворете
-
Отворете фронтенда си:
- Отидете в директорията на фронтенда
- Отворете
index.htmlв браузъра - Или използвайте разширението Live Server на VS Code за по-добро разработване
-
Изпробвайте чат функционалността:
- Въведете съобщение в полето за въвеждане
- Натиснете "Изпрати" или Enter
- Проверете дали AI отговаря правилно
- Проверете конзолата на браузъра за JavaScript грешки
Отстраняване на често срещани проблеми
| Проблем | Симптоми | Решение |
|---|---|---|
| Грешка CORS | Фронтенд не може да достъпи бекенда | Уверете се, че FastAPI CORSMiddleware е правилно конфигуриран |
| Грешка с API ключ | 401 Unauthorized отговори | Проверете променливата на средата GITHUB_TOKEN |
| Връзката е отказана | Грешки в мрежата във фронтенда | Проверете URL на бекенда и дали Flask сървърът работи |
| Няма AI отговор | Празни или грешни отговори | Проверете логовете на бекенда за квоти или проблеми с автентикацията |
Често използвани стъпки за дебъг:
- Проверете конзолата на Developer Tools за JavaScript грешки
- Проверете Network таба за успешни API заявки и отговори
- Прегледайте изхода в терминала на бекенда за Python грешки или проблеми с API
- Потвърдете че променливите на средата са коректно заредени и достъпни
📈 Вашата времева линия за овладяване на разработка на AI приложения
timeline
title Пълно пътешествие в разработката на AI приложения
section Основи на AI
Разбиране на генеративния AI
: Усвояване на концепции за разпознаване на образци
: Овладяване на управлението на параметрите на AI
: Научаване на техники за инженеринг на подканите
Интеграция на модели от GitHub
: Навигация в платформите за AI услуги
: Сигурно управление на автентикацията
: Оптимизация на параметрите на модела
section Разработка на бекенд
Архитектура на Python API
: Създаване на FastAPI приложения
: Имплементиране на асинхронни операции
: Създаване на защитени крайни точки
Интеграция на AI услуги
: Свързване към външни AI API-та
: Управление на ограничаването на честотата
: Имплементиране на граници при грешки
section Майсторство във фронтенд
Модерни JavaScript шаблони
: Овладяване на ES6 класова архитектура
: Имплементиране на async/await потоци
: Създаване на адаптивни интерфейси
Реално време на потребителско изживяване
: Създаване на динамични чат интерфейси
: Управление на състояния за зареждане
: Оптимизация на потребителските взаимодействия
section Готовност за продукция
Сигурност и производителност
: Имплементиране на сигурно управление на токени
: Предотвратяване на XSS уязвимости
: Оптимизация на производителността на API
Професионално внедряване
: Изграждане на мащабируеми архитектури
: Създаване на поддържлив код
: Документиране на процесите на разработка
🎓 Ключова цел: Успешно сте изградили пълно AI-задвижвано приложение с помощта на същите технологии и архитектурни модели, които захранват модерните AI асистенти. Тези умения са пресечната точка между традиционната уеб разработка и напредналото AI интегриране.
🔄 Следващо ниво възможности:
- Готови сте да изследвате напреднали AI фреймуъркове (LangChain, LangGraph)
- Подготвени сте да изграждате мултимодални AI приложения (текст, изображение, глас)
- Оборудвани сте да имплементирате векторни бази данни и системи за търсене
- Основата е изградена за машинно обучение и фина настройка на AI модели
Предизвикателство GitHub Copilot Agent 🚀
Използвайте режим Agent, за да изпълните следното предизвикателство:
Описание: Добавете към чат асистента история на разговорите и запазване на съобщенията. Това ще ви помогне да научите как да управлявате състоянието в чат приложения и как да имплементирате съхранение на данни за по-добро потребителско изживяване.
Задача: Модифицирайте чат приложението да включва история на разговорите, която се запазва между сесиите. Добавете функционалност за запазване на чат съобщения в local storage, показване на историята при зареждане на страницата и бутон "Изчисти история". Също така имплементирайте индикатори за писане и отметки за времето на съобщенията, за да направите чата по-реалистичен.
Научете повече за agent mode тук.
Задание: Изградете своя личен AI асистент
Сега ще създадете собствена имплементация на AI асистент. Вместо просто да копирате кода от урока, това е възможност да приложите концепциите, като изградите нещо, което отразява вашите интереси и цели.
Изисквания за проекта
Нека организираме проекта ви с чиста, подредена структура:
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
Основни задачи за имплементация
Разработка на бекенд:
- Използвайте нашия FastAPI код като основа и го направете свой
- Създайте уникална AI личност – може би полезен готварски асистент, творчески партньор за писане или учебен приятел?
- Добавете стабилна обработка на грешки, за да не спира приложението при проблеми
- Напишете ясна документация за всеки, който иска да разбере как работи вашият API
Разработка на фронтенд:
- Изградете чат интерфейс, който да е интуитивен и приветлив
- Напишете чист, модерен JavaScript, с който да се гордеете пред други разработчици
- Дизайнирайте персонализирани стилове, които отразяват личността на вашия AI – забавен и цветен? Чист и минималистичен? Изцяло ваш избор!
- Уверете се, че работи добре и на телефони, и на компютри
Персонализационни изисквания:
- Изберете уникално име и характер за вашия AI асистент – нещо, което отразява интересите ви или проблемите, които искате да решите
- Персонализирайте визуалния дизайн според атмосферата на асистента
- Напишете привлекателно приветствено съобщение, което кара хората да искат да започнат чат
- Тествайте асистента си с различни въпроси, за да видите как отговаря
Идеи за подобрения (по избор)
Искате да издигнете проекта си на следващото ниво? Ето някои интересни идеи:
| Функция | Описание | Умения, които ще практикувате |
|---|---|---|
| История на съобщения | Запомня разговорите дори след презареждане на страницата | Работа с localStorage, обработка на JSON |
| Индикатори за писане | Показва „AI пише...“ докато чака отговор | CSS анимации, асинхронно програмиране |
| Отметки за времето на съобщенията | Показва кога е изпратено всяко съобщение | Форматиране на дата/час, UX дизайн |
| Експорт на чат | Позволява на потребителите да изтеглят разговора си | Работа с файлове, експорт на данни |
| Смяна на тема | Превключване между светъл и тъмен режим | CSS променливи, потребителски предпочитания |
| Гласов вход | Добавя функция за реч към текст | Уеб API, достъпност |
Тестване и документация
Гаранция за качество:
- Тествайте приложението си с различни типове вход и гранични случаи
- Проверете дали отзивчивият дизайн работи на различни резолюции
- Проверете достъпността с навигация с клавиатура и четци на екрана
- Валидирайте HTML и CSS към стандартите
Изисквания за документацията:
- Напишете README.md с описание на проекта и как да се стартира
- Включете екранни снимки на чат интерфейса в действие
- Документирайте уникални функции или персонализации
- Дайте ясни инструкции за настройка за други разработчици
Насоки за подаване
Проектните документи:
- Цяла папка с проекта и изходния код
- README.md с описание на проекта и инструкции за стартиране
- Скриншотове, показващи работещия чат асистент
- Кратък разказ за наученото и предизвикателствата
Критерии за оценяване:
- Функционалност: Работи ли чат асистентът както се очаква?
- Качество на кода: Добре ли е организиран, коментиран и поддържан?
- Дизайн: Визуално привлекателен и лесен за ползване ли е интерфейсът?
- Креативност: Колко уникална и персонализирана е вашата версия?
- Документация: Ясни и пълни ли са инструкциите за настройка?
💡 Съвет за успех: Започнете с базовите изисквания, след това постепенно добавяйте подобрения. Фокусирайте се първо върху създаване на завършен основен опит, преди да добавяте напреднали функции.
Решение
Бонус предизвикателства
Готови ли сте да издигнете AI асистента си на следващото ниво? Опитайте тези напреднали предизвикателства, които ще задълбочат разбирането ви за AI интеграция и уеб разработка.
Персонализация на личността
Истинската магия се случва, когато придадете на AI асистента уникална личност. Експериментирайте с различни системни подсказки, за да създадете специализирани асистенти:
Пример за професионален асистент:
call_llm(message, "You are a professional business consultant with 20 years of experience. Provide structured, actionable advice with specific steps and considerations.")
Помощник за творческо писане:
call_llm(message, "You are an enthusiastic creative writing coach. Help users develop their storytelling skills with imaginative prompts and constructive feedback.")
Пример за технически ментор:
call_llm(message, "You are a patient senior developer who explains complex programming concepts using simple analogies and practical examples.")
Фронтенд подобрения
Трансформирайте чат интерфейса с тези визуални и функционални подобрения:
Напреднали CSS функции:
- Прилагайте плавни анимации и преходи за съобщенията
- Добавете персонализирани чат балони със CSS форми и градиенти
- Създайте анимация за индикатор за писане, когато AI „мисли“
- Дизайнирайте реакции с емоджита или система за оценка на съобщения
JavaScript подобрения:
- Добавете клавишни комбинации (Ctrl+Enter за изпращане, Escape за изчистване)
- Имплементирайте търсене и филтриране на съобщения
- Създайте функция за износ на разговор (изтегляне като текст или JSON)
- Добавете авто-запазване в localStorage, за да се предотврати загуба на съобщения
Напреднала AI интеграция
Множество AI личности:
- Създайте падащо меню за превключване между различни AI личности
- Запазвайте избраната личност на потребителя в localStorage
- Имплементирайте превключване на контекста, което запазва потока на разговора
Интелигентни функции за отговор:
- Добавете осъзнаване на контекста в разговора (AI помни предишни съобщения)
- Изпълнете интелигентни предложения въз основа на темата на разговора
- Създайте бутони за бърз отговор за често задавани въпроси
🎯 Цел на обучението: Тези бонус предизвикателства ви помагат да разберете напреднали модели за уеб разработка и техники за интеграция на ИИ, които се използват в продукционни приложения.
Обобщение и следващи стъпки
Поздравления! Успешно създадохте пълен чат асистент с изкуствен интелект от нулата. Този проект ви предостави практически опит с модерни технологии за уеб разработка и интеграция на ИИ – умения, които стават все по-ценни в съвременния технологичен пейзаж.
Какво постигнахте
През този урок овладяхте няколко ключови технологии и концепции:
Backend разработка:
- Интегрирахте се с GitHub Models API за функционалност с ИИ
- Изградихте RESTful API с Flask с правилна обработка на грешки
- Реализирахте сигурна автентикация чрез променливи на средата
- Конфигурирахте CORS за заявки между фронтенд и бекенд
Frontend разработка:
- Създадохте отзивчив чат интерфейс с използване на семантичен HTML
- Използвахте модерен JavaScript с async/await и архитектура базирана на класове
- Дизайнихте завладяващ потребителски интерфейс с CSS Grid, Flexbox и анимации
- Добавихте функции за достъпност и принципи на адаптивен дизайн
Пълна стек интеграция:
- Свързахте фронтенд и бекенд чрез HTTP API извиквания
- Обработвахте реалновременни потребителски взаимодействия и асинхронен поток от данни
- Имплементирахте обработка на грешки и обратна връзка към потребителя из цялото приложение
- Тествахте цялостния работен процес от потребителски вход до отговор на ИИ
Основни научени резултати
mindmap
root((Умения за AI чат приложение))
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
Този проект ви въведе в основите на създаването на приложения с изкуствен интелект, които представляват бъдещето на уеб разработката. Сега разбирате как да интегрирате ИИ функционалности в традиционни уеб приложения, създавайки завладяващи потребителски преживявания, които се усещат интелигентни и отзивчиви.
Професионални приложения
Уменията, които развихте в този урок, са директно приложими към съвременната кариера в софтуерната разработка:
- Пълна стек уеб разработка с модерни рамки и API-та
- Интеграция на ИИ в уеб и мобилни приложения
- Проектиране и разработка на API за микроуслуги
- Разработка на потребителски интерфейси с акцент върху достъпността и адаптивния дизайн
- DevOps практики, включващи конфигуриране на среди и деплоймънт
Продължаване на Вашето AI развитие
Следващи стъпки за учене:
- Изследвайте по-напреднали AI модели и API-та (GPT-4, Claude, Gemini)
- Научете се на техники за prompt engineering за по-добри отговори от ИИ
- Изучете дизайн на разговори и принципи за потребителско преживяване на чатботове
- Разгледайте безопасността, етиката и отговорното развитие на ИИ
- Създавайте по-сложни приложения с памет на разговорите и контекстна осъзнатост
Идеи за напреднали проекти:
- Много-потребителски чат стаи с ИИ модерация
- Чатботове за обслужване на клиенти с изкуствен интелект
- Обучителни асистенти с персонализирано обучение
- Творчески сътрудници за писане с различни ИИ личности
- Асистенти за техническа документация за разработчици
Започване с GitHub Codespaces
Искате ли да опитате този проект в облачна среда за разработка? GitHub Codespaces предоставя пълна развойна среда в браузъра ви, идеална за експериментиране с ИИ приложения без нужда от локална настройка.
Настройване на вашата развойна среда
Стъпка 1: Създаване от шаблон
- Отидете до Web Dev For Beginners repository
- Кликнете "Use this template" в горния десен ъгъл (уверете се, че сте влезли в GitHub)
Стъпка 2: Стартиране на Codespaces
- Отворете новосъздадения си репозиториум
- Кликнете зеления бутон "Code" и изберете "Codespaces"
- Изберете "Create codespace on main" за стартиране на развойната си среда
Стъпка 3: Конфигуриране на средата
След като вашият Codespace се зареди, ще имате достъп до:
- Предварително инсталирани Python, Node.js и всички необходими инструменти за разработка
- VS Code интерфейс с разширения за уеб разработка
- Терминален достъп за стартиране на бекенд и фронтенд сървъри
- Пренасочване на портове за тестване на вашите приложения
Какво предоставят Codespaces:
- Премахва нуждата от локална настройка и конфигуриране на средата
- Осигурява постоянна среда за разработка във всички устройства
- Включва предварително конфигурирани инструменти и разширения за уеб разработка
- Предлага безпроблемна интеграция с GitHub за управление на версиите и сътрудничество
🚀 Профи съвет: Codespaces е идеален за обучение и прототипиране на AI приложения, тъй като автоматично се грижи за всички сложни настройки на средата, позволявайки ви да се концентрирате върху създаването и ученето, вместо върху отстраняването на конфигурационни проблеми.
Отказ от отговорност: Този документ е преведен с помощта на AI услуга за превод Co-op Translator. Въпреки че се стремим към точност, моля, имайте предвид, че автоматичните преводи могат да съдържат грешки или неточности. Оригиналният документ на родния му език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Не носим отговорност за никакви недоразумения или неправилни тълкувания, произтичащи от използването на този превод.