Formato e struttura dei dati di input

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

Prerequisiti

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

I file di dati di input devono essere organizzati nel seguente modo:

  • Ogni batch di file di dati di input deve trovarsi in una singola directory Cloud Storage.
  • I file di dati devono essere posizionati direttamente sotto batch_root e denominati con i seguenti suffissi: .csv, .json e .avro.
  • La directory principale del batch può contenere al massimo 5000 oggetti (file).
  • Ogni file di dati viene interpretato come un insieme di record. Il formato del record è determinato 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 tuoi campi facoltativi supportati da Vertex AI Feature Store, come restrizioni e affollamento.
  • Potrebbe essere presente una sottodirectory denominata delete. Ogni file direttamente sotto batch_root/delete viene considerato un file di testo di id record con un id in ogni riga.
  • Tutte le altre sottodirectory non sono consentite.
  • La transcodifica dei file compressi con gzip non è supportata come dati di input.

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 essere visualizzato una sola volta in un batch. Se esiste un duplicato con lo stesso ID, viene visualizzato come un conteggio di un vettore.
  • Un ID non può essere presente sia in un file di dati normale sia in un file di dati di eliminazione.
  • Tutti gli ID di un file di dati in eliminazione vengono rimossi dalla versione successiva dell'indice.
  • I record dei file di dati regolari sono 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:

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

  • Embedding ibridi:

    {"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 del 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 successiva dell'indice.

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 uno dei valori embedding o sparse_embedding.
  • Il campo embedding è un array di numeri in virgola mobile N che rappresenta il vettore delle caratteristiche, dove N è la dimensione del vettore delle caratteristiche configurato al momento della creazione dell'indice. Questo campo può essere utilizzato solo per gli incorporamenti densi.
    • configs.dimensions, 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 i campi values e dimensions. Il campo values è un elenco di numeri in virgola mobile che rappresenta il vettore delle caratteristiche, mentre il campo dimensions è un elenco di numeri interi che rappresentano la dimensione in cui si trova il valore corrispondente. Ad esempio, un embedding 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_embedding.values deve essere uguale a quella di sparse_embedding.dimensions. Non devono avere la stessa lunghezza di configs.dimensions, che è specificato al momento della creazione dell'indice e non si applica a sparse_embedding.
  • Può essere incluso un campo restricts facoltativo che specifica un array di oggetti TokenNamespace in restricts. Per ogni oggetto:
    • Specifica un campo namespace che sia TokenNamespace.namespace.
    • Un campo allow facoltativo può essere impostato su un array di stringhe che corrispondono all'elenco di TokenNamespace.string_tokens.
    • Un campo deny facoltativo può essere impostato su un array di stringhe che corrispondono all'elenco di TokenNamespace.string_blacklist_tokens.
    • Il valore del campo crowding_tag, se presente, deve essere una stringa.
  • Può essere incluso 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 è solo per le 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, deve essere specificato almeno un tipo di embedding denso o sparso.
  • Per un incorporamento denso, i successivi N valori rappresentano il vettore delle caratteristiche, dove N è la dimensione del vettore delle caratteristiche configurata durante la creazione dell'indice.
  • Per un embedding sparso, è possibile specificare un numero qualsiasi di dimension:value, in cui value viene analizzato come un numero in virgola mobile e dimension viene analizzato come long.
  • Per un embedding ibrido che contiene embedding densi e sparsi, gli embedding densi devono essere specificati prima degli embedding sparsi.
  • I valori del vettore delle caratteristiche devono essere valori letterali in virgola mobile come definiti 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 una sola 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 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 di tipo numerico vengono interpretate come limitazioni dello spazio dei nomi numerico. Il suffisso del tipo di numero è i per int, f per float e d per double. Lo stesso nome non deve essere ripetuto, in quanto deve 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 }

  • 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 affollamento test, lista consentita di token color: red, blue, lista bloccata di token color: purple e limite numerico ratio con valore float 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