미디어 문서 및 데이터 스토어 정보

이 페이지에서는 미디어용 문서와 데이터 스토어에 대한 정보를 제공합니다. 미디어 추천 또는 미디어 검색을 사용하는 경우 데이터를 업로드하기 전에 이 페이지에서 문서 및 데이터 스토어의 스키마 요구사항을 검토하세요.

개요

문서는 Vertex AI Agent Builder 데이터 스토어에 업로드하는 모든 항목입니다. 미디어의 경우 일반적으로 문서에는 동영상, 뉴스 기사, 음악 파일 또는 팟캐스트와 같은 미디어 콘텐츠에 대한 메타데이터 정보가 포함됩니다. API의 Document 객체는 이 메타데이터 정보를 캡처합니다.

데이터 스토어에는 업로드한 문서 모음이 포함됩니다. 데이터 스토어를 만들 때 미디어 문서가 포함되도록 지정합니다. 미디어용 데이터 스토어는 미디어 앱에만 연결될 수 있으며 일반 검색 및 추천과 같은 다른 앱 유형에는 연결될 수 없습니다. 데이터 스토어는 API에서 DataStore 리소스로 표현됩니다.

업로드하는 데이터의 품질은 미디어 앱에서 제공하는 결과의 품질에 직접적인 영향을 미칩니다. 일반적으로 더 정확하고 구체적인 정보를 제공하면 결과 품질이 높아집니다.

데이터 스토어에 업로드하는 데이터는 특정 JSON 스키마 형식이어야 합니다. 스키마에 정렬된 데이터는 BigQuery 테이블, Cloud Storage의 파일이거나 파일 집합 또는 Google Cloud 콘솔을 사용하여 직접 업로드할 수 있는 JSON 객체에 있어야 합니다.

Google 사전 정의 스키마와 커스텀 스키마 비교

미디어 데이터 스키마에는 두 가지 옵션이 있습니다.

• Google 사전 정의 스키마. 미디어 데이터용 스키마를 아직 설계하지 않았으면 Google 사전 정의 스키마를 사용하는 것이 좋습니다.

• 자체 스키마. 스키마 형식의 데이터가 이미 있으면 다음 요구사항을 충족하는 자체 스키마를 사용할 수 있습니다.

  스키마에 미디어의 5가지 키 속성에 매핑할 수 있는 필드가 있어야 합니다.

  • title
  • uri
  • category
  • media_available_time
  • media_duration 이 필드는 전환율(CVR)이나 방문자당 시청 시간을 극대화하는 것이 비즈니스 목표인 미디어 추천 앱에 중요합니다.

  필수가 아닌 추가 키 속성이 있습니다. 그러나 품질 결과를 위해 이러한 키 속성을 최대한 많이 스키마에 매핑하는 것이 좋습니다. 이러한 미디어 속성은 다음과 같습니다.

  • description(권장됨)
  • image
  • image_name
  • image_uri
  • language-code
  • media_aggregated_rating
  • media_aggregated_rating_count
  • media_aggregated_rating_score
  • media_aggregated_rating_source
  • media_content_index
  • media_content_rating
  • media_country_of_origin
  • media_expire_time
  • media_filter_tag
  • media_hash_tag
  • media_in_language
  • media_organization
  • media_organization_custom_role
  • media_organization_name
  • media_organization_rank
  • media_organization_role
  • media_organization_uri
  • media_person
  • media_person_custom_role
  • media_person_name
  • media_person_rank
  • media_person_role
  • media_person_uri
  • media_production_year
  • media_type

  이러한 속성에 대한 자세한 내용은 키 속성을 참조하세요. 이름은 비슷하지만 약간 다릅니다. 예를 들어 일부 이름은 media_로 시작하고 일부 이름은 복수형입니다.

Document의 JSON 스키마

문서에서 미디어를 사용할 때 미디어에 Google 사전 정의 JSON 스키마를 사용할 수 있습니다.

참고: Google 사전 정의 스키마 대신 자체 스키마를 사용하는 경우 자체 스키마를 가져오는 방법은 스키마 제공 또는 자동 감지를 참조하세요.

문서는 JSON 또는 구조체 데이터 표현으로 업로드됩니다. 문서 JSON 또는 구조체가 다음 JSON 스키마를 준수해야 합니다. JSON 스키마는 유효성 검사에 JSON 스키마 2020-12를 사용합니다. JSON 스키마에 대한 자세한 내용은 json-schema.org의 JSON 스키마 사양 문서를 참조하세요.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
    },
    "description": {
      "type": "string",
    },
    "media_type": {
      "type": "string",
    },
    "language_code": {
      "type": "string",
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
      }
    },
    "uri": {
      "type": "string",
    },
    "images": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "uri": {
            "type": "string",
          },
          "name": {
            "type": "string",
          }
        },
      }
    },
    "in_languages": {
      "type": "array",
      "items": {
        "type": "string",
      }
    },
    "country_of_origin": {
      "type": "string",
    },
    "content_index": {
      "type": "integer",
    },
    "persons": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
          },
          "role": {
            "type": "string",
          },
          "custom_role": {
            "type": "string",
          },
          "rank": {
            "type": "integer",
          },
          "uri": {
            "type": "string",
          }
        },
        "required": ["name", "role"],
      }
    },
    "organizations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
          },
          "role": {
            "type": "string",
          },
          "custom_role": {
            "type": "string",
          },
          "rank": {
            "type": "integer",
          },
          "uri": {
            "type": "string",
          }
        },
        "required": ["name", "role"],
      }
    },
    "hash_tags": {
      "type": "array",
      "items": {
        "type": "string",
      }
    },
    "filter_tags": {
      "type": "array",
      "items": {
        "type": "string",
      }
    },
    "duration": {
      "type": "string",
    },
    "content_rating": {
      "type": "array",
      "items": {
        "type": "string",
      }
    },
    "aggregate_ratings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "rating_source": {
            "type": "string",
          },
          "rating_score": {
            "type": "number",
          },
          "rating_count": {
            "type": "integer",
          }
        },
        "required": ["rating_source"],
      }
    },
    "available_time": {
      "type": "datetime",
    },
    "expire_time": {
      "type": "string",
    },
    "production_year": {
      "type": "integer",
    }
  },
  "required": ["title", "categories", "uri", "available_time"],
}

샘플 JSON Document 객체

다음 예시에서는 JSON Document 객체 예시를 보여줍니다.

{
  "title": "Test document title",
  "description": "Test document description",
  "media_type": "sports-game",
  "in_languages": [
    "en-US"
  ],
  "language_code": "en-US",
  "categories": [
    "sports > clip",
    "sports > highlight"
  ],
  "uri": "http://www.example.com",
  "images": [
    {
      "uri": "http://example.com/img1",
      "name": "image_1"
    }
  ],
  "country_of_origin": "US",
  "content_index": 0,
  "persons": [
    {
      "name": "sports person",
      "role": "player",
      "rank": 0,
      "uri": "http://example.com/person"
    },
  ],
  "organizations": [
    {
      "name": "sports team",
      "role": "team",
      "rank": 0,
      "uri": "http://example.com/team"
    },
  ],
  "hash_tags": [
    "tag1"
  ],
  "filter_tags": [
    "filter_tag"
  ],
  "duration": "100s",
  "production_year": 1900,
  "content_rating": [
    "PG-13"
  ],
  "aggregate_ratings": [
    {
      "rating_source": "imdb",
      "rating_score": 4.5,
      "rating_count": 1250
    }
  ],
  "available_time": "2022-08-26T23:00:17Z"
}

문서 필드

이 섹션에는 데이터 스토어의 문서를 만들 때 제공하는 필드 값이 나와 있습니다. 값은 내부 문서 데이터베이스에서 사용되는 값과 일치해야 하며 표시된 항목을 정확하게 반영해야 합니다.

Document 객체 필드

다음 필드는 Document 객체의 최상위 필드입니다. 또한 Document 참조 페이지에서 이러한 필드를 참조하세요.

필드	참고
name	문서의 고유한 전체 리소스 이름입니다. create 및 import를 제외한 모든 Document 메서드에 필수입니다. 가져오는 동안 이름이 자동으로 생성되므로 수동으로 제공할 필요가 없습니다.
id	내부 데이터베이스에서 사용하는 문서 ID입니다. ID 필드는 전체 데이터 스토어에서 고유해야 합니다. 사용자 이벤트를 기록할 때 동일한 값이 사용되며 recommend 및 search 메서드에서도 반환됩니다.
schemaId	필수 항목. 같은 데이터 스토어에 있는 스키마의 식별자입니다. 기본 데이터 스토어가 생성될 때 자동으로 생성되는 'default_schema'로 설정해야 합니다.
parentDocumentId	상위 문서 ID입니다. 최상위(루트) 문서의 경우 parent_document_id는 비어 있거나 자가 자신을 가리킬 수 있습니다. 하위 문서의 경우 parent_document_id는 유효한 루트 문서를 가리켜야 합니다.

주요 속성

다음 속성은 미디어용 사전 정의된 JSON 스키마 형식을 통해 정의됩니다.

JSON 속성에 대한 자세한 내용은 json-schema.org에서 속성에 대한 JSON 스키마 이해 문서를 참조하세요.

다음 표에는 플랫 키 속성이 정의되어 있습니다.

필드 이름	참고
title	문자열 - 필수 데이터베이스의 문서 제목입니다. UTF-8로 인코딩된 문자열입니다. 최대 1,000자(영문 기준)까지 입력할 수 있습니다.
categories	문자열 - 필수 문서 카테고리입니다. 이 속성은 여러 병렬 카테고리에 속하는 문서 하나를 지원하기 위해 반복됩니다. 품질 결과를 높이려면 전체 카테고리 경로를 사용합니다. 카테고리의 전체 경로를 나타내려면 > 기호를 사용하여 계층 구조를 구분합니다. >가 카테고리 이름에 포함된 경우 다른 문자로 바꿉니다. 예를 들면 다음과 같습니다. "categories": [ "sports > highlight" ] 문서에는 카테고리가 최대 250개까지 포함될 수 있습니다. 각 카테고리는 UTF-8로 인코딩된 문자열이며 길이 제한은 5,000자(영문 기준)입니다.
uri	문자열 - 필수 문서 URI입니다. 길이 제한은 5,000자(영문 기준)입니다.
description	문자열 - 권장됨 문서에 대한 설명입니다. 길이 제한은 5,000자(영문 기준)입니다.
media_type	문자열 - 영화 및 TV 프로그램을 위한 필수 필드 최상위 카테고리입니다. movie, show, concert, event, live-event, broadcast, tv-series, episode, video-game, clip, vlog, audio, audio-book, music, album, articles, news, radio, podcast, book, sports-game 유형이 지원됩니다. movie 및 show 값에는 특별한 의미가 있습니다. 이를 통해 순위가 개선되고 사용자가 제목 검색을 통해 관심을 가질 만한 대체 콘텐츠를 찾는 데 도움이 되는 방식으로 문서가 보강됩니다.
language_code	문자열 - 선택사항 제목/설명 및 기타 문자열 속성의 언어입니다. BCP 47에 정의된 언어 태그를 사용합니다. 문서 추천의 경우 이 필드는 무시되고 텍스트 언어가 자동으로 감지됩니다. 문서에 서로 다른 언어로 작성된 텍스트가 포함될 수 있지만 여러 언어로 작성된 텍스트를 제공하기 위해 문서를 중복하면 성능이 저하될 수 있습니다. 문서 검색에 이 필드가 사용됩니다. 설정하지 않으면 기본값은 'en-US'입니다. 예를 들면 "language_code": "en-US"입니다.
duration	문자열 - 클릭률(CVR)이거나 세션당 시청 시간이 비즈니스 목표인 미디어 추천 앱에 필요합니다. 미디어 콘텐츠 기간입니다. 기간은 문자열로 인코딩되어야 합니다. 인코딩은 google::protobuf::Duration JSON 문자열 인코딩과 동일해야 합니다. 예를 들면 '5s', '1m'입니다.
available_time	날짜/시간 - 필수사항 최종 사용자가 콘텐츠를 사용할 수 있는 시간입니다. 이 필드는 최종 사용자의 콘텐츠 신선도를 나타냅니다. 타임스탬프는 RFC 3339 표준을 준수해야 합니다. 예를 들면 다음과 같습니다. "2022-08-26T23:00:17Z"
expire_time	문자열 - 선택사항 최종 사용자의 콘텐츠가 만료되는 시간입니다. 이 필드는 최종 사용자의 콘텐츠 신선도를 나타냅니다. 타임스탬프는 RFC 3339 표준을 준수해야 합니다. 예를 들면 다음과 같습니다. "2032-12-31T23:00:17Z"
in_languages	문자열 - 선택사항 - 반복됨 미디어 콘텐츠 언어입니다. BCP 47에 정의된 언어 태그를 사용합니다. 예: "in_languages": [ "en-US"]
country_of_origin	문자열 - 선택사항 미디어 문서 원본 국가입니다. 길이 제한은 128자(영문 기준)입니다. 예: "country_of_origin": "US"
content_index	정수 - 선택사항 미디어 문서의 콘텐츠 색인입니다. 콘텐츠 색인 필드는 다른 문서와 비교하여 문서를 정렬하는 데 사용될 수 있습니다. 예를 들어 에피소드 번호를 콘텐츠 색인으로 사용할 수 있습니다. 콘텐츠 색인은 음이 아닌 정수여야 합니다. 예: "content_index": 0
filter_tags	문자열 - 선택사항 - 반복됨 문서의 태그를 필터링합니다. 값은 문서당 최대 250개까지 허용되며 길이 제한은 1,000자(영문 기준)입니다. 그렇지 않으면 INVALID_ARGUMENT 오류가 반환됩니다. 이 태그는 태그를 RecommendRequest.filter의 일부로 전달하여 추천 결과를 필터링하는 데 사용될 수 있습니다. 예: "filter_tags": [ "filter_tag"]
hash_tags	문자열 - 선택사항 - 반복됨 문서의 해시태그입니다. 값은 문서당 최대 100개까지 허용되며 길이 제한은 5,000자(영문 기준)입니다. 예: "hash_tags": [ "soccer", "world cup"]
content_rating	문자열 - 선택사항 - 반복됨 콘텐츠 경고 시스템 및 잠재고객을 기반으로 하는 콘텐츠 필터링에 사용되는 콘텐츠 등급입니다. 값은 문서당 최대 100개까지 허용되며 길이 제한은 128자(영문 기준)입니다. 이 태그는 태그를 RecommendRequest.filter의 일부로 전달하여 추천 결과를 필터링하는 데 사용될 수 있습니다. 예: content_rating: ["PG-13"]

다음 표에서는 계층적 키 속성을 정의합니다.

필드 이름	참고
images	객체 - 선택사항 - 반복됨 이미지 관련 속성을 캡슐화하는 루트 키 속성입니다.
images.uri	문자열 - 선택사항 이미지 URI입니다. 길이 제한은 5,000자(영문 기준)입니다.
images.name	문자열 - 선택사항 이미지 이름입니다. 길이 제한은 128자(영문 기준)입니다.
persons	객체 - 선택사항 - 반복됨 사용자 관련 속성을 캡슐화하는 루트 키 속성입니다. 예를 들면 다음과 같습니다. "persons":[{"name":"sports person","role":"player","rank":0,"uri":"http://example.com/person"}]
persons.name	문자열 - 필수 사용자 이름입니다.
persons.role	문자열 - 필수 미디어 항목에서의 사용자 역할입니다. 감독, 배우, 선수, 팀, 리그, 편집자, 작가, 캐릭터, 참여자, 크리에이터, 편집자, 후원자, 제작자, 제공자, 게시자, 스폰서, 번역가, 작곡가, 채널, 커스텀 역할 값이 지원됩니다. 지원되는 값이 role에 적용되지 않으면 role을 custom-role로 설정하고 값을 custom_role 필드에 제공합니다.
persons.custom_role	문자열 - 선택사항 custom_role은 role이 custom-role로 설정된 경우에만 설정됩니다. UTF-8로 인코딩된 문자열이어야 하며 길이 제한은 128자(영문 기준)입니다. [a-zA-Z0-9][a-zA-Z0-9_]* 패턴과 일치해야 합니다.
persons.rank	정수 - 선택사항 역할 순위에 사용됩니다. 예를 들어 첫 번째 배우의 경우에는 role = "actor", rank = 1입니다.
persons.uri	문자열 - 선택사항 사용자 URI입니다.
organizations	객체 - 선택사항 - 반복됨 organization 관련 속성을 캡슐화하는 루트 키 속성입니다. 예를 들면 다음과 같습니다. "organizations ":[{"name":"sports team","role":"team","rank":0,"uri":"http://example.com/team"}]
organizations.name	문자열 - 필수 조직의 이름입니다.
organizations.role	문자열 - 필수 미디어 항목에서의 조직 역할입니다. 감독, 배우, 선수, 팀, 리그, 편집자, 작가, 캐릭터, 참여자, 크리에이터, 편집자, 후원자, 제작자, 제공자, 게시자, 스폰서, 번역가, 작곡가, 채널, 커스텀 역할 값이 지원됩니다. 지원되는 값이 role에 적용되지 않으면 role을 custom-role로 설정하고 값을 custom_role 필드에 제공합니다.
organizations.custom_role	문자열 - 선택사항 custom_role은 role이 custom-role로 설정된 경우에만 설정됩니다. UTF-8로 인코딩된 문자열이어야 하며 길이 제한은 128자(영문 기준)입니다. [a-zA-Z0-9][a-zA-Z0-9_]* 패턴과 일치해야 합니다.
organizations.rank	문자열 - 선택사항 역할 순위에 사용됩니다. 예를 들어 첫 번째 게시자의 경우 role = "publisher", rank = 1입니다.
organizations.uri	문자열 - 선택사항 조직 URI입니다.
aggregate_ratings	객체 - 선택사항 - 반복됨 aggregate_rating 관련 속성을 캡슐화하는 루트 키 속성입니다.
aggregate_ratings.rating_source	문자열 - 필수 평점 출처입니다. 예를 들면 imdb 또는 rotten_tomatoes입니다. UTF-8로 인코딩된 문자열이어야 하며 길이 제한은 128자(영문 기준)입니다. [a-zA-Z0-9][a-zA-Z0-9_]* 패턴과 일치해야 합니다.
aggregate_ratings.rating_score	실수 - 선택사항 집계된 등급입니다. 등급은 [1, 5] 범위로 정규화되어야 합니다.
aggregate_ratings.rating_count	정수 - 선택사항 개별 리뷰 수입니다. 음이 아닌 값이어야 합니다.

문서 수준

문서 수준은 데이터 스토어의 계층 구조를 결정합니다. 일반적으로 단일 수준 데이터 스토어나 2단계 데이터 스토어가 있어야 합니다. 레이어 2개만 지원됩니다.

예를 들어 각 문서가 개별 항목인 단일 수준 데이터 스토어가 있을 수 있습니다. 또는 항목 그룹과 개별 항목이 모두 포함된 2단계 데이터 스토어를 선택할 수 있습니다.

문서 수준 유형

문서 수준 유형에는 두 가지가 있습니다.

• 상위. 상위 문서는 Vertex AI Search가 추천과 검색에 반환하는 문서입니다. 상위 문서는 개별 문서나 유사한 문서 그룹일 수 있습니다. 이 수준 유형을 사용하는 것이 좋습니다.

• 하위. 하위 문서는 그룹 상위 문서의 버전입니다. 개별 문서만 하위 문서가 될 수 있습니다. 예를 들어 상위 문서가 'Example TV Show'이면 하위 문서는 'Episode 1' 및 'Episode 2'일 수 있습니다. 이 수준 유형을 구성하고 유지하기 어려울 수 있으므로 사용하지 않는 것이 좋습니다.

데이터 스토어 계층 구조 정보

데이터 스토어 계층 구조를 계획할 때는 데이터 스토어에 상위 문서만 또는 상위 문서와 하위 문서가 포함되어야 하는지 결정합니다. 추천과 검색에서는 상위 문서만 반환한다는 점이 중요합니다.

예를 들어 상위 전용 데이터 스토어는 오디오북에 적합할 수 있으며 추천 패널은 개별 오디오북 선택을 반환합니다. 반면에 TV 프로그램 에피소드를 상위 전용 데이터 스토어에 상위 문서로 업로드한 경우 순서가 잘못된 여러 에피소드가 같은 패널에 추천될 수 있습니다.

TV 프로그램 데이터 스토어는 상위 문서와 하위 문서 모두에서 작동할 수 있습니다. 여기서 각 상위 문서는 TV 프로그램의 에피소드를 나타내는 하위 문서가 있는 TV 프로그램을 나타냅니다. 이 2단계 데이터 스토어는 추천 패널에 비슷한 여러 TV 프로그램을 표시할 수 있습니다. 최종 사용자는 특정 프로그램을 클릭하여 시청할 에피소드를 선택할 수 있습니다.

상위-하위 계층 구조를 구성하고 유지하기가 어려울 수 있으므로 상위 전용 데이터 스토어를 사용하는 것이 좋습니다.

예를 들어 TV 프로그램 데이터 스토어는 각 상위 문서가 추천 가능한 TV 프로그램을 나타내고 개별 에피소드가 포함되지 않아 추천되지 않는 상위 전용 데이터 스토어로 적합할 수 있습니다.

데이터 스토어에 상위 문서와 하위 문서, 즉 그룹과 단일 항목이 모두 있어야 한다고 판단했지만 현재 단일 항목만 있으면 그룹의 상위 문서를 만들어야 합니다. 최소한 상위 문서에 id, title, categories 정보를 제공해야 합니다. 자세한 내용은 문서 필드 섹션을 참조하세요.

미디어용 BigQuery 스키마

BigQuery에서 문서를 가져오려면 사전 정의된 BigQuery 스키마를 사용하여 올바른 형식의 BigQuery 테이블을 만들고 문서를 가져오기 전에 문서 데이터로 로드합니다.

[
  {
    "name": "id",
    "mode": "REQUIRED",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "schemaId",
    "mode": "REQUIRED",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "parentDocumentId",
    "mode": "NULLABLE",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "jsonData",
    "mode": "NULLABLE",
    "type": "STRING",
    "fields": []
  }
]