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 el 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 esos requisitos de formato se describen. Consulta Formatos de archivo 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.
  • Se ignorarán todos los demás directorios y archivos.

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.

Este es un ejemplo de JSON:

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

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 un campo embedding que sea un array de números de punto flotante N que 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.
  • 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.

  • 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": "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

  • 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, 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.
  • 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
}

¿Qué sigue?