À propos des documents multimédias et des datastores

Cette page fournit des informations sur les documents et les magasins de données pour les contenus multimédias. Si vous utilisez les recommandations de contenus multimédias ou la recherche de contenus multimédias, 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. Lorsque vous créez un data store, vous spécifiez qu'il contiendra des documents multimédias. Les data stores pour les contenus multimédias ne peuvent être associés qu'à des applications multimédias, et non à d'autres types d'applications telles que la recherche générique et les 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 data store 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 pouvant être importé directement à l'aide de la console Google Cloud.

Schéma prédéfini Google par rapport à un 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 propriétés clés pour les contenus multimédias:

    • title
    • uri
    • category
    • media_available_time
    • media_duration Ce champ est important pour les applications de recommandations multimédias dont l'objectif commercial est de maximiser le taux de conversion (CTR) ou 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 (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 de clé. 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. Assurez-vous que le document JSON ou la struct correspondent au schéma JSON suivant. Le schéma JSON utilise JSON Schema 2020-12 pour la 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": "datetime",
    },
    "expire_time": {
      "type": "string",
    },
    "production_year": {
      "type": "integer",
    }
  },
  "required": ["title", "categories", "uri", "available_time"],
}

Exemple d'objet JSON Document

L'exemple suivant montre un exemple d'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 votre base de données de documents internes et doivent refléter avec précision l'élément représenté.

Champs d'objet Document

Les champs suivants sont des champs de niveau supérieur 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 toutes les 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 de document utilisé par votre base de données interne. Le champ d'ID doit être unique dans l'ensemble de votre data store. 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 data store par défaut.
parentDocumentId ID du document parent. Pour les documents de premier niveau (racine), parent_document_id peut être vide ou pointer sur 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 documentation sur la compréhension des schémas JSON pour les propriétés sur json-schema.org.

Le tableau suivant définit les propriétés de clé plates.

Nom du champ Remarques
title

Chaîne : obligatoire

Titre du document dans votre base de données. Chaîne encodée en UTF-8. 1 000 caractères maximum.

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 > pour séparer les hiérarchies. Si > fait partie du nom de la catégorie, remplacez-le par un ou plusieurs autres caractères.

Exemple :

"categories": [ "sports > highlight" ]

Un document ne peut contenir au maximum 250 catégories. Chaque catégorie est une chaîne encodée en UTF-8 limitée à 5 000 caractères.

uri

Chaîne : obligatoire

URI du document. 5 000 caractères maximum.

description

Chaîne : vivement recommandé

Description du document. 5 000 caractères maximum.

media_type

Chaîne : ce champ est obligatoire pour les films et les séries

Catégorie racine.

Types acceptés: movie, show, concert, event, live-event, broadcast, tv-series, episode, video-game, clip, vlog, audio, audio-book, music, album, articles, news, radio, podcast, book et sports-game.

Les valeurs movie et show ont une signification particulière. Ils enrichissent les documents de manière à améliorer leur classement et à aider les utilisateurs à effectuer des recherches par titre pour trouver d'autres contenus susceptibles de les intéresser.

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 utilisé pour la recherche de documents. La valeur par défaut est "en-US" si elle n'est pas définie. Par exemple, "language_code": "en-US".

duration

Chaîne : obligatoire pour les applications de recommandations de contenus multimédias dont l'objectif commercial est le taux de clics (CTR) 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 google::protobuf::Duration. Exemple: "5s", "1m"

available_time

Date/Heure (obligatoire)

Date à laquelle le contenu est disponible 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 :

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

expire_time

Chaîne (facultatif)

Date 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 :

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

in_languages

Chaîne (facultatif, répété)

Langue des contenus multimédias. Utilisez les balises de langue définies par la norme BCP 47.

Par exemple : "in_languages": [ "en-US"]

country_of_origin

Chaîne (facultatif)

Pays d'origine du document multimédia. La longueur maximale est de 128 caractères.

Par exemple : "country_of_origin": "US"

content_index

Int (facultatif)

Indice 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 : "content_index": 0

filter_tags

Chaîne (facultatif, répété)

Filtrer les balises du document Vous ne pouvez pas dépasser 250 valeurs 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 RecommendRequest.filter.

Par exemple : "filter_tags": [ "filter_tag"]

hash_tags

Chaîne (facultatif, répété)

Hashtags du document. 100 valeurs maximum sont autorisées par document, avec une longueur limitée à 5 000 caractères.

Par exemple : "hash_tags": [ "soccer", "world cup"]

content_rating

Chaîne (facultatif, répété)

Classification du contenu, utilisée pour les systèmes d'avis sur le contenu et le filtrage du contenu en fonction de l'audience. Vous ne pouvez pas dépasser 100 valeurs par document, avec une limite de longueur de 128 caractères.

Cette balise peut être utilisée pour filtrer les résultats de recommandation en transmettant la balise dans le RecommendRequest.filter.

Par exemple : content_rating: ["PG-13"]

Le tableau suivant définit les propriétés de clé hiérarchiques.

Nom du champ Remarques
images

Objet (facultatif) – répété

Propriété de clé racine pour encapsuler les propriétés liées aux images.

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 clé racine pour encapsuler les propriétés liées à la personne.

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

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, financeur, producteur, fournisseur, éditeur, sponsor, traducteur, musique-par, chaîne, rôle personnalisé

Si aucune des valeurs compatibles n'est appliquée à role, définissez role sur custom-role et fournissez la valeur dans le champ custom_role.

persons.custom_role

Chaîne (facultatif)

custom_role est défini si et seulement si role est défini comme custom-role. Doit être une chaîne encodée en UTF-8 avec une longueur limitée à 128 caractères. Il doit correspondre au modèle : [a-zA-Z0-9][a-zA-Z0-9_]*.

persons.rank

Int (facultatif)

Utilisé pour le classement des rôles. Par exemple, pour le premier acteur, role = "actor", rank = 1

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 à organization.

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

organizations.name

Chaîne : obligatoire

Nom de l'organisation.

organizations.role

Chaîne : obligatoire

Rôle de l'organisation dans l'élément 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 compatibles n'est appliquée à role, définissez role sur custom-role et indiquez la valeur dans le champ custom_role.

organizations.custom_role

Chaîne (facultatif)

custom_role est défini si et seulement si role est défini comme custom-role. Doit être une chaîne encodée en UTF-8 avec une longueur limitée à 128 caractères. Il doit correspondre au modèle : [a-zA-Z0-9][a-zA-Z0-9_]*.

organizations.rank

Chaîne (facultatif)

Utilisé pour le classement des rôles. Par exemple, pour le premier éditeur : role = "publisher", rank = 1.

organizations.uri

Chaîne (facultatif)

URI de l'organisation.

aggregate_ratings

Objet (facultatif) – répété

Propriété de clé racine pour encapsuler les propriétés liées à aggregate_rating.

aggregate_ratings.rating_source

Chaîne : obligatoire

Source de la classification. Par exemple, imdb ou rotten_tomatoes. Doit être une chaîne encodée en UTF-8 d'une longueur maximale de 128 caractères. Il doit correspondre au modèle : [a-zA-Z0-9][a-zA-Z0-9_]*.

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. Doit être une valeur non négative.

Niveaux de document

Les niveaux de document déterminent la hiérarchie dans votre data store. En règle générale, vous devez disposer d'un data store à un ou deux niveaux. Seules deux couches sont acceptées.

Par exemple, vous pouvez avoir un data store à un seul niveau, où chaque document est un élément individuel. Vous pouvez également choisir un data store à deux niveaux contenant à la fois des groupes d'éléments et des éléments individuels.

Types au niveau du document

Il existe deux types au niveau du 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 d'émission TV", les enfants peuvent ê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

Lorsque vous planifiez la hiérarchie de votre data store, décidez s'il doit contenir uniquement des parents ou des parents et des enfants. N'oubliez pas que les recommandations et les recherches ne renvoient que des documents parents.

Par exemple, un data store réservé aux parents peut être adapté aux livres audio, où un panneau de recommandations renvoie une sélection de livres audio individuels. En revanche, si vous avez importé des épisodes de séries TV en tant que documents parents dans un entrepôt de données réservé aux parents, plusieurs épisodes hors séquence peuvent être recommandés dans le même panneau.

Un data store 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 au panneau de recommandations d'afficher une gamme d'émissions de télévision similaires. L'utilisateur final peut cliquer sur une émission spécifique pour sélectionner un épisode à regarder.

Étant donné que les hiérarchies parent-enfant peuvent être difficiles à configurer et à gérer, nous vous recommandons d'utiliser des magasins de données réservés aux parents.

Par exemple, un data store d'émissions télévisées peut fonctionner comme un data store réservé aux parents, où chaque document parent représente une émission télévisée pouvant être recommandée, et que les épisodes individuels ne sont pas inclus (et donc pas recommandés).

Si vous déterminez que votre data store doit comporter à la fois des parents et des enfants, c'est-à-dire des groupes et des éléments uniques, mais que vous ne disposez que d'éléments uniques pour le moment, vous devez créer des parents pour les groupes. Les informations minimales que vous devez fournir pour un parent sont id, title et categories. Pour en savoir plus, consultez la section Champs de 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 de 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": []
  }
]