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

标识符。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 规范化（即转换为 UTC 零时区格式并在末尾附加 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 规范化（即转换为 UTC 零时区格式并在末尾附加 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

用于执行分面搜索的分面规范。

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

object (FacetKey)

必需。分面键规范。
limit

integer

针对相应分面返回的分面值的数量上限。如果未指定，则默认为 20。允许的最大值为 300。大于 300 的值会强制转换为 300。对于医疗保健搜索中的汇总，当 [FacetKey.key] 为“healthcare_aggregation_key”时，无论此处设置的值是多少，系统都会在内部将限制替换为 10,000。

如果此字段为负数，则系统会返回 INVALID_ARGUMENT。
excludedFilterKeys[]

string

分面时要排除的键列表。

默认情况下，除非 FacetKey.key 列在此字段中，否则不会从过滤条件中排除。

在此字段中列出分面键后，即使分面键值被过滤出搜索结果，仍可显示为分面结果。使用此字段不会影响返回的搜索结果。

例如，假设有 100 个文档的颜色分面为“Red”，200 个文档的颜色分面为“Blue”。包含过滤条件“color:ANY("Red")”且将“color”设为 FacetKey.key 的查询默认只会在搜索结果中返回“Red”文档，并且还会返回“Red”（数量为 100）作为唯一的颜色分面。虽然也有蓝色文档可用，但“Blue”不会显示为可用的分面值。

如果“color”列在“excludedFilterKeys”中，则查询会返回分面值“Red”（数量为 100）和“Blue”（数量为 200），因为“color”键现已从过滤条件中排除。由于此字段不会影响搜索结果，因此搜索结果仍会正确过滤，仅返回“Red”文档。

最多允许 100 个值。否则，系统会返回 INVALID_ARGUMENT 错误。
enableDynamicPosition

boolean

为相应分面启用动态位置。如果设置为 true，则系统会自动确定此分面在响应中所有分面中的位置。如果启用了动态分面，则系统会一起排序。如果设置为 false，则此分面在响应中的位置与在请求中的位置相同，并且其排名高于启用动态位置的分面和所有动态分面。

例如，您可能始终希望在响应中返回评分分面，但不一定总是将评分分面显示在顶部。在这种情况下，您可以将 enableDynamicPosition 设置为 true，以便自动确定评分分面在响应中的位置。

再举一个例子，假设请求中包含以下分面：

  • "rating", enableDynamicPosition = true

  • "price", enableDynamicPosition = false

  • "brands", enableDynamicPosition = false

此外，您还启用了动态分面，这会生成分面 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)

仅当值应分桶到区间时才设置。必须针对具有数值的分面进行设置。不得针对具有文本值的分面进行设置。区间数上限为 30。
restrictedValues[]

string

仅获取给定受限值的分面。仅支持文本字段。例如，假设“category”有三个值：“Action > 2022”“Action > 2021”和“Sci-Fi > 2022”。如果将“restrictedValues”设置为“Action > 2022”，则“category”分面仅包含“Action > 2022”。仅支持文本字段。最大值为 10。
prefixes[]

string

仅获取以给定字符串前缀开头的分面值。例如，假设“category”有三个值：“Action > 2022”“Action > 2021”和“Sci-Fi > 2022”。如果将“prefixes”设置为“Action”，则“category”分面仅包含“Action > 2022”和“Action > 2021”。仅支持文本字段。最大值为 10。
contains[]

string

仅获取包含给定字符串的分面值。例如，假设“category”有三个值：“Action > 2022”“Action > 2021”和“Sci-Fi > 2022”。如果将“contains”设置为“2022”，则“category”分面仅包含“Action > 2022”和“Sci-Fi > 2022”。仅支持文本字段。最大值为 10。
caseInsensitive

boolean

如果为 true，则在获取包含 prefixes 或 contains 的分面值时，分面键不区分大小写；否则为 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 字段，则下限为负无穷大。

此字段的值不得大于 max。否则，系统会返回 INVALID_ARGUMENT 错误。min 只能是下列其中一项：
minimum

number

含下限。
exclusiveMinimum

number

不含下限。

联合字段 max。区间的上限。如果未设置任何 max 字段，则上限为正无穷大。

此字段不得小于 min。否则，系统将返回 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 Search 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 截止级别。

召回率是检索到的相关文档占所有相关文档的比例。

示例 (top-5)：* 对于单个 SampleQuery，如果在前 5 个结果中检索到 5 个相关文档中的 3 个，则 recall@5 = 3/5 = 0.6
docPrecision

object (TopkMetrics)

每个文档的精确率，在各种 top-k 截止级别。

精确率是检索到的相关文档占检索到的文档总数的比例。

示例 (top-5)：* 对于单个 SampleQuery，如果前 5 个检索到的文档中有 4 个相关，则 precision@5 = 4/5 = 0.8
docNdcg

object (TopkMetrics)

每个文档的归一化折损累计增益 (NDCG)，在各种 top-k 截止级别。

NDCG 可衡量排名质量，为靠前的结果赋予更高的相关性。

示例 (top-3)：假设 SampleQuery 有 3 个检索到的文档（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 截止级别。

召回率是检索到的相关页面占所有相关页面的比例。

示例 (top-5)：* 对于单个 SampleQuery，如果在前 5 名中检索到 5 个相关网页中的 3 个，则 recall@5 = 3/5 = 0.6
pageNdcg

object (TopkMetrics)

每个页面的归一化折损累计增益 (NDCG)，在各种 top-k 截止级别。

NDCG 可衡量排名质量，为靠前的结果赋予更高的相关性。

示例 (top-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

存储特定 top-k 级别的指标值。

JSON 表示法 
{
  "top1": number,
  "top3": number,
  "top5": number,
  "top10": number
}
字段
top1

number

top-1 值。
top3

number

top-3 值。
top5

number

top-5 值。
top10

number

top-10 值。

状态

描述评估的状态。

枚举
STATE_UNSPECIFIED 未指定评估。
PENDING 服务正在准备运行评估。
RUNNING 评估正在进行中。
SUCCEEDED 评估已成功完成。
FAILED 评估失败。

方法

create

 创建 Evaluation。

get

 获取 Evaluation。

list

 获取 Evaluation 的列表。

listResults

 获取给定 Evaluation 的结果列表。