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 usar campos de documentos 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 as recomendações de mídia, consulte Introdução à Vertex AI Search for media.

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

Depois de qualquer atualização da repositório de dados, você vai precisar esperar até 8 horas enquanto o modelo é retrainado. Isso ocorre porque o modelo precisa saber sobre os valores atuais nos metadados do documento e quais campos estã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 é feita primeiro e a filtragem, depois.

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 filmes infantis é aplicado, apenas WALL·E é retornado como uma 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 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 os 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 de inserção de 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. Elas não podem ser usadas como parte de uma cláusula OR ou uma negação (NOT). Só é possível 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 em expressões ANY(). Se uma cláusula OR tiver várias expressões ANY(), todos os argumentos dela serão contabilizados 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. 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 na performance de veiculaçã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 milhões de 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 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 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 Criador de agentes 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 o campo ou os campos do documento que você quer filtrar. Por exemplo, para os documentos em Antes de começar, você pode usar o campo categories como um 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 linha categorias e 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 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"
```
- PROJECT_ID: o ID do seu projeto.
- DATA_STORE_ID: o ID do repositório de dados.
- DOCUMENT_ID: o ID do documento para o qual você quer visualizar as 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 pseudônimo do usuário. Você pode usar um cookie HTTP para esse campo, que identifica com exclusividade 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 degradaria a qualidade do modelo. 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 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 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, poderá receber uma resposta semelhante a esta. A resposta inclui os dois documentos com um valor de categories de Children e um valor de 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"
}
```