Format und Struktur von Eingabedaten

Wenn Sie einen neuen Index erstellen oder einen vorhandenen Index aktualisieren möchten, stellen Sie Vektoren für die Vektorsuche in dem Format und der Struktur zur Verfügung, die in den folgenden Abschnitten beschrieben werden.

Eingabedatenspeicher und Dateiorganisation

Vorbereitung

Speichern Sie Ihre Eingabedaten in einem Cloud Storage-Bucket in Ihrem Google Cloud-Projekt.

Eingabedatendateien sollten so organisiert sein:

  • Jeder Batch von Eingabedatendateien sollte sich in einem einzigen Cloud Storage-Verzeichnis befinden.
  • Datendateien sollten direkt unter batch_root platziert und mit den folgenden Suffixen benannt werden: .csv, .json, .avro.
  • Das Batchstammverzeichnis darf maximal 5.000 Objekte (Dateien) enthalten.
  • Jede Datendatei wird als Sammlung von Datensätzen interpretiert. Das Format des Datensatzes wird durch das Suffix des Dateinamens bestimmt. Die entsprechenden Formatanforderungen werden unten beschrieben. Weitere Informationen finden Sie unter Dateiformate für Daten.
  • Jeder Datensatz sollte eine id, einen Featurevektor und Ihre optionalen Felder enthalten, die von Vertex AI Feature Store unterstützt werden, z. B. Einschränkungen und Mengenbeschränkungen.
  • Ein Unterverzeichnis namens delete kann vorhanden sein. Jede Datei direkt unter batch_root/delete wird als Textdatei mit id-Datensätzen mit einer id in jeder Zeile betrachtet.
  • Alle anderen Unterverzeichnisse sind nicht zulässig.

Eingabedatenverarbeitung

  • Alle Datensätze aus allen Datendateien, einschließlich der Datensätze unter delete, enthalten einen einzelnen Eingabe-Batch.
  • Die Reihenfolge der Datensätze innerhalb einer Datendatei ist nicht wichtig.
  • Eine einzelne ID sollte nur einmal in einem Batch vorkommen. Wenn dieselbe ID doppelt vorhanden ist, wird dies als ein einziger Vektor gezählt.
  • Eine ID darf nicht gleichzeitig in einer regulären Datendatei und in einer delete-Datendatei enthalten sein.
  • Alle IDs aus einer Datendatei unter „delete“ führen dazu, dass sie aus der nächsten Indexversion entfernt werden.
  • Datensätze aus regulären Datendateien werden in die nächste Version aufgenommen, wobei ein Wert in einer älteren Indexversion überschrieben wird.

Die folgenden Beispiele zeigen dichte, dünne und hybride Einbettungen:

  • Vollbesetzte Einbettungen:

    {"id": "1", "embedding": [1,1,1]}
{"id": "2", "embedding": [2,2,2]}

  • Dünnbesetzte Einbettungen (öffentliche Vorschau):

    {"id": "3", "sparse_embedding": {"values": [0.1, 0.2], "dimensions": [1, 4]}}
{"id": "4", "sparse_embedding": {"values": [-0.4, 0.2, -1.3], "dimensions": [10, 20, 20]}}

  • Hybride Einbettungen (öffentliche Vorschau):

    {"id": "5", "embedding": [5, 5, -5], "sparse_embedding": {"values": [0.1], "dimensions": [500]}}
{"id": "6", "embedding": [6, 7, -8.1], "sparse_embedding": {"values": [0.1, -0.2], "dimensions": [40, 901]}}

Das folgende Beispiel zeigt eine gültige Organisation einer Eingabedatendatei:

batch_root/
  feature_file_1.csv
  feature_file_2.csv
  delete/
    delete_file.txt

Die Dateien feature_file_1.csv und feature_file_2.csv enthalten Datensätze im -Format. Die Datei delete_file.txt enthält eine Liste von Datensatz-IDs, die aus der nächsten Indexversion gelöscht werden sollen.

Datendateiformate

JSON

  • Codieren Sie die Datei mit UTF-8.
  • Jede Zeile der JSON-Datei wird als separates JSON-Objekt interpretiert.
  • Jeder Eintrag muss ein id-Feld enthalten, um die ID des Vektors anzugeben.
  • Jeder Eintrag muss mindestens embedding oder sparse_embedding enthalten.
  • Das Feld embedding ist ein Array von N Gleitkommazahlen, das den Featurevektor darstellt. N ist die Dimension des Featurevektors, die beim Erstellen des Index konfiguriert wurde. Dieses Feld kann nur für dichte Einbettungen verwendet werden.
    • configs.dimensions, das bei der Indexerstellung angegeben wird, muss dieselbe Länge wie embeddings haben. configs.dimensions gilt nur für embedding, nicht für sparse_embedding.
  • Das Feld sparse_embedding ist ein Objekt mit den Feldern values und dimensions. Das Feld values ist eine Liste von Gleitkommazahlen, die den Featurevektor darstellen, und das Feld dimensions ist eine Liste von Ganzzahlen, die die Dimension darstellen, in der sich der entsprechende Wert befindet. Beispielsweise kann eine sparse Einbettung, die wie [0,0.1,0,0,0.2] aussieht, als "sparse_embedding": {"values": [0.1, 0.2], "dimensions": [1,4]} dargestellt werden. Dieses Feld kann nur für spärliche Einbettungen verwendet werden.
    • Die Länge von sparse_embedding.values muss der von sparse_embedding.dimensions entsprechen. Sie müssen nicht dieselbe Länge wie configs.dimensions haben, die beim Erstellen des Index angegeben wird und nicht für sparse_embedding gilt.
  • Ein optionales restricts-Feld kann eingeschlossen werden, das ein Array von TokenNamespace-Objekten in Einschränkungen angibt. Für jedes Objekt:
    • Geben Sie ein namespace-Feld an, das das TokenNamespace.namespace ist.
    • Ein optionales allow-Feld kann auf ein Array von Strings gesetzt werden, das die Liste von TokenNamespace.string_tokens ist.
    • Ein optionales deny-Feld kann auf ein Array von Strings gesetzt werden, das die Liste von TokenNamespace.string_blacklist_tokens ist.
    • Der Wert des Felds crowding_tag, falls vorhanden, sollte ein String sein.
  • Ein optionales numeric_restricts-Feld kann enthalten werden, das ein Array von NumericRestrictNamespace angibt. Für jedes Objekt:
    • Geben Sie ein namespace-Feld an, das das NumericRestrictNamespace.namespace ist.
    • Eines der Wertfelder value_int, value_float und value_double.
    • Es darf kein Feld mit dem Namen "op" enthalten. Dieses Feld ist nur für Abfragen vorgesehen.

Avro

  • Verwenden Sie eine gültige Avro-Datei.
  • Wenn Sie einen nur aus wenigen Datenpunkten bestehenden Datenpunkt darstellen möchten, geben Sie im Feld sparse_embedding eine sparse Einbettung und im Feld embedding eine leere Liste ein.

  • Erstellen Sie Datensätze, die dem folgenden Schema entsprechen:

    {
  "type": "record",
  "name": "FeatureVector",
  "fields": [
    {
      "name": "id",
      "type": "string"
    },
    {
      "name": "embedding",
      "type": {
        "type": "array",
        "items": "float"
      }
    },
    {
      "name": "sparse_embedding",
      "type": [
        "null",
        {
          "type": "record",
          "name": "sparse_embedding",
          "fields": [
            {
              "name": "values",
              "type": {
                "type": "array",
                "items": "float"
              }
            },
            {
              "name": "dimensions",
              "type": {
                "type": "array",
                "items": "long"
              }
            }
          ]
        }
      ]
    },
    {
      "name": "restricts",
      "type": [
        "null",
        {
          "type": "array",
          "items": {
            "type": "record",
            "name": "Restrict",
            "fields": [
              {
                "name": "namespace",
                "type": "string"
              },
              {
                "name": "allow",
                "type": [
                  "null",
                  {
                    "type": "array",
                    "items": "string"
                  }
                ]
              },
              {
                "name": "deny",
                "type": [
                  "null",
                  {
                    "type": "array",
                    "items": "string"
                  }
                ]
              }
            ]
          }
        }
      ]
    },
    {
      "name": "numeric_restricts",
      "type": [
        "null",
        {
          "type": "array",
          "items": {
            "name": "NumericRestrict",
            "type": "record",
            "fields": [
              {
                "name": "namespace",
                "type": "string"
              },
              {
                "name": "value_int",
                "type": [ "null", "int" ],
                "default": null
              },
              {
                "name": "value_float",
                "type": [ "null", "float" ],
                "default": null
              },
              {
                "name": "value_double",
                "type": [ "null", "double" ],
                "default": null
              }
            ]
          }
        }
      ],
      "default": null
    },
    {
      "name": "crowding_tag",
      "type": [
        "null",
        "string"
      ]
    }
  ]
}

CSV

  • Format: ID,N feature vector values,Any number of dimension:value sparse values,name=value lists
  • Codieren Sie die Datei mit UTF-8.
  • Jede Zeile der CSV-Datei muss genau einen Datensatz enthalten.
  • Der erste Wert in jeder Zeile muss die Vektor-ID sein, die ein gültiger UTF-8-String sein muss.
  • Nach der ID muss mindestens eine der Optionen „Dense Embedding“ (Vollbesetzte Einbettung) oder „Sparse Embedding“ (Dünnbesetzte Einbettung) angegeben werden.
  • Bei einer dichten Einbettung stellen die nächsten N Werte den Featurevektor dar, wobei N die Dimension des Featurevektors ist, der beim Erstellen des Index konfiguriert wurde.
  • Für eine sparse Einbettung kann eine beliebige Anzahl von dimension:value angegeben werden, wobei value als Float und dimension als long geparst wird.
  • Bei einer Hybrid-Einbettung mit sowohl dichten als auch dünn besetzten Einbettungen müssen die dichten Einbettungen vor den dünn besetzten Einbettungen angegeben werden.
  • Featurevektorwerte müssen Gleitkommaliterale sein, wie in der Java-Sprachspezifikation definiert.
  • Zusätzliche Werte können das Format name=value haben.
  • Der Name crowding_tag wird als Crowding-Tag interpretiert und darf nur einmal im Datensatz vorkommen.

  • Alle anderen name=value-Paare werden als Namespace-Einschränkungen interpretiert. Derselbe Name kann wiederholt werden, wenn ein Namespace mehrere Werte enthält.

    Beispielsweise steht color=red,color=blue für diesen TokenNamespace:

    {
  "namespace": "color"
  "string_tokens": ["red", "blue"]
}

  • Wenn der Wert mit ! beginnt, wird der Rest des Strings als ausgeschlossener Wert interpretiert.

    Beispielsweise steht color=!red für diesen TokenNamespace:

    {
  "namespace": "color"
  "string_blacklist_tokens": ["red"]
}

  • #name=numericValue-Paare mit Zahlentyp-Suffix werden als numerische Namespace-Einschränkungen interpretiert. Das Zahlentypsuffix ist i für Ganzzahl, f für Gleitkommazahl und d für Double. Derselbe Name sollte nicht wiederholt werden, da jedem Namespace ein einzelner Wert zugeordnet sein sollte.

    Beispielsweise steht #size=3i für diesen NumericRestrictNamespace:

    {
  "namespace": "size"
  "value_int": 3
}

    #ratio=0.1f steht für diese NumericRestrictNamespace:

    {
  "namespace": "ratio"
  "value_float": 0.1
}

    #weight=0.3d steht für diese NumericRestriction:

    {
  "namespace": "weight"
  "value_double": 0.3
}

  • Das folgende Beispiel ist ein Datenpunkt mit id: "6", embedding: [7, -8.1], sparse_embedding: {values: [0.1, -0.2, 0.5], dimensions: [40, 901, 1111]}}, dem Crowding-Tag test, der Token-Zulassungsliste color: red, blue, der Token-Sperrliste color: purple und der numerischen Einschränkung ratio mit dem Gleitkommawert 0.1:

    6,7,-8.1,40:0.1,901:-0.2,1111:0.5,crowding_tag=test,color=red,color=blue,color=!purple,ratio=0.1f

Nächste Schritte