Method: projects.locations.dataStores.servingConfigs.recommend

Faz uma recomendação, que exige um evento contextual do usuário.

Solicitação HTTP

POST https://discoveryengine.googleapis.com/v1alpha/{servingConfig=projects/*/locations/*/dataStores/*/servingConfigs/*}:recommend

O URL usa a sintaxe de transcodificação gRPC.

Parâmetros de caminho

Parâmetros
servingConfig

string

Obrigatório. Nome completo do recurso de um ServingConfig: projects/*/locations/global/collections/*/engines/*/servingConfigs/* ou projects/*/locations/global/collections/*/dataStores/*/servingConfigs/*

Uma configuração de exibição padrão é criada com a criação do mecanismo de recomendação. O ID do mecanismo é usado como o ID da configuração de exibição padrão. Por exemplo, para o mecanismo projects/*/locations/global/collections/*/engines/my-engine, você pode usar projects/*/locations/global/collections/*/engines/my-engine/servingConfigs/my-engine para suas solicitações RecommendationService.Recommend.

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

Representação JSON 
{
  "userEvent": {
    object (UserEvent)
  },
  "pageSize": integer,
  "filter": string,
  "validateOnly": boolean,
  "params": {
    string: value,
    ...
  },
  "userLabels": {
    string: string,
    ...
  }
}
Campos
userEvent

object (UserEvent)

Obrigatório. Contexto sobre o usuário, o que ele está visualizando e qual ação ele realizou para acionar a solicitação servingConfigs.recommend. Esse detalhe do evento do usuário não será ingerido nos registros userEvent. Portanto, uma solicitação de gravação userEvent separada é necessária para o registro de eventos.

Não defina UserEvent.user_pseudo_id ou UserEvent.user_info.user_id como o mesmo ID fixo para usuários diferentes. Se você estiver tentando receber recomendações não personalizadas (não recomendado, isso pode afetar negativamente a performance do modelo), defina UserEvent.user_pseudo_id como um ID exclusivo aleatório e deixe UserEvent.user_info.user_id não definido.
pageSize

integer

Número máximo de resultados a serem retornados. Defina essa propriedade como o número de resultados de recomendação necessários. Se for zero, o serviço vai escolher um padrão razoável. O valor máximo permitido é 100. Valores acima de 100 são definidos como 100.
filter

string

Filtro para restringir os resultados de recomendação com um limite de 5.000 caracteres. No momento, apenas expressões de filtro no atributo filterTags são aceitas.

Exemplos:

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

Se attributeFilteringSyntax estiver definido como verdadeiro no campo params, expressões baseadas em atributos serão esperadas em vez da sintaxe baseada em tags descrita acima. Exemplos:

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

Se o filtro bloquear todos os resultados, a API vai retornar documentos genéricos (não filtrados) populares. Se você quiser apenas resultados que correspondam estritamente aos filtros, defina strictFiltering como true em RecommendRequest.params para receber resultados vazios.

A API nunca retorna Documents com storageStatus como EXPIRED ou DELETED, independentemente das opções de filtro.
validateOnly

boolean

Use o modo de validação apenas para essa consulta de recomendação. Se definido como true, um modelo falso será usado e retornará IDs de documentos arbitrários. O modo de validação só deve ser usado para testar a API ou se o modelo não estiver pronto.
params

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

Outros parâmetros específicos do domínio para as recomendações.

Valores permitidos:

  • returnDocument: booleano. Se definido como true, o objeto de documento associado será retornado em RecommendResponse.RecommendationResult.document.
  • returnScore: booleano. Se definido como verdadeiro, a pontuação de recomendação correspondente a cada documento retornado será definida em RecommendResponse.RecommendationResult.metadata. A pontuação indica a probabilidade de uma conversão de documento, considerando o contexto e o histórico do usuário.
  • strictFiltering: booleano. "True" por padrão. Se definido como false, o serviço vai retornar documentos genéricos (não filtrados) populares em vez de vazios se o filtro bloquear todos os resultados de recomendação.
  • diversityLevel: string. Padrão vazio. Se definido como não vazio, ele precisa ser um destes:
    • no-diversity
    • low-diversity
    • medium-diversity
    • high-diversity
    • auto-diversity: oferece controle no nível da solicitação e ajusta os resultados de recomendação com base na categoria do documento.
  • attributeFilteringSyntax: booleano. Falso por padrão. Se definido como verdadeiro, o campo filter será interpretado de acordo com a nova sintaxe baseada em atributos.
userLabels

map (key: string, value: string)

Os rótulos de usuário aplicados a um recurso precisam atender aos seguintes requisitos:

  • Cada recurso pode ter vários rótulos, até um máximo de 64.
  • Cada rótulo precisa ser um par de chave-valor.
  • As chaves têm um comprimento mínimo de 1 caractere e um máximo de 63 caracteres e não podem estar vazias. Os valores podem estar vazios e ter um comprimento máximo de 63 caracteres.
  • As chaves e os valores podem conter apenas letras minúsculas, caracteres numéricos, sublinhados e hífens. Todos os caracteres precisam usar a codificação UTF-8, e os caracteres internacionais são permitidos.
  • A parte da chave de um rótulo precisa ser única. No entanto, você pode usar a mesma chave com vários recursos.
  • As chaves precisam começar com uma letra minúscula ou um caractere internacional.

Consulte Requisitos para rótulos para mais detalhes.

Corpo da resposta

Se a solicitação for bem-sucedida, o corpo da resposta conterá uma instância de RecommendResponse.

Escopos de autorização

Requer um dos seguintes escopos do OAuth:

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

Para mais informações, consulte Authentication Overview.

Permissões do IAM

Requer a seguinte permissão do IAM no recurso servingConfig:

  • discoveryengine.servingConfigs.recommend

Para mais informações, consulte a documentação do IAM.