Method: projects.locations.collections.engines.servingConfigs.search

執行搜尋。

HTTP 要求

POST https://discoveryengine.googleapis.com/v1beta/{servingConfig=projects/*/locations/*/collections/*/engines/*/servingConfigs/*}:search

這個網址使用 gRPC 轉碼語法。

路徑參數

參數
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。這個欄位用於識別供應設定名稱，也就是用於進行搜尋的一組模型。

要求主體

要求主體包含下列結構的資料：

JSON 表示法 
{
  "branch": string,
  "query": string,
  "imageQuery": {
    object (ImageQuery)
  },
  "pageSize": integer,
  "pageToken": string,
  "offset": integer,
  "oneBoxPageSize": integer,
  "dataStoreSpecs": [
    {
      object (DataStoreSpec)
    }
  ],
  "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,
  "contentSearchSpec": {
    object (ContentSearchSpec)
  },
  "embeddingSpec": {
    object (EmbeddingSpec)
  },
  "rankingExpression": string,
  "rankingExpressionBackend": enum (RankingExpressionBackend),
  "safeSearch": boolean,
  "userLabels": {
    string: string,
    ...
  },
  "naturalLanguageQueryUnderstandingSpec": {
    object (NaturalLanguageQueryUnderstandingSpec)
  },
  "searchAsYouTypeSpec": {
    object (SearchAsYouTypeSpec)
  },
  "displaySpec": {
    object (DisplaySpec)
  },
  "session": string,
  "sessionSpec": {
    object (SessionSpec)
  },
  "relevanceThreshold": enum (RelevanceThreshold),
  "personalizationSpec": {
    object (PersonalizationSpec)
  },
  "relevanceScoreSpec": {
    object (RelevanceScoreSpec)
  },
  "searchAddonSpec": {
    object (SearchAddonSpec)
  }
}
欄位
branch

string

分支版本的資源名稱，例如 projects/*/locations/global/collections/default_collection/dataStores/default_data_store/branches/0。

使用 default_branch 做為分支 ID，或將這個欄位留空，即可搜尋預設分支下的文件。
query

string

原始搜尋查詢。
imageQuery

object (ImageQuery)

原始圖片查詢。
pageSize

integer

要傳回的 Document 數量上限。允許的最大值取決於資料類型。如果值超過上限，系統會強制設為上限值。

  • 基本索引網站：預設 10、最多 25。
  • 進階索引網站：預設 25、最多 50。
  • 其他：預設 50、最大 100。

如果這個欄位為負數，系統會傳回 INVALID_ARGUMENT。
pageToken

string

接收自前一個 SearchService.Search 呼叫的網頁權杖。提供此項目即可擷取後續網頁。

進行分頁時，提供至 SearchService.Search 的所有其他參數須與提供網頁權杖的呼叫相符。否則，系統會傳回 INVALID_ARGUMENT 錯誤。
offset

integer

以 0 為索引的整數，用來指定搜尋結果中目前的偏移量 (也就是 API 視為相關的Document中的起始結果位置)。只有在未設定 pageToken 時，才會考慮使用此欄位。

如果這個欄位為負數，系統會傳回 INVALID_ARGUMENT。

如果偏移量過大，系統可能會將其限制在合理範圍內。
oneBoxPageSize

integer

OneBox 傳回的結果數上限。這項規定適用於各個 OneBox 類型。預設值為 10。
dataStoreSpecs[]

object (DataStoreSpec)

定義要搜尋的特定 DataStore，以及這些資料儲存區的設定。只有在Engine有多個資料儲存庫時，系統才會考量這項因素。如果引擎只有一個資料存放區，請使用 SearchRequest 下方的規格。
filter

string

篩選器語法包含運算式語言，可從要篩選的文件的一或多個欄位建構述詞。篩選運算式會區分大小寫。

如果無法辨識這個欄位，系統會傳回 INVALID_ARGUMENT。

在 Vertex AI servingConfigs.search 中進行篩選時，系統會將 LHS 篩選鍵對應至 Vertex AI servingConfigs.search 後端定義的鍵屬性，而這項對應是由客戶在結構定義中定義。舉例來說，媒體客戶的結構定義中可能會有「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)

多面向搜尋的 facet 規格。如果留空，就不會傳回任何構面。

最多可輸入 100 個值。否則，系統會傳回 INVALID_ARGUMENT 錯誤。
boostSpec

object (BoostSpec)

提高特定文件的規格。如要進一步瞭解加成，請參閱「加成」一文。
params

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

其他搜尋參數。

僅限公開網站搜尋，支援的值如下：

  • user_country_code：字串。預設為空白。如果設為非空白，系統會根據提供的地點限制或提升結果。例如：user_country_code: "au"

如要查看可用代碼，請參閱「國家/地區代碼」。

  • searchType：雙精度浮點數。預設為空白。視值而定，啟用非網頁搜尋功能。唯一有效的非預設值為 1，可啟用圖片搜尋功能。例如：searchType: 1
queryExpansionSpec

object (QueryExpansionSpec)

查詢擴充規格，指定查詢擴充的發生條件。
spellCorrectionSpec

object (SpellCorrectionSpec)

拼字校正規格，指定拼字校正生效的模式。
userPseudoId

string

用於追蹤訪客的專屬 ID。舉例來說，這項功能可以透過 HTTP Cookie 實作，應能識別單一裝置上的訪客。訪客登入或登出網站時，這個專屬 ID 不應變更。

這個欄位「不得」有固定值，例如 unknown_visitor。

這個 ID 應與 UserEvent.user_pseudo_id 和 CompleteQueryRequest.user_pseudo_id 相同

這個欄位必須是 UTF-8 編碼的字串，長度上限為 128 個字元。否則，系統會傳回 INVALID_ARGUMENT 錯誤。
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)：如果信號為 NaN，則傳回 0，否則傳回 1。
  • fillNan(signal1, signal2 | double) - 如果 signal1 為 NaN，則傳回 signal2 | double，否則傳回 signal1。

以下列舉幾個使用支援的排名運算式類型的排名公式：

  • 0.2 * semanticSimilarityScore + 0.8 * log(keywordSimilarityScore) -- mostly rank by the logarithm of with slight adjustment.keywordSimilarityScoresemantic_smilarity_score
  • 0.2 * exp(fillNan(semanticSimilarityScore, 0)) + 0.3 * isNan(keywordSimilarityScore) - 依 semanticSimilarityScore 的指數排序，如果值為 NaN，則填入 0，如果 semanticSimilarityScore 為 NaN，則在最終分數中加入常數 0.3 的調整值。
  • 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) 可從使用者角度評估搜尋結果的關聯性和吸引力。預估點擊率越高，表示結果越有可能滿足使用者的查詢和意圖，因此是排名時的重要信號。
  • freshnessRank：以排名形式呈現的新鮮度調整
  • documentAge：文件上次更新後經過的小時數，以浮點數表示 (例如 0.25 代表 15 分鐘)。
  • topicalityRank：主題性調整值 (以排名形式呈現)。使用 Google 專屬模型判斷查詢和文件之間基於關鍵字的重疊程度。
  • baseRank：結果的預設排名
rankingExpressionBackend

enum (RankingExpressionBackend)

(選用步驟) 用於排名運算式評估的後端。
userLabels

map (key: string, value: string)

套用於資源的使用者標籤必須符合下列規定：

  • 每項資源可以有多個標籤，上限為 64 個。
  • 每個標籤都必須是鍵/值組合。
  • 鍵的長度必須至少為 1 個字元，最多 63 個字元，且不能空白。值可以空白，長度上限為 63 個字元。
  • 鍵和值只能使用小寫字母、數字字元、底線和連字號。所有字元都必須使用 UTF-8 編碼，且可使用國際字元。
  • 標籤中的鍵部分不得重複，但可讓多個資源使用相同的鍵。
  • 鍵的開頭必須是小寫字母或國際字元。

詳情請參閱 Google Cloud 文件。
naturalLanguageQueryUnderstandingSpec

object (NaturalLanguageQueryUnderstandingSpec)

(選用步驟) 自然語言查詢理解功能設定，例如從查詢中擷取結構化欄位篩選器。詳情請參閱這份說明文件。如果未指定 naturalLanguageQueryUnderstandingSpec，系統就不會進行額外的自然語言查詢理解作業。
searchAsYouTypeSpec

object (SearchAsYouTypeSpec)

servingConfigs.search 即時搜尋設定。僅支援 IndustryVertical.MEDIA 垂直。
displaySpec

object (DisplaySpec)

(選用步驟) 設定顯示功能，例如在搜尋結果中醒目顯示相符項目。
session

string

工作階段資源名稱。選填。

使用者可透過工作階段執行多輪 /search API 呼叫，或協調 /search API 呼叫和 /answer API 呼叫。

範例 1 (多輪 /search API 呼叫)：使用在第一次呼叫中產生的工作階段 ID 呼叫 /search API。系統會將先前的搜尋查詢納入查詢狀態考量。也就是說，如果第一個查詢是「Alphabet 在 2022 年的表現如何？」，而目前的查詢是「2023 年的表現如何？」，系統會將目前的查詢解讀為「Alphabet 在 2023 年的表現如何？」。

範例 2 (在 /search API 呼叫和 /answer API 呼叫之間協調)：使用第一次呼叫中產生的工作階段 ID 呼叫 /answer API。在這裡，答案生成作業會在第一次搜尋呼叫的搜尋結果脈絡中進行。

Multi-turn servingConfigs.search 功能目前處於私人正式發布階段。在公開發布這項功能前，請改用 v1alpha 或 v1beta 版。您也可以透過 Google 支援團隊申請加入允許清單。
sessionSpec

object (SessionSpec)

工作階段規格。

只有在設定 session 時才能使用。
relevanceThreshold

enum (RelevanceThreshold)

搜尋結果的關聯性門檻。

預設為 Google 定義的門檻，可兼顧準確度和召回率，提供高度準確的結果，並全面涵蓋相關資訊。

這項功能不支援醫療保健搜尋。
personalizationSpec

object (PersonalizationSpec)

個人化規格。

請注意，如果同時設定 ServingConfig.personalization_spec 和 SearchRequest.personalization_spec，SearchRequest.personalization_spec 會覆寫 ServingConfig.personalization_spec。
relevanceScoreSpec

object (RelevanceScoreSpec)

(選用步驟) 傳回關聯性分數的規格。
searchAddonSpec

object (SearchAddonSpec)

(選用步驟) 根據新的重新定價模式，SearchAddonSpec 用於停用搜尋的外掛程式。這個欄位僅支援搜尋要求。

回應主體

如果成功，回應主體會包含 SearchResponse 的執行個體。

授權範圍

需要下列其中一種 OAuth 範圍：

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/discoveryengine.readwrite
  • https://www.googleapis.com/auth/discoveryengine.assist.readwrite

詳情請參閱Authentication Overview。

IAM 權限

需要 servingConfig 資源的下列 IAM 權限：

  • discoveryengine.servingConfigs.search

詳情請參閱 IAM 說明文件。