Referência de assistência vetorial

MySQL   |  PostgreSQL   |  SQL Server

Pré-lançamento — Vector Assist

Este recurso está sujeito aos "Termos da Oferta Pré-GA" na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. É possível tratar dados pessoais para esse recurso conforme descrito no Aditivo sobre tratamento de dados do Cloud, sujeito às obrigações e restrições descritas no contrato que rege o acesso ao Google Cloud. Os recursos pré-GA estão disponíveis no estado em que se encontram e podem ter assistência limitada. Para mais informações, consulte as descrições das fases de lançamento.

Esta página fornece informações detalhadas sobre todas as funções de assistência vetorial disponíveis e os parâmetros obrigatórios e opcionais delas.

vector_assist.define_spec

Define uma nova especificação de vetor, ou especificação de vetor, e retorna recomendações necessárias para aumentar a carga de trabalho de vetor. Essa função aplica as especificações fornecidas pelo usuário para gerar as recomendações.

Função

CREATE OR REPLACE FUNCTION vector_assist.define_spec(
    spec_id TEXT DEFAULT NULL,
    table_name TEXT,
    schema_name TEXT DEFAULT NULL,
    vector_column_name TEXT DEFAULT NULL,
    text_column_name TEXT DEFAULT NULL,
    vector_index_type TEXT DEFAULT NULL, -- Allowed: 'hnsw', 'ivfflat'
    embeddings_available BOOL DEFAULT NULL,
    embedding_model TEXT DEFAULT NULL,
    num_vectors INT DEFAULT NULL,
    dimensionality INT DEFAULT NULL,
    distance_func TEXT DEFAULT NULL, -- Allowed: 'cosine', 'ip', 'l2', 'l1'
    quantization TEXT DEFAULT NULL, -- Allowed: 'none', 'halfvec', 'bit'
    prefilter_column_names TEXT[] DEFAULT NULL,
    memory_budget_kb INT DEFAULT NULL, -- In KB
    target_recall FLOAT DEFAULT NULL,
    target_top_k INT DEFAULT NULL,
    tune_vector_index BOOL DEFAULT FALSE, -- Set to true if target_recall is set
)
RETURNS SETOF vector_assist.RECOMMENDATIONS;

Parâmetros

Parâmetro	Obrigatório?	Descrição
spec_id	Obrigatório (gerado automaticamente)	Um ID exclusivo para a especificação de vetor definida por você.
table_name	Obrigatório?	O nome da tabela a ser usado na configuração da carga de trabalho de vetor.
schema_name	Opcional	O esquema que contém a tabela a ser usada na carga de trabalho de vetor. O esquema é inferido automaticamente com base no caminho de pesquisa do esquema.
vector_column_name	Opcional ou obrigatório	O nome da coluna que contém os embeddings de vetor. Essa coluna é obrigatória se você estiver usando mais de uma coluna de vetor e o text_column_name não estiver declarado. Se você estiver usando apenas uma coluna de vetor, esse parâmetro será opcional.
text_column_name	Opcional ou obrigatório	O nome da coluna de texto. Se a carga de trabalho de vetor exigir a geração de incorporações de uma coluna de texto, esse parâmetro será obrigatório. Essa coluna é obrigatória se o parâmetro vector_column_name for NULL e não houver outras colunas de vetor. Esse parâmetro usa a extensão google_ml_integration para gerar embeddings da coluna de texto especificada.
vector_index_type	Opcional	O tipo do índice vetorial. Os valores aceitáveis são: HNSW IVFFlat SCANN
embeddings_available	Opcional	Um booleano que verifica se os embeddings de vetor existem na tabela selecionada. Esse campo será definido como FALSE se nenhuma coluna de vetor for detectada e o parâmetro text_column_name for definido.
embedding_model	Opcional ou obrigatório	O ID do modelo de google_ml.models a ser usado para gerar os embeddings. Esse campo é opcional, a menos que o parâmetro embeddings_available seja FALSE ou NULL.
num_vectors	Opcional	O número de vetores na tabela.
dismensionality	Opcional	A dimensão dos vetores fornecidos.
distance_func	Opcional	A função de distância a ser usada para comparar vetores. Os valores aceitáveis incluem cosine, ip, l2 ou l1.
quantization	Opcional	A quantização para os índices de vetor. Os valores aceitáveis incluem none, halfvec ou bit.
prefilter_column_names	Opcional	Cria um índice para a coluna especificada para pré-filtragem. Isso pode ajudar a melhorar o desempenho de consultas com um filtro de alta seletividade na coluna.
memory_budget_kb	Opcional	A memória máxima (em KB) para a criação de índices.
target_recall	Opcional	O recall de destino para consultas vetoriais padrão.
target_top_k	Opcional	Os principais valores correspondentes a serem extraídos para o cálculo de recall. Esse valor será usado se o parâmetro target_recall for especificado.
tune_vector_index	Opcional	Ajusta os índices de vetores na sua carga de trabalho. Se ativada, a assistência de vetor ajusta automaticamente o índice de vetor ou a consulta de pesquisa usando a especificação de vetor e calcula os parâmetros ideais de banco de dados e índice. Os valores aceitáveis incluem TRUE ou FALSE.

Valor de retorno

Retorna uma tabela de recomendações que precisam ser aplicadas para configurar a carga de trabalho de vetor solicitada. Cada linha é uma única recomendação que contém uma consulta SQL executável e uma explicação detalhada de por que aplicar a recomendação. A recomendação pode ser aplicada usando a função apply_recommendation().

Observação: essa função é uma operação de longa duração (LRO, na sigla em inglês). Se você estiver usando um cliente com um tempo limite (como o Cloud SQL Studio com um tempo limite de 5 minutos), a chamada de função poderá ser encerrada. Para resolver esse problema, aumente o limite de tempo limite ou crie uma cópia da tabela que você está usando com apenas um subconjunto de dados para atender aos requisitos de tempo limite.

A tabela de recomendações contém as seguintes colunas:

Nome da coluna	Tipo	Descrição
recommendation_id	Texto	O ID da recomendação. A recomendação é aplicada usando esse ID.
vector_spec_id	Texto	O ID da especificação de vetor associada à recomendação.
table_name	Texto	O nome da tabela associada à recomendação.
schema_name	Texto	O nome do esquema que contém a tabela especificada.
query	Texto	A consulta SQL executável que será executada para alcançar o resultado da recomendação.
recommendation	Texto	A explicação da recomendação, incluindo o resultado esperado depois que ela for aplicada. Essa coluna também contém o motivo e a justificativa da recomendação. Use esse contexto para ajustar a consulta conforme necessário e gerar recomendações novamente.
applied	Booleano	Mostra se a recomendação foi aplicada.
modified	Booleano	Mostra se a recomendação foi modificada pelo usuário.
created_at	Carimbo de data/hora com fuso horário	O momento em que a recomendação foi gerada no formato timestamp with time zone. Por exemplo, 2024-07-18 09:00:00-08.

vector_assist.list_specs

Retorna a especificação de vetor atual para uma determinada tabela e coluna.

Função

CREATE OR REPLACE FUNCTION vector_assist.list_specs(
  table_name      TEXT,
  column_name     TEXT DEFAULT NULL
)
RETURNS SETOF vector_assist.VECTOR_SPECS

Parâmetros

Parâmetro	Obrigatório?	Descrição
table_name	Obrigatório?	O nome da tabela para que a especificação do vetor é recuperada.
column_name	Opcional	O nome da coluna para filtrar a tabela antes de retornar a especificação. Se o nome da coluna for especificado, as especificações que contêm nomes de colunas de texto ou vetor que correspondem a esse nome serão retornadas.

Valor de retorno

Retorna uma tabela de especificações para a tabela e, opcionalmente, o nome da coluna.

vector_assist.modify_spec

Modifica uma especificação de vetor atual. Quando a especificação de vetor é modificada, as recomendações associadas são regeneradas com base nas novas especificações.

Função

CREATE OR REPLACE FUNCTION vector_assist.modify_spec(
  spec_id                TEXT,
  table_name             TEXT DEFAULT NULL,
  schema_name            TEXT DEFAULT NULL,
  vector_column_name     TEXT DEFAULT NULL,
  text_column_name       TEXT DEFAULT NULL,
  vector_index_type      TEXT DEFAULT NULL,
  embeddings_available   BOOL DEFAULT NULL,
  num_vectors            INT DEFAULT NULL,
  dimensionality         INT DEFAULT NULL,
  embedding_model        TEXT DEFAULT NULL,
  prefilter_column_names TEXT[] DEFAULT NULL,
  distance_func          TEXT DEFAULT NULL,
  quantization           TEXT DEFAULT NULL,
  memory_budget_kb       INT DEFAULT NULL,
  target_recall          FLOAT DEFAULT NULL,
  target_top_k           INT DEFAULT NULL,
  tune_vector_index      BOOL DEFAULT NULL
)
RETURNS SETOF vector_assist.RECOMMENDATIONS

Parâmetros

Parâmetro	Obrigatório?	Descrição
spec_id	Obrigatório (gerado automaticamente)	Um ID exclusivo para a especificação de vetor definida por você.
table_name	Obrigatório?	O nome da tabela a ser usado na configuração da carga de trabalho de vetor.
schema_name	Opcional	O esquema que contém a tabela a ser usada na carga de trabalho de vetor. O esquema é inferido automaticamente com base no caminho de pesquisa do esquema.
vector_column_name	Opcional ou obrigatório	O nome da coluna que contém os embeddings de vetor. Essa coluna é obrigatória se você estiver usando mais de uma coluna de vetor e o text_column_name não estiver declarado. Se você estiver usando apenas uma coluna de vetor, esse parâmetro será opcional.
text_column_name	Opcional ou obrigatório	O nome da coluna de texto. Se a carga de trabalho de vetor exigir a geração de incorporações de uma coluna de texto, esse parâmetro será obrigatório. Essa coluna é obrigatória se o parâmetro vector_column_name for NULL e não houver outras colunas de vetor. Esse parâmetro usa a extensão google_ml_integration para gerar embeddings da coluna de texto especificada.
vector_index_type	Opcional	O tipo do índice vetorial. Os valores aceitáveis são: HNSW IVFFlat SCANN
embeddings_available	Opcional	Um booleano que verifica se os embeddings de vetor existem na tabela selecionada. Esse campo será definido como FALSE se nenhuma coluna de vetor for detectada e o parâmetro text_column_name for definido.
embedding_model	Opcional ou obrigatório	O ID do modelo de google_ml.models a ser usado para gerar os embeddings. Esse campo é opcional, a menos que o parâmetro embeddings_available seja FALSE ou NULL.
num_vectors	Opcional	O número de vetores na tabela.
dismensionality	Opcional	A dimensão dos vetores fornecidos.
distance_func	Opcional	A função de distância a ser usada para comparar vetores. Os valores aceitáveis incluem cosine, ip, l2 ou l1.
quantization	Opcional	A quantização para os índices de vetor. Os valores aceitáveis incluem none, halfvec ou bit.
prefilter_column_names	Opcional	Identifica as colunas que são disponibilizadas para pré-filtragem em consultas de pesquisa vetorial.
memory_budget_kb	Opcional	A memória máxima (em KB) para a criação de índices.
target_recall	Opcional	O recall de destino para consultas vetoriais padrão.
target_top_k	Opcional	Os principais valores correspondentes a serem extraídos para o cálculo de recall. Esse valor será usado se o parâmetro target_recall for especificado.
tune_vector_index	Opcional	Ajusta os índices de vetores na sua carga de trabalho. Se ativada, a assistência de vetor ajusta automaticamente o índice de vetor ou a consulta de pesquisa usando a especificação de vetor e calcula os parâmetros ideais de banco de dados e índice. Os valores aceitáveis incluem TRUE ou FALSE.

Valor de retorno

Retorna uma tabela atualizada de recomendações que precisam ser aplicadas para configurar a carga de trabalho de vetor solicitada. Cada linha é uma única recomendação que contém uma consulta SQL executável e uma explicação detalhada de por que aplicar a recomendação. A recomendação pode ser aplicada usando a função apply_recommendation().

A tabela de recomendações contém as seguintes colunas:

Nome da coluna	Tipo	Descrição
recommendation_id	Texto	O ID da recomendação. A recomendação é aplicada usando esse ID.
vector_spec_id	Texto	O ID da especificação de vetor associada à recomendação.
table_name	Texto	O nome da tabela associada à recomendação.
schema_name	Texto	O nome do esquema que contém a tabela especificada.
query	Texto	A consulta SQL executável que será executada para alcançar o resultado da recomendação.
recommendation	Texto	A explicação da recomendação, incluindo o resultado esperado depois que ela for aplicada. Essa coluna também contém o motivo e a justificativa da recomendação. Use esse contexto para ajustar a consulta conforme necessário e gerar recomendações novamente.
applied	Booleano	Mostra se a recomendação foi aplicada.
modified	Booleano	Mostra se a recomendação foi modificada pelo usuário.
created_at	Carimbo de data/hora com fuso horário	O horário em que a recomendação foi gerada.

vector_assist.get_recommendations

Retorna recomendações associadas a um vetor spec_id específico.

Função

CREATE OR REPLACE FUNCTION vector_assist.get_recommendations (
    spec_id TEXT
)
RETURNS SETOF vector_assist.RECOMMENDATIONS;

Parâmetros

Parâmetro	Obrigatório?	Descrição
spec_id	Obrigatório?	Recebe recomendações para o vetor spec_id especificado.

Valor de retorno

Retorna uma tabela de recomendações solicitadas.

A tabela de recomendações contém as seguintes colunas:

Nome da coluna	Tipo	Descrição
recommendation_id	Texto	O ID da recomendação. A recomendação é aplicada usando esse ID.
vector_spec_id	Texto	O ID da especificação de vetor associada à recomendação.
table_name	Texto	O nome da tabela associada à recomendação.
schema_name	Texto	O nome do esquema que contém a tabela especificada.
query	Texto	A consulta SQL executável que será executada para alcançar o resultado da recomendação.
recommendation	Texto	A explicação da recomendação, incluindo o resultado esperado depois que ela for aplicada. Essa coluna também contém o motivo e a justificativa da recomendação. Use esse contexto para ajustar a consulta conforme necessário e gerar recomendações novamente.
applied	Booleano	Mostra se a recomendação foi aplicada.
modified	Booleano	Mostra se a recomendação foi modificada pelo usuário.
created_at	Carimbo de data/hora com fuso horário	O horário em que a recomendação foi gerada.

vector_assist.apply_recommendation

Aplica uma única recomendação usando o recommendation_id.

Função

CREATE OR REPLACE FUNCTION vector_assist.get_recommendations (
    spec_id TEXT
)
RETURNS SETOF vector_assist.RECOMMENDATIONS;

Parâmetros

Parâmetro	Obrigatório?	Descrição
recommenation_id	Obrigatório?	O ID da recomendação de vetor a ser aplicada.

Valor de retorno

Retorna um booleano que confirma se uma recomendação foi aplicada com sucesso e atualiza a coluna applied da tabela vector_assist.RECOMMENDATIONS para TRUE.

Se o Vector Assist não conseguir aplicar a recomendação, uma mensagem de erro será exibida.

vector_assist.apply_spec

Aplica todas as recomendações associadas a um vetor spec_id ou nome de tabela específico. Essa função passa por todas as recomendações e executa a função vector_assist.apply_recommendation em cada uma delas.

É necessário especificar um spec_id ou table_name para executar a função.

Função

CREATE OR REPLACE FUNCTION vector_assist.apply_spec(
    spec_id TEXT DEFAULT NULL,
    table_name TEXT DEFAULT NULL,
    schema_name TEXT DEFAULT NULL,
    column_name TEXT DEFAULT NULL -- text_column_name or vector_column_name
)
RETURNS BOOLEAN;

Parâmetros

Parâmetro	Obrigatório?	Descrição
spec_id	Opcional	Aplica todas as recomendações ao vetor spec_id especificado.
table_name	Opcional	Aplica todas as recomendações à tabela especificada.
schema_name	Opcional	O esquema que contém a tabela especificada.
column_name	Opcional	Identifica o text_column_name ou vector_column_name a ser usado se a tabela contiver várias especificações de vetor.

Valor de retorno

Retorna um booleano que confirma se todas as recomendações foram aplicadas com sucesso e define o valor na coluna da tabela vector_assist.RECOMMENDATIONS applied como TRUE para todas as recomendações.

Se o Vector Assist não conseguir aplicar a recomendação, uma mensagem de erro será exibida.

vector_assist.modify_recommendation

Modifica a consulta de uma recomendação específica e define o campo modified na tabela vector_assist.RECOMMENDATIONS da recomendação associada como TRUE.

Função

CREATE OR REPLACE FUNCTION vector_assist.modify_recommendation(
    recommendation_id TEXT,
    modified_query TEXT
)
RETURNS BOOLEAN;

Parâmetros

Parâmetro	Obrigatório?	Descrição
recommendation_id	Obrigatório?	O ID da recomendação a ser modificada.
modified_query	Obrigatório?	Uma consulta SQL modificada pelo usuário para a recomendação.

Valor de retorno

Retorna um booleano que confirma se uma recomendação foi atualizada e define a coluna modified da tabela vector_assist.RECOMMENDATIONS como TRUE.

Se a assistência de vetor não conseguir atualizar a recomendação, uma mensagem de erro será exibida.

vector_assist.generate_query

Gera uma consulta de pesquisa de vetor otimizada com base na especificação de vetor definida e nos parâmetros de pesquisa. Essa função pode ajustar o valor ef_search para atender ao target_recall definido, se aplicável.

Função

CREATE OR REPLACE FUNCTION vector_assist.generate_query(
    spec_id TEXT DEFAULT NULL,
    table_name TEXT DEFAULT NULL,
    schema_name TEXT DEFAULT NULL,
    column_name TEXT DEFAULT NULL, -- text_column_name or vector_column_name of the spec
    search_text TEXT DEFAULT NULL,
    search_vector VECTOR DEFAULT NULL, -- e.g. '[1.0,2.0,3.0]'::vector
   output_column_names TEXT[] DEFAULT NULL, -- Columns to retrieve, NULL for SELECT *
    top_k INT DEFAULT NULL,
    filter_expressions TEXT[] DEFAULT NULL,
    target_recall FLOAT DEFAULT NULL, -- Inherited from spec, can be overridden
    iterative_index_search BOOL DEFAULT NULL
)
RETURNS TEXT; -- Returns the text representing the search query

Parâmetros

Parâmetro	Obrigatório?	Descrição
spec_id	Opcional	Especifica o spec_id para gerar a consulta.
table_name	Opcional	Especifica o nome da tabela para gerar a consulta de pesquisa se o spec_id não for fornecido. Se uma tabela tiver várias especificações, o parâmetro vai retornar um erro.
column_name	Opcional	Especifica o nome da coluna para gerar a consulta de pesquisa se o spec_id não for fornecido. Se a coluna tiver várias especificações, o parâmetro vai retornar um erro. O column_name pode ser o text_column_name ou o vector_column_name.
output_column_name	Opcional	Os nomes das colunas a serem recuperadas na consulta de saída. Para recuperar todas as colunas, defina esse parâmetro como NULL.
search_text	Opcional	O texto de pesquisa para gerar embeddings. Exige o embedding_model na especificação do vetor. O embedding é gerado usando o modelo da especificação. Só é possível definir o parâmetro search_text ou search_vector.
search_vector	Opcional	O vetor da consulta de pesquisa. Só é possível definir o parâmetro search_text ou search_vector.
top_k	Opcional	O número de vizinhos mais próximos a serem retornados.
filter_expressions	Opcional	As expressões de filtro a serem aplicadas na consulta de pesquisa. Os filtros podem ser aplicados a campos na tabela, como preço < 100.
iterative_index_search	Opcional	Define se uma pesquisa iterativa de índice será realizada para consultas filtradas.Esse parâmetro substitui as configurações na especificação do vetor.
target_recall	Opcional	A meta de recall apenas para a consulta de pesquisa. Esse parâmetro substitui as configurações na especificação do vetor e ajusta ef_search.

Valor de retorno

Retorna um texto que contém a consulta de pesquisa vetorial para os parâmetros especificados. Essa consulta pode ser executada ou salva para ser executada mais tarde.

vector_assist.evaluate_query_recall

Avalia o recall do índice de vetor para uma determinada consulta. Essa função usa as configurações de banco de dados e índice em uma string JSON como entradas.

Função

CREATE OR REPLACE FUNCTION vector_assist.evaluate_query_recall(
  IN ann_query text,
  IN vector_search_configurations json DEFAULT NULL,
  OUT recall float,
  OUT ann_execution_time float,
  OUT ground_truth_execution_time float,
  OUT index_type text)
RETURNS RECORD

Parâmetros

Parâmetro	Obrigatório?	Descrição
ann_query	Obrigatório?	A consulta SQL para a qual o recall precisa ser avaliado. Essa consulta precisa ser uma consulta de ANN pgvector.
vector_search_configurations	Opcional	As configurações que podem ser definidas para a consulta de ANN. Esse parâmetro precisa estar no formato JSON.

Valor de retorno

Retorna uma tabela que avalia o recall do índice vetorial para a consulta especificada.

A tabela contém as seguintes colunas:

Nome da coluna	Tipo	Descrição
recall	Ponto flutuante	A porcentagem de vetores que o índice retorna, que são verdadeiros vizinhos mais próximos. Essa métrica é usada para quantificar a qualidade da pesquisa. Com essa função, é possível ajustar os parâmetros para retornar os resultados esperados de recall da consulta de vetor.
ann_execution_time	Ponto flutuante	O tempo que uma consulta de vetor leva para ser executada usando verificações de índice.
ground_truth_execution_time	Ponto flutuante	O tempo que leva para a consulta ser executada usando uma verificação sequencial.

Exemplo

O exemplo a seguir avalia o recall de um índice HNSW e substitui o parâmetro de configuração HNSW.ef_search:

SELECT * FROM vector_assist.evaluate_query_recall(
  ann_query => 'SELECT id FROM items ORDER BY embedding <=> ''[1,2,3]'' LIMIT 10',
  vector_search_configurations => '{"hnsw.ef_search": 30}'
);