Method: projects.locations.collections.engines.servingConfigs.search

执行搜索。

HTTP 请求

POST https://discoveryengine.googleapis.com/v1beta/{servingConfig=projects/*/locations/*/collections/*/engines/*/servingConfigs/*}:search

网址采用 gRPC 转码语法。

路径参数

参数
servingConfig

string

必需。servingConfigs.search 服务配置的资源名称，例如 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。此字段用于标识服务配置名称，即用于执行搜索的一组模型。

请求正文

请求正文中包含结构如下的数据：

JSON 表示法 
{
  "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)
  }
}
字段
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 servingConfigs.search 中的过滤是通过将 LHS 过滤键映射到 Vertex AI servingConfigs.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。在此示例中，答案生成是在第一次搜索调用返回的搜索结果的上下文中进行的。

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

响应正文

如果成功，则响应正文包含一个 SearchResponse 实例。

授权范围

需要以下 OAuth 范围之一：

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/discoveryengine.readwrite
  • https://www.googleapis.com/auth/discoveryengine.assist.readwrite

如需了解详情，请参阅 Authentication Overview。

IAM 权限

需要拥有 servingConfig 资源的以下 IAM 权限：

  • discoveryengine.servingConfigs.search

如需了解详情，请参阅 IAM 文档。