Fournir ou détecter automatiquement un schéma

Lorsque vous importez des données structurées à l'aide de la console Google Cloud, Vertex AI Agent Builder détecte automatiquement le schéma. Vous pouvez utiliser ce schéma détecté automatiquement dans votre moteur ou utiliser l'API pour fournir un schéma indiquant la structure des données.

Si vous fournissez un schéma et que vous le mettez à jour par la suite avec un nouveau schéma, ce dernier doit être rétrocompatible avec l'original. Sinon, la mise à jour du schéma échoue.

Pour plus d'informations sur le schéma, consultez dataStores.schemas.

Méthodes permettant de fournir le schéma de votre data store

Il existe différentes approches pour déterminer le schéma des données structurées.

  • Détection et modification automatiques. Laissez Vertex AI Agent Builder détecter automatiquement et suggérer un schéma initial. Vous affinez ensuite le schéma via l'interface de la console. Google vous recommande vivement de mapper les propriétés clés à tous les champs importants une fois vos champs détectés automatiquement.

    C'est l'approche que vous suivrez lorsque vous suivrez les instructions de la console Google Cloud pour les données structurées dans Créer un data store de recherche et Créer un data store de recommandations génériques.

  • Fournissez le schéma en tant qu'objet JSON. Fournissez le schéma à Vertex AI Agent Builder en tant qu'objet JSON. Vous devez avoir préparé un objet JSON correct. Pour obtenir un exemple d'objet JSON, consultez Exemple de schéma en tant qu'objet JSON. Après avoir créé le schéma, importez vos données en fonction de celui-ci.

    C'est l'approche que vous pouvez utiliser lorsque vous créez un data store via l'API à l'aide d'une commande (ou d'un programme) curl. Consultez Importer une fois depuis BigQuery pour en savoir plus. Consultez également les instructions suivantes : Fournir votre propre schéma.

  • Multimédia: fournissez vos données dans le schéma défini par Google. Si vous créez un datastore pour les contenus multimédias, vous pouvez choisir d'utiliser le schéma prédéfini de Google. Si vous choisissez cette option, vous devez avoir structuré votre objet JSON au format indiqué dans la section À propos des documents multimédias et du magasin de données. Par défaut, la détection automatique ajoute au schéma tous les nouveaux champs qu'elle trouve lors de l'ingestion des données.

    C'est l'approche que vous suivez lorsque vous suivez les instructions de la section Créer une application multimédia et un datastore. C'est également l'approche adoptée dans les tutoriels Premiers pas avec les recommandations de contenus multimédias et Premiers pas avec la recherche de contenus multimédias, où les exemples de données sont fournis dans le schéma prédéfini de Google.

  • Éléments multimédias: détection et modification automatiques, en veillant à inclure les propriétés multimédias requises. Pour les données multimédias, vous pouvez utiliser la détection automatique pour suggérer le schéma et le modifier pour l'affiner. Dans votre objet JSON, vous devez inclure des champs pouvant être mappés aux propriétés de clé multimédia: title, uri, category, media_duration et media_available_time.

    C'est l'approche que vous utiliserez lorsque vous importerez des données multimédias via la console Google Cloud si elles ne figurent pas dans le schéma défini par Google.

  • Média: fournissez votre propre schéma en tant qu'objet JSON. Fournissez le schéma à Vertex AI Agent Builder en tant qu'objet JSON. Vous devez avoir préparé un objet JSON correct. Le schéma doit inclure des champs pouvant être mappés aux propriétés de clé multimédia: title, uri, category, media_duration et media_available_time.

    Pour obtenir un exemple d'objet JSON, consultez Exemple de schéma en tant qu'objet JSON. Après avoir créé le schéma, importez vos données multimédias en fonction de ce schéma.

    Pour cette approche, vous utilisez l'API via une commande (ou un programme) curl. Consultez les instructions suivantes : Fournir votre propre schéma.

À propos de la détection et de la modification automatiques

Lorsque vous commencez à importer des données, Vertex AI Search échantillonne les premiers documents importés. Sur la base de ces documents, il propose un schéma pour les données, que vous pouvez ensuite consulter ou modifier.

Si les champs que vous souhaitez mapper à des propriétés clés ne sont pas présents dans les documents échantillonnés, vous pouvez les ajouter manuellement lorsque vous examinez le schéma.

Si Vertex AI Search rencontre des champs supplémentaires plus tard lors de l'importation des données, il les importe toujours et les ajoute au schéma. Si vous souhaitez modifier le schéma une fois toutes les données importées, consultez Mettre à jour votre schéma.

Exemple de schéma en tant qu'objet JSON

Vous pouvez définir votre propre schéma à l'aide du format JSON Schema, qui est un langage déclaratif Open Source permettant de définir, d'annoter et de valider des documents JSON. Voici un exemple d'annotation de schéma JSON valide:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "dynamic": "true",
  "datetime_detection": true,
  "geolocation_detection": true,
  "properties": {
    "title": {
      "type": "string",
      "keyPropertyMapping": "title",
      "retrievable": true,
      "completable": true
    },
    "description": {
      "type": "string",
      "keyPropertyMapping": "description"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "keyPropertyMapping": "category"
      }
    },
    "uri": {
      "type": "string",
      "keyPropertyMapping": "uri"
    },
    "brand": {
      "type": "string",
      "indexable": true,
      "dynamicFacetable": true
    },
    "location": {
      "type": "geolocation",
      "indexable": true,
      "retrievable": true
    },
    "creationDate": {
      "type": "datetime",
      "indexable": true,
      "retrievable": true
    },
    "isCurrent": {
      "type": "boolean",
      "indexable": true,
      "retrievable": true
    },
    "runtime": {
      "type": "string",
      "keyPropertyMapping": "media_duration"
    },
    "releaseDate": {
      "type": "string",
      "keyPropertyMapping": "media_available_time"
    }
  }
}

Si vous définissez un schéma multimédia, vous devez inclure des champs pouvant être mappés aux propriétés de clé multimédia. Ces propriétés clés sont illustrées dans cet exemple.

Voici quelques-uns des champs de cet exemple de schéma:

  • dynamic. Si dynamic est défini sur la valeur de chaîne "true", toutes les nouvelles propriétés trouvées dans les données importées sont ajoutées au schéma. Si dynamic est défini sur "false", les nouvelles propriétés détectées dans les données importées sont ignorées. Les propriétés ne sont pas ajoutées au schéma, et les valeurs ne sont pas importées.

    Par exemple, un schéma comporte deux propriétés: title et description, et vous importez des données contenant des propriétés pour title, description et rating. Si dynamic est défini sur "true", la propriété et les données de classification sont importées. Si dynamic est défini sur "false", les propriétés rating ne sont pas importées, contrairement à title et description.

    La valeur par défaut est "true".

  • datetime_detection. Si datetime_detection est défini sur la valeur booléenne true, lorsque des données au format date/heure sont importées, le type de schéma est défini sur datetime. Les formats acceptés sont RFC 3339 et ISO 8601.

    Exemple :

    • 2024-08-05 08:30:00 UTC

    • 2024-08-05T08:30:00Z

    • 2024-08-05T01:30:00-07:00

    • 2024-08-05

    • 2024-08-05T08:30:00+00:00

    Si datatime_detection est défini sur la valeur booléenne false, lorsque des données au format date/heure sont importées, le type de schéma est défini sur string.

    La valeur par défaut est true.

  • geolocation_detection. Si geolocation_detection est défini sur le booléen true, lorsque des données au format géolocalisation sont importées, le type de schéma est défini sur geolocation. Les données sont détectées comme géolocalisation s'il s'agit d'un objet contenant un nombre de latitude et un nombre de longitude, ou d'un objet contenant une chaîne d'adresse.

    Exemple :

    • "myLocation": {"latitude":37.42, "longitude":-122.08}

    • "myLocation": {"address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043"}

    Si geolocation_detection est défini sur la valeur booléenne false, lorsque des données au format géolocalisation sont importées, le type de schéma est défini sur object.

    La valeur par défaut est true.

  • keyPropertyMapping : champ qui met en correspondance des mots clés prédéfinis avec des champs critiques de vos documents, ce qui permet de clarifier leur signification sémantique. Les valeurs incluent title, description, uri et category. Notez que le nom de votre champ n'a pas besoin de correspondre à la valeur keyPropertyValues. Par exemple, pour un champ que vous avez nommé my_title, vous pouvez inclure un champ keyPropertyValues avec une valeur de title.

    Pour les data stores de recherche, les champs marqués avec keyPropertyMapping sont par défaut indexables et exploitables, mais pas récupérables, completables ni dynamiques. Cela signifie que vous n'avez pas besoin d'inclure les champs indexable ou searchable avec un champ keyPropertyValues pour obtenir le comportement par défaut attendu.

  • type : type du champ. Il s'agit d'une valeur de chaîne qui est datetime, geolocation ou l'un des types primitifs (integer, boolean, object, array, number ou string).

Les champs de propriété suivants ne s'appliquent qu'aux applications de recherche:

  • retrievable : indique si ce champ peut être renvoyé dans une réponse de recherche. Cette valeur peut être définie pour les champs de type number, string, boolean, integer, datetime et geolocation. Vous pouvez définir jusqu'à 50 champs comme récupérables. Les champs définis par l'utilisateur et les champs keyPropertyValues ne sont pas récupérables par défaut. Pour rendre un champ récupérable, incluez "retrievable": true avec le champ.

  • indexable : indique si ce champ peut être filtré, facetté, optimisé ou trié dans la méthode servingConfigs.search. Cette valeur peut être définie pour les champs de type number, string, boolean, integer, datetime et geolocation. Vous pouvez définir jusqu'à 50 champs comme indexables. Les champs définis par l'utilisateur ne sont pas indexables par défaut, sauf ceux contenant le champ keyPropertyMapping. Pour rendre un champ indexable, incluez "indexable": true avec le champ.

  • dynamicFacetable : indique que le champ peut être utilisé en tant qu'attribut dynamique. Cette valeur peut être définie pour les champs de type number, string, boolean et integer. Pour qu'un champ soit filtrable dynamiquement, il doit également être indexable : incluez "dynamicFacetable": true et "indexable": true avec le champ.

  • searchable : indique si ce champ peut être indexé en mode inverse pour correspondre aux requêtes de texte non structuré. Cette valeur ne peut être définie que pour les champs de type string. Vous pouvez définir jusqu'à 50 champs comme pouvant être recherchés. Les champs définis par l'utilisateur ne sont pas indexés par défaut, sauf ceux contenant le champ keyPropertyMapping. Pour rendre un champ accessible par recherche, incluez "searchable": true avec le champ.

  • completable : indique si ce champ peut être renvoyé en tant que suggestion de saisie semi-automatique. Cette valeur ne peut être définie que pour les champs de type string. Pour rendre un champ remplissable, incluez "completable": true avec le champ.

De plus, le champ suivant ne s'applique qu'aux applications de recommandations:

  • recommendationsFilterable : indique que le champ peut être utilisé dans une expression de filtre de recommandations. Pour obtenir des informations générales sur les recommandations de filtrage, consultez la section Filtrer les recommandations.

      ...
    "genres": {
    "type": "string",
    "recommendationsFilterable": true,
    ...
  },

Fournir votre propre schéma en tant qu'objet JSON

Pour fournir votre propre schéma, vous devez créer un data store contenant un schéma vide, puis le mettre à jour en le fournissant en tant qu'objet JSON. Procédez comme suit :

  1. Préparez le schéma en tant qu'objet JSON, en vous appuyant sur l'exemple de schéma en tant qu'objet JSON.

  2. Créez un data store.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores?dataStoreId=DATA_STORE_ID" \
-d '{
  "displayName": "DATA_STORE_DISPLAY_NAME",
  "industryVertical": "INDUSTRY_VERTICAL"
}'

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet Google Cloud
    • DATA_STORE_ID: ID du data store Vertex AI Search que vous souhaitez créer. Cet identifiant ne peut contenir que des lettres minuscules, des chiffres, des traits de soulignement et des traits d'union.
    • DATA_STORE_DISPLAY_NAME: nom à afficher du data store Vertex AI Search que vous souhaitez créer.
    • INDUSTRY_VERTICAL : GENERIC ou MEDIA

  3. Utilisez la méthode d'API schemas.patch pour fournir votre nouveau schéma JSON en tant qu'objet JSON.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/schemas/default_schema" \
-d '{
  "structSchema": JSON_SCHEMA_OBJECT
}'

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet Google Cloud
    • DATA_STORE_ID: ID du data store Vertex AI Search.

    • JSON_SCHEMA_OBJECT: votre nouveau schéma JSON en tant qu'objet JSON. Exemple :

      {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "keyPropertyMapping": "title"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "keyPropertyMapping": "category"
      }
    },
    "uri": {
      "type": "string",
      "keyPropertyMapping": "uri"
    }
  }
}

  4. Facultatif: Examinez le schéma en suivant la procédure Afficher la définition d'un schéma.

Étape suivante