Formato e struttura dei dati di input

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

Prerequisiti

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

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 inseriti direttamente in batch_root e denominati con i seguenti suffissi: .csv, .json e .avro.
• Nella directory principale del batch è presente un limite di 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 campi facoltativi supportati da Gemini Enterprise Agent Platform Feature Store, come restricts 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 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 singolo batch di input.
• L'ordinamento 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 è presente un duplicato con lo stesso ID, viene visualizzato come un conteggio di vettori.
• 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 delete vengono rimossi dalla versione dell'indice successiva.
• I record dei file di dati normali sono inclusi nella versione successiva, sovrascrivendo un valore in una versione dell'indice precedente.

Di seguito sono riportati 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]}}
  

• Incorporamenti 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 dei 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 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 tra embedding o sparse_embedding.
• Il campo embedding è un array di N numeri con virgola mobile che rappresenta il vettore di caratteristiche, dove N è la dimensione del vettore di caratteristiche configurata 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 con virgola mobile che rappresenta il vettore di caratteristiche e il campo dimensions è un elenco di numeri interi che rappresenta la dimensione in cui si trova il valore corrispondente. Ad esempio, un incorporamento sparso che assomiglia 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 applicato a sparse_embedding.
• È possibile includere un campo restricts facoltativo che specifica un array di oggetti TokenNamespace in restricts. Per ogni oggetto:
  • Specifica un campo namespace che è il 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 è il 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 sparse_embedding campo e inserisci un elenco vuoto nel embedding campo.

• 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 del vettore, che deve essere una stringa UTF-8 valida.
• Dopo l'ID, deve essere specificato almeno un incorporamento denso o sparso.
• Per un incorporamento denso, i successivi N valori rappresentano il vettore di caratteristiche, dove N è la dimensione del vettore di caratteristiche configurata al momento della creazione dell'indice.
• Per un incorporamento sparso, è possibile specificare un numero qualsiasi di dimension:value, in cui value viene analizzato come float e dimension viene analizzato come long.
• Per un incorporamento ibrido con incorporamenti densi e sparsi, gli incorporamenti densi devono essere specificati prima degli incorporamenti sparsi.
• I valori del vettore di caratteristiche devono essere valori letterali con 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 il tag di affollamento e può essere visualizzato 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 restrizioni dello spazio dei nomi numerico. Il suffisso di tipo numerico è i per int, f per float e d per double. Lo stesso nome non deve essere ripetuto perché 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 questa 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, elenco consentiti di token color: red, blue, elenco non consentiti di token color: purple e restrizione numerica di ratio con 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

• Scopri come creare e gestire l'indice