Formato e struttura dei dati di input

Per creare un nuovo indice o aggiornare un indice esistente, fornisci i 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 una singola directory Cloud Storage.
  • I file di dati devono essere posizionati direttamente in batch_root e denominati con i seguenti suffissi: .csv, .json e .avro.
  • Esiste un limite di 5000 oggetti (file) nella directory radice del batch.
  • Ogni file di dati viene interpretato come un insieme di record. Il formato del record è determinato dal suffisso del nome file e vengono descritti i requisiti di formato. Consulta Formati file di dati.
  • Ogni record deve avere un id, un vettore di caratteristiche e i campi facoltativi supportati da Vertex AI Feature Store, come limitazioni e crowding.
  • Potrebbe essere presente una sottodirectory denominata delete. Ogni file che si trova direttamente in batch_root/delete viene preso come un file di testo di record id con un id per riga.
  • Tutte le altre directory e tutti gli altri file vengono ignorati.

Elaborazione dei dati di input

  • Tutti i record di tutti i file di dati, inclusi quelli in delete, sono costituiti da un singolo 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 un conteggio vettoriale.
  • Un ID non può essere visualizzato sia in un file di dati normale sia in un file di dati di eliminazione.
  • Tutti gli ID di un file di dati in fase di eliminazione ne comportano la rimozione dalla versione dell'indice successiva.
  • I record dei normali file di dati sono inclusi nella versione successiva, sovrascrivendo un valore in una versione precedente dell'indice.

Ecco un esempio JSON:

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

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

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. Il file delete_file.txt contiene un elenco di ID di record da eliminare a partire dalla versione dell'indice successiva.

Formati 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 un campo embedding ovvero un array di numeri in virgola mobile N che rappresentano il vettore di caratteristiche, dove N è la dimensione del vettore di caratteristiche configurato al momento della creazione dell'indice.
  • È possibile includere un campo restricts facoltativo che specifica un array di TokenNamespace oggetti nei limiti. Per ogni oggetto:
    • Specifica un campo namespace che corrisponda a TokenNamespace.namespace.
    • Un campo allow facoltativo può essere impostato su un array di stringhe che sono l'elenco di TokenNamespace.string_tokens.
    • Un campo deny facoltativo può essere impostato su un array di stringhe che sono 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 un array di NumericRestrictNamespace. Per ogni oggetto:
    • Specifica un campo namespace che corrisponde a NumericRestrictNamespace.namespace.
    • Uno dei campi di valore value_int, value_float e value_double.
    • Non deve contenere un campo denominato op. Questo campo è destinato esclusivamente alle query.

Avro

  • Utilizza un file Avro valido.

  • Crea record conformi al seguente schema:

    {
  "type": "record",
  "name": "FeatureVector",
  "fields": [
    {
      "name": "id",
      "type": "string"
    },
    {
      "name": "embedding",
      "type": {
        "type": "array",
        "items": "float"
      }
    },
    {
      "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

  • Codifica il file CSV utilizzando UTF-8.
  • Ogni riga del file CSV deve contenere esattamente un record.
  • Il primo valore in ogni riga deve essere l'ID vettore, che deve essere una stringa UTF-8 valida.
  • Dopo l'ID, i successivi valori N rappresentano il vettore di caratteristiche, dove N è la dimensione del vettore di caratteristiche configurato al momento della creazione dell'indice.
  • I valori dei vettori di caratteristiche devono essere valori letterali con virgola mobile, come definito nelle specifiche del linguaggio Java.
  • I valori aggiuntivi possono essere nel formato name=value.
  • Il nome crowding_tag viene interpretato come tag di crowding e può essere visualizzato solo una volta nel record.

  • Tutte le altre coppie name=value vengono interpretate come restrizioni dello spazio dei nomi dei token. Lo stesso nome può essere ripetuto se ci sono più valori in uno 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 valore escluso.

    Ad esempio, color=!red rappresenta questo TokenNamespace:

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

  • Le coppie #name=numericValue con suffisso di tipo numerico vengono interpretate come restrizioni dello spazio dei nomi numerico. Il suffisso del tipo numerico è i per int, f per float e d per doppio. Lo stesso nome non deve essere ripetuto poiché dovrebbe essere associato un singolo valore per 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
}

Passaggi successivi