Otimizar e ocultar recomendações de mídia

Nesta página, explicamos como mudar a posição de classificação das recomendações de mídia retornadas pelo modelo usando controles de veiculação de reforço (também chamados de controles).

Um controle de aumento muda a ordem das recomendações depois que elas foram retornadas pelo modelo. Você aplica uma expressão de filtro aos resultados para identificar quais recomendações quer otimizar ou ocultar e, em seguida, aplica um valor de otimização entre -1 e +1. Um valor de aumento de +1 oferece o maior aumento a uma recomendação, colocando-a no topo das recomendações retornadas. Um valor de -1 esconde a recomendação na parte de baixo da lista de recomendações retornadas.

O aumento é um controle de tempo de veiculação. Primeiro, o modelo de recomendações retorna uma lista de recomendações. Usando uma configuração de exibição, o controle de aumento é aplicado a essa lista para ajustar a classificação das recomendações. O controle de aumento não adiciona nem exclui recomendações, mas controla a ordem em que elas são apresentadas ao usuário.

Aumentar as recomendações em vez de filtrá-las

O Boost é um filtro suave. Já o filtro normal para recomendações, descrito em Filtrar recomendações, é um filtro rígido.

Se você aplicar um filtro rígido às recomendações, nunca vai encontrar os documentos filtrados. No entanto, com um filtro flexível, você não remove documentos da lista de recomendações. Em vez disso, o filtro é usado para determinar quais documentos precisam estar mais altos ou mais baixos na lista de recomendações retornadas.

Evite inundar seu modelo de recomendações

Ao aplicar um filtro de otimização ou ocultação, valores pequenos próximos a zero são recomendados. Valores próximos a +1 ou -1 provavelmente vão sobrecarregar o modelo de recomendações, de modo que a classificação de recomendações aplicada pelo modelo não seja refletida na ordem em que o usuário vê as recomendações.

Por exemplo, se você aumentar os filmes animados com +1, os usuários só vão ver filmes animados na parte de cima da lista de recomendações. Isso empurra os filmes não animados que foram altamente recomendados pelo modelo para a parte de baixo da lista, onde o usuário pode não encontrá-los.

Rebaixamento x arquivamento

A despromoção e a ocultação movem as recomendações para posições mais baixas na lista de recomendações retornadas que seriam exibidas de outra forma.

No entanto, a rebaixa é baseada na idade do conteúdo ou se o usuário já assistiu parte dele. Para mais informações sobre a redução, consulte Rebaixar recomendações de mídia.

O ocultamento se aplica ao conteúdo identificado por um filtro. O filtro pode ser qualquer campo de dados marcado como filtrável no esquema. Para informações gerais sobre filtros de recomendação, incluindo como marcar um campo como filtrável, consulte Filtros de recomendação.

Sobre os controles de boost e as configurações de exibição

Cada controle de veiculação de aumento é composto por um filtro e um valor de aumento. Por exemplo, um controle de aumento aumenta os filmes com "Christmas" no título com um valor de 0.1, e outro enterra filmes de terror com um valor de -0.2.

Depois de criar um ou mais controles de aumento, anexe os controles a uma configuração de exibição. Quando qualquer app de pesquisa da Vertex AI é criado, uma configuração de exibição padrão também é criada automaticamente. A configuração de exibição é referenciada no momento da exibição para determinar quais resultados o app gera. Além dos controles de aumento, a configuração de veiculação pode conter outros tipos de controles, como diversificar e rebaixar.

A configuração de veiculação pode ser aplicada quando você chama o método de recomendação. Todos os controles na configuração de veiculação são aplicados às recomendações retornadas pela chamada de método.

Além disso, é possível ter várias configurações de exibição associadas ao app. Isso permite aplicar diferentes conjuntos de controles em diferentes circunstâncias. Por exemplo, se a solicitação de recomendação vier de uma conta de criança, aumente os filmes em categorias adequadas para crianças e oculte os inadequados. Da mesma forma, se a solicitação vier de uma conta marcada como adulta, aumente os títulos ou as categorias que são populares entre adultos. Como alternativa, você pode escolher ter configurações de veiculação diferentes para locais geográficos diferentes e aumentar o conteúdo de acordo com o que é popular na região. Para mais informações sobre configurações de exibição, consulte Criar e gerenciar configurações de exibição de mídia.

Os valores de otimização são aditivos

Se você tiver anexado vários controles de exibição a uma configuração de exibição, os aumentos e os ocultamentos vão se tornar aditivos.

Por exemplo, se você aumentar os filmes infantis animados em 0,3 e os filmes de aventura animados em 0,4, um filme que é categorizado como aventura infantil animada será aumentado em 0,7.

Da mesma forma, se um filme de terror for aumentado em 0,2 por um controle e reduzido em -0,3 por outro controle na mesma configuração de veiculação, o resultado líquido será reduzir o filme em -0,1.

A soma dos boosts pode ser maior que +1. Por exemplo, se os controles aumentassem os filmes de animação infantil em 0,6 e os filmes de aventura animados em 0,5, um filme de aventura animado infantil seria aumentado em +1,1.

Exemplos de filtros

Confira a seguir alguns exemplos de filtros para recomendações de mídia.

Filtros em propriedades de chave comuns

Exemplos de filtros em propriedades de string de chave comuns (category, image_name, image_uri, language, title e uri).

  • Animações para crianças:
    "filter": "categories: ANY(\"animation\") AND categories: ANY(\"children\")"

  • Mídia assustadora:
    "filter": "categories: ANY(\"horror\", \"thriller\", \"crime\")

  • Mídias com o título "Christmas":
    "filter": "title: ANY(\"Christmas\")"

  • Mídia em que o primeiro item na matriz images tem o name "bola de praia":
    "filter": "images[0].name: ANY(\"beach ball\")"

Filtros nas propriedades da chave de mídia

Exemplos de filtros em propriedades de chave de mídia. As propriedades da chave de mídia começam com media_ e, na sintaxe do filtro, o nome do campo é precedido por media_key_properties.. Para conferir uma lista de propriedades de chave de mídia, consulte Esquema predefinido do Google em comparação com o esquema personalizado.

  • Mídias em que o tipo é audio:
    "filter": "media_key_properties.media_type: ANY(\"audio\")"

  • Mídia em que a matriz "hash_tags" contém uma string #winter:
    "filter": "media_key_properties.hash_tags: ANY(\"#winter\")"

  • Mídia em que o primeiro elemento da matriz "hash_tags" é a string #winter:
    "filter": "media_key_properties.hash_tags[0]: ANY(\"#winter\")"

Campos personalizados

Exemplos de filtros em campos personalizados. Para atributos personalizados, antecipe o nome do campo com attributes..

  • Você tem um campo de string personalizado, festival, no esquema para representar em qual festival de cinema um filme estreou. Para filtrar apenas os filmes que estrearam em Cannes:
    "filter": "attributes.festival: ANY(\"Cannes\")

  • Você tem um campo booleano personalizado, audio_desc, que é verdadeiro quando a mídia inclui uma descrição em áudio para espectadores com deficiência visual. Para filtrar mídias com uma descrição de áudio:
    "filter": "attributes.audio_desc: ANY(true)"

Limitações nos campos que aceitam filtros

As limitações a seguir se aplicam aos controles de exibição do Boost:

  • Somente campos de propriedade dos tipos string e booleano podem ser usados em expressões de filtro para o aumento.

  • Não é possível filtrar campos aninhados em mais de um nível. Por exemplo, é possível filtrar em persons.name, mas não em um campo persons.name.stage, mesmo que ele exista.

  • Os filtros precisam ser correspondências exatas. Isso significa que, nos exemplos, um filme chamado "Christmas Story" ou "CHRISTMAS" não seria impulsionado.

Antes de começar

Otimize ou oculte recomendações

Este procedimento descreve como criar controles de aumento e anexar os controles a uma configuração de exibição.

Depois que os controles forem anexados à configuração de exibição, será possível especificar a configuração de exibição ao chamar o método servingConfigs.recommend, e o controle de aprimoramento será usado para influenciar a ordem das recomendações retornadas.

REST

Para criar controles de exibição de reforço e anexá-los a uma configuração de exibição, siga estas etapas:

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

    1. No Console do Google Cloud, acesse a página Criador de agentes.

      Acessar "Apps".

    2. Na página Apps, encontre o nome do app e confira o ID dele na coluna ID.

  2. 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.

  3. Criar um controle de aumento:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-H "X-Goog-User-Project: PROJECT_NUMBER" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
      "displayName": "CONTROL_DISPLAY_NAME",
          "solutionType": "SOLUTION_TYPE_RECOMMENDATION",
          "boostAction": {
               "dataStore": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/dataStores/DATA_STORE_ID",
               "boost" :  BOOST_VALUE,
               "filter": "FILTER"
          }
    }'

    • PROJECT_NUMBER: o número do seu projeto do Google Cloud.

    • CONTROL_DISPLAY_NAME: um nome legível para identificar o controle. Precisa ser uma string UTF-8 com um comprimento máximo de 128 caracteres.

    • CONTROL_ID: um identificador exclusivo (em um repositório de dados) para o controle. O ID pode conter letras minúsculas, dígitos, hífens e sublinhados.

    • APP_ID: o ID do app da Vertex AI para Pesquisa.

    • DATA_STORE_ID: o ID do repositório de dados da Vertex AI para Pesquisa.

    • BOOST_VALUE: um número de ponto flutuante no intervalo [-1,1]. Quando o valor é negativo, as recomendações aparecem mais abaixo nos resultados. Quando o valor é positivo, as recomendações são promovidas (elas aparecem mais acima nos resultados).

    • FILTER: a expressão de filtro que descreve quais documentos serão impulsionados ou ocultados. Para informações detalhadas sobre como formular a expressão de filtro, consulte Expressões de filtro.

  4. Repita a etapa 3 para cada controle de aumento que você quer aplicar às suas recomendações. Por exemplo, você pode querer um controle de aumento que aumente filmes infantis, boost-kids, e um segundo controle que oculte filmes de terror, bury-horror.

  5. Encontre o ID da configuração de veiculação. Se você já tiver o ID de configuração de veiculação, pule para a próxima etapa.

    1. No Console do Google Cloud, acesse a página Criador de agentes.

      Acessar "Apps".

    2. Na página Apps, clique no nome do app.

    3. Acesse a página Configurações e clique na guia Exibição.

    4. Extraia o ID da configuração de exibição da coluna ID.

  6. Anexe o novo controle de veiculação do aumento à configuração de veiculação com uma solicitação de atualização usando o método engines.servingConfigs.patch.

    curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/CONFIG_ID?update_mask=boost_control_ids" \
-d '{
  "boostControlIds": ["CONTROL_ID"]
}'

    Substitua:

    • CONFIG_ID: o ID da configuração de veiculação que você quer anexar aos controles de aumento, por exemplo, my_app-1234567_id. Consulte a etapa anterior.

    • CONTROL_ID: contém os IDs de um ou mais controles de veiculação do aumento que você quer anexar à configuração de veiculação. Por exemplo, "boost-kids", "bury-horror". Esse é um array de strings. Se você tiver mais de um ID, não se esqueça de usar aspas e vírgulas para separá-los.

  7. Aguarde alguns minutos para que os resultados entrem em vigor.

  8. Visualize os efeitos do controle de aumento. Consulte Receber recomendações de mídia.

Atualizar o controle de reforço

Este procedimento descreve como atualizar um controle de aprimoramento para mudar o valor do aprimoramento ou do filtro.

Depois de testar o controle de reforço, você pode descobrir que quer aumentar ou diminuir o reforço. Como alternativa, mude a string do filtro.

Ao atualizar um valor ou filtro de aumento, chame o método engines.controls.patch.

O método de patch substitui os valores de boost e filter pelos novos valores fornecidos. Este procedimento mostra como editar o valor boost (etapa 3) e o valor filter (etapa 4) separadamente. No entanto, se você quiser editar os dois, faça isso em um único comando curl.

REST

Para modificar o valor do aumento do filtro de um controle, siga estas etapas:

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

    1. No Console do Google Cloud, acesse a página Criador de agentes.

      Acessar "Apps".

    2. Na página Apps, encontre o nome do app e confira o ID dele na coluna ID.

  2. Encontre o ID do controle de aumento que você quer atualizar usando o método engines.servingConfigs.get. Se você já tiver o ID, pule para a próxima etapa.

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls"

    • PROJECT_ID: o ID do seu projeto do Google Cloud.

    • APP_ID: o ID do app da Vertex AI para Pesquisa.

  3. Edite o valor de aumento do controle:

    curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls/CONTROL_ID?update_mask=boost_action.boost" \
-d '{
    "name": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls/CONTROL_ID",
    "boostAction": {
      "boost": BOOST_VALUE
    }
}'

    • PROJECT_ID: o ID do seu projeto do Google Cloud.

    • APP_ID: o ID do app da Vertex AI para Pesquisa.

    • CONTROL_ID: o identificador exclusivo do controle de aumento que você quer editar, a parte final da saída do campo name pelo comando GET na etapa 2. Por exemplo, boost-kids.

    • BOOST_VALUE: um número de ponto flutuante no intervalo [-1,1]. Quando o valor é negativo, as recomendações aparecem mais abaixo nos resultados. Quando o valor é positivo, as recomendações são promovidas (elas aparecem mais acima nos resultados).

  4. Edite o filtro do controle de aumento:

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls/CONTROL_ID?update_mask=boost_action.filter" \
-d '{
    "name": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls/CONTROL_ID",
    "boostAction": {
      "filter": "FILTER"
    }
}'

    • PROJECT_ID: o ID do seu projeto do Google Cloud.

    • APP_ID: o ID do app da Vertex AI para Pesquisa.

    • CONTROL_ID: o identificador exclusivo do controle de aumento que você quer editar, a parte final da saída do campo name pelo comando GET na etapa 2.

    • FILTER: a expressão de filtro que descreve quais documentos serão impulsionados ou ocultados. Para informações detalhadas sobre como formular a expressão de filtro, consulte Expressões de filtro.

Excluir um controle de aumento

Este procedimento descreve como excluir um controle de reforço. Se você não estiver usando um controle de aumento, a prática recomendada é excluí-lo para que não alcance ou exceda a cota do número de controles permitidos.

Ao excluir um controle de aumento, você chama o método engines.controls.delete.

Não é possível excluir controles de aumento que estão anexados a uma configuração de veiculação. Se você tentar excluir um controle de aumento, uma mensagem de erro vai mostrar o nome da configuração de veiculação. Em seguida, exclua essa configuração de exibição ou desvincule esse controle da configuração de exibição.

REST

Para excluir um controle de aumento, siga estas etapas:

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

    1. No Console do Google Cloud, acesse a página Criador de agentes.

      Acessar "Apps".

    2. Na página Apps, encontre o nome do app e confira o ID dele na coluna ID.

  2. Encontre o ID do controle de aumento que você quer excluir usando o método engines.servingConfigs.get. Se você já tiver o ID, pule para a próxima etapa.

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls"

    • PROJECT_ID: o ID do seu projeto do Google Cloud.

    • APP_ID: o ID do app da Vertex AI para Pesquisa.

  3. Verifique a saída. Se o controle de aumento estiver anexado a uma configuração de exibição, atualize a configuração de exibição para remover o controle que você quer excluir. Consulte Atualizar uma configuração de veiculação para remover um controle de aumento.

  4. Execute o comando curl a seguir para excluir um controle de boost:

    curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls/CONTROL_ID"

    • PROJECT_ID: o ID do seu projeto do Google Cloud.

    • APP_ID: o ID do app da Vertex AI para Pesquisa.

    • CONTROL_ID: o identificador exclusivo do controle de aumento que você quer excluir, a parte final da saída do campo name pelo comando GET na etapa 2.

    Se você receber uma mensagem de erro informando que o controle é referenciado ativamente por pelo menos uma configuração de veiculação, consulte Atualizar uma configuração de veiculação para remover um controle de aumento.

Atualizar uma configuração de exibição para remover um controle de aumento

Antes de excluir um controle de aumento, você precisa desanexá-lo de todos os controles de veiculação. Para fazer isso, aplique um patch nos controles de veiculação para remover o ID do controle de aprimoramento.

Para desanexar os controles de aumento de uma configuração de veiculação, siga estas etapas:

  1. Para descobrir quais controles de aumento estão anexados à configuração de exibição, faça uma solicitação engines.servingConfigs.get e verifique o campo boostControlIds na resposta.

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/CONFIG_ID"

    • PROJECT_ID: o ID do seu projeto do Google Cloud.

    • APP_ID: o ID do app da Vertex AI para Pesquisa.

    • CONFIG_ID: o ID da configuração de veiculação sobre a qual você quer saber mais.

  2. Para atualizar a configuração de veiculação e remover um controle de aumento, use o método engines.servingConfigs.patch.

    curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/CONFIG_ID?update_mask=boost_control_ids" \
-d '{
  "boostControlIds": ["CONTROL_ID"]
}'

    • CONFIG_ID: o ID da configuração de veiculação a que você quer anexar os controles de aumento, por exemplo, my_app-1234567_id. Consulte a etapa anterior.

    • CONTROL_ID: contém os IDs de um ou mais controles de aprimoramento que você quer que a configuração de veiculação tenha. Não inclua os controles de reforço que você quer excluir. Esta é uma matriz de strings. Se você tiver mais de um ID, não se esqueça de usar aspas e vírgulas para separá-los. Por exemplo, boost-1", "boost-2.