Diese Seite wurde von der Cloud Translation API übersetzt.

Mediendokumente und Datenspeicher

Auf dieser Seite finden Sie Informationen zu Dokumenten und Datenspeichern für Medien. Wenn Sie Medienempfehlungen oder die Mediensuche verwenden, lesen Sie sich die Schemaanforderungen für Ihre Dokumente und Datenspeicher auf dieser Seite durch, bevor Sie Ihre Daten hochladen.

Übersicht

Ein Dokument ist ein beliebiges Element, das Sie in einen Vertex AI Agent Builder-Datenspeicher hochladen. Bei Medien enthält ein Dokument in der Regel Metadaten zu Medieninhalten wie Videos, Nachrichtenartikeln, Musikdateien oder Podcasts. Diese Metadaten werden im Document-Objekt in der API erfasst.

Ihr Datenspeicher enthält eine Sammlung von Dokumenten, die Sie hochgeladen haben. Wenn Sie einen Datenspeicher erstellen, geben Sie an, dass er Mediendokumente enthalten soll. Datenspeicher für Medien können nur an Medien-Apps angehängt werden, nicht an andere App-Typen wie allgemeine Suchanwendungen und Empfehlungen. Datenspeicher werden in der API durch die Ressource DataStore dargestellt.

Die Qualität der von Ihnen hochgeladenen Daten hat direkten Einfluss auf die Qualität der Ergebnisse, die von Medien-Apps bereitgestellt werden. Im Allgemeinen gilt: Je genauer und spezifischer die Informationen sind, desto höher ist die Qualität der Ergebnisse.

Die Daten, die Sie in den Datenspeicher hochladen, müssen in einem bestimmten JSON-Schema formatiert sein. Die in diesem Schema angeordneten Daten müssen sich in einer BigQuery-Tabelle, einer Datei oder mehreren Dateien in Cloud Storage oder in einem JSON-Objekt befinden, das direkt über die Google Cloud Console hochgeladen werden kann.

Von Google vordefiniertes Schema im Vergleich zu einem benutzerdefinierten Schema

Für das Schema für Mediendaten haben Sie zwei Möglichkeiten.

Das von Google vordefinierte Schema. Wenn Sie noch kein Schema für Ihre Mediendaten entworfen haben, ist das von Google vordefinierte Schema eine gute Wahl.
Ihr eigenes Schema Wenn Ihre Daten bereits in einem Schema formatiert sind, können Sie Ihr eigenes Schema verwenden. Dabei gelten die folgenden Anforderungen:

Ihr Schema muss Felder enthalten, die den fünf wichtigsten Eigenschaften für Medien zugeordnet werden können:
- title
- uri
- category
- media_available_time
- media_duration Dieses Feld ist wichtig für Apps mit Medienempfehlungen, bei denen das Geschäftsziel darin besteht, die Conversion-Rate (CVR) oder die Wiedergabedauer pro Besucher zu maximieren.
Es gibt weitere wichtige Properties, die nicht erforderlich sind. Für qualitativ hochwertige Ergebnisse sollten Sie jedoch so viele wie möglich Ihrem Schema zuordnen. Diese Medieneigenschaften sind:
- description (empfohlen)
- image
- image_name
- image_uri
- language-code
- media_aggregated_rating
- media_aggregated_rating_count
- media_aggregated_rating_score
- media_aggregated_rating_source
- media_content_index
- media_content_rating
- media_country_of_origin
- media_expire_time
- media_filter_tag
- media_hash_tag
- media_in_language
- media_organization
- media_organization_custom_role
- media_organization_name
- media_organization_rank
- media_organization_role
- media_organization_uri
- media_person
- media_person_custom_role
- media_person_name
- media_person_rank
- media_person_role
- media_person_uri
- media_production_year
- media_type
Weitere Informationen zu diesen Properties finden Sie unter Schlüsseleigenschaften. Die Namen sind ähnlich, aber einige unterscheiden sich geringfügig. Einige Namen haben beispielsweise das Präfix media_ und andere sind im Plural.

JSON-Schema für `Document`

Wenn Sie Medien verwenden, können Dokumente das von Google vordefinierte JSON-Schema für Medien verwenden.

Dokumente werden entweder als JSON- oder als Strukturdaten hochgeladen. Achten Sie darauf, dass das JSON-Dokument oder -Objekt dem folgenden JSON-Schema entspricht. Für die Validierung des JSON-Schemas wird JSON Schema 2020-12 verwendet. Weitere Informationen zu JSON-Schemas finden Sie in der JSON-Schema-Spezifikationsdokumentation auf json-schema.org.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
    },
    "description": {
      "type": "string",
    },
    "media_type": {
      "type": "string",
    },
    "language_code": {
      "type": "string",
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
      }
    },
    "uri": {
      "type": "string",
    },
    "images": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "uri": {
            "type": "string",
          },
          "name": {
            "type": "string",
          }
        },
      }
    },
    "in_languages": {
      "type": "array",
      "items": {
        "type": "string",
      }
    },
    "country_of_origin": {
      "type": "string",
    },
    "content_index": {
      "type": "integer",
    },
    "persons": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
          },
          "role": {
            "type": "string",
          },
          "custom_role": {
            "type": "string",
          },
          "rank": {
            "type": "integer",
          },
          "uri": {
            "type": "string",
          }
        },
        "required": ["name", "role"],
      }
    },
    "organizations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
          },
          "role": {
            "type": "string",
          },
          "custom_role": {
            "type": "string",
          },
          "rank": {
            "type": "integer",
          },
          "uri": {
            "type": "string",
          }
        },
        "required": ["name", "role"],
      }
    },
    "hash_tags": {
      "type": "array",
      "items": {
        "type": "string",
      }
    },
    "filter_tags": {
      "type": "array",
      "items": {
        "type": "string",
      }
    },
    "duration": {
      "type": "string",
    },
    "content_rating": {
      "type": "array",
      "items": {
        "type": "string",
      }
    },
    "aggregate_ratings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "rating_source": {
            "type": "string",
          },
          "rating_score": {
            "type": "number",
          },
          "rating_count": {
            "type": "integer",
          }
        },
        "required": ["rating_source"],
      }
    },
    "available_time": {
      "type": "datetime",
    },
    "expire_time": {
      "type": "string",
    },
    "production_year": {
      "type": "integer",
    }
  },
  "required": ["title", "categories", "uri", "available_time"],
}

Beispiel für ein JSON-`Document`-Objekt

Das folgende Beispiel zeigt ein JSON-Document-Objekt.

{
  "title": "Test document title",
  "description": "Test document description",
  "media_type": "sports-game",
  "in_languages": [
    "en-US"
  ],
  "language_code": "en-US",
  "categories": [
    "sports > clip",
    "sports > highlight"
  ],
  "uri": "http://www.example.com",
  "images": [
    {
      "uri": "http://example.com/img1",
      "name": "image_1"
    }
  ],
  "country_of_origin": "US",
  "content_index": 0,
  "persons": [
    {
      "name": "sports person",
      "role": "player",
      "rank": 0,
      "uri": "http://example.com/person"
    },
  ],
  "organizations": [
    {
      "name": "sports team",
      "role": "team",
      "rank": 0,
      "uri": "http://example.com/team"
    },
  ],
  "hash_tags": [
    "tag1"
  ],
  "filter_tags": [
    "filter_tag"
  ],
  "duration": "100s",
  "production_year": 1900,
  "content_rating": [
    "PG-13"
  ],
  "aggregate_ratings": [
    {
      "rating_source": "imdb",
      "rating_score": 4.5,
      "rating_count": 1250
    }
  ],
  "available_time": "2022-08-26T23:00:17Z"
}

Dokumentfelder

In diesem Abschnitt sind die Feldwerte aufgeführt, die Sie angeben, wenn Sie Dokumente für Ihren Datenspeicher erstellen. Die Werte sollten den Werten entsprechen, die in Ihrer internen Dokumentendatenbank verwendet werden. Außerdem sollten sie das dargestellte Element genau widerspiegeln.

`Document`-Objektfelder

Die folgenden Felder sind übergeordnete Felder für das Document-Objekt. Weitere Informationen zu diesen Feldern finden Sie auf der Document-Referenzseite.

Feld	Hinweise
`name`	Der vollständige, eindeutige Ressourcenname des Dokuments. Erforderlich für alle `Document`-Methoden mit Ausnahme von `create` und `import`. Während des Imports wird der Name automatisch generiert und muss nicht manuell angegeben werden.
`id`	Die Dokument-ID, die von Ihrer internen Datenbank verwendet wird. Das ID-Feld muss in Ihrem gesamten Datenspeicher eindeutig sein. Derselbe Wert wird beim Aufzeichnen eines Nutzerereignisses verwendet und auch von den Methoden `recommend` und `search` zurückgegeben.
`schemaId`	Erforderlich. Die Kennung des Schemas im selben Datenspeicher. Muss auf „default_schema“ festgelegt werden, das automatisch beim Erstellen des Standarddatenspeichers erstellt wird.
`parentDocumentId`	Die ID des übergeordneten Dokuments. Bei Dokumenten der obersten Ebene (Stammdokumenten) kann `parent_document_id` leer sein oder auf sich selbst verweisen. Bei untergeordneten Dokumenten sollte `parent_document_id` auf ein gültiges Stammdokument verweisen.

Haupteigenschaften

Die folgenden Properties werden mit dem vordefinierten JSON-Schemaformat für Medien definiert.

Weitere Informationen zu JSON-Properties finden Sie in der Dokumentation zu JSON-Schemas unter json-schema.org im Abschnitt Properties.

In der folgenden Tabelle werden flache Schlüsseleigenschaften definiert.

Feldname	Hinweise
`title`	String – erforderlich Dokumenttitel aus Ihrer Datenbank. Ein UTF-8-codierter String. Er ist auf maximal 1.000 Zeichen beschränkt.
`categories`	String – erforderlich Dokumentkategorien Diese Property wird wiederholt, um ein Dokument zu unterstützen, das zu mehreren parallelen Kategorien gehört. Verwenden Sie den vollständigen Pfad zur Kategorie, um bessere Ergebnisse zu erzielen. Verwenden Sie das Symbol `>`, um Hierarchien zu trennen und den vollständigen Pfad einer Kategorie darzustellen. Wenn `>` Teil des Kategorienamens ist, ersetzen Sie es durch ein anderes Zeichen. Beispiel: `"categories": [ "sports > highlight" ]` Ein Dokument kann maximal 250 Kategorien enthalten. Jede Kategorie ist ein UTF-8-codierter String mit einer maximalen Länge von 5.000 Zeichen.
`uri`	String – erforderlich URI des Dokuments. Die Länge ist auf 5.000 Zeichen begrenzt.
`description`	String – dringend empfohlen Beschreibung des Dokuments. Die Länge ist auf 5.000 Zeichen begrenzt.
`media_type`	String – dieses Feld ist für Filme und Serien erforderlich Kategorie der obersten Ebene. Unterstützte Typen: `movie`, `show`, `concert`, `event`, `live-event`, `broadcast`, `tv-series`, `episode`, `video-game`, `clip`, `vlog`, `audio`, `audio-book`, `music`, `album`, `articles`, `news`, `radio`, `podcast`, `book` und `sports-game`. Die Werte `movie` und `show` haben eine besondere Bedeutung. Sie sorgen dafür, dass Dokumente so angereichert werden, dass das Ranking verbessert wird und Nutzer bei Titelsuchen alternative Inhalte finden, die für sie interessant sein könnten.
`language_code`	String – optional Sprache des Titels/der Beschreibung und anderer Stringattribute. Verwenden Sie Sprachentags, die gemäß BCP 47 definiert sind. Bei der Dokumentenrecommendation wird dieses Feld ignoriert und die Textsprache wird automatisch erkannt. Das Dokument kann Text in verschiedenen Sprachen enthalten. Das Duplizieren von Dokumenten, um Text in mehreren Sprachen bereitzustellen, kann jedoch zu einer Leistungsminderung führen. Dieses Feld wird für die Dokumentensuche verwendet. Wenn dieser Wert nicht festgelegt ist, wird standardmäßig „en-US“ verwendet. Beispiel: `"language_code": "en-US"`.
`duration`	String – erforderlich für Anwendungen für Medienempfehlungen, bei denen das Geschäftsziel die Klickrate (Click-through-Rate, CTR) oder die Wiedergabedauer pro Sitzung ist. Dauer der Medieninhalte. Die Dauer sollte als String codiert sein. Die Codierung muss der JSON-Stringcodierung von `google::protobuf::Duration` entsprechen. Beispiel: „5 s“, „1 Min.“
`available_time`	Datum/Uhrzeit – erforderlich Die Zeit, zu der die Inhalte für die Endnutzer verfügbar sind. Dieses Feld gibt die Aktualität von Inhalten für Endnutzer an. Der Zeitstempel muss dem RFC 3339-Standard entsprechen. Beispiel: `"2022-08-26T23:00:17Z"`
`expire_time`	String – optional Der Zeitpunkt, zu dem die Inhalte für die Endnutzer ablaufen. Dieses Feld gibt die Aktualität von Inhalten für Endnutzer an. Der Zeitstempel muss dem RFC 3339-Standard entsprechen. Beispiel: `"2032-12-31T23:00:17Z"`
`in_languages`	String – optional – wiederholbar Sprache der Medieninhalte. Verwenden Sie Sprachentags, die gemäß BCP 47 definiert sind. Beispiel: `"in_languages": [ "en-US"]`
`country_of_origin`	String – optional Herkunftsland des Mediendokuments. Die maximale Länge beträgt 128 Zeichen. Beispiel: `"country_of_origin": "US"`
`content_index`	Int – optional Inhaltsindex des Mediendokuments. Mit dem Inhaltsindexfeld können Sie die Dokumente in Bezug auf andere sortieren. Als Inhaltsindex kann beispielsweise die Folgennummer verwendet werden. Der Inhaltsindex muss eine nicht negative Ganzzahl sein. Beispiel: `"content_index": 0`
`filter_tags`	String – optional – wiederholbar Tags für das Dokument filtern Pro Dokument sind maximal 250 Werte mit einer Länge von maximal 1.000 Zeichen zulässig. Andernfalls wird der Fehler INVALID_ARGUMENT zurückgegeben. Dieses Tag kann zum Filtern von Empfehlungsergebnissen verwendet werden, indem es als Teil von `RecommendRequest.filter` übergeben wird. Beispiel: `"filter_tags": [ "filter_tag"]`
`hash_tags`	String – optional – wiederholbar Hashtags für das Dokument. Pro Dokument sind maximal 100 Werte mit einer Länge von maximal 5.000 Zeichen zulässig. Beispiel: `"hash_tags": [ "soccer", "world cup"]`
`content_rating`	String – optional – wiederholbar Die Altersfreigabe, die für Inhaltswarnsysteme und die inhaltsbasierte Filterung verwendet wird. Pro Dokument sind maximal 100 Werte mit einer Länge von maximal 128 Zeichen zulässig. Dieses Tag kann zum Filtern von Empfehlungsergebnissen verwendet werden, indem es als Teil von `RecommendRequest.filter` übergeben wird. Beispiel: `content_rating: ["PG-13"]`

In der folgenden Tabelle sind hierarchische Schlüsseleigenschaften definiert.

Feldname	Hinweise
`images`	Objekt – optional – wiederholt Stammschlüsseleigenschaft zum Kapseln von bildbezogenen Properties.
`images.uri`	String – optional URI des Bildes. Die Länge ist auf 5.000 Zeichen beschränkt.
`images.name`	String – optional Name des Bilds. Die maximale Länge beträgt 128 Zeichen.
`persons`	Objekt – optional – wiederholt Stammschlüssel-Property zum Kapseln der personenbezogenen Properties. Beispiele: `"persons":[{"name":"sports person","role":"player","rank":0,"uri":"http://example.com/person"}]`
`persons.name`	String – erforderlich Name der Person.
`persons.role`	String – erforderlich Die Rolle der Person im Medienelement. Unterstützte Werte: director, actor, player, team, league, editor, author, character, contributor, creator, editor, funder, producer, provider, publisher, sponsor, translator, music-by, channel, custom-role Wenn keiner der unterstützten Werte auf `role` angewendet wird, setzen Sie `role` auf `custom-role` und geben Sie den Wert im Feld `custom_role` an.
`persons.custom_role`	String – optional `custom_role` ist nur dann festgelegt, wenn `role` auf `custom-role` gesetzt ist. Muss ein UTF-8-codierter String mit einer Länge von maximal 128 Zeichen sein. Muss mit dem folgenden Muster übereinstimmen: `[a-zA-Z0-9][a-zA-Z0-9_]*`.
`persons.rank`	Int – optional Wird für das Rollenranking verwendet. Beispiel für den ersten Schauspieler: `role = "actor", rank = 1`
`persons.uri`	String – optional URI der Person.
`organizations`	Objekt – optional – wiederholt Stammschlüssel-Property zum Kapseln der `organization`-bezogenen Properties. Beispiele: `"organizations ":[{"name":"sports team","role":"team","rank":0,"uri":"http://example.com/team"}]`
`organizations.name`	String – erforderlich Name der Organisation.
`organizations.role`	String – erforderlich Die Rolle der Organisation im Medienelement. Unterstützte Werte: director, actor, player, team, league, editor, author, character, contributor, creator, editor, funder, producer, provider, publisher, sponsor, translator, music-by, channel, custom-role Wenn keiner der unterstützten Werte auf `role` angewendet wird, setzen Sie `role` auf `custom-role` und geben Sie den Wert im Feld `custom_role` an.
`organizations.custom_role`	String – optional `custom_role` ist nur dann festgelegt, wenn `role` auf `custom-role` gesetzt ist. Muss ein UTF-8-codierter String mit einer Länge von maximal 128 Zeichen sein. Muss mit dem folgenden Muster übereinstimmen: `[a-zA-Z0-9][a-zA-Z0-9_]*`.
`organizations.rank`	String – optional Wird für das Rollenranking verwendet. Beispiel für den ersten Publisher: `role = "publisher", rank = 1`.
`organizations.uri`	String – optional URI der Organisation.
`aggregate_ratings`	Objekt – optional – wiederholt Stammschlüsseleigenschaft zum Kapseln der `aggregate_rating`-bezogenen Properties.
`aggregate_ratings.rating_source`	String – erforderlich Die Quelle der Altersfreigabe. Beispiel: `imdb` oder `rotten_tomatoes`. Muss ein UTF-8-codierter String mit einer maximalen Länge von 128 Zeichen sein. Muss mit dem folgenden Muster übereinstimmen: `[a-zA-Z0-9][a-zA-Z0-9_]*`.
`aggregate_ratings.rating_score`	Doppelt – optional Die Gesamtbewertung. Die Bewertung sollte auf den Bereich [1, 5] normalisiert sein.
`aggregate_ratings.rating_count`	Int – optional Die Anzahl der einzelnen Rezensionen. Muss ein nicht negativer Wert sein.

Dokumentebenen

Dokumentebenen bestimmen die Hierarchie in Ihrem Datenspeicher. Normalerweise sollten Sie einen Datenspeicher auf einer oder zwei Ebenen haben. Es werden nur zwei Ebenen unterstützt.

Sie können beispielsweise einen Datenspeicher auf einer Ebene haben, in dem jedes Dokument ein einzelnes Element ist. Alternativ können Sie einen zweistufigen Datenspeicher auswählen, der sowohl Artikelgruppen als auch einzelne Artikel enthält.

Typen auf Dokumentebene

Es gibt zwei Arten von Dokumentebenen:

Eltern Übergeordnete Dokumente werden von Vertex AI Search in Empfehlungen und Suchanfragen zurückgegeben. Als übergeordnete Dokumente können einzelne Dokumente oder Gruppen ähnlicher Dokumente verwendet werden. Dieser Ebenentyp wird empfohlen.
Kind Untergeordnete Dokumente sind Versionen des übergeordneten Dokuments einer Gruppe. Untergeordnete Dokumente können nur einzelne Dokumente sein. Wenn das übergeordnete Dokument beispielsweise „Beispiel-TV-Sendung“ lautet, könnten die untergeordneten Elemente „Folge 1“ und „Folge 2“ sein. Dieser Ebenentyp kann schwierig zu konfigurieren und zu verwalten sein und wird daher nicht empfohlen.

Datenspeicherhierarchie

Entscheiden Sie bei der Planung der Datenspeicherhierarchie, ob Ihr Datenspeicher nur übergeordnete oder übergeordnete und untergeordnete Elemente enthalten soll. Wichtig ist, dass bei Empfehlungen und Suchanfragen nur übergeordnete Dokumente zurückgegeben werden.

Ein Datenspeicher, der nur für Eltern zugänglich ist, eignet sich beispielsweise gut für Hörbücher, bei denen ein Empfehlungsbereich eine Auswahl einzelner Hörbücher zurückgibt. Wenn du hingegen Folgen einer Serie als übergeordnete Dokumente in einen Datenspeicher hochgeladen hast, der nur übergeordnete Elemente enthält, werden dir im selben Bereich möglicherweise mehrere Folgen in der falschen Reihenfolge empfohlen.

Ein Datenspeicher für Serien kann sowohl über übergeordnete als auch untergeordnete Elemente verfügen. Dabei steht jedes übergeordnete Dokument für eine Serie mit untergeordneten Dokumenten, die die Folgen dieser Serie darstellen. Mit diesem zweistufigen Datenspeicher kann in der Empfehlungsübersicht eine Reihe ähnlicher Serien angezeigt werden. Der Endnutzer kann auf eine bestimmte Sendung klicken, um eine Folge auszuwählen.

Da Eltern-Kind-Hierarchien schwierig zu konfigurieren und zu verwalten sind, werden Datenspeicher nur mit übergeordneten Elementen empfohlen.

Ein Datenspeicher für Serien eignet sich beispielsweise gut als Datenspeicher nur für übergeordnete Elemente, bei dem jedes übergeordnete Dokument eine Serie darstellt, die empfohlen werden kann. Einzelne Folgen sind nicht enthalten und werden daher nicht empfohlen.

Wenn Sie feststellen, dass Ihr Datenspeicher sowohl übergeordnete als auch untergeordnete Elemente, also Gruppen und einzelne Elemente, haben muss, Sie aber derzeit nur einzelne Elemente haben, müssen Sie übergeordnete Elemente für die Gruppen erstellen. Sie müssen mindestens id, title und categories angeben. Weitere Informationen finden Sie im Abschnitt Dokumentfelder.

BigQuery-Schema für Medien

Wenn Sie Ihre Dokumente aus BigQuery importieren möchten, verwenden Sie das vordefinierte BigQuery-Schema, um eine BigQuery-Tabelle mit dem richtigen Format zu erstellen und mit Ihren Dokumentendaten zu laden, bevor Sie Ihre Dokumente importieren.

[
  {
    "name": "id",
    "mode": "REQUIRED",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "schemaId",
    "mode": "REQUIRED",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "parentDocumentId",
    "mode": "NULLABLE",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "jsonData",
    "mode": "NULLABLE",
    "type": "STRING",
    "fields": []
  }
]