Formato y estructura de los datos de entrada

Para compilar un índice nuevo o actualizar un índice existente, proporciona vectores a Vector Search con el formato y la estructura descritos en las siguientes secciones.

Requisitos previos

Almacena los datos de entrada en un bucket de Cloud Storage en tu proyecto Google Cloud .

Los archivos de datos de entrada deben organizarse de la siguiente manera:

• Cada lote de archivos de datos de entrada debe estar en un solo directorio de Cloud Storage.
• Los archivos de datos deben colocarse directamente en batch_root y se les debe asignar un nombre con los siguientes sufijos: .csv, .json y .avro.
• Existe un límite de 5,000 objetos (archivos) en el directorio raíz por lotes.
• Cada archivo de datos se interpreta como un conjunto de registros. El formato del registro se determina mediante el sufijo del nombre del archivo y esos requisitos de formato se describen a continuación. Consulta Formatos de archivos de datos.
• Cada registro debe tener un id, un vector de atributos y los campos opcionales compatibles con Vertex AI Feature Store, como las restricciones y la agrupamiento.
• Puede haber un subdirectorio llamado delete. Cada archivo que se encuentre directamente en batch_root/delete se toma como un archivo de texto de registros id con un id en cada línea.
• No se permiten otros subdirectorios.
• La transcodificación de archivos comprimidos en gzip no se admite como datos de entrada.

Procesamiento de datos de entrada

• Todos los registros de todos los archivos de datos, incluidos los de delete, constan de un solo lote de entrada.
• El orden relativo de los registros dentro de un archivo de datos no es importante.
• Un ID único debe aparecer una sola vez en un lote. Si hay un duplicado con el mismo ID, se muestra como un recuento de vectores.
• Un ID no puede aparecer en un archivo de datos regulares y en un archivo de datos "delete".
• Todos los ID de un archivo de datos en "delete" causan que se quiten de la próxima versión del índice.
• En la próxima versión, se incluyen los registros de archivos de datos regulares y se reemplazará un valor en una versión anterior del índice.

A continuación, se muestran ejemplos de las incorporaciones densas, dispersas e híbridas:

• Incorporaciones densas:

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

• Incorporaciones dispersas:

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

• Incorporaciones híbridas:

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

El siguiente es un ejemplo de una organización de archivo de datos de entrada válida:

batch_root/
  feature_file_1.csv
  feature_file_2.csv
  delete/
    delete_file.txt

Los archivos feature_file_1.csv y feature_file_2.csv contienen registros en formato CSV. El archivo delete_file.txt contiene una lista de IDs de registro que se borrarán de la siguiente versión del índice.

Formatos de archivo de datos

JSON

• Codifica el archivo JSON a través de UTF-8.
• Cada línea del archivo JSON se interpretará como un objeto JSON independiente.
• Cada registro debe contener un campo id para especificar el ID del vector.
• Cada registro debe contener al menos uno de los campos embedding o sparse_embedding.
• El campo embedding es un array de números de punto flotante N que representa el vector de atributos, en el que N es la dimensión del vector de atributos que se configuró cuando se creó el índice. Este campo solo se puede usar para embeddings densos.
  • configs.dimensions, que se especifica en el momento de la creación del índice, debe tener la misma longitud que embeddings. configs.dimensions solo se aplica a embedding, no a sparse_embedding.
• El campo sparse_embedding es un objeto con campos values y dimensions. El campo values es una lista de números de punto flotante que representa el vector de atributos, y el campo dimensions es una lista de números enteros que representa la dimensión en la que se encuentra el valor correspondiente. Por ejemplo, una incorporación dispersa que se ve como [0,0.1,0,0,0.2] se puede representar como "sparse_embedding": {"values": [0.1, 0.2], "dimensions": [1,4]}. Este campo solo se puede usar para embeddings dispersos.
  • La longitud de sparse_embedding.values debe ser la misma que la de sparse_embedding.dimensions. No es necesario que tengan la misma longitud que configs.dimensions, que se especifica en el momento de la creación del índice y no se aplica a sparse_embedding.
• Se puede incluir un campo restricts opcional que especifique un array de objetos TokenNamespace en restricciones. En cada objeto:
  • Especifica un campo namespace que sea el TokenNamespace.namespace.
  • Un campo opcional allow se puede establecer en un array de cadenas que sean la lista de TokenNamespace.string_tokens.
  • Un campo opcional deny se puede establecer en un array de cadenas que sean la lista de TokenNamespace.string_blacklist_tokens.
  • El valor del campo crowding_tag, si está presente, debe ser una cadena.
• Se puede incluir un campo numeric_restricts opcional que especifique un array de NumericRestrictNamespace. En cada objeto:
  • Especifica un campo namespace que sea el NumericRestrictNamespace.namespace.
  • Uno de los campos de valor value_int, value_float y value_double.
  • No debe tener un campo llamado op. Este campo solo se usa para consultas.

Avro

• Usa un archivo Avro válido.
• Para representar un punto de datos solo disperso, proporciona una incorporación dispersa en el campo sparse_embedding y, luego, ingresa una lista vacía en el campo embedding.

• Haz registros que se ajusten al siguiente esquema:

  {
    "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 el archivo CSV con UTF-8.
• Cada línea del archivo CSV debe contener exactamente un registro.
• El primer valor de cada línea debe ser el ID del vector, que debe ser una cadena UTF-8 válida.
• Después del ID, se debe especificar al menos un embedding denso o disperso.
• Para una incorporación densa, los siguientes valores N representan el vector de atributos, en el que N es la dimensión del vector de atributos que se configuró cuando se creó el índice.
• En el caso de una incorporación dispersa, se puede especificar cualquier cantidad de dimension:value, en la que value se analiza como un número de punto flotante y dimension se analiza como un long.
• En el caso de un embedding híbrido que tenga embeddings densos y dispersos, los embeddings densos deben especificarse antes que los dispersos.
• Los valores del vector de atributos deben ser literales de punto flotante como se define en las especificaciones del lenguaje Java.
• Los valores adicionales pueden tener el formato name=value.
• El nombre crowding_tag se interpreta como la etiqueta de agrupamiento y solo puede aparecer una vez en el registro.

• Todos los demás pares name=value se interpretan como restricciones de espacio de nombres del token. El mismo nombre se puede repetir si hay varios valores en un espacio de nombres.

  Por ejemplo, color=red,color=blue representa este TokenNamespace:

  {
    "namespace": "color"
    "string_tokens": ["red", "blue"]
  }
  

• Si el valor comienza con !, el resto de la cadena se interpreta como un valor excluido.

  Por ejemplo, color=!red representa este TokenNamespace:

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

• Los pares #name=numericValue con sufijo de tipo numérico se interpretan como restricciones numéricas del espacio de nombres. El sufijo del tipo numérico es i para int, f para número de punto flotante y d para doble. El mismo nombre no se debe repetir, ya que debe haber un solo valor asociado por espacio de nombres.

  Por ejemplo, #size=3i representa este NumericRestrictNamespace:

  {
    "namespace": "size"
    "value_int": 3
  }
  

  #ratio=0.1f representa este NumericRestrictNamespace:

  {
    "namespace": "ratio"
    "value_float": 0.1
  }
  

  #weight=0.3d representa este NumericRestriction:

  {
    "namespace": "weight"
    "value_double": 0.3
  }
  

• El siguiente ejemplo es un dato con id: "6", embedding: [7, -8.1], sparse_embedding: {values: [0.1, -0.2, 0.5], dimensions: [40, 901, 1111]}, etiqueta de agrupamiento test, lista de tokens permitidos de color: red, blue, lista de bloqueo de tokens de color: purple y restricción numérica de ratio con número de punto flotante 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
  

¿Qué sigue?

• Obtén más información sobre cómo crear y administrar tu índice.