Halaman ini diterjemahkan oleh Cloud Translation API.

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 hasilnya.

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 penyimpanan data 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 yang 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": []
  }
]