# בניית עוזר צ'אט עם AI
זוכרים את "מסע בין כוכבים" כשהצוות היה משוחח עם מחשב הספינה, שואל שאלות מורכבות ומקבל תשובות מחושבות? מה שנראה כמו מדע בדיוני טהור בשנות ה-60 הוא עכשיו משהו שאתם יכולים לבנות באמצעות טכנולוגיות אינטרנט שאתם כבר מכירים.
בשיעור הזה, ניצור עוזר צ'אט מבוסס AI באמצעות HTML, CSS, JavaScript וקצת אינטגרציה בצד השרת. תגלו איך הכישורים שאתם כבר לומדים יכולים להתחבר לשירותי AI חזקים שמבינים הקשר ומייצרים תשובות משמעותיות.
חשבו על AI כמו גישה לספרייה עצומה שיכולה לא רק למצוא מידע אלא גם לסנתז אותו לתשובות קוהרנטיות המותאמות לשאלות שלכם. במקום לחפש בין אלפי עמודים, אתם מקבלים תשובות ישירות וממוקדות.
האינטגרציה מתבצעת באמצעות טכנולוגיות אינטרנט מוכרות שעובדות יחד. HTML יוצר את ממשק הצ'אט, CSS מטפל בעיצוב החזותי, JavaScript מנהל את האינטראקציות עם המשתמש, ו-API בצד השרת מחבר הכל לשירותי AI. זה דומה לאיך חלקים שונים בתזמורת עובדים יחד כדי ליצור סימפוניה.
בעצם אנחנו בונים גשר בין תקשורת אנושית טבעית לעיבוד מכונה. תלמדו גם את היישום הטכני של אינטגרציית שירותי AI וגם את דפוסי העיצוב שגורמים לאינטראקציות להרגיש אינטואיטיביות.
בסוף השיעור הזה, אינטגרציית AI תרגיש פחות כמו תהליך מסתורי ויותר כמו עוד API שאפשר לעבוד איתו. תבינו את דפוסי היסוד שמניעים יישומים כמו ChatGPT ו-Claude, תוך שימוש באותם עקרונות פיתוח אינטרנט שאתם כבר לומדים.
## ⚡ מה אפשר לעשות ב-5 דקות הקרובות
**מסלול התחלה מהירה למפתחים עסוקים**
```mermaid
flowchart LR
A[⚡ 5 minutes] --> B[Get GitHub token]
B --> C[Test AI playground]
C --> D[Copy Python code]
D --> E[See AI responses]
```
- **דקה 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 From Web Development to AI Integration
section Understanding AI Foundations
Discover generative AI concepts: 4: You
Explore GitHub Models platform: 6: You
Master AI parameters and prompts: 8: You
section Backend Integration
Build Python API server: 5: You
Implement AI function calls: 7: You
Handle async operations: 8: You
section Frontend Development
Create modern chat interface: 6: You
Master real-time interactions: 8: You
Build responsive user experience: 9: You
section Professional Application
Deploy complete AI system: 7: You
Optimize performance patterns: 8: You
Create production-ready app: 9: You
```
**יעד המסע שלכם**: בסוף השיעור הזה, תבנו אפליקציה שלמה מבוססת AI באמצעות אותן טכנולוגיות ודפוסים שמניעים עוזרי AI מודרניים כמו ChatGPT, Claude ו-Google Bard.
## הבנת AI: ממסתורין לשליטה
לפני שנצלול לקוד, בואו נבין עם מה אנחנו עובדים. אם השתמשתם ב-APIs בעבר, אתם מכירים את הדפוס הבסיסי: שליחת בקשה, קבלת תשובה.
APIs של AI פועלים במבנה דומה, אבל במקום לשלוף נתונים שמורים מראש ממאגר מידע, הם מייצרים תשובות חדשות בהתבסס על דפוסים שנלמדו מכמויות עצומות של טקסט. חשבו על זה כמו ההבדל בין מערכת קטלוג ספרייה לבין ספרן בעל ידע שמסנתז מידע ממקורות רבים.
### מה זה בעצם "Generative AI"?
חשבו איך אבן הרוזטה אפשרה לחוקרים להבין הירוגליפים מצריים על ידי מציאת דפוסים בין שפות מוכרות ולא מוכרות. מודלים של AI פועלים באופן דומה – הם מוצאים דפוסים בכמויות עצומות של טקסט כדי להבין איך שפה עובדת, ואז משתמשים בדפוסים האלה כדי לייצר תשובות מתאימות לשאלות חדשות.
**בואו נפשט את זה עם השוואה פשוטה:**
- **מאגר נתונים מסורתי**: כמו לבקש תעודת לידה – אתם מקבלים את אותו מסמך בדיוק בכל פעם
- **מנוע חיפוש**: כמו לבקש מספרן למצוא ספרים על חתולים – הם מראים לכם מה זמין
- **Generative AI**: כמו לשאול חבר בעל ידע על חתולים – הם מספרים לכם דברים מעניינים במילים שלהם, מותאמים למה שאתם רוצים לדעת
```mermaid
graph LR
A[Your Question] --> B[AI Model]
B --> C[Pattern Recognition]
C --> D[Content Generation]
D --> E[Contextual Response]
F[Training Data Books, Articles, Web] --> B
```
### איך מודלים של AI לומדים (הגרסה הפשוטה)
מודלים של AI לומדים דרך חשיפה למאגרי נתונים עצומים המכילים טקסט מספרים, מאמרים ושיחות. בתהליך הזה, הם מזהים דפוסים ב:
- איך מחשבות מובנות בתקשורת כתובה
- אילו מילים מופיעות יחד בדרך כלל
- איך שיחות זורמות בדרך כלל
- הבדלים הקשריים בין תקשורת פורמלית ולא פורמלית
**זה דומה לאיך שארכיאולוגים מפענחים שפות עתיקות**: הם מנתחים אלפי דוגמאות כדי להבין דקדוק, אוצר מילים והקשר תרבותי, ובסופו של דבר מסוגלים לפרש טקסטים חדשים באמצעות הדפוסים שנלמדו.
### למה דווקא GitHub Models?
אנחנו משתמשים ב-GitHub Models מסיבה די פרקטית – זה נותן לנו גישה ל-AI ברמה ארגונית מבלי שנצטרך להקים תשתית AI משלנו (שזה, תאמינו לי, לא משהו שתרצו לעשות כרגע!). חשבו על זה כמו להשתמש ב-API של מזג אוויר במקום לנסות לחזות את מזג האוויר בעצמכם על ידי הקמת תחנות מזג אוויר בכל מקום.
זה בעצם "AI כשירות", והחלק הכי טוב? זה חינמי להתחיל, כך שתוכלו להתנסות מבלי לדאוג לחשבון מנופח.
```mermaid
graph LR
A[Frontend Chat UI] --> B[Your Backend API]
B --> C[GitHub Models API]
C --> D[AI Model Processing]
D --> C
C --> B
B --> A
```
נשתמש ב-GitHub Models לאינטגרציה בצד השרת, שמספקת גישה ליכולות AI ברמה מקצועית דרך ממשק ידידותי למפתחים. [GitHub Models Playground](https://github.com/marketplace/models/azure-openai/gpt-4o-mini/playground) משמש כסביבת בדיקה שבה תוכלו להתנסות במודלים שונים של AI ולהבין את יכולותיהם לפני יישומם בקוד.
## 🧠 אקוסיסטם פיתוח אפליקציות AI
```mermaid
mindmap
root((AI Development))
Understanding AI
Generative Models
Pattern Recognition
Content Generation
Context Understanding
Response Synthesis
AI Parameters
Temperature Control
Token Limits
Top-p Filtering
System Prompts
Backend Architecture
API Integration
GitHub Models
Authentication
Request Handling
Error Management
Python Infrastructure
FastAPI Framework
Async Operations
Environment Security
CORS Configuration
Frontend Experience
Chat Interface
Real-time Updates
Message History
User Feedback
Loading States
Modern Web Tech
ES6 Classes
Async/Await
DOM Manipulation
Event Handling
Professional Patterns
Security Best Practices
Token Management
Input Validation
XSS Prevention
Error Boundaries
Production Readiness
Performance Optimization
Responsive Design
Accessibility
Testing Strategies
```
**עיקרון מרכזי**: פיתוח אפליקציות 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
# To authenticate with the model you will need to generate a personal access token (PAT) in your GitHub settings.
# Create your PAT token by following instructions here: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
client = OpenAI(
base_url="https://models.github.ai/inference",
api_key=os.environ["GITHUB_TOKEN"],
)
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 שיפנה לשרתים של 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: כוונון התנהגות התשובה
הפרמטרים המספריים בקריאות API של AI שולטים באיך המודל מייצר תשובות. ההגדרות האלה מאפשרות לכם להתאים את התנהגות ה-AI לשימושים שונים:
#### Temperature (0.0 עד 2.0): כפתור היצירתיות
**מה זה עושה**: שולט עד כמה התשובות של ה-AI יהיו יצירתיות או צפויות.
**חשבו על זה כמו רמת האלתור של מוזיקאי ג'אז:**
- **Temperature = 0.1**: מנגן את אותה מנגינה בדיוק בכל פעם (צפוי מאוד)
- **Temperature = 0.7**: מוסיף כמה וריאציות בטעם תוך שמירה על זיהוי (יצירתיות מאוזנת)
- **Temperature = 1.5**: ג'אז ניסיוני מלא עם פניות בלתי צפויות (בלתי צפוי מאוד)
```python
# Very predictable responses (good for factual questions)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "What is 2+2?"}],
temperature=0.1 # Will almost always say "4"
)
# Creative responses (good for brainstorming)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Write a creative story opening"}],
temperature=1.2 # Will generate unique, unexpected stories
)
```
#### Max Tokens (1 עד 4096+): בקר אורך התשובה
**מה זה עושה**: קובע גבול על כמה ארוכה יכולה להיות תשובת ה-AI.
**חשבו על טוקנים כבערך שווים למילים** (בערך 1 טוקן = 0.75 מילים באנגלית):
- **max_tokens=50**: קצר וקולע (כמו הודעת טקסט)
- **max_tokens=500**: פסקה או שתיים נחמדות
- **max_tokens=2000**: הסבר מפורט עם דוגמאות
```python
# Short, concise answers
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Explain JavaScript"}],
max_tokens=100 # Forces a brief explanation
)
# Detailed, comprehensive answers
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Explain JavaScript"}],
max_tokens=1500 # Allows for detailed explanations with examples
)
```
#### Top_p (0.0 עד 1.0): פרמטר המיקוד
**מה זה עושה**: שולט עד כמה ה-AI נשאר ממוקד בתשובות הסבירות ביותר.
**דמיינו של-AI יש אוצר מילים עצום, מדורג לפי כמה כל מילה סבירה:**
- **top_p=0.1**: מתחשב רק ב-10% מהמילים הסבירות ביותר (ממוקד מאוד)
- **top_p=0.9**: מתחשב ב-90% מהמילים האפשריות (יותר יצירתי)
- **top_p=1.0**: מתחשב בהכל (מגוון מקסימלי)
**לדוגמה**: אם תשאלו "השמיים בדרך כלל..."
- **top_p נמוך**: כמעט בוודאות יגיד "כחולים"
- **top_p גבוה**: עשוי לומר "כחולים", "מעוננים", "רחבים", "משתנים", "יפים" וכו'.
### חיבור הכל יחד: שילובי פרמטרים לשימושים שונים
```python
# For factual, consistent answers (like a documentation bot)
factual_params = {
"temperature": 0.2,
"max_tokens": 300,
"top_p": 0.3
}
# For creative writing assistance
creative_params = {
"temperature": 1.1,
"max_tokens": 1000,
"top_p": 0.9
}
# For conversational, helpful responses (balanced)
conversational_params = {
"temperature": 0.7,
"max_tokens": 500,
"top_p": 0.8
}
```
```mermaid
quadrantChart
title AI Parameter Optimization Matrix
x-axis Low Creativity --> High Creativity
y-axis Short Response --> Long Response
quadrant-1 Creative Content
quadrant-2 Detailed Analysis
quadrant-3 Quick Facts
quadrant-4 Conversational 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
# ❌ Vague system prompt
"You are helpful."
# ✅ Detailed, effective system prompt
"You are Dr. Sarah Chen, a senior software engineer with 15 years of experience at major tech companies. You explain programming concepts using real-world analogies and always provide practical examples. You're patient with beginners and enthusiastic about helping them understand complex topics."
```
#### דוגמאות להנחיות מערכת עם הקשר
בואו נראה איך הנחיות מערכת שונות יוצרות אישיות AI שונות לחלוטין:
```python
# Example 1: The Patient Teacher
teacher_prompt = """
You are an experienced programming instructor who has taught thousands of students.
You break down complex concepts into simple steps, use analogies from everyday life,
and always check if the student understands before moving on. You're encouraging
and never make students feel bad for not knowing something.
"""
# Example 2: The Creative Collaborator
creative_prompt = """
You are a creative writing partner who loves brainstorming wild ideas. You're
enthusiastic, imaginative, and always build on the user's ideas rather than
replacing them. You ask thought-provoking questions to spark creativity and
offer unexpected perspectives that make stories more interesting.
"""
# Example 3: The Strategic Business Advisor
business_prompt = """
You are a strategic business consultant with an MBA and 20 years of experience
helping startups scale. You think in frameworks, provide structured advice,
and always consider both short-term tactics and long-term strategy. You ask
probing questions to understand the full business context before giving advice.
"""
```
#### לראות הנחיות מערכת בפעולה
בואו נבדוק את אותה שאלה עם הנחיות מערכת שונות כדי לראות את ההבדלים הדרמטיים:
**שאלה**: "איך אני מטפל באימות משתמש באפליקציית האינטרנט שלי?"
```python
# With teacher prompt:
teacher_response = call_llm(
"How do I handle user authentication in my web app?",
teacher_prompt
)
# Typical response: "Great question! Let's break authentication down into simple steps.
# Think of it like a nightclub bouncer checking IDs..."
# With business prompt:
business_response = call_llm(
"How do I handle user authentication in my web app?",
business_prompt
)
# Typical response: "From a strategic perspective, authentication is crucial for user
# trust and regulatory compliance. Let me outline a framework considering security,
# user experience, and scalability..."
```
#### טכניקות מתקדמות להנחיות מערכת
**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. עיצוב פלט**: הסבר ל-AI כיצד לבנות תגובות
```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. הגדרת מגבלות**: קבע מה ה-AI לא צריך לעשות
```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.
"""
```
#### למה זה חשוב עבור עוזר הצ'אט שלך
הבנת הנחיות מערכת מעניקה לך כוח מדהים ליצור עוזרי AI מותאמים אישית:
- **בוט שירות לקוחות**: מועיל, סבלני, מודע למדיניות
- **מורה ללמידה**: מעודד, צעד-אחר-צעד, בודק הבנה
- **שותף יצירתי**: יצירתי, בונה על רעיונות, שואל "מה אם?"
- **מומחה טכני**: מדויק, מפורט, מודע לאבטחה
**התובנה המרכזית**: אתה לא רק מפעיל API של AI – אתה יוצר אישיות AI מותאמת שמשרתת את המקרה הספציפי שלך. זה מה שהופך יישומי AI מודרניים למותאמים ושימושיים במקום גנריים.
### 🎯 בדיקה פדגוגית: תכנות אישיות AI
**עצור וחשוב**: הרגע למדת לתכנת אישיות AI באמצעות הנחיות מערכת. זו מיומנות בסיסית בפיתוח יישומי AI מודרניים.
**הערכה עצמית מהירה**:
- האם אתה יכול להסביר כיצד הנחיות מערכת שונות מהודעות משתמש רגילות?
- מה ההבדל בין פרמטרים של temperature ו-top_p?
- כיצד היית יוצר הנחיית מערכת עבור מקרה שימוש ספציפי (כמו מורה לקוד)?
**קישור לעולם האמיתי**: הטכניקות של הנחיות מערכת שלמדת משמשות בכל יישום AI מרכזי - החל מסיוע בקידוד של GitHub Copilot ועד ממשק השיחה של ChatGPT. אתה שולט באותם דפוסים שמשתמשים בהם צוותי מוצר AI בחברות טכנולוגיה גדולות.
**שאלת אתגר**: כיצד היית מעצב אישיות AI שונה עבור סוגי משתמשים שונים (מתחילים מול מומחים)? שקול כיצד אותו מודל AI בסיסי יכול לשרת קהלים שונים באמצעות הנדסת הנחיות.
## בניית ה-API עם FastAPI: מרכז התקשורת המהיר שלך עם AI
עכשיו נבנה את ה-backend שמחבר את ה-frontend לשירותי AI. נשתמש ב-FastAPI, מסגרת Python מודרנית שמצטיינת בבניית APIs ליישומי AI.
FastAPI מציע מספר יתרונות עבור סוג זה של פרויקט: תמיכה מובנית ב-async לטיפול בבקשות מקבילות, יצירת תיעוד API אוטומטי וביצועים מצוינים. שרת ה-FastAPI שלך פועל כמתווך שמקבל בקשות מה-frontend, מתקשר עם שירותי AI ומחזיר תגובות מעוצבות.
### למה FastAPI מתאים ליישומי AI?
אולי אתה תוהה: "האם אני לא יכול פשוט לקרוא ל-AI ישירות מ-JavaScript ב-frontend?" או "למה FastAPI במקום Flask או Django?" שאלות מצוינות!
**הנה למה FastAPI מושלם למה שאנחנו בונים:**
- **Async כברירת מחדל**: יכול לטפל במספר בקשות AI בו-זמנית מבלי להיתקע
- **תיעוד אוטומטי**: בקר ב-`/docs` וקבל דף תיעוד API אינטראקטיבי ויפה בחינם
- **אימות מובנה**: מזהה שגיאות לפני שהן גורמות לבעיות
- **מהיר במיוחד**: אחת המסגרות המהירות ביותר ב-Python
- **Python מודרני**: משתמש בכל התכונות החדשות והטובות ביותר של Python
**והנה למה אנחנו צריכים בכלל backend:**
**אבטחה**: מפתח ה-API של ה-AI שלך הוא כמו סיסמה – אם תשים אותו ב-JavaScript של ה-frontend, כל מי שיצפה בקוד המקור של האתר שלך יוכל לגנוב אותו ולהשתמש בקרדיטים של ה-AI שלך. ה-backend שומר על אישורים רגישים בצורה מאובטחת.
**הגבלת קצב ושליטה**: ה-backend מאפשר לך לשלוט בתדירות שבה משתמשים יכולים לבצע בקשות, ליישם אימות משתמשים ולהוסיף רישום למעקב אחר שימוש.
**עיבוד נתונים**: ייתכן שתרצה לשמור שיחות, לסנן תוכן לא הולם או לשלב מספר שירותי AI. ה-backend הוא המקום שבו ההיגיון הזה מתבצע.
**הארכיטקטורה דומה למודל לקוח-שרת:**
- **Frontend**: שכבת ממשק משתמש לאינטראקציה
- **Backend API**: שכבת עיבוד בקשות וניתוב
- **שירות AI**: חישוב חיצוני ויצירת תגובות
- **משתני סביבה**: אחסון מאובטח של תצורה ואישורים
### הבנת זרימת הבקשה-תגובה
בואו נעקוב אחרי מה שקורה כאשר משתמש שולח הודעה:
```mermaid
sequenceDiagram
participant User as 👤 User
participant Frontend as 🌐 Frontend
participant API as 🔧 FastAPI Server
participant AI as 🤖 AI Service
User->>Frontend: Types "Hello AI!"
Frontend->>API: POST /hello {"message": "Hello AI!"}
Note over API: Validates request Adds system prompt
API->>AI: Sends formatted request
AI->>API: Returns AI response
Note over API: Processes response Logs conversation
API->>Frontend: {"response": "Hello! How can I help?"}
Frontend->>User: Displays AI message
```
**הבנת כל שלב:**
1. **אינטראקציה עם המשתמש**: אדם מקליד בממשק הצ'אט
2. **עיבוד ב-frontend**: JavaScript לוכד את הקלט ומעצב אותו כ-JSON
3. **אימות API**: FastAPI מאמת את הבקשה באופן אוטומטי באמצעות מודלים של Pydantic
4. **שילוב AI**: ה-backend מוסיף הקשר (הנחיית מערכת) וקורא לשירות ה-AI
5. **טיפול בתגובה**: ה-API מקבל את תגובת ה-AI ויכול לשנות אותה אם צריך
6. **תצוגה ב-frontend**: JavaScript מציג את התגובה בממשק הצ'אט
### הבנת ארכיטקטורת API
```mermaid
sequenceDiagram
participant Frontend
participant FastAPI
participant AI Function
participant GitHub Models
Frontend->>FastAPI: POST /hello {"message": "Hello AI!"}
FastAPI->>AI Function: call_llm(message, system_prompt)
AI Function->>GitHub Models: API request
GitHub Models->>AI Function: AI response
AI Function->>FastAPI: response text
FastAPI->>Frontend: {"response": "Hello! How can I help?"}
```
```mermaid
flowchart TD
A[User Input] --> B[Frontend Validation]
B --> C[HTTP POST Request]
C --> D[FastAPI Router]
D --> E[Pydantic Validation]
E --> F[AI Function Call]
F --> G[GitHub Models API]
G --> H[Response Processing]
H --> I[JSON Response]
I --> J[Frontend Update]
subgraph "Security Layer"
K[CORS Middleware]
L[Environment Variables]
M[Error Handling]
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
# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
# Create FastAPI application
app = FastAPI(
title="AI Chat API",
description="A high-performance API for AI-powered chat applications",
version="1.0.0"
)
# Configure CORS
app.add_middleware(
CORSMiddleware,
allow_origins=["*"], # Configure appropriately for production
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
# Pydantic models for request/response validation
class ChatMessage(BaseModel):
message: str
class ChatResponse(BaseModel):
response: str
@app.get("/")
async def root():
"""Root endpoint providing API information."""
return {
"message": "Welcome to the AI Chat API",
"docs": "/docs",
"health": "/health"
}
@app.get("/health")
async def health_check():
"""Health check endpoint."""
return {"status": "healthy", "service": "ai-chat-api"}
@app.post("/hello", response_model=ChatResponse)
async def chat_endpoint(chat_message: ChatMessage):
"""Main chat endpoint that processes messages and returns AI responses."""
try:
# Extract and validate message
message = chat_message.message.strip()
if not message:
raise HTTPException(status_code=400, detail="Message cannot be empty")
logger.info(f"Processing message: {message[:50]}...")
# Call AI service (note: call_llm should be made async for better performance)
ai_response = await call_llm_async(message, "You are a helpful and friendly assistant.")
logger.info("AI response generated successfully")
return ChatResponse(response=ai_response)
except HTTPException:
raise
except Exception as e:
logger.error(f"Error processing chat message: {str(e)}")
raise HTTPException(status_code=500, detail="Internal server error")
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=5000, reload=True)
```
**הבנת יישום FastAPI:**
- **ייבוא** FastAPI עבור פונקציונליות של מסגרת אינטרנט מודרנית ו-Pydantic לאימות נתונים
- **יצירת** תיעוד API אוטומטי (זמין ב-`/docs` כשהשרת פועל)
- **הפעלת** CORS middleware כדי לאפשר בקשות frontend ממקורות שונים
- **הגדרת** מודלים של Pydantic לאימות ותיעוד אוטומטי של בקשות/תגובות
- **שימוש** בנקודות קצה async לביצועים טובים יותר עם בקשות מקבילות
- **יישום** קודי סטטוס HTTP מתאימים וטיפול בשגיאות עם HTTPException
- **הוספת** רישום מובנה למעקב ופתרון בעיות
- **מתן** נקודת בדיקת בריאות למעקב אחר מצב השירות
**יתרונות מרכזיים של FastAPI על פני מסגרות מסורתיות:**
- **אימות אוטומטי**: מודלים של Pydantic מבטיחים שלמות נתונים לפני עיבוד
- **תיעוד אינטראקטיבי**: בקר ב-`/docs` עבור תיעוד API שנוצר אוטומטית וניתן לבדיקה
- **בטיחות טיפוס**: רמזי טיפוס של Python מונעים שגיאות בזמן ריצה ומשפרים את איכות הקוד
- **תמיכה ב-async**: טיפול במספר בקשות AI בו-זמנית ללא חסימה
- **ביצועים**: עיבוד בקשות מהיר משמעותית עבור יישומים בזמן אמת
### הבנת CORS: שומר האבטחה של האינטרנט
CORS (Cross-Origin Resource Sharing) הוא כמו שומר אבטחה בבניין שבודק אם מבקרים מורשים להיכנס. בואו נבין למה זה חשוב וכיצד זה משפיע על האפליקציה שלך.
#### מה זה CORS ולמה הוא קיים?
**הבעיה**: דמיין אם כל אתר יכול לבצע בקשות לאתר הבנק שלך בשמך ללא רשותך. זה יהיה סיוט אבטחה! דפדפנים מונעים זאת כברירת מחדל באמצעות "מדיניות מקור זהה".
**מדיניות מקור זהה**: דפדפנים מאפשרים לדפי אינטרנט לבצע בקשות רק לאותו דומיין, פורט ופרוטוקול שממנו נטענו.
**אנלוגיה בעולם האמיתי**: זה כמו אבטחת בניין דירות – רק דיירים (מקור זהה) יכולים לגשת לבניין כברירת מחדל. אם אתה רוצה לתת לחבר (מקור שונה) לבקר, אתה צריך לומר לאבטחה שזה בסדר.
#### CORS בסביבת הפיתוח שלך
במהלך הפיתוח, ה-frontend וה-backend שלך פועלים על פורטים שונים:
- Frontend: `http://localhost:3000` (או file:// אם פותחים HTML ישירות)
- Backend: `http://localhost:5000`
אלה נחשבים "מקורות שונים" למרות שהם על אותו מחשב!
```python
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI(__name__)
CORS(app) # This tells browsers: "It's okay for other origins to make requests to this API"
```
**מה תצורת CORS עושה בפועל:**
- **מוסיפה** כותרות HTTP מיוחדות לתגובות API שאומרות לדפדפנים "בקשה זו ממקור שונה מותרת"
- **מטפלת** בבקשות "preflight" (לפעמים דפדפנים בודקים הרשאות לפני שליחת הבקשה האמיתית)
- **מונעת** את השגיאה המפחידה "נחסם על ידי מדיניות CORS" בקונסולת הדפדפן שלך
#### אבטחת CORS: פיתוח מול ייצור
```python
# 🚨 Development: Allows ALL origins (convenient but insecure)
CORS(app)
# ✅ Production: Only allow your specific frontend domain
CORS(app, origins=["https://yourdomain.com", "https://www.yourdomain.com"])
# 🔒 Advanced: Different origins for different environments
if app.debug: # Development mode
CORS(app, origins=["http://localhost:3000", "http://127.0.0.1:3000"])
else: # Production mode
CORS(app, origins=["https://yourdomain.com"])
```
**למה זה חשוב**: בפיתוח, `CORS(app)` הוא כמו להשאיר את דלת הכניסה שלך לא נעולה – נוח אבל לא בטוח. בייצור, אתה רוצה לציין בדיוק אילו אתרים יכולים לדבר עם ה-API שלך.
#### תרחישי CORS נפוצים ופתרונות
| תרחיש | בעיה | פתרון |
|----------|---------|----------|
| **פיתוח מקומי** | ה-frontend לא יכול להגיע ל-backend | הוסף CORSMiddleware ל-FastAPI |
| **GitHub Pages + Heroku** | ה-frontend המותקן לא יכול להגיע ל-API | הוסף את כתובת ה-URL של GitHub Pages למקורות CORS |
| **דומיין מותאם אישית** | שגיאות CORS בייצור | עדכן את מקורות CORS כך שיתאימו לדומיין שלך |
| **אפליקציה ניידת** | האפליקציה לא יכולה להגיע ל-web API | הוסף את דומיין האפליקציה שלך או השתמש ב-`*` בזהירות |
**טיפ מקצועי**: אתה יכול לבדוק כותרות CORS בכלי המפתחים של הדפדפן שלך תחת לשונית הרשת. חפש כותרות כמו `Access-Control-Allow-Origin` בתגובה.
### טיפול בשגיאות ואימות
שימו לב כיצד ה-API שלנו כולל טיפול נכון בשגיאות:
```python
# Validate that we received a message
if not message:
return jsonify({"error": "Message field is required"}), 400
```
**עקרונות מפתח לאימות:**
- **בודק** שדות נדרשים לפני עיבוד בקשות
- **מחזיר** הודעות שגיאה משמעותיות בפורמט JSON
- **משתמש** בקודי סטטוס HTTP מתאימים (400 עבור בקשות שגויות)
- **מספק** משוב ברור כדי לעזור למפתחי frontend לפתור בעיות
## הגדרת והפעלת ה-backend שלך
עכשיו כשיש לנו את האינטגרציה עם ה-AI ושרת FastAPI מוכן, בואו נתחיל הכל. תהליך ההגדרה כולל התקנת תלות Python, תצורת משתני סביבה והפעלת שרת הפיתוח שלך.
### הגדרת סביבת Python
בואו נגדיר את סביבת הפיתוח של Python שלך. סביבות וירטואליות הן כמו גישה מחולקת לפרויקט – כל פרויקט מקבל את החלל המבודד שלו עם כלים ותלות ספציפיים, מה שמונע קונפליקטים בין פרויקטים שונים.
```bash
# Navigate to your backend directory
cd backend
# Create a virtual environment (like creating a clean room for your project)
python -m venv venv
# Activate it (Linux/Mac)
source ./venv/bin/activate
# On Windows, use:
# venv\Scripts\activate
# Install the good stuff
pip install openai fastapi uvicorn python-dotenv
```
**מה שעשינו עכשיו:**
- **יצרנו** את הבועה הקטנה שלנו ב-Python שבה נוכל להתקין חבילות מבלי להשפיע על שום דבר אחר
- **הפעלנו** אותה כך שהטרמינל שלנו יודע להשתמש בסביבה הספציפית הזו
- **התקנו** את הדברים החיוניים: OpenAI לקסם AI, FastAPI ל-web API שלנו, Uvicorn כדי להפעיל אותו בפועל, ו-python-dotenv לניהול סודות בצורה מאובטחת
**הסבר תלות מרכזיות:**
- **FastAPI**: מסגרת אינטרנט מודרנית ומהירה עם תיעוד API אוטומטי
- **Uvicorn**: שרת ASGI מהיר שמפעיל אפליקציות FastAPI
- **OpenAI**: ספרייה רשמית לאינטגרציה עם מודלים של GitHub ו-OpenAI API
- **python-dotenv**: טעינת משתני סביבה מאובטחת מקבצי .env
### תצורת סביבה: שמירה על סודות
לפני שנפעיל את ה-API שלנו, אנחנו צריכים לדבר על אחד השיעורים החשובים ביותר בפיתוח אינטרנט: איך לשמור על הסודות שלך באמת סודיים. משתני סביבה הם כמו כספת מאובטחת שרק האפליקציה שלך יכולה לגשת אליה.
#### מה הם משתני סביבה?
**חשוב על משתני סביבה כמו כספת בטוחה** – אתה שם את הדברים היקרים שלך שם, ורק אתה (והאפליקציה שלך) מחזיקים את המפתח כדי להוציא אותם. במקום לכתוב מידע רגיש ישירות בקוד שלך (שכל אחד יכול לראות), אתה שומר אותו בצורה בטוחה בסביבה.
**הנה ההבדל:**
- **הדרך הלא נכונה**: לכתוב את הסיסמה שלך על פתק ולהדביק אותו על המסך שלך
- **הדרך הנכונה**: לשמור את הסיסמה שלך במנהל סיסמאות מאובטח שרק אתה יכול לגשת אליו
#### למה משתני סביבה חשובים
```python
# 🚨 NEVER DO THIS - API key visible to everyone
client = OpenAI(
api_key="ghp_1234567890abcdef...", # Anyone can steal this!
base_url="https://models.github.ai/inference"
)
# ✅ DO THIS - API key stored securely
client = OpenAI(
api_key=os.environ["GITHUB_TOKEN"], # Only your app can access this
base_url="https://models.github.ai/inference"
)
```
**מה קורה כשאתה מקודד סודות:**
1. **חשיפה בגרסת שליטה**: כל מי שיש לו גישה למאגר Git שלך רואה את מפתח ה-API שלך
2. **מאגר ציבורי**: אם אתה דוחף ל-GitHub, המפתח שלך גלוי לכל האינטרנט
3. **שיתוף צוותי**: מפתחים אחרים שעובדים על הפרויקט שלך מקבלים גישה למפתח ה-API האישי שלך
4. **פריצות אבטחה**: אם מישהו גונב את מפתח ה-API שלך, הוא יכול להשתמש בקרדיטים של ה-AI שלך
#### יצירת קובץ סביבה
צור קובץ `.env` בספריית ה-backend שלך. קובץ זה מאחסן את הסודות שלך באופן מקומי:
```bash
# .env file - This should NEVER be committed to Git
GITHUB_TOKEN=your_github_personal_access_token_here
FASTAPI_DEBUG=True
ENVIRONMENT=development
```
**הבנת קובץ .env:**
- **סוד אחד בכל שורה** בפורמט `KEY=value`
- **ללא רווחים** סביב סימן השווה
- **ללא מרכאות** סביב ערכים (בדרך כלל)
- **הערות** מתחילות ב-`#`
#### יצירת אסימון גישה אישי ל-GitHub
האסימון שלך ל-GitHub הוא כמו סיסמה מיוחדת שנותנת לאפליקציה שלך הרשאה להשתמש בשירותי ה-AI של GitHub:
**שלבים ליצירת אסימון:**
1. **עבור להגדרות GitHub** → הגדרות מפתחים → אסימוני גישה אישיים → אסימונים (קלאסיים)
2. **לחץ על "צור אסימון חדש (קלאסי)"**
3. **הגדר תאריך תפוגה** (30 ימים לבדיקה, יותר לייצור)
4. **בחר תחומים**: סמן "repo" וכל הרשאות אחרות שאתה צריך
5. **צור אסימון** והעתק אותו מיד (לא תוכל לראות אותו שוב!)
6. **הדבק אותו בקובץ .env שלך**
```bash
# Example of what your token looks like (this is fake!)
GITHUB_TOKEN=ghp_1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R
```
#### טעינת משתני סביבה ב-Python
```python
import os
from dotenv import load_dotenv
# Load environment variables from .env file
load_dotenv()
# Now you can access them securely
api_key = os.environ.get("GITHUB_TOKEN")
if not api_key:
raise ValueError("GITHUB_TOKEN not found in environment variables!")
client = OpenAI(
api_key=api_key,
base_url="https://models.github.ai/inference"
)
```
**מה הקוד הזה עושה:**
- **טוען** את קובץ ה-.env שלך והופך משתנים לזמינים ל-Python
- **בודק** אם האסימון הנדרש קיים (טיפול טוב בשגיאות!)
- **מעלה** שגיאה ברורה אם האסימון חסר
- **משתמש** באסימון בצורה מאובטחת מבלי לחשוף אותו בקוד
#### אבטחת Git: קובץ .gitignore
קובץ ה-.gitignore שלך אומר ל-Git אילו קבצים לא לעקוב או להעלות:
```bash
# .gitignore - Add these lines
.env
*.env
.env.local
.env.production
__pycache__/
venv/
.vscode/
```
**למה זה קריטי**: ברגע שאתה מוסיף את .env ל-.gitignore, Git יתעלם מקובץ הסביבה שלך, מה שמונע ממך להעלות בטעות את הסודות שלך ל-GitHub.
#### סביבות שונות, סודות שונים
אפליקציות מקצועיות משתמשות במפתחות API שונים עבור סביבות שונות:
```bash
# .env.development
GITHUB_TOKEN=your_development_token
DEBUG=True
# .env.production
GITHUB_TOKEN=your_production_token
DEBUG=False
```
**למה זה חשוב**: אתה לא רוצה שהניסויים שלך בפיתוח ישפיעו על מכסת השימוש ב-AI בייצור, ואתה רוצה ר
עכשיו מגיע הרגע המרגש – הפעלת שרת הפיתוח של FastAPI וצפייה באינטגרציה של הבינה המלאכותית שלכם מתעוררת לחיים! FastAPI משתמש ב-Uvicorn, שרת ASGI מהיר במיוחד שתוכנן במיוחד עבור יישומי Python אסינכרוניים.
#### הבנת תהליך הפעלת שרת FastAPI
```bash
# Method 1: Direct Python execution (includes auto-reload)
python api.py
# Method 2: Using Uvicorn directly (more control)
uvicorn api:app --host 0.0.0.0 --port 5000 --reload
```
כשאתם מריצים את הפקודה הזו, הנה מה שקורה מאחורי הקלעים:
**1. Python טוען את יישום FastAPI שלכם**:
- מייבא את כל הספריות הנדרשות (FastAPI, Pydantic, OpenAI וכו')
- טוען משתני סביבה מקובץ `.env` שלכם
- יוצר מופע של יישום FastAPI עם תיעוד אוטומטי
**2. Uvicorn מגדיר את שרת ASGI**:
- מתחבר לפורט 5000 עם יכולות טיפול בבקשות אסינכרוניות
- מגדיר ניתוב בקשות עם ולידציה אוטומטית
- מאפשר טעינה מחדש בזמן פיתוח (מחדש את השרת עם שינויי קבצים)
- יוצר תיעוד API אינטראקטיבי
**3. השרת מתחיל להאזין**:
- הטרמינל שלכם מציג: `INFO: Uvicorn running on http://0.0.0.0:5000`
- השרת יכול לטפל בבקשות בינה מלאכותית מרובות בו-זמנית
- ה-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 שלכם פועל כראוי
**שיטה 3: בדיקה דרך שורת הפקודה (מתקדמת)**
```bash
# Test with curl (if available)
curl -X POST http://localhost:5000/hello \
-H "Content-Type: application/json" \
-d '{"message": "Hello AI!"}'
# Expected response:
# {"response": "Hello! I'm your AI assistant. How can I help you today?"}
```
**שיטה 4: סקריפט בדיקה ב-Python**
```python
# test_api.py - Create this file to test your API
import requests
import json
# Test the API endpoint
url = "http://localhost:5000/hello"
data = {"message": "Tell me a joke about programming"}
response = requests.post(url, json=data)
if response.status_code == 200:
result = response.json()
print("AI Response:", result['response'])
else:
print("Error:", response.status_code, response.text)
```
#### פתרון בעיות נפוצות בהפעלה
| הודעת שגיאה | מה זה אומר | איך לתקן |
|-------------|------------|----------|
| `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` | אימות שירות הבינה המלאכותית נכשל | ודאו שהטוקן שלכם נכון ויש לו הרשאות מתאימות |
#### שיטות עבודה מומלצות לפיתוח
**טעינה מחדש אוטומטית**: FastAPI עם Uvicorn מספק טעינה מחדש אוטומטית כשאתם שומרים שינויים בקבצי Python שלכם. זה אומר שאתם יכולים לשנות את הקוד ולבדוק מיד בלי להפעיל מחדש ידנית.
```python
# Enable hot reloading explicitly
if __name__ == "__main__":
app.run(host="0.0.0.0", port=5000, debug=True) # debug=True enables hot reload
```
**לוגים לפיתוח**: הוסיפו לוגים כדי להבין מה קורה:
```python
import logging
# Set up logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
@app.route("/hello", methods=["POST"])
def hello():
data = request.get_json()
message = data.get("message", "")
logger.info(f"Received message: {message}")
if not message:
logger.warning("Empty message received")
return jsonify({"error": "Message field is required"}), 400
try:
response = call_llm(message, "You are a helpful and friendly assistant.")
logger.info(f"AI response generated successfully")
return jsonify({"response": response})
except Exception as e:
logger.error(f"AI API error: {str(e)}")
return jsonify({"error": "AI service temporarily unavailable"}), 500
```
**למה לוגים עוזרים**: במהלך הפיתוח, אתם יכולים לראות בדיוק אילו בקשות נכנסות, מה הבינה המלאכותית מגיבה, ואיפה מתרחשות שגיאות. זה הופך את תהליך הדיבוג למהיר יותר.
### הגדרה עבור GitHub Codespaces: פיתוח בענן בצורה קלה
GitHub Codespaces הוא כמו מחשב פיתוח חזק בענן שאתם יכולים לגשת אליו מכל דפדפן. אם אתם עובדים ב-Codespaces, יש כמה צעדים נוספים כדי להפוך את ה-backend שלכם לנגיש ל-frontend.
#### הבנת רשתות ב-Codespaces
בסביבת פיתוח מקומית, הכול פועל על אותו מחשב:
- Backend: `http://localhost:5000`
- Frontend: `http://localhost:3000` (או file://)
ב-Codespaces, סביבת הפיתוח שלכם פועלת על השרתים של GitHub, כך ש-"localhost" מקבל משמעות שונה. GitHub יוצר אוטומטית כתובות URL ציבוריות לשירותים שלכם, אבל אתם צריכים להגדיר אותם כראוי.
#### הגדרת Codespaces שלב אחר שלב
**1. הפעלת שרת ה-backend שלכם**:
```bash
cd backend
python api.py
```
תראו את הודעת ההפעלה המוכרת של FastAPI/Uvicorn, אבל שימו לב שהיא פועלת בתוך סביבת Codespace.
**2. הגדרת נראות הפורט**:
- חפשו את לשונית "Ports" בפאנל התחתון של VS Code
- מצאו את פורט 5000 ברשימה
- לחצו לחיצה ימנית על פורט 5000
- בחרו "Port Visibility" → "Public"
**למה להפוך אותו לציבורי?** כברירת מחדל, פורטים ב-Codespace הם פרטיים (נגישים רק לכם). הפיכתם לציבוריים מאפשרת ל-frontend (שפועל בדפדפן) לתקשר עם ה-backend.
**3. קבלת כתובת URL ציבורית**:
לאחר שהפכתם את הפורט לציבורי, תראו כתובת URL כמו:
```
https://your-codespace-name-5000.app.github.dev
```
**4. עדכון הגדרות ה-frontend שלכם**:
```javascript
// In your frontend app.js, update the BASE_URL:
this.BASE_URL = "https://your-codespace-name-5000.app.github.dev";
```
#### הבנת כתובות URL של Codespace
כתובות URL של Codespace עוקבות אחר תבנית צפויה:
```
https://[codespace-name]-[port].app.github.dev
```
**פירוק זה:**
- `codespace-name`: מזהה ייחודי ל-Codespace שלכם (בדרך כלל כולל את שם המשתמש שלכם)
- `port`: מספר הפורט שבו השירות שלכם פועל (5000 עבור אפליקציית FastAPI שלנו)
- `app.github.dev`: הדומיין של GitHub עבור אפליקציות Codespace
#### בדיקת הגדרת Codespace שלכם
**1. בדקו את ה-backend ישירות**:
פתחו את כתובת ה-URL הציבורית שלכם בלשונית דפדפן חדשה. אתם אמורים לראות:
```
Welcome to the AI Chat API. Send POST requests to /hello with JSON payload containing 'message' field.
```
**2. בדקו עם כלי פיתוח של הדפדפן**:
```javascript
// Open browser console and test your API
fetch('https://your-codespace-name-5000.app.github.dev/hello', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({message: 'Hello from Codespaces!'})
})
.then(response => response.json())
.then(data => console.log(data));
```
#### Codespaces לעומת פיתוח מקומי
| היבט | פיתוח מקומי | GitHub Codespaces |
|------|------------|-------------------|
| **זמן הגדרה** | ארוך יותר (התקנת Python, תלות) | מיידי (סביבה מוגדרת מראש) |
| **גישה לכתובת URL** | `http://localhost:5000` | `https://xyz-5000.app.github.dev` |
| **הגדרת פורט** | אוטומטית | ידנית (הפיכת פורטים לציבוריים) |
| **התמדה של קבצים** | מחשב מקומי | מאגר GitHub |
| **שיתוף פעולה** | קשה לשתף סביבה | קל לשתף קישור ל-Codespace |
| **תלות באינטרנט** | רק עבור קריאות API של בינה מלאכותית | נדרש עבור הכול |
#### טיפים לפיתוח ב-Codespace
**משתני סביבה ב-Codespaces**:
קובץ `.env` שלכם פועל באותו אופן ב-Codespaces, אבל אתם יכולים גם להגדיר משתני סביבה ישירות ב-Codespace:
```bash
# Set environment variable for the current session
export GITHUB_TOKEN="your_token_here"
# Or add to your .bashrc for persistence
echo 'export GITHUB_TOKEN="your_token_here"' >> ~/.bashrc
```
**ניהול פורטים**:
- Codespaces מזהה אוטומטית כאשר האפליקציה שלכם מתחילה להאזין לפורט
- אתם יכולים להעביר מספר פורטים בו-זמנית (שימושי אם תוסיפו מסד נתונים מאוחר יותר)
- פורטים נשארים נגישים כל עוד ה-Codespace שלכם פועל
**תהליך עבודה בפיתוח**:
1. בצעו שינויים בקוד ב-VS Code
2. FastAPI טוען מחדש אוטומטית (בזכות מצב הטעינה מחדש של Uvicorn)
3. בדקו שינויים מיד דרך כתובת ה-URL הציבורית
4. בצעו commit ו-push כשאתם מוכנים
> 💡 **טיפ מקצועי**: שמרו את כתובת ה-URL של ה-backend שלכם ב-Codespace במהלך הפיתוח. מכיוון ששמות ה-Codespace יציבים, הכתובת לא תשתנה כל עוד אתם משתמשים באותו Codespace.
## יצירת ממשק הצ'אט של ה-Frontend: המקום שבו אנשים פוגשים את הבינה המלאכותית
עכשיו נבנה את ממשק המשתמש – החלק שקובע איך אנשים מתקשרים עם העוזר האישי שלכם. כמו עיצוב ממשק האייפון המקורי, אנחנו מתמקדים בלגרום לטכנולוגיה מורכבת להרגיש אינטואיטיבית וטבעית לשימוש.
### הבנת ארכיטקטורת ה-Frontend המודרנית
ממשק הצ'אט שלנו יהיה מה שנקרא "אפליקציית עמוד יחיד" או SPA. במקום הגישה הישנה שבה כל לחיצה טוענת עמוד חדש, האפליקציה שלנו מתעדכנת בצורה חלקה ומיידית:
**אתרים ישנים**: כמו לקרוא ספר פיזי – מדפדפים לעמודים חדשים לחלוטין
**אפליקציית הצ'אט שלנו**: כמו להשתמש בטלפון שלכם – הכול זורם ומתעדכן בצורה חלקה
```mermaid
graph TD
A[User Types Message] --> B[JavaScript Captures Input]
B --> C[Validate & Format Data]
C --> D[Send to Backend API]
D --> E[Display Loading State]
E --> F[Receive AI Response]
F --> G[Update Chat Interface]
G --> H[Ready for Next Message]
```
```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 : manipulates
ChatApp --> FastAPI : sends requests
```
### שלושת עמודי התווך של פיתוח Frontend
כל אפליקציית Frontend – מאתרים פשוטים ועד אפליקציות מורכבות כמו Discord או Slack – בנויה על שלוש טכנולוגיות ליבה. חשבו עליהן כבסיס לכל מה שאתם רואים ומתקשרים איתו באינטרנט:
**HTML (מבנה)**: זהו הבסיס שלכם
- קובע אילו אלמנטים קיימים (כפתורים, אזורי טקסט, מכולות)
- נותן משמעות לתוכן (זה כותרת, זה טופס וכו')
- יוצר את המבנה הבסיסי שעליו הכול נבנה
**CSS (הצגה)**: זהו המעצב הפנימי שלכם
- גורם להכול להיראות יפה (צבעים, פונטים, פריסות)
- מטפל בגדלי מסך שונים (טלפון מול מחשב נייד מול טאבלט)
- יוצר אנימציות חלקות ומשוב חזותי
**JavaScript (התנהגות)**: זהו המוח שלכם
- מגיב למה שהמשתמשים עושים (לחיצות, הקלדה, גלילה)
- מתקשר עם ה-backend ומעדכן את העמוד
- הופך הכול לאינטראקטיבי ודינמי
**חשבו על זה כמו עיצוב אדריכלי:**
- **HTML**: התוכנית המבנית (הגדרת חללים ויחסים)
- **CSS**: העיצוב האסתטי והסביבתי (סגנון חזותי וחוויית משתמש)
- **JavaScript**: המערכות המכאניות (פונקציונליות ואינטראקטיביות)
### למה ארכיטקטורת JavaScript מודרנית חשובה
אפליקציית הצ'אט שלנו תשתמש בתבניות JavaScript מודרניות שתראו באפליקציות מקצועיות. הבנת מושגים אלו תעזור לכם ככל שתתפתחו כמפתחים:
**ארכיטקטורה מבוססת מחלקות**: נארגן את הקוד שלנו למחלקות, שזה כמו יצירת תוכניות עבור אובייקטים
**Async/Await**: דרך מודרנית לטפל בפעולות שלוקחות זמן (כמו קריאות API)
**תכנות מונחה אירועים**: האפליקציה שלנו מגיבה לפעולות משתמשים (לחיצות, הקשות) במקום לרוץ בלולאה
**מניפולציה של DOM**: עדכון דינמי של תוכן העמוד בהתאם לאינטראקציות משתמשים ותגובות API
### הגדרת מבנה הפרויקט
צרו תיקיית Frontend עם מבנה מאורגן זה:
```text
frontend/
├── index.html # Main HTML structure
├── app.js # JavaScript functionality
└── styles.css # Visual styling
```
**הבנת הארכיטקטורה:**
- **מפריד** בין מבנה (HTML), התנהגות (JavaScript), והצגה (CSS)
- **שומר** על מבנה קבצים פשוט שקל לנווט ולשנות
- **עוקב** אחר שיטות עבודה מומלצות לפיתוח אתרים עבור ארגון ותחזוקה
### בניית בסיס HTML: מבנה סמנטי לנגישות
נתחיל עם מבנה ה-HTML. פיתוח אתרים מודרני מדגיש "HTML סמנטי" – שימוש באלמנטים HTML שמתארים בבירור את מטרתם, לא רק את המראה שלהם. זה הופך את האפליקציה שלכם לנגישה לקוראי מסך, מנועי חיפוש וכלים אחרים.
**למה HTML סמנטי חשוב**: דמיינו שאתם מתארים את אפליקציית הצ'אט שלכם למישהו בטלפון. הייתם אומרים "יש כותרת עם הכותרת, אזור מרכזי שבו מופיעות שיחות, וטופס בתחתית להקלדת הודעות." HTML סמנטי משתמש באלמנטים שמתאימים לתיאור הטבעי הזה.
צרו `index.html` עם סימון מובנה ומחושב זה:
```html
AI Chat Assistant
AI Chat Assistant
Ask me anything!
```
**הבנת כל אלמנט HTML ומטרתו:**
#### מבנה המסמך
- **``**: אומר לדפדפן שזה HTML5 מודרני
- **``**: מציין את שפת העמוד עבור קוראי מסך וכלי תרגום
- **``**: מבטיח קידוד תווים נכון לטקסט בינלאומי
- **``**: הופך את העמוד לרספונסיבי לנייד על ידי שליטה בזום ובסקייל
#### אלמנטים סמנטיים
- **``**: מזהה בבירור את החלק העליון עם כותרת ותיאור
- **``**: מציין את אזור התוכן הראשי (איפה שהשיחות מתרחשות)
- **`