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

进行推荐，这需要情境用户事件。

HTTP 请求

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

网址采用 gRPC 转码语法。

路径参数

参数
servingConfig

string

必需。ServingConfig 的完整资源名称：projects/*/locations/global/collections/*/engines/*/servingConfigs/* 或 projects/*/locations/global/collections/*/dataStores/*/servingConfigs/*

在创建商品推荐引擎的同时，系统还会创建一个默认的服务配置。引擎 ID 用作默认投放配置的 ID。例如，对于引擎 projects/*/locations/global/collections/*/engines/my-engine，您可以针对 RecommendationService.Recommend 请求使用 projects/*/locations/global/collections/*/engines/my-engine/servingConfigs/my-engine。

请求正文

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

JSON 表示法 
{
  "userEvent": {
    object (UserEvent)
  },
  "pageSize": integer,
  "filter": string,
  "validateOnly": boolean,
  "params": {
    string: value,
    ...
  },
  "userLabels": {
    string: string,
    ...
  }
}
字段
userEvent

object (UserEvent)

必需。有关用户的背景信息、用户正在查看的内容以及用户触发 servingConfigs.recommend 请求所采取的操作。请注意，此用户事件详细信息不会被提取到 userEvent 日志中。因此，需要单独的 userEvent 写入请求才能记录事件。

请勿为不同的用户将 UserEvent.user_pseudo_id 或 UserEvent.user_info.user_id 设置为相同的固定 ID。如果您尝试接收非个性化推荐（不建议这样做；这会对模型性能产生负面影响），请将 UserEvent.user_pseudo_id 设置为随机唯一 ID，并使 UserEvent.user_info.user_id 保持未设置状态。
pageSize

integer

页面中结果的数量上限。将此属性设置为所需的推荐结果数量。如果为零，服务会选择合理的默认值。允许的最大值为 100。大于 100 的值设置为 100。
filter

string

用于限制建议结果的过滤条件，长度上限为 5,000 个字符。目前，仅支持针对 filterTags 属性的过滤表达式。

示例：

  • (filterTags: ANY("Red", "Blue") OR filterTags: ANY("Hot", "Cold"))
  • (filterTags: ANY("Red", "Blue")) AND NOT (filterTags: ANY("Green"))

如果 params 字段下的 attributeFilteringSyntax 设置为 true，则系统会预期出现基于属性的表达式，而不是上述基于标记的语法。示例：

  • (language: ANY("en", "es")) AND NOT (categories: ANY("Movie"))
  • (available: true) AND (language: ANY("en", "es")) OR (categories: ANY("Movie"))

如果您的过滤条件屏蔽了所有结果，则 API 会返回常规（未过滤）的热门文档。如果您只希望获得与过滤条件完全匹配的结果，请在 RecommendRequest.params 中将 strictFiltering 设置为 true，这样系统会返回空结果。

请注意，无论过滤条件如何选择，API 都不会返回 storageStatus 为 EXPIRED 或 DELETED 的 Document。
validateOnly

boolean

针对此推荐查询使用仅验证模式。如果设置为 true，则使用返回任意文档 ID 的虚假模型。请注意，仅验证模式应仅用于测试 API，或在模型未准备就绪时使用。
params

map (key: string, value: value (Value format))

建议的其他网域专用参数。

允许的值：

  • returnDocument：布尔值。如果设置为 true，则在 RecommendResponse.RecommendationResult.document 中返回关联的 Document 对象。
  • returnScore：布尔值。如果设置为 true，则会在 RecommendResponse.RecommendationResult.metadata 中设置与每个返回的 Document 对应的推荐得分。给定的得分表示在给定用户情境和历史记录的情况下，文档转化的概率。
  • strictFiltering：布尔值。默认值为 true。如果设置为 false，则当过滤条件屏蔽所有建议结果时，服务会返回通用的（未过滤的）热门文档，而不是返回空结果。
  • diversityLevel：字符串。默认值为空。如果设置为非空，则必须是以下值之一：
    • no-diversity
    • low-diversity
    • medium-diversity
    • high-diversity
    • auto-diversity 这可提供请求级控制，并根据文档类别调整推荐结果。
  • attributeFilteringSyntax：布尔值。默认值为 false。如果设置为 true，则根据新的基于属性的语法来解读 filter 字段。
userLabels

map (key: string, value: string)

应用于资源的用户标签必须符合以下要求：

  • 每项资源可以有多个标签，但不能超过 64 个。
  • 每个标签都必须采用键值对形式。
  • 键至少有 1 个字符，最多有 63 个字符，且不能为空。值可以为空，且最多包含 63 个字符。
  • 键和值只能包含小写字母、数字字符、下划线和短划线。所有字符必须使用 UTF-8 编码，允许使用国际字符。
  • 标签的键部分必须是唯一的。不过，您可以将同一个键用于多个资源。
  • 键必须以小写字母或国际字符开头。

如需了解详情，请参阅标签的要求。

响应正文

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

授权范围

需要以下 OAuth 范围之一：

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

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

IAM 权限

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

  • discoveryengine.servingConfigs.recommend

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