דירוג מחדש של תוצאות חיפוש באמצעות VertexRanker

‫Agent Retrieval (לשעבר חיפוש וקטורי 2.0) מספק את VertexRanker לדירוג סמנטי מחדש, שמופעל על ידי Ranking API.

אחרי ש-Agent Retrieval מאחזר וממזג את התוצאות המועמדות (באמצעות Reciprocal Rank Fusion (RRF)), ‏ VertexRanker מדרג מחדש את המועמדים הממוזגים לפי השאילתה בשפה טבעית באמצעות מודל סמנטי ייעודי. כך משתפרת הרלוונטיות של תוצאות ה-Top-K, במיוחד בשאילתות שבהן החיפוש לבדו מפספס ניואנסים. הדירוג מחדש מתבצע בצד השרת באמצעות קריאות ל-BatchSearchDataObjects. אין צורך בחיווט נוסף בצד הלקוח או בנסיעות הלוך ושוב נוספות.

VertexRanker

‫VertexRanker מוגדר ככלי לדירוג מחדש של השדה combine.ranker באובייקט BatchSearchDataObjectsRequest. צריך להגדיר מדרג ראשי (רק RRF נתמך). הדירוג מחדש פועל אחרי שלב המיזוג של ה-RRF ומחליף את הפלט ברשימה שדורגה מחדש מבחינה סמנטית.

בטבלה הבאה מפורטים שדות התצורה של הדירוג.

שדה חובה תיאור
combine.ranker.rrf.weights כן המשקלים של מיזוג ה-RRF של תוצאות החיפוש הבסיסיות.
combine.ranker.vertex_ranker.model כן שם המודל לדירוג. ערכים נתמכים: semantic-ranker-fast@latest,‏ semantic-ranker-default@latest,‏ semantic-ranker-fast-004,‏ semantic-ranker-default-004. לפרטים על כל אחד מהמודלים, ראו מודלים של Ranking API.
combine.ranker.vertex_ranker.top_n כן המספר המקסימלי של מועמדים מהרשימה הממוזגת שיישלחו למדרג. הערכים התקינים הם בין 1 ל-1000.
combine.ranker.vertex_ranker.text_record_spec.query כן השאילתה בשפה טבעית שמשמשת את המדרג כדי לתת ציון לרשומות.
combine.ranker.vertex_ranker.text_record_spec.title_template כן מחרוזת התבנית, למשל {title}, שמציינת איך לחלץ (ליצור) את הכותרת של כל רשומה. משתמשים בנתיבי נקודות כדי לציין שדות נתונים.
combine.ranker.vertex_ranker.text_record_spec.content_template כן מחרוזת התבנית, לדוגמה {body.text}, שמציינת איך לחלץ (ליצור) את התוכן הראשי של כל רשומה. משתמשים בנתיבי נקודות כדי לציין שדות נתונים.
combine.top_k אופציונלי מספר התוצאות הסופי שיוחזר אחרי הדירוג מחדש. הערך חייב להיות קטן מ-vertex_ranker.top_n או שווה לו, וקטן מ-1,000 או שווה לו.

בדוגמה הבאה מוצג גוף של בקשה.

{
  "searches": [
    { "semantic_search": { "search_text": "running shoes", "search_field": "embedding", "task_type": "RETRIEVAL_QUERY", "top_k": 50 } },
    { "text_search":     { "search_text": "running shoes", "data_field_names": ["title"], "top_k": 50 } }
  ],
  "combine": {
    "top_k": 10,
    "ranker": {
      "rrf": { "weights": [1.0, 1.0] },
      "vertex_ranker": {
        "model": "semantic-ranker-fast@latest",
        "top_n": 50,
        "text_record_spec": {
          "query": "running shoes",
          "title_template": "{title}",
          "content_template": "{body.text}"
        }
      }
    }
  }
}

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

מכסות ותמחור

ב-VertexRanker ב-Agent Retrieval יש מכסה בחינם, וחיוב על חריגה מהמכסה לפי השימוש. כל פרויקט מקבל הקצאה חינמית לשימוש בדירוג בכל תקופה של 30 יום. השימוש במסגרת המכסה הזו הוא ללא עלות. התמחור הרגיל של Ranking API חל על פרויקט הצרכן לכל שימוש מעבר למכסה הזו.

בטבלה הבאה מפורטים ערכי המכסות.

פריט ערך
הקצאה בתוכנית בחינם ‫80,000 יחידות דירוג לכל פרויקט צרכן לתקופה של 30 ימים.
מעבר למכסה החיוב מתבצע לפי התמחור הרגיל של Ranking API בפרויקט הצרכן.
מספר הרשומות המקסימלי לכל קריאה לדירוג מחדש ‫1000 (הערך של top_n חייב להיות בטווח [1, 1000] ו-top_k <= top_n).

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

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

כדי להשתמש ב-VertexRanker, צריך להפעיל את Discovery Engine בפרויקט של הצרכן. מידע נוסף מופיע במאמר תנאי כשל.

טיפול בכשלים ואזהרות

‫VertexRanker הוא מדרג שעושה את המקסימום. אם הקריאה לדירוג נכשלת, ה-RPC של BatchSearchDataObjects עדיין מצליח ומחזיר את התוצאות הממוזגות של ה-RRF, כשהן חתוכות ל-top_k. השגיאה מדווחת בשדה search_response_metadata.warnings בתגובה. קוד הסטטוס המלא מ-Ranking API נשמר. קוד האזהרה לסטטוסים לא צפויים הוא UNAVAILABLE, והודעת האזהרה היא: "Reranking is temporarily unavailable. Returning fused (RRF) results without semantic reranking."

תנאי הכישלון

כל ה-RPC של BatchSearchDataObjects נכשל עם FAILED_PRECONDITION (אין חזרה ל-RRF) במקרים הבאים.

  • ‫Discovery Engine API לא מופעל – ה-Ranking API מחזיר את השגיאה FAILED_PRECONDITION עם ההודעה Discovery Engine API is not enabled for the consumer project /<N/>. Please enable the API and try again.". הפתרון: מפעילים את Discovery Engine API בפרויקט הצרכן.

כדי שהדירוג מחדש יתבצע, הלקוח צריך להפעיל את Discovery Engine בפרויקט הצרכן.

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

קוד אזהרה סיבה אופיינית הודעת אזהרה
RESOURCE_EXHAUSTED חריגה מהמכסה של Ranking API בפרויקט הצרכן. הערה: חריגה מהמכסה של 80,000 יחידות דירוג לא גורמת לאזהרה הזו. במקום זאת, החריגה מחויבת. <Quota exceeded message>; RankService.Rank call failed for consumer project <N> with request query: <query> and <model>: semantic-ranker-fast@latest number of records: <N>
DEADLINE_EXCEEDED הפעולה Ranker.Rank לא הושלמה במסגרת המועד האחרון של הבקשה. <deadline-exceeded message from Ranker.Rank>; RankService.Rank call failed for consumer project <N> with request query: <query> and <model>: semantic-ranker-fast@latest number of records: <N>
UNAVAILABLE או שהפונקציה Ranker.Rank החזירה את הערך UNAVAILABLE, או שהיא החזירה קוד שלא נשמר (לדוגמה, INTERNAL) שהצטמצם לערך UNAVAILABLE. אם הקוד הבסיסי הוא UNAVAILABLE: "RankService.Rank call failed for consumer project...

אחרת: "Reranking is temporarily unavailable. Returning fused (RRF) results without semantic reranking."
FAILED_PRECONDITION כל FAILED_PRECONDITION שמוחזר על ידי ה-Ranking API. RankService.Rank call failed for consumer project <N> with request query: <query> and <model>: semantic-ranker-fast@latest number of records: <N>
CANCELLED המתקשר ביטל את ה-RPC של BatchSearchDataObjects לפני שהדירוג מחדש הסתיים. <cancellation message from the cancelled RankService.Rank RPC>; RankService.Rank call failed for consumer project <N> with request query: <query> and <model>: semantic-ranker-fast@latest number of records: <N>