REST Resource: projects.locations.evaluations

资源：评价

评估是指评估流程的单次执行（或运行）。它封装了评估的状态和生成的数据。

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 个文档的颜色构面为“红色”，200 个文档的颜色构面为“蓝色”。包含过滤条件“color:ANY("Red")”且将“color”设为 FacetKey.key 的查询默认只会返回搜索结果中的“红色”文档，并且还会返回“红色”以及数量 100，作为唯一的颜色构面。虽然也有蓝色文档，但“蓝色”不会显示为可用的构面值。

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

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

boolean

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

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

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

  • “rating”，enableDynamicPosition = true

  • “price”，enableDynamicPosition = false

  • “brands”，enableDynamicPosition = false

此外，您还启用了动态分面，这会生成分面 gender。然后，响应中各构面的最终顺序可以是（“价格”“品牌”“评分”“性别”），也可以是（“价格”“品牌”“性别”“评分”），具体取决于 API 如何对“性别”和“评分”构面进行排序。不过，请注意，“价格”和“品牌”始终排在第一位和第二位，因为它们的 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

仅获取指定受限值的分面。仅支持文本字段。例如，假设“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，则在获取带有前缀或包含的分面值时，分面键不区分大小写；否则为 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 字段，则上限为正无穷大。

此字段不得小于最小值。否则，系统将返回 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)

在各种前 k 名截断水平下，每个文档的召回率。

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

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

object (TopkMetrics)

每个文档的精确度，在各种 top-k 截止水平下。

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

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

object (TopkMetrics)

每个文档在各种前 k 名截止水平下的归一化折扣累计增益 (NDCG)。

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

示例（前 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 截断水平下的召回率。

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

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

object (TopkMetrics)

每个网页的归一化折扣累计增益 (NDCG)，采用各种 top-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 的结果列表。