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)
  },

  // Union field search_spec can be only one of the following:
  "searchRequest": {
    object (SearchRequest)
  }
  // End of list of possible types for union field search_spec.
}
欄位
querySetSpec

object (QuerySetSpec)

(選用步驟) 查詢集的規格。
聯集欄位 search_spec。搜尋規格。search_spec 只能是下列其中一項：
searchRequest

object (SearchRequest)

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

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

ImageQuery

指定圖片查詢輸入內容。

JSON 表示法 
{

  // Union field image can be only one of the following:
  "imageBytes": string
  // End of list of possible types for union field image.
}
欄位

聯集欄位 image。

image 只能是下列其中一項：
imageBytes

string

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

FacetSpec

執行多面向搜尋的 facet 規格。

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 份文件的顏色 Facet 為「紅色」，200 份文件的顏色 Facet 為「藍色」。如果查詢包含「color:ANY("Red")」篩選器，且「color」為 FacetKey.key，則預設只會在搜尋結果中傳回「Red」文件，並只傳回「Red」和計數 100 做為顏色 Facet。雖然也有藍色文件，但「藍色」不會顯示為可用的 Facet 值。

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

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

boolean

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

舉例來說，您可能希望一律在回應中傳回評分層面，但不一定會一律在頂端顯示評分層面。在這種情況下，您可以將 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 設定。不得為含有文字值的 facet 設定。間隔數上限為 30。
restrictedValues[]

string

只取得指定受限值的 facet。僅支援文字欄位。舉例來說，假設「類別」有三個值：「動作 > 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 表示法 
{

  // Union field min can be only one of the following:
  "minimum": number,
  "exclusiveMinimum": number
  // End of list of possible types for union field min.

  // Union field max can be only one of the following:
  "maximum": number,
  "exclusiveMaximum": number
  // End of list of possible types for union field max.
}
欄位

聯集欄位 min。間隔的下限。如果未設定任何 min 欄位，下限為負無限大。

這個欄位不得大於最大值。否則，系統會傳回 INVALID_ARGUMENT 錯誤。min 只能是下列其中一項：
minimum

number

包含下限。
exclusiveMinimum

number

不含下限。

聯集欄位 max。間隔的上限。如果未設定任一上限欄位，則上限為正無限大。

這個欄位不得小於最小值。否則，系統會傳回 INVALID_ARGUMENT 錯誤。max 只能是下列其中一項：
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 時才有效。

如果設定此欄位，系統會覆寫 ServingConfig.geo_search_query_detection_field_names 中設定的欄位名稱。
extractedFilterBehavior

enum (ExtractedFilterBehavior)

(選用步驟) 控制如何將擷取的篩選器套用至搜尋。預設行為取決於要求。如果是單一資料儲存庫結構化搜尋，預設值為 HARD_FILTER。如果是多資料存放區搜尋，預設行為為 SOFT_BOOST。系統一律會將位置篩選器套用為硬性篩選器，且 SOFT_BOOST 設定不會影響這類篩選器。只有在 [SearchRequest.natural_language_query_understanding_spec.filter_extraction_condition][] 設為 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)
}
欄位
condition

enum (Condition)

即時搜尋功能應執行的條件。預設值為 Condition.DISABLED。

條件

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

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

DisplaySpec

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

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

enum (MatchHighlightingCondition)

應醒目顯示相符項目的條件。

MatchHighlightingCondition

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

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

SessionSpec

工作階段規格。

多輪搜尋功能目前處於不公開正式發布階段。在公開發布這項功能前，請改用 v1alpha 或 v1beta 版。您也可以透過 Google 支援團隊申請加入允許清單。

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 高關聯性門檻。

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，系統會停用生成式答案外掛程式。生成式答案外掛程式包含自然語言篩選器和簡單答案。

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 項中擷取了 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)

每份文件的正規化折減累計增益 (NDCG)，適用於各種前 k 個截斷層級。

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 名)：* 如果有 3 個相關網頁在前 5 名中擷取，則單一 SampleQuery 的 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

最高值。
top3

number

前 3 名的值。
top5

number

前 5 個值。
top10

number

前 10 名的值。

狀態

說明評估的狀態。

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

方法

create

 建立 Evaluation。

get

 取得 Evaluation。

list

 取得 Evaluation 清單。

listResults

 取得指定 Evaluation 的結果清單。