Usar a assistência de vetor

O Vector Assist no AlloyDB para PostgreSQL oferece um framework SQL declarativo que permite implantar, ajustar e gerenciar cargas de trabalho de pesquisa vetorial nas suas instâncias. É possível definir os requisitos de busca vetorial, gerar e aplicar as configurações de SQL recomendadas e monitorar o desempenho da carga de trabalho. Para saber mais sobre como o Vector Assist funciona, consulte Visão geral do Vector Assist.

Antes de começar

  • Confirme se a instância está usando a versão de manutenção correta. O Vector Assist requer um número mínimo de versão de manutenção de POSTGRES_17.20260128.03_06. Para mais informações sobre como realizar a manutenção de autoatendimento, consulte Manutenção de autoatendimento de desempenho.

  • Ative a extensão de assistência de vetor 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 pelo assistente de vetor.

Usar o assistente de vetor para implantar uma carga de trabalho de vetor

Para usar o assistente de vetor para implantar e gerenciar uma carga de trabalho de vetor, faça o seguinte:

Definir a especificação do vetor

Definir a especificação do vetor, ou especificação do vetor, é a primeira etapa para usar o assistente de vetor. 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 função vector_assist.define_spec 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 de vetor.

  • (Opcional) VECTOR_COLUMN_NAME: coluna em que você quer realizar uma pesquisa semântica. Se você tiver apenas uma coluna com vetores na tabela, o 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 o Vector Assist atenda. Se especificado, o vector_assist testa diferentes valores de ef_search, comparando o recall em pesquisas exatas de vizinho mais próximo. vector_assist define ef_search como o valor que fornece o recall desejado mais próximo. O valor padrão é 0.95.

  • (Opcional) TUNE_INDEX: booleano que especifica se o Vector Assist 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 de vetor.

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

Ver recomendações do Vector Assist

Para conferir as recomendações geradas pelo Vector Assist usando sua especificação do vetor, execute a função vector_assist.get_recommendations:

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

Substitua SPEC_ID pelo ID da especificação do vetor para o qual você quer ver as recomendações. Para ver a lista de especificações do vetor disponíveis, consulte Listar suas especificações do 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 recomendações do Vector Assist

É possível aplicar as recomendações geradas individualmente ou em conjunto.

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

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

Substitua RECOMMENDATION_ID pelo ID da recomendação do Vector Assist que você quer aplicar da tabela vector_assist.RECOMMENDATIONS.

Para aplicar todas as recomendações juntas, execute a função vector_assist.apply_spec 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.

Se quiser, você também pode 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 do Vector Assist.

Depois de aplicar as recomendações geradas pelo assistente de vetor, o índice de vetor estará pronto para uso.

Gerar consultas de pesquisa

Use o assistente de vetor para criar consultas de pesquisa otimizadas para as cargas de trabalho de vetor 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 função vector_assist.generate_query:

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

Substitua os seguintes parâmetros:

  • SPEC_ID: ID da especificação que você quer usar.

  • SEARCH_VECTOR: vetor da sua 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 o Vector Assist atenda. Se especificado, o vector_assist testa diferentes valores de ef_search, comparando o recall em pesquisas exatas de vizinho mais próximo. vector_assist define ef_search como o valor que fornece o recall desejado mais próximo.

  • (Opcional) FILTER_EXPRESSION: qualquer filtro para a consulta de pesquisa. Por exemplo, filtragem com base em outras colunas.

Para ver uma lista completa de todos os parâmetros disponíveis para gerar uma consulta de pesquisa, consulte Referências de funções do Vector Assist.

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

Listar as especificações do vetor

Se você precisar listar as especificações do vetor de uma tabela, execute a função vector_assist.list_specs ou use vector_assist.get_spec para visualizar uma única especificação do vetor por ID:

SELECT vector_assist.list_specs(
  table_name => 'TABLE_NAME',
  column_name => 'COLUMN_NAME'
);

Substitua os seguintes parâmetros:

  • TABLE_NAME: nome da tabela que você usou para definir a especificação do vetor.

  • (Opcional) COLUMN_NAME: nome da coluna de vetor na tabela. Se omitido, vector_assist.list_specs retorna todas as especificações de vetor definidas na tabela especificada. Para recuperar uma especificação de vetor específica por ID, chame SELECT vector_assist.get_spec(spec_id => 'SPEC_ID');.

A seguir