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

Mettre à jour un schéma

Vous pouvez mettre à jour le schéma pour toutes les données contenant des données compatibles avec un schéma, telles que les données structurées, les données de site Web avec données structurées ou d'autres données non structurées avec métadonnées.

Vous pouvez mettre à jour le schéma dans la console Google Cloud ou à l'aide de la méthode d'API schemas.patch. La mise à jour du schéma d'un site Web n'est possible que via l'API REST.

Pour mettre à jour le schéma, vous pouvez ajouter de nouveaux champs, modifier l'indexable, l'index de recherche et des annotations récupérables pour un champ ou de marquer un champ comme propriété de clé, par exemple title, uri et description.

Mettre à jour votre schéma

Vous pouvez mettre à jour votre schéma dans la console Google Cloud ou à l'aide de l'API.

Console

Pour mettre à jour un schéma dans la console Google Cloud, procédez comme suit:

Consultez la section Conditions requises et limites pour vérifier que la mise à jour de votre schéma est valide.
Si vous mettez à jour des annotations de champ (en définissant des champs comme indexables, récupérables, en facetable dynamique, en recherche ou en remplissage), consultez Configurer les paramètres des champs pour connaître les limites et les exigences de chaque type d'annotation.
Vérifiez que vous avez terminé l'ingestion des données. Sinon, il est possible que le schéma ne soit pas encore disponible à la modification.
Dans la console Google Cloud, accédez à la page Agent Builder.

Agent Builder
Dans le menu de navigation, cliquez sur Data stores (Datastores).
Dans la colonne Nom, cliquez sur le magasin de données contenant le schéma que vous souhaitez mettre à jour.
Cliquez sur l'onglet Schéma pour afficher le schéma de vos données.

Cet onglet peut être vide si vous modifiez les champs pour la première fois.
Cliquez sur le bouton Modifier.
Mettez à jour votre schéma:
- Mapper les propriétés de la clé:dans la colonne Propriétés de la clé de votre schéma, sélectionnez une propriété de clé à laquelle mapper un champ. Par exemple, si un champ appelé details contient toujours la description d'un document. Mappez ce champ. à la propriété de clé Description.
- Mettre à jour le nombre de dimensions (option avancée): vous pouvez modifier ce paramètre. si vous utilisez des représentations vectorielles continues personnalisées avec Vertex AI Search. Consultez la section Avancé : utiliser des représentations vectorielles continues personnalisées.
- Mettre à jour les annotations de champ : pour mettre à jour les annotations d'un champ, sélectionnez ou désélectionnez le paramètre d'annotation du champ. Les annotations disponibles sont Récupérable, Indexable, Ajout d'attributs dynamique, Inclus dans l'index de recherche et Complète. Certains paramètres des champs sont limités. Consultez la section Configurer les paramètres des champs pour obtenir des descriptions et des exigences pour chaque type d'annotation.
- Ajouter un champ : ajouter des champs à votre schéma avant d'importer de nouveaux documents avec ces champs peut réduire le temps nécessaire à Vertex AI Agent Builder pour réindexer vos données après l'importation.
  1. Cliquez sur Ajouter des champs pour développer cette section.
  2. Cliquez sur add_box Ajouter un nœud, puis spécifiez les paramètres du nouveau champ.
    
    Pour indiquer un tableau, définissez Array (Tableau) sur Yes (Oui). Par exemple, pour ajouter un tableau de chaînes, définissez type sur string et Array sur Yes
    
    Pour un index de datastore de site Web, tous les champs que vous ajoutez sont des tableaux par défaut.
Cliquez sur Enregistrer pour appliquer les modifications apportées au schéma.

La modification du schéma déclenche la réindexation. Pour les datastores volumineux, la réindexation peut prendre plusieurs heures.

REST

Pour mettre à jour votre schéma à l'aide de l'API, procédez comme suit:

Consultez les Conditions requises et limites, ainsi que les Restrictions exemples (REST uniquement) pour vérifier que votre schéma modifie sont valides.

Pour mettre à jour le schéma des data stores contenant des sites Web ou des données non structurées avec passez à l'étape 5 pour appeler la méthode schema.patch.
Si vous mettez à jour des annotations de champ (en définissant les champs comme indexables, récupérables, avec ajout d'attributs dynamique ou inclus dans l'index de recherche), vérifiez Configurez les paramètres de champ pour la les limites et les exigences de chaque type d'annotation.
Si vous modifiez un schéma détecté automatiquement, assurez-vous d'avoir terminé l'ingestion des données. Sinon, il est possible que le schéma ne soit pas encore disponible à la modification.
Recherchez votre ID de data store. Si vous disposez déjà de votre data store ID, passez à l'étape suivante.
1. Dans la console Google Cloud, accédez à la page Agent Builder. Dans le menu de navigation, cliquez sur Data stores (Magasins de données).
  
  Accéder à la page "Data stores"
2. Cliquez sur le nom de votre data store.
3. Sur la page Données de votre data store, obtenez l'ID du data store.

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 sous forme de 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 une définition de schéma.

C#

Pour en savoir plus, consultez les API C# de Vertex AI Agent Builder documentation de référence.

Pour vous authentifier auprès de Vertex AI Agent Builder, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

using Google.Cloud.DiscoveryEngine.V1;
using Google.LongRunning;

public sealed partial class GeneratedSchemaServiceClientSnippets
{
    /// <summary>Snippet for UpdateSchema</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void UpdateSchemaRequestObject()
    {
        // Create client
        SchemaServiceClient schemaServiceClient = SchemaServiceClient.Create();
        // Initialize request argument(s)
        UpdateSchemaRequest request = new UpdateSchemaRequest
        {
            Schema = new Schema(),
            AllowMissing = false,
        };
        // Make the request
        Operation<Schema, UpdateSchemaMetadata> response = schemaServiceClient.UpdateSchema(request);

        // Poll until the returned long-running operation is complete
        Operation<Schema, UpdateSchemaMetadata> completedResponse = response.PollUntilCompleted();
        // Retrieve the operation result
        Schema result = completedResponse.Result;

        // Or get the name of the operation
        string operationName = response.Name;
        // This name can be stored, then the long-running operation retrieved later by name
        Operation<Schema, UpdateSchemaMetadata> retrievedResponse = schemaServiceClient.PollOnceUpdateSchema(operationName);
        // Check if the retrieved long-running operation has completed
        if (retrievedResponse.IsCompleted)
        {
            // If it has completed, then access the result
            Schema retrievedResult = retrievedResponse.Result;
        }
    }
}

Go

Pour en savoir plus, consultez la documentation de référence de l'API Go Vertex AI Agent Builder.

Pour vous authentifier auprès de Vertex AI Agent Builder, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.


package main

import (
	"context"

	discoveryengine "cloud.google.com/go/discoveryengine/apiv1"
	discoveryenginepb "cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := discoveryengine.NewSchemaClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &discoveryenginepb.UpdateSchemaRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb#UpdateSchemaRequest.
	}
	op, err := c.UpdateSchema(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}

	resp, err := op.Wait(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

Pour en savoir plus, consultez les API Java de Vertex AI Agent Builder documentation de référence.

import com.google.cloud.discoveryengine.v1.Schema;
import com.google.cloud.discoveryengine.v1.SchemaServiceClient;
import com.google.cloud.discoveryengine.v1.UpdateSchemaRequest;

public class SyncUpdateSchema {

  public static void main(String[] args) throws Exception {
    syncUpdateSchema();
  }

  public static void syncUpdateSchema() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (SchemaServiceClient schemaServiceClient = SchemaServiceClient.create()) {
      UpdateSchemaRequest request =
          UpdateSchemaRequest.newBuilder()
              .setSchema(Schema.newBuilder().build())
              .setAllowMissing(true)
              .build();
      Schema response = schemaServiceClient.updateSchemaAsync(request).get();
    }
  }
}

Python

Pour en savoir plus, consultez les API Python de Vertex AI Agent Builder documentation de référence.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import discoveryengine_v1


def sample_update_schema():
    # Create a client
    client = discoveryengine_v1.SchemaServiceClient()

    # Initialize request argument(s)
    request = discoveryengine_v1.UpdateSchemaRequest(
    )

    # Make the request
    operation = client.update_schema(request=request)

    print("Waiting for operation to complete...")

    response = operation.result()

    # Handle the response
    print(response)

Ruby

Pour en savoir plus, consultez les API Ruby de Vertex AI Agent Builder documentation de référence.

require "google/cloud/discovery_engine/v1"

##
# Snippet for the update_schema call in the SchemaService service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DiscoveryEngine::V1::SchemaService::Client#update_schema.
#
def update_schema
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DiscoveryEngine::V1::SchemaService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DiscoveryEngine::V1::UpdateSchemaRequest.new

  # Call the update_schema method.
  result = client.update_schema request

  # The returned object is of type Gapic::Operation. You can use it to
  # check the status of an operation, cancel it, or wait for results.
  # Here is how to wait for a response.
  result.wait_until_done! timeout: 60
  if result.response?
    p result.response
  else
    puts "No response received."
  end
end

Conditions requises et limites

Lorsque vous mettez à jour un schéma, assurez-vous qu'il est rétrocompatible avec le schéma que vous mettez à jour. Pour mettre à jour un schéma avec un nouveau schéma non rétrocompatible, vous devez supprimer tout les documents du data store, supprimer le schéma et en créer un autre.

La mise à jour d'un schéma déclenche la réindexation de tous les documents. Cela peut prendre du temps et entraîner des coûts supplémentaires :

l'heure. La réindexation d'un data store volumineux peut prendre plusieurs heures, voire plusieurs jours.
Dépense. La réindexation peut entraîner des coûts, selon l'analyseur. Par exemple, le réindexage des entrepôts de données qui utilisent l'analyseur OCR ou l'analyseur de mise en page entraîne des coûts. Pour en savoir plus, consultez la page Tarifs des fonctionnalités Document AI.

Les mises à jour de schéma ne sont pas compatibles avec les éléments suivants :

Modifier un type de champ. Une mise à jour de schéma ne permet pas de modifier le type du domaine. Par exemple, vous ne pouvez pas remplacer un champ mappé sur un entier par une chaîne.
Supprimer un champ : Une fois défini, un champ ne peut plus être supprimé. Vous pouvez continuer à ajouter de nouveaux champs, mais vous ne pouvez pas supprimer un champ existant.

Exemples de limites (REST uniquement)

Cette section présente des exemples de types de mises à jour de schéma valides et non valides. Ces exemples utilisent l'exemple de schéma JSON suivant:

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

Exemples de mises à jour compatibles

Les mises à jour suivantes de l'exemple de schéma sont acceptées.

Ajoutez un champ. Dans cet exemple, le champ properties.uri a été ajouté au schéma.

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

Ajout ou suppression d'annotations de propriété clé pour title, description ou uri. Dans cet exemple, keyPropertyMapping a été ajouté au title.

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

Exemples de mises à jour de schéma non valides

Les mises à jour suivantes de l'exemple de schéma ne sont pas acceptées.

Modifier un type de champ. Dans cet exemple, le type du champ title est passé de chaîne à nombre. Cela n'est pas pris en charge.

  {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "title": {
        "type": "number" // Changed from string. Not allowed.
      },
      "description": {
        "type": "string",
        "keyPropertyMapping": "description"
      },
      "categories": {
        "type": "array",
        "items": {
          "type": "string",
          "keyPropertyMapping": "category"
        }
      }
    }
  }

Supprimer un champ Dans cet exemple, le champ title a été supprimé. Cela n'est pas pris en charge.

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