Criar e gerenciar índices vetoriais

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

Antes de começar

Antes de criar um índice de vetor, carregue os dados na tabela base com valores de embedding 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.

Ative a flag de banco de dados cloudsql_vector na instância do Cloud SQL.

Para instâncias que usam o Cloud SQL para MySQL 9.7 ou posterior, embora não seja necessário ativar o cloudsql_vector para criar e armazenar embeddings de vetor, é preciso ativar a flag de banco de dados cloudsql_vector na instância do Cloud SQL para criar índices de vetor.

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 a í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 vetorial: a parte 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 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 í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 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 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.

cloudsql_vector_max_mem_size valores

O intervalo de alocação de memória para o índice vetorial é o seguinte:

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

É possível ajustar a memória mais tarde, conforme necessário.

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

Para atualizar a alocação de memória 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á alterando 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 vetorial:

• 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 de 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 vetor 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 ];

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

• USING SCANN: opcional. Indica o tipo de índice a ser usado. SCANN é o único valor compatível.
• QUANTIZER: opcional. Associa um vetor de alta dimensão a uma representação compactada. SQ8 é o único valor compatível.
• 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 que a distância definida nas opções de pesquisa approx_distance. Os literais compatíveis são:
  • L2_SQUARED
  • COSINE
  • DOT_PRODUCT
• NUM_LEAVES: opcional. Especifica quantas partições (folhas) serão criadas. Só mude essa configuraçã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 embeddings na tabela base.

Por exemplo, para criar um índice de vetor, 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 um modo somente leitura, e nenhuma DML é permitida nela.

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

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

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

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 vetorial. Para ajustar o índice vetorial, use essas informações para determinar como influenciar o processo de criação.

Verifique se cloudsql_vector_max_mem_size está configurado 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 o build.

Remover um índice vetorial

Para remover um índice vetorial, use as instruções SQL DROP INDEX ou ALTER TABLE com o nome do índice que você quer remover, conforme mostrado a seguir:

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 vetoriais carregados na memória:

• information_schema.innodb_vector_indexes lista todos os índices vetoriais que são abertos na memória após a reinicialização.
• information_schema.innodb_all_vector_indexes lista todos os índices vetoriais 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 da memória dos índices vetoriais na instância.

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

Para ver as 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

Práticas recomendadas para trabalhar com índices vetoriais

Nesta seção, você conhecerá práticas recomendadas para trabalhar com índices de vetor. Cada carga de trabalho é diferente, e talvez você precise ajustá-la de acordo.

• Após as principais operações de linguagem de manipulação de dados (DML), é uma boa prática recriar o índice.
• Em geral, é aceitável permitir que o Cloud SQL calcule o número de folhas ou contêineres de embeddings a serem usados. O número de folhas determina em quantas partições o índice de vetor é dividido. Se você quiser especificar o número de folhas em um caso de uso, recomendamos ter pelo menos 100 vetores por folha para o melhor recall. No contexto da busca vetorial, o recall se refere à porcentagem de vetores retornados pelo índice que são vizinhos mais próximos reais.

A seguir

• Leia a visão geral sobre a pesquisa vetorial no Cloud SQL.
• Saiba como ativar e desativar embeddings de vetor na sua instância.
• Saiba como gerar embeddings de vetor.
• Saiba como realizar pesquisas em embeddings de vetor.