Importar dados de índice do BigQuery

Este guia explica como importar dados de índice do BigQuery para a Pesquisa vetorial com a API ImportIndex, simplificando o processo de preenchimento dos índices da Pesquisa vetorial diretamente das tabelas do BigQuery que contêm incorporações de vetores.

Como preparar dados do BigQuery para importação

Antes de importar dados de índice, sua tabela do BigQuery precisa ter as seguintes colunas:

  • Identificadores exclusivos: essa coluna contém identificadores exclusivos para cada ponto de dados. Ele é mapeado para o campo id na pesquisa de vetor.

  • Embeddings de vetor: essa coluna contém os embeddings de vetor, representados como um campo FLOAT repetido. Ele é mapeado para o campo de embedding na Pesquisa Vetorial.

Também é possível incluir as seguintes colunas:

  • Restrições: são colunas para restrições de string e numéricas, que permitem filtrar seus dados durante as pesquisas.

  • Metadados: são colunas de metadados que serão retornadas com os resultados da consulta de índice da pesquisa vetorial.

Como preparar o índice da pesquisa de vetor para importação

Depois de preparar os dados do BigQuery, verifique se o índice de pesquisa vetorial de destino:

  • Existe na pesquisa vetorial no seu projeto: esse índice serve como destino para os dados importados. O índice precisa ser criado no seu projeto.

  • Está definido para substituir ou anexar dados: durante o processo de importação, você pode substituir os dados atuais no índice de pesquisa vetorial ou anexar os dados importados do BigQuery. A substituição substitui os pontos de dados atuais pelos dados importados. A anexação adiciona os novos dados ao índice atual.

  • Corresponde à dimensionalidade: a dimensionalidade dos embeddings armazenados nos dados do BigQuery precisa ser idêntica à dimensionalidade configurada para o índice de pesquisa vetorial.

Como especificar o ImportIndexRequest

Antes de importar dados do BigQuery, crie um objeto ImportIndexRequest que especifique o índice de destino, se os dados atuais serão substituídos e a configuração para conexão com o BigQuery. Envie esse objeto de solicitação para a API ImportIndex.

Este é um exemplo de ImportIndexRequest no formato JSON:

{
  "name": "projects/[PROJECT_ID]/locations/[LOCATION]/indexes/[INDEX_ID]",
  "isCompleteOverwrite": true,
  "config": {
    "bigQuerySourceConfig": {
      "tablePath": "[PROJECT_ID].[DATASET_ID].[TABLE_ID]",
      "datapointFieldMapping": {
        "idColumn": "[ID_COLUMN_NAME]",
        "embeddingColumn": "[EMBEDDING_COLUMN_NAME]",
        "restricts": [
          {
            "namespace": "[RESTRICT_NAMESPACE]",
            "allowColumn": ["[RESTRICT_ALLOW_COLUMN_NAME]"],
            "denyColumn": ["[RESTRICT_DENY_COLUMN_NAME]"]
          }
        ],
        "numericRestricts": [
          {
            "namespace": "[RESTRICT_NAMESPACE]",
            "valueColumn": "[RESTRICT_VALUE_COLUMN_NAME]",
            "valueType": "INT"
          }
        ],
        "metadataColumns": ["METADATA_COLUMN1", "METADATA_COLUMN2", ...]
      }
    }
  }
}

  • name: o nome completo do recurso do índice de pesquisa vetorial em que você quer importar os dados.

  • isCompleteOverwrite: um booleano que indica se os dados atuais no índice serão substituídos. Defina como true para substituir os dados atuais.

  • config: contém a configuração da origem do BigQuery.

    • bigquerySourceConfig: especifica os detalhes da conexão com sua tabela do BigQuery.

    • tablePath: o caminho completo para sua tabela do BigQuery no formato [PROJECT_ID].[DATASET_ID].[TABLE_ID].

    • datapointFieldMapping: mapeia as colunas na sua tabela do BigQuery para os campos na pesquisa de vetor.

      • idColumn: o nome da coluna que contém identificadores exclusivos.

      • embeddingColumn: o nome da coluna que contém embeddings de vetor.

      • restricts: (opcional) especifica restrições de string.

      • namespace: o namespace da restrição.

      • allowColumn: a matriz que contém os nomes das colunas para valores permitidos da restrição.

      • denyColumn: a matriz que contém os nomes das colunas para valores negados para a restrição.

      • numericRestricts: (opcional) especifica restrições numéricas.

      • namespace: o namespace da restrição numérica.

      • value_column: o nome da coluna que contém valores numéricos.

      • value_type: o tipo do valor numérico, como INT, FLOAT ou DOUBLE.

      • metadataColumns: (opcional) campos de metadados a serem incluídos com a incorporação de recursos. Esses campos de metadados podem ser recuperados dos resultados da pesquisa de índice, mas não afetam a pesquisa em si. Por exemplo, não é possível filtrar campos de metadados.

Executar a importação

Depois de criar um ImportIndexRequest, envie-o para o endpoint da API ImportIndex. Isso aciona o processo de importação, que exporta dados do BigQuery e os ingere no seu índice de pesquisa vetorial. ImportIndex retorna uma operação de longa duração. Use o ID da operação para monitorar o progresso da importação.

Depois que os dados importados são armazenados, eles ficam no seu índice de pesquisa vetorial e são indistinguíveis dos dados ingeridos usando outros métodos. O índice pode continuar sendo gerenciado usando as APIs padrão de pesquisa vetorial.

O exemplo de código a seguir demonstra um resultado de consulta com return_full_datapoint definido como "true" e a configuração do conector do BigQuery que especifica uma restrição genre, uma restrição numérica year e colunas de metadados title e description.

nearest_neighbors {
  neighbors {
    datapoint {
      datapoint_id: "4"
      feature_vector: 0.7
      feature_vector: 0.8
      restricts {
        namespace: "genre"
        allow_list: "Drama"
      }
      embedding_metadata {
        title: "A Movie"
        description: "The story of A Movie..."
      }
      crowding_tag {
        crowding_attribute: "0"
      }
      numeric_restricts {
        namespace: "year"
        value_int: 1942
      }
    }
    distance: 0.75
  }
}