REST Resource: projects.locations.evaluations

資源：Evaluation

評估是指評估程序的單次執行作業 (或執行)。其中封裝了評估狀態和產生的資料。

JSON 表示法 
{
  "name": string,
  "evaluationSpec": {
    object (EvaluationSpec)
  },
  "qualityMetrics": {
    object (QualityMetrics)
  },
  "state": enum (State),
  "error": {
    object (Status)
  },
  "createTime": string,
  "endTime": string,
  "errorSamples": [
    {
      object (Status)
    }
  ]
}
欄位
name

string

ID。Evaluation 的完整資源名稱，格式為 projects/{project}/locations/{location}/evaluations/{evaluation}。

這個欄位必須是 UTF-8 編碼的字串，長度上限為 1024 個字元。
evaluationSpec

object (EvaluationSpec)

這是必要旗標，評估規格。
qualityMetrics

object (QualityMetrics)

僅供輸出。評估作業產生的指標，是 SampleQuerySet 中所有 SampleQuery 的平均值。

只有在評估狀態為「SUCCEEDED」時才會填入資料。
state

enum (State)

僅供輸出。評估狀態。
error

object (Status)

僅供輸出。評估時發生的錯誤。只有在評估狀態為 FAILED 時才會填入。
createTime

string (Timestamp format)

僅供輸出。建立 Evaluation 的時間戳記。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
endTime

string (Timestamp format)

僅供輸出。Evaluation 完成時間的時間戳記。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
errorSamples[]

object (Status)

僅供輸出。處理要求時發生的錯誤範例。

EvaluationSpec

說明評估規格。

JSON 表示法 
{
  "querySetSpec": {
    object (QuerySetSpec)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "searchRequest": {
    object (SearchRequest)
  }
  // End of mutually exclusive fields.
}
欄位
querySetSpec

object (QuerySetSpec)

選用。查詢集的規格。
搜尋規格。以下列出互斥欄位。回應中最多會設定一個欄位：
searchRequest

object (SearchRequest)

這是必要旗標，用於執行評估的搜尋要求。

系統僅支援 SearchRequest 中的下列欄位；如果提供任何其他欄位，系統會傳回 UNSUPPORTED 錯誤：
互斥欄位的結尾。

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)
  },
  "customRankingParams": {
    object (CustomRankingParams)
  },
  "entity": string
}
欄位
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 做為分支 ID，或將這個欄位留空，即可搜尋預設分支下的文件。
query

string

原始搜尋查詢。
pageCategories[]

string

選用。與類別頁面相關聯的類別。必須為類別導覽查詢設定，才能獲得良好的搜尋品質。格式應與 PageInfo.page_category 相同。這個欄位等同於瀏覽 (導覽) 查詢的查詢。查詢空白時，瀏覽模型會使用這項功能。

如果欄位留空，瀏覽模型就不會使用。如果欄位包含多個元素，系統只會使用第一個元素。

如要表示類別的完整路徑，請使用「>」字元分隔不同層級。如果類別名稱包含「>」，請替換成其他字元。舉例來說，Graphics Cards > RTX>4090 > Founders Edition (其中「RTX > 4090」代表一個層級) 可以改寫為 Graphics Cards > RTX_4090 > Founders Edition
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 下方的規格。

如果引擎有多個資料儲存庫，這個欄位為選填欄位。如果為空白，系統會搜尋所有引擎的資料儲存庫 (混合搜尋)。除非指定確切的資料儲存庫，否則系統不支援部分要求欄位 (例如 orderBy 和 queryExpansionSpec)，並會傳回 INVALID_ARGUMENT 錯誤。
numResultsPerDataStore

integer

選用。從每個資料儲存庫擷取的結果數上限。如未指定，系統會使用提供的 SearchRequest.DataStoreSpec.num_results，否則不會設限。
filter

string

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

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

在 Vertex AI Search 中，篩選作業是透過將 LHS 篩選鍵對應至 Vertex AI 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 搜尋的 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 錯誤。
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) - 如果信號為 NaN，則傳回 0，否則傳回 1。
  • fillNan(signal1, signal2 | double) -- if signal1 is NaN, returns signal2 | double, else returns signal1.

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

  • 0.2 * semanticSimilarityScore + 0.8 * log(keywordSimilarityScore) -- mostly rank by the logarithm of keywordSimilarityScore with slight semantic_smilarity_score adjustment.
  • 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) - mostly rank by the reciprocal rank of keywordSimilarityScore with slight adjustment of reciprocal rank of semantic_smilarity_score.

系統支援下列信號：

  • semanticSimilarityScore：語意相似度調整值，是使用 Google 專有模型生成的嵌入計算而得。這個分數會決定搜尋查詢與文件的語意相似程度。
  • keywordSimilarityScore：關鍵字比對調整項使用最佳比對 25 (BM25) 排名函式。這項分數是使用機率模型計算得出，用於估算文件與特定查詢的相關程度。
  • relevanceScore：語意關聯性調整，使用 Google 專有模型判斷使用者查詢的意義和意圖，並考量文件內容。
  • pctrRank：預測轉換率調整幅度，做為排名依據。預測點閱率 (pCTR) 可從使用者角度評估搜尋結果的關聯性和吸引力。預估點擊率越高，表示結果越有可能滿足使用者的查詢和意圖，因此是排名時的重要信號。
  • freshnessRank：以等級表示的新鮮度調整幅度
  • documentAge：文件上次更新後經過的時間 (以小時為單位)，為浮點數 (例如 0.25 代表 15 分鐘)。
  • topicalityRank：主題性調整值 (做為排名)。使用 Google 專屬模型判斷查詢和文件之間基於關鍵字的重疊程度。
  • baseRank：結果的預設排名
  • mediaActorMatch：媒體演員是否符合查詢條件
  • mediaDirectorMatch：媒體總監是否符合查詢條件
  • mediaGenreMatch：媒體類型是否符合查詢條件
  • mediaLanguageMatch：媒體語言是否與查詢相符
  • mediaTitleMatch：媒體名稱是否符合查詢
  • mediaPrefixSimilarityRank：媒體結果的前置字串相似度排名
  • mediaSemanticSimilarityRank：媒體結果的語意相似度排名
rankingExpressionBackend

enum (RankingExpressionBackend)

選用。用於評估排序運算式的後端。
userLabels

map (key: string, value: string)

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

  • 每項資源可以有多個標籤，上限為 64 個。
  • 每個標籤都必須是鍵/值組合。
  • 鍵的長度至少要有 1 個字元，最多 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)

選用。擁擠度規格，可提升結果多樣性。如果指定多個 CrowdingSpec，系統會評估每個 field 值的不重複組合，而 maxCount 會是所有 CrowdingSpec 中 maxCount 的最大值。舉例來說，如果第一個 CrowdingSpec 的 field =「color」且 maxCount = 3，第二個 CrowdingSpec 的 field =「size」且 maxCount = 2，則在傳回 3 個顏色和尺寸相同的文件後，後續文件應移除或降級。
session

string

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

使用者可透過 Session 進行多輪 /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。在這裡，系統會根據第一次搜尋呼叫的搜尋結果生成答案。
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 用於停用搜尋的外掛程式。此欄位僅適用於搜尋要求。
customRankingParams

object (CustomRankingParams)

選用。自訂排序功能的選用設定。
entity

string

選用。客戶的實體，可能經營多個不同的實體、網域、網站或區域，例如「Google 美國」、「Google Ads」、「Waymo」、「google.com」、「youtube.com」等。如果設定此值，應與 UserEvent.entity 完全比對，才能透過實體提升搜尋結果。

ImageQuery

指定圖片查詢輸入內容。

JSON 表示法 
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "imageBytes": string
  // End of mutually exclusive fields.
}
欄位
指定圖片位元組。以下列出互斥欄位。回應中最多會設定一個欄位：
imageBytes

string

Base64 編碼的圖片位元組。支援的圖片格式：JPEG、PNG 和 BMP。
互斥欄位的結尾。

FacetSpec

用於執行多面向搜尋的商情項目規格。

JSON 表示法 
{
  "facetKey": {
    object (FacetKey)
  },
  "limit": integer,
  "excludedFilterKeys": [
    string
  ],
  "enableDynamicPosition": boolean
}
欄位
facetKey

object (FacetKey)

這是必要旗標，構面鍵規格。
limit

integer

這個 facet 傳回的 facet 值數量上限。如未指定，則預設值為 20。最大值為 300。超過 300 的值會強制設為 300。如果是醫療照護搜尋的匯總作業，當 [FacetKey.key] 為「healthcare_aggregation_key」時，系統會將限制內部覆寫為 10,000，無論在此設定的值為何。

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

string

建立多面向時要排除的鍵清單。

根據預設，除非這個欄位列出 FacetKey.key，否則不會從篩選器中排除。

在這個欄位中列出 facet 鍵，即使 facet 值已從搜尋結果中篩除，仍會顯示為 facet 結果。使用這個欄位不會影響傳回的搜尋結果。

舉例來說，假設有 100 份文件的顏色側邊欄為「紅色」，200 份文件的顏色側邊欄為「藍色」。如果查詢包含「color:ANY("Red")」篩選條件，且「color」為 FacetKey.key，則預設只會在搜尋結果中傳回「Red」文件，並傳回「Red」和計數 100 做為唯一的顏色商情項目。雖然也有藍色文件，但「藍色」不會顯示為可用的篩選條件值。

如果「color」列在「excludedFilterKeys」中，查詢就會傳回刻面值「Red」，計數為 100，以及「Blue」，計數為 200，因為「color」鍵現在已從篩選器中排除。由於這個欄位不會影響搜尋結果，因此搜尋結果仍會正確篩選，只傳回「紅色」文件。

最多只能有 100 個值，否則會傳回 INVALID_ARGUMENT 錯誤。
enableDynamicPosition

boolean

啟用這個 facet 的動態位置。如果設為 true，系統會自動決定這個側面的位置，以及回應中的所有側面。如果啟用動態 facet，系統會一併排序。如果設為 false，回應中這個商情項目的位置會與要求中的位置相同，且會排在啟用動態位置的商情項目和所有動態商情項目之前。

舉例來說，您可能一律希望在回應中傳回評分構面，但不一定總是將評分構面顯示在頂端。在這種情況下，您可以將 enableDynamicPosition 設為 true，讓系統自動決定回應中評分層面的位置。

再舉一例，假設要求中包含下列側欄：

  • "rating", enableDynamicPosition = true

  • "price", enableDynamicPosition = false

  • 「brands」，enableDynamicPosition = false

此外，您也啟用了動態 facet，這會產生 facet gender。然後，回應中最終的構面順序可以是 ("price"、"brands"、"rating"、"gender") 或 ("price"、"brands"、"gender"、"rating")，取決於 API 如何排序「gender」和「rating」構面。不過請注意，「price」和「brands」一律會排在第一和第二位，因為它們的 enableDynamicPosition 為 false。

FacetKey

指定如何計算構面。

JSON 表示法 
{
  "key": string,
  "intervals": [
    {
      object (Interval)
    }
  ],
  "restrictedValues": [
    string
  ],
  "prefixes": [
    string
  ],
  "contains": [
    string
  ],
  "caseInsensitive": boolean,
  "orderBy": string
}
欄位
key

string

這是必要旗標，Document 物件中支援的文字和數值層面鍵，系統會根據這些鍵計算層面值。分面鍵會區分大小寫。
intervals[]

object (Interval)

只有在值應分組為間隔時才設定。必須為含有數值的層面設定。如果 facet 含有文字值，則不得設定此屬性。間隔數上限為 30 個。
restrictedValues[]

string

只取得指定受限值的側邊。僅支援文字欄位。舉例來說，假設「類別」有三個值：「動作 > 2022」、「動作 > 2021」和「科幻 > 2022」。如果將「restrictedValues」設為「Action > 2022」，則「category」構面只會包含「Action > 2022」。僅支援文字欄位。最多 10 個。
prefixes[]

string

只取得以指定字串前置字元開頭的側欄值。舉例來說，假設「類別」有三個值：「動作 > 2022」、「動作 > 2021」和「科幻 > 2022」。如果將「前置字元」設為「動作」，則「類別」構面只會包含「動作 > 2022」和「動作 > 2021」。僅支援文字欄位。最多 10 個。
contains[]

string

只取得包含指定字串的側滑選單值。舉例來說，假設「類別」有三個值：「動作 > 2022」、「動作 > 2021」和「科幻 > 2022」。如果將「包含」設為「2022」，「類別」層面只會包含「動作 > 2022」和「科幻 > 2022」。僅支援文字欄位。最多 10 個。
caseInsensitive

boolean

如果使用前置字串或包含項目取得分面值時，要讓分面鍵不區分大小寫，請設為 True；否則請設為 False。
orderBy

string

傳回文件的順序。

允許的值包括：

如未設定，文字值會以自然順序排序；數值間隔則會以 FacetSpec.FacetKey.intervals 指定的順序排序。

時間間隔

浮點間隔。

JSON 表示法 
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "minimum": number,
  "exclusiveMinimum": number
  // End of mutually exclusive fields.

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "maximum": number,
  "exclusiveMaximum": number
  // End of mutually exclusive fields.
}
欄位

區間下限。如果未設定任何 min 欄位，下限為負無限大。

這個欄位不得大於最大值，否則會傳回 INVALID_ARGUMENT 錯誤。以下列出互斥欄位。回應中最多會設定一個欄位：
minimum

number

包含下限。
exclusiveMinimum

number

下限 (不含)。
互斥欄位的結尾。

區間上限。如果未設定任一上限欄位，則上限為正無限大。

這個欄位不得小於最小值，否則會傳回 INVALID_ARGUMENT 錯誤。以下列出互斥欄位。回應中最多會設定一個欄位：
maximum

number

上限 (含)。
exclusiveMaximum

number

上限 (不含)。
互斥欄位的結尾。

QueryExpansionSpec

規格，用於判斷查詢擴充的條件。

JSON 表示法 
{
  "condition": enum (Condition),
  "pinUnexpandedResults": boolean
}
欄位
condition

enum (Condition)

查詢擴充的條件。預設為 Condition.DISABLED。
pinUnexpandedResults

boolean

是否要固定未展開的結果。如果這個欄位設為 true，搜尋結果一律會先顯示未使用擴充功能的產品，再顯示擴充結果。

條件

列舉說明查詢擴充應在何種條件下發生。

列舉
CONDITION_UNSPECIFIED 未指定查詢擴充條件。在這種情況下，伺服器行為會預設為 Condition.DISABLED。
DISABLED 已停用查詢擴充功能。即使 SearchResponse.total_size 為零，系統還是只會使用完全相符的搜尋查詢。
AUTO 由 Search API 建立的自動查詢擴充。

SpellCorrectionSpec

查詢拼字修正的規格。

JSON 表示法 
{
  "mode": enum (Mode)
}
欄位
mode

enum (Mode)

拼字修正功能取代原始搜尋查詢的模式。預設值為 Mode.AUTO。

模式

列舉，說明應以哪種模式進行拼字修正。

列舉
MODE_UNSPECIFIED 未指定拼字校正模式。在這種情況下，伺服器行為會預設為 Mode.AUTO。
SUGGESTION_ONLY 搜尋 API 會嘗試提供拼字建議。如果找到建議，就會放在 SearchResponse.corrected_query 中。系統不會將拼字建議做為搜尋查詢。
AUTO 由 Search API 建立的自動拼字修正功能。如果找到修正後的查詢，系統會根據該查詢進行搜尋。

EmbeddingSpec

這項規格會使用自訂查詢嵌入向量，執行語意文件擷取作業。

JSON 表示法 
{
  "embeddingVectors": [
    {
      object (EmbeddingVector)
    }
  ]
}
欄位
embeddingVectors[]

object (EmbeddingVector)

用於檢索的嵌入向量。最多只能有 1 個。

EmbeddingVector

嵌入向量。

JSON 表示法 
{
  "fieldPath": string,
  "vector": [
    number
  ]
}
欄位
fieldPath

string

結構定義中的嵌入欄位路徑。
vector[]

number

查詢嵌入向量。

RankingExpressionBackend

用於評估排序運算式的後端。

列舉
RANKING_EXPRESSION_BACKEND_UNSPECIFIED 未指定/不明值的預設選項。
BYOE

已淘汰：請改用 RANK_BY_EMBEDDING。依自訂嵌入模型排序，這是評估排序運算式的預設方式。舊版列舉選項，請改用 RANK_BY_EMBEDDING。
CLEARBOX

已淘汰：請改用 RANK_BY_FORMULA。依自訂公式排序。舊版列舉選項，請改用 RANK_BY_FORMULA。
RANK_BY_EMBEDDING 依自訂嵌入模型排序，這是評估排序運算式的預設方式。
RANK_BY_FORMULA 依自訂公式排序。

NaturalLanguageQueryUnderstandingSpec

規格：為搜尋要求啟用自然語言理解功能。

JSON 表示法 
{
  "filterExtractionCondition": enum (FilterExtractionCondition),
  "geoSearchQueryDetectionFieldNames": [
    string
  ],
  "extractedFilterBehavior": enum (ExtractedFilterBehavior),
  "allowedFieldNames": [
    string
  ]
}
欄位
filterExtractionCondition

enum (FilterExtractionCondition)

篩選器擷取作業的發生條件。伺服器行為預設為 DISABLED。
geoSearchQueryDetectionFieldNames[]

string

用於根據位置資訊篩選的欄位名稱，系統會在自然語言搜尋查詢中偵測到地理位置篩選器。只有在 FilterExtractionCondition 設為 ENABLED 時才有效。
extractedFilterBehavior

enum (ExtractedFilterBehavior)

選用。控制將擷取的篩選條件套用至搜尋的行為。預設行為取決於要求。單一資料儲存庫結構化搜尋的預設值為 HARD_FILTER。如果是多個資料存放區的搜尋，預設行為為 SOFT_BOOST。系統一律會將位置資訊篩選器套用為硬性篩選器，且 SOFT_BOOST 設定不會影響這些篩選器。只有在 SearchRequest.NaturalLanguageQueryUnderstandingSpec.FilterExtractionCondition 設為 FilterExtractionCondition.ENABLED 時，才會使用這個欄位。
allowedFieldNames[]

string

選用。可用於擷取自然語言篩選條件的欄位許可清單。如果未指定，預設所有可建立索引的欄位都符合自然語言篩選條件的擷取資格 (但不保證會使用)。如果 allowedFieldNames 中指定了任何欄位，只有在結構定義中標示為可建立索引，且位於允許清單中的欄位，才符合自然語言篩選器擷取條件。注意：多資料存放區搜尋目前不支援這項功能，系統會忽略這項設定。

FilterExtractionCondition

列舉，說明應在何種條件下擷取篩選器。

列舉
CONDITION_UNSPECIFIED 伺服器行為預設為 DISABLED。
DISABLED 停用 NL 篩選器擷取作業。
ENABLED 啟用 NL 篩選器擷取功能。

ExtractedFilterBehavior

列舉說明如何將擷取的篩選器套用至搜尋。

列舉
EXTRACTED_FILTER_BEHAVIOR_UNSPECIFIED EXTRACTED_FILTER_BEHAVIOR_UNSPECIFIED 會使用預設行為來擷取篩選器。如果是單一資料儲存區搜尋，預設會套用硬性篩選器。如果是多資料儲存庫搜尋，預設會套用為軟性提升。
HARD_FILTER 將所有擷取的篩選條件套用至結果，做為硬性篩選條件。如果結果未通過擷取的篩選條件，就不會傳回結果集。
SOFT_BOOST 將所有擷取的篩選條件套用為軟性加成。通過篩選器的結果會在結果集中獲得較高的排名。

SearchAsYouTypeSpec

在搜尋要求中輸入內容時的搜尋規格。

JSON 表示法 
{
  "condition": enum (Condition),
  "fields": [
    {
      object (Field)
    }
  ],
  "scoreThreshold": number
}
欄位
condition

enum (Condition)

即時搜尋功能的觸發條件。預設為 Condition.DISABLED。
fields[]

object (Field)

選用。用於「即時搜尋」評分的欄位清單。
scoreThreshold

number

選用。輸入分數門檻，即可篩選出符合條件的結果。如果 score >= scoreThreshold，我們會保留結果。

條件

列舉，說明應在何種條件下進行輸入時搜尋。

列舉
CONDITION_UNSPECIFIED 伺服器行為預設為 Condition.DISABLED。
DISABLED 停用即時搜尋功能。
ENABLED 啟用即時搜尋功能。
AUTO 自動在「邊打邊搜尋」和標準搜尋模式之間切換，非常適合單一 API 實作 (例如去抖動)。

欄位

用於這項要求中「邊打邊搜尋」評分的結構定義欄位。在要求期間，覆寫任何資料儲存庫層級的「隨打即搜尋」欄位設定。

JSON 表示法 
{
  "key": string,
  "weight": number
}
欄位
key

string

這是必要旗標，已編入索引的欄位鍵，可供「即時搜尋」功能使用。
weight

number

選填。這個欄位的分數權重。如未指定，預設值為 1.0。

DisplaySpec

指定顯示功能，例如相符處醒目顯示。

JSON 表示法 
{
  "matchHighlightingCondition": enum (MatchHighlightingCondition)
}
欄位
matchHighlightingCondition

enum (MatchHighlightingCondition)

比對醒目顯示的條件。

MatchHighlightingCondition

列舉，說明應在何種條件下醒目顯示相符項目。

列舉
MATCH_HIGHLIGHTING_CONDITION_UNSPECIFIED 伺服器行為與 MATCH_HIGHLIGHTING_DISABLED 相同。
MATCH_HIGHLIGHTING_DISABLED 停用所有文件中的相符內容醒目顯示功能。
MATCH_HIGHLIGHTING_ENABLED 在所有文件中啟用相符內容醒目顯示功能。

CrowdingSpec

擁擠度規格。擁擠度會限制共用相同欄位值的結果數量，藉此提升搜尋結果的多樣性。舉例來說，如果顏色欄位的 maxCount 為 3，且模式為 DROP_CROWDED_RESULTS，則所有頁面最多會傳回 3 個顏色相同的結果。

JSON 表示法 
{
  "field": string,
  "maxCount": integer,
  "mode": enum (Mode)
}
欄位
field

string

用於擁擠的欄位。Document 物件中的欄位可能會導致文件過於擁擠。擁擠度欄位會區分大小寫。
maxCount

integer

每個欄位值要保留的文件數量上限。如果至少有 maxCount 個先前的結果包含指定欄位的相同值 (根據 orderBy 中指定的順序)，則具有相同值的後續結果會「擠掉」先前的結果。如未指定，預設值為 1。
mode

enum (Mode)

用於擁擠文件的模式。

模式

列舉，說明要用於擠出文件的模式。這些產品可能會遭到刪除或降級至後續頁面。

列舉
MODE_UNSPECIFIED 未指定擁擠模式。在這種情況下，伺服器行為會預設為 Mode.DROP_CROWDED_RESULTS。
DROP_CROWDED_RESULTS 捨棄擁擠的結果。
DEMOTE_CROWDED_RESULTS_TO_END 將擁擠的結果降級至後續頁面。

SessionSpec

工作階段規格。

JSON 表示法 
{
  "queryId": string,
  "searchResultPersistenceCount": integer
}
欄位
queryId

string

如果已設定，搜尋結果會儲存在這個查詢 ID 指定的「回合」。

示例：假設工作階段如下：session { name: ".../sessions/xxx" turns { query { text: "What is foo?" queryId: ".../questions/yyy" } answer: "Foo is ..." } turns { query { text: "How about bar then?" queryId: ".../questions/zzz" } } }

使用者可以透過類似下列要求的形式呼叫 /search API：

session: ".../sessions/xxx" sessionSpec { queryId: ".../questions/zzz" }

接著，API 會儲存搜尋結果，並與最後一輪對話建立關聯。後續的 /answer API 呼叫 (指定工作階段 ID 和查詢 ID) 可以使用儲存的搜尋結果。此外，您也可以使用相同的會期 ID 和查詢 ID，平行呼叫 /search 和 /answer。
searchResultPersistenceCount

integer

要保留的最相關搜尋結果數量。後續的 /answer API 呼叫可使用保存的搜尋結果。

這個欄位與 SearchRequest.ContentSearchSpec.SummarySpec.summary_result_count 中的 summaryResultCount 欄位類似。

文件模式最多 10 個結果，區塊模式最多 50 個結果。

RelevanceThreshold

搜尋結果的關聯性門檻。關聯性門檻越高，顯示的相關結果就越多，但傳回的結果數會減少。

列舉
RELEVANCE_THRESHOLD_UNSPECIFIED 預設值。在這種情況下，伺服器行為會預設為 Google 定義的門檻。
LOWEST 最低關聯性門檻。
LOW 關聯性門檻偏低。
MEDIUM 中等關聯性門檻。
HIGH 高關聯性門檻。

RelevanceFilterSpec

關聯性篩選規格。

JSON 表示法 
{
  "keywordSearchThreshold": {
    object (RelevanceThresholdSpec)
  },
  "semanticSearchThreshold": {
    object (RelevanceThresholdSpec)
  }
}
欄位
keywordSearchThreshold

object (RelevanceThresholdSpec)

選用。指定關鍵字搜尋的關聯性篩選門檻。
semanticSearchThreshold

object (RelevanceThresholdSpec)

選用。語意搜尋的關聯性篩選門檻規格。

RelevanceThresholdSpec

特定子搜尋的關聯性篩選規格。

JSON 表示法 
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "relevanceThreshold": enum (RelevanceThreshold),
  "semanticRelevanceThreshold": number
  // End of mutually exclusive fields.
}
欄位
設定決定關聯性門檻的方式。以下列出互斥欄位。回應中最多會設定一個欄位：
relevanceThreshold

enum (RelevanceThreshold)

子搜尋的預先定義關聯性門檻。
semanticRelevanceThreshold

number

子搜尋的自訂關聯性門檻。值必須介於 [0.0, 1.0] 之間。
互斥欄位的結尾。

RelevanceScoreSpec

傳回文件關聯分數的規格。

JSON 表示法 
{
  "returnRelevanceScore": boolean
}
欄位
returnRelevanceScore

boolean

選用。是否要傳回搜尋結果的關聯性分數。分數越高，表示文件與查詢的關聯性越高。

SearchAddonSpec

根據新的重新定價模式，SearchAddonSpec 用於停用搜尋的外掛程式。如果未指定 SearchAddonSpec，系統預設會視為客戶想在適用的位置啟用這些功能。

JSON 表示法 
{
  "disableSemanticAddOn": boolean,
  "disableKpiPersonalizationAddOn": boolean,
  "disableGenerativeAnswerAddOn": boolean
}
欄位
disableSemanticAddOn

boolean

選用。如果為 true，則會停用語意外掛程式。語意外掛程式包含嵌入和 Jetstream。
disableKpiPersonalizationAddOn

boolean

選用。如為 true，系統會停用事件重新排序和個人化功能，以盡量提升 KPI 和個人化搜尋結果。
disableGenerativeAnswerAddOn

boolean

選用。如果設為 true，系統會停用生成式答案外掛程式。生成式回覆外掛程式包含自然語言篩選器和簡單回覆。

CustomRankingParams

自訂排序功能的設定參數。

JSON 表示法 
{
  "expressionsToPrecompute": [
    string
  ]
}
欄位
expressionsToPrecompute[]

string

選用。要評估的排名運算式清單 (請參閱 rankingExpression 的語法說明文件)。評估結果會以 SearchResponse.SearchResult.rank_signals.precomputed_expression_values 欄位傳回。

QuerySetSpec

說明查詢集的規格。

JSON 表示法 
{
  "sampleQuerySet": string
}
欄位
sampleQuerySet

string

選用。用於評估的 SampleQuerySet 完整資源名稱，格式為 projects/{project}/locations/{location}/sampleQuerySets/{sampleQuerySet}。

QualityMetrics

說明評估產生的指標。

JSON 表示法 
{
  "docRecall": {
    object (TopkMetrics)
  },
  "docPrecision": {
    object (TopkMetrics)
  },
  "docNdcg": {
    object (TopkMetrics)
  },
  "pageRecall": {
    object (TopkMetrics)
  },
  "pageNdcg": {
    object (TopkMetrics)
  }
}
欄位
docRecall

object (TopkMetrics)

各個文件的召回率，以及各種 top-k 截斷層級。

召回率是指檢索到的相關文件占所有相關文件的比例。

範例 (前 5 項)：* 如果在前 5 項中擷取了 3 份相關文件，則單一 SampleQuery 的 recall@5 = 3/5 = 0.6
docPrecision

object (TopkMetrics)

各個前 k 個截斷層級的文件精確度。

精確度是指檢索到的文件中，相關文件的比例。

範例 (前 5 名)： * 單一 SampleQuery，如果前 5 名檢索到的文件中，有 4 份與查詢相關，則 precision@5 = 4/5 = 0.8
docNdcg

object (TopkMetrics)

各個前 k 個截斷層級的文件正規化折減累計增益 (NDCG)。

NDCG 會評估排名品質，並為排名較高的結果提供較高的關聯性。

範例 (前 3 名)：假設 SampleQuery 擷取了三份文件 (D1、D2、D3)，且二元相關性判斷結果 (1 代表相關，0 代表不相關) 如下：

擷取：[D3 (0)、D1 (1)、D2 (1)] 理想：[D1 (1)、D2 (1)、D3 (0)]

計算每個 SampleQuery 的 NDCG@3： * DCG@3：0/log2(1+1) + 1/log2(2+1) + 1/log2(3+1) = 1.13 * 理想 DCG@3：1/log2(1+1) + 1/log2(2+1) + 0/log2(3+1) = 1.63 * NDCG@3：1.13/1.63 = 0.693
pageRecall

object (TopkMetrics)

每個網頁的召回率，以及各種 top-k 截斷層級。

召回率是指系統檢索到的相關網頁，占所有相關網頁的比例。

範例 (前 5 名)： * 針對單一 SampleQuery，如果前 5 名中擷取了 3 個相關網頁，則 recall@5 = 3/5 = 0.6
pageNdcg

object (TopkMetrics)

各網頁的正規化折減累計增益 (NDCG)，以及各種前 k 個結果的截斷層級。

NDCG 會評估排名品質，並為排名較高的結果提供較高的關聯性。

範例 (前 3 名)：假設 SampleQuery 擷取了三個網頁 (P1、P2、P3)，且二元相關性判斷結果為 (1 代表相關，0 代表不相關)：

已擷取：[P3 (0)、P1 (1)、P2 (1)] 理想：[P1 (1)、P2 (1)、P3 (0)]

計算 SampleQuery 的 NDCG@3： * DCG@3：0/log2(1+1) + 1/log2(2+1) + 1/log2(3+1) = 1.13 * 理想 DCG@3：1/log2(1+1) + 1/log2(2+1) + 0/log2(3+1) = 1.63 * NDCG@3：1.13/1.63 = 0.693

TopkMetrics

儲存特定前 K 個層級的指標值。

JSON 表示法 
{
  "top1": number,
  "top3": number,
  "top5": number,
  "top10": number
}
欄位
top1

number

前 1 名的值。
top3

number

前 3 名的價值。
top5

number

前 5 名的值。
top10

number

前 10 名的值。

狀態

說明評估的狀態。

列舉
STATE_UNSPECIFIED 未指定評估。
PENDING 服務正在準備執行評估。
RUNNING 評估正在進行中。
SUCCEEDED 評估作業已順利完成。
FAILED 評估失敗。

方法

create

 建立 Evaluation。

get

 取得 Evaluation。

list

 取得 Evaluation 清單。

listResults

 取得指定 Evaluation 的結果清單。