Estrutura e formato dos dados de entrada

Para criar um novo índice ou atualizar um existente, forneça vetores ao Vector Search no formato e na estrutura descritos nas seções a seguir.

Armazenamento de dados de entrada e organização de arquivos

Pré-requisitos

Armazene os dados de entrada em um bucket do Cloud Storage no projeto do Google Cloud.

Os arquivos de dados de entrada precisam ser organizados da seguinte maneira:

  • Cada lote de arquivos de dados de entrada precisa estar em um único diretório do Cloud Storage.
  • Os arquivos de dados precisam ser colocados diretamente em batch_root e nomeados com os seguintes sufixos: .csv, .json e .avro.
  • Há um limite de 5.000 objetos no diretório raiz do lote.
  • Cada arquivo de dados é interpretado como um conjunto de registros. O formato do registro é determinado pelo sufixo do nome do arquivo, e esses requisitos de formato são descritos. Consulte Formatos de arquivo de dados.
  • Cada registro precisa ter um id, um vetor de recurso e campos opcionais compatíveis com o Feature Store da Vertex AI, como restrições e distanciamento.
  • Um subdiretório chamado delete pode estar presente. Cada arquivo diretamente colocado em batch_root/delete é processado como um arquivo de texto de registros id com um id em cada linha.
  • Todos os outros diretórios e arquivos são ignorados.

Processamento de dados de entrada

  • Todos os registros de todos os arquivos de dados, incluindo aqueles em delete, consistem em um único lote de entrada.
  • A ordem relativa dos registros em um arquivo de dados não é importante.
  • Um único ID só deve aparecer uma vez em um lote. Se houver uma cópia com o mesmo ID, ela será mostrada como uma contagem de vetores.
  • Um ID não pode aparecer em um arquivo de dados normal e em um arquivo de dados de exclusão.
  • Todos os IDs de um arquivo de dados em exclusão fazem com que ele seja removido da próxima versão do índice.
  • Os registros de arquivos de dados regulares serão incluídos na próxima versão, possivelmente substituindo um valor em uma versão de índice mais antiga.

Veja um exemplo de JSON:

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

Veja a seguir um exemplo de organização válida de arquivos de dados de entrada:

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

Os arquivos feature_file_1.csv e feature_file_2.csv contêm registros no formato CSV. O arquivo delete_file.txt contém uma lista de IDs de registro a serem excluídos da próxima versão do índice.

Formatos de arquivo de dados

JSON

  • Codifique o arquivo JSON usando UTF-8.
  • Cada linha do arquivo JSON será interpretada como um objeto JSON separado.
  • Cada registro precisa conter um campo id para especificar o ID do vetor.
  • Cada registro precisa conter um campo embedding, que seja uma matriz de números de ponto flutuante N que representa o vetor de atributo, em que N é a dimensão do vetor de atributo que foi configurado quando o índice foi criado.
  • É possível incluir um campo restricts opcional para especificar uma matriz de objetos TokenNamespace em restrições. Para cada objeto:
    • Especifique um campo namespace que seja o TokenNamespace.namespace.
    • Um campo allow opcional pode ser definido como uma matriz de strings, que são a lista de TokenNamespace.string_tokens.
    • Um campo deny opcional pode ser definido como uma matriz de strings, que são a lista de TokenNamespace.string_blacklist_tokens.
    • O valor do campo crowding_tag, se presente, precisa ser uma string.
  • É possível incluir um campo numeric_restricts opcional que especifica uma matriz de NumericRestrictNamespace. Para cada objeto:
    • Especifique um campo namespace que seja o NumericRestrictNamespace.namespace.
    • Um dos campos de valor value_int, value_float e value_double.
    • Ele não pode ter um campo chamado op. Esse campo é apenas para consultas.

Avro

  • Use um arquivo Avro válido.

  • Faça registros que estejam em conformidade com o seguinte 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

  • Codifique o arquivo CSV usando UTF-8.
  • Cada linha do CSV precisa conter exatamente um registro.
  • O primeiro valor em cada linha precisa ser o ID do vetor, que precisa ser uma string UTF-8 válida.
  • Depois do ID, os próximos valores de N representam o vetor do atributo, em que N é a dimensão do vetor de atributo que foi configurado quando o índice foi criado.
  • Os valores de vetor de recurso precisam ser literais de ponto flutuante, conforme definido na especificação da linguagem Java.
  • Os valores adicionais podem estar no formato name=value.
  • O nome crowding_tag é interpretado como a tag de distanciamento e só pode aparecer uma vez no registro.

  • Todos os outros pares name=value são interpretados como restrições de namespace. O mesmo nome pode ser repetido se houver vários valores em um namespace.

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

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

  • Se o valor começar com !, o restante da string será interpretado como um valor excluído.

    Por exemplo, color=!red representa este TokenNamespace:

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

  • Pares #name=numericValue com sufixo de tipo numérico são interpretados como restrições numéricas de namespace. O sufixo do tipo de número é i para int, f para flutuante e d para duplo. O mesmo nome não pode ser repetido, porque precisa haver um único valor associado por namespace.

    Por exemplo, #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
}

A seguir