Schema angeben oder automatisch erkennen lassen

Wenn Sie strukturierte Daten mit der Google Cloud Console importieren, erkennt Agent Search das Schema automatisch. Sie können entweder dieses automatisch erkannte Schema in Ihrer Engine verwenden oder über die API ein Schema bereitstellen, um die Struktur der Daten anzugeben.

Wenn Sie ein Schema bereitstellen und es später mit einem neuen Schema aktualisieren, muss das neue Schema abwärtskompatibel mit dem ursprünglichen Schema sein. Andernfalls schlägt die Schemaaktualisierung fehl.

Weitere Informationen zum Schema finden Sie unter dataStores.schemas.

Möglichkeiten zum Bereitstellen des Schemas für Ihren Datenspeicher

Es gibt verschiedene Möglichkeiten, das Schema für strukturierte Daten zu bestimmen.

  • Automatische Erkennung und Bearbeitung : Lassen Sie Agent Search das erste Schema automatisch erkennen und vorschlagen. Anschließend verfeinern Sie das Schema über die Console-Oberfläche. Google empfiehlt dringend, nach der automatischen Erkennung der Felder allen wichtigen Feldern Schlüsselattribute zuzuordnen.

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

  • Schema als JSON-Objekt bereitstellen : Stellen Sie das Schema als JSON-Objekt für Agent Search bereit. 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 entsprechend hoch.

    Dieser Ansatz kann verwendet werden, wenn Sie einen Datenspeicher über die API mit einem curl-Befehl (oder einem Programm) erstellen. Ein Beispiel finden Sie unter Einmaliger Import aus BigQuery. Weitere Informationen finden Sie in der folgenden Anleitung, Eigenes Schema bereitstellen.

  • Medien: Daten im von Google definierten Schema bereitstellen : Wenn Sie einen Datenspeicher für Medien erstellen, können Sie das von Google vordefinierte Schema verwenden. Bei dieser Option wird davon ausgegangen, dass Sie Ihr JSON-Objekt im Format unter Informationen zu Mediendokumenten und Datenspeichern strukturiert haben. Standardmäßig werden dem Schema durch die automatische Erkennung alle neuen Felder angehängt, die bei der Datenaufnahme gefunden werden.

    Dieser Ansatz wird verwendet, wenn Sie der Anleitung unter Medien-App und Datenspeicher erstellen folgen. Er wird auch in den Anleitungen Erste Schritte mit Medien empfehlungen und Erste Schritte mit der Medien suche verwendet, in denen die Beispieldaten im von Google vordefinierten Schema bereitgestellt werden.

  • Medien: Automatische Erkennung und Bearbeitung, wobei die erforderlichen Medienattribute berücksichtigt werden müssen : Für Mediendaten können Sie die automatische Erkennung verwenden, um das Schema vorzuschlagen, und die Bearbeitung, um es zu verfeinern. In Ihrem JSON-Objekt müssen Sie Felder einfügen, die den Schlüsselattributen für Medien zugeordnet werden können: title, uri, category, media_duration und media_available_time.

    Dieser Ansatz wird verwendet, wenn Sie Mediendaten über die Google Cloud Console importieren und die Mediendaten nicht im von Google definierten Schema vorliegen.

  • Medien: Eigenes Schema als JSON-Objekt bereitstellen : Stellen Sie das Schema als JSON-Objekt für Agent Search bereit. Sie müssen ein korrektes JSON-Objekt vorbereitet haben. Das Schema muss Felder enthalten, die den Schlüsselattributen für Medien zugeordnet werden können: title, uri, category, media_duration und media_available_time.

    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 entsprechend hoch.

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

Informationen zur automatischen Erkennung und Bearbeitung

Wenn Sie mit dem Importieren von Daten beginnen, werden in Agent Search die ersten importierten Dokumente als Beispiele 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üsselattributen zuordnen möchten, in den Beispieldokumenten nicht vorhanden sind, können Sie sie manuell hinzufügen, wenn Sie das Schema überprüfen.

Wenn Agent Search später beim Datenimport zusätzliche Felder findet, 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 Abschnitt Schema aktualisieren.

Beispielschema als JSON-Objekt

Sie können Ihr eigenes Schema im Format eines JSON-Schemas definieren. Das ist eine deklarative Open-Source-Sprache zum Definieren, Annotieren und Validieren von JSON-Dokumenten. Beispiel für eine gültige JSON-Schema-Annotation:

{
  "$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 einfügen, die den Schlüsselattributen für Medien zugeordnet werden können. Diese Schlüsselattribute sind in diesem Beispiel dargestellt.

Dieses Beispielschema enthält u. a. die folgenden Felder:

  • dynamic: Wenn dynamic auf den Stringwert "true" gesetzt ist, werden alle neuen Attribute, die in den importierten Daten gefunden werden, dem Schema hinzugefügt. Wenn dynamic auf "false" gesetzt ist, werden neue Attribute in importierten Daten ignoriert. Die Attribute werden dem Schema nicht hinzugefügt die Werte werden nicht importiert.

    Angenommen, ein Schema hat zwei Attribute: title und description. Sie laden Daten hoch, die Attribute für title, description und rating enthalten. Wenn dynamic "true" ist, werden das Attribut und die Daten für „rating“ importiert. Wenn dynamic "false" ist, werden die Attribute für rating nicht importiert, title und description aber schon.

    Der Standardwert ist "true".

  • datetime_detection: Wenn datetime_detection auf den booleschen Wert true gesetzt ist, wird der Schematyp beim Import von Daten im Datums-/Uhrzeitformat auf datetime festgelegt. 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 gesetzt ist, wird der Schematyp beim Import von Daten im Datums-/Uhrzeitformat auf string festgelegt.

    Der Standardwert ist true.

  • geolocation_detection: Wenn geolocation_detection auf den booleschen Wert true gesetzt ist, wird der Schematyp beim Import von Daten im Format für die Standortbestimmung auf geolocation festgelegt. Daten werden als Standortbestimmung erkannt, wenn es sich um ein Objekt mit einer Breitengrad- und einer Längengradzahl oder um ein Objekt mit einem Adressstring 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 gesetzt ist, wird der Schematyp beim Import von Daten im Format für die Standortbestimmung auf object festgelegt.

    Der Standardwert ist true.

  • keyPropertyMapping: Ein Feld, in dem vordefinierte Suchbegriffe kritischen Feldern in Ihren Dokumenten zugeordnet werden, um ihre semantische Bedeutung zu verdeutlichen. Werte sind unter anderem title, description, uri, category, update_time und create_time. Der Feldname muss nicht mit dem Wert keyPropertyValues übereinstimmen. Für ein Feld mit dem Namen my_title können Sie beispielsweise das Feld keyPropertyValues mit dem Wert title einfügen.

    Bei Suchdatenspeichern sind mit keyPropertyMapping gekennzeichnete Felder standardmäßig indexierbar und suchbar, aber nicht abrufbar, vervollständigbar oder als dynamicFacetable-Attribut verwendbar. Das bedeutet, dass Sie die Felder indexable oder searchable nicht zusammen mit dem Feld keyPropertyValues angeben müssen, um das erwartete Standardverhalten zu erhalten.

    Mit Schlüsselattributen lässt sich die Qualität von Such- und Empfehlungsergebnissen und die Genauigkeit der automatischen Vervollständigung von Suchanfragen verbessern. Wenn Sie die automatische Schemaerkennung verwenden, werden Schlüsselattribute nicht automatisch zugeordnet. Sie müssen die Zuordnung manuell hinzufügen.

    Die Zuordnung eines Dokumentfelds zu update_time (oder create_time als Fallback) ist für das benutzerdefinierte Ranking-Signal document_age erforderlich. Weitere Informationen zu document_age finden Sie unter Standard signal.

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

Die folgenden Attributfelder gelten nur für Suchanwendungen:

  • retrievable: Gibt an, ob dieses Feld in einer Suchantwort zurückgegeben werden kann. Dies 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 Sie ein Feld abrufbar machen möchten, fügen Sie "retrievable": true in das Feld ein.

  • indexable: Gibt an, ob dieses Feld in der Methode servingConfigs.search gefiltert, facettiert, optimiert oder sortiert werden kann. Dies 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 Sie ein Feld indexierbar machen möchten, fügen Sie "indexable": true in das Feld ein.

  • dynamicFacetable: Gibt an, dass das Feld als dynamisches Attribut verwendet werden kann. Dies kann für Felder des Typs number, string, boolean und integer festgelegt werden. Damit ein Feld als dynamisches Attribut verwendbar ist, muss es auch indexierbar sein. Fügen Sie dazu "dynamicFacetable": true und "indexable": true in das Feld ein.

  • searchable: Gibt an, ob dieses Feld rückwärts indexiert werden kann, um unstrukturierte Textanfragen abzugleichen. Dieser Wert kann nur für Felder vom Typ string festgelegt werden. Es können maximal 50 Felder als suchbar festgelegt werden. Benutzerdefinierte Felder sind standardmäßig nicht suchbar, mit Ausnahme von Feldern, die das Feld keyPropertyMapping enthalten. Wenn Sie ein Feld suchbar machen möchten, fügen Sie "searchable": true in das Feld ein.

  • completable: Gibt an, ob dieses Feld als automatisch vervollständigter Vorschlag zurückgegeben werden kann. Dieser Wert kann nur für Felder vom Typ string festgelegt werden. Wenn ein Feld vervollständigbar werden soll, fügen Sie "completable": true hinzu.

Außerdem gilt das folgende Feld nur für Empfehlungsanwendungen:

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

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

Eigenes Schema als JSON-Objekt bereitstellen

Wenn Sie ein eigenes Schema bereitstellen möchten, erstellen Sie einen Datenspeicher, der ein leeres Schema enthält. Anschließend aktualisieren Sie das Schema und stellen Ihr Schema als JSON-Objekt bereit. Gehen Sie so vor:

  1. Bereiten Sie das Schema als JSON-Objekt vor. Verwenden Sie dazu das Beispielschema als JSON-Objekt als Leitfaden.

  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: die ID Ihres Google Cloud Projekts in.
    • DATA_STORE_ID: die ID des Agent Search-Datenspeichers, den Sie erstellen möchten. Diese ID darf nur Kleinbuchstaben, Ziffern, Unterstriche und Bindestriche enthalten.
    • DATA_STORE_DISPLAY_NAME: der Anzeigename des Agent Search-Datenspeichers, den Sie erstellen möchten.
    • INDUSTRY_VERTICAL: GENERIC oder MEDIA

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

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

Nächste Schritte