Formato e struttura dei dati di input

Per creare un nuovo indice o aggiornarne uno esistente, fornisci vettori a Vector Search nel formato e nella struttura descritti nelle sezioni seguenti.

Archiviazione dei dati di input e organizzazione dei file

Prerequisito

Archivia i dati di input in un bucket Cloud Storage nel tuo progetto Google Cloud.

I file di dati di input devono essere organizzati come segue:

  • Ogni batch di file di dati di input deve trovarsi in un'unica directory Cloud Storage.
  • I file di dati devono essere posizionati direttamente sotto batch_root e denominati con i seguenti suffissi: .csv, .json e .avro.
  • Esiste un limite di 5000 oggetti (file) nella directory radice batch.
  • Ogni file di dati viene interpretato come un insieme di record. Il formato del record è determinati dal suffisso del nome file e i requisiti di formato sono descritti. Consulta Formati dei file di dati.
  • Ogni record deve avere un id, un vettore di caratteristiche e i campi facoltativi supportate da Vertex AI Feature Store, come limitazioni e crowding.
  • Potrebbe essere presente una sottodirectory denominata delete. Ogni file direttamente batch_root/delete viene considerato un file di testo di record id con un id in ogni riga.
  • Tutte le altre sottodirectory non sono consentite.

Elaborazione dei dati di input

  • Tutti i record di tutti i file di dati, inclusi quelli in delete, sono costituiti da un unico batch di input.
  • L'ordine relativo dei record all'interno di un file di dati non è importante.
  • Un singolo ID deve apparire una sola volta in un batch. Se esiste un duplicato con lo stesso ID, viene visualizzato come un conteggio vettoriale.
  • Un ID non può essere presente sia in un normale file di dati sia in un file di dati eliminato.
  • Tutti gli ID di un file di dati in fase di eliminazione ne causano la rimozione dal successivo dell'indice.
  • I record dei file di dati regolari vengono inclusi nella versione successiva, sovrascrivendo un valore in una versione dell'indice precedente.

Di seguito sono riportati alcuni esempi di embedding densi, sparsi e ibridi:

  • Incorporamenti densi:

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

  • Incorporamenti sparsi (anteprima pubblica):

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

  • Incorporamenti ibridi (anteprima pubblica):

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

Di seguito è riportato un esempio di organizzazione di un file di dati di input valido:

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

I file feature_file_1.csv e feature_file_2.csv contengono record in formato CSV formato. Il file delete_file.txt contiene un elenco di ID record da eliminare dalla versione dell'indice successiva.

Formati dei file di dati

JSON

  • Codifica il file JSON utilizzando UTF-8.
  • Ogni riga del file JSON verrà interpretata come un oggetto JSON separato.
  • Ogni record deve contenere un campo id per specificare l'ID del vettore.
  • Ogni record deve contenere almeno un valore embedding o sparse_embedding.
  • Il campo embedding è un array di N numeri in virgola mobile che rappresenta il vettore di caratteristiche, dove N è la dimensione del il vettore di caratteristiche configurato al momento della creazione dell'indice. Questo campo può essere utilizzato solo per gli embedding densi.
    • configs.dimensions, che viene specificato al momento della creazione dell'indice, deve essere della stessa lunghezza di embeddings. configs.dimensions si applica solo a embedding, non a sparse_embedding.
  • Il campo sparse_embedding è un oggetto con values e dimensions campi. Il campo values è un elenco di rappresentazione in virgola mobile numeri che rappresentano il vettore di caratteristiche e il campo dimensions è un elenco di numeri interi che rappresentano la dimensione in cui il valore corrispondente. Ad esempio, un incorporamento sparso che sembra che [0,0.1,0,0,0.2] possa essere rappresentato "sparse_embedding": {"values": [0.1, 0.2], "dimensions": [1,4]}. Questo può essere usato solo per gli incorporamenti sparsi.
  • È possibile includere un campo restricts facoltativo che specifica un array di TokenNamespace oggetti nelle limitazioni. Per ogni oggetto:
    • Specifica un campo namespace che sia il TokenNamespace.namespace.
    • Un campo facoltativo allow può essere impostato su un array di stringhe che rappresentano l'elenco di TokenNamespace.string_tokens.
    • Un campo deny facoltativo può essere impostato su un array di stringhe che l'elenco di TokenNamespace.string_blacklist_tokens.
    • Il valore del campo crowding_tag, se presente, deve essere una stringa.
  • È possibile includere un campo numeric_restricts facoltativo che specifica di NumericRestrictNamespace. Per ogni oggetto:
    • Specifica un campo namespace che corrisponda al NumericRestrictNamespace.namespace.
    • Uno dei campi valore value_int, value_float e value_double.
    • Non deve avere un campo denominato op. Questo campo è riservato solo alle query.

Avro

  • Utilizza un documento Avro valido .
  • Per rappresentare un punto dati solo sparso, fornire un incorporamento sparso nel sparse_embedding e inserisci un elenco vuoto nel campo embedding.

  • Crea record conformi allo schema seguente:

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

  • Formato: ID,N feature vector values,Any number of dimension:value sparse values,name=value lists
  • Codifica il file CSV utilizzando UTF-8.
  • Ogni riga del file CSV deve contenere esattamente un record.
  • Il primo valore di ogni riga deve essere l'ID vettore, che deve essere una stringa UTF-8 valida.
  • Dopo l'ID, deve essere specificato almeno un embedding denso o sparso.
  • Per un incorporamento denso, i successivi valori di N rappresentano il vettore di caratteristiche, dove N è la dimensione del vettore di caratteristiche configurato quando è stato creato l'indice.
  • Per un embedding sparso, è possibile specificare un numero qualsiasi di dimension:value, in cui value viene analizzato come valore in virgola mobile e dimension viene analizzato come long.
  • Per un incorporamento ibrido con incorporamenti sia densi che sparsi, i dati densi gli incorporamenti devono essere specificati prima degli incorporamenti sparsi.
  • I valori del vettore di funzionalità devono essere letterali a virgola mobile come definito nella specifica del linguaggio Java.
  • I valori aggiuntivi possono essere nel formato name=value.
  • Il nome crowding_tag viene interpretato come tag di affollamento e può comparire solo una volta nel record.

  • Tutte le altre coppie name=value sono interpretate come limitazioni dello spazio dei nomi dei token. Lo stesso nome può essere ripetuto se ci sono più valori in un nello spazio dei nomi.

    Ad esempio, color=red,color=blue rappresenta questo TokenNamespace:

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

  • Se il valore inizia con !, il resto della stringa viene interpretato come un escluso.

    Ad esempio, color=!red rappresenta questo TokenNamespace:

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

  • #name=numericValue coppia con suffisso del tipo numerico viene interpretata come limitazioni dello spazio dei nomi numerico. Il suffisso del tipo di numero è i per int, f per numero in virgola mobile e d per doppio. Lo stesso nome non deve essere ripetuto deve essere un singolo valore associato per ogni spazio dei nomi.

    Ad esempio, #size=3i rappresenta questo NumericRestrictNamespace:

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

    #ratio=0.1f rappresenta questo NumericRestrictNamespace:

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

    #weight=0.3d rappresenta questo NumericRestriction:

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

  • L'esempio seguente è un punto dati con id: "6", embedding: [7, -8.1], sparse_embedding: {values: [0.1, -0.2, 0.5], dimensions: [40, 901, 1111]}}, tag di crowding test, lista consentita di token di color: red, blue, lista bloccata di token di color: purple e limitazione numerica di ratio con numero in virgola mobile 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

Passaggi successivi