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

Faz uma recomendação, que requer um evento do utilizador contextual.

Pedido HTTP

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

O URL usa a sintaxe de transcodificação de 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/*

É criada uma configuração de publicação predefinida juntamente com a criação do motor de recomendações. O ID do motor é usado como o ID da configuração de publicação predefinida. Por exemplo, para o motor projects/*/locations/global/collections/*/engines/my-engine, pode usar projects/*/locations/global/collections/*/engines/my-engine/servingConfigs/my-engine para os seus pedidos RecommendationService.Recommend.

Corpo do pedido

O corpo do pedido 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 utilizador, o que está a ver e que ação realizou para acionar o pedido servingConfigs.recommend. Tenha em atenção que este detalhe do evento do utilizador não é carregado para os registos userEvent. Assim, é necessária uma solicitação de gravação userEvent separada para o registo de eventos.

Não defina UserEvent.user_pseudo_id ou UserEvent.user_info.user_id para o mesmo ID fixo para diferentes utilizadores. Se estiver a tentar receber recomendações não personalizadas (não recomendado; isto pode afetar negativamente o desempenho do modelo), defina UserEvent.user_pseudo_id como um ID único aleatório e deixe UserEvent.user_info.user_id não definido.
pageSize

integer

Número máximo de resultados a devolver. Defina esta propriedade para o número de resultados de recomendações necessários. Se for zero, o serviço escolhe uma predefinição razoável. O valor máximo permitido é 100. Os valores acima de 100 são definidos como 100.
filter

string

Filtro para restringir os resultados de recomendações com um limite de 5000 carateres. Atualmente, apenas são suportadas 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 verdadeiro no campo params, são esperadas expressões baseadas em atributos em vez da sintaxe baseada em etiquetas 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 devolve documentos populares genéricos (não filtrados). Se quiser apenas resultados que correspondam estritamente aos filtros, defina strictFiltering como true em RecommendRequest.params para receber resultados vazios.

Tenha em atenção que a API nunca devolve Documents com storageStatus como EXPIRED ou DELETED, independentemente das escolhas de filtros.
validateOnly

boolean

Use o modo de validação apenas para esta consulta de recomendação. Se estiver definido como true, é usado um modelo falso que devolve IDs de documentos arbitrários. Tenha em atenção que o modo de validação apenas deve ser usado para testar a API ou se o modelo não estiver pronto.
params

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

Parâmetros adicionais específicos do domínio para as recomendações.

Valores permitidos:

  • returnDocument: booleano. Se estiver definido como true, o objeto Document associado é devolvido em RecommendResponse.RecommendationResult.document.
  • returnScore: booleano. Se estiver definido como verdadeiro, a pontuação de recomendação correspondente a cada documento devolvido é definida em RecommendResponse.RecommendationResult.metadata. A pontuação fornecida indica a probabilidade de uma conversão de documentos, dado o contexto e o histórico do utilizador.
  • strictFiltering: booleano. O valor predefinido é True. Se estiver definido como false, o serviço devolve documentos populares genéricos (não filtrados) em vez de vazios se o filtro bloquear todos os resultados de recomendações.
  • diversityLevel: String. Predefinição vazia. Se estiver definido como não vazio, tem de ser um dos seguintes:
    • no-diversity
    • low-diversity
    • medium-diversity
    • high-diversity
    • auto-diversity Isto dá controlo ao nível do pedido e ajusta os resultados das recomendações com base na categoria do documento.
  • attributeFilteringSyntax: booleano. O valor predefinido é False. Se for definido como verdadeiro, o campo filter é interpretado de acordo com a nova sintaxe baseada em atributos.
userLabels

map (key: string, value: string)

As etiquetas de utilizador aplicadas a um recurso têm de cumprir os seguintes requisitos:

  • Cada recurso pode ter várias etiquetas, até um máximo de 64.
  • Cada etiqueta tem de ser um par chave-valor.
  • As chaves têm um comprimento mínimo de 1 carater e um comprimento máximo de 63 carateres, e não podem estar vazias. Os valores podem estar vazios e ter um comprimento máximo de 63 carateres.
  • As chaves e os valores só podem conter letras minúsculas, carateres numéricos, sublinhados e travessões. Todos os carateres têm de usar a codificação UTF-8, e são permitidos carateres internacionais.
  • A parte da chave de uma etiqueta tem de ser exclusiva. No entanto, pode usar a mesma chave com vários recursos.
  • As chaves têm de começar com uma letra minúscula ou um caráter internacional.

Consulte os requisitos para etiquetas para mais detalhes.

Corpo da resposta

Se for bem-sucedido, o corpo da resposta contém uma instância de RecommendResponse.

Âmbitos de autorização

Requer um dos seguintes âmbitos do OAuth:

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

Para mais informações, consulte o Authentication Overview.

Autorizações de IAM

Requer a seguinte autorização de IAM no recurso servingConfig:

  • discoveryengine.servingConfigs.recommend

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