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 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.

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 (versión preliminar pública):

    {"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 (versión preliminar pública):

    {"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?