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

Hace una recomendación, lo que requiere un evento de usuario contextual.

Solicitud HTTP

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

La URL utiliza la sintaxis de transcodificación a gRPC.

Parámetros de ruta

Parámetros
servingConfig

string

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

Se crea una configuración de servicio predeterminada junto con el motor de recomendaciones. El ID de motor se usa como ID de la configuración de publicación predeterminada. Por ejemplo, en el caso del 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 que presentan 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 la acción que ha realizado para activar la solicitud servingConfigs.recommend. Ten en cuenta que este detalle del evento de usuario no se incluirá en los registros userEvent. Por lo tanto, se necesita una solicitud de escritura de userEvent independiente para registrar eventos.

No asigne el mismo ID fijo a UserEvent.user_pseudo_id o UserEvent.user_info.user_id para diferentes usuarios. Si quieres recibir recomendaciones no personalizadas (no es recomendable, ya que puede afectar negativamente al rendimiento del modelo), asigna a UserEvent.user_pseudo_id un ID único aleatorio y deja UserEvent.user_info.user_id sin asignar.
pageSize

integer

Número máximo de resultados que se devolverán. Asigna a esta propiedad el número de resultados de recomendación que necesites. Si es cero, el servicio elige un valor predeterminado razonable. El valor máximo permitido es 100. Los valores superiores a 100 se definen como 100.
filter

string

Filtro para restringir los resultados de las recomendaciones con un límite de longitud de 5000 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 tiene el valor "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 devuelve documentos populares genéricos (sin filtrar). Si solo quieres obtener resultados que coincidan exactamente con los filtros, asigna el valor true a strictFiltering en RecommendRequest.params para recibir resultados vacíos.

Ten en cuenta que la API nunca devuelve Documents con storageStatus como EXPIRED o DELETED, independientemente de los filtros elegidos.
validateOnly

boolean

Usa el modo de solo validación para esta consulta de recomendación. Si se asigna el valor true, se usa un modelo falso que devuelve IDs de documento 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))

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

Valores permitidos:

  • returnDocument: booleano. Si se le asigna el valor true, el objeto Document asociado se devuelve en RecommendResponse.RecommendationResult.document.
  • returnScore: booleano. Si se define como true, la puntuación de recomendación correspondiente a cada documento devuelto se define en RecommendResponse.RecommendationResult.metadata. La puntuación indica la probabilidad de que se produzca una conversión de documento en función del contexto y el historial del usuario.
  • strictFiltering: booleano. "True" de forma predeterminada Si se define como false, el servicio devuelve documentos populares genéricos (sin filtrar) en lugar de estar vacío si el filtro bloquea todos los resultados de recomendación.
  • diversityLevel: cadena. El valor predeterminado es una cadena vacía. Si se asigna un valor 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 solicitud y ajusta los resultados de las recomendaciones en función de la categoría del documento.
  • attributeFilteringSyntax: booleano. El valor predeterminado es "false". Si se define como true, el campo filter se interpreta según la nueva sintaxis basada en atributos.
userLabels

map (key: string, value: string)

Las etiquetas de usuario aplicadas a un recurso deben cumplir los siguientes requisitos:

  • Cada recurso puede tener varias etiquetas, hasta un máximo de 64.
  • Cada etiqueta debe ser un par clave-valor.
  • Las claves tienen 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 tener una longitud máxima de 63 caracteres.
  • Las claves y los valores solo pueden contener letras en minúscula, caracteres numéricos, guiones bajos y guiones. Todos los caracteres deben usar la codificación UTF-8 y se pueden utilizar caracteres internacionales.
  • La parte de la clave de una etiqueta debe ser única. Sin embargo, puedes usar la misma clave con varios recursos.
  • Las claves deben empezar por una letra minúscula o un carácter internacional.

Consulta los requisitos de las etiquetas para obtener más información.

Cuerpo de la respuesta

Si la solicitud se hace correctamente, en el cuerpo de la respuesta se incluye una instancia de RecommendResponse.

Permisos de autorización

Debes disponer de 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 el Authentication Overview.

Permisos de IAM

Requiere el siguiente permiso de gestión de identidades y accesos en el recurso servingConfig:

  • discoveryengine.servingConfigs.recommend

Para obtener más información, consulta la documentación de gestión de identidades y accesos.