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 错误：

SearchRequest

SearchService.Search 方法的请求消息。

JSON 表示法 
{
  "servingConfig": string,
  "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)
  }
}
字段
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

原始搜索查询。
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 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)

用于分面搜索的分面规范。如果为空，则系统不会返回任何分面。

最多允许 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

可选。用于跟踪访问者的唯一标识符。例如，可以通过 HTTP Cookie 实现，该 Cookie 应能够唯一标识单个设备上的访问者。如果访问者登录或退出网站，此唯一标识符不应更改。

此字段不应具有 unknown_visitor 等固定值。

此标识符应与 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) -- 倒数排名转换，第二个参数为分母常量。
  • isNan(signal) -- 如果信号为 NaN，则返回 0；否则返回 1。
  • fillNan(signal1, signal2 | double) -- 如果 signal1 为 NaN，则返回 signal2 | double，否则返回 signal1。

以下是一些使用支持的排名表达式类型的排名公式示例：

  • 0.2 * semanticSimilarityScore + 0.8 * log(keywordSimilarityScore) -- 主要按 keywordSimilarityScore 的对数进行排名，并进行小幅度 semantic_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) 从用户角度衡量搜索结果的相关性和吸引力。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)

即搜即得配置。仅 IndustryVertical.MEDIA 垂直行业支持此配置。
displaySpec

object (DisplaySpec)

可选。显示功能（例如搜索结果中的匹配项突出显示）的配置。
session

string

会话资源名称。可选。

会话允许用户进行多轮 /Search API 调用，或在 /Search API 调用和 /Answer API 调用之间进行协调。

示例 #1（多轮 /Search API 调用）：使用在第一次调用中生成的会话 ID 调用 /Search API。在此示例中，系统会在查询理解中考虑之前的搜索查询。也就是说，如果第一个查询是“How did Alphabet do in 2022?”，当前查询是“How about 2023?”，则当前查询将解读为“How did Alphabet do in 2023?”。

示例 2（/Search API 调用与 /Answer API 调用之间的协调）：使用在第一次调用中生成的会话 ID 调用 /Answer API。在此示例中，回答生成是在第一次搜索调用返回的搜索结果的上下文中进行的。

多轮搜索结果功能目前处于非公开正式版阶段。在此功能正式向公众发布之前，请改为使用 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 用于根据新的重新定价模型停用搜索的插件。只有搜索请求支持此字段。

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。

DataStoreSpec

一个结构体，用于定义搜索调用中要过滤的数据存储区以及这些数据存储区的配置。如果未正确设置，则会返回 INVALID_ARGUMENT 错误。

JSON 表示法 
{
  "dataStore": string,
  "filter": string,
  "boostSpec": {
    object (BoostSpec)
  },
  "customSearchOperators": string
}
字段
dataStore

string

必需。DataStore 的完整资源名称，例如 projects/{project}/locations/{location}/collections/{collectionId}/dataStores/{dataStoreId}。路径必须包含项目编号，此字段不支持项目 ID。
filter

string

可选。用于过滤由 dataStore 字段指定的数据存储区中的文档的过滤条件规范。如需详细了解过滤，请参阅过滤
boostSpec

object (BoostSpec)

可选。提升规范以提升特定文档。如需详细了解提升，请参阅提升
customSearchOperators

string

可选。自定义搜索运算符，如果指定，将用于过滤来自工作区数据存储区的结果。如需详细了解自定义搜索运算符，请参阅 SearchOperators。

BoostSpec

用于提升特定文档的提升规范。

JSON 表示法 
{
  "conditionBoostSpecs": [
    {
      object (ConditionBoostSpec)
    }
  ]
}
字段
conditionBoostSpecs[]

object (ConditionBoostSpec)

条件提升规范。如果文档满足规范中的多个条件，则这些规范中的提升得分都会应用，并以非线性的方式进行组合。规范数量上限为 20。

ConditionBoostSpec

提升功能适用于符合条件的文档。

JSON 表示法 
{
  "condition": string,
  "boost": number,
  "boostControlSpec": {
    object (BoostControlSpec)
  }
}
字段
condition

string

用于指定提升条件的表达式。语法和支持的字段与过滤表达式相同。如需了解详细的语法和限制，请参阅 SearchRequest.filter。

示例：

  • 如需提高文档 ID 为“doc_1”或“doc_2”且颜色为“Red”或“Blue”的文档的排名，请使用以下查询：(documentId: ANY("doc_1", "doc_2")) AND (color: ANY("Red", "Blue"))
boost

number

条件提升的强度，应介于 [-1, 1] 之间。设为负值代表降位。 默认值为 0.0。

设置为 1.0 可大幅提升文档的权重。但并不一定意味着升位后的文档在任何时候都会显示在结果最上方，或者其他文档会被排除。即使没有符合条件的商品，系统仍会显示结果。 此外，与搜索查询明显更相关的搜索结果仍会优先于您非常关注但不相关的文档。

设置为 -1.0 会大幅降低相应文档的权重。不过，系统可能仍会显示深度相关的结果。该文档需与上游文档竞争才能获得较高的排名，但不会完全被阻止。

设置为 0.0 表示不应用任何提升。系统会忽略提升条件。只能设置（条件、提升）组合或下面的 boostControlSpec 之一。如果两者都已设置，则系统会忽略全局提升，并应用更精细的 boostControlSpec。
boostControlSpec

object (BoostControlSpec)

基于客户定义的属性值的自定义排名复杂规范。

BoostControlSpec

基于客户指定的属性值的自定义排名规范。与上述简单的（条件、提升）组合相比，它可提供更多用于自定义排名的控件。

JSON 表示法 
{
  "fieldName": string,
  "attributeType": enum (AttributeType),
  "interpolationType": enum (InterpolationType),
  "controlPoints": [
    {
      object (ControlPoint)
    }
  ]
}
字段
fieldName

string

将用于确定提升幅度的字段的名称。
attributeType

enum (AttributeType)

用于确定提升幅度的属性类型。属性值可以从指定 fieldName 的字段值派生而来。对于数值，这很简单，即 attributeValue = numerical_field_value。不过，对于新鲜度，attributeValue = (time.now() - datetime_field_value)。
interpolationType

enum (InterpolationType)

用于连接下列控制点的插值类型。
controlPoints[]

object (ControlPoint)

用于定义曲线的控制点。单调函数（通过上面的 interpolationType 定义）会通过此处列出的控制点。

AttributeType

要针对其应用自定义排名的属性（或函数）。

枚举
ATTRIBUTE_TYPE_UNSPECIFIED 未指定 AttributeType。
NUMERICAL 数值字段的值将用于动态更新提升幅度。在这种情况下，控制点的 attributeValue（即 x 值）将是指定了 boostAmount 的数值字段的实际值。
FRESHNESS 对于新鲜度应用场景，属性值将是当前时间与指定日期时间字段中的日期之间的时长。该值必须采用 XSD dayTimeDuration 值（ISO 8601 时长值的受限子集）的格式。该值的格式为：[nD][T[nH][nM][nS]]。例如，5D、3DT12H30M、T24H。

InterpolationType

要应用的插值类型。默认值为线性（分段线性）。

枚举
INTERPOLATION_TYPE_UNSPECIFIED 插值类型未指定。在这种情况下，该字段会默认设置为线性。
LINEAR 系统将应用分段线性插值。

ControlPoint

用于定义曲线的控制点。通过这些控制点定义的曲线只能单调递增或递减（可接受常量值）。

JSON 表示法 
{
  "attributeValue": string,
  "boostAmount": number
}
字段
attributeValue

string

可以是以下值之一：1. 数值字段值。2. 新鲜度对应的时长规范：该值必须采用 XSD dayTimeDuration 值（ISO 8601 时长值的受限子集）的格式。该值的格式为：[nD][T[nH][nM][nS]]。
boostAmount

number

如果 attributeValue 的求值结果为上述指定的值，则该字段的值用于提升得分（介于 -1 到 1 之间）。

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 的结果列表。