メディアレコメンデーションのデータ品質を確認する

注: この機能はプレビュー版で、GCP サービス固有の規約の「pre-GA サービス規約」が適用されます。一般提供前のプロダクトと機能では、サポートが制限されることがあります。また、これらのプロダクトや機能には、他の一般提供前のバージョンと互換性のない変更が行われる場合があります。詳細については、リリースステージの説明をご覧ください。さらに、この機能を使用すると、生成 AI プレビュー版の利用規約（以下「プレビュー規約」）に同意したことになります。この機能については、お客様は Cloud のデータ処理に関する追加条項に記載されているとおりに個人データを処理できます。その際、（プレビュー規約に定義されるとおり）本契約で規定されている制限と義務が適用されます。

このページでは、メディアデータのさまざまな指標が要件のしきい値を満たしているかどうかに関する情報を返す check requirements メソッドを呼び出す方法について説明します。

メディアデータの品質チェックについて

メディアのおすすめでは最近のユーザーイベントが非常に重要であるため、取り込まれたデータとユーザーイベントの品質を定期的に確認する必要があります。これを行うには、メディアデータストアで check requirements メソッドを実行します。

指標のしきい値が満たされていない場合、curl コマンドは警告を出力します。次に、指標とその説明を確認して、メディアの品質を改善するために取るべき対応を決定する必要があります。

すべてのモデルと目標は、一般的な指標のしきい値を満たす必要があります。モデルと目標によっては、追加の指標としきい値があり、2 回目の要件チェックを実行する必要があります。

レコメンデーションモデルと目標については、メディアアプリのレコメンデーションタイプについてをご覧ください。

データ品質の確認

メディアレコメンデーションデータの品質を確認するには、次のように requirements:checkRequirement メソッドを使用します。

REST

コマンドラインから品質を確認する手順は次のとおりです。

データストア ID を確認します。データストア ID がすでにある場合は、次のステップに進みます。
1. Google Cloud コンソールで [Agent Builder] ページに移動し、ナビゲーションメニューで [データストア] をクリックします。
  
  [データストア] ページに移動
2. データストアの名前をクリックします。
3. データストアの [データ] ページで、データストア ID を取得します。

次の curl コマンドを実行して、メディアの推奨事項が一般的な指標のしきい値を満たしているかどうかを確認します。

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: Google Cloud プロジェクトの ID。
DATA_STORE_ID: Vertex AI Search データストアの ID。

コマンドと結果の例

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"
}

出力を確認する：
1. requirementResult の値を探します。
  - 値が SUCCESS の場合、データは一般的な要件を満たしています。ステップ 4 に進みます。
  - 値が WARNING の場合は、ステップ b に進みます。
  - 出力に requirementResult が表示されない場合は、次のような理由が考えられます。
    - リクエストの PROJECT_ID または DATA_STORE_ID が正しくありません。
    - 一部の指標値は利用できません。6 時間後にもう一度お試しいただくか、カスタマーエンジニアにお問い合わせください。
2. 式（requirement.Condition.Expression）を探します。この式が false と評価された場合、データに問題があります。
  
  注: 式の小なり記号は「<」ではなく、Unicode の \u003c で表示されます。
  指標の値は requirementCondition.metricResults.value フィールドにあります。警告しきい値は MetricBindings.warningThreshold フィールドにあります。description フィールドは、指標の目的を把握するのに役立ちます。
  
  たとえば、doc_with_same_title_percentage の値は 30.47 で、doc_with_same_title_percentage_threshold の警告しきい値は 1 です。データストア内のタイトルの多くが同じであるというデータの問題があり、調査する必要があります。

おすすめアプリに使用されているモデルと目標の組み合わせがこの表に表示されている場合は、モデルと目標の値を更新した check requirement メソッドも呼び出す必要があります。

モデル	目標	`MODEL_OBJ`
関連メディアのおすすめ	コンバージョン率	`oyml/cvr`
あなたへのおすすめ	コンバージョン率	`rfy/cvr`
もっと見る	コンバージョン率	`mlt/cvr`
最も人気	コンバージョン率	`mp/cvr`
関連メディアのおすすめ	セッションごとの視聴時間	`oyml/wdps`
あなたへのおすすめ	セッションごとの視聴時間	`rfy/wdps`
もっと見る	セッションごとの視聴時間	`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: Google Cloud プロジェクトの ID。
DATA_STORE_ID: Vertex AI Search データストアの ID。
MODEL_OBJ: おすすめアプリに適した値を選択するには、上の表をご覧ください。

コマンドと結果の例

この例は、「もっと見る」モデルと総再生時間の目標を使用しています。

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"
}

出力を確認する：
1. requirementResult の値を探します。
  - 値が SUCCESS の場合、データは十分です。
  - 値が WARNING の場合は、ステップ b に進みます。
  - 出力に requirementResult が表示されない場合は、次のような理由が考えられます。
    - リクエストの PROJECT_ID または DATA_STORE_ID が正しくありません。
    - 一部の指標値は利用できません。6 時間後にもう一度お試しいただくか、カスタマーエンジニアにお問い合わせください。
2. 式（requirement.Condition.Expression）を確認します。この式が false と評価された場合、データに問題があります。
  
  注: 式の小なり記号は、< ではなく、Unicode の \u003c で表示されます。
  指標の値は requirementCondition.metricResults.value フィールドにあり、警告しきい値は MetricBindings.warningThreshold フィールドにあります。description フィールドは、指標の目的を把握するのに役立ちます。

メディア レコメンデーションのデータ品質を確認する

メディアデータの品質チェックについて

データ品質の確認

コマンドと結果の例

コマンドと結果の例

メディアレコメンデーションのデータ品質を確認する