Formato e struttura dei dati di input

Per creare un nuovo indice o aggiornarne uno esistente, fornisci vettori a ricerca vettoriale nel formato e nella struttura descritti in le 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 il 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 di 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.
  • 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'unica 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 normali file di dati saranno inclusi nella prossima versione, 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 formato. 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 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 può essere utilizzato solo per gli incorporamenti 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 per 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.
    • La lunghezza di sparse_embeddings.values deve essere uguale a sparse_embeddings.dimensions. Non devono essere della stessa lunghezza del 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 l'elenco di TokenNamespace.string_tokens.
    • Un campo deny facoltativo può essere impostato su un array di stringhe 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 un valore valido Stringa UTF-8.
  • Dopo l'ID, deve essere presente almeno un incorporamento sparso o denso che l'utente può specificare.
  • 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 incorporamento sparso, è possibile specificare qualsiasi numero di dimension:value, in cui value viene analizzato come numero 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 dei vettori di caratteristiche devono essere valori letterali in virgola mobile come definito nel 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 usato solo appaiono 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