Questa pagina fornisce informazioni su documenti e data store per i contenuti multimediali. Se utilizzi i suggerimenti sui contenuti multimediali o la ricerca di contenuti multimediali, prima di caricare i dati, consulta i requisiti dello schema per i documenti e i datastore in questa pagina.
Panoramica
Un documento è qualsiasi elemento caricato in un datastore di Vertex AI Agent Builder. Per i contenuti multimediali, un documento in genere contiene informazioni sui metadati dei contenuti multimediali, come video, articoli di notizie, file musicali o podcast. L'oggetto Document nell'API acquisisce queste informazioni sui metadati.
Il tuo datastore contiene una raccolta di documenti che hai caricato. Quando crei un datastore, specifica che conterrà documenti multimediali. I datastore per i contenuti multimediali possono essere collegati solo ad app multimediali, non ad altri tipi di app come la ricerca generica e i consigli. I datastore sono rappresentati nell'API dalla risorsa DataStore.
La qualità dei dati che carichi ha un effetto diretto sulla qualità dei risultati forniti dalle app multimediali. In generale, più accurate e specifiche sono le informazioni che fornisci, più alta sarà la qualità dei risultati.
I dati caricati nell'datastore devono essere formattati in uno schema JSON specifico. I dati organizzati in questo schema devono trovarsi in una tabella BigQuery, in un file o in un insieme di file in Cloud Storage o in un oggetto JSON che puoi caricare direttamente utilizzando la console Google Cloud.
Schema predefinito di Google e schema personalizzato
Hai a disposizione due opzioni per lo schema dei dati multimediali.
Lo schema predefinito di Google. Se non hai ancora progettato uno schema per i tuoi dati multimediali, lo schema predefinito di Google è una buona scelta.
Il tuo schema. Se i tuoi dati sono già formattati in uno schema, puoi utilizzare il tuo schema, con il seguente requisito.
Lo schema deve contenere campi che possono essere mappati alle cinque proprietà chiave per i media:
titleuricategorymedia_available_timemedia_durationQuesto campo è importante per le app di consigli sui contenuti multimediali in cui lo scopo commerciale è massimizzare il tasso di conversione (CVR) o la durata di visualizzazione per visitatore.
Esistono altre proprietà chiave non obbligatorie, ma per risultati di qualità, mappane il maggior numero possibile allo schema. Queste proprietà media sono le seguenti:
description(altamente consigliato)imageimage_nameimage_urilanguage-codemedia_aggregated_ratingmedia_aggregated_rating_countmedia_aggregated_rating_scoremedia_aggregated_rating_sourcemedia_content_indexmedia_content_ratingmedia_country_of_originmedia_expire_timemedia_filter_tagmedia_hash_tagmedia_in_languagemedia_organizationmedia_organization_custom_rolemedia_organization_namemedia_organization_rankmedia_organization_rolemedia_organization_urimedia_personmedia_person_custom_rolemedia_person_namemedia_person_rankmedia_person_rolemedia_person_urimedia_production_yearmedia_type
Per ulteriori informazioni su queste proprietà, consulta la sezione Proprietà chiave. I nomi sono simili, ma alcuni variano leggermente. Ad esempio, alcuni nomi sono preceduti da
media_e altri sono declinati al plurale.
Schema JSON per Document
Quando utilizzi i contenuti multimediali, i documenti possono utilizzare lo schema JSON predefinito di Google per i contenuti multimediali.
I documenti vengono caricati con una rappresentazione dei dati JSON o Struct. Assicurati che il documento JSON o lo struct sia conforme allo schema JSON seguente. Lo schema JSON utilizza JSON Schema 2020-12 per la convalida. Per saperne di più su JSON Schema, consulta anche la documentazione della specifica JSON Schema su 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"], }
Oggetto JSON Document di esempio
L'esempio seguente mostra un esempio di oggetto 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" }
Campi documento
Questa sezione elenca i valori di campo che fornisci quando crei i documenti per il tuo datastore. I valori devono corrispondere a quelli utilizzati nel database di documenti interno e devono rispecchiare con precisione l'elemento rappresentato.
Campi oggetto Document
I seguenti campi sono campi di primo livello per l'oggetto Document. Consulta inoltre questi campi nella pagina di riferimento Document.
| Campo | Note |
|---|---|
name
|
Il nome completo e univoco della risorsa del documento. Obbligatorio per tutti
metodi Document, ad eccezione di create e
import. Durante l'importazione, il nome viene generato automaticamente
e non è necessario fornirlo manualmente.
|
id
|
L'ID documento utilizzato dal tuo database interno. Il campo ID deve essere
univoco nell'intero datastore. Lo stesso valore viene utilizzato quando
registri un evento utente e viene restituito anche dai metodi recommend
e search.
|
schemaId
|
Obbligatorio. L'identificatore dello schema nello stesso datastore. Deve essere impostato su "default_schema", che viene creato automaticamente quando viene creato l'datastore predefinito. |
parentDocumentId
|
L'ID del documento principale. Per i documenti di primo livello (radice),
parent_document_id può essere vuoto o può fare riferimento a se stesso. Per i documenti secondari, parent_document_id deve fare riferimento a un documento principale valido.
|
Proprietà chiave
Le seguenti proprietà sono definite utilizzando il formato JSON Schema predefinito per i contenuti multimediali.
Per ulteriori informazioni sulle proprietà JSON, consulta la documentazione relativa alla comprensione di JSON Schema per le proprietà su json-schema.org.
La tabella seguente definisce le proprietà delle chiavi piatte.
| Nome campo | Note |
|---|---|
title
|
Stringa - obbligatoria Titolo del documento del tuo database. Una stringa codificata UTF-8. Sono consentiti massimo 1000 caratteri. |
categories
|
Stringa - obbligatoria Categorie di documenti. Questa proprietà viene ripetuta per supportare un documento appartenente a più categorie parallele. Utilizza il percorso completo della categoria per risultati di qualità superiore.
Per rappresentare il percorso completo di una categoria, utilizza il simbolo Ad esempio:
Un documento può contenere al massimo 250 categorie. Ogni categoria è una stringa codificata UTF-8 con un limite di lunghezza di 5000 caratteri. |
uri
|
Stringa - obbligatoria URI del documento. Lunghezza massima di 5000 caratteri. |
description
|
Stringa: vivamente consigliata Descrizione del documento. Lunghezza massima di 5000 caratteri. |
media_type
|
Stringa: questo campo è obbligatorio per film e programmi Categoria di primo livello.
Tipi supportati:
I valori |
language_code
|
Stringa (facoltativa) Lingua del titolo/della descrizione e di altri attributi di stringa. Utilizza i tag lingua definiti da BCP 47. Per il consiglio del documento, questo campo viene ignorato e la lingua del testo viene rilevata automaticamente. Il documento può includere testo in lingue diverse, ma la duplicazione dei documenti per fornire testo in più lingue può comportare un calo del rendimento.
Per la ricerca di documenti, questo campo è in uso. Se non viene impostato, il valore predefinito è "en-US".
Ad esempio, |
duration
|
Stringa: obbligatoria per le app per suggerimenti sui contenuti multimediali in cui l'obiettivo commerciale è la percentuale di clic (CVR) o la durata di visualizzazione per sessione.
Durata dei contenuti multimediali. La durata deve essere codificata come stringa.
La codifica deve essere la stessa della |
available_time
|
Data/ora - obbligatorio Il momento in cui i contenuti sono disponibili per gli utenti finali. Questo campo identifica l'aggiornamento dei contenuti per gli utenti finali. Il timestamp deve essere conforme allo standard RFC 3339. Ad esempio:
|
expire_time
|
Stringa (facoltativa) La data di scadenza dei contenuti per gli utenti finali. Questo campo identifica l'aggiornamento dei contenuti per gli utenti finali. Il timestamp deve essere conforme allo standard RFC 3339. Ad esempio:
|
in_languages
|
Stringa - facoltativa - ripetuta Lingua dei contenuti multimediali. Utilizza i tag lingua definiti da BCP 47.
Ad esempio: |
country_of_origin
|
Stringa (facoltativa) Paese di origine del documento multimediale. Lunghezza massima di 128 caratteri.
Ad esempio: |
content_index
|
Int - facoltativo Indice dei contenuti del documento multimediale. Il campo dell'indice dei contenuti può essere utilizzato per ordinare i documenti rispetto ad altri. Ad esempio, il numero di puntata può essere utilizzato come indice dei contenuti. L'indice dei contenuti deve essere un numero intero non negativo.
Ad esempio: |
filter_tags
|
Stringa - facoltativa - ripetuta Filtra i tag per il documento. Sono consentiti al massimo 250 valori per documento con un limite di lunghezza di 1000 caratteri. In caso contrario, viene restituito un errore INVALID_ARGUMENT.
Questo tag può essere utilizzato per filtrare i risultati dei consigli passando il
tag come parte del
Ad esempio: |
hash_tags
|
Stringa - facoltativa - ripetuta Hashtag per il documento. Sono consentiti massimo 100 valori per documento, con un limite di lunghezza di 5000 caratteri.
Ad esempio: |
content_rating
|
Stringa - facoltativa - ripetuta La classificazione dei contenuti, utilizzata per i sistemi di consulenza sui contenuti e per il filtro dei contenuti in base al pubblico. Sono consentiti massimo 100 valori per documento con un limite di lunghezza di 128 caratteri.
Questo tag può essere utilizzato per filtrare i risultati dei consigli passando il
tag come parte del
Ad esempio: |
La tabella seguente definisce le proprietà delle chiavi gerarchiche.
| Nome campo | Note |
|---|---|
images
|
Oggetto (facoltativo) - ripetuto Proprietà della chiave principale per l'incapsulamento delle proprietà relative alle immagini. |
images.uri
|
Stringa (facoltativa) URI dell'immagine. Lunghezza massima di 5000 caratteri. |
images.name
|
Stringa (facoltativa) Nome dell'immagine. Lunghezza massima di 128 caratteri. |
persons
|
Oggetto (facoltativo) - ripetuto Proprietà della chiave principale per incapsulare le proprietà correlate alla persona.
Ad esempio:
|
persons.name
|
Stringa - obbligatoria Nome della persona. |
persons.role
|
Stringa - obbligatoria Il ruolo della persona nell'elemento multimediale. Valori supportati: director, actor, player, team, league, editor, author, character, contributor, creator, editor, funder, producer, provider, publisher, sponsor, translator, music-by, channel, custom-role
Se a |
persons.custom_role
|
Stringa (facoltativa)
|
persons.rank
|
Int - facoltativo
Utilizzato per il ranking dei ruoli. Ad esempio, per il primo attore,
|
persons.uri
|
Stringa (facoltativa) URI della persona. |
organizations
|
Oggetto (facoltativo) - ripetuto
Proprietà della chiave principale per incapsulare le proprietà correlate a
Ad esempio:
|
organizations.name
|
Stringa - obbligatoria Nome dell'organizzazione. |
organizations.role
|
Stringa - obbligatoria Il ruolo dell'organizzazione nell'elemento multimediale. Valori supportati: director, actor, player, team, league, editor, author, character, contributor, creator, editor, funder, producer, provider, publisher, sponsor, translator, music-by, channel, custom-role
Se a |
organizations.custom_role
|
Stringa (facoltativa)
|
organizations.rank
|
Stringa (facoltativa)
Utilizzato per il ranking dei ruoli. Ad esempio, per il primo editore:
|
organizations.uri
|
Stringa (facoltativa) URI dell'organizzazione. |
aggregate_ratings
|
Oggetto (facoltativo) - ripetuto
Proprietà chiave principale per incapsulare le proprietà correlate a |
aggregate_ratings.rating_source
|
Stringa - obbligatoria
La fonte della classificazione. Ad esempio, |
aggregate_ratings.rating_score
|
Doppio - facoltativo La valutazione aggregata. La valutazione deve essere normalizzata nell'intervallo [1, 5]. |
aggregate_ratings.rating_count
|
Int - facoltativo Il numero di recensioni singole. Deve essere un valore non negativo. |
Livelli di documento
I livelli dei documenti determinano la gerarchia nel tuo datastore. In genere, dovresti avere un datastore a un livello o a due livelli. Sono supportati solo due livelli.
Ad esempio, puoi avere un datastore a un livello in cui ogni documento è un singolo elemento. In alternativa, puoi scegliere un datastore a due livelli che contenga sia gruppi di elementi sia singoli elementi.
Tipi a livello di documento
Esistono due tipi a livello di documento:
Genitore. I documenti principali sono quelli restituiti da Vertex AI Search nei consigli e nelle ricerche. I documenti principali possono essere singoli documenti o gruppi di documenti simili. Questo tipo di livello è consigliato.
Bambino. I documenti secondari sono versioni del documento principale di un gruppo. I bambini possono essere solo singoli documenti. Ad esempio, se il documento principale è "Programma TV di esempio", i documenti secondari potrebbero essere "Puntata 1" e "Puntata 2". Questo tipo di livello può essere difficile da configurare e gestire e non è consigliato.
Informazioni sulla gerarchia del datastore
Quando pianifichi la gerarchia del tuo datastore, decidi se deve contenere solo elementi principali o elementi principali e secondari. Il punto chiave da ricordare è che i consigli e le ricerche restituiscono solo i documenti principali.
Ad esempio, un datastore solo per i genitori potrebbe funzionare bene per gli audiolibri, in cui un riquadro dei consigli restituisce una selezione di singoli audiolibri. D'altra parte, se hai caricato gli episodi di un programma TV come documenti principali in un data store solo per i documenti principali, nello stesso riquadro potrebbero essere consigliati diversi episodi fuori sequenza.
Un datastore di programmi TV potrebbe funzionare sia con i documenti principali che con quelli secondari, in cui ogni documento principale rappresenta un programma TV con documenti secondari che rappresentano le puntate del programma TV. Questo datastore a due livelli consente al riquadro di suggerimenti di mostrare una serie di programmi TV simili. L'utente finale può fare clic su un determinato programma per selezionare una puntata da guardare.
Poiché le gerarchie padre-figlio possono essere difficili da configurare e gestire, è consigliabile utilizzare datastore solo per i dati principali.
Ad esempio, un datastore di programmi TV può funzionare bene come datastore solo per i documenti principali, dove ogni documento principale rappresenta un programma TV che può essere consigliato e le singole puntate non sono incluse (e quindi non consigliate).
Se stabilisci che il tuo datastore deve avere sia elementi principali che elementi secondari, ovvero gruppi e articoli singoli, ma al momento hai solo articoli singoli, devi creare elementi principali per i gruppi. Le informazioni minime che devi fornire per un genitore sono id, title e categories. Per ulteriori informazioni, consulta la sezione Campi dei documenti.
Schema BigQuery per i contenuti multimediali
Se prevedi di importare i documenti da BigQuery, utilizza lo schema BigQuery predefinito per creare una tabella BigQuery con il formato corretto e caricarla con i dati dei documenti prima di importare i documenti.
[ { "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": [] } ]