Schema angeben oder automatisch erkennen

Wenn Sie strukturierte Daten über die Google Cloud Console importieren, wird das Schema in Vertex AI Agent Builder automatisch erkannt. Sie können dieses automatisch erkannte Schema entweder in Ihrer Engine verwenden oder über die API ein Schema angeben, um die Struktur der Daten anzugeben.

Wenn Sie ein Schema angeben und es später durch ein neues Schema aktualisieren, muss das neue Schema rückwärtskompatibel mit dem Original sein. Andernfalls schlägt die Schemaaktualisierung fehl.

Weitere Informationen zum Schema finden Sie unter dataStores.schemas.

Ansätze für die Bereitstellung des Schemas für Ihren Datenspeicher

Es gibt verschiedene Ansätze, um das Schema für strukturierte Daten zu bestimmen.

  • Automatische Erkennung und Bearbeitung Lassen Sie Vertex AI Agent Builder ein Anfangsschema automatisch erkennen und vorschlagen. Anschließend können Sie das Schema über die Console-Benutzeroberfläche optimieren. Google empfiehlt dringend, nach der automatischen Erkennung Ihrer Felder allen wichtigen Feldern wichtige Properties zuzuordnen.

    Dieser Ansatz wird verwendet, wenn Sie der Anleitung für strukturierte Daten in der Google Cloud Console unter Suchdatenspeicher erstellen und Allgemeinen Empfehlungsdatenspeicher erstellen folgen.

  • Geben Sie das Schema als JSON-Objekt an. Geben Sie das Schema als JSON-Objekt in Vertex AI Agent Builder an. Sie müssen ein korrektes JSON-Objekt vorbereitet haben. Ein Beispiel für ein JSON-Objekt finden Sie unter Beispiel für ein Schema als JSON-Objekt. Nachdem Sie das Schema erstellt haben, laden Sie Ihre Daten gemäß diesem Schema hoch.

    Dieser Ansatz kann verwendet werden, wenn Sie einen Datenspeicher über die API mit einem Curl-Befehl (oder -Programm) erstellen. Weitere Informationen finden Sie unter Einmal aus BigQuery importieren. Weitere Informationen finden Sie in der Anleitung Eigenes Schema angeben.

  • Medien: Geben Sie Ihre Daten im von Google definierten Schema an. Wenn Sie einen Datenspeicher für Medien erstellen, können Sie das vordefinierte Schema von Google verwenden. Wenn Sie diese Option auswählen, wird davon ausgegangen, dass Sie Ihr JSON-Objekt im Format strukturiert haben, das unter Mediendokumente und Datenspeicher beschrieben wird. Standardmäßig werden dem Schema bei der automatischen Erkennung alle neuen Felder hinzugefügt, die bei der Datenaufnahme gefunden werden.

    Dieser Ansatz wird verwendet, wenn Sie der Anleitung unter Media-App und Datenspeicher erstellen folgen. Dieser Ansatz wird auch in den Anleitungen Erste Schritte: Medienempfehlungen und Erste Schritte: Mediensuche verwendet, in denen die Beispieldaten im vorab definierten Google-Schema bereitgestellt werden.

  • Medien: Automatische Erkennung und Bearbeitung. Achten Sie darauf, die erforderlichen Medieneigenschaften anzugeben. Bei Mediendaten können Sie die automatische Erkennung verwenden, um ein Schema vorzuschlagen, und es dann bearbeiten, um es zu optimieren. Dein JSON-Objekt muss Felder enthalten, die den Media-Schlüsseleigenschaften title, uri, category, media_duration und media_available_time zugeordnet werden können.

    Diese Methode verwenden Sie, wenn Sie Mediendaten über die Google Cloud Console importieren, die nicht dem von Google definierten Schema entsprechen.

  • Medien: Geben Sie ein eigenes Schema als JSON-Objekt an. Geben Sie das Schema als JSON-Objekt in Vertex AI Agent Builder an. Sie müssen ein korrektes JSON-Objekt vorbereitet haben. Das Schema muss Felder enthalten, die den Media-Schlüsseleigenschaften title, uri, category, media_duration und media_available_time zugeordnet werden können.

    Ein Beispiel für ein JSON-Objekt finden Sie unter Beispiel für ein Schema als JSON-Objekt. Nachdem Sie das Schema erstellt haben, laden Sie Ihre Mediendaten gemäß diesem Schema hoch.

    Bei diesem Ansatz verwenden Sie die API über einen Curl-Befehl (oder ein Curl-Programm). Weitere Informationen finden Sie in der Anleitung unter Eigenes Schema bereitstellen.

Automatische Erkennung und Bearbeitung

Wenn Sie mit dem Importieren von Daten beginnen, werden in Vertex AI Search die ersten paar importierten Dokumente als Stichprobe verwendet. Anhand dieser Dokumente wird ein Schema für die Daten vorgeschlagen, das Sie dann überprüfen oder bearbeiten können.

Wenn Felder, die Sie Schlüsseleigenschaften zuordnen möchten, in den Stichprobendokumenten nicht vorhanden sind, können Sie diese Felder beim Überprüfen des Schemas manuell hinzufügen.

Wenn Vertex AI Search später im Datenimport auf zusätzliche Felder stößt, werden diese Felder trotzdem importiert und dem Schema hinzugefügt. Wenn Sie das Schema bearbeiten möchten, nachdem alle Daten importiert wurden, lesen Sie den Hilfeartikel Schema aktualisieren.

Beispiel für ein Schema als JSON-Objekt

Sie können Ihr eigenes Schema mit dem JSON Schema-Format definieren. Das ist eine Open-Source-deklarative Sprache zum Definieren, Annotieren und Validieren von JSON-Dokumenten. Dies ist beispielsweise eine gültige JSON-Schema-Anmerkung:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "dynamic": "true",
  "datetime_detection": true,
  "geolocation_detection": true,
  "properties": {
    "title": {
      "type": "string",
      "keyPropertyMapping": "title",
      "retrievable": true,
      "completable": true
    },
    "description": {
      "type": "string",
      "keyPropertyMapping": "description"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "keyPropertyMapping": "category"
      }
    },
    "uri": {
      "type": "string",
      "keyPropertyMapping": "uri"
    },
    "brand": {
      "type": "string",
      "indexable": true,
      "dynamicFacetable": true
    },
    "location": {
      "type": "geolocation",
      "indexable": true,
      "retrievable": true
    },
    "creationDate": {
      "type": "datetime",
      "indexable": true,
      "retrievable": true
    },
    "isCurrent": {
      "type": "boolean",
      "indexable": true,
      "retrievable": true
    },
    "runtime": {
      "type": "string",
      "keyPropertyMapping": "media_duration"
    },
    "releaseDate": {
      "type": "string",
      "keyPropertyMapping": "media_available_time"
    }
  }
}

Wenn Sie ein Medienschema definieren, müssen Sie Felder angeben, die den Schlüsseleigenschaften der Medien zugeordnet werden können. Diese wichtigen Properties sind in diesem Beispiel zu sehen.

Hier sind einige der Felder in diesem Schemabeispiel:

  • dynamic: Wenn dynamic auf den Stringwert "true" gesetzt ist, werden dem Schema alle neuen Properties hinzugefügt, die in den importierten Daten gefunden werden. Wenn dynamic auf "false" gesetzt ist, werden neue Properties, die in importierten Daten gefunden werden, ignoriert. Sie werden weder dem Schema hinzugefügt noch importiert.

    Ein Schema hat beispielsweise zwei Eigenschaften: title und description. Sie laden Daten hoch, die Eigenschaften für title, description und rating enthalten. Wenn dynamic "true" ist, werden die Bewertungseigenschaft und die Daten importiert. Wenn dynamic "false" ist, werden rating-Attribute nicht importiert, title- und description-Attribute jedoch schon.

    Der Standardwert ist "true".

  • datetime_detection: Wenn datetime_detection auf den booleschen Wert true festgelegt ist, wird der Schematyp auf datetime gesetzt, wenn Daten im Datums-/Uhrzeitformat importiert werden. Die unterstützten Formate sind RFC 3339 und ISO 8601.

    Beispiel:

    • 2024-08-05 08:30:00 UTC

    • 2024-08-05T08:30:00Z

    • 2024-08-05T01:30:00-07:00

    • 2024-08-05

    • 2024-08-05T08:30:00+00:00

    Wenn datatime_detection auf den booleschen Wert false festgelegt ist, wird der Schematyp auf string gesetzt, wenn Daten im Datums-/Uhrzeitformat importiert werden.

    Der Standardwert ist true.

  • geolocation_detection: Wenn geolocation_detection auf den booleschen Wert true gesetzt ist, wird beim Importieren von Daten im Geolocation-Format der Schematyp auf geolocation festgelegt. Daten werden als Standortdaten erkannt, wenn es sich um ein Objekt mit einem Breiten- und einem Längengrad oder um ein Objekt mit einer Adresszeichenfolge handelt.

    Beispiel:

    • "myLocation": {"latitude":37.42, "longitude":-122.08}

    • "myLocation": {"address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043"}

    Wenn geolocation_detection auf den booleschen Wert false festgelegt ist, wird beim Importieren von Daten im Geolocation-Format der Schematyp auf object festgelegt.

    Der Standardwert ist true.

  • keyPropertyMapping: Ein Feld, das vordefinierte Keywords wichtigen Feldern in Ihren Dokumenten zuordnet, um ihre semantische Bedeutung zu verdeutlichen. Zulässige Werte sind title, description, uri und category. Der Feldname muss nicht mit dem keyPropertyValues-Wert übereinstimmen. Sie können beispielsweise für ein Feld mit dem Namen my_title ein keyPropertyValues-Feld mit dem Wert title einfügen.

    Bei Suchdatenspeichern sind Felder, die mit keyPropertyMapping gekennzeichnet sind, standardmäßig indexierbar und suchbar, aber nicht abrufbar, ausfüllbar oder für dynamische Facetten verfügbar. Das bedeutet, dass Sie die Felder indexable oder searchable nicht in einem Feld vom Typ keyPropertyValues angeben müssen, um das erwartete Standardverhalten zu erhalten.

  • type: Der Typ des Felds. Dies ist ein Stringwert, der datetime, geolocation oder einer der primitiven Typen (integer, boolean, object, array, number oder string) ist.

Die folgenden Property-Felder gelten nur für Such-Apps:

  • retrievable: Gibt an, ob dieses Feld in einer Suchantwort zurückgegeben werden kann. Diese Option kann für Felder vom Typ number, string, boolean, integer, datetime und geolocation festgelegt werden. Es können maximal 50 Felder als abrufbar festgelegt werden. Benutzerdefinierte Felder und keyPropertyValues-Felder können standardmäßig nicht abgerufen werden. Wenn ein Feld abgerufen werden soll, muss es "retrievable": true enthalten.

  • indexable: Gibt an, ob dieses Feld mit der Methode servingConfigs.search gefiltert, facettiert, geboostet oder sortiert werden kann. Diese Option kann für Felder vom Typ number, string, boolean, integer, datetime und geolocation festgelegt werden. Es können maximal 50 Felder als indexierbar festgelegt werden. Benutzerdefinierte Felder sind standardmäßig nicht indexierbar, mit Ausnahme von Feldern, die das Feld keyPropertyMapping enthalten. Wenn ein Feld indexierbar sein soll, muss es "indexable": true enthalten.

  • dynamicFacetable: Gibt an, dass das Feld als dynamisches Attribut verwendet werden kann. Diese Option kann für Felder vom Typ number, string, boolean und integer festgelegt werden. Damit ein Feld dynamisch facettiert werden kann, muss es auch indexierbar sein. Fügen Sie dazu "dynamicFacetable": true und "indexable": true in das Feld ein.

  • searchable: Gibt an, ob dieses Feld umgekehrt indexiert werden kann, um unstrukturierte Textabfragen abzugleichen. Diese Option kann nur für Felder vom Typ string festgelegt werden. Es können maximal 50 Felder als suchbar festgelegt werden. Benutzerdefinierte Felder können standardmäßig nicht durchsucht werden, mit Ausnahme von Feldern, die das Feld keyPropertyMapping enthalten. Wenn ein Feld suchbar sein soll, muss es "searchable": true enthalten.

  • completable: Gibt an, ob dieses Feld als Vorschlag für die automatische Vervollständigung zurückgegeben werden kann. Diese Option kann nur für Felder vom Typ string festgelegt werden. Wenn ein Feld ausfüllbar sein soll, fügen Sie "completable": true in das Feld ein.

Außerdem gilt das folgende Feld nur für Empfehlungs-Apps:

  • recommendationsFilterable: Gibt an, dass das Feld in einem Empfehlungsfilterausdruck verwendet werden kann. Allgemeine Informationen zum Filtern von Empfehlungen finden Sie unter Empfehlungen filtern.

      ...
        "genres": {
        "type": "string",
        "recommendationsFilterable": true,
        ...
      },

Eigenes Schema als JSON-Objekt angeben

Wenn Sie ein eigenes Schema bereitstellen möchten, erstellen Sie einen Datenspeicher mit einem leeren Schema und aktualisieren das Schema dann, indem Sie es als JSON-Objekt angeben. Gehen Sie so vor:

  1. Bereiten Sie das Schema als JSON-Objekt vor. Orientieren Sie sich dabei am Beispielschema als JSON-Objekt.

  2. Erstellen Sie einen Datenspeicher.

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores?dataStoreId=DATA_STORE_ID" \
    -d '{
      "displayName": "DATA_STORE_DISPLAY_NAME",
      "industryVertical": "INDUSTRY_VERTICAL"
    }'
    

    Ersetzen Sie Folgendes:

    • PROJECT_ID ist die ID Ihres Google Cloud-Projekts.
    • DATA_STORE_ID: Die ID des Vertex AI Search-Datenspeichers, den Sie erstellen möchten. Die ID darf nur Kleinbuchstaben, Ziffern, Unterstriche und Bindestriche enthalten.
    • DATA_STORE_DISPLAY_NAME: Der Anzeigename des Vertex AI Search-Datenspeichers, den Sie erstellen möchten.
    • INDUSTRY_VERTICAL: GENERIC oder MEDIA
  3. 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"
          }
        }
      }
  4. Optional: Sehen Sie sich das Schema an. Folgen Sie dazu der Anleitung unter Schemadefinition ansehen.

Nächste Schritte