Cette page a été traduite par l'API Cloud Translation.

À propos des documents multimédias et des data stores

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 `>` pour : des hiérarchies distinctes. Si `>` fait partie du nom de la catégorie, remplacez-le par un ou plusieurs autres caractères. Exemple : `"categories": [ "sports > highlight" ]` 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: `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 des valeurs l'importance. 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 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, `"language_code": "en-US"`.
`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 `google::protobuf::Duration`. Par exemple : "5 s", "1 min"
`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 : `"2022-08-26T23:00:17Z"`
`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 : `"2032-12-31T23:00:17Z"`
`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 : `"in_languages": [ "en-US"]`
`country_of_origin`	Chaîne (facultatif) Pays d'origine du document multimédia. Il ne doit pas dépasser 128 caractères. Par exemple : `"country_of_origin": "US"`
`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 : `"content_index": 0`
`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 `RecommendRequest.filter`. Par exemple : `"filter_tags": [ "filter_tag"]`
`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 : `"hash_tags": [ "soccer", "world cup"]`
`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 `RecommendRequest.filter`. Par exemple : `content_rating: ["PG-13"]`

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":"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, bailleurs de fonds, 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 sur `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 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 à `role`, définissez `role` à `custom-role` et indiquez la valeur dans le `custom_role`.
`organizations.custom_role`	Chaîne (facultatif) `custom_role` est défini si et seulement si `role` est défini sur `custom-role`. Doit être une chaîne encodée au format UTF-8 avec ne doit pas dépasser 128 caractères. Doit correspondre au format: `[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 la clé racine permettant d'encapsuler le `aggregate_rating` propriétés associées.
`aggregate_ratings.rating_source`	Chaîne (obligatoire) Source de la note. 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. 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": []
  }
]