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

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 后端中定义的键属性来完成的，此映射由客户在其架构中定义。例如，媒体客户的架构中可能包含“名称”字段。在这种情况下，过滤条件将如下所示：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：double。默认值为空。根据值启用非网页搜索。唯一有效的非默认值为 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。在此示例中，系统会在查询排名中考虑之前的搜索查询。也就是说，如果第一个查询是“Alphabet 在 2022 年的表现如何？”，如果上一个查询是“Alphabet 在 2022 年的表现如何？”，而当前查询是“2023 年呢？”，则当前查询会被解读为“Alphabet 在 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”且颜色为“红色”或“蓝色”的文档的得分，请使用以下查询：(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 个文档的颜色构面为“红色”，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 的结果列表。