Tentang dokumen media dan penyimpanan data

Halaman ini memberikan informasi tentang dokumen dan penyimpanan data untuk media. Jika Anda menggunakan rekomendasi media atau penelusuran media, tinjau persyaratan skema untuk dokumen dan penyimpanan data Anda di halaman ini sebelum mengupload data.

Ringkasan

Dokumen adalah item apa pun yang Anda upload ke penyimpanan data Vertex AI Agent Builder. Untuk media, dokumen biasanya berisi informasi metadata tentang konten media, seperti video, artikel berita, file musik, atau podcast. Objek Document di API menangkap informasi metadata ini.

Penyimpanan data Anda berisi kumpulan dokumen yang telah Anda upload. Saat membuat penyimpanan data, Anda menentukan bahwa penyimpanan tersebut akan berisi dokumen media. Penyimpanan data untuk media hanya dapat dilampirkan ke aplikasi media, bukan ke jenis aplikasi lain seperti penelusuran dan rekomendasi umum. Penyimpanan data direpresentasikan dalam API oleh resource DataStore.

Kualitas data yang Anda upload memiliki efek langsung pada kualitas hasil yang diberikan aplikasi media. Secara umum, semakin akurat dan spesifik informasi yang dapat Anda berikan, semakin tinggi kualitas hasil Anda.

Data yang Anda upload ke penyimpanan data harus diformat dalam skema JSON tertentu. Data yang diatur dalam skema tersebut harus berada dalam tabel BigQuery, file, atau kumpulan file di Cloud Storage, atau dalam objek JSON yang dapat diupload langsung menggunakan konsol Google Cloud.

Skema standar Google versus skema kustom

Anda memiliki dua opsi untuk skema data media.

  • Skema standar Google. Jika Anda belum mendesain skema untuk data media, skema standar Google adalah pilihan yang tepat.

  • Skema Anda sendiri. Jika data Anda sudah diformat dalam skema, Anda dapat menggunakan skema Anda sendiri, dengan persyaratan berikut.

    Anda harus memiliki kolom dalam skema yang dapat dipetakan ke lima properti utama untuk media:

    • title
    • uri
    • category
    • media_available_time
    • media_duration Kolom ini penting untuk aplikasi rekomendasi media dengan tujuan bisnis untuk memaksimalkan rasio konversi (CVR) atau durasi tonton per pengunjung.

    Ada properti utama tambahan yang tidak diperlukan, tetapi untuk hasil berkualitas, petakan sebanyak mungkin properti ini ke skema Anda. Properti media ini adalah sebagai berikut:

    • description (sangat direkomendasikan)
    • 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

    Untuk mengetahui informasi selengkapnya tentang properti ini, lihat Properti kunci. Namanya serupa, tetapi beberapa nama sedikit berbeda. (Misalnya, beberapa nama diawali dengan media_ dan beberapa dibuat jamak.)

Skema JSON untuk Document

Saat menggunakan media, dokumen dapat menggunakan skema JSON standar Google untuk media.

Dokumen diupload dengan representasi data JSON atau Struct. Pastikan JSON atau Struct dokumen sesuai dengan skema JSON berikut. Skema JSON menggunakan JSON Schema 2020-12 untuk validasi. Untuk mengetahui informasi selengkapnya tentang JSON Schema, lihat juga dokumentasi spesifikasi JSON Schema di json-schema.org.

{
  "$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"],
}

Contoh objek Document JSON

Contoh berikut menunjukkan contoh objek Document JSON.

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

Kolom dokumen

Bagian ini mencantumkan nilai kolom yang Anda berikan saat membuat dokumen untuk penyimpanan data. Nilai harus sesuai dengan nilai yang digunakan dalam database dokumen internal Anda, dan harus mencerminkan item yang diwakili secara akurat.

Kolom objek Document

Kolom berikut adalah kolom tingkat atas untuk objek Document. Lihat juga kolom ini di halaman referensi Document.

Kolom Catatan
name Nama resource lengkap dan unik dari dokumen. Wajib untuk semua metode Document kecuali create dan import. Selama impor, nama akan otomatis dibuat dan tidak perlu diberikan secara manual.
id ID dokumen yang digunakan oleh database internal Anda. Kolom ID harus unik di seluruh datastore Anda. Nilai yang sama digunakan saat Anda merekam peristiwa pengguna, dan juga ditampilkan oleh metode recommend dan search.
schemaId Wajib. ID skema yang berada di penyimpanan data yang sama. Harus ditetapkan sebagai "default_schema", yang otomatis dibuat saat penyimpanan data default dibuat.
parentDocumentId ID dokumen induk. Untuk dokumen level teratas (root), parent_document_id dapat kosong atau dapat mengarah ke dirinya sendiri. Untuk dokumen turunan, parent_document_id harus mengarah ke dokumen root yang valid.

Properti utama

Properti berikut ditentukan menggunakan format Skema JSON yang telah ditentukan untuk media.

Untuk informasi selengkapnya tentang properti JSON, lihat dokumentasi Memahami Skema JSON untuk properti di json-schema.org.

Tabel berikut menentukan properti kunci datar.

Nama kolom Catatan
title

String - wajib

Judul dokumen dari database Anda. String yang dienkode UTF-8. Dibatasi hingga 1.000 karakter.

categories

String - wajib

Kategori dokumen. Properti ini diulang untuk mendukung satu dokumen yang termasuk dalam beberapa kategori paralel. Gunakan jalur kategori lengkap untuk mendapatkan hasil yang lebih berkualitas.

Untuk merepresentasikan jalur lengkap kategori, gunakan simbol > untuk memisahkan hierarki. Jika > adalah bagian dari nama kategori, ganti dengan karakter lain.

Contoh:

"categories": [ "sports > highlight" ]

Dokumen dapat berisi maksimal 250 kategori. Setiap kategori adalah string berenkode UTF-8 dengan batas panjang 5.000 karakter.

uri

String - wajib

URI dokumen. Batas panjang 5.000 karakter.

description

String - sangat direkomendasikan

Deskripsi dokumen. Batas panjang 5.000 karakter.

media_type

String - kolom ini wajib diisi untuk film dan acara TV

Kategori tingkat atas.

Jenis yang didukung: movie, show, concert, event, live-event, broadcast, tv-series, episode, video-game, clip, vlog, audio, audio-book, music, album, articles, news, radio, podcast, book, dan sports-game.

Nilai movie dan show memiliki signifikansi khusus. Hal ini menyebabkan dokumen diperkaya dengan cara yang meningkatkan peringkat dan membantu pengguna melakukan penelusuran judul untuk menemukan konten alternatif yang mungkin mereka minati.

language_code

String - opsional

Bahasa judul/deskripsi dan atribut string lainnya. Gunakan tag bahasa yang ditentukan oleh BCP 47.

Untuk rekomendasi dokumen, kolom ini diabaikan dan bahasa teks terdeteksi secara otomatis. Dokumen dapat menyertakan teks dalam bahasa yang berbeda, tetapi menduplikasi dokumen untuk menyediakan teks dalam beberapa bahasa dapat menyebabkan penurunan performa.

Untuk penelusuran dokumen, kolom ini digunakan. Defaultnya adalah "en-US" jika tidak ditetapkan. Misalnya, "language_code": "en-US".

duration

String - wajib untuk aplikasi rekomendasi media dengan tujuan bisnis rasio klik-tayang (CVR) atau durasi tonton per sesi.

Durasi konten media. Durasi harus dienkode sebagai string. Encoding harus sama dengan encoding string JSON google::protobuf::Duration. Misalnya: "5d", "1m"

available_time

Tanggal waktu - wajib diisi

Waktu konten tersedia untuk pengguna akhir. Kolom ini mengidentifikasi keaktualan konten untuk pengguna akhir. Stempel waktu harus sesuai dengan standar RFC 3339.

Contoh:

"2022-08-26T23:00:17Z"

expire_time

String - opsional

Waktu berakhirnya masa berlaku konten untuk pengguna akhir. Kolom ini mengidentifikasi keaktualan konten untuk pengguna akhir. Stempel waktu harus sesuai dengan standar RFC 3339.

Contoh:

"2032-12-31T23:00:17Z"

in_languages

String - opsional - berulang

Bahasa konten media. Gunakan tag bahasa yang ditentukan oleh BCP 47.

Contoh: "in_languages": [ "en-US"]

country_of_origin

String - opsional

Negara asal dokumen media. Batas panjang 128 karakter.

Contoh: "country_of_origin": "US"

content_index

Int - opsional

Indeks konten dokumen media. Kolom indeks konten dapat digunakan untuk mengurutkan dokumen relatif terhadap dokumen lain. Misalnya, nomor episode dapat digunakan sebagai indeks konten.

Indeks konten harus berupa bilangan bulat non-negatif.

Contoh: "content_index": 0

filter_tags

String - opsional - berulang

Memfilter tag untuk dokumen. Maksimal 250 nilai diizinkan per dokumen dengan batas panjang 1.000 karakter. Jika tidak, error INVALID_ARGUMENT akan ditampilkan.

Tag ini dapat digunakan untuk memfilter hasil rekomendasi dengan meneruskan tag sebagai bagian dari RecommendRequest.filter.

Contoh: "filter_tags": [ "filter_tag"]

hash_tags

String - opsional - berulang

Hashtag untuk dokumen. Maksimal 100 nilai diizinkan per dokumen, dengan batas panjang 5.000 karakter.

Contoh: "hash_tags": [ "soccer", "world cup"]

content_rating

String - opsional - berulang

Rating konten, yang digunakan untuk sistem saran konten dan pemfilteran konten berdasarkan audiens. Maksimal 100 nilai diizinkan per dokumen dengan batas panjang 128 karakter.

Tag ini dapat digunakan untuk memfilter hasil rekomendasi dengan meneruskan tag sebagai bagian dari RecommendRequest.filter.

Contoh: content_rating: ["PG-13"]

Tabel berikut menentukan properti kunci hierarkis.

Nama kolom Catatan
images

Objek - opsional - berulang

Properti kunci root untuk mengenkapsulasi properti terkait gambar.

images.uri

String - opsional

URI gambar. Batas panjang 5.000 karakter.

images.name

String - opsional

Nama gambar. Batas panjang 128 karakter.

persons

Objek - opsional - berulang

Properti kunci root untuk mengenkapsulasi properti terkait orang.

Misalnya: "persons":[{"name":"sports person","role":"player","rank":0,"uri":"http://example.com/person"}]

persons.name

String - wajib

Nama orang.

persons.role

String - wajib

Peran orang dalam item media.

Nilai yang didukung: sutradara, aktor, pemain, tim, liga, editor, penulis, karakter, kontributor, kreator, editor, pendana, produser, penyedia, penerbit, sponsor, penerjemah, musik-oleh, channel, peran-kustom

Jika tidak ada nilai yang didukung yang diterapkan ke role, tetapkan role ke custom-role dan berikan nilai di kolom custom_role.

persons.custom_role

String - opsional

custom_role ditetapkan jika dan hanya jika role ditetapkan menjadi custom-role. Harus berupa string yang dienkode UTF-8 dengan batas panjang 128 karakter. Harus cocok dengan pola: [a-zA-Z0-9][a-zA-Z0-9_]*.

persons.rank

Int - opsional

Digunakan untuk peringkat peran. Misalnya, untuk aktor pertama, role = "actor", rank = 1

persons.uri

String - opsional

URI orang.

organizations

Objek - opsional - berulang

Properti kunci root untuk mengenkapsulasi properti terkait organization.

Misalnya: "organizations ":[{"name":"sports team","role":"team","rank":0,"uri":"http://example.com/team"}]

organizations.name

String - wajib

Nama organisasi.

organizations.role

String - wajib

Peran organisasi dalam item media.

Nilai yang didukung: sutradara, aktor, pemain, tim, liga, editor, penulis, karakter, kontributor, kreator, editor, pendana, produser, penyedia, penerbit, sponsor, penerjemah, musik-oleh, channel, peran-kustom

Jika tidak ada nilai yang didukung yang diterapkan ke role, tetapkan role ke custom-role dan berikan nilai di kolom custom_role.

organizations.custom_role

String - opsional

custom_role ditetapkan jika dan hanya jika role ditetapkan menjadi custom-role. Harus berupa string yang dienkode UTF-8 dengan batas panjang 128 karakter. Harus cocok dengan pola: [a-zA-Z0-9][a-zA-Z0-9_]*.

organizations.rank

String - opsional

Digunakan untuk peringkat peran. Misalnya, untuk penayang pertama: role = "publisher", rank = 1.

organizations.uri

String - opsional

URI organisasi.

aggregate_ratings

Objek - opsional - berulang

Properti kunci root untuk mengenkapsulasi properti terkait aggregate_rating.

aggregate_ratings.rating_source

String - wajib

Sumber untuk rating. Misalnya, imdb atau rotten_tomatoes. Harus berupa string yang dienkode UTF-8 dengan batas panjang 128 karakter. Harus cocok dengan pola: [a-zA-Z0-9][a-zA-Z0-9_]*.

aggregate_ratings.rating_score

Ganda - opsional

Rating gabungan. Rating harus dinormalisasi ke rentang [1, 5].

aggregate_ratings.rating_count

Int - opsional

Jumlah ulasan individual. Harus berupa nilai positif.

Tingkat dokumen

Tingkat dokumen menentukan hierarki di penyimpanan data Anda. Biasanya, Anda harus memiliki penyimpanan data satu tingkat atau penyimpanan data dua tingkat. Hanya dua lapisan yang didukung.

Misalnya, Anda dapat memiliki penyimpanan data satu tingkat dengan setiap dokumen adalah item individual. Atau, Anda dapat memilih penyimpanan data dua tingkat yang berisi grup item dan item individual.

Jenis tingkat dokumen

Ada dua jenis tingkat dokumen:

  • Induk. Dokumen induk adalah dokumen yang ditampilkan Vertex AI Search dalam rekomendasi dan penelusuran. Induk dapat berupa dokumen individual atau grup dokumen yang serupa. Jenis tingkat ini direkomendasikan.

  • Turunan. Dokumen turunan adalah versi dokumen induk grup. Turunan hanya dapat berupa dokumen individual. Misalnya, jika dokumen induk adalah "Contoh Acara TV", turunan dapat berupa "Episode 1" dan "Episode 2". Jenis level ini mungkin sulit dikonfigurasi dan dikelola, dan tidak direkomendasikan.

Tentang hierarki penyimpanan data

Saat merencanakan hierarki penyimpanan data, tentukan apakah penyimpanan data Anda hanya berisi induk atau induk dan turunan. Poin penting yang perlu diingat adalah rekomendasi dan penelusuran hanya menampilkan dokumen induk.

Misalnya, penyimpanan data khusus orang tua mungkin berfungsi dengan baik untuk buku audio, dengan panel rekomendasi menampilkan pilihan buku audio individual. Di sisi lain, jika Anda mengupload episode acara TV sebagai dokumen induk ke penyimpanan data khusus induk, beberapa episode yang tidak berurutan dapat direkomendasikan di panel yang sama.

Penyimpanan data acara TV dapat berfungsi dengan induk dan turunan, dengan setiap dokumen induk mewakili acara TV dengan dokumen turunan yang mewakili episode acara TV tersebut. Penyimpanan data dua tingkat ini memungkinkan panel rekomendasi menampilkan berbagai acara TV yang serupa. Pengguna akhir dapat mengklik acara tertentu untuk memilih episode yang akan ditonton.

Karena hierarki induk-turunan dapat sulit dikonfigurasi dan dikelola, penyimpanan data khusus induk direkomendasikan.

Misalnya, penyimpanan data acara TV dapat berfungsi dengan baik sebagai penyimpanan data khusus induk dengan setiap dokumen induk mewakili acara TV yang dapat direkomendasikan, dan setiap episode tidak disertakan (sehingga tidak direkomendasikan).

Jika Anda menentukan bahwa penyimpanan data Anda harus memiliki induk dan turunan, yaitu grup dan item tunggal, tetapi saat ini Anda hanya memiliki item tunggal, Anda harus membuat induk untuk grup. Informasi minimum yang perlu Anda berikan untuk induk adalah id, title, dan categories. Untuk mengetahui informasi selengkapnya, lihat bagian Kolom dokumen.

Skema BigQuery untuk media

Jika Anda berencana mengimpor dokumen dari BigQuery, gunakan skema BigQuery standar untuk membuat tabel BigQuery dengan format yang benar dan muat dengan data dokumen sebelum Anda mengimpor dokumen.

[
  {
    "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": []
  }
]