Cette page fournit des informations sur les documents et les data stores pour les médias. Si vous utilisez les recommandations de contenus multimédias ou la recherche multimédia, consultez les exigences concernant les schémas pour vos documents et vos data stores sur cette page avant d'importer vos données.
Présentation
Un document est un élément que vous importez dans un data store Vertex AI Agent Builder. Pour les contenus multimédias, un document contient généralement des informations de métadonnées sur le contenu multimédia, comme des vidéos, des articles d'actualité, des fichiers musicaux ou des podcasts. L'objet Document
de l'API capture ces informations de métadonnées.
Votre data store contient une collection de documents que vous avez importés. Quand ?
lorsque vous créez un data store, vous indiquez qu'il contiendra des documents multimédias. Données
les magasins de contenus multimédias ne peuvent être associés qu'à des applications multimédias, et non à d'autres types d'applications :
sous forme de recherche générique et de recommandations. Dans l'API, les datastores sont représentés par la ressource DataStore
.
La qualité des données que vous importez a un effet direct sur la qualité des résultats fournis par les applications multimédias. En règle générale, plus les informations sont précises et spécifiques, plus la qualité des résultats est élevée.
Les données que vous importez dans le magasin de données doivent être mises en forme dans un schéma JSON spécifique. Les données organisées dans ce schéma doivent se trouver dans une table BigQuery, un fichier ou un ensemble de fichiers dans Cloud Storage, ou dans un objet JSON qui peuvent être importées directement à l'aide de la console Google Cloud.
Schéma Google prédéfini et schéma personnalisé
Deux options s'offrent à vous pour votre schéma de données multimédias.
Schéma Google prédéfini. Si vous n'avez pas encore conçu de schéma pour vos données multimédias, le schéma prédéfini de Google est un bon choix.
Votre propre schéma. Si vos données sont déjà mises en forme dans un schéma, vous pouvez utiliser votre propre schéma, à condition que les exigences suivantes soient respectées.
Votre schéma doit comporter des champs pouvant être mappés aux cinq clés Propriétés des médias:
title
uri
category
media_available_time
media_duration
Ce champ est important pour les applications de recommandations de contenus multimédias dont l'objectif commercial est de maximiser le taux de conversion la durée de visionnage par visiteur.
D'autres propriétés clés ne sont pas obligatoires, mais pour obtenir des résultats de qualité, mappez-en autant que possible à votre schéma. Ces propriétés multimédias sont les suivantes :
description
(fortement recommandé)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
Pour en savoir plus sur ces propriétés, consultez la section propriétés. Les noms sont similaires, mais certains varient légèrement. (Par exemple, certains noms sont précédés de
media_
et d'autres sont au pluriel.)
Schéma JSON pour Document
Lorsque vous utilisez des contenus multimédias, les documents peuvent utiliser le schéma JSON prédéfini de Google pour les contenus multimédias.
Les documents sont importés avec une représentation de données JSON ou Struct. Marque assurez-vous que le fichier JSON ou Struct du document est conforme au schéma JSON suivant. Le fichier JSON utilisation du schéma Schéma JSON 2020-12 pour validation. Pour en savoir plus sur le schéma JSON, consultez également la documentation de spécification du schéma JSON sur 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"], }
Exemple d'objet JSON Document
L'exemple suivant présente un objet 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" }
Champs du document
Cette section liste les valeurs de champ que vous fournissez lorsque vous créez des documents. pour votre data store. Les valeurs doivent correspondre à celles utilisées dans vos de documents internes, et doit refléter précisément l'article représenté.
Champs d'objet Document
Les champs suivants sont des champs de premier niveau pour l'objet Document
. Consultez également ces champs sur la page de référence Document
.
Champ | Remarques |
---|---|
name
|
Nom de ressource unique complet du document. Obligatoire pour tous
Méthodes Document , à l'exception de create et
import Lors de l'importation, le nom est généré automatiquement
et n'a pas besoin d'être fourni manuellement.
|
id
|
ID du document utilisé par votre base de données interne. Le champ d'ID doit être unique dans l'ensemble de votre magasin de données. La même valeur est utilisée lorsque vous enregistrez un événement utilisateur. Elle est également renvoyée par les méthodes recommend et search .
|
schemaId
|
Obligatoire. Identifiant du schéma situé dans le même data store. Doit être défini sur "default_schema", qui est créé automatiquement lors de la création du magasin de données par défaut. |
parentDocumentId
|
ID du document parent. Pour les documents de premier niveau (racine),
parent_document_id peut être vide ou pointer vers lui-même. Pour les documents enfants, parent_document_id doit pointer vers un document racine valide.
|
Propriétés clés
Les propriétés suivantes sont définies à l'aide du format de schéma JSON prédéfini pour les contenus multimédias.
Pour en savoir plus sur les propriétés JSON, consultez la page "Comprendre le schéma JSON". documentation pour propriétés sur json-schema.org.
Le tableau suivant définit les propriétés des clés plates.
Nom du champ | Remarques |
---|---|
title
|
Chaîne : obligatoire Titre du document issu de votre base de données. Chaîne encodée en UTF-8. Limité à 1 000 caractères. |
categories
|
Chaîne : obligatoire Catégories de documents Cette propriété est répétée pour prendre en charge un document appartenant à plusieurs catégories parallèles. Utilisez le chemin d'accès complet de la catégorie pour obtenir des résultats de meilleure qualité.
Pour représenter le chemin d'accès complet d'une catégorie, utilisez le symbole Exemple :
Un document peut contenir jusqu'à 250 catégories. Chaque catégorie est un format UTF-8 une chaîne encodée de 5 000 caractères maximum. |
uri
|
Chaîne : obligatoire URI du document. 5 000 caractères maximum. |
description
|
Chaîne : vivement recommandé Description du document. Il ne doit pas dépasser 5 000 caractères. |
media_type
|
Chaîne : ce champ est obligatoire pour les films et les séries. Catégorie racine.
Types compatibles:
Les valeurs |
language_code
|
Chaîne (facultatif) Langue du titre/de la description et des autres attributs de chaîne. Utilisez les balises de langue définies par BCP 47. Pour les recommandations de documents, ce champ est ignoré et la langue du texte est détectée automatiquement. Le document peut inclure du texte dans différentes langues. Toutefois, la duplication des documents pour fournir du texte dans plusieurs langues peut nuire aux performances.
Ce champ est déjà utilisé pour la recherche de documents. La valeur par défaut est "en-US". si elle n'est pas définie.
Par exemple, |
duration
|
Chaîne : obligatoire pour les applications de recommandations de médias dans lesquelles l'entreprise l'objectif est le taux de clics (CVR) ou la durée de visionnage par session.
Durée du contenu multimédia. La durée doit être encodée sous forme de chaîne.
L'encodage doit être identique à celui de la chaîne JSON |
available_time
|
Chaîne : obligatoire Heure à laquelle le contenu est disponible pour les utilisateurs finaux. Ce champ indique la fraîcheur d'un contenu pour les utilisateurs finaux. Le code temporel doit respecter la norme RFC 3339. Exemple :
|
expire_time
|
Chaîne (facultatif) Heure d'expiration du contenu pour les utilisateurs finaux. Ce champ identifie la fraîcheur d'un contenu pour les utilisateurs finaux. Le code temporel doit respecter la norme RFC 3339. Exemple :
|
in_languages
|
Chaîne – facultative – répétée Langue des contenus multimédias. Utilisez les balises de langue définies par le standard BCP 47.
Par exemple : |
country_of_origin
|
Chaîne (facultatif) Pays d'origine du document multimédia. Il ne doit pas dépasser 128 caractères.
Par exemple : |
content_index
|
Int : facultatif Index de contenu du document multimédia. Le champ d'index de contenu peut être utilisé pour ordonner les documents par rapport aux autres. Par exemple, le numéro d'épisode peut être utilisé comme indice de contenu. L'indice de contenu doit être un nombre entier non négatif.
Par exemple : |
filter_tags
|
Chaîne (facultatif, répété) Filtrer les balises du document 250 valeurs maximum sont autorisées par document avec une longueur maximale de 1 000 caractères. Dans le cas contraire, une erreur INVALID_ARGUMENT est renvoyée.
Cette balise peut être utilisée pour filtrer les résultats de recommandation en transmettant la balise dans le
Par exemple : |
hash_tags
|
Chaîne (facultatif, répété) Hashtags du document. Un document peut contenir jusqu'à 100 valeurs. avec une longueur maximale de 5 000 caractères.
Par exemple : |
content_rating
|
Chaîne – facultative – répétée La classification du contenu, utilisée pour les systèmes de conseil et les contenus en fonction de l'audience. Vous ne pouvez pas dépasser 100 valeurs par ne doit pas dépasser 128 caractères.
Cette balise peut être utilisée pour filtrer les résultats des recommandations en transmettant le paramètre
dans
Par exemple : |
Le tableau suivant définit les propriétés des clés hiérarchiques.
Nom du champ | Remarques |
---|---|
images
|
Objet – Facultatif – répété Propriété de clé racine permettant d'encapsuler les propriétés liées à l'image. |
images.uri
|
Chaîne (facultatif) URI de l'image. Nombre maximal de caractères : 5 000. |
images.name
|
Chaîne (facultatif) Nom de l'image. La longueur maximale est de 128 caractères. |
persons
|
Objet – Facultatif – répété Propriété de la clé racine permettant d'encapsuler les propriétés liées aux personnes.
Par exemple :
|
persons.name
|
Chaîne (obligatoire) Nom de la personne. |
persons.role
|
Chaîne : obligatoire Rôle de la personne dans l'élément multimédia. Valeurs acceptées: réalisateur, acteur, joueur, équipe, ligue, éditeur, auteur, personnage, contributeur, créateur, éditeur, bailleurs de fonds, producteur, fournisseur éditeur, sponsor, traducteur, musique par, chaîne, rôle personnalisé
Si aucune des valeurs compatibles n'est appliquée à |
persons.custom_role
|
Chaîne (facultatif)
|
persons.rank
|
Int : facultatif
Utilisé pour le classement des rôles. Par exemple, pour le premier acteur,
|
persons.uri
|
Chaîne (facultatif) URI de la personne. |
organizations
|
Objet – Facultatif – répété
Propriété de clé racine pour encapsuler les propriétés liées à
Par exemple :
|
organizations.name
|
Chaîne : obligatoire Nom de l'organisation. |
organizations.role
|
Chaîne : obligatoire Rôle de l'organisation dans le contenu multimédia. Valeurs acceptées : réalisateur, acteur, joueur, équipe, ligue, éditeur, auteur, personnage, contributeur, créateur, éditeur, financeur, producteur, fournisseur, éditeur, sponsor, traducteur, music-by, chaîne, rôle personnalisé
Si aucune des valeurs acceptées n'est appliquée à |
organizations.custom_role
|
Chaîne (facultatif)
|
organizations.rank
|
Chaîne (facultatif)
Utilisé pour le classement des rôles. Par exemple, pour le premier éditeur:
|
organizations.uri
|
Chaîne (facultatif) URI de l'organisation. |
aggregate_ratings
|
Objet – Facultatif – répété
Propriété de la clé racine permettant d'encapsuler le
|
aggregate_ratings.rating_source
|
Chaîne (obligatoire)
Source de la note. Par exemple, |
aggregate_ratings.rating_score
|
Double (facultatif) Note globale. La note doit être normalisée dans la plage [1, 5]. |
aggregate_ratings.rating_count
|
Int (facultatif) Nombre d'avis individuels. La valeur doit être non négative. |
Niveaux de document
Les niveaux de document déterminent la hiérarchie dans votre magasin de données. En règle générale, vous devez disposer d'un datastore à un ou deux niveaux. Seulement deux couches sont pris en charge.
Par exemple, vous pouvez avoir un data store à un seul niveau dans lequel chaque document est un élément individuel. Vous pouvez également choisir un data store à deux niveaux qui contient à la fois des groupes d'articles et des éléments individuels.
Types au niveau du document
Il existe deux types de niveaux de document:
Parent. Ce sont les documents parents que Vertex AI Search renvoie dans les recommandations et les recherches. Les parents peuvent être des documents individuels ou des groupes de documents similaires. Ce type de niveau est recommandé.
Enfant. Les documents enfants sont des versions du document parent d'un groupe. Les enfants ne peuvent être que des documents individuels. Par exemple, si le document parent est "Exemple de série TV", le nombre d'enfants peut être "Épisode 1" et "Épisode 2". Ce type de niveau peut être difficile à configurer et à gérer, et n'est pas recommandé.
À propos de la hiérarchie des data store
Lors de la planification de la hiérarchie de votre data store, déterminez si votre data store doit ne contiennent que des parents ou des parents et enfants. Le point essentiel à retenir est que les recommandations et les recherches ne renvoient que des documents parents.
Par exemple, un entrepôt de données réservé aux parents peut être adapté aux livres audio, où un panneau de recommandations renvoie une sélection de livres audio individuels. De l'autre Si vous importez les épisodes d'une série TV en tant que documents parents dans un dossier de données plusieurs épisodes dans le désordre peuvent être recommandés dans le même panneau.
Un entrepôt de données d'émissions télévisées peut fonctionner à la fois avec des parents et des enfants, chaque document parent représentant une émission télévisée avec des documents enfants représentant les épisodes de cette émission. Ce data store à deux niveaux permet de recommander pour afficher une série d'émissions télévisées similaires. L'utilisateur final peut cliquer sur une émission spécifique pour sélectionner un épisode à regarder.
Comme les hiérarchies parent-enfant peuvent être difficiles à configurer et à gérer, les data stores "parent uniquement" sont recommandés.
Par exemple, un data store d'émission télévisée peut fonctionner comme data store réservé aux parents. où chaque document parent représente une série TV pouvant être recommandée ; les épisodes individuels ne sont pas inclus (et ne sont donc pas recommandés).
Si vous déterminez que votre data store
doit avoir des parents et des enfants,
c'est-à-dire des groupes et des éléments singuliers, mais que vous n'avez plus que des éléments singuliers,
devez créer des parents
pour les groupes. Les informations minimales que vous devez fournir pour un parent sont id
, title
et categories
. Pour plus d'informations,
consultez la section Champs du document.
Schéma BigQuery pour les contenus multimédias
Si vous prévoyez d'importer vos documents à partir de BigQuery, utilisez le schéma BigQuery prédéfini pour créer une table BigQuery au format approprié et y insérer vos données de documents avant d'importer vos documents.
[ { "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": [] } ]