Criar e gerenciar índices vetoriais

Nesta página, descrevemos como configurar a memória para índices vetoriais e criar, ajustar, monitorar e descartar esses índices.

Antes de começar

Antes de criar um índice de vetor, carregue os dados na tabela base com valores de incorporação de vetor. Sua tabela base precisa ter pelo menos 1.000 linhas. Se houver mais pontos de dados disponíveis, você terá um melhor particionamento e treinamento do índice.

Configurar a alocação de memória para índices de vetor

A flag de banco de dados cloudsql_vector_max_mem_size controla quanta memória a instância do Cloud SQL dedica aos índices de vetor. Essa é uma flag estática que exige a reinicialização da instância. Essa memória tem duas finalidades principais:

  1. Armazenamento da estrutura do índice de vetor:a parte não folha do índice de vetor (o TREE_MEMORY) reside nessa memória. O tamanho aproximado dessa árvore depende do número de nós folha (num_leaves) e das dimensões dos vetores:

     Approximate TREE_MEMORY = num_leaves * vector dimensions * 4 * 2

    Por exemplo, um índice com 1.000 folhas e 768 dimensões teria um TREE_MEMORY aproximado de 1.000 * 768 * 4 * 2 ou 6.144.000 bytes. Também é possível verificar o TREE_MEMORY real usando a tabela information_schema.innodb_vector_indexes. O Cloud SQL gerencia essa memória. Não é necessário alocar espaço para todos os índices vetoriais simultaneamente, já que os inativos são descarregados para abrir espaço para outras solicitações.

  2. Memória para criação de índice (dados de treinamento): durante a criação do índice de vetor, é necessário ter memória para processar uma amostra dos dados da tabela de base e criar o índice. Ela é usada apenas durante o processo de criação do índice e é liberada depois. O tamanho aproximado da memória necessária para o treinamento é:

     approximate_training_memory = num_rows in base table * 0.1 * 4 * vector dimensions

    Por exemplo, com uma tabela de 1.000.000 de linhas e 768 dimensões, o training_memory seria 1.000.000 * 0,1 * 768 * 4 ou 307.200.000 bytes. Apenas 10% dos dados da tabela de base são amostrados para calcular os centroides da árvore.

    Quando você ativa a flag cloudsql_vector, o Cloud SQL define automaticamente um cloudsql_vector_max_mem_size padrão com base no tamanho da VM. Esse padrão geralmente é suficiente para cargas de trabalho típicas. O Cloud SQL reduz a flag innodb_buffer_pool_size para alocar essa memória. O valor máximo padrão para cloudsql_vector_max_mem_size é 16 GB. Se você precisar ajustar o tamanho da memória, ajuste dinamicamente cloudsql_vector_max_mem_size com base no uso do índice de vetor.

    Importante: se você aumentar cloudsql_vector_max_mem_size, diminua innodb_buffer_pool_size para evitar problemas de memória.

cloudsql_vector_max_mem_size valores

Tamanho da VM cloudsql_vector_max_mem_size
4 GB 194MB
8 GB 515MB
16 GB 1,2 GB
32 GB 2,56 GB
64 GB 5,12 GB
128 GB 10,24 GB
256 GB ou mais 16 GB

O intervalo de memória alocada para o índice de vetor é o seguinte:

  • 128 MB (mínimo)
  • 10% do pool de buffer
  • Máximo de 16 GB

Você pode ajustar a memória depois, conforme necessário. Para mais informações, consulte Ativar a flag de banco de dados para embeddings de vetores.

Para informações sobre como monitorar o tamanho do índice vetorial, consulte Monitorar índices vetoriais.

Para atualizar a memória alocada para índices de vetor na instância, use o comando a seguir:

gcloud sql instances patch INSTANCE_NAME \
 --database-flags= cloudsql_vector_max_mem_size=NEW_MEMORY_VALUE;

Substitua:

  • INSTANCE_NAME: o nome da instância em que você está mudando a alocação de memória.
  • NEW_MEMORY_VALUE: a alocação de memória atualizada, em bytes, para seus índices de vetor.

Essa mudança entra em vigor imediatamente após a reinicialização do banco de dados.

Criar um índice vetorial

Há duas maneiras de criar um índice de vetor:

  • CREATE VECTOR INDEXstatement, uma extensão do Cloud SQL para a sintaxe padrão do MySQL.
  • instrução ALTER TABLE com a extensão da cláusula ADD VECTOR INDEX do Cloud SQL. Não é possível executar essa instrução simultaneamente com outras instruções DDL na tabela.

Use a seguinte sintaxe para criar um índice de vetores usando CREATE VECTOR INDEX:

CREATE
  VECTOR INDEX INDEX_NAME
ON TABLE_NAME(COLUMN_NAME)
USING
  SCANN[QUANTIZER = SQ8]
    DISTANCE_MEASURE
  = L2_SQUARED | COSINE | DOT_PRODUCT[NUM_LEAVES = INT_VALUE { '</var>' }}];

Estas são as opções de índice:

  • USING SCANN: opcional. Indica o tipo de índice a ser usado. SCANN é o único valor aceito.
  • QUANTIZER: opcional. Mapeia um vetor de alta dimensão para uma representação compactada. SQ8 é o único valor aceito.
  • DISTANCE_MEASURE: obrigatório. Especifica uma fórmula matemática para calcular a similaridade de dois vetores. Defina a mesma medida de distância nesse parâmetro e nas opções de pesquisa approx_distance. Os literais aceitos são:
    • L2_SQUARED
    • COSINE
    • DOT_PRODUCT
  • NUM_LEAVES: opcional. Especifica quantas partições (folhas) serão criadas. Só mude essa configuração do padrão se você tiver um bom entendimento da pesquisa de ANN e do seu conjunto de dados. O número especificado não pode ser maior que o número de incorporações na tabela de base.

Por exemplo, para criar um índice de vetores, execute o seguinte:

CREATE
  VECTOR INDEX vectorIndex
ON dbname.books(embeddings) DISTANCE_MEASURE = L2_SQUARED;

Enquanto a instrução CREATE está em execução, a tabela base é colocada em modo somente leitura e nenhuma DML é permitida nela.

Use a seguinte sintaxe para criar um índice em uma tabela existente:

ALTER TABLE tbl_name
  ADD VECTOR INDEX index_name(key_part)[index_option];

Por exemplo, para criar um índice em uma tabela atual:

ALTER TABLE t1 ADD VECTOR INDEX index1(j)
USING SCANN QUANTIZER = SQ8 DISTANCE_MEASURE = l2_squared NUM_LEAVES = 10;

Ajustar o índice vetorial

Nesta seção, você encontra mais informações sobre os parâmetros usados para criar o índice de vetor. Para ajustar o índice de vetor, use essas informações para determinar como influenciar o processo de build.

Parâmetro Descrição Padrão Scope Impacto
cloudsql_vector_max_mem_size Memória alocada para treinamento de índice. Varia Instância Memória insuficiente pode causar falhas de build. Consulte Configurar a alocação de memória para índices de vetor.
innodb_ddl_threads Grau de paralelismo para treinamento e criação de índice. 4 Sessão Valores mais altos reduzem o tempo de build, mas aumentam a carga da CPU. Defina esse valor como o número de CPUs que você pode poupar sem afetar negativamente as operações do banco de dados.

Verifique se a cloudsql_vector_max_mem_size está configurada corretamente para o treinamento. Ajuste innodb_ddl_threads para equilibrar o tempo de build e a carga da CPU, considerando o impacto nas operações simultâneas do banco de dados. Monitore o uso da CPU durante a compilação.

Descartar um índice vetorial

Para descartar um índice de vetor, use as instruções SQL DROP INDEX ou ALTER TABLE com o nome do índice que você quer descartar, conforme mostrado abaixo:

DROP INDEX index_name ON books;

ALTER TABLE table_name
DROP INDEX index_name;

Monitorar índices vetoriais

O Cloud SQL fornece as seguintes tabelas de esquema de informações com informações em tempo real sobre os índices de vetor carregados na memória:

  • information_schema.innodb_vector_indexes lista todos os índices vetoriais abertos na memória após a reinicialização.
  • information_schema.innodb_all_vector_indexes lista todos os índices de vetor que existem na instância, mesmo que ainda não estejam abertos na memória.
  • information_schema.innodb_vector_indexes_memory fornece informações sobre o uso geral de memória dos índices vetoriais na instância.

Para mais informações, consulte o Esquema de informações.

Para ver informações na tabela innodb_vector_indexes, execute o seguinte comando:

SELECT * FROM information_schema.innodb_vector_indexes \ G;

A saída será assim:

 INDEX_NAME: t1_vec_index
 TABLE_NAME: test.t1
 INDEX_TYPE: TREE_SQ
 DIMENSION: 3
 DIST_MEASURE: COSINE
 STATUS: Ready
 STATE: INDEX_READY_TO_USE
 NUM_LEAVES: 10
 NUM_LEAVES_TO_SEARCH: 10
 QUERIES: 1
 MUTATIONS: 1
 TREE_MEMORY: 443

A seguir