הגדרת השלמה אוטומטית מתקדמת

בדף הזה מתוארת תכונת ההשלמה האוטומטית המתקדמת של Agent Search.

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

לפני שקוראים את הדף הזה, כדאי להכיר את ההשלמה האוטומטית הבסיסית של Agent Search. איך מגדירים השלמה אוטומטית

תכונות מרכזיות של השלמה אוטומטית מתקדמת

התכונות העיקריות של ההשלמה האוטומטית המתקדמת שמבדילות אותה מההשלמה האוטומטית הבסיסית הן:

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

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

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

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

לפני שמתחילים

לפני שמתחילים להשתמש בהשלמה אוטומטית מתקדמת, צריך לבצע את הפעולות הבאות:

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

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

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

• אם אתם מתכננים להשתמש בהצעות לחיפושים האחרונים (RECENT_SEARCH), ודאו שאתם מתעדים אירועים של משתמשי חיפוש. חיפוש מבוסס סוכנים לא מאכלס אוטומטית את אינדקס החיפושים האחרונים כשמבצעים חיפושים באמצעות השיטה SearchService.Search. כדי להחזיר שאילתות אחרונות, צריך לתעד אירועים של משתמשי חיפוש באמצעות השיטה userEvents.write. מידע על שאילתות אחרונות זמין במאמר לפני שמתחילים.

שליחת בקשות להשלמה אוטומטית

בדוגמה הבאה אפשר לראות איך לשלוח בקשות מתקדמות להשלמה אוטומטית באמצעות השיטה completionConfig.completeQuery.

REST

כדי לשלוח בקשה להשלמה אוטומטית באמצעות ה-API, פועלים לפי השלבים הבאים:

1. מאתרים את מזהה האפליקציה. אם כבר יש לכם מזהה אפליקציה, דלגו לשלב הבא.

   1. נכנסים לדף AI Applications במסוף Google Cloud .

      מעבר אל 'אפליקציות'

   2. בדף אפליקציות, מאתרים את שם האפליקציה ומעתיקים את המזהה שלה מהעמודה מזהה.

2. מבצעים קריאה ל-method‏ completionConfig.completeQuery.

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/completionConfig:completeQuery" \
   -d '{
         "query":"QUERY_STRING"
       }'
   

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

   • ‫APP_ID: המזהה של אפליקציית חיפוש מבוסס סוכנים.

   • ‫QUERY_STRING: הקלט של ההשלמה האוטומטית שמשמש לאחזור הצעות.

שליחת בקשה להשלמה אוטומטית עם שיפור שפה

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

ערך ההגברה צריך להיות בין ‎-1 ל-1. הגדרת מספר שלילי 'קוברת' את ההצעות להשלמה אוטומטית בשפה הזו, והגדרת מספר חיובי משפרת את השפה.

משתמשים בתגי שפה בני שתי אותיות שמוגדרים ב-BCP 47 – לדוגמה, en,‏ fr,‏ hi ו-zh.

REST

כדי לשלוח בקשת השלמה אוטומטית שכוללת ערך של הגברת שפה:

1. מאתרים את מזהה האפליקציה. אם כבר יש לכם מזהה אפליקציה, דלגו לשלב הבא.

   1. נכנסים לדף AI Applications במסוף Google Cloud .

      מעבר אל 'אפליקציות'

   2. בדף אפליקציות, מאתרים את שם האפליקציה ומעתיקים את המזהה שלה מהעמודה מזהה.

2. מבצעים קריאה ל-method‏ completionConfig.completeQuery.

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/completionConfig:completeQuery" \
   -d '{
         "query":"QUERY_STRING",
         "boostSpec": {
            "conditionBoostSpecs": [{
              "condition": "(langCode: ANY(LANG_CODE))",
              "boost": BOOST_VALUE
            }]
         }
       }'
   
   

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

   • ‫APP_ID: המזהה של אפליקציית חיפוש מבוסס סוכנים.

   • ‫QUERY_STRING: הקלט של ההשלמה האוטומטית שמשמש לאחזור הצעות.

   • ‫LANG_CODE: קוד בן שתי אותיות של שפה אחת או יותר, במירכאות עם תווי escape. לדוגמה, \"fr\", \"es\" כדי להחיל את ערך ההגדלה על ספרדית וצרפתית.

   • ‫BOOST_VALUE: מספר בשיטת נקודה צפה בין ‎-1 ל-1. אם הערך שלילי, ההצעות האוטומטיות בשפה יופיעו במקום נמוך יותר ברשימת ההצעות. אם הערך חיובי, ההצעות מקודמות (הן מופיעות גבוה יותר ברשימה).

   פקודה לדוגמה

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/completionConfig:completeQuery" \
   -d '{
        "query": "hol",
        "boostSpec": {
           "conditionBoostSpecs": [{
             "condition": "(langCode: ANY(\"es\", \"fr\"))",
             "boost": 0.75 }, {
             "condition": "(langCode: ANY(\"en\"))",
             "boost": -1
           }]
         }
       }'
    

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

שליחת בקשת השלמה אוטומטית והחזרת שאילתות מהזמן האחרון

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

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

חשוב: התכונה'חיפוש באמצעות סוכן' לא מתעדת באופן אוטומטי בהיסטוריית החיפושים האחרונה של המשתמש את שאילתות החיפוש שבוצעו באמצעות השיטה SearchService.Search. כדי להחזיר שאילתות אחרונות, צריך לתעד אירועים של משתמשים בחיפוש. פרטים נוספים מופיעים במאמר לפני שמתחילים.

לפני שמתחילים

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

אם אירועי משתמשים בחיפוש לא נכתבים, בקשות אל completionConfig.completeQuery עם suggestionTypes: ["RECENT_SEARCH"] מחזירות רשימה ריקה של הצעות ({}).

כדי לתעד אירוע של משתמש שביצע חיפוש, שולחים בקשת POST לשיטה userEvents.write עם הערכים הבאים:

• ‫eventType: מוגדר ל-"search"
• ‫userPseudoId: מוגדר למזהה הייחודי של המשתמש שעבר פסאודונימיזציה
• ‫engine: מוגדר לשם המשאב של המנוע
• ‫searchInfo.searchQuery: מוגדר למחרוזת של שאילתת החיפוש שהמשתמש הזין

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/userEvents:write" \
  -d '{
        "eventType": "search",
        "userPseudoId": "USER_PSEUDO_ID",
        "engine": "projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID",
        "searchInfo": {
          "searchQuery": "SEARCH_QUERY"
        }
      }'

מחליפים את מה שכתוב בשדות הבאים:

• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
• ‫LOCATION: המיקום של האפליקציה או מאגר הנתונים (לדוגמה, global או us).
• ‫APP_ID: המזהה של אפליקציית חיפוש מבוסס סוכנים.
• ‫USER_PSEUDO_ID: מזהה פסאודונימי של המשתמש. הערך הזה צריך להיות זהה לערך userPseudoId שמועבר בבקשות completionConfig.completeQuery הבאות.
• ‫SEARCH_QUERY: מחרוזת השאילתה שהמשתמש חיפש.

מידע נוסף זמין במאמר בנושא תיעוד אירועים של משתמשים בזמן אמת באמצעות השיטה userEvents.write.

דוגמה

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

‫PTO, Vacation blackout periods, How much vacation time do I have?, Time off, Vacation policy, covering a vacant position during absences וגם Can I take unpaid time off?.

עכשיו, בתגובה להקלדה של vac בתיבת החיפוש על ידי העובד, ההצעות להשלמה אוטומטית יהיו:

• Vacation blackout periods
• How much vacation time do I have?
• Vacation policy
• Covering a vacant position during absences

התהליך

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

REST

1. מאתרים את מזהה האפליקציה. אם כבר יש לכם מזהה אפליקציה, דלגו לשלב הבא.

   1. נכנסים לדף AI Applications במסוף Google Cloud .

      מעבר אל 'אפליקציות'

   2. בדף אפליקציות, מאתרים את שם האפליקציה ומעתיקים את המזהה שלה מהעמודה מזהה.

2. מבצעים קריאה ל-method‏ completionConfig.completeQuery.

   
   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/completionConfig:completeQuery" \
   -d '{
         "query":"QUERY_STRING",
         "suggestionTypes": ["RECENT_SEARCH"],
         "userPseudoId": "USER_PSEUDO_ID"
       }'
   
   

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

   • ‫APP_ID: המזהה של אפליקציית חיפוש מבוסס סוכנים.

   • ‫QUERY_STRING: הקלט של ההשלמה האוטומטית שמשמש לאחזור הצעות.

   • ‫USER_PSEUDO_ID: מזהה של המשתמש שעבר פסאודונימיזציה. אפשר להשתמש בקובץ Cookie של HTTP בשדה הזה, כדי לזהות מבקר באופן ייחודי במכשיר יחיד. אל תגדירו בשדה הזה את אותו מזהה לכמה משתמשים. הפעולה הזו תשלב את היסטוריית השאילתות שלהם. אסור לכלול פרטים אישיים מזהים (PII) בשדה הזה.

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

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/completionConfig:completeQuery" \
   -d '{
         "query": "hol",
         "suggestionTypes": ["RECENT_SEARCH"],
         "userPseudoId": "test_user"
       }'
   
   {
     "recentSearchSuggestions": [
       {
         "suggestion": "holiday readiness",
         "recentSearchTime": "2025-05-19T18:27:07.261698Z"
       },
       {
         "suggestion": "holiday freeze",
         "recentSearchTime": "2025-05-19T18:25:45.744021Z"
       },
       {
         "suggestion": "holiday",
         "recentSearchTime": "2025-05-19T18:20:08.916884Z"
       }
     ]
   }
   

הערה: אם מציינים את suggestionTypes כ-RECENT_SEARCH, המערכת מתעלמת מכל הפרמטרים boostSpec, queryModel או includeTailSuggestions בפקודת curl.

שימוש ברשימת חסימה של השלמה אוטומטית

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

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

מידע על יצירה ושימוש ברשימות חסימה זמין במאמר שימוש ברשימת חסימה להשלמה אוטומטית.

שימוש ברשימה מיובאת של הצעות להשלמה אוטומטית

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

מידע על ייבוא רשימה זמין במאמר שימוש ברשימה מיובאת של הצעות להשלמה אוטומטית.