Schema aktualisieren

Sie können das Schema für alle Daten aktualisieren, die ein Schema unterstützen, z. B. strukturierte Daten, Websitedaten mit strukturierten Daten oder andere unstrukturierte Daten mit Metadaten.

Sie können das Schema in der Google Cloud Console aktualisieren oder mithilfe der schemas.patch. Das Aktualisieren des Schemas für eine Website wird nur über die REST API unterstützt.

Um das Schema zu aktualisieren, können Sie neue Felder hinzufügen, „Indexierbar“, „Suchbar“ und abgerufen werden können oder ein Feld als Schlüsselattribut zu markieren, z. B. title, uri und description.

Schema aktualisieren

Sie können Ihr Schema in der Google Cloud Console oder über die API aktualisieren.

Console

So aktualisieren Sie ein Schema in der Google Cloud Console:

  1. Im Abschnitt Anforderungen und Einschränkungen können Sie prüfen, ob Ihre Schemaaktualisierung gültig ist.

  2. Wenn Sie Feldanmerkungen aktualisieren (Felder als indexierbar, abrufbar, dynamische Facetable, suchbar oder ausfüllbar festlegen), finden Sie unter Feldeinstellungen konfigurieren Informationen zu den Einschränkungen und Anforderungen der einzelnen Anmerkungstypen.

  3. Prüfen Sie, ob Sie die Datenaufnahme abgeschlossen haben. Andernfalls ist das Schema möglicherweise noch nicht zur Bearbeitung verfügbar.

  4. Rufen Sie in der Google Cloud Console die Seite Agent Builder auf.

    Zum Agent Builder

  5. Klicken Sie im Navigationsmenü auf Datenspeicher.

  6. Klicken Sie in der Spalte Name auf den Datenspeicher mit dem Schema, das Sie aktualisieren möchten.

  7. Klicken Sie auf den Tab Schema, um das Schema für Ihre Daten anzuzeigen.

    Dieser Tab ist möglicherweise leer, wenn Sie die Felder zum ersten Mal bearbeiten.

  8. Klicken Sie auf Bearbeiten.

  9. Aktualisieren Sie Ihr Schema:

    • Schlüsselattribute zuordnen: Wählen Sie in der Spalte Schlüsselattribute Ihres Schemas ein Schlüsselattribut aus, dem ein Feld zugeordnet werden soll. Wenn z. B. ein Feld namens details enthält immer die Beschreibung eines Dokuments, ordnen dieses Feld zu in die Schlüsseleigenschaft Description ein.

    • Anzahl der Dimensionen aktualisieren (erweitert): Sie können diese Einstellung aktualisieren, wenn Sie benutzerdefinierte Vektoreinbettungen mit der Vertex AI-Suche verwenden. Weitere Informationen finden Sie unter Erweitert: Benutzerdefinierte Einbettungen verwenden

    • Feldhinweise aktualisieren: Wenn Sie die Anmerkungen für ein Feld aktualisieren möchten, aktivieren oder deaktivieren Sie die Anmerkungseinstellung des Felds. Verfügbare Anmerkungen sind Abrufbar, Indexierbar, Als dynamisches Attribut verwendbar, Suchbar und Ausfüllbar. Für einige Feldeinstellungen gelten Einschränkungen. Weitere Informationen finden Sie unter Feldeinstellungen für Beschreibungen konfigurieren und die Anforderungen für die einzelnen Anmerkungstypen.

    • Neues Feld hinzufügen:Dem Schema werden vor dem Import neue Felder hinzugefügt. Dokumente mit diesen Feldern die benötigte Zeit Vertex AI Agent Builder, um Ihre Daten nach dem Import neu zu indexieren.

      1. Klicken Sie auf Neue Felder hinzufügen, um den Bereich zu maximieren.

      2. Klicken Sie auf add_box Add node und Einstellungen für das neue Feld festlegen.

        Wenn es sich um ein Array handelt, setzen Sie Array auf Ja. Um beispielsweise ein String-Array, setzen Sie type auf string und Array auf Yes.

        Bei einem Website-Datenspeicherindex sind alle Felder, die Sie hinzufügen, Arrays Standardeinstellung.

  10. Klicken Sie auf Speichern, um die Schemaänderungen zu übernehmen.

    Das Ändern des Schemas löst eine Neuindexierung aus. Bei großen Datenspeichern kann dies Stunden dauern.

REST

So aktualisieren Sie Ihr Schema mit der API:

  1. Lesen Sie sich die Anforderungen und Einschränkungen sowie die Einschränkung Beispiele (nur REST), um zu prüfen, ob sich Ihr Schema ändert. sind gültig.

    Um das Schema für Datenspeicher mit Websites oder unstrukturierten Daten mit Fahren Sie mit Schritt 5 fort, um die Methode schema.patch aufzurufen.

  2. Wenn Sie Feldanmerkungen aktualisieren (Felder als indexierbar, abrufbar, dynamische Facetable oder suchbar festlegen), finden Sie unter Feldeinstellungen konfigurieren Informationen zu den Einschränkungen und Anforderungen der einzelnen Anmerkungstypen.

  3. Wenn Sie ein automatisch erkanntes Schema bearbeiten, benötigen Sie abgeschlossene Datenaufnahme abgeschlossen. Andernfalls ist das Schema möglicherweise nicht für bearbeitet haben.

  4. Suchen Sie Ihre Datenspeicher-ID. Wenn Sie bereits einen Datenspeicher haben ID verwenden, fahren Sie mit dem nächsten Schritt fort.

    1. Rufen Sie in der Google Cloud Console die Seite Agent Builder auf und klicken Sie im Navigationsmenü auf Datenspeicher.

      Zur Seite „Datenspeicher“

    2. Klicken Sie auf den Namen des Datenspeichers.

    3. Rufen Sie auf der Datenseite Ihres Datenspeichers die Datenspeicher-ID ab.

  5. Verwenden Sie die API-Methode schemas.patch, um Ihr neues JSON-Schema als JSON-Objekt anzugeben.

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

    Ersetzen Sie Folgendes:

    • PROJECT_ID ist die ID Ihres Google Cloud-Projekts.
    • DATA_STORE_ID: die ID des Vertex AI Search-Datenspeichers.
    • JSON_SCHEMA_OBJECT: Ihr neues JSON-Schema als JSON-Objekt. Beispiel:

      {
        "$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"
          }
        }
      }
  6. Optional: Überprüfen Sie das Schema, indem Sie der Anleitung unter Schemadefinition ansehen folgen.

C#

Weitere Informationen finden Sie in der Referenzdokumentation zur Vertex AI Agent Builder C# API.

Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei Vertex AI Agent Builder zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

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

Weitere Informationen finden Sie in der Referenzdokumentation zur Vertex AI Agent Builder Go API.

Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei Vertex AI Agent Builder zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.


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

Weitere Informationen finden Sie in der Referenzdokumentation zur Vertex AI Agent Builder Java API.

Richten Sie zur Authentifizierung bei Vertex AI Agent Builder Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

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

Weitere Informationen finden Sie in der Vertex AI Agent Builder Python API Referenzdokumentation.

Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei Vertex AI Agent Builder zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

# 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

Weitere Informationen finden Sie in der Vertex AI Agent Builder Ruby API Referenzdokumentation.

Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei Vertex AI Agent Builder zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

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

Anforderungen und Einschränkungen

Achten Sie beim Aktualisieren eines Schemas darauf, dass das neue Schema rückwärtskompatibel mit dem Schema ist, das Sie aktualisieren. So aktualisieren Sie ein Schema: mit einem neuen Schema, das nicht abwärtskompatibel ist, die Dokumente im Datenspeicher, löschen das Schema und erstellen ein neues Schema.

Das Aktualisieren eines Schemas löst eine Neuindexierung aller Dokumente aus. Das kann einige Zeit dauern und zusätzliche Kosten verursachen:

  • Zeit Die Neuindexierung eines großen Datenspeichers kann Stunden oder Tage dauern.

  • Ausgabe Je nach Parser können für die Neuindexierung Kosten anfallen. So fallen beispielsweise Kosten für die erneute Indexierung von Datenspeichern an, die den OCR-Parser oder den Layout-Parser verwenden. Weitere Informationen finden Sie unter Document AI-Funktion Preise.

Folgendes wird bei Schemaaktualisierungen nicht unterstützt:

  • Feldtyp ändern: Bei einer Schemaaktualisierung kann der Typ nicht geändert werden auf diesem Gebiet. Ein Feld, das auf eine Ganzzahl zugeordnet ist, kann beispielsweise nicht in einen String geändert werden.
  • Feld entfernen Einmal definiert, kann ein Feld nicht mehr entfernt werden. Sie können weiterhin neue Felder hinzufügen, aber keine vorhandenen Felder entfernen.

Beispiele für Einschränkungen (nur REST)

Dieser Abschnitt enthält Beispiele für gültige und ungültige Typen von Schemaaktualisierungen. In diesen Beispielen wird das folgende JSON-Schema verwendet:

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

Beispiele für unterstützte Updates

Die folgenden Änderungen am Beispielschema werden unterstützt.

  • Feld hinzufügen: In diesem Beispiel wurde das Feld properties.uri dem Schema hinzugefügt wurden.

    {
      "$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"
          }
        }
      }
    }
    
  • Hinweise zu wichtigen Properties für title, description oder uri hinzufügen oder entfernen In diesem Beispiel wurde dem Feld title keyPropertyMapping hinzugefügt.

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

Beispiele für ungültige Schemaaktualisierungen

Die folgenden Änderungen am Beispielschema werden nicht unterstützt.

  • Feldtyp ändern: In diesem Beispiel hat der Feldtyp title von Zeichenfolge in Zahl geändert. Dies wird nicht unterstützt.

      {
        "$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"
            }
          }
        }
      }
    
  • Feld entfernen In diesem Beispiel wurde das Feld title entfernt. Dies wird nicht unterstützt.

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

Nächste Schritte