미디어 추천의 데이터 품질 확인

이 페이지에서는 미디어 데이터의 다양한 측정항목이 요구사항 기준점을 충족하는지 여부에 관한 정보를 반환하는 요구사항 확인 메서드를 호출하는 방법을 설명합니다.

미디어 데이터 품질 확인 정보

최근 사용자 이벤트는 미디어 추천에 매우 중요하므로 처리된 데이터와 사용자 이벤트의 품질을 정기적으로 확인해야 합니다. 이렇게 하려면 미디어 데이터 스토어에서 요구사항 확인 메서드를 실행하면 됩니다.

측정항목의 기준점이 충족되지 않으면 curl 명령어는 경고를 출력합니다. 그런 다음 측정항목과 설명을 검토하여 미디어 품질을 개선하기 위해 취해야 할 조치를 결정해야 합니다.

모든 모델과 목표는 일반 측정항목 기준점을 통과해야 합니다. 일부 모델 및 목표에는 추가 측정항목과 기준점이 있으며 두 번째 요구사항 확인을 실행해야 합니다.

추천 모델 및 목표에 대한 자세한 내용은 미디어 앱 추천 유형 정보를 참고하세요.

데이터 품질 확인

다음과 같이 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로 평가되면 데이터에 문제가 있는 것입니다.
  
  참고: 표현식의 미만 부호는 '<' 대신 유니코드 \u003c로 표시됩니다.
  
  측정항목의 값은 requirementCondition.metricResults.value 필드에 있습니다. 경고 기준점 값은 MetricBindings.warningThreshold 필드에 있습니다. description 필드를 사용하면 측정항목의 목적을 파악하는 데 도움이 됩니다.
  
  예를 들어 doc_with_same_title_percentage의 값은 30.47이고 doc_with_same_title_percentage_threshold의 경고 기준점은 1입니다. 데이터 스토어의 제목이 너무나도 많은 동일한 데이터 문제가 있으며 이를 조사해야 합니다.

추천 앱에 사용된 모델 및 목표 조합이 이 표에 표시되면 모델 및 목표의 값으로 업데이트된 요구사항 확인 메서드도 호출해야 합니다.

모델	목표	`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로 평가되면 데이터에 문제가 있는 것입니다.
  
  참고: 표현식의 미만 부호는 < 대신 유니코드 \u003c로 표시됩니다.
  
  측정항목 값은 requirementCondition.metricResults.value 필드에서, 경고 기준점 값은 MetricBindings.warningThreshold 필드에서 확인할 수 있습니다. description 필드를 사용하면 측정항목의 목적을 파악하는 데 도움이 됩니다.