Formato e struttura dei dati di input

Per creare un nuovo indice o aggiornare un indice 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 è determinato dal suffisso del nome file e tali requisiti di formato sono descritti. Consulta Formati di 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 direttamente in batch_root/delete viene considerato un file di testo di record id con un id per ogni riga.
  • Tutti gli altri file e directory 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 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 stato di eliminazione ne causano la rimozione dalla versione di indice successiva.
  • I record dei normali file di dati saranno inclusi nella versione successiva, sovrascrivendo un valore in una versione precedente dell'indice.

Di seguito sono riportati alcuni esempi di incorporamenti 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 valida di un file di dati di input:

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 record da eliminare 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 almeno uno dei seguenti valori: embedding o sparse_embedding.
  • Il campo embedding è un array di numeri in virgola mobile N che rappresenta il vettore di caratteristiche, dove N è la dimensione del vettore di caratteristiche configurato al momento della creazione dell'indice. Questo campo può essere utilizzato solo per gli incorporamenti densi.
    • configs.dimensions, che viene specificato al momento della creazione dell'indice, deve avere la stessa lunghezza di embeddings. configs.dimensions si applica solo a embedding, non a sparse_embedding.
  • Il campo sparse_embedding è un oggetto con campi values e dimensions. Il campo values è un elenco di numeri in virgola mobile che rappresentano il vettore di caratteristiche, mentre il campo dimensions è un elenco di numeri interi che rappresentano la dimensione in cui si trova il valore corrispondente. Ad esempio, un incorporamento sparso simile a [0,0.1,0,0,0.2] può essere rappresentato come "sparse_embedding": {"values": [0.1, 0.2], "dimensions": [1,4]}. Questo campo può essere utilizzato solo per gli incorporamenti sparsi.
    • La lunghezza di sparse_embeddings.values deve essere la stessa di sparse_embeddings.dimensions. Non devono essere della stessa durata di configs.dimensions, che viene specificato al momento della creazione dell'indice e non si applica a sparse_embeddings.
  • È possibile includere un campo restricts facoltativo che specifica un array di TokenNamespace oggetti nelle limitazioni. 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 costituiscono l'elenco di TokenNamespace.string_tokens.
    • Un campo deny facoltativo può essere impostato su un array di stringhe che costituiscono 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 sia 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 file Avro valido.
  • Per rappresentare un punto dati solo sparso, fornisci un incorporamento sparso nel campo 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, è necessario specificare almeno un incorporamento sparso o denso.
  • Per un incorporamento denso, i successivi valori N rappresentano il vettore di caratteristiche, dove N è la dimensione del vettore di caratteristiche configurato al momento della creazione dell'indice.
  • Per un incorporamento sparso, è possibile specificare qualsiasi numero di dimension:value, in cui value viene analizzato come numero in virgola mobile e dimension come long.
  • Per un incorporamento ibrido con incorporamenti sia densi che sparsi, gli incorporamenti densi devono essere specificati prima di quelli sparsi.
  • I valori dei vettori di caratteristiche devono essere valori letterali con virgola mobile come definito nelle specifiche del linguaggio Java.
  • I valori aggiuntivi potrebbero essere nel formato name=value.
  • Il nome crowding_tag viene interpretato come tag di crowding e può essere visualizzato una sola 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 sono presenti 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 un valore escluso.

    Ad esempio, color=!red rappresenta questo TokenNamespace:

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

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