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

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

Solicitação HTTP

POST https://discoveryengine.googleapis.com/v1beta/{servingConfig=projects/*/locations/*/collections/*/engines/*/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 junto com o mecanismo de recomendação. O ID do mecanismo é usado como o ID da configuração de veiculação padrão. Por exemplo, para o Engine projects/*/locations/global/collections/*/engines/my-engine, é possível usar projects/*/locations/global/collections/*/engines/my-engine/servingConfigs/my-engine nas 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á olhando e qual ação ele realizou para acionar a solicitação "servingConfigs.recommend". Esses detalhes não serão ingeridos nos registros de userEvent. Portanto, é necessário fazer uma solicitação de gravação userEvent separada para o registro de eventos.

Não defina UserEvent.user_pseudo_id ou UserEvent.user_info.user_id com 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 sem definição.
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, só há suporte para expressões de filtro no atributo filterTags.

Exemplos:

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

Se attributeFilteringSyntax estiver definido como "true" no campo params, serão esperadas expressões baseadas em atributos em vez da sintaxe baseada em tag 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 populares genéricos (sem filtro). 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, independente das opções de filtro.
validateOnly

boolean

Use o modo "validar apenas" para esta consulta de recomendação. Se definido como true, um modelo simulado será usado e vai retornar IDs de documentos arbitrários. O modo "validate only" 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 Document associado será retornado em RecommendResponse.RecommendationResult.document.
  • returnScore: booleano. Se definido como "true", 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) em vez de vazios se o filtro bloquear todos os resultados de recomendação.
  • diversityLevel: string. O padrão é vazio. Se definido como não vazio, ele precisará ser um destes:
    • no-diversity
    • low-diversity
    • medium-diversity
    • high-diversity
    • auto-diversity Isso oferece controle no nível da solicitação e ajusta os resultados da recomendação com base na categoria do documento.
  • attributeFilteringSyntax: booleano. O padrão é "falso". Se definido como "true", 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 comprimento mínimo de um caractere e comprimento 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 traços. 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, é possível 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

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.