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

Realiza una recomendación, que requiere un evento contextual del usuario.

Solicitud HTTP

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

La URL usa la sintaxis de la transcodificación gRPC.

Parámetros de ruta

Parámetros
servingConfig

string

Obligatorio. Nombre de recurso completo de un ServingConfig: projects/*/locations/global/collections/*/engines/*/servingConfigs/* o projects/*/locations/global/collections/*/dataStores/*/servingConfigs/*

Se crea una configuración de publicación predeterminada junto con la creación del motor de recomendaciones. El ID del motor se usa como el ID de la configuración de publicación predeterminada. Por ejemplo, para el motor projects/*/locations/global/collections/*/engines/my-engine, puedes usar projects/*/locations/global/collections/*/engines/my-engine/servingConfigs/my-engine para tus solicitudes RecommendationService.Recommend.

Cuerpo de la solicitud

El cuerpo de la solicitud contiene datos con la siguiente estructura:

Representación JSON 
{
  "userEvent": {
    object (UserEvent)
  },
  "pageSize": integer,
  "filter": string,
  "validateOnly": boolean,
  "params": {
    string: value,
    ...
  },
  "userLabels": {
    string: string,
    ...
  }
}
Campos
userEvent

object (UserEvent)

Obligatorio. Contexto sobre el usuario, lo que está viendo y qué acción realizó para activar la solicitud servingConfigs.recommend. Ten en cuenta que este detalle del evento del usuario no se incorporará a los registros de userEvent. Por lo tanto, se requiere una solicitud de escritura de userEvent independiente para el registro de eventos.

No establezcas UserEvent.user_pseudo_id ni UserEvent.user_info.user_id en el mismo ID fijo para diferentes usuarios. Si intentas recibir recomendaciones no personalizadas (no se recomienda, ya que puede afectar negativamente el rendimiento del modelo), establece UserEvent.user_pseudo_id en un ID único aleatorio y deja UserEvent.user_info.user_id sin configurar.
pageSize

integer

Cantidad máxima de resultados que se mostrarán Establece esta propiedad en la cantidad de resultados de recomendaciones necesarios. Si es cero, el servicio elige un valor predeterminado razonable. El valor máximo permitido es 100. Los valores superiores a 100 se establecen en 100.
filter

string

Filtro para restringir los resultados de recomendaciones con un límite de longitud de 5,000 caracteres. Actualmente, solo se admiten expresiones de filtro en el atributo filterTags.

Ejemplos:

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

Si attributeFilteringSyntax se establece en true en el campo params, se esperan expresiones basadas en atributos en lugar de la sintaxis basada en etiquetas descrita anteriormente. Ejemplos:

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

Si tu filtro bloquea todos los resultados, la API muestra documentos populares genéricos (sin filtrar). Si solo quieres resultados que coincidan estrictamente con los filtros, establece strictFiltering en true en RecommendRequest.params para recibir resultados vacíos en su lugar.

Ten en cuenta que la API nunca muestra Documents con storageStatus como EXPIRED o DELETED, independientemente de las opciones de filtro.
validateOnly

boolean

Usa el modo de solo validación para esta consulta de recomendación. Si se establece en true, se usa un modelo falso que muestra IDs de documentos arbitrarios. Ten en cuenta que el modo de solo validación solo se debe usar para probar la API o si el modelo no está listo.
params

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

Parámetros adicionales específicos del dominio para las recomendaciones.

Valores permitidos:

  • returnDocument: Booleano. Si se establece en true, el objeto Document asociado se muestra en RecommendResponse.RecommendationResult.document.
  • returnScore: Booleano. Si se establece en true, la puntuación de recomendación correspondiente a cada documento que se muestra se establece en RecommendResponse.RecommendationResult.metadata. La puntuación determinada indica la probabilidad de una conversión de documentos según el contexto y el historial del usuario.
  • strictFiltering: Booleano. True como valor predeterminado. Si se establece en false, el servicio muestra documentos populares genéricos (sin filtrar) en lugar de vacíos si el filtro bloquea todos los resultados de recomendaciones.
  • diversityLevel: String. Valor predeterminado vacío. Si se establece para que no esté vacío, debe ser uno de los siguientes:
    • no-diversity
    • low-diversity
    • medium-diversity
    • high-diversity
    • auto-diversity Esto proporciona control a nivel de la solicitud y ajusta los resultados de recomendaciones según la categoría del documento.
  • attributeFilteringSyntax: Booleano. False de manera predeterminada. Si se establece en true, el campo filter se interpreta según la sintaxis nueva basada en atributos.
userLabels

map (key: string, value: string)

Las etiquetas de usuario que se aplican a un recurso deben cumplir los siguientes requisitos:

  • Cada recurso puede tener varias etiquetas, hasta 64.
  • Cada etiqueta debe ser un par clave-valor.
  • La longitud de las claves debe ser de entre 1 y 63 caracteres, y no pueden estar vacías. Los valores pueden estar vacíos y su longitud máxima es de 63 caracteres.
  • Las claves y los valores pueden contener solo letras en minúscula, caracteres numéricos, guiones bajos y guiones. Todos los caracteres deben usar la codificación UTF-8 y se permiten los caracteres internacionales.
  • La porción de clave de una etiqueta debe ser única. Sin embargo, puedes usar la misma clave en varios recursos.
  • Las claves deben comenzar con una letra en minúscula o un carácter internacional.

Consulta Requisitos para las etiquetas para obtener más detalles.

Cuerpo de la respuesta

Si se ejecuta de forma correcta, el cuerpo de la respuesta contiene una instancia de RecommendResponse.

Alcances de autorización

Se necesita uno de los siguientes permisos de OAuth:

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

Para obtener más información, consulta Authentication Overview.

Permisos de IAM

Se requiere el siguiente permiso de IAM en el recurso servingConfig:

  • discoveryengine.servingConfigs.recommend

Para obtener más información, consulta la documentación de IAM.