Method: projects.locations.dataStores.documents.search

חיפוש במסמכים של מאגר נתונים אחד.

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

בקשת HTTP

POST https://vectorsearch.googleapis.com/v1beta/{parent}/documents:search

פרמטרים של הנתיב

פרמטרים
parent

string

חובה. ה-DataStore שבו רוצים לחפש. פורמט: projects/{project}/locations/{location}/dataStores/{dataStore}

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג ב-JSON
{
  "topK": integer,
  "documentIds": [
    string
  ],
  "rankingSpec": {
    object (RankingSpec)
  },
  "filter": {
    object
  },
  "outputFields": {
    object (OutputFields)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "textQuery": {
    object (TextQuery)
  }
  // End of mutually exclusive fields.
}
שדות
topK

integer

זה שינוי אופציונלי. מספר התוצאות שיוצגו. ברירת המחדל היא 10. ערכים גבוהים יותר יומרו ל-100.

documentIds[]

string

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

rankingSpec

object (RankingSpec)

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

filter

object (Struct format)

זה שינוי אופציונלי. החיפוש מוגבל לפלחים שתואמים למסנן הזה, אובייקט JSON בנתיבי השדות של DocumentSearchResult:

  • ‫metadata.<property>: מאפיין שהוצהר ב-documentMetadataSchema של מאגר הנתונים, למשל metadata.category.
  • ‫unstructured_details.page_range.start_page ו-.end_page: ל-DataStore של UNSTRUCTURED. לא לכל קטע יש טווח דפים. אפשר לעיין בUnstructuredSegmentDetails.page_range.
  • ‫video_details.start_offset ו-.end_offset: בשניות, ל-DataStore של VIDEO.

השוואות: $eq, ‏$ne, ‏$lt, ‏$lte, ‏$gt, ‏$gte, ‏$in, ‏$nin, ‏$all ו-$exists. לשלב אותם עם $and, $or ו-$not, עם הטמעה של עד שתי רמות. לדוגמה:

{"$and": [{"metadata.year": {"$gte": 2025}}, {"unstructured_details.page_range.start_page": {"$lte": 20}}]}

outputFields

object (OutputFields)

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

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

object (TextQuery)

שאילתת טקסט.

סוף השדות שמוציאים זה את זה.

גוף התשובה

הודעת התשובה של DocumentSearchService.SearchDocuments.

אם הפעולה מצליחה, גוף התשובה מכיל נתונים במבנה הבא:

ייצוג ב-JSON
{
  "results": [
    {
      object (DocumentSearchResult)
    }
  ],
  "warnings": [
    {
      object (Status)
    }
  ]
}
שדות
results[]

object (DocumentSearchResult)

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

warnings[]

object (Status)

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

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/vectorsearch
  • https://www.googleapis.com/auth/vectorsearch.readonly

ניתן למצוא מידע נוסף כאן: Authentication Overview.

TextQuery

שאילתת טקסט.

ייצוג ב-JSON
{
  "text": string
}
שדות
text

string

חובה. הטקסט שאותו מחפשים.

RankingSpec

קובע את דירוג התוצאות.

ייצוג ב-JSON
{
  "rerankingSpec": {
    object (RerankingSpec)
  }
}
שדות
rerankingSpec

object (RerankingSpec)

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

RerankingSpec

הגדרת הדירוג הסמנטי החוזר שמוחל על תוצאות מועמדות אחרי אחזור היברידי ו-Reciprocal Rank Fusion ‏(RRF).

ייצוג ב-JSON
{
  "enabled": boolean,
  "rankOversamplingFactor": integer
}
שדות
enabled

boolean

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

כשהאפשרות הזו מופעלת, הדירוג מחדש משתמש ב-semantic-ranker-fast@latest ב-Vertex Ranking Service, וצריך להפעיל את Discovery Engine API בפרויקט של מבצע הקריאה החוזרת.

אין תמיכה ב-DataStore מסוג VIDEO: בקשה שמפעילה אותו נכשלת עם INVALID_ARGUMENT.

rankOversamplingFactor

integer

זה שינוי אופציונלי. הגורם שלפיו מתבצעת דגימת יתר של המועמדים לפני הדירוג מחדש. המספר הכולל של המועמדים שאוחזרו לדירוג מחדש הוא min(rankOversamplingFactor * topK, 200). אחרי הדירוג מחדש, התוצאות מצטמצמות ל-SearchDocumentsRequest.top_k.

המערכת מתעלמת מהמאפיין הזה, אלא אם הערך של enabled הוא true. כשהאפשרות מופעלת, ברירת המחדל היא 5 (אחזור של min(5 * topK, 200) מועמדים, עד 200).

כדי לדרג מחדש בלי דגימת יתר, מגדירים את השדה הזה ל-1.

OutputFields

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

ייצוג ב-JSON
{
  "metadata": [
    string
  ]
}
שדות
metadata[]

string

זה שינוי אופציונלי. מאפייני מטא-נתונים שיוחזרו ב-DocumentSearchResult.document.metadata, עם השמות שהוגדרו ב-documentMetadataSchema של מאגר הנתונים. מאפיין בתצוגת עץ נקרא לפי הנתיב שלו עם נקודות, למשל address.city, בלי הקידומת metadata. שבה משתמשים ב-filter. הפונקציה "*" מחזירה כל נכס שהוצהר. אם לא מגדירים את המאפיין, לא מוחזר ערך. מאפיין שלמסמך אין ערך בשבילו מושמט.

DocumentSearchResult

קטע תואם אחד במסמך.

ייצוג ב-JSON
{
  "document": {
    object (Document)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "videoDetails": {
    object (VideoSegmentDetails)
  },
  "unstructuredDetails": {
    object (UnstructuredSegmentDetails)
  }
  // End of mutually exclusive fields.
}
שדות
document

object (Document)

פלט בלבד. המסמך שממנו הגיע הפלח, כולל שם המשאב והמיקום ב-Cloud Storage שממנו הוא הועבר.

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

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

object (VideoSegmentDetails)

מוגדר כאשר documentType של מאגר הנתונים הראשי הוא VIDEO.

unstructuredDetails

object (UnstructuredSegmentDetails)

מוגדר כאשר documentType של מאגר הנתונים הראשי הוא UNSTRUCTURED.

סוף השדות שמוציאים זה את זה.

VideoSegmentDetails

מאתר קטע במסמך וידאו.

ייצוג ב-JSON
{
  "startOffset": string,
  "endOffset": string
}
שדות
startOffset

string (Duration format)

פלט בלבד. איפה הקטע הזה מתחיל, ביחס לתחילת סרטון המקור.

משך זמן בשניות עם עד תשע ספרות אחרי הנקודה העשרונית, שמסתיים ב-"s". לדוגמה: "3.5s".

endOffset

string (Duration format)

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

משך זמן בשניות עם עד תשע ספרות אחרי הנקודה העשרונית, שמסתיים ב-"s". לדוגמה: "3.5s".

UnstructuredSegmentDetails

מאתר קטע במסמך לא מובנה ומעביר את הטקסט שלו.

ייצוג ב-JSON
{
  "contentSnippet": string,
  "pageRange": {
    object (PageRange)
  }
}
שדות
contentSnippet

string

פלט בלבד. תוכן הטקסט של הקטע.

pageRange

object (PageRange)

פלט בלבד. המיקום של הקטע במסמך המקור. ההגדרה הזו מיועדת לקובצי PDF, ‏ PowerPoint ו-Excel, שבהם דף הוא דף PDF, שקף או גיליון. בקובצי HTML, טקסט פשוט, Markdown, ‏ JSON, ‏ XML ו-Word, צריך להגדיר את זה רק כשהקובץ מפוצל לדפים (pageSegmentationConfig עם ניתוח דיגיטלי). הדפים הם קטעים עוקבים של הטקסט, שממוספרים לפי הסדר.

PageRange

טווח דפים במסמך המקור. הדפים מבוססים על 1 והטווח כולל. דף בודד מיוצג בתור startPage == endPage.

ייצוג ב-JSON
{
  "startPage": string,
  "endPage": string
}
שדות
startPage

string (int64 format)

פלט בלבד. הדף הראשון בטווח.

endPage

string (int64 format)

פלט בלבד. הדף האחרון בטווח.