Criar e gerenciar índices vetoriais

Esta página descreve como configurar a memória para índices vetoriais e criar, otimizar, monitorar e excluir índices vetoriais.

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 você tiver mais pontos de dados disponíveis, poderá melhorar o particionamento e o 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 a quantidade de memória que a instância do Cloud SQL dedica aos índices de vetor. Essa é uma flag estática que requer a reinicialização da instância. Essa recordação tem dois propósitos principais:

  1. Armazenamento da estrutura do índice vetorial:a parte que não é folha do índice vetorial (o TREE_MEMORY) reside nessa memória. O tamanho aproximado dessa árvore depende do número de nós de 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 614.4000 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 índices 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 vetorial, é necessária memória para processar uma amostra dos dados da tabela base para criar o índice. Essa memória é 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 linhas e 768 dimensões, o training_memory será 1.000.000 * 0,1 * 768 * 4 ou 307.200.000 bytes. Apenas 10% dos dados da tabela 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 de 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, será necessário diminuir 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 do índice vetorial alocado é o seguinte:

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

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

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 seguinte comando:

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 uma reinicialização do banco de dados.

Criar um índice vetorial

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

  • Instrução CREATE VECTOR INDEX, 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>' }}];

Confira 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 a ser usada para calcular a semelhança de dois vetores. É necessário definir a mesma medida de distância neste parâmetro como a distância definida 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 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 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 no modo somente leitura e nenhuma DML é permitida na tabela base.

Use a sintaxe a seguir 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 existente:

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

Ajustar o índice vetorial

Esta seção oferece mais informações sobre os parâmetros usados para criar o índice de vetores. 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 o treinamento de índice. Varia Instância A memória insuficiente pode causar falhas no build. Consulte Configurar a alocação de memória para índices de vetor.
innodb_ddl_threads Grau de paralelismo para treinamento e build 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 usar 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 a utilização da CPU durante a versão.

Descartar um índice vetorial

Para excluir um índice de vetor, use as instruções SQL DROP INDEX ou ALTER TABLE com o nome do índice que você quer excluir, 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 índices de vetores carregados na memória:

  • information_schema.innodb_vector_indexes lista todos os índices de vetor que são abertos na memória após a reinicialização.
  • information_schema.innodb_all_vector_indexes lista todos os índices de vetores 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 conferir 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