Usar a assistência de vetor

A assistência vetorial no AlloyDB para PostgreSQL oferece um framework SQL declarativo que permite implantar, ajustar e gerenciar cargas de trabalho de pesquisa vetorial nas instâncias. É possível definir os requisitos de pesquisa vetorial, gerar e aplicar configurações SQL recomendadas e monitorar a performance da carga de trabalho. Para saber mais sobre como a assistência vetorial funciona, consulte Visão geral da assistência vetorial.

Antes de começar

  • Confirme se a instância está usando a versão de manutenção correta. A assistência vetorial exige um número de versão de manutenção mínimo de POSTGRES_17.20260128.03_06. Para mais informações sobre como realizar a manutenção de autoatendimento, consulte Manutenção de autoatendimento de performance.

  • Ative a extensão de assistência vetorial usando o seguinte comando no banco de dados que você quer usar:

    CREATE EXTENSION vector_assist CASCADE;

    Isso gera o esquema vector_assist, que é usado pela assistência vetorial.

Usar a assistência vetorial para implantar uma carga de trabalho vetorial

Para usar a assistência vetorial para implantar e gerenciar uma carga de trabalho vetorial, faça o seguinte:

Definir a especificação vetorial

A definição da especificação vetorial, ou especificação de vetor, é a primeira etapa para usar a assistência vetorial. Dependendo do tipo de carga de trabalho vetorial, os campos usados para definir a especificação do vetor podem ser diferentes.

Por exemplo, se você quiser ativar a pesquisa semântica em uma coluna específica de uma tabela, execute a vector_assist.define_spec função para definir a especificação do vetor:

SELECT
  recommendation_id,
  REGEXP_REPLACE(query, 'SET hnsw.ef_search TO \d+', 'SET hnsw.ef_search TO') AS query_1,
  recommendation,
  vector_spec_id,
  table_name,
  applied,
  modified
FROM vector_assist.define_spec(
  table_name => 'TABLE_NAME',
  vector_column_name => 'VECTOR_COLUMN_NAME',
  target_recall => TARGET_RECALL,
  tune_vector_index => TUNE_INDEX
);

Substitua os seguintes parâmetros:

  • TABLE_NAME: nome da tabela que você quer usar na carga de trabalho vetorial.
  • (Opcional) VECTOR_COLUMN_NAME: coluna em que você quer realizar uma pesquisa semântica. Se você tiver apenas uma coluna com vetores na tabela, vector_assist poderá definir isso automaticamente. Se houver mais de uma tabela com vetores, especifique qual coluna usar.
  • (Opcional) TARGET_RECALL: recall de destino que você quer que a assistência vetorial atenda. Se especificado, vector_assist testa diferentes valores de ef_search, comparando o recall em pesquisas exatas e de vizinhos mais próximos. vector_assist define ef_search como o valor que fornece o recall de destino mais próximo. O valor padrão é 0.95.
  • (Opcional) TUNE_INDEX: booleano que especifica se a assistência vetorial ajusta os índices de vetor na carga de trabalho. O valor padrão é false, o que significa que apenas os parâmetros relacionados à pesquisa (ef_search) são ajustados. Os parâmetros de tempo de build (m, ef_construction) não são ajustados.

Para conferir uma lista completa de todos os parâmetros disponíveis para a especificação do vetor, consulte Referências de funções de assistência vetorial.

Depois de executar a consulta para criar a especificação do vetor, a assistência vetorial gera automaticamente etapas, chamadas de recomendações, que você precisa executar para implantar a carga de trabalho vetorial.

Conferir as recomendações de assistência vetorial

Para conferir as recomendações geradas pela assistência vetorial usando a especificação do vetor, execute a vector_assist.get_recommendations função:

SELECT vector_assist.get_recommendations(
  spec_id => 'SPEC_ID'
);

Substitua SPEC_ID pelo ID da especificação do vetor para a qual você quer conferir as recomendações. Para conferir a sua lista de especificações de vetor disponíveis, consulte Listar as especificações de vetor.

vector_assist.get_recommendations retorna uma tabela chamada vector_assist.RECOMMENDATIONS que contém todas as recomendações. Cada recomendação é armazenada em uma tabela com o spec_id associado. Cada recomendação geralmente contém as seguintes informações:

  • Consulta SQL que você precisa executar
  • Explicação detalhada da recomendação
  • Outras informações relevantes que explicam a recomendação

Aplicar as recomendações de assistência vetorial

É possível aplicar as recomendações geradas individualmente ou como um todo.

Para aplicar uma recomendação específica, execute a vector_assist.apply_recommendation função:

SELECT vector_assist.apply_recommendation(
  recommendation_id => 'RECOMMENDATION_ID'
);

Substitua RECOMMENDATION_ID pelo ID da recomendação de assistência vetorial que você quer aplicar na tabela vector_assist.RECOMMENDATIONS.

Para aplicar todas as recomendações juntas, execute a vector_assist.apply_spec função com o parâmetro spec_id ou table_name:

SELECT vector_assist.apply_spec(
  spec_id => 'SPEC_ID'
);

Substitua SPEC_ID pelo ID da especificação do vetor que você quer usar.

Opcionalmente, também é possível inserir os parâmetros schema_name ou column_name. Para informações sobre todos os parâmetros de consulta disponíveis, consulte Referências de funções de assistência vetorial.

Depois de aplicar as recomendações geradas pela assistência vetorial, o índice de vetor estará pronto para uso.

Gerar consultas de pesquisa

É possível usar a assistência vetorial para ajudar a criar consultas de pesquisa otimizadas para cargas de trabalho vetoriais implantadas usando a especificação do vetor da carga de trabalho e o índice de vetor gerado. Para gerar uma consulta de pesquisa otimizada, execute a vector_assist.generate_query função:

SELECT vector_assist.generate_query(
  spec_id => 'SPEC_ID',
  search_vector => 'SEARCH_VECTOR',
  top_k => 'TOP_K',
  target_recall => TARGET_RECALL,
  filter_expression => 'FILTER_EXPRESSION'
);

Substitua os seguintes parâmetros:

  • SPEC_ID: ID da especificação que você quer usar.
  • SEARCH_VECTOR: vetor da consulta de pesquisa. Por exemplo, [1, 2, 3].
  • (Opcional) TOP_K: número de vizinhos mais próximos a serem retornados. Se não for especificado, o valor padrão será 10.
  • (Opcional) TARGET_RECALL: recall de destino que você quer que a assistência vetorial atenda. Se especificado, vector_assist testa diferentes valores de ef_search, comparando o recall em pesquisas exatas e de vizinhos mais próximos. vector_assist define ef_search como o valor que fornece o recall de destino mais próximo.
  • (Opcional) FILTER_EXPRESSION: todos os filtros da consulta de pesquisa. Por exemplo, filtragem com base em outras colunas.

Para conferir uma lista completa de todos os parâmetros disponíveis para gerar uma consulta de pesquisa, consulte Referências de funções de assistência vetorial.

A saída dessa função retorna um texto que contém uma consulta SQL. Você pode executar ou salvar essa consulta SQL conforme necessário.

Listar as especificações do vetor

Se você precisar listar uma ou todas as especificações do vetor atuais, execute a função vector_assist.list_specs:

SELECT vector_assist.list_specs(
  spec_id => 'SPEC_ID',
  table_name => 'TABLE_NAME'
);

Substitua os seguintes parâmetros:

  • (Opcional) SPEC_ID: ID da especificação do vetor que você quer usar.
  • TABLE_NAME: nome da tabela usada para definir a especificação do vetor.

A seguir