# בניית עוזר צ'אט עם AI
זוכרים את "מסע בין כוכבים" כשהצוות היה משוחח עם מחשב הספינה, שואל שאלות מורכבות ומקבל תשובות מחושבות? מה שנראה כמו מדע בדיוני טהור בשנות ה-60 הוא עכשיו משהו שאתם יכולים לבנות באמצעות טכנולוגיות אינטרנט שאתם כבר מכירים.
בשיעור הזה, ניצור עוזר צ'אט מבוסס AI באמצעות HTML, CSS, JavaScript וקצת אינטגרציה בצד השרת. תגלו איך הכישורים שאתם כבר לומדים יכולים להתחבר לשירותי AI חזקים שמבינים הקשר ומייצרים תשובות משמעותיות.
חשבו על AI כמו גישה לספרייה עצומה שיכולה לא רק למצוא מידע אלא גם לסנתז אותו לתשובות קוהרנטיות המותאמות לשאלות שלכם. במקום לחפש בין אלפי עמודים, אתם מקבלים תשובות ישירות וממוקדות.
האינטגרציה מתבצעת באמצעות טכנולוגיות אינטרנט מוכרות שעובדות יחד. HTML יוצר את ממשק הצ'אט, CSS מטפל בעיצוב החזותי, JavaScript מנהל את האינטראקציות עם המשתמש, ו-API בצד השרת מחבר הכל לשירותי AI. זה דומה לאיך חלקים שונים בתזמורת עובדים יחד כדי ליצור סימפוניה.
בעצם אנחנו בונים גשר בין תקשורת אנושית טבעית לעיבוד מכונה. תלמדו גם את היישום הטכני של אינטגרציית שירותי AI וגם את דפוסי העיצוב שגורמים לאינטראקציות להרגיש אינטואיטיביות.
בסוף השיעור הזה, אינטגרציית AI תרגיש פחות כמו תהליך מסתורי ויותר כמו עוד API שאפשר לעבוד איתו. תבינו את הדפוסים הבסיסיים שמניעים אפליקציות כמו ChatGPT ו-Claude, תוך שימוש באותם עקרונות פיתוח אינטרנט שלמדתם.
כך ייראה הפרויקט המוגמר שלכם:
## להבין את ה-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?
אנחנו משתמשים במודלים של GitHub מסיבה די פרקטית – זה נותן לנו גישה ל-AI ברמה ארגונית מבלי שנצטרך להקים תשתית AI משלנו (שזה, תאמינו לי, לא משהו שתרצו לעשות כרגע!). חשבו על זה כמו להשתמש ב-API של מזג אוויר במקום לנסות לחזות את מזג האוויר בעצמכם על ידי הקמת תחנות מזג אוויר בכל מקום.
זה בעצם "AI-as-a-Service", והחלק הכי טוב? זה חינם להתחיל, כך שתוכלו להתנסות בלי לדאוג לחשבון גדול.
```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 לאינטגרציה בצד השרת, שמספקים גישה ליכולות AI ברמה מקצועית דרך ממשק ידידותי למפתחים. [GitHub Models Playground](https://github.com/marketplace/models/azure-openai/gpt-4o-mini/playground) משמש כסביבת בדיקה שבה תוכלו להתנסות במודלים שונים של AI ולהבין את יכולותיהם לפני שתיישמו אותם בקוד.
**הנה מה שהופך את ה-Playground לכל כך שימושי:**
- **התנסות** במודלים שונים כמו 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"],
)
```python
response = client.chat.completions.create(
messages=[
{
"role": "system",
"content": "",
},
{
"role": "user",
"content": "What is the capital of France?",
}
],
model="openai/gpt-4o-mini",
temperature=1,
max_tokens=4096,
top_p=1
)
print(response.choices[0].message.content)
```
**מה קורה בקוד הזה:**
- **אנחנו מייבאים** את הכלים שאנחנו צריכים: `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
}
```
**להבין למה הפרמטרים האלה חשובים**: אפליקציות שונות צריכות סוגים שונים של תשובות. בוט שירות לקוחות צריך להיות עקבי ועובדתי (טמפרטורה נמוכה), בעוד שעוזר לכתיבה יצירתית צריך להיות דמיוני ומגוון (טמפרטורה גבוהה). הבנת הפרמטרים האלה נותנת לכם שליטה על האישיות וסגנון התשובה של ה-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 נכונים לתיעוד קוד טוב יותר
- **מחזירה** רק את תוכן התשובה, מה שמקל על השימוש ב-API שלנו
- **שומרת** על אותם פרמטרי מודל להתנהגות 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 מודרניות להרגיש מותאמות ושימושיות.
## בניית ה-API עם FastAPI: מרכז תקשורת AI בעל ביצועים גבוהים
עכשיו נבנה את צד השרת שמחבר את צד הלקוח לשירותי AI. נשתמש ב-FastAPI, מסגרת Python מודרנית שמצטיינת בבניית APIs לאפליקציות AI.
FastAPI מציעה כמה יתרונות לפרויקט מסוג זה: תמיכה מובנית ב-async לטיפול בבקשות מקבילות, יצירת תיעוד API אוטומטי וביצועים מצוינים. שרת FastAPI שלכם ישמש כמתווך שמקבל בקשות מצד הלקוח, מתקשר עם שירותי AI ומחזיר תשובות מעוצבות.
### למה FastAPI לאפליקציות AI?
אולי אתם שואלים: "לא יכולתי פשוט לקרוא ל-AI ישירות מ-JavaScript בצד הלקוח?" או "למה FastAPI במקום Flask או Django?" שאלות מצוינות!
**הנה למה FastAPI מושלם למה שאנחנו בונים:**
- **אסינכרוני כברירת מחדל**: יכול להתמודד עם מספר בקשות AI בו-זמנית בלי להיתקע
- **תיעוד אוטומטי**: בקרו ב-`/docs` וקבלו דף תיעוד API אינטראקטיבי ויפה בחינם
- **אימות מובנה**: מזהה שגיאות לפני שהן גורמות לבעיות
- **מהיר במיוחד**: אחד ממסגרות הפיתוח המהירות ביותר בפייתון
- **פייתון מודרני**: משתמש בכל התכונות החדשות והמתקדמות של פייתון
**והנה למה אנחנו בכלל צריכים צד שרת:**
**אבטחה**: מפתח ה-API של ה-AI שלכם הוא כמו סיסמה – אם תכניסו אותו ל-JavaScript בצד הלקוח, כל מי שיצפה בקוד המקור של האתר שלכם יוכל לגנוב אותו ולהשתמש בקרדיטים של ה-AI שלכם. צד השרת שומר על האישורים הרגישים בצורה מאובטחת.
**הגבלת קצב ושליטה**: צד השרת מאפשר לכם לשלוט בתדירות הבקשות של המשתמשים, ליישם אימות משתמשים ולהוסיף רישום למעקב אחר השימוש.
**עיבוד נתונים**: ייתכן שתרצו לשמור שיחות, לסנן תוכן לא מתאים או לשלב בין שירותי AI שונים. צד השרת הוא המקום שבו הלוגיקה הזו מתבצעת.
**הארכיטקטורה דומה למודל לקוח-שרת:**
- **צד לקוח**: שכבת ממשק משתמש לאינטראקציה
- **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. **עיבוד בצד הלקוח**: JavaScript לוכד את הקלט ומעצב אותו כ-JSON
3. **אימות API**: FastAPI מאמת את הבקשה באופן אוטומטי באמצעות מודלים של Pydantic
4. **שילוב AI**: צד השרת מוסיף הקשר (הנחיית מערכת) וקורא לשירות ה-AI
5. **טיפול בתגובה**: ה-API מקבל את תגובת ה-AI ויכול לשנות אותה אם צריך
6. **תצוגה בצד הלקוח**: 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?"}
```
### יצירת אפליקציית 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 כדי לאפשר בקשות צד לקוח ממקורות שונים
- **הגדרת** מודלים של Pydantic לאימות ותיעוד אוטומטי של בקשות/תגובות
- **שימוש** בנקודות קצה אסינכרוניות לביצועים טובים יותר עם בקשות מקבילות
- **יישום** קודי סטטוס HTTP נכונים וטיפול בשגיאות עם HTTPException
- **הוספת** רישום מובנה למעקב ופתרון בעיות
- **סיפוק** נקודת בדיקת בריאות למעקב אחר מצב השירות
**יתרונות מרכזיים של FastAPI על פני מסגרות מסורתיות:**
- **אימות אוטומטי**: מודלים של Pydantic מבטיחים שלמות נתונים לפני עיבוד
- **תיעוד אינטראקטיבי**: בקרו ב-`/docs` לתיעוד API אוטומטי שניתן לבדיקה
- **בטיחות טיפוסים**: רמזי טיפוס בפייתון מונעים שגיאות בזמן ריצה ומשפרים את איכות הקוד
- **תמיכה באסינכרוניות**: טיפול במספר בקשות AI בו-זמנית ללא חסימה
- **ביצועים**: עיבוד בקשות מהיר משמעותית עבור אפליקציות בזמן אמת
### הבנת CORS: שומר האבטחה של האינטרנט
CORS (שיתוף משאבים בין-מקוריים) הוא כמו שומר אבטחה בבניין שבודק אם מבקרים מורשים להיכנס. בואו נבין למה זה חשוב ואיך זה משפיע על האפליקציה שלכם.
#### מה זה CORS ולמה הוא קיים?
**הבעיה**: דמיינו שכל אתר יכול לבצע בקשות לאתר הבנק שלכם בשמכם ללא רשותכם. זה יהיה סיוט אבטחה! דפדפנים מונעים זאת כברירת מחדל באמצעות "מדיניות מקור זהה".
**מדיניות מקור זהה**: דפדפנים מאפשרים לדפי אינטרנט לבצע בקשות רק לדומיין, פורט ופרוטוקול זהים לאלה שמהם נטענו.
**אנלוגיה מהחיים האמיתיים**: זה כמו אבטחת בניין דירות – רק דיירים (מקור זהה) יכולים לגשת לבניין כברירת מחדל. אם אתם רוצים לתת לחבר (מקור שונה) לבקר, עליכם להודיע לשומר שזה בסדר.
#### CORS בסביבת הפיתוח שלכם
במהלך הפיתוח, צד הלקוח וצד השרת פועלים על פורטים שונים:
- צד לקוח: `http://localhost:3000` (או file:// אם פותחים HTML ישירות)
- צד שרת: `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 שאומרות לדפדפנים "בקשה בין-מקורית זו מותרת"
- **מטפלת** בבקשות "בדיקה מוקדמת" (דפדפנים לפעמים בודקים הרשאות לפני שליחת הבקשה בפועל)
- **מונעת** את השגיאה המפחידה "נחסם על ידי מדיניות 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 נפוצים ופתרונות
| תרחיש | בעיה | פתרון |
|----------|---------|----------|
| **פיתוח מקומי** | צד לקוח לא יכול להגיע לצד שרת | הוסיפו CORSMiddleware ל-FastAPI |
| **GitHub Pages + Heroku** | צד לקוח שהופעל לא יכול להגיע ל-API | הוסיפו את כתובת ה-URL של GitHub Pages ל-CORS origins |
| **דומיין מותאם אישית** | שגיאות CORS בייצור | עדכנו את CORS origins להתאים לדומיין שלכם |
| **אפליקציה ניידת** | אפליקציה לא יכולה להגיע ל-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 עבור בקשות שגויות)
- **סיפוק** משוב ברור כדי לעזור למפתחים בצד הלקוח לפתור בעיות
## הגדרת והפעלת צד השרת שלכם
עכשיו כשיש לנו את שילוב ה-AI ואת שרת FastAPI מוכן, בואו נתחיל הכל. תהליך ההגדרה כולל התקנת תלות פייתון, הגדרת משתני סביבה והפעלת שרת הפיתוח שלכם.
### הגדרת סביבת פייתון
בואו נגדיר את סביבת הפיתוח של פייתון שלכם. סביבות וירטואליות הן כמו גישה מחולקת לפרויקט – כל פרויקט מקבל את המרחב המבודד שלו עם כלים ותלות ספציפיים, מה שמונע קונפליקטים בין פרויקטים שונים.
```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
```
**מה שעשינו עכשיו:**
- **יצרנו** בועה קטנה משלנו בפייתון שבה נוכל להתקין חבילות מבלי להשפיע על שום דבר אחר
- **הפעלנו** אותה כך שהטרמינל שלנו ידע להשתמש בסביבה הספציפית הזו
- **התקנו** את הדברים החיוניים: OpenAI לקסם ה-AI, FastAPI ל-API האינטרנטי שלנו, Uvicorn כדי להפעיל אותו בפועל, ו-python-dotenv לניהול סודות בצורה מאובטחת
**הסבר תלות מרכזיות:**
- **FastAPI**: מסגרת אינטרנט מודרנית ומהירה עם תיעוד API אוטומטי
- **Uvicorn**: שרת ASGI מהיר במיוחד שמפעיל אפליקציות FastAPI
- **OpenAI**: ספרייה רשמית לשירותי GitHub Models ושילוב API של OpenAI
- **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 שלכם, הוא יכול להשתמש בקרדיטים שלכם
#### הגדרת קובץ הסביבה שלכם
צרו קובץ `.env` בתיקיית צד השרת שלכם. קובץ זה מאחסן את הסודות שלכם באופן מקומי:
```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
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 שלכם והופך משתנים לזמינים בפייתון
- **בודק** אם האסימון הנדרש קיים (טיפול טוב בשגיאות!)
- **מעלה** שגיאה ברורה אם האסימון חסר
- **משתמש** באסימון בצורה מאובטחת מבלי לחשוף אותו בקוד
#### אבטחת 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 שלכם וצפייה בשילוב ה-AI שלכם מתעורר לחיים! FastAPI משתמש ב-Uvicorn, שרת ASGI מהיר במיוחד שמיועד במיוחד לאפליקציות פייתון אסינכרוניות.
#### הבנת תהליך הפעלת שרת 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. פייתון טוען את אפליקציית FastAPI שלכם**:
- מייבא את כל הספריות הנדרשות (FastAPI, Pydantic, OpenAI וכו')
- טוען משתני סביבה מקובץ ה-.env שלכם
- יוצר את מופע אפליקציית FastAPI עם תיעוד אוטומטי
**2. Uvicorn מגדיר את שרת ASGI**:
- מתחבר לפורט 5000 עם יכולות טיפול בבקשות אסינכרוניות
- מגדיר ניתוב בקשות עם אימות אוטומטי
- מאפשר טעינה מחדש בזמן פיתוח (מחדש את השרת עם שינויי קבצים)
- יוצר תיעוד API אינטראקטיבי
**3. השרת מתחיל להאזין**:
- הטרמינל שלכם מציג: `INFO: Uvicorn running on http://0.0.0.0:5000`
- השרת יכול לטפל במספר בקשות AI בו-זמנית
- ה-API שלכם מוכן עם תיעוד אוטומטי ב-`http://localhost:5000/docs`
#### מה אתם צריכים לראות כשהכל עובד
```bash
$ python api.py
INFO: Will watch for changes in these directories: ['/your/project/path']
INFO: Uvicorn running on http://0.0.0.0:5000 (Press CTRL+C to quit)
INFO: Started reloader process [12345] using WatchFiles
INFO: Started server process [12346]
INFO: Waiting for application startup.
INFO: Application startup complete.
```
**הבנת הפלט של FastAPI:**
- **יעקוב אחר שינויים**: טעינה מחדש אוטומטית מופעלת לפיתוח
- **Uvicorn פועל**: שרת ASGI בעל ביצועים גבוהים פעיל
- **תהליך טעינה מחדש התחיל**: צופה קבצים לטעינה מחדש אוטומטית
- **הפעלת אפליקציה הושלמה**: אפליקציית FastAPI הופעלה בהצלחה
- **תיעוד אינטראקטיבי זמין**: בקרו ב-`/docs` לתיעוד API אוטומטי
#### בדיקת FastAPI שלכם: גישות חזקות רבות
FastAPI מספק מספר דרכים נוחות לבדוק את ה-API שלכם, כולל תיעוד אינטראקטיבי אוטומטי:
**שיטה 1: תיעוד API אינטראקטיבי (מומלץ)**
1. פתחו את הדפדפן שלכם ועברו ל-`http://localhost:5000/docs`
2. תראו את ממשק Swagger UI עם כל נקודות הקצה שלכם מתועדות
3. לחצו על `/hello` → "נסה את זה" → הכניסו הודעת בדיקה → "בצע"
4. ראו את התגובה ישירות בדפדפן עם עיצוב נכון
**שיטה 2:
```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` | אימות שירות AI נכשל | ודא שהטוקן של GitHub נכון ויש לו הרשאות מתאימות |
#### שיטות עבודה מומלצות לפיתוח
**טעינה מחדש אוטומטית**: 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
```
**למה רישום לוגים עוזר**: במהלך הפיתוח, אתה יכול לראות בדיוק אילו בקשות נכנסות, מה התשובות של ה-AI, ואיפה מתרחשות שגיאות. זה הופך את תהליך הדיבוג למהיר יותר.
### הגדרת 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 של AI | נדרש לכל דבר |
#### טיפים לפיתוח ב-Codespaces
**משתני סביבה ב-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 ודחוף כאשר אתה מוכן
> 💡 **טיפ מקצועי**: שמור את כתובת ה-URL של ה-backend שלך ב-Codespace במהלך הפיתוח. מכיוון ששמות ה-Codespace יציבים, הכתובת לא תשתנה כל עוד אתה משתמש באותו Codespace.
## יצירת ממשק הצ'אט ב-Frontend: איפה אנשים פוגשים את ה-AI
עכשיו נבנה את ממשק המשתמש – החלק שקובע איך אנשים מתקשרים עם העוזר ה-AI שלך. כמו העיצוב של ממשק האייפון המקורי, אנחנו מתמקדים בלגרום לטכנולוגיה מורכבת להרגיש אינטואיטיבית וטבעית לשימוש.
### הבנת ארכיטקטורת 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]
```
### שלושת עמודי התווך של פיתוח 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 מודרני
- **``**: מציין את שפת העמוד עבור קוראי מסך וכלי תרגום
- **``**: מבטיח קידוד תווים נכון לטקסט בינלאומי
- **``**: הופך את העמוד לרספונסיבי לנייד על ידי שליטה בזום ובסקייל
#### אלמנטים סמנטיים
- **``**: מזהה בבירור את החלק העליון עם כותרת ותיאור
- **``**: מציין את אזור התוכן הראשי (איפה שהשיחות מתרחשות)
- **`