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 Aktualisieren des Schemas für eine Website wird nur über die REST API unterstützt.

Sie können neue Felder hinzufügen, indexierbare, suchbare und abrufbare Anmerkungen für ein Feld ändern oder ein Feld als Schlüsselattribut kennzeichnen, z. B. title, uri und description.

Hinweis

Bevor Sie Ihr Schema aktualisieren, sollten Sie die wichtigsten Konzepte kennen, die in diesem Abschnitt erläutert werden.

Bedeutung von Schlüsselattributen

Es gibt mehrere Gründe, warum Sie Ihre Schemafelder Schlüsselattributen zuordnen müssen:

• Google empfiehlt dringend, Ihr Schema mit Zuordnungen von Schlüsselattributen zu aktualisieren, insbesondere für title. So wird sichergestellt, dass Ihre Ergebnisse korrekt angezeigt werden, und Agent Search kann wichtige Informationen identifizieren, um bessere Ergebnisse zu generieren.

• Wenn Sie in strukturierten Datenspeichern das keywordSimilarityScore Signal in Ihrer Suchantwort erhalten möchten, müssen Sie Ihr Schema aktualisieren, um Folgendes zu tun:

  • Ordnen Sie die für Keyword-Optionen erforderlichen Textfelder den Schlüsselattributen title und description zu.
  • Aktualisieren Sie die Anmerkung für die Textfelder als Searchable.

Voraussetzungen

Wenn Sie ein Schema aktualisieren, muss das neue Schema abwärtskompatibel mit dem Schema sein, 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.

Durch das Aktualisieren eines Schemas wird eine Neuindexierung aller Dokumente ausgelöst. Dies kann Zeit in Anspruch nehmen und zusätzliche Kosten verursachen:

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

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

• Auswirkungen auf den Dienst : Die Neuindexierung kann zu langsamen oder nicht verfügbaren Diensten führen, insbesondere bei großen Datenspeichern. Google empfiehlt, Schemaaktualisierungen entsprechend zu planen und potenzielle Ausfallzeiten für kritische Anwendungen zu berücksichtigen.

Schemaaktualisierungen unterstützen Folgendes nicht:

• Ändern eines Feldtyps : Bei einer Schemaaktualisierung kann der Typ des Felds nicht geändert werden. Ein Feld, das integer zugeordnet ist, kann beispielsweise nicht in string geändert werden.
• Entfernen eines Felds : Nachdem ein Feld definiert wurde, kann es nicht mehr entfernt werden. Sie können weiterhin neue Felder hinzufügen, aber ein vorhandenes Feld kann nicht entfernt werden.

Schema aktualisieren

Sie können Ihr Schema in der Google Cloud Console oder mit der API aktualisieren.

Hinweis: Wenn Sie das Schema bearbeiten, wird Ihr Datenspeicher noch einmal indexiert. Bei großen Datenspeichern kann die Indexierung mehrere Stunden dauern.

Console

So aktualisieren Sie ein Schema in der Google Cloud Console:

1. Lesen Sie den Abschnitt Anforderungen und Einschränkungen, um zu prüfen , ob Ihre Schemaaktualisierung gültig ist.

2. Wenn Sie Feldanmerkungen aktualisieren (Felder als indexierbar, abrufbar, dynamisch facettierbar, suchbar oder vervollständigbar festlegen), lesen Sie den Abschnitt Feldeinstellungen konfigurieren, um die Einschränkungen und Anforderungen für jeden Anmerkungstyp zu erfahren.

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 KI-Anwendungen auf.

   KI-Anwendungen

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 mit dem Namen details beispielsweise immer die Beschreibung eines Dokuments enthält, ordnen Sie dieses Feld dem Schlüsselattribut Description zu.

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

   • Feldanmerkungen aktualisieren:Wenn Sie Anmerkungen für ein Feld aktualisieren möchten, wählen Sie die Anmerkungseinstellung eines Felds aus oder heben Sie die Auswahl auf. Verfügbare Anmerkungen sind Abrufbar, Indexierbar, Dynamisch facettierbar, Suchbar und Vervollständigbar. Für einige Feldeinstellungen gelten Einschränkungen. Unter Feldeinstellungen konfigurieren finden Sie Beschreibungen und Anforderungen für jeden Anmerkungstyp.

   • 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 Agent Search für die Neuindexierung Ihrer Daten nach dem Import benötigt.

     1. Klicken Sie auf Neue Felder hinzufügen , um diesen Abschnitt zu maximieren.

     2. Klicken Sie auf add_box Knoten hinzufügen und geben Sie die Einstellungen für das neue Feld an.

        Wenn Sie ein Array angeben möchten, setzen Sie Array auf Ja. Wenn Sie beispielsweise ein Array von Strings hinzufügen möchten, setzen Sie Typ auf string und Array auf Yes.

        Bei einem Index für einen Datenspeicher für Websitedaten sind alle Felder, die Sie hinzufügen, standardmäßig Arrays.

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

    Durch das Ändern des Schemas wird eine Neuindexierung ausgelöst. Bei großen Datenspeichern kann die Neuindexierung Stunden dauern.

REST

So aktualisieren Sie das Schema mit der API:

1. Lesen Sie die Abschnitte Anforderungen und Einschränkungen und Beispiele für Einschränkungen (nur REST), 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, dynamisch facettierbar oder suchbar festlegen), lesen Sie den Abschnitt Feldeinstellungen konfigurieren, um die Einschränkungen und Anforderungen für jeden Anmerkungstyp zu erfahren.

3. Wenn Sie ein automatisch erkanntes Schema bearbeiten, prüfen Sie, ob die Datenaufnahme abgeschlossen ist. Andernfalls ist das Schema möglicherweise noch nicht zur Bearbeitung verfügbar.

4. Suchen Sie nach Ihrer Datenspeicher-ID. Wenn Sie die ID Ihres Datenspeichers bereits haben, fahren Sie mit dem nächsten Schritt fort.

   1. Rufen Sie in der Google Cloud Console die Seite KI-Anwendungen auf und klicken Sie im Navigationsmenü auf Datenspeicher.

      Rufen Sie die Seite Datenspeicher auf.

   2. Klicken Sie auf den Namen des Datenspeichers.

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

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

   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: die ID Ihres Google Cloud Projekts in.
   • DATA_STORE_ID: die ID des Agent 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"
         }
       }
     }

     Beispielbefehl und -ergebnis

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

6. Optional: Überprüfen Sie das Schema, indem Sie die Schritte unter Schemadefinition ansehen ausführen.

C#

Weitere Informationen finden Sie in der API-Referenzdokumentation zu Agent SearchC#.

Richten Sie zur Authentifizierung bei Agent Search 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 API-Referenzdokumentation zu Agent SearchGo.

Richten Sie zur Authentifizierung bei Agent Search 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 API-Referenzdokumentation zu Agent Search Java.

Richten Sie zur Authentifizierung bei Agent Search 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 API-Referenzdokumentation zu Agent Search Python.

Richten Sie zur Authentifizierung bei Agent Search 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 APIRuby Referenzdokumentation zu Agent Search.

Richten Sie zur Authentifizierung bei Agent Search 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

Beispiele für Einschränkungen (nur REST)

In diesem Abschnitt finden Sie Beispiele für gültige und ungültige Arten von Schemaaktualisierungen. In diesen Beispielen wird das folgende JSON-Beispielschema 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 Aktualisierungen

Die folgenden Aktualisierungen des Beispielschemas 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 für Schlüsselattribute für title, description oder uri hinzufügen oder entfernen. In diesem Beispiel wurde dem Feld title die Anmerkung 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 Aktualisierungen des Beispielschemas werden nicht unterstützt.

• Ändern eines Feldtyps : In diesem Beispiel wurde der Typ des Felds title von „string“ in „number“ 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"
          }
        }
      }
    }
  

• Entfernen eines Felds : 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

• Schemadefinition für strukturierte Daten ansehen
• Schema für strukturierte Daten löschen
• Suchergebnisse in der Vorschau ansehen