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

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

Solicitud HTTP

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

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

Parámetros de ruta de acceso

Parámetros
servingConfig

string

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

Se crea una configuración de entrega 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 de 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. Es el 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 o 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 de forma negativa 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 que se necesitan. 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

Es un filtro para restringir los resultados de la recomendación 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 como verdadero en el campo params, se esperan expresiones basadas en atributos en lugar de la sintaxis basada en etiquetas que se describió 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 devolverá documentos populares genéricos (sin filtrar). Si solo quieres obtener resultados que coincidan estrictamente con los filtros, configura strictFiltering como true en RecommendRequest.params para recibir resultados vacíos.

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

boolean

Usa el modo de solo validación para esta búsqueda de recomendaciones. Si se establece en true, se usa un modelo falso que devuelve IDs de documentos arbitrarios. Ten en cuenta que el modo de solo validación solo debe usarse para probar la API o si el modelo no está listo.
params

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

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

Valores permitidos:

  • returnDocument: Booleano. Si se establece en true, el objeto Document asociado se devuelve en RecommendResponse.RecommendationResult.document.
  • returnScore: Booleano. Si se establece como verdadero, la puntuación de recomendación correspondiente a cada documento devuelto se establece en RecommendResponse.RecommendationResult.metadata. La puntuación proporcionada indica la probabilidad de una conversión de Documento en función del historial y el contexto del usuario.
  • strictFiltering: Booleano. El valor predeterminado es verdadero. Si se establece en false, el servicio devuelve documentos populares genéricos (sin filtrar) en lugar de vacíos si el filtro bloquea todos los resultados de la recomendación.
  • diversityLevel: Cadena. El valor predeterminado es vacío. Si se configura 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 las recomendaciones según la categoría del documento.
  • attributeFilteringSyntax: Booleano. El valor predeterminado es falso. Si se establece como verdadero, el campo filter se interpreta según la nueva sintaxis basada en atributos.
userLabels

map (key: string, value: string)

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

  • Cada recurso puede tener varias etiquetas, hasta 64.
  • Cada etiqueta debe ser un par clave-valor.
  • Las claves deben tener una longitud mínima de 1 carácter y una longitud máxima de 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 solo pueden contener letras en minúscula, números, 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

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.