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 的值會強制轉型為 100。
documentIds[]

string

選用。將搜尋範圍限制在這些文件 ID。最多 100 個。如果留空，系統會搜尋整個 DataStore。
rankingSpec

object (RankingSpec)

選用。控制結果的排序方式。
filter

object (Struct format)

選用。將搜尋範圍限制為符合這項篩選條件的區隔，也就是 DocumentSearchResult 欄位路徑上的 JSON 物件：

  • metadata.<property>：在 DataStore 的 documentMetadataSchema 中宣告的屬性，例如 metadata.category。
  • unstructured_details.page_range.start_page 和 .end_page：適用於 UNSTRUCTURED DataStore。並非每個區段都有頁面範圍，請參閱 UnstructuredSegmentDetails.page_range。
  • video_details.start_offset 和 .end_offset：以秒為單位，適用於 VIDEO DataStore。

比較：$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

混合檢索和倒數排名融合 (RRF) 後，對候選結果套用語意重新排名。

JSON 表示法 
{
  "enabled": boolean,
  "rankOversamplingFactor": integer
}
欄位
enabled

boolean

選用。是否要重新排序融合結果。預設為 false：除非呼叫端選擇加入，否則結果會依 RRF 融合順序傳回。

啟用後，重新排名功能會使用 Vertex Ranking Service 上的 semantic-ranker-fast@latest，且呼叫端專案必須啟用 Discovery Engine API。

不支援 VIDEO DataStore：啟用這項功能的請求會失敗，並傳回 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 中傳回的中繼資料屬性，名稱與 DataStore 的 documentMetadataSchema 中宣告的名稱相同。巢狀屬性會以點分隔路徑命名，例如 address.city，不含 filter 使用的 metadata. 前置字元。"*" 會傳回所有宣告的屬性。未設定則傳回 none。如果文件沒有某個屬性的值，系統會省略該屬性。

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。
區隔在文件中的位置詳細資料。設定哪個欄位取決於父項 DataStore 的 document_type。以下是互斥欄位清單。回應中最多會設定下列其中一個欄位：
videoDetails

object (VideoSegmentDetails)

在父項 DataStore 的 documentType 為 VIDEO 時設定。
unstructuredDetails

object (UnstructuredSegmentDetails)

在父項 DataStore 的 documentType 為 UNSTRUCTURED 時設定。
互斥欄位結束。

VideoSegmentDetails

找出影片文件中的片段。

JSON 表示法 
{
  "startOffset": string,
  "endOffset": string
}
欄位
startOffset

string (Duration format)

僅供輸出。這個片段的起點 (相對於來源影片的起點)。

以秒為單位的時間長度，最多 9 個小數位數，結尾為「s」。例如："3.5s"。
endOffset

string (Duration format)

僅供輸出。這個片段的結束時間 (相對於來源影片的開始時間)。

以秒為單位的時間長度，最多 9 個小數位數，結尾為「s」。例如："3.5s"。

UnstructuredSegmentDetails

找出非結構化文件中的某個區段，並擷取當中的文字。

JSON 表示法 
{
  "contentSnippet": string,
  "pageRange": {
    object (PageRange)
  }
}
欄位
contentSnippet

string

僅供輸出。語音片段的文字內容。
pageRange

object (PageRange)

僅供輸出。語句在來源文件中的位置。適用於 PDF、PowerPoint 和 Excel 檔案，其中一頁是指 PDF 頁面、投影片或工作表。如果是純文字和 Word 檔案，只有在檔案分割成頁面時 (pageSegmentationConfig 搭配數位剖析)，才需要設定這個屬性。頁面會是連續的文字區段，並依序編號。

PageRange

來源文件中的頁碼範圍。頁面從 1 開始，範圍包含指定頁面；單一頁面以 startPage == endPage 表示。

JSON 表示法 
{
  "startPage": string,
  "endPage": string
}
欄位
startPage

string (int64 format)

僅供輸出。範圍的第一頁。
endPage

string (int64 format)

僅供輸出。範圍的最後一頁。