Remarque : Vertex AI Search est renommé Agent Search. Nous sommes en train de mettre à jour le contenu pour refléter le nouveau branding.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Mettre à jour un schéma

Vous pouvez mettre à jour le schéma de toutes les données qui en sont compatibles, comme les données structurées, les données de site Web avec des données structurées ou d'autres données non structurées avec des métadonnées.

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

Pour mettre à jour le schéma, vous pouvez ajouter des champs, modifier les annotations indexables, pouvant faire l'objet d'une recherche et récupérables pour un champ, ou marquer un champ comme propriété clé, comme title, uri et description.

Avant de commencer

Avant de mettre à jour votre schéma, comprenez les concepts clés expliqués dans cette section.

Importance des propriétés clés

Voici quelques raisons pour lesquelles vous devez mapper les champs de votre schéma à des propriétés clés :

Google vous recommande vivement de mettre à jour votre schéma avec des mappages de propriétés clés, en particulier pour title. Cela permet de s'assurer que vos résultats s'affichent correctement et aide la recherche d'agent à identifier les informations importantes qui lui permettent de générer de meilleurs résultats.
Dans les datastores de données structurées, pour obtenir le keywordSimilarityScore signal dans votre réponse de recherche, vous devez mettre à jour votre schéma comme suit :
- Mappez les champs de texte essentiels pour la correspondance des mots clés aux propriétés clés title et description.
- Mettez à jour l'annotation des champs de texte en tant que Searchable.

Conditions requises

Lorsque vous mettez à jour un schéma, assurez-vous que le nouveau schéma est rétrocompatible avec celui que vous mettez à jour. Pour mettre à jour un schéma avec un nouveau schéma qui n'est pas rétrocompatible, vous devez supprimer tous les documents du data store, supprimer le schéma, puis en créer un.

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 :

Temps : la réindexation d'un data store volumineux peut prendre plusieurs heures, voire plusieurs jours.
Coût : la réindexation peut entraîner des coûts, selon l'analyseur. Par exemple, la réindexation des datastores qui utilisent l'analyseur OCR ou l'analyseur de mise en page entraîne des coûts. Pour en savoir plus, consultez Tarifs des fonctionnalités de Document AI.
Impact sur le service : la réindexation peut entraîner des services lents ou indisponibles, en particulier pour les datastores volumineux. Google vous recommande de planifier les mises à jour de schéma en conséquence, en tenant compte des temps d'arrêt potentiels pour les applications critiques.

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

Modification du type de champ : une mise à jour de schéma n'est pas compatible avec la modification du type de champ. Par exemple, un champ mappé à integer ne peut pas être remplacé par string.
Suppression d'un champ : une fois défini, un champ ne peut pas être supprimé. Vous pouvez continuer à ajouter des champs, mais vous ne pouvez pas supprimer un champ existant.

Mettre à jour votre schéma

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

Console

Pour mettre à jour un schéma dans la Google Cloud console, 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 (définition de champs comme indexables, récupérables, pouvant faire l'objet d'une facette dynamique, pouvant faire l'objet d'une recherche ou pouvant être complétés), consultez Configurer les paramètres de champ 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 pour être modifié.
Dans la Google Cloud console, accédez à la page Applications d'IA.

AI Applications
Dans le menu de navigation, cliquez sur Datastores.
Dans la colonne Nom, cliquez sur le data store dont vous souhaitez mettre à jour le schéma.
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 des propriétés clés : dans la colonne Propriétés clés de votre schéma, sélectionnez une propriété 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é clé Description.
- Modifier le nombre de dimensions (avancé) : vous pouvez modifier ce paramètre si vous utilisez des embeddings vectoriels personnalisés avec la recherche d'agent. Consultez Avancé : Utiliser des embeddings personnalisés.
- Modifier les annotations de champ : pour modifier les annotations d'un champ, cochez ou décochez le paramètre d'annotation du champ. Les annotations disponibles sont Récupérable, Indexable, Pouvant faire l'objet d'une facette dynamique, Pouvant faire l'objet d'une recherche et Pouvant être complété. Certains paramètres de champ sont soumis à des limites. Consultez Configurer les paramètres de champ pour obtenir des descriptions et connaître les exigences de chaque type d'annotation.
- Ajouter un champ : l'ajout de champs à votre schéma avant d'importer de nouveaux documents avec ces champs peut réduire le temps nécessaire à la recherche d'agent 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 et spécifiez les paramètres du nouveau champ.
    
    Pour indiquer un tableau, définissez Tableau sur Oui. Par exemple, pour ajouter un tableau de chaînes, définissez type sur string et Tableau sur Yes.
    
    Pour un index de data store de site Web, tous les champs que vous ajoutez sont des tableaux par défaut.
Cliquez sur Enregistrer pour appliquer les modifications apportées à votre 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 utiliser l'API afin de mettre à jour votre schéma, procédez comme suit :

Consultez les sections Conditions requises et limites et Exemples de limites (REST uniquement) pour vérifier que les modifications apportées à votre schéma sont valides.

Pour mettre à jour le schéma des datastores avec des sites Web ou des données non structurées avec des métadonnées, passez à l'étape 5 pour appeler la méthode schema.patch.
Si vous mettez à jour des annotations de champ (définition de champs comme indexables, récupérables, pouvant faire l'objet d'une facette dynamique ou pouvant faire l'objet d'une recherche), consultez Configurer les paramètres de champ pour connaître 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 pour être modifié.
Recherchez l'ID de votre data store. Si vous disposez déjà de l'ID de votre data store, passez à l'étape suivante.
1. Dans la Google Cloud console, accédez à la page Applications d'IA et cliquez sur Datastores dans le menu de navigation.
  
  Accéder à la page "Datastores"
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 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 Google Cloud projet.
DATA_STORE_ID : ID du data store de recherche d'agent.

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

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

C#

Pour en savoir plus, consultez la documentation de référence sur l' API C# de la recherche d'agent.

Pour vous authentifier auprès de la recherche d'agent, 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 sur l'API de la recherche d'agent.Go


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 la documentation de référence sur l'API Agent Search Java.

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 la documentation de référence sur l' API Python de la recherche d'agent.

# 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 la documentation de référence sur l' API Ruby de la recherche d'agent.

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

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 compatibles.

Ajout d'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és clés pour title, description ou uri. dans cet exemple, keyPropertyMapping a été ajouté au champ 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 compatibles.

Modification du type de champ : dans cet exemple, le type du champ title est passé de chaîne à nombre. Cette opération n'est pas compatible.

  {
    "$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"
        }
      }
    }
  }

Suppression d'un champ : dans cet exemple, le champ title a été supprimé. Cette opération n'est pas compatible.

  {
    "$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"
        }
      }
    }
  }