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 oder mit der API-Methode schemas.patch aktualisieren. Das Schema für eine Website kann nur über die REST API aktualisiert werden.

Sie können neue Felder hinzufügen, Anmerkungen zu indexierbaren, suchbaren und abrufbaren Feldern ändern oder ein Feld als Schlüsselattribut kennzeichnen, z. B. title, uri und description, um das Schema zu aktualisieren.

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 die Datenaufnahme abgeschlossen ist. 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 aufzurufen.

    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 ein Feld namens details beispielsweise immer die Beschreibung eines Dokuments enthält, ordnen Sie dieses Feld der Schlüsseleigenschaft Beschreibung zu.

    • 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 für das Feld. Verfügbare Anmerkungen sind Abrufbar, Indexierbar, Als dynamisches Attribut verwendbar, Suchbar und Ausfüllbar. Für einige Feldeinstellungen gelten Einschränkungen. Beschreibungen und Anforderungen für die einzelnen Annotationstypen finden Sie unter Feldeinstellungen konfigurieren.

    • Neues Feld hinzufügen:Wenn Sie Ihrem Schema neue Felder hinzufügen, bevor Sie neue Dokumente mit diesen Feldern importieren, kann die Zeit verkürzt werden, die Vertex AI Agent Builder benötigt, 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 Knoten hinzufügen und geben Sie die Einstellungen für das neue Feld an.

        Wenn es sich um ein Array handelt, setzen Sie Array auf Ja. Wenn Sie beispielsweise ein String-Array hinzufügen möchten, legen Sie für type den Wert string und für Array den Wert Yes fest.

        Bei einem Index für einen Websitedatenspeicher sind alle hinzugefügten Felder standardmäßig Arrays.

  10. Klicken Sie auf Speichern, um die Schemaänderungen anzuwenden.

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

REST

So aktualisieren Sie Ihr Schema mithilfe der API:

  1. Sehen Sie sich die Abschnitte Anforderungen und Einschränkungen und Beispiele für Einschränkungen (nur REST) an, um zu prüfen, ob Ihre Schemaänderungen gültig sind.

    Wenn Sie das Schema für Datenspeicher mit Websites oder unstrukturierten Daten mit Metadaten aktualisieren möchten, 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, müssen Sie die Datenaufnahme abgeschlossen haben. Andernfalls ist das Schema möglicherweise noch nicht zur Bearbeitung verfügbar.

  4. Suchen Sie die Datenspeicher-ID. Wenn Sie die Datenspeicher-ID bereits haben, 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: Sehen Sie sich das Schema an. Folgen Sie dazu der Anleitung unter Schemadefinition ansehen.

C#

Weitere Informationen finden Sie in der Referenzdokumentation zur Vertex AI Agent Builder C# 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.

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 zur Authentifizierung bei Vertex AI Agent Builder Standardanmeldedaten für Anwendungen ein. 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 Referenzdokumentation zur Vertex AI Agent Builder Python 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.

# 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 Referenzdokumentation zur Vertex AI Agent Builder Ruby 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.

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. Wenn Sie ein Schema mit einem neuen Schema aktualisieren möchten, das nicht abwärtskompatibel ist, müssen Sie alle Dokumente im Datenspeicher löschen, das Schema löschen und ein neues Schema erstellen.

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

  • Zeit Das erneute Indexieren 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 Preise für die Document AI-Funktion.

Folgendes wird bei Schemaaktualisierungen nicht unterstützt:

  • Feldtyp ändern Bei einer Schemaaktualisierung kann der Feldtyp nicht geändert werden. Ein Feld, das auf eine Ganzzahl zugeordnet ist, kann beispielsweise nicht in einen String geändert werden.
  • Feld entfernen Ein Feld kann nach der Definition 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 Schemaupdates. 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 dem Schema das Feld properties.uri hinzugefügt.

    {
      "$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"
          }
        }
      }
    }
    
  • Anmerkungen 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 wurde der Typ des Felds title von „String“ in „Zahl“ geändert. Das ist nicht möglich.

      {
        "$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. Das ist nicht möglich.

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