Fournir ou détecter automatiquement un schéma

Lorsque vous importez des données structurées à l'aide de la Google Cloud console, Gemini Enterprise 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 ultérieurement avec un nouveau schéma, ce dernier doit être rétrocompatible avec le schéma d'origine. Sinon, la mise à jour du schéma échoue.

Important : Si vous ne fournissez pas de schéma, la fonctionnalité de détection automatique peut mettre à jour votre schéma en intégrant tous les nouveaux champs détectés lorsque vous importez de nouvelles données. Si des documents de vos données importées contiennent de nouveaux champs qui ne sont pas rétrocompatibles avec votre schéma d'origine, leur importation échoue.

Pour obtenir des informations de référence sur le schéma, consultez dataStores.schemas.

Termes clés : Dans le contexte du schéma, les termes champ et propriété sont utilisés de manière interchangeable.

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

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

• Détection et modification automatiques Laissez Gemini Enterprise détecter automatiquement et suggérer un schéma initial. Ensuite, affinez le schéma via l'interface de la console. Nous vous recommandons vivement de mapper les propriétés clés à tous les champs importants une fois que vos champs ont été détectés automatiquement.

  Il s'agit de l'approche que vous utiliserez en suivant les Google Cloud instructions de la console pour les données structurées dans Créer un données first party party.

• Fournir le schéma en tant qu'objet JSON Fournissez le schéma à Gemini Enterprise 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 ce schéma.

  Il s'agit de l'approche que vous pouvez utiliser lorsque vous créez un data store via l'API à l'aide d'une commande curl (ou d'un programme). Consultez par exemple Importer une seule fois depuis BigQuery. Consultez également 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, Gemini Enterprise échantillonne les premiers documents importés. En fonction de ces documents, il propose un schéma pour les données, que vous pouvez ensuite examiner 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.

Conseil : Assurez-vous que les documents au début de votre ensemble de données sont de bonne qualité et que tous les champs clés sont représentés. Ainsi, vous n'aurez pas à ajouter ni à modifier des champs ultérieurement.

Si Gemini Enterprise rencontre d'autres champs ultérieurement lors de l'importation des données, il les importe quand même 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 au 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
    }
  }
}

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 trouvé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. Vous importez des données contenant des propriétés pour title, description et rating. Si dynamic est "true", la propriété et les données de notation sont importées. Si dynamic est "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 et heure sont importées, le type de schéma est défini sur datetime. Les formats compatibles 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 et 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 la valeur booléenne true, lorsque des données au format de géolocalisation sont importées, le type de schéma est défini sur geolocation. Les données sont détectées comme des données de géolocalisation s'il s'agit d'un objet contenant un numéro de latitude et un numéro 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 de 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 mappe des mots clés prédéfinis à des champs essentiels 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 keyPropertyValues champ avec la valeur title.

  Les champs marqués avec keyPropertyMapping sont indexables et consultables par défaut, mais ils ne sont pas récupérables, complétables ni dynamiquement facettables. 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 la précision de la saisie semi-automatique. Si vous utilisez la détection automatique de schéma, les propriétés clés ne sont pas ajoutées automatiquement. Nous vous recommandons vivement d'utiliser la schemas.patch méthode 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).

• retrievable: indique si ce champ peut être renvoyé dans une réponse de recherche. Cette option 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é, boosté ou trié dans la méthode servingConfigs.search . Cette option 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, à l'exception des champs contenant le champ keyPropertyMapping. Pour rendre un champ indexable, incluez "indexable": true avec le champ.

• dynamicFacetable: indique que le champ peut être utilisé comme un attribut dynamique. Cette option peut être définie pour les champs de type number, string, boolean et integer. Pour rendre un champ dynamiquement facettable, il doit également être indexable: incluez "dynamicFacetable": true et "indexable": true avec le champ.

• searchable: indique si ce champ peut être indexé inversément pour correspondre aux requêtes de texte non structurées. Cette option ne peut être définie que pour les champs de type string. Vous pouvez définir jusqu'à 50 champs comme consultables. Les champs définis par l'utilisateur ne sont pas consultables par défaut, à l'exception des champs contenant le champ keyPropertyMapping. Pour rendre un champ consultable, incluez "searchable": true avec le champ.

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

Remarque : Pour les schémas détectés automatiquement, les nouveaux champs détectés sont automatiquement indexables, consultables et récupérables, à condition qu'ils respectent les exigences de type et qu'ils ne dépassent pas les limites maximales.

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

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

1. Préparez le schéma en tant qu'objet JSON, en vous basant 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.
   • DATA_STORE_ID : ID du data store que vous souhaitez créer. Cet ID ne peut contenir que des lettres minuscules, des chiffres, des traits de soulignement et des traits d'union.
   • DATA_STORE_DISPLAY_NAME : nom à afficher pour le data store que vous souhaitez créer.
   • INDUSTRY_VERTICAL: GENERIC

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.
   • DATA_STORE_ID : ID du data store.

   • 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 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"
     }
     }
     

4. Facultatif : examinez le schéma en suivant la procédure Afficher une définition de schéma.

Étape suivante

• Créer une application de recherche
• Obtenir la définition de schéma pour les données structurées
• Mettre à jour un schéma pour des données structurées