Filtrar recomendações

Se você tiver um app de recomendações, poderá usar campos de documentos para filtrar os resultados das recomendações. Nesta página, explicamos como usar campos de documentos para filtrar uma recomendação para um conjunto específico de documentos. Embora os exemplos nesta página sejam para recomendações de mídia, os princípios mostrados aqui são os mesmos para recomendações personalizadas. Para mais informações sobre recomendações de mídia, consulte Introdução à pesquisa de agentes para mídia.

Filtrar recomendações e atualizações do repositório de dados

Após qualquer atualização do repositório de dados, será necessário aguardar até 8 horas enquanto o modelo é treinado novamente. Isso ocorre porque o modelo precisa saber sobre os valores atuais nos metadados do documento, bem como quais campos estão configurados como filtráveis. É necessário aguardar a propagação das mudanças de documentos e de esquema. Para recomendações (ao contrário da pesquisa), a filtragem não é feita em tempo real.

Configurações de filtros e diversificação (somente recomendações de mídia)

Além dos filtros, a configuração de diversificação de um app também afeta os resultados retornados em uma resposta de recomendação de mídia. Os efeitos dos filtros e da diversificação são combinados. A diversificação é feita primeiro e a filtragem é feita em segundo.

A combinação de diversidade alta baseada em regras e filtragem de atributos baseada em categorias geralmente resulta em saída vazia. Isso ocorre porque a alta diversidade limita o app a retornar um resultado para cada categoria.

Por exemplo, você quer recomendar filmes com base em Toy Story. Você define o nível de diversidade baseado em regras como alto. Como o nível de diversidade é alto, embora muitos filmes possam ser recomendados, apenas um filme (por exemplo, WALL·E) na categoria de filmes infantis é retornado. Quando o filtro de filmes infantis é aplicado, apenas WALL·E é retornado como recomendação.

Para informações gerais sobre diversidade, consulte Diversificar recomendações de mídia.

Antes de começar

Verifique se você criou um app de recomendações e um repositório de dados. Para mais informações, consulte Criar apps de mídia ou Criar um repositório de dados de recomendações personalizadas.

Exemplos de documentos

Analise estes exemplos de documentos de mídia. Você pode consultar esses exemplos de documentos enquanto lê esta página.

{"id":"1","schemaId":"default_schema","structData":{"title":"Toy Story (1995)","categories":["Adventure","Animation","Children","Comedy","Fantasy"],"uri":"http://mytestdomain.movie/content/1","available_time":"2023-01-01T00:00:00Z","media_type":"movie"}}
{"id":"88125","schemaId":"default_schema","structData":{"title":"Harry Potter and the Deathly Hallows: Part 2 (2011)","categories":["Action","Adventure","Drama","Fantasy","Mystery","IMAX"],"uri":"http://mytestdomain.movie/content/88125","available_time":"2023-01-01T00:00:00Z","media_type":"movie"}}
{"id":"2857","schemaId":"default_schema","structData":{"title":"Yellow Submarine (1968)","categories":["Adventure","Animation","Comedy","Fantasy","Musical"],"uri":"http://mytestdomain.movie/content/2857","available_time":"2023-01-01T00:00:00Z","media_type":"movie"}}
{"id":"60069","schemaId":"default_schema","structData":{"title":"WALL·E (2008)","categories":["Adventure","Animation","Children","Romance","Sci-Fi"],"uri":"http://mytestdomain.movie/content/60069","available_time":"2023-01-01T00:00:00Z","media_type":"movie"}}

Expressões de filtro

Use expressões de filtro para definir os filtros de recomendações.

Sintaxe de expressões de filtro

O formulário Backus-Naur estendido a seguir resume a sintaxe da expressão de filtro que você pode usar para definir os filtros de recomendações.

  # A single expression or multiple expressions that are joined by "AND" or "OR".
  filter = expression, { " AND " | "OR", expression };
  # An expression can be prefixed with "-" or "NOT" to express a negation.
  expression = [ "-" | "NOT " ],
    # A parenthesized expression
    | "(", expression, ")"
    # A simple expression applying to a textual field.
    # Function "ANY" returns true if the field contains any of the literals.
    textual_field, ":", "ANY", "(", literal, { ",", literal }, ")"
    # OR filter by "available"
    available, ":", "true",
  # A literal is any double-quoted string. You must escape backslash (\) and
  # quote (") characters.
  literal = double-quoted string;
  textual_field = see the tables below;

Restrições de expressões de filtro

As seguintes restrições se aplicam a expressões de filtro para recomendações:

  • A profundidade da incorporação de operadores AND e OR entre parênteses é limitada. As expressões lógicas no filtro precisam estar na forma normal conjuntiva (CNF). A expressão lógica compatível mais complexa pode ser uma lista de cláusulas conectadas por AND que contenham apenas OR operadores, como: (... OR ... OR ...) AND (... OR ...) AND (... OR ...)

  • As expressões podem ser negadas com a palavra-chave NOT ou com -. Isso só funciona com expressões ANY() com um único argumento.

  • As restrições available precisam estar no nível superior. Elas não podem ser usadas como parte de uma cláusula OR ou uma negação (NOT). Só é possível usar available: true. Se você omitir esse filtro, documentos expirados e documentos ainda não disponíveis poderão ser retornados como recomendações.

    O campo available é mapeado para a seguinte lógica:

    datetime.now >= available_time AND datetime.now <= expire_time

    Se o expire_time não estiver definido, datetime.now <= expire_time será resolvido como true.

  • O número máximo de termos na cláusula AND de nível superior é 20.

  • Uma cláusula OR pode ter até 100 argumentos incluídos em expressões ANY(). Se uma cláusula OR tiver várias expressões ANY(), todos os argumentos serão contados para esse limite. Por exemplo, categories: ANY("drama", "comedy") OR categories: ANY("adventure") tem três argumentos.

Exemplos de expressões de filtro

A tabela a seguir mostra exemplos de expressões de filtro válidas e inválidas. Ela também informa os motivos pelos quais os exemplos inválidos são inválidos.

Expressão Válido Observações
language_code: ANY("en", "fr") Sim
NOT language_code: ANY("en") Sim
NOT language_code: ANY("en", "fr") Não Nega um ANY() com mais de um argumento.
language_code: ANY("en", "fr") OR categories: ANY("drama") Sim
(language_code: ANY("en") OR language_code: ANY("fr")) AND categories: ANY("drama") Sim
(language_code: ANY("en") AND language_code: ANY("fr")) OR categories: ANY("drama") Não Não está na forma normal conjuntiva.
(language_code: ANY("en")) AND (available: true) Sim
(language_code: ANY("en")) OR (available: true) Não Combina available em uma expressão OR com outras condições.

A expressão de filtro a seguir filtra documentos que estão na categoria de drama ou ação, que não estão em inglês e que estão disponíveis:

categories: ANY("drama", "action") AND NOT language_code: ANY("en") AND available: true

Limites de filtragem

Cada campo de documento filtrável consome alguma memória em cada um dos seus modelos. Os limites a seguir ajudam a evitar efeitos adversos no desempenho da veiculação:

  • Até 10 campos personalizados podem ser definidos como filtráveis no seu esquema.

    Se mais de 10 campos personalizados forem encontrados durante o treinamento do app, apenas 10 serão usados.

  • Até 100.000.000 valores de campo filtráveis podem estar presentes no seu esquema.

    Para estimar o número total de valores de campo filtráveis no seu esquema, multiplique o número de documentos no esquema pelo número de campos filtráveis. Se você exceder esses limites, o seguinte vai acontecer:

    • Não é possível definir outros campos como filtráveis.
    • O treinamento do app falha.

Filtrar recomendações

Para filtrar recomendações de mídia, siga estas etapas:

  1. Encontre o ID do repositório de dados. Se você já tiver o ID do repositório de dados, pule para a próxima etapa.

    1. No Google Cloud console, acesse a página Aplicativos de IA e no menu de navegação, clique em Repositórios de dados.

      Acessar a página "Repositórios de dados"

    2. Clique no nome do seu repositório de dados.

    3. Na página Dados do seu repositório de dados, encontre o ID do repositório.

  2. Determine o campo ou campos de documento que você quer filtrar. Por exemplo, para os documentos em Antes de começar, você pode usar o campo categories como um filtro.

  3. Para tornar o campo categories filtrável, faça o seguinte:

    1. No Google Cloud console, acesse a página Aplicativos de IA.

      Aplicativos de IA

    2. Clique no app de recomendações.

    3. Clique na guia Esquema. Essa guia mostra as configurações de campo atuais.

    4. Clique em Editar.

    5. Se ainda não estiver selecionada, marque a caixa de seleção Filtrável na linha categories e clique em Salvar.

    6. Aguarde seis horas para que a edição do esquema seja propagada. Após seis horas, você pode passar para a próxima etapa.

  4. Para receber uma recomendação e filtrar o campo categories, execute o seguinte código na linha de comando:

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
     "userEvent": {
       "eventType": "EVENT_TYPE",
       "userPseudoId": "USER_PSEUDO_ID",
       "documents": {
         "id": "DOCUMENT_ID"
       }
     },
     "params": {
       "returnDocument": true,
       "attributeFilteringSyntax": true,
       "strictFiltering": true
     },
     "filter": "FILTER"
   }' \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/SERVING_CONFIG_ID:recommend"

    Substitua:

    • PROJECT_ID: ID do projeto.
    • DATA_STORE_ID: ID do repositório de dados.
    • DOCUMENT_ID: ID do documento para o qual você quer visualizar as recomendações. Use o ID que você usou para esse documento no momento da ingestão dos dados.
    • EVENT_TYPE: o tipo de evento do usuário. Para eventType valores, consulte UserEvent.
    • USER_PSEUDO_ID: uma string codificada em UTF-8, que atua como um identificador pseudonimizado exclusivo que rastreia os usuários. Ele pode ter um comprimento máximo de 128 caracteres. O Google recomenda o uso desse campo porque ele melhora o desempenho do modelo e a qualidade da personalização. Você pode usar um cookie HTTP para esse campo, que identifica exclusivamente um visitante em um único dispositivo. Algumas considerações importantes são as seguintes:

      • Esse identificador não muda quando o visitante faz login ou logout de um site.
      • Esse campo não pode ser definido como o mesmo identificador para vários usuários. Caso contrário, o mesmo ID de usuário poderá combinar históricos de eventos de diferentes usuários e degradar a qualidade do modelo.
      • Esse campo não pode incluir informações de identificação pessoal (PII).

      Para mais informações, consulte userPseudoId.

    • SERVING_CONFIG_ID: ID da configuração de veiculação. O ID da configuração de veiculação é o mesmo que o ID do mecanismo. Portanto, use o ID do mecanismo aqui.
    • FILTER: um campo de texto que permite filtrar um conjunto especificado de campos usando a sintaxe da expressão de filtro. O valor padrão é uma string vazia, o que significa que nenhum filtro é aplicado.

    Por exemplo, suponha que você queira uma recomendação para um evento de usuário de reprodução de mídia específico e queira filtrar os resultados da recomendação para conter apenas documentos que estejam: (1) na categoria "Crianças" e (2) disponíveis no momento. Para fazer isso, inclua as seguintes declarações na chamada:

    • "eventType": "media-play"
    • "filter": "categories: ANY(\"Children\") AND available: true"

    Para mais informações, consulte o recommend método.

    Clique para conferir um exemplo de resposta.

    Se você fizer uma solicitação de recomendação como a anterior, poderá receber uma resposta semelhante à seguinte. Observe que a resposta inclui os dois documentos que têm um valor categories de Children e um valor availability_start_time posterior à data atual.

    {
"results": [
  {
    "id":"1",
    "schemaId":"default_schema",
    "structData":{"title":"Toy Story (1995)","categories":["Adventure","Animation","Children","Comedy","Fantasy"],"uri":"http://mytestdomain.movie/content/1",
    "availability_start_time":"2023-01-01T00:00:00Z",
    "media_type":"movie"
    }
  },
  {
    "id":"60069",
    "schemaId":"default_schema",
    "structData":{"title":"WALL·E (2008)","categories":["Adventure","Animation","Children","Romance","Sci-Fi"],"uri":"http://mytestdomain.movie/content/60069",
    "availability_start_time":"2023-01-01T00:00:00Z",
    "media_type":"movie"
    }
  }
],
"attributionToken": "ChMzMDk3NTQ4MzQxOTcxOTE0ODM1GglhZi10ZXN0LTEiDmFmLXRlc3QtMTE0NTE0KAAwBg"
}