Verificar a qualidade dos dados para receber recomendações de mídia

Observação: Este recurso é uma solução em pré-lançamento e está sujeita aos "Termos das soluções pré-GA". dos Termos Específicos de Serviço do GCP. Os produtos e recursos pré-GA podem ter suporte limitado, e as mudanças neles podem não ser compatíveis com outras versões pré-GA. Para mais informações, consulte a descrições da fase de lançamento. Além disso, ao usar esse recurso, você concorda com os Termos e Condições da Prévia da IA generativa ("Termos de visualização"). Para usar esse recurso, é possível processar dados pessoais conforme descrito no Adendo sobre processamento de dados do Cloud, sujeito às restrições e obrigações aplicáveis do Contrato (conforme definido nos Termos de Prévia).

Esta página descreve como chamar o método de verificação de requisitos que retorna informações sobre se as diversas métricas dos seus dados de mídia atendem aos requisitos de conformidade.

Sobre a verificação da qualidade dos dados de mídia

Como os eventos recentes do usuário são muito importantes para as recomendações de mídia, é necessário verificar regularmente a qualidade dos dados ingeridos e dos eventos do usuário. Você pode fazer isso executando o método de verificação de requisitos no repositório de dados de mídia.

Se o limite de uma métrica não for atendido, o comando curl vai gerar um aviso. Depois, é preciso analisar a métrica e a descrição dela para determinar qual ação que você deve seguir para melhorar a qualidade da mídia.

Todos os modelos e objetivos precisam ultrapassar os limites de métricas gerais. Alguns modelos têm métricas e limites adicionais e exigem que você execute uma na segunda verificação de requisitos.

Para mais informações sobre os modelos e objetivos de recomendação, consulte Sobre os tipos de recomendações de apps de música.

Verificar a qualidade dos dados

Use o método requirements:checkRequirement para verificar a qualidade dos dados de recomendações de mídia, como mostrado a seguir.

REST

Para verificar a qualidade na linha de comando, siga estas etapas:

1. Encontre o ID do repositório de dados. Se você já tem seu repositório de dados ID, 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.

      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. Execute o seguinte comando curl para saber se suas recomendações de mídia atendem aos requisitos os limites para as métricas gerais:

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-GFE-SSL: yes" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/requirements:checkRequirement" \
   -d '{
         "location": "projects/PROJECT_ID/locations/global",
         "requirementType": "discoveryengine.googleapis.com/media_recs/general/all/warning",
         "resources": [
           {
             "labels": {
               "branch_id": "0",
               "collection_id": "default_collection",
               "datastore_id": "DATA_STORE_ID",
               "location_id": "global",
               "project_number": "PROJECT_ID"
             },
             "type": "discoveryengine.googleapis.com/Branch"
           },
           {
             "labels": {
               "collection_id": "default_collection",
               "datastore_id": "DATA_STORE_ID",
               "location_id": "global",
               "project_number": "PROJECT_ID"
             },
             "type": "discoveryengine.googleapis.com/DataStore"
           }
         ]
       }'
   

   • PROJECT_ID: o ID do seu projeto do Google Cloud.
   • DATA_STORE_ID: o ID do repositório de dados da Vertex AI para Pesquisa.

   Exemplo de comando e resultado

   curl -X POST
   -H "Authorization: Bearer $(gcloud auth print-access-token)"
   -H "Content-Type: application/json"
   -H "X-GFE-SSL: yes"
   -H "X-Goog-User-Project: my-project-123"
   "https://discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/requirements:checkRequirement"
   -d '{
     "location": "projects/123456/locations/global",
     "requirementType": "discoveryengine.googleapis.com/media_recs/general/all/warning",
     "resources": [
       {
         "labels": {
           "branch_id": "0",
           "collection_id": "default_collection",
           "datastore_id": "my-data-store",
           "location_id": "global",
           "project_number": "123456"
         },
         "type": "discoveryengine.googleapis.com/Branch"
       },
       {
         "labels": {
           "collection_id": "default_collection",
           "datastore_id": "my-data-store",
           "location_id": "global",
           "project_number": "123456"
         },
         "type": "discoveryengine.googleapis.com/DataStore"
       }
     ]
   }'
       
   
   {
   "requirement": {
   "type": "discoveryengine.googleapis.com/media_recs/general/all/warning",
   "displayName": "Warning level requirements for all models and all business objectives.",
   "description": "Requirements for the media recommendations model that will result in performance issue if not met for all media recommendations models and all business objectives.",
   "condition": {
     "expression": "doc_with_same_title_percentage \u003c doc_with_same_title_percentage_threshold && most_common_visitor_id_percentage \u003c most_common_visitor_id_percentage_threshold && short_term_unjoined_events_percentage \u003c short_term_unjoined_events_percentage_threshold && long_term_unjoined_events_percentage \u003c long_term_unjoined_events_percentage_threshold"
   },
   "metricBindings": [
     {
       "variableId": "doc_with_same_title_percentage",
       "resourceType": "discoveryengine.googleapis.com/Branch",
       "metricFilter": "metric.type = 'discoveryengine.googleapis.com/branch/documents/items_with_same_title' AND metric.labels.is_percentage = 'True' AND resource.labels.project_number = '123456' AND resource.labels.branch_id = '0' AND resource.labels.datastore_id = 'my-data-store' AND resource.labels.location_id = 'global' AND resource.labels.collection_id = 'default_collection'",
       "description": "The percentage of the documents with the same title in a branch.",
       "category": "Document"
     },
     {
       "variableId": "most_common_visitor_id_percentage",
       "resourceType": "discoveryengine.googleapis.com/DataStore",
       "metricFilter": "metric.type = 'discoveryengine.googleapis.com/branch/datastore/user_events/most_used_visitor_id_events' AND metric.labels.is_percentage = 'True' AND resource.labels.datastore_id = 'my-data-store' AND resource.labels.project_number = '123456' AND resource.labels.location_id = 'global' AND resource.labels.collection_id = 'default_collection'",
       "description": "The percentage of the events with the same visitor id.",
       "category": "DataStore"
     },
     {
       "variableId": "short_term_unjoined_events_percentage",
       "resourceType": "discoveryengine.googleapis.com/DataStore",
       "metricFilter": "metric.type = 'discoveryengine.googleapis.com/datastore/user_events/unjoined_events_for_document_ids' AND metric.labels.is_percentage = 'True' AND metric.conditions.time_range = 'WEEK' AND resource.labels.datastore_id = 'my-data-store' AND resource.labels.project_number = '123456' AND resource.labels.location_id = 'global' AND resource.labels.collection_id = 'default_collection'",
       "description": "The percentage of events refers to a document id that is not in the catalog in the last 7 days.",
       "category": "DataStore"
     },
     {
       "variableId": "long_term_unjoined_events_percentage",
       "resourceType": "discoveryengine.googleapis.com/DataStore",
       "metricFilter": "metric.type = 'discoveryengine.googleapis.com/datastore/user_events/unjoined_events_for_document_ids' AND metric.labels.is_percentage = 'True' AND metric.conditions.time_range = 'NINETY_DAYS' AND resource.labels.datastore_id = 'my-data-store' AND resource.labels.project_number = '123456' AND resource.labels.location_id = 'global' AND resource.labels.collection_id = 'default_collection'",
       "description": "The percentage of events refers to a document id that is not in the catalog in the last 90 days.",
       "category": "DataStore"
     }
   ],
   "thresholdBindings": [
     {
       "variableId": "doc_with_same_title_percentage_threshold",
       "warningThreshold": 1,
       "blockingThreshold": 100,
       "description": "The threshold for the percentage of the documents with the same title in a branch."
     },
     {
       "variableId": "most_common_visitor_id_percentage_threshold",
       "warningThreshold": 5,
       "blockingThreshold": 100,
       "description": "The threshold for the percentage of the events with the same visitor id."
     },
     {
       "variableId": "short_term_unjoined_events_percentage_threshold",
       "warningThreshold": 2,
       "blockingThreshold": 100,
       "description": "The threshold for the percentage of the events refers to a document id that is not in the catalog in the last 7 days."
     },
     {
       "variableId": "long_term_unjoined_events_percentage_threshold",
       "warningThreshold": 2,
       "blockingThreshold": 100,
       "description": "The threshold for the percentage of the events refers to a document id that is not in the catalog in the last 90 days"
     }
   ]
   },
   "requirementResult": "WARNING",
   "requirementCondition": {
   "expression": "doc_with_same_title_percentage \u003c doc_with_same_title_percentage_threshold && most_common_visitor_id_percentage \u003c most_common_visitor_id_percentage_threshold && short_term_unjoined_events_percentage \u003c short_term_unjoined_events_percentage_threshold && long_term_unjoined_events_percentage \u003c long_term_unjoined_events_percentage_threshold"
   },
   "metricResults": [
   {
     "name": "short_term_unjoined_events_percentage",
     "value": {
       "doubleValue": 0
     },
     "timestamp": "2024-06-06T03:03:13.416900898Z",
     "unit": "%",
     "metricType": "discoveryengine.googleapis.com/datastore/user_events/unjoined_events_for_document_ids"
   },
   {
     "name": "long_term_unjoined_events_percentage",
     "value": {
       "doubleValue": 0
     },
     "timestamp": "2024-06-06T03:03:13.417962744Z",
     "unit": "%",
     "metricType": "discoveryengine.googleapis.com/datastore/user_events/unjoined_events_for_document_ids"
   },
   {
     "name": "most_common_visitor_id_percentage",
     "value": {
       "doubleValue": 0.8
     },
     "timestamp": "2024-06-06T03:03:16.090037135Z",
     "unit": "%",
     "metricType": "discoveryengine.googleapis.com/datastore/user_events/most_used_visitor_id_events"
   },
   {
     "name": "doc_with_same_title_percentage",
     "value": {
       "doubleValue": 30.47
     },
     "timestamp": "2024-06-06T03:03:17.599458357Z",
     "unit": "%",
     "metricType": "discoveryengine.googleapis.com/documents/items_with_same_title"
   }
   ],
   "oldestMetricTimestamp": "2024-06-06T03:03:13.416900898Z"
   }
   

3. Confira a saída:

   1. Procure o valor de requirementResult:

      • Se o valor for SUCCESS, seus dados atendem aos requisitos gerais. Continue para a etapa 4.

      • Se o valor for WARNING, continue para a etapa b.

      • Se você não encontrar requirementResult na saída, há alguns motivos possíveis:

        • O PROJECT_ID ou DATA_STORE_ID na solicitação está incorreto.

        • Alguns valores de métricas não estão disponíveis. Tente de novo em 6 horas ou entre em contato com um engenheiro de clientes para receber ajuda.

   2. Procure a expressão (requirement.Condition.Expression): se este expressão for avaliada como falsa, há um problema com seus dados.

      Observação: o sinal menor que na expressão aparece unicode, \u003c, em vez de "<".

      O valor das métricas está no requirementCondition.metricResults.value. Os valores do limite de alerta estão nos campos MetricBindings.warningThreshold. Os campos description podem ajudar a entender a finalidade da métrica.

      Por exemplo, o valor de doc_with_same_title_percentage é 30.47 e o limite de aviso para doc_with_same_title_percentage_threshold é 1. Há um problema de dados que muitos dos títulos no repositório de dados são iguais, e isso precisa ser investigado.

4. Se a combinação de modelo e objetivo usada para seu app de recomendações aparecer nessa tabela, você também precisará chamar o requisito de verificação , atualizado com os valores do seu modelo e objetivo:

   Modelo	Objetivo	MODEL_OBJ
   Outros itens que você pode gostar	Taxa de conversão	oyml/cvr
   Recomendados para você	Taxa de conversão	rfy/cvr
   Mais conteúdo semelhante	Taxa de conversão	mlt/cvr
   Mais popular	Taxa de conversão	mp/cvr
   Outros itens que você pode gostar	Duração da exibição por sessão.	oyml/wdps
   Recomendados para você	Duração da exibição por sessão.	rfy/wdps
   Mais conteúdo semelhante	Duração da exibição por sessão.	mlt/wdps

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-GFE-SSL: yes" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/requirements:checkRequirement" \
   -d '{
         "location": "projects/PROJECT_ID/locations/global",
         "requirementType": "discoveryengine.googleapis.com/media_recs/MODEL_OBJ/warning",
         "resources": [
           {
             "labels": {
               "branch_id": "0",
               "collection_id": "default_collection",
               "datastore_id": "DATA_STORE_ID",
               "location_id": "global",
               "project_number": "PROJECT_ID"
             },
             "type": "discoveryengine.googleapis.com/Branch"
           },
           {
             "labels": {
               "collection_id": "default_collection",
               "datastore_id": "DATA_STORE_ID",
               "location_id": "global",
               "project_number": "PROJECT_ID"
             },
             "type": "discoveryengine.googleapis.com/DataStore"
           }
         ]
       }'
   

   • PROJECT_ID: o ID do seu projeto do Google Cloud.
   • DATA_STORE_ID: o ID do repositório de dados da Vertex AI para Pesquisa.
   • MODEL_OBJ: consulte a tabela anterior para escolher o valor correto para seu app de recomendações.

   Exemplo de comando e resultado

   Este exemplo é para o modelo "Mais como este" e a duração do vídeo objetivo:

   curl -X POST
   -H "Authorization: Bearer $(gcloud auth print-access-token)"
   -H "Content-Type: application/json"
   -H "X-GFE-SSL: yes"
   -H "X-Goog-User-Project: my-project-123"
   "https://discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/dataStores/my-data-store/branches/0/requirements:checkRequirement"
   -d '{
     "location": "projects/my-project-123/locations/global",
     "requirementType": "discoveryengine.googleapis.com/media_recs/mlt/wdps/warning",
     "resources": [
       {
         "labels": {
           "branch_id": "0",
           "collection_id": "default_collection",
           "datastore_id": "my-data-store",
           "location_id": "global",
           "project_number": "my-project-123"
         },
         "type": "discoveryengine.googleapis.com/Branch"
       },
       {
         "labels": {
           "collection_id": "default_collection",
           "datastore_id": "my-data-store",
           "location_id": "global",
           "project_number": "my-project-123"
         },
         "type": "discoveryengine.googleapis.com/DataStore"
       }
     ]
   }'
       
   
   {
   "requirement": {
   "type": "discoveryengine.googleapis.com/media_recs/mlt/wdps/warning",
   "displayName": "Warning level requirements for 'More Like This' models and 'Watch duration per session' business objectives.",
   "description": "Requirements for the media recommendations model that will result in performance issue if not met for the 'More Like This' model and the 'Watch duration per session' business objective.",
   "condition": {
     "expression": "invalid_sequence_percentage \u003c= invalid_sequence_percentage_threshold"
   },
   "metricBindings": [
     {
       "variableId": "invalid_sequence_percentage",
       "resourceType": "discoveryengine.googleapis.com/DataStore",
       "metricFilter": "metric.type = 'discoveryengine.googleapis.com/datastore/user_events/invalid_sequences_media_play_media_complete' AND metric.labels.is_percentage = 'True'  AND resource.labels.location_id = 'global' AND resource.labels.collection_id = 'default_collection' AND resource.labels.project_number = '123456' AND resource.labels.datastore_id = 'my-data-store'",
       "description": "The percentage of invalid sequences for media play and media complete events sampled by randomly selected visitor ids.",
       "category": "DataStore"
     }
   ],
   "thresholdBindings": [
     {
       "variableId": "invalid_sequence_percentage_threshold",
       "warningThreshold": 50,
       "blockingThreshold": 100,
       "description": "The threshold for the percentage of invalid sequences sampled among all media play and media complete events."
     }
   ]
   },
   "requirementResult": "SUCCESS",
   "requirementCondition": {
   "expression": "invalid_sequence_percentage \u003c= invalid_sequence_percentage_threshold"
   },
   "metricResults": [
   {
     "name": "invalid_sequence_percentage",
     "value": {
       "doubleValue": 0
     },
     "timestamp": "2024-06-06T02:32:00.460056386Z",
     "unit": "%",
     "metricType": "discoveryengine.googleapis.com/datastore/user_events/invalid_sequences_media_play_media_complete"
   }
   ],
   "oldestMetricTimestamp": "2024-06-06T02:32:00.460056386Z"
   }
   

5. Confira o resultado:

   1. Procure o valor de requirementResult:

      • Se o valor for SUCCESS, seus dados são suficientes.

      • Se o valor for WARNING, continue para a etapa b.

      • Se você não encontrar requirementResult na saída, há alguns motivos possíveis:

        • O PROJECT_ID ou DATA_STORE_ID na solicitação está incorreto.

        • Alguns valores de métricas não estão disponíveis. Tente de novo em seis horas ou entre em contato com um engenheiro de atendimento ao cliente para receber ajuda.

   2. Procure a expressão (requirement.Condition.Expression). Se esse expressão for avaliada como falsa, há um problema com seus dados.

      Observação: o sinal menor que na expressão aparece unicode, \u003c, em vez de <.

      O valor das métricas pode ser encontrado no arquivo requirementCondition.metricResults.value, e o limite de aviso nos campos MetricBindings.warningThreshold. Os campos description podem ajudar você a entender a finalidade da métrica.