HUGGINGFACE_SPACES_GUIDE.md

# 🚀 מדריך מפורט: פריסה ב-Hugging Face Spaces

מדריך זה ילווה אותך צעד אחר צעד בהקמת הפרויקט ב-Hugging Face Spaces.

---

## 📋 תוכן עניינים

1. [דרישות מקדימות](#דרישות-מקדימות)
2. [שלב 1: יצירת Space חדש](#שלב-1-יצירת-space-חדש)
3. [שלב 2: הכנת הפרויקט](#שלב-2-הכנת-הפרויקט)
4. [שלב 3: העלאת הקוד](#שלב-3-העלאת-הקוד)
5. [שלב 4: הגדרת API Keys](#שלב-4-הגדרת-api-keys)
6. [שלב 5: העלאת קובץ הנתונים](#שלב-5-העלאת-קובץ-הנתונים)
7. [שלב 6: בדיקה ופתרון בעיות](#שלב-6-בדיקה-ופתרון-בעיות)
8. [שלב 7: עדכונים עתידיים](#שלב-7-עדכונים-עתידיים)

---

## דרישות מקדימות

לפני שנתחיל, ודא שיש לך:

- ✅ **חשבון ב-Hugging Face** - [הירשם כאן](https://huggingface.co/join)
- ✅ **API Key מ-Google Gemini** - [קבל כאן](https://makersuite.google.com/app/apikey)
  - או **API Key מ-OpenAI** - [קבל כאן](https://platform.openai.com/api-keys)
- ✅ **קובץ הנתונים** - `0_preprocessing/feedback_transformed_2.csv`
- ✅ **Git מותקן** במחשב שלך

---

## שלב 1: יצירת Space חדש

### 1.1 כניסה ל-Hugging Face Spaces

1. היכנס ל-[Hugging Face Spaces](https://huggingface.co/spaces)
2. לחץ על הכפתור **"Create new Space"** (או **"New Space"**)

### 1.2 הגדרת ה-Space

מלא את הפרטים הבאים:

- **Space name**: `feedback-analysis-agent` (או שם אחר לבחירתך)
  - ⚠️ **חשוב**: השם חייב להיות באנגלית, ללא רווחים, עם מקפים בלבד
- **SDK**: בחר **"Docker"** 
  - זה נדרש כי אנחנו משתמשים ב-FastAPI
- **Visibility**: בחר **Public** (ציבורי) או **Private** (פרטי)
  - אם יש לך נתונים רגישים, בחר **Private**

### 1.3 יצירת ה-Space

לחץ על **"Create Space"**

🎉 **מזל טוב!** יצרת Space חדש. עכשיו תועבר לדף ה-Space שלך.

---

## שלב 2: הכנת הפרויקט

### 2.1 בדיקת הקבצים הנדרשים

ודא שיש לך את הקבצים הבאים בפרויקט:

```
📁 Feedback_Analysis_RAG_Agent_runpod/
├── 📄 app.py                    ← נקודת כניסה ל-HF Spaces (חדש!)
├── 📄 Dockerfile                ← קובץ Docker
├── 📄 requirements.txt          ← תלויות Python
├── 📄 README.md                 ← תיעוד עם metadata
├── 📁 2_backend_llm/            ← קוד ה-backend
│   ├── 📁 app/
│   │   ├── api.py
│   │   ├── config.py
│   │   ├── data_loader.py
│   │   └── sql_service.py
│   └── app.py
├── 📁 1_frontend/               ← קוד ה-frontend
│   ├── index.html
│   └── app.js
└── 📁 0_preprocessing/
    └── feedback_transformed_2.csv  ← קובץ הנתונים
```

### 2.2 בדיקת Git

ודא שהפרויקט שלך הוא Git repository:

```bash
cd /path/to/Feedback_Analysis_RAG_Agent_runpod
git status
```

אם זה לא Git repository, הפעל:

```bash
git init
git add .
git commit -m "Initial commit for HF Spaces deployment"
```

---

## שלב 3: העלאת הקוד

יש לך שתי אפשרויות להעלות את הקוד:

### אפשרות א': דרך Git (מומלץ) ⭐

זו הדרך המומלצת כי היא מאפשרת עדכונים קלים בעתיד.

#### 3.1 קבלת ה-URL של ה-Space

1. פתח את ה-Space שלך ב-Hugging Face
2. לחץ על הכפתור **"Files and versions"** (או **"Files"**)
3. תמצא את ה-URL של ה-Git repository בחלק העליון
   - זה ייראה כך: `https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME`

#### 3.2 הוספת Remote

פתח טרמינל בתיקיית הפרויקט והפעל:

```bash
# החלף YOUR_USERNAME ו-YOUR_SPACE_NAME בשם האמיתי שלך
git remote add huggingface https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
```

**דוגמה:**
```bash
git remote add huggingface https://huggingface.co/spaces/galbendavids/feedback-analysis-agent
```

#### 3.3 דחיפת הקוד

```bash
# ודא שאתה על branch main
git checkout main

# דחוף את הקוד ל-Hugging Face
git push huggingface main
```

**הערה**: בפעם הראשונה, Hugging Face יבקש ממך שם משתמש וסיסמה:
- **Username**: שם המשתמש שלך ב-Hugging Face
- **Password**: Token אישי (לא הסיסמה!)
  - קבל Token מ-[כאן](https://huggingface.co/settings/tokens)
  - בחר **"Write"** permissions

### אפשרות ב': דרך ה-Web UI

אם אתה מעדיף לא להשתמש ב-Git:

1. פתח את ה-Space ב-Hugging Face
2. לחץ על **"Files and versions"** → **"Add file"** → **"Upload files"**
3. העלה את הקבצים הבאים (גרור ושחרר):
   - `app.py`
   - `Dockerfile`
   - `requirements.txt`
   - `README.md`
   - כל התיקייה `2_backend_llm/` (עם כל התוכן)
   - כל התיקייה `1_frontend/` (עם כל התוכן)

⚠️ **חשוב**: העלה את כל הקבצים והתיקיות, אחרת האפליקציה לא תעבוד!

---

## שלב 4: הגדרת API Keys

**⚠️ קריטי**: ללא API Key, האפליקציה לא תעבוד!

### 4.1 יצירת Token ב-Hugging Face

1. לך ל-[Hugging Face Settings → Tokens](https://huggingface.co/settings/tokens)
2. לחץ על **"New token"**
3. תן שם ל-Token (למשל: "HF Spaces API Key")
4. בחר **"Read"** permissions (זה מספיק)
5. לחץ על **"Generate token"**
6. **העתק את ה-Token** - לא תוכל לראות אותו שוב!

### 4.2 הוספת API Keys כ-Secrets

1. פתח את ה-Space שלך ב-Hugging Face
2. לך ל-**"Settings"** (בתפריט העליון)
3. לחץ על **"Repository secrets"** (בתפריט הצד)
4. לחץ על **"New secret"**

#### הוסף את ה-Secrets הבאים:

**Secret 1: GEMINI_API_KEY**
- **Name**: `GEMINI_API_KEY`
- **Value**: ה-API Key שלך מ-Google Gemini
- לחץ על **"Add secret"**

**Secret 2: OPENAI_API_KEY** (אופציונלי - רק אם אתה משתמש ב-OpenAI)
- **Name**: `OPENAI_API_KEY`
- **Value**: ה-API Key שלך מ-OpenAI
- לחץ על **"Add secret"**

**⚠️ חשוב**: לפחות אחד מה-API Keys חייב להיות מוגדר!

### 4.3 איך לקבל API Keys?

**Google Gemini:**
1. לך ל-[Google AI Studio](https://makersuite.google.com/app/apikey)
2. לחץ על **"Get API Key"**
3. בחר או צור פרויקט
4. העתק את ה-API Key

**OpenAI:**
1. לך ל-[OpenAI Platform](https://platform.openai.com/api-keys)
2. לחץ על **"Create new secret key"**
3. תן שם ל-Key
4. העתק את ה-API Key

---

## שלב 5: העלאת קובץ הנתונים

### 5.1 בדיקת קובץ הנתונים

ודא שקובץ הנתונים קיים:
- `0_preprocessing/feedback_transformed_2.csv`

### 5.2 העלאת הקובץ

יש לך שתי אפשרויות:

#### אפשרות א': דרך Git (אם הקובץ קטן מ-10MB)

```bash
# ודא שהקובץ קיים
ls 0_preprocessing/feedback_transformed_2.csv

# הוסף ל-Git (אם הוא לא ב-.gitignore)
git add 0_preprocessing/feedback_transformed_2.csv
git commit -m "Add feedback data file"
git push huggingface main
```

#### אפשרות ב': דרך ה-Web UI

1. פתח את ה-Space ב-Hugging Face
2. לחץ על **"Files and versions"** → **"Add file"** → **"Upload files"**
3. צור תיקייה `0_preprocessing/` (אם היא לא קיימת)
4. העלה את `feedback_transformed_2.csv` לתיקייה `0_preprocessing/`

**⚠️ הערה**: אם הקובץ גדול מ-10MB, ייתכן שתצטרך להשתמש ב-Git LFS:
```bash
git lfs install
git lfs track "*.csv"
git add .gitattributes
git add 0_preprocessing/feedback_transformed_2.csv
git commit -m "Add feedback data with LFS"
git push huggingface main
```

---

## שלב 6: בדיקה ופתרון בעיות

### 6.1 בדיקת הבנייה

1. פתח את ה-Space שלך ב-Hugging Face
2. לחץ על הטאב **"Logs"** (בתפריט העליון)
3. תצפה בלוגים - Hugging Face בונה את ה-Space אוטומטית

**מה לחפש:**
- ✅ `Building...` - הבנייה התחילה
- ✅ `Successfully built` - הבנייה הצליחה
- ✅ `SQL service initialized successfully` - השירות עלה בהצלחה
- ❌ שגיאות - ראה [פתרון בעיות](#פתרון-בעיות) למטה

### 6.2 בדיקת האפליקציה

לאחר שהבנייה הסתיימה:

1. לחץ על הטאב **"App"** (בתפריט העליון)
2. האפליקציה אמורה להיפתח
3. נסה לשאול שאלה, למשל: "כמה משתמשים כתבו תודה?"

### 6.3 פתרון בעיות

#### ❌ שגיאה: "No feedback data available"

**פתרון:**
1. ודא ש-`0_preprocessing/feedback_transformed_2.csv` קיים ב-Space
2. בדוק את ה-Logs - שם תראה את הנתיב המדויק שהאפליקציה מחפשת
3. ודא שהקובץ נמצא בנתיב הנכון: `0_preprocessing/feedback_transformed_2.csv`

#### ❌ שגיאה: "API Key not found"

**פתרון:**
1. לך ל-**"Settings"** → **"Repository secrets"**
2. ודא ש-`GEMINI_API_KEY` או `OPENAI_API_KEY` מוגדרים
3. ודא שהשמות מדויקים (case-sensitive!)
4. נסה למחוק ולהוסיף מחדש את ה-Secret

#### ❌ שגיאה: "Port 7860 already in use"

**פתרון:**
- זה לא אמור לקרות ב-HF Spaces
- אם זה קורה, בדוק את ה-Logs לפרטים נוספים

#### ❌ שגיאה: "Module not found"

**פתרון:**
1. ודא ש-`requirements.txt` מעודכן
2. בדוק את ה-Logs - שם תראה איזה מודול חסר
3. הוסף את המודול החסר ל-`requirements.txt` ודחוף מחדש

#### ❌ Space לא עולה / קורס

**פתרון:**
1. בדוק את ה-**Logs** - שם תראה את השגיאה המדויקת
2. ודא ש-`app.py` קיים בשורש הפרויקט
3. ודא ש-`Dockerfile` קיים
4. ודא ש-`requirements.txt` מעודכן

---

## שלב 7: עדכונים עתידיים

### 7.1 עדכון הקוד

כשאתה רוצה לעדכן את ה-Space:

```bash
# בצע שינויים בקוד המקומי
# ...

# הוסף את השינויים
git add .

# Commit
git commit -m "Update: תיאור השינויים"

# דחוף ל-Hugging Face
git push huggingface main
```

Hugging Face יבנה מחדש את ה-Space אוטומטית!

### 7.2 עדכון API Keys

אם אתה צריך לעדכן API Key:

1. לך ל-**"Settings"** → **"Repository secrets"**
2. לחץ על ה-Secret שברצונך לעדכן
3. לחץ על **"Edit"** או **"Delete"** ויצור חדש

---

## ✅ סיכום - רשימת בדיקה

לפני שאתה מסיים, ודא ש:

- [ ] Space נוצר ב-Hugging Face
- [ ] הקוד נדחף/הועלה ל-Space
- [ ] `app.py` קיים בשורש הפרויקט
- [ ] `Dockerfile` קיים
- [ ] `requirements.txt` מעודכן
- [ ] API Key מוגדר ב-Repository secrets
- [ ] קובץ הנתונים `0_preprocessing/feedback_transformed_2.csv` קיים
- [ ] הבנייה הצליחה (בודק ב-Logs)
- [ ] האפליקציה עובדת (בודק ב-App)

---

## 🎉 מזל טוב!

הפרויקט שלך אמור לעבוד עכשיו ב-Hugging Face Spaces!

**קישור ל-Space שלך:**
`https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME`

---

## 📚 משאבים נוספים

- [Hugging Face Spaces Documentation](https://huggingface.co/docs/hub/spaces)
- [Docker Spaces Guide](https://huggingface.co/docs/hub/spaces-sdks-docker)
- [Environment Variables in Spaces](https://huggingface.co/docs/hub/spaces-sdks-docker#environment-variables)
- [Git LFS Documentation](https://git-lfs.github.com/)

---

## 💬 תמיכה

אם נתקלת בבעיות:

1. בדוק את ה-Logs ב-Hugging Face Spaces
2. בדוק את [פתרון בעיות](#פתרון-בעיות) למעלה
3. פתח Issue ב-GitHub repository

**בהצלחה! 🚀**