הוספת חיפוש וקטורים של Firestore לאפליקציות לנייד באמצעות תוספי Firebase

1. סקירה כללית

ב-codelab הזה תלמדו איך להוסיף לאפליקציה תכונות חיפוש מתקדמות באמצעות חיפוש דמיון וקטורי ב-Firestore. תטמיעו תכונה של חיפוש סמנטי באפליקציה לסיכום פגישות שנכתבה ב-Swift וב-SwiftUI.

מה תלמדו

• איך להתקין את התוסף Vector Search with Firestore כדי לחשב הטמעות וקטוריות.
• איך קוראים ל-Firebase Cloud Functions מאפליקציית Swift.
• איך מסננים מראש נתונים על סמך המשתמש שמחובר לחשבון.

מה צריך

• ‫Xcode 15.3
• קוד לדוגמה של ה-codelab. תורידו אותו בשלב מאוחר יותר של ה-codelab.

2. יצירה והגדרה של פרויקט Firebase

כדי להשתמש בתוסף Firebase Vector Search, צריך פרויקט Firebase. בחלק הזה של ה-codelab, תיצרו פרויקט חדש ב-Firebase ותפעילו את השירותים הנדרשים, כמו Cloud Firestore ו-Firebase Authentication.

יצירת פרויקט Firebase

1. נכנסים למסוף Firebase באמצעות חשבון Google.
2. לוחצים על הלחצן כדי ליצור פרויקט חדש, ואז מזינים שם לפרויקט (לדוגמה, Firestore Vector Search Codelab).
   
3. לוחצים על המשך.
4. אם מוצגת בקשה לעשות זאת, קוראים ומאשרים את התנאים של Firebase, ואז לוחצים על המשך.
5. (אופציונלי) מפעילים את העזרה מבוססת-AI במסוף Firebase (שנקראת Gemini ב-Firebase).
6. ב-codelab הזה לא צריך להשתמש ב-Google Analytics, ולכן משביתים את האפשרות Google Analytics.
7. לוחצים על יצירת פרויקט, מחכים שהפרויקט יוקצה ולוחצים על המשך.

מידע נוסף על פרויקטים ב-Firebase זמין במאמר הסבר על פרויקטים ב-Firebase.

שדרוג תוכנית התמחור של Firebase

כדי להשתמש בתוספים של Firebase ובשירותי הענן הבסיסיים שלהם, הפרויקט שלכם ב-Firebase צריך להיות בתוכנית התמחור 'תשלום לפי שימוש' (Blaze), כלומר הוא צריך להיות מקושר לחשבון לחיוב ב-Cloud.

• בחשבון לחיוב ב-Cloud צריך להגדיר אמצעי תשלום, כמו כרטיס אשראי.
• אם אתם חדשים ב-Firebase וב-Google Cloud, כדאי לבדוק אם אתם עומדים בדרישות לקבלת קרדיט בסך 300$וחשבון לחיוב ב-Cloud עם תקופת ניסיון בחינם.
• אם אתם משתתפים בסדנת קוד כחלק מאירוע, כדאי לשאול את מארגן האירוע אם יש קרדיטים ל-Cloud.

כדי לשדרג את הפרויקט לתוכנית Blaze, פועלים לפי השלבים הבאים:

1. במסוף Firebase, בוחרים באפשרות שדרוג התוכנית.
2. בוחרים בתוכנית Blaze. פועלים לפי ההוראות במסך כדי לקשר חשבון לחיוב ב-Cloud לפרויקט.
   אם הייתם צריכים ליצור חשבון לחיוב ב-Cloud כחלק מהשדרוג, יכול להיות שתצטרכו לחזור לתהליך השדרוג במסוף Firebase כדי להשלים את השדרוג.

הפעלה והגדרה של מוצרי Firebase במסוף

האפליקציה שאתם מפתחים משתמשת בכמה מוצרים של Firebase שזמינים לאפליקציות של אפל:

• אימות ב-Firebase כדי לאפשר למשתמשים להיכנס לאפליקציה בקלות.
• ‫Cloud Firestore כדי לשמור נתונים מובנים בענן ולקבל הודעה מיידית כשמתבצעים שינויים בנתונים.
• כללי אבטחה של Firebase כדי לאבטח את מסד הנתונים.

כדי להשתמש בחלק מהמוצרים האלה, צריך לבצע הגדרה מיוחדת או להפעיל אותם באמצעות מסוף Firebase.

הפעלת אימות אנונימי ב-Firebase Authentication

האפליקציה הזו משתמשת באימות אנונימי כדי לאפשר למשתמשים להתחיל להשתמש באפליקציה בלי ליצור חשבון קודם. כך תהליך ההצטרפות יהיה פשוט ומהיר. מידע נוסף על אימות אנונימי (ועל שדרוג לחשבון עם שם) זמין במאמר שיטות מומלצות לאימות אנונימי.

1. בחלונית הימנית במסוף Firebase, לוחצים על Build > Authentication (פיתוח > אימות). אחר כך לוחצים על שנתחיל?.
2. עכשיו אתם במרכז הבקרה של האימות, שבו תוכלו לראות את המשתמשים שנרשמו, להגדיר ספקי כניסה ולנהל את ההגדרות.
3. בוחרים בכרטיסייה שיטת הכניסה (או לוחצים כאן כדי לעבור ישירות לכרטיסייה).
4. לוחצים על אנונימי באפשרויות הספק, מעבירים את המתג למצב הפעלה ואז לוחצים על שמירה.

הגדרת Cloud Firestore

אפליקציית Swift הזו משתמשת ב-Cloud Firestore כדי לשמור הערות.

כך מגדירים את Cloud Firestore בפרויקט Firebase:

1. בחלונית הימנית במסוף Firebase, מרחיבים את Build ובוחרים באפשרות Firestore database.
2. לוחצים על יצירת מסד נתונים.
3. משאירים את הערך (default) בשדה מזהה מסד הנתונים.
4. בוחרים מיקום למסד הנתונים ולוחצים על הבא.
   באפליקציה אמיתית, כדאי לבחור מיקום שקרוב למשתמשים.
5. לוחצים על התחלה במצב בדיקה. קוראים את כתב הוויתור בנוגע לכללי האבטחה.
   בהמשך ה-codelab הזה, תוסיפו כללי אבטחה כדי לאבטח את הנתונים. אל תפיצו או תחשפו אפליקציה באופן ציבורי בלי להוסיף כללי אבטחה למסד הנתונים.
6. לוחצים על יצירה.

הגדרה של Cloud Storage for Firebase

אפליקציית האינטרנט משתמשת ב-Cloud Storage for Firebase כדי לאחסן, להעלות ולשתף תמונות.

כך מגדירים את Cloud Storage for Firebase בפרויקט Firebase:

1. בחלונית הימנית במסוף Firebase, מרחיבים את Build (פיתוח) ובוחרים באפשרות Storage (אחסון).
2. לוחצים על תחילת העבודה.
3. בוחרים מיקום לקטגוריית האחסון שמוגדרת כברירת מחדל.
   קטגוריות ב-US-WEST1, ב-US-CENTRAL1 וב-US-EAST1 יכולות ליהנות מהמסלול תמיד בחינם של Google Cloud Storage. התמחור והשימוש בקטגוריות בכל המיקומים האחרים מפורטים בתמחור ובשימוש ב-Google Cloud Storage.
4. לוחצים על התחלה במצב בדיקה. קוראים את כתב הוויתור בנוגע לכללי האבטחה.
   בהמשך ה-codelab, תוסיפו כללי אבטחה כדי לאבטח את הנתונים. אל תפיצו או תחשפו אפליקציה לציבור בלי להוסיף כללי אבטחה לדלי שלכם ב-Storage.
5. לוחצים על יצירה.

3. חיבור האפליקציה לנייד

בקטע הזה של ה-codelab, תורידו את קוד המקור של אפליקציה פשוטה לרישום הערות, ותקשרו אותה לפרויקט Firebase שיצרתם.

הורדת האפליקציה לדוגמה

1. עוברים אל https://github.com/FirebaseExtended/codelab-firestore-vectorsearch-ios ומשכפלים את המאגר למחשב המקומי
2. פותחים את הפרויקט Notes.xcodeproj ב-Xcode.

קישור האפליקציה לפרויקט Firebase

כדי שהאפליקציה תוכל לגשת לשירותי Firebase, צריך להגדיר את האפליקציה במסוף Firebase. אפשר לקשר כמה אפליקציות לקוח לאותו פרויקט Firebase. לדוגמה, אם יוצרים אפליקציית Android או אפליקציית אינטרנט, כדאי לקשר אותן לאותו פרויקט Firebase.

מידע נוסף על פרויקטים ב-Firebase זמין במאמר הסבר על פרויקטים ב-Firebase.

1. במסוף Firebase, עוברים לדף הסקירה הכללית של פרויקט Firebase.
2. לוחצים על סמל ה-iOS+ כדי להוסיף את אפליקציית ה-iOS.
3. במסך Add Firebase to your Apple app (הוספת Firebase לאפליקציית Apple), מזינים את מזהה החבילה מפרויקט Xcode (com.google.firebase.codelab.Notes).
4. אם רוצים, אפשר להזין כינוי לאפליקציה (הערות ל-iOS).
5. לוחצים על Register app (רישום אפליקציה) כדי לעבור לשלב הבא.
6. מורידים את הקובץ GoogleServices-Info.plist.
7. גוררים את GoogleServices-Info.plist לתיקייה Notes של פרויקט Xcode. דרך טובה לעשות את זה היא להעביר את הקובץ מתחת לקובץ Assets.xcassets.
8. בוחרים באפשרות העתקת פריטים אם צריך, מוודאים שיעד הערות נבחר באפשרות הוספה ליעדים ולוחצים על סיום.
9. במסוף Firebase, אפשר עכשיו ללחוץ על שאר השלבים בתהליך ההגדרה: בדוגמה שהורדתם בתחילת הקטע הזה כבר מותקן Firebase Apple SDK, וההגדרה של האתחול כבר בוצעה. כדי לסיים את התהליך, לוחצים על המשך אל מסוף.

הפעלת האפליקציה

הגיע הזמן לנסות את האפליקציה!

1. חוזרים ל-Xcode ומריצים את האפליקציה ב-iOS Simulator. בתפריט הנפתח Run Destinations (יעדי הרצה), בוחרים קודם באחד מהסימולטורים של iOS.
2. לאחר מכן, לוחצים על הלחצן Run או מקישים על ‎⌘ + R.
3. אחרי שהאפליקציה מופעלת בהצלחה בסימולטור, מוסיפים כמה הערות.
4. במסוף Firebase, עוברים לדפדפן הנתונים של Firestore כדי לראות מסמכים חדשים שנוצרים כשמוסיפים הערות חדשות באפליקציה.

4. התקנה של התוסף Vector Search with Firestore

בחלק הזה של ה-codelab, תתקינו את התוסף Vector Search with Firestore ותגדירו אותו בהתאם לדרישות של אפליקציית סיכום הפגישות שאתם עובדים עליה.

התחלת ההתקנה של התוסף

1. עדיין בקטע Firestore, לוחצים על הכרטיסייה תוספים.
2. לוחצים על סקירת מרכז התוספים.
3. מקלידים 'וקטור'.
4. לוחצים על Vector Search with Firestore extension (חיפוש וקטורי עם תוסף Firestore). תועברו לדף הפרטים של התוסף, שבו תוכלו לקרוא מידע נוסף על התוסף, על אופן הפעולה שלו, על שירותי Firebase שהוא דורש ועל אופן ההגדרה שלו.
5. לוחצים על Install in Firebase console (התקנה במסוף Firebase).
6. תוצג רשימה של כל הפרויקטים שלכם.
7. בוחרים את הפרויקט שיצרתם בשלב הראשון של ה-codelab הזה.

הגדרת התוסף

1. בודקים את ממשקי ה-API שהופעלו ואת המשאבים שנוצרו.
2. מפעילים את השירותים הנדרשים.
3. אחרי שמפעילים את כל השירותים, לוחצים על הבא.
4. בודקים את הגישה שניתנה לתוסף הזה.
5. מגדירים את התוסף:
   • בוחרים באפשרות Vertex AI בתור מודל שפה גדול (LLM)
   • נתיב האוסף: notes
   • מגבלת ברירת המחדל של שאילתות: 3
   • שם השדה להזנת קלט: text
   • שם שדה הפלט: embedding
   • שם שדה הסטטוס:* *status*
   • הטמעת מסמכים קיימים: כן
   • עדכון מסמכים קיימים: כן
   • המיקום של Cloud Function: us-central1
6. לוחצים על התקנת התוסף כדי לסיים את ההתקנה.

יכול להיות שהתהליך יימשך כמה דקות. בזמן שמחכים לסיום ההתקנה, אפשר לעבור לסעיף הבא במדריך ולקרוא מידע רקע על הטמעות וקטוריות.

5. רקע

בזמן שמחכים לסיום ההתקנה, כדאי לקרוא את המידע הבא על אופן הפעולה של התוסף Vector Search with Firestore.

מהם וקטורים, הטמעות ומסדי נתונים וקטוריים?

• וקטורים הם אובייקטים מתמטיים שמייצגים את הגודל והכיוון של כמות מסוימת. אפשר להשתמש בהם כדי להציג נתונים בצורה שמאפשרת להשוות ולחפש אותם בקלות.
• הטמעות הן וקטורים שמייצגים את המשמעות של מילה או ביטוי. הם נוצרים על ידי אימון רשת נוירונים על קורפוס גדול של טקסט, ולמידת הקשרים בין המילים.
• מסדי נתונים וקטוריים הם מסדי נתונים שעברו אופטימיזציה לאחסון ולחיפוש של נתונים וקטוריים. הם מאפשרים חיפוש יעיל של השכן הקרוב ביותר, שהוא תהליך של מציאת הווקטורים הכי דומים לווקטור שאילתה נתון.

איך פועל חיפוש וקטורי?

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

אפשר למדוד את הדמיון בין שני וקטורים באמצעות מגוון מדדי מרחק. מדד המרחק הנפוץ ביותר הוא דמיון קוסינוס, שמודד את הזווית בין שני וקטורים.

6. כדאי לנסות את התוסף Vector Search with Firestore

לפני שמשתמשים בתוסף Vector Search with Firestore באפליקציית iOS שהורדתם קודם ב-codelab הזה, אפשר לנסות את התוסף במסוף Firebase.

קריאת התיעוד

תוספי Firebase כוללים תיעוד שמסביר איך הם פועלים.

1. בסיום ההתקנה של התוסף, לוחצים על הלחצן תחילת העבודה.
2. בכרטיסייה 'איך התוסף הזה פועל' מוסבר:
   • איך מחשבים הטמעות של מסמכים על ידי הוספה שלהם לאוסף notes,
   • איך לשלוח שאילתה לאינדקס באמצעות קריאה לפונקציה ext-firestore-vector-search-queryCallable callable,
   • או איך לשלוח שאילתה לאינדקס על ידי הוספת מסמך שאילתה לאוסף _firestore-vector-search/index/queries.
   • בנוסף, מוסבר איך להגדיר פונקציית הטמעה מותאמת אישית – זה שימושי אם אף אחד מה-LLM שנתמכים על ידי התוסף לא עונה על הדרישות שלכם, ואתם רוצים להשתמש ב-LLM אחר כדי לחשב הטמעות.
3. לוחצים על הקישור Cloud Firestore dashboard כדי לעבור למופע של Firestore.
4. עוברים למסמך _firestore-vector-search/index. אמור להופיע שהתוסף סיים לחשב את ההטמעות של כל מסמכי הסיכומים שיצרתם בשלב מוקדם יותר ב-codelab הזה.
5. כדי לוודא זאת, פותחים אחד ממסמכי ההערות וצריך לראות שדה נוסף בשם embedding מסוג vector<768>, וגם שדה status.

יצירת מסמך לדוגמה

כדי לראות את התוסף בפעולה, אפשר ליצור מסמך חדש במסוף Firebase.

1. עדיין בדפדפן הנתונים של Firestore, עוברים לאוסף notes ולוחצים על + הוספת מסמך בעמודה האמצעית.
2. לוחצים על Auto-ID (מזהה אוטומטי) כדי ליצור מזהה מסמך ייחודי חדש.
3. מוסיפים שדה בשם text מסוג מחרוזת, ומדביקים טקסט בשדה value. חשוב שהטקסט לא יהיה lorem ipsum או טקסט אקראי אחר. לדוגמה, בוחרים כתבה חדשותית.
4. לוחצים על שמירה.
   • שימו לב איך התוסף מוסיף שדה סטטוס שמציין שהוא מעבד נתונים.
   • אחרי רגע קצר, אמור להופיע שדה חדש embedding עם הערך vector<768>.
   

ביצוע שאילתה

ל-Vector Search עם תוסף Firestore יש תכונה קטנה ושימושית שמאפשרת לשלוח שאילתות לאינדקס המסמכים בלי לחבר אפליקציה.

1. בקטע Firestore במסוף Firebase, עוברים למסמך _firestore-vector-search/index
2. לוחצים על + יצירת אוסף
3. יצירת אוסף משנה חדש בשם queries
4. יוצרים מסמך חדש ומגדירים את השדה query לטקסט שמופיע באחד המסמכים. התכונה הזו פועלת בצורה הכי טובה עם שאילתות סמנטיות, כמו "איך ממפים מסמכי Firestore באמצעות Swift" (בתנאי שלפחות אחת מההערות שהוספתם מכילה טקסט שמתייחס לנושא הזה).
5. יכול להיות שתראו שגיאה בסטטוס
6. הסיבה לכך היא שחסר אינדקס. כדי להגדיר את תצורת האינדקס החסרה, עוברים אל מסוף Google Cloud של הפרויקט באמצעות הקישור הזה, ואז בוחרים את הפרויקט מהרשימה
7. ב-Cloud Log Explorer, אמורה להופיע הודעת שגיאה שאומרת "FAILED_PRECONDITION: Missing vector index configuration. צריך ליצור את האינדקס הנדרש באמצעות פקודת gcloud הבאה: ..."
8. הודעת השגיאה מכילה גם פקודה gcloud שצריך להריץ כדי להגדיר את האינדקס החסר.
9. מריצים את הפקודה הבאה משורת הפקודה. אם ה-CLI של gcloud לא מותקן במחשב, אפשר לפעול לפי ההוראות האלה כדי להתקין אותו.

   gcloud alpha firestore indexes composite create --project=INSERT-YOUR=PROJECT-ID-HERE --collection-group=notes --query-scope=COLLECTION --field-config=vector-config='{"dimension":"768","flat": "{}"}',field-path=embedding
   

   יצירת האינדקס נמשכת כמה דקות. אפשר לבדוק את ההתקדמות בכרטיסייה Indexes (אינדקסים) בקטע Firestore במסוף Firebase.
10. אחרי שמגדירים את האינדקס, אפשר ליצור מסמך שאילתה חדש.
11. עכשיו אמורה להופיע רשימה של מזהי מסמכים תואמים בשדה התוצאות
12. מעתיקים אחד מהמזהים האלה וחוזרים לאוסף notes.
13. משתמשים בצירוף המקשים ⌘+F כדי לחפש את מזהה המסמך שהעתקתם – זה המסמך שהכי מתאים לשאילתה שלכם.

7. הטמעה של חיפוש סמנטי

הגיע הזמן לקשר את האפליקציה לנייד לתוסף Vector Search with Firestore ולהטמיע תכונת חיפוש סמנטי שתאפשר למשתמשים לחפש את ההערות שלהם באמצעות שאילתות בשפה טבעית.

קישור הפונקציה שאפשר להפעיל כדי לבצע שאילתות

התוסף Vector Search with Firestore כולל Cloud Function שאפשר להפעיל מאפליקציית המובייל כדי לשלוח שאילתה לאינדקס שיצרתם קודם ב-codelab הזה. בשלב הזה, יוצרים חיבור בין האפליקציה לנייד לבין הפונקציה הזו שאפשר להפעיל. ‫Firebase Swift SDK כולל ממשקי API שמאפשרים לקרוא לפונקציות מרחוק בצורה חלקה.

1. חוזרים ל-Xcode ומוודאים שאתם בפרויקט ששיבטתם בשלב הקודם ב-codelab הזה.
2. פותחים את הקובץ NotesRepository.swift.
3. מחפשים את השורה שמכילה את private lazy var vectorSearchQueryCallable: Callable = functions.httpsCallable("")

כדי להפעיל פונקציה שאפשר לקרוא לה ב-Cloud Functions, צריך לציין את שם הפונקציה שרוצים להפעיל.

4. נכנסים למסוף Firebase של הפרויקט ופותחים את הפריט Functions בתפריט בקטע Build.
5. תוצג רשימה של פונקציות שהותקנו על ידי התוסף.
6. מחפשים את הקובץ שנקרא ext-firestore-vector-search-queryCallable ומעתיקים את השם שלו.
7. מדביקים את השם בקוד. הטקסט צריך להיות

   private lazy var vectorSearchQueryCallable: Callable<String, String> = functions.httpsCallable("ext-firestore-vector-search-queryCallable")
   

הפעלת פונקציית השאילתה

1. מאתרים את השיטה performQuery
2. קוראים לפונקציה שאפשר לקרוא לה על ידי הפעלה

   let result = try await vectorSearchQueryCallable(searchTerm)
   

יכול להיות שהשיחה תכשל כי היא מתבצעת מרחוק.

3. מוסיפים טיפול בסיסי בשגיאות כדי לזהות שגיאות ולתעד אותן במסוף של Xcode.

   private func performQuery(searchTerm: String) async -> [String] {
     do {
       let result = try await vectorSearchQueryCallable(searchTerm)
       return [result]
     }
     catch {
       print(error.localizedDescription)
       return []
     }
   }
   

חיבור ממשק המשתמש

כדי לאפשר למשתמשים לחפש את ההערות שלהם, צריך להטמיע סרגל חיפוש במסך רשימת ההערות. כשהמשתמש מקליד מונח חיפוש, צריך להפעיל את השיטה performQuery שהטמעתם בשלב הקודם. הודות לשינויים בתצוגה searchable ו-task ש-SwiftUI מספקת, נדרשות רק כמה שורות קוד.

1. קודם, פותחים את NotesListScreen.swift
2. כדי להוסיף תיבת חיפוש לתצוגת הרשימה, מוסיפים את משנה התצוגה .searchable(text: $searchTerm, prompt: "Search") ממש מעל השורה .navigationTitle("Notes")
3. לאחר מכן, מפעילים את פונקציית החיפוש על ידי הוספת הקוד הבא ממש מתחת:

.task(id: searchTerm, debounce: .milliseconds(800)) {
  await notesRepository.semanticSearch(searchTerm: searchTerm)
}

קטע הקוד הזה קורא לשיטת semanticSearch באופן אסינכרוני. הגדרתם פסק זמן של 800 אלפיות השנייה, ולכן שיניתם את ההתנהגות של הפונקציה לשינוי המשימה כך שהיא תמתין 0.8 שניות לפני שהיא תבצע את הפעולה. כלומר, הפונקציה semanticSearch תופעל רק אחרי שהמשתמש יפסיק להקליד למשך יותר מ-0.8 שניות.

הקוד אמור להיראות כך:

...
List(repository.notes) { note in
  NavigationLink(value: note) {
    NoteRowView(note: note)
  }
  .swipeActions {
    Button(role: .destructive, action: { deleteNote(note: note) }) {
      Label("Delete", systemImage: "trash")
    }
  }
}
.searchable(text: $searchTerm, prompt: "Search")
.task(id: searchTerm, debounce: .milliseconds(800)) {
  await notesRepository.semanticSearch(searchTerm: searchTerm)
}
.navigationTitle("Notes")
...

הפעלת האפליקציה

1. מקישים על ‎⌘ + R (או לוחצים על הלחצן Run) כדי להפעיל את האפליקציה ב-iOS Simulator.
2. אתם אמורים לראות את אותן הערות שהוספתם באפליקציה בשלב מוקדם יותר ב-codelab הזה, וגם את כל ההערות שהוספתם דרך מסוף Firebase.
3. שדה החיפוש יופיע בראש רשימת ההערות.
4. מקלידים מונח שמופיע באחד המסמכים שהוספתם. השיטה הזו מתאימה במיוחד לשאילתות סמנטיות, כמו "איך אפשר להתקשר לממשקי API אסינכרוניים של Firebase מ-Swift" (בתנאי שלפחות אחת מההערות שהוספתם מכילה טקסט שמתייחס לנושא הזה).
5. סביר להניח שציפיתם לראות את תוצאת החיפוש, אבל במקום זאת, תצוגת הרשימה ריקה, ובמסוף של Xcode מוצגת הודעת שגיאה: 'הפונקציה הופעלה עם ארגומנט לא תקין'

המשמעות היא ששלחתם את הנתונים בפורמט שגוי.

ניתוח הודעת השגיאה

1. כדי לגלות מה הבעיה, עוברים אל מסוף Firebase
2. עוברים לקטע פונקציות.
3. מאתרים את הפונקציה ext-firestore-vector-search-queryCallable, פותחים את תפריט האפשרויות הנוספות בלחיצה על שלוש הנקודות האנכיות.
4. בוחרים באפשרות הצגת יומנים כדי לעבור אל Logs Explorer.
5. אמורה להופיע שגיאה

Unhandled error ZodError: [
  {
    "code": "invalid_type",
    "expected": "object",
    "received": "string",
    "path": [],
    "message": "Expected object, received string"
  }
]

המשמעות היא ששלחתם את הנתונים בפורמט שגוי.

שימוש בסוגי הנתונים הנכונים

כדי לגלות באיזה פורמט התוסף מצפה שהפרמטרים יהיו, כדאי לעיין במסמכי התיעוד של התוסף.

1. עוברים לקטע תוספים במסוף Firebase.
2. לוחצים על ניהול ->
3. בקטע How this extension works (איך התוסף הזה פועל) מפורטים פרמטרים של קלט ופלט.
4. חוזרים אל Xcode ועוברים אל NotesRepository.swift
5. מוסיפים את הקוד הבא בתחילת הקובץ:
   ‫

   private struct QueryRequest: Codable {
     var query: String
     var limit: Int?
     var prefilters: [QueryFilter]?
   }
   
   private struct QueryFilter: Codable {
     var field: String
     var `operator`: String
     var value: String
   
   }
   
   private struct QueryResponse: Codable {
     var ids: [String]
   }
   

   ‫QueryRequest תואם למבנה של פרמטר הקלט שהתוסף מצפה לו, בהתאם לתיעוד של התוסף. הוא מכיל גם מאפיין prefilter מקונן שתצטרכו בהמשך.QueryResponse תואם למבנה של התגובה של התוסף.
6. מציאת המפרט של הפונקציה שאפשר להפעיל ועדכון של סוגי הקלט והפלט

   private lazy var vectorSearchQueryCallable: Callable<QueryRequest, QueryResponse> = functions.httpsCallable("ext-firestore-vector-search-queryCallable")
   

7. עדכון הקריאה לפונקציה שאפשר להפעיל ב-performQuery

   private func performQuery(searchTerm: String) async -> [String] {
     do {
       let queryRequest = QueryRequest(query: searchTerm,
                                       limit: 2)
       let result = try await vectorSearchQueryCallable(queryRequest)
       print(result.ids)
       return result.ids
     }
     catch {
       print(error.localizedDescription)
       return []
     }
   }
   

הפעלת האפליקציה שוב

1. הפעלת האפליקציה שוב
2. מקלידים שאילתת חיפוש שמכילה מונחים שנכללים באחת מההערות
3. עכשיו אמורה להופיע רשימת הערות מסוננת

סינון מוקדם של נתוני משתמשים

לפני שתצאו במחולות משמחה – יש בעיה בגרסה הנוכחית של האפליקציה: קבוצת התוצאות מכילה נתונים של כל המשתמשים.

כדי לוודא זאת, אפשר להריץ את האפליקציה בסימולטור אחר ולהוסיף עוד מסמכים. המסמכים החדשים יופיעו רק בסימולטור הזה. אם תפעילו את האפליקציה שוב בסימולטור השני, יופיעו רק המסמכים שיצרתם בפעם הראשונה.

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

ב-performQuery, מעדכנים את הקוד באופן הבא:

  let prefilters: [QueryFilter] = if let uid = user?.uid {
    [QueryFilter(field: "userId", operator: "==", value: uid)]
  }
  else {
    []
  }

  let queryRequest = QueryRequest(query: searchTerm,
                                  limit: 2,
                                  prefilters: prefilters)

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

מריצים את הפקודה הבאה משורת הפקודה כדי להגדיר אינדקס חדש של Firestore שכולל גם את userId וגם את הטמעות הווקטור בשדה embedding.

gcloud alpha firestore indexes composite create --project=INSERT-YOUR-PROJECT-ID-HERE --collection-group=notes --query-scope=COLLECTION --field-config=order=ASCENDING,field-path=userId --field-config=vector-config='{"dimension":"768","flat": "{}"}',field-path=embedding

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

8. מזל טוב

כל הכבוד, סיימתם את ה-Codelab!

ב-Codelab הזה למדתם איך:

• מגדירים מסד נתונים של Cloud Firestore עם חיפוש סמנטי מופעל.
• יוצרים אפליקציית SwiftUI פשוטה כדי ליצור אינטראקציה עם מסד הנתונים.
• מטמיעים סרגל חיפוש באמצעות modifier של תצוגה שניתן לחיפוש ב-SwiftUI ואת ה-modifier של המשימה.
• קוראים לפונקציית Cloud כדי לבצע חיפוש סמנטי במסד הנתונים, באמצעות הממשק Callable של Firestore SDK.

בעזרת הידע שרכשתם ב-codelab הזה, אתם יכולים עכשיו ליצור אפליקציות עוצמתיות שמנצלות את יכולות החיפוש הסמנטי של Cloud Firestore כדי לספק למשתמשים חוויית חיפוש אינטואיטיבית ויעילה יותר.

מידע נוסף על שדה הווקטור החדש של Firestore ועל חישוב הטמעות וקטוריות זמין במאמרי העזרה.