Questa pagina è stata tradotta dall'API Cloud Translation.

Informazioni sui documenti multimediali e sui datastore

Questa pagina fornisce informazioni su documenti e datastore per contenuti multimediali. Se utilizzi consigli sui contenuti multimediali o la ricerca di contenuti multimediali, rivedi le requisiti di schema per i tuoi documenti e datastore in questa pagina prima caricare i dati.

Panoramica

Un documento è qualsiasi elemento che carichi in un datastore di Vertex AI Agent Builder. Per multimediali, un documento in genere contiene informazioni metadati contenuti multimediali, come video, articoli di notizie, file musicali podcast. L'oggetto Document nell'API acquisisce queste informazioni sui metadati.

Il tuo data store contiene una raccolta di documenti che hai caricato. Quando crei un datastore, specifichi 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 da la risorsa DataStore.

La qualità dei dati che carichi ha un effetto diretto sulla qualità dei i risultati forniti dalle app multimediali. In generale, più precisi e specifici informazioni che fornisci, migliori saranno i risultati.

I dati che carichi nel datastore devono essere formattati in un JSON specifico . I dati organizzati in questo schema devono essere in una tabella BigQuery, un file o un insieme di file in Cloud Storage oppure in un oggetto JSON che possono essere caricati direttamente utilizzando la console Google Cloud.

Confronto tra schema predefinito di Google e schema personalizzato

Hai 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 usare il tuo schema, con il seguente requisito.

Lo schema deve contenere campi che possono essere mappati alle cinque proprietà chiave per i contenuti multimediali:
- title
- uri
- category
- media_available_time
- media_duration Questo 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 che non sono obbligatorie, ma per la qualità di questi risultati, mappane il maggior numero possibile al tuo schema. Questi contenuti multimediali sono le seguenti:
- description (altamente consigliato)
- 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
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 pluralized.)

Schema JSON per `Document`

Quando si utilizzano contenuti multimediali, i documenti possono utilizzare lo schema JSON predefinito di Google per i media.

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. Il file JSON lo schema utilizza Schema JSON 2020-12 per la convalida. Per ulteriori informazioni sullo schema JSON, consulta anche Documentazione sulle specifiche degli schemi JSON all'indirizzo 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": "string",
    },
    "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 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"
}

Campi documento

Questa sezione elenca i valori di campo che fornisci quando crei i documenti per il tuo data store. I valori devono corrispondere a quelli utilizzati in database interno di Google e dovrebbe rispecchiare con precisione l'elemento rappresentato.

`Document` campi oggetto

I seguenti 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 data store. 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 situato nello stesso datastore. Deve essere impostato come "default_schema", che viene creato automaticamente quando viene creato un datastore predefinito.
`parentDocumentId`	L'ID del documento principale. Per i documenti di primo livello (root), Il campo `parent_document_id` può essere vuoto o puntare a se stesso. Per documenti secondari, `parent_document_id` deve indirizzare a un principale.

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 dal tuo database. Una stringa con codifica 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 la categoria completa per migliorare la qualità dei risultati. Per rappresentare il percorso completo di una categoria, utilizza il simbolo `>` per separare le gerarchie. Se `>` fa parte del nome della categoria, sostituiscilo con altri caratteri. Ad esempio: `"categories": [ "sports > highlight" ]` Un documento può contenere al massimo 250 categorie. Ogni categoria utilizza un linguaggio UTF-8 stringa codificata 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: `movie`, `show`, `concert`, `event`, `live-event`, `broadcast`, `tv-series`, `episode`, `video-game`, `clip`, `vlog`, `audio`, `audio-book`, `music`, `album`, `articles`, `news`, `radio`, `podcast`, `book` e `sports-game`. I valori `movie` e `show` hanno un significato speciale. Determinano l'arricchimento dei documenti in modo migliora il ranking e aiuta gli utenti che effettuano ricerche di titoli per trovare alternative contenuti a cui potrebbero essere interessati.
`language_code`	Stringa - facoltativa Lingua del titolo/della descrizione e di altri attributi di stringa. Utilizza le funzionalità di di linguaggio definiti BCP 47. Per i suggerimenti relativi ai documenti, questo campo viene ignorato e viene utilizzata la lingua di testo viene rilevata automaticamente. Il documento può includere testo in diversi lingue diverse, ma duplicando i documenti per fornire il testo in più lingue può compromettere le prestazioni. Per la ricerca di documenti, questo campo è in uso. Il valore predefinito è "en-US" se non viene configurato. Ad esempio, `"language_code": "en-US"`.
`duration`	Stringa: obbligatoria per le app per suggerimenti sui contenuti multimediali in cui l'attività è la percentuale di clic (CVR) o la durata della visualizzazione per sessione. Durata dei contenuti multimediali. La durata deve essere codificata come stringa. La codifica deve essere la stessa della `google::protobuf::Duration` codifica della stringa JSON. Ad esempio: "5 s", "1 m"
`available_time`	Stringa - obbligatoria 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 è conforme allo standard RFC 3339. Ad esempio: `"2022-08-26T23:00:17Z"`
`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: `"2032-12-31T23:00:17Z"`
`in_languages`	Stringa - facoltativa - ripetuta Lingua dei contenuti multimediali. Utilizza i tag per la lingua definiti da BCP 47. Ad esempio: `"in_languages": [ "en-US"]`
`country_of_origin`	Stringa (facoltativa) Paese di origine del documento multimediale. Lunghezza massima di 128 caratteri. Ad esempio: `"country_of_origin": "US"`
`content_index`	Int - facoltativo Indice dei contenuti del documento multimediale. Il campo Indice dei contenuti può essere utilizzato 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: `"content_index": 0`
`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. Altrimenti, . Questo tag può essere utilizzato per filtrare i risultati dei suggerimenti passando il parametro come parte di `RecommendRequest.filter`. Ad esempio: `"filter_tags": [ "filter_tag"]`
`hash_tags`	Stringa - facoltativa - ripetuta Hashtag per il documento. Sono consentiti al massimo 100 valori per documento. con un limite di lunghezza di 5000 caratteri. Ad esempio: `"hash_tags": [ "soccer", "world cup"]`
`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 al massimo 100 valori per documento con una lunghezza massima di 128 caratteri. Questo tag può essere utilizzato per filtrare i risultati dei suggerimenti passando il parametro come parte di `RecommendRequest.filter`. Ad esempio: `content_rating: ["PG-13"]`

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 radice per includere le proprietà relative alle persone. Ad esempio: `"persons":[{"name":"sports person","role":"player","rank":0,"uri":"http://example.com/person"}]`
`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 nessuno dei valori supportati viene applicato a `role`, imposta da `role` a `custom-role` e specifica il valore nel campo `custom_role`.
`persons.custom_role`	Stringa - facoltativa `custom_role` è impostato se e solo se `role` è impostato su `custom-role`. Deve essere una stringa codificata in UTF-8 con un limite di lunghezza di 128 caratteri. Deve corrispondere al pattern: `[a-zA-Z0-9][a-zA-Z0-9_]*`.
`persons.rank`	Int - facoltativo Utilizzato per il ranking dei ruoli. Ad esempio, per il primo attore, `role = "actor", rank = 1`
`persons.uri`	Stringa (facoltativa) URI della persona.
`organizations`	Oggetto (facoltativo) - ripetuto Proprietà della chiave principale per incapsulare le proprietà correlate a `organization`. Ad esempio: `"organizations ":[{"name":"sports team","role":"team","rank":0,"uri":"http://example.com/team"}]`
`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 `role` non viene applicato nessuno dei valori supportati, imposta `role` su `custom-role` e fornisci il valore nel campo `custom_role`.
`organizations.custom_role`	Stringa - facoltativa `custom_role` è impostato se e solo se `role` è impostato su `custom-role`. Deve essere una stringa codificata in UTF-8 con un limite di lunghezza di 128 caratteri. Deve corrispondere al pattern: `[a-zA-Z0-9][a-zA-Z0-9_]*`.
`organizations.rank`	Stringa (facoltativa) Utilizzato per il ranking dei ruoli. Ad esempio, per il primo editore: `role = "publisher", rank = 1`.
`organizations.uri`	Stringa - facoltativa URI dell'organizzazione.
`aggregate_ratings`	Oggetto (facoltativo) - ripetuto Proprietà chiave principale per incapsulare le proprietà correlate a `aggregate_rating`.
`aggregate_ratings.rating_source`	Stringa - obbligatoria La fonte della classificazione. Ad esempio, `imdb` o `rotten_tomatoes`. Deve essere una stringa con codifica UTF-8 e lunghezza di 128 caratteri. Deve corrispondere al pattern: `[a-zA-Z0-9][a-zA-Z0-9_]*`.
`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 di documento determinano la gerarchia del datastore. Di solito, deve avere un datastore a livello singolo o a due livelli. Sono supportati solo due livelli.

Ad esempio, puoi avere un datastore a livello singolo in cui ogni documento rappresenta un singolo elemento. In alternativa, puoi scegliere un data store 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 genitori possono essere documenti individuali o gruppi di documenti simili. Questo tipo di livello è consigliato.
Figlio. 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 dei datastore

Quando pianifichi la gerarchia del datastore, decidi se il datastore deve contenere solo genitori o genitori e figli. Il punto chiave da ricordare è che i consigli e le ricerche restituiscono solo i documenti principali.

Ad esempio, un data store riservato ai 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 data store 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 come datastore solo per i genitori in cui ogni documento principale rappresenta un programma TV che può essere consigliato; le singole puntate non vengono incluse (quindi sono sconsigliate).

Se stabilisci che il tuo data store 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": []
  }
]