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

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 en savoir plus sur le schéma, consultez dataStores.schemas

Approches permettant de fournir le schéma de votre data store

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

Détection et modification automatiques. Laissez Vertex AI Agent Builder détecter automatiquement et suggérer un schéma initial. Ensuite, vous affinez le schéma de la console Google Cloud. Google recommande vivement Une fois les champs détectés automatiquement, vous mappez les propriétés clés les champs importants.

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 la section Exemple de schéma en tant qu'objet JSON. Après avoir créé le schéma, importer vos données selon ce schéma.

C'est l'approche que vous pouvez utiliser lorsque vous créez un entrepôt de données via l'API à l'aide d'une commande (ou d'un programme) curl. Par exemple, reportez-vous à la section Importer une fois dans BigQuery. Consultez également les ressources suivantes : instructions, Fournir votre propre schéma.
Multimédia: fournissez vos données dans le schéma défini par Google. Si vous créez un ensemble de données de stockage de contenus multimédias, vous pouvez choisir d'utiliser le schéma prédéfini de Google. Sélection cette option suppose que vous avez structuré votre objet JSON au format présentées dans l'article À propos des documents multimédias et du data store. 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. Il s'agit également dans les tutoriels, Premiers pas avec les recommandations et Premiers pas avec les médias search, où les exemples de données sont fournis Schéma Google prédéfini.
Contenus multimédias: détection et modification automatiques, en veillant à inclure les éléments multimédias requis propriétés. 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 être mappées avec les propriétés de la clé multimédia: title, uri, category, media_duration et media_available_time.

Vous utiliserez cette méthode pour importer des données multimédias via Console Google Cloud si les données multimédias ne figurent pas dans le schéma défini par Google.
Multimédia: fournissez votre propre schéma en tant qu'objet JSON. Indiquez le paramètre vers 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 mappées aux propriétés de la clé multimédia: title, uri, category, media_duration et media_available_time.

Pour obtenir un exemple d'objet JSON, consultez la section 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 automatique et de la modification

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 le schéma JSON qui est un langage déclaratif Open Source permettant de définir, d'annoter et 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 de média, vous devez inclure des champs pouvant être mappées aux propriétés de la clé multimédia. Ces propriétés clés sont présentées dans à titre d'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 fichiers importés les données sont ignorées. les propriétés ne sont pas ajoutées au schéma de valeurs soient 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. bien que title et description le soient.

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éfinie sur datetime. Les formats acceptés sont les suivants : 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éfinie sur string.

La valeur par défaut est true.
geolocation_detection Si geolocation_detection est défini sur la valeur booléenne true, lorsque des données au format de géolocalisation sont importées, le type de schéma est définie sur geolocation. Les données sont détectées en tant que géolocalisation s'il s'agit d'un objet contenant un numéro de latitude et de longitude ou 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. 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 que vous avez nommé my_title, vous pouvez inclure un champ keyPropertyValues dont la valeur est 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.

Remarque :Les propriétés clés peuvent améliorer la qualité des résultats de recherche et résultats de recommandations et précision de la saisie semi-automatique lors des recherches. Si vous utilisez la détection automatique de schéma, les propriétés de clé ne sont pas ajoutées automatiquement. Nous vous recommandons vivement d'utiliser la méthode schemas.patch pour marquer les champs de données comme propriétés clés, en particulier title, uri et description.
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. Il peut être défini 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 Par défaut, les champs keyPropertyValues ne peuvent pas être récupérés. Pour créer un champ récupérable, incluez "retrievable": true dans le champ.
indexable Indique si ce champ peut être filtré, à attributs boostées ou triées dans le servingConfigs.search . Cette valeur peut être définie pour les champs de type number, string, boolean, integer, datetime et geolocation. 50 champs au maximum peuvent être définis 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. Il peut être défini pour les champs de type number, string, boolean et integer Pour qu'un champ puisse être ajouté de manière dynamique, il doit également être indexable: incluez "dynamicFacetable": true et "indexable": true dans 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 inclus dans l'index de recherche. Définies par l'utilisateur les champs ne sont pas inclus dans l'index de recherche par défaut, à l'exception de ceux contenant 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 un 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 magasin de données contenant un schéma vide, puis le mettre à jour en le fournissant en tant qu'objet JSON. Procédez comme suit :

Préparez le schéma en tant qu'objet JSON à l'aide de la méthode Consultez cet exemple de schéma en tant qu'objet JSON.
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 de Vertex AI Recherchez le data store que vous souhaitez créer.
- INDUSTRY_VERTICAL : GENERIC ou MEDIA

Utilisez la méthode schemas.patch. Méthode API permettant de 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"
    }
  }
}

Exemple de commande et de résultat

curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/dataStores/my-data-store/schemas/default_schema" -d '{
"structSchema": {
"$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"
}
}
}
}'

{
"name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/schemas/default_schema/operations/update-schema-10569824819404198922",
"metadata": {
"@type": "type.googleapis.com/google.cloud.discoveryengine.v1.UpdateSchemaMetadata"
}
}

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