Esta página foi traduzida pela API Cloud Translation.

Filtrar recomendações

Se você tiver um app de recomendações que usa dados estruturados, use os campos de documento para filtrar os resultados das recomendações. Esta página explica como use campos do documento para filtrar uma recomendação para um conjunto específico de documentos. Embora os exemplos desta página sejam para recomendações de mídia, os princípios mostrados aqui são os mesmos para recomendações genéricas. Para mais informações sobre recomendações de mídia, consulte Introdução à Vertex AI para Pesquisa para mídia.

Filtrar recomendações e atualizações do armazenamento de dados

Depois de qualquer atualização da loja de dados, você vai precisar esperar até 8 horas enquanto o modelo é retrainado. Isso ocorre porque o modelo precisa saber sobre os valores atuais em os metadados do documento e quais campos são configurados como filtráveis. É necessário esperar que as mudanças de documento e de esquema sejam propagadas. Para as recomendações (ao contrário da pesquisa), a filtragem não é feita em tempo real.

Filtros e configurações de 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 é é feito primeiro e a filtragem é feita em segundo.

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

Por exemplo, você quer recomendar filmes com base em Toy Story. Você definiu o nível de diversidade com base 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 para crianças filmes são aplicados, 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 mais informações, consulte Criar apps de mídia ou Criar um repositório de dados de recomendações genéricas.

Exemplos de documentos

Confira estes exemplos de documentos de mídia. Você pode consultar esses documentos de exemplo 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 filtros de recomendações.

Sintaxe das expressões de filtro

O formato estendido de Backus-Naur 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 restrições a seguir se aplicam às expressões de filtro para recomendações:

A profundidade da incorporação dos operadores AND e OR entre parênteses é limitada. As expressões lógicas no filtro precisam estar na forma normal conjuntiva (CNF, na sigla em inglês). A expressão lógica mais complexa com suporte pode ser uma lista de cláusulas conectadas por AND que contenha apenas operadores OR, 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. Eles não podem ser usados como parte de uma cláusula OR ou uma negação (NOT). Você só pode usar available: 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 nas expressões ANY(). Se uma cláusula OR tiver várias expressões ANY(), as todos os argumentos contam 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álidos e inválidos. Ele também informa os motivos pelos quais os exemplos 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 um pouco de memória em cada um dos seus modelos. Os limites a seguir ajudam a evitar efeitos adversos no desempenho da exibição:

É possível definir até 10 campos personalizados como filtráveis no 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 campos 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 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.
- Falha no treinamento do app.

Filtrar recomendações

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

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 console do Google Cloud, acesse a página Agent Builder e No menu de navegação, clique em Repositórios de dados.
  
  Acesse 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.
Determine os campos do documento que você quer filtrar. Para exemplo, para os documentos em Antes de começar, você pode usar o campo categories como filtro.
Para tornar o campo categories filtrável, faça o seguinte:
1. No Console do Google Cloud, acesse a página Criador de agentes.
  
  Agent Builder.
2. Clique no app de recomendações.
3. Clique na guia Esquema. Essa guia mostra as configurações atuais do campo.
4. Clique em Editar.
5. Se ainda não estiver selecionada, marque a caixa de seleção Filtrável na categorias e, em seguida, clique em Salvar.
6. Aguarde seis horas para que a edição do esquema seja propagada. Após seis horas, você pode prosseguir para a próxima etapa.
Para receber uma recomendação e filtrar no campo categories, execute o código a seguir 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"
```
- PROJECT_ID: o ID do seu projeto.
- DATA_STORE_ID: o ID do repositório de dados.
- DOCUMENT_ID: o ID do documento que você quer visualizar recomendações. Use o ID que você usou para este documento no momento em que fez a transferência dos dados.
- EVENT_TYPE: o tipo de evento do usuário. Para valores eventType, consulte UserEvent.
- USER_PSEUDO_ID: um identificador pseudonimizado do usuário. Você pode usar um cookie HTTP nesse campo, que identifica exclusivamente um visitante em um único dispositivo. Não defina este campo como o mesmo identificador para vários usuários. Isso combinaria os históricos de eventos e degradam a qualidade dos modelos. Não inclua informações de identificação pessoal (PII) neste campo.
- SERVING_CONFIG_ID: o ID da sua configuração de veiculação. O ID da configuração de veiculação é o mesmo que o ID do mecanismo. Use o ID do mecanismo aqui.
- FILTER: um campo de texto que permite filtrar um conjunto específico. usando a sintaxe da expressão de filtro. O valor padrão é um valor vazio , 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 e queira filtrar os resultados da recomendação para que eles contenham apenas documentos que estejam: (1) na categoria "Crianças" e (2) disponíveis no momento. Para isso, inclua as seguintes instruções na chamada:
- "eventType": "media-play"
- "filter": "categories: ANY(\"Children\") AND available: true"
Para mais informações, consulte o método recommend.
Clique para conferir um exemplo de resposta.

Se você fizer uma solicitação de recomendação como a anterior, vai esperar para receber uma resposta semelhante a esta. Observe que a resposta inclui os dois documentos que têm um valor categories de Children e um valor availability_start_time que é 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",
"debugInfo": {
  "fallbackModelInvoked": false
}
}
```