SearchRequest

הודעת בקשה לשיטה SearchService.Search.

ייצוג ב-JSON 
{
  "servingConfig": string,
  "branch": string,
  "query": string,
  "pageCategories": [
    string
  ],
  "imageQuery": {
    object (ImageQuery)
  },
  "pageSize": integer,
  "pageToken": string,
  "offset": integer,
  "oneBoxPageSize": integer,
  "dataStoreSpecs": [
    {
      object (DataStoreSpec)
    }
  ],
  "numResultsPerDataStore": integer,
  "filter": string,
  "canonicalFilter": string,
  "orderBy": string,
  "userInfo": {
    object (UserInfo)
  },
  "languageCode": string,
  "regionCode": string,
  "facetSpecs": [
    {
      object (FacetSpec)
    }
  ],
  "boostSpec": {
    object (BoostSpec)
  },
  "params": {
    string: value,
    ...
  },
  "queryExpansionSpec": {
    object (QueryExpansionSpec)
  },
  "spellCorrectionSpec": {
    object (SpellCorrectionSpec)
  },
  "userPseudoId": string,
  "useLatestData": boolean,
  "contentSearchSpec": {
    object (ContentSearchSpec)
  },
  "embeddingSpec": {
    object (EmbeddingSpec)
  },
  "rankingExpression": string,
  "rankingExpressionBackend": enum (RankingExpressionBackend),
  "safeSearch": boolean,
  "userLabels": {
    string: string,
    ...
  },
  "naturalLanguageQueryUnderstandingSpec": {
    object (NaturalLanguageQueryUnderstandingSpec)
  },
  "searchAsYouTypeSpec": {
    object (SearchAsYouTypeSpec)
  },
  "customFineTuningSpec": {
    object (CustomFineTuningSpec)
  },
  "displaySpec": {
    object (DisplaySpec)
  },
  "crowdingSpecs": [
    {
      object (CrowdingSpec)
    }
  ],
  "session": string,
  "sessionSpec": {
    object (SessionSpec)
  },
  "relevanceThreshold": enum (RelevanceThreshold),
  "relevanceFilterSpec": {
    object (RelevanceFilterSpec)
  },
  "personalizationSpec": {
    object (PersonalizationSpec)
  },
  "relevanceScoreSpec": {
    object (RelevanceScoreSpec)
  },
  "searchAddonSpec": {
    object (SearchAddonSpec)
  }
}
שדות
servingConfig

string

חובה. שם המשאב של הגדרת הצגת התוצאות בחיפוש, כמו projects/*/locations/global/collections/default_collection/engines/*/servingConfigs/default_serving_config או projects/*/locations/global/collections/default_collection/dataStores/default_data_store/servingConfigs/default_serving_config. השדה הזה משמש לזיהוי השם של הגדרת ההצגה, קבוצת המודלים שמשמשים לביצוע החיפוש.
branch

string

שם המשאב של הענף, למשל projects/*/locations/global/collections/default_collection/dataStores/default_data_store/branches/0.

כדי לחפש מסמכים בענף ברירת המחדל, משתמשים ב-default_branch כמזהה הענף או משאירים את השדה הזה ריק.
query

string

שאילתת חיפוש גולמית.
pageCategories[]

string

זה שינוי אופציונלי. הקטגוריות שמשויכות לדף קטגוריה. כדי להשיג איכות חיפוש טובה, צריך להגדיר את הפרמטר הזה לשאילתות ניווט בקטגוריות. הפורמט צריך להיות זהה לפורמט PageInfo.page_category. השדה הזה מקביל לשאילתה של שאילתות גלישה (ניווט). הוא משמש את מודל הגלישה כשהשאילתה ריקה.

אם השדה ריק, המודל לא ישתמש בו. אם השדה מכיל יותר מרכיב אחד, המערכת תשתמש רק ברכיב הראשון.

כדי לייצג נתיב מלא של קטגוריה, משתמשים בתו '>' כדי להפריד בין היררכיות שונות. אם התו '>' הוא חלק משם הקטגוריה, צריך להחליף אותו בתווים אחרים. לדוגמה, Graphics Cards > RTX>4090 > Founders Edition כאשר 'RTX > 4090' מייצג רמה אחת, אפשר לכתוב מחדש כ-Graphics Cards > RTX_4090 > Founders Edition
imageQuery

object (ImageQuery)

שאילתה של תמונה בפורמט Raw.
pageSize

integer

המספר המקסימלי של Documents שיוחזרו. הערך המקסימלי המותר תלוי בסוג הנתונים. ערכים שגבוהים מהערך המקסימלי נכפים להיות הערך המקסימלי.

  • אתרים עם אינדוקס בסיסי: ברירת מחדל 10, מקסימום 25.
  • אתרים עם הוספה מתקדמת לאינדקס: ברירת מחדל 25, מקסימום 50.
  • אחר: ברירת מחדל 50, מקסימום 100.

אם השדה הזה שלילי, הפונקציה מחזירה INVALID_ARGUMENT.
pageToken

string

טוקן של דף שהתקבל מקריאה קודמת של SearchService.Search. צריך להזין את הטוקן כדי לאחזר את הדף הבא.

כשמבצעים חלוקה לעמודים, כל הפרמטרים האחרים שסופקו ל-SearchService.Search חייבים להיות זהים לקריאה שסיפקה את הטוקן של הדף. אחרת, תוחזר שגיאת INVALID_ARGUMENT.
offset

integer

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

אם השדה הזה שלילי, הפונקציה מחזירה INVALID_ARGUMENT.

יכול להיות שערך אופסט גדול יוגבל לסף סביר.
oneBoxPageSize

integer

המספר המקסימלי של תוצאות שיוחזרו ל-OneBox. ההגבלה הזו חלה על כל סוג של OneBox בנפרד. מספר ברירת המחדל הוא 10.
dataStoreSpecs[]

object (DataStoreSpec)

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

integer

זה שינוי אופציונלי. המספר המקסימלי של תוצאות לאחזור מכל מאגר נתונים. אם לא מציינים ערך, המערכת משתמשת בערך SearchRequest.DataStoreSpec.num_results אם הוא מסופק, אחרת אין מגבלה.
filter

string

תחביר המסנן מורכב משפת ביטויים לבניית פרדיקט משדה אחד או יותר של המסמכים שמסננים. ביטוי המסנן תלוי אותיות רישיות (case-sensitive).

אם השדה לא מזוהה, מוחזר INVALID_ARGUMENT.

סינון ב-חיפוש מבוסס-Vertex AI מתבצע על ידי מיפוי של מפתח הסינון בצד ימין למאפיין מפתח שמוגדר בבק-אנד של חיפוש מבוסס-Vertex AI. הלקוח מגדיר את המיפוי הזה בסכימה שלו. לדוגמה, ללקוח בתחום המדיה יכול להיות שדה בשם 'name' בסכימה שלו. במקרה הזה, המסנן ייראה כך: filter --> name:'ANY("king kong")'

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

string

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

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

מידע נוסף על תחביר המסננים זמין במאמר SearchRequest.filter.
orderBy

string

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

מידע נוסף על סידור תוצאות החיפוש באתר זמין במאמר סידור תוצאות החיפוש באינטרנט. למידע נוסף על סידור תוצאות החיפוש של שירותי בריאות, אפשר לעיין במאמר סידור תוצאות החיפוש של שירותי בריאות. אם השדה לא מזוהה, מוחזר INVALID_ARGUMENT.
userInfo

object (UserInfo)

מידע על משתמש הקצה. מומלץ מאוד לניתוח נתונים ולהתאמה אישית. ‫UserInfo.user_agent משמש להסקת deviceType לצורך ניתוח נתונים.
languageCode

string

קוד השפה בפורמט BCP-47, כמו en-US או sr-Latn. מידע נוסף מופיע במאמר בנושא שדות רגילים. השדה הזה עוזר לפרש טוב יותר את השאילתה. אם לא מציינים ערך, קוד שפת השאילתה מזוהה באופן אוטומטי, אבל יכול להיות שהזיהוי לא יהיה מדויק.
regionCode

string

קוד המדינה/האזור של Unicode‏ (CLDR) של מיקום, כמו US ו-419. מידע נוסף מופיע במאמר בנושא שדות רגילים. אם הערך מוגדר, התוצאות יקבלו דחיפה על סמך הערך של regionCode שסופק.
facetSpecs[]

object (FacetSpec)

מפרטים של היבטים לחיפוש עם היבטים. אם הוא ריק, לא מוחזרים היבטים.

אפשר להזין עד 100 ערכים. אחרת, מוחזרת שגיאת INVALID_ARGUMENT.
boostSpec

object (BoostSpec)

הגדרת חיזוק כדי להדגיש מסמכים מסוימים. מידע נוסף על קידום תוכן זמין במאמר בנושא קידום תוכן
params

map (key: string, value: value (Value format))

פרמטרים נוספים לחיפוש.

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

  • ‫user_country_code: מחרוזת. ברירת המחדל היא ריק. אם המדיניות מוגדרת כלא ריקה, התוצאות מוגבלות או מקודמות על סמך המיקום שצוין. לדוגמה, user_country_code: "au".

רשימת הקודים הזמינים מופיעה במאמר קודי מדינות

  • ‫searchType: double. ברירת המחדל היא ריק. ההגדרה מאפשרת חיפוש שלא בדפי אינטרנט, בהתאם לערך. הערך החוקי היחיד שאינו ברירת המחדל הוא 1, שמפעיל חיפוש תמונות. לדוגמה, searchType: 1.
queryExpansionSpec

object (QueryExpansionSpec)

מפרט הרחבת השאילתה שמציין את התנאים שבהם מתבצעת הרחבת השאילתה.
spellCorrectionSpec

object (SpellCorrectionSpec)

המפרט של תיקון האיות שמציין את המצב שבו תיקון האיות נכנס לתוקף.
userPseudoId

string

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

בשדה הזה לא צריך להזין ערך קבוע כמו unknown_visitor.

המזהה הזה צריך להיות זהה למזהה UserEvent.user_pseudo_id ולמזהה CompleteQueryRequest.user_pseudo_id

השדה חייב להיות מחרוזת בקידוד UTF-8, עם מגבלת אורך של 128 תווים. אחרת, מוחזרת שגיאת INVALID_ARGUMENT.
useLatestData

boolean

משתמש ב-Engine, ב-ServingConfig וב-Control שנקראו מהמסד הנתונים.

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

object (ContentSearchSpec)

מפרט להגדרת אופן הפעולה של חיפוש התוכן.
embeddingSpec

object (EmbeddingSpec)

משתמש בהטמעה שסופקה כדי לבצע אחזור סמנטי נוסף של מסמכים. האחזור מבוסס על המכפלה הסקלרית של SearchRequest.EmbeddingSpec.EmbeddingVector.vector ושל הטמעת המסמך שמופיעה ב-SearchRequest.EmbeddingSpec.EmbeddingVector.field_path.

אם לא מציינים את SearchRequest.EmbeddingSpec.EmbeddingVector.field_path, המערכת משתמשת ב-ServingConfig.EmbeddingConfig.field_path.
rankingExpression

string

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

אם לא מציינים את rankingExpressionBackend או אם הוא מוגדר לערך RANK_BY_EMBEDDING, צריך לציין פונקציה אחת או כמה פונקציות שמחוברות באמצעות '+'.

  • rankingExpression = function, { " + ", function };

פונקציות נתמכות:

  • ‫double * relevanceScore
  • ‫double * dotProduct(embedding_field_path)

משתני פונקציה:

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

ביטוי הדירוג לדוגמה:

אם במסמך יש שדה הטמעה doc_embedding, ביטוי הדירוג יכול להיות 0.5 * relevanceScore + 0.3 * dotProduct(doc_embedding).

אם הערך של rankingExpressionBackend הוא RANK_BY_FORMULA, המערכת תומכת בסוגי הביטויים הבאים (ובשילובים שלהם, שמשורשרים באמצעות האופרטורים + או *):

  • double
  • signal
  • log(signal)
  • exp(signal)
  • ‫rr(signal, double > 0) -- reciprocal rank transformation with second argument being a denominator constant.
  • ‫isNan(signal) -- מחזירה 0 אם האות הוא NaN, אחרת מחזירה 1.
  • ‫fillNan(signal1, signal2 | double) -- if signal1 is NaN, returns signal2 | double, else returns signal1.

ריכזנו כאן כמה דוגמאות לנוסחאות דירוג שמשתמשות בסוגי הביטויים הנתמכים לדירוג:

  • ‫0.2 * semanticSimilarityScore + 0.8 * log(keywordSimilarityScore) – הדירוג מתבסס בעיקר על הלוגריתם של keywordSimilarityScore עם התאמה קלה של semantic_smilarity_score.
  • ‫0.2 * exp(fillNan(semanticSimilarityScore, 0)) + 0.3 * isNan(keywordSimilarityScore) -- rank by the exponent of semanticSimilarityScore filling the value with 0 if it's NaN, also add constant 0.3 adjustment to the final score if semanticSimilarityScore is NaN.
  • ‫0.2 * rr(semanticSimilarityScore, 16) + 0.8 * rr(keywordSimilarityScore, 16) -- בעיקר דירוג לפי הדירוג ההופכי של keywordSimilarityScore עם התאמה קלה של הדירוג ההופכי של semantic_smilarity_score.

יש תמיכה באותות הבאים:

  • ‫semanticSimilarityScore: התאמה של דמיון סמנטי שמחושבת באמצעות ההטמעות שנוצרו על ידי מודל קנייני של Google. הציון הזה קובע עד כמה שאילתת חיפוש דומה מבחינה סמנטית למסמך.
  • ‫keywordSimilarityScore: ההתאמה של מילות המפתח מתבססת על פונקציית הדירוג Best Match 25 (BM25). הציון הזה מחושב באמצעות מודל הסתברותי כדי להעריך את ההסתברות שמסמך רלוונטי לשאילתה מסוימת.
  • ‫relevanceScore: התאמה של הרלוונטיות הסמנטית באמצעות מודל קנייני של Google, כדי לקבוע את המשמעות והכוונה שמאחורי שאילתת משתמש בהקשר של התוכן במסמכים.
  • ‫pctrRank: התאמה של שיעור ההמרה החזוי כשימוש בדירוג. שיעור הקליקים החזוי (pCTR) משמש להערכת הרלוונטיות והאטרקטיביות של תוצאת חיפוש מנקודת המבט של המשתמש. שיעור גבוה יותר של pCTR מצביע על כך שהתוצאה עשויה לספק את השאילתה ואת כוונת המשתמש, ולכן זהו אות חשוב לדירוג.
  • ‫freshnessRank: התאמת העדכניות כדרגה
  • ‫documentAge: הזמן בשעות שחלף מאז העדכון האחרון של המסמך, מספר נקודה צפה (לדוגמה, ‫0.25 מייצג 15 דקות).
  • ‫topicalityRank: התאמה לנושא כציון. המערכת משתמשת במודל קנייני של Google כדי לקבוע את החפיפה בין השאילתה לבין המסמך על סמך מילות המפתח.
  • ‫baseRank: הדירוג שמוגדר כברירת מחדל של התוצאה
rankingExpressionBackend

enum (RankingExpressionBackend)

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

map (key: string, value: string)

התוויות של המשתמש שמוחלות על משאב צריכות לעמוד בדרישות הבאות:

  • אפשר להוסיף לכל משאב כמה תוויות, עד 64 לכל היותר.
  • כל תווית צריכה להיות צמד מפתח/ערך.
  • האורך המינימלי של המפתחות הוא תו אחד, והאורך המקסימלי הוא 63 תווים. המפתחות לא יכולים להיות ריקים. הערכים יכולים להיות ריקים, והאורך המקסימלי שלהם הוא 63 תווים.
  • המפתחות והערכים יכולים להכיל רק אותיות קטנות, ספרות, קווים תחתונים ומקפים. כל התווים צריכים להיות בקידוד UTF-8, ומותר להשתמש בתווים בינלאומיים.
  • החלק של המפתח בתווית חייב להיות ייחודי. עם זאת, אפשר להשתמש באותו מפתח עם כמה משאבים.
  • המפתחות צריכים להתחיל באות קטנה או בתו בינלאומי.

פרטים נוספים מופיעים במאמר מסמך Google Cloud.
naturalLanguageQueryUnderstandingSpec

object (NaturalLanguageQueryUnderstandingSpec)

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

object (SearchAsYouTypeSpec)

הגדרה של חיפוש בזמן ההקלדה. התכונה הזו נתמכת רק בקטגוריה IndustryVertical.MEDIA.
customFineTuningSpec

object (CustomFineTuningSpec)

הגדרות בהתאמה אישית של כוונון עדין. אם ההגדרה הזו מוגדרת, היא מקבלת עדיפות גבוהה יותר מההגדרות שמוגדרות ב-ServingConfig.custom_fine_tuning_spec.
displaySpec

object (DisplaySpec)

זה שינוי אופציונלי. הגדרות לתכונות תצוגה, כמו הדגשת התאמות בתוצאות החיפוש.
crowdingSpecs[]

object (CrowdingSpec)

זה שינוי אופציונלי. הגדרות צפיפות לשיפור מגוון התוצאות. אם מציינים כמה CrowdingSpecs, הצפיפות תיבדק בכל שילוב ייחודי של ערכי field, והערך של maxCount יהיה הערך המקסימלי של maxCount בכל ה-CrowdingSpecs. לדוגמה, אם ב-CrowdingSpec הראשון הערך של field הוא color והערך של maxCount הוא 3, וב-CrowdingSpec השני הערך של field הוא size והערך של maxCount הוא 2, אז אחרי שיוחזרו 3 מסמכים עם אותו צבע ואותה מידה, המסמכים הבאים צריכים להיות מוסרים או להופיע במקום נמוך יותר.
session

string

שם המשאב של הסשן. זה שינוי אופציונלי.

הסשן מאפשר למשתמשים לבצע קריאות ל-API של חיפוש מרובה או תיאום בין קריאות ל-API של חיפוש וקריאות ל-API של תשובה.

דוגמה מספר 1 (קריאות ל-API של חיפוש מרובות): שליחת קריאה ל-API של חיפוש עם מזהה הסשן שנוצר בקריאה הראשונה. כאן, שאילתת החיפוש הקודמת נלקחת בחשבון בסטטוס השאילתה. כלומר, אם השאילתה הראשונה היא "How did Alphabet do in 2022?‎" (מה היו הביצועים של אלפבית בשנת 2022?) והשאילתה הנוכחית היא "מה לגבי 2023?", השאילתה הנוכחית תפורש כ "מה היו הביצועים של Alphabet בשנת 2023?".

דוגמה מספר 2 (תיאום בין קריאות ל-API של /search וקריאות ל-API של /answer): קריאה ל-API של /answer עם מזהה הסשן שנוצר בקריאה הראשונה. במקרה הזה, יצירת התשובה מתבצעת בהקשר של תוצאות החיפוש מהקריאה הראשונה לחיפוש.
sessionSpec

object (SessionSpec)

מפרט הסשן.

אפשר להשתמש בו רק אם מוגדר session.
relevanceThreshold

enum (RelevanceThreshold)

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

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

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

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

object (RelevanceFilterSpec)

זה שינוי אופציונלי. המפרט של סינון רלוונטיות גרנולרי.

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

התכונה הזו נתמכת כרגע רק בחיפוש מותאם אישית ובחיפוש באתר.
personalizationSpec

object (PersonalizationSpec)

המפרט להתאמה אישית.

שימו לב: אם גם ServingConfig.personalization_spec וגם SearchRequest.personalization_spec מוגדרים, SearchRequest.personalization_spec מבטל את ServingConfig.personalization_spec.
relevanceScoreSpec

object (RelevanceScoreSpec)

זה שינוי אופציונלי. ההגדרה להחזרת ציון הרלוונטיות.
searchAddonSpec

object (SearchAddonSpec)

זה שינוי אופציונלי. ה-SearchAddonSpec משמש להשבתת תוספים לחיפוש בהתאם למודל החדש של תמחור מחדש. השדה הזה נתמך רק בבקשות חיפוש.