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.

Almacenamiento de datos de entrada y organización de archivos

Requisitos

Almacena los datos de entrada en un bucket de Cloud Storage en tu proyecto de 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 se describen esos requisitos de formato. 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.

Los siguientes son ejemplos de incorporaciones densas, dispersas y 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 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 representan la dimensión en la que se encuentra el valor correspondiente. Por ejemplo, una incorporación dispersa que se parece a [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 dispersas.
    • 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 dato 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 una de las incorporaciones densas o dispersas.
  • 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.
  • Para 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.
  • Para una incorporación híbrida que tenga incorporaciones densas y dispersas, las incorporaciones densas deben especificarse antes que las dispersas.
  • 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?