Referência de assistência vetorial

MySQL   |  PostgreSQL   |  SQL Server

Pré-visualização — Vector Assist

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. Pode tratar dados pessoais para esta funcionalidade conforme descrito na Alteração ao Tratamento de Dados do Cloud, sujeita às obrigações e restrições descritas no contrato ao abrigo do qual acede ao Google Cloud. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. 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 respetivos parâmetros obrigatórios e opcionais.

vector_assist.define_spec

Define uma nova especificação de vetor, ou especificação de vetor, e devolve as recomendações necessárias para aumentar a carga de trabalho do vetor. Esta função aplica as especificações fornecidas pelos utilizadores 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 do vetor que definir.
table_name	Obrigatório?	O nome da tabela a usar na configuração da carga de trabalho de vetores.
schema_name	Opcional	O esquema que contém a tabela a usar na carga de trabalho vetorial. 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 as incorporações de vetores. Esta coluna é obrigatória se estiver a usar mais do que uma coluna de vetor e o text_column_name não estiver declarado. Se estiver a usar apenas uma coluna de vetor, este parâmetro é opcional.
text_column_name	Opcional ou obrigatório	O nome da coluna de texto. Se a sua carga de trabalho vetorial exigir a geração de incorporações a partir de uma coluna de texto, este parâmetro é obrigatório. Esta coluna é obrigatória se o parâmetro vector_column_name for NULL e não existirem outras colunas de vetores. Este parâmetro usa a extensão google_ml_integration para gerar incorporações a partir da coluna de texto fornecida.
vector_index_type	Opcional	O tipo de índice vetorial. Os valores aceitáveis incluem: HNSW IVFFlat SCANN
embeddings_available	Opcional	Um valor booleano que verifica se existem incorporações de vetores na tabela selecionada. Este campo está definido como FALSE se não forem detetadas colunas de vetores e o parâmetro text_column_name estiver definido.
embedding_model	Opcional ou obrigatório	O ID do modelo de google_ml.models a usar para gerar as incorporações. Este campo é opcional, exceto se o parâmetro embeddings_available for 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 usar para comparar o vetor. Os valores aceitáveis incluem cosine, ip, l2 ou l1.
quantization	Opcional	A quantização para os índices de vetores. Os valores aceitáveis incluem none, halfvec ou bit.
prefilter_column_names	Opcional	Cria um índice para a coluna especificada para pré-filtragem. Isto pode ajudar a melhorar o desempenho das consultas com um filtro de seletividade elevado na coluna.
memory_budget_kb	Opcional	A memória máxima (em KB) para a criação de índices.
target_recall	Opcional	A capacidade de memorização alvo para consultas de vetores padrão.
target_top_k	Opcional	Os valores correspondentes principais de K a obter para o cálculo da capacidade de memorização. Este valor é usado se o parâmetro target_recall for especificado.
tune_vector_index	Opcional	Ajusta os índices vetoriais na sua carga de trabalho. Se estiver ativado, o vetor assist ajusta automaticamente o índice de vetores ou a consulta de pesquisa através da especificação de vetores e calcula os parâmetros ideais da base de dados e do índice. Os valores aceitáveis incluem TRUE ou FALSE.

Valor devolvido

Devolve uma tabela de recomendações que têm de ser aplicadas para configurar a carga de trabalho de vetores pedida. Cada linha é uma única recomendação que contém uma consulta SQL executável e uma explicação detalhada do motivo pelo qual deve aplicar a recomendação. A recomendação pode ser aplicada através da função apply_recommendation().

Nota: esta função é uma operação de longa duração (LRO). Se estiver a usar um cliente com um limite de tempo (como o Cloud SQL Studio com um limite de tempo de 5 minutos), a chamada de função pode ser terminada. Para mitigar este problema, pode aumentar o limite de tempo limite ou criar uma cópia da tabela que está a usar apenas com um subconjunto de dados para cumprir os 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 através deste ID.
vector_spec_id	Texto	O ID da especificação do vetor associada à recomendação.
table_name	Texto	O nome da tabela associado à recomendação.
schema_name	Texto	O nome do esquema que contém a tabela especificada.
query	Texto	A consulta SQL executável a ser executada para alcançar o resultado da recomendação.
recommendation	Texto	A explicação da recomendação, incluindo o resultado esperado assim que a recomendação for aplicada. Esta coluna também contém o motivo e a justificação da recomendação. Pode usar este contexto para ajustar a consulta conforme necessário e regenerar as recomendações.
applied	Booleano	Mostra se a recomendação foi aplicada.
modified	Booleano	Mostra se a recomendação foi modificada pelo utilizador.
created_at	Indicação de tempo com fuso horário	A hora 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

Devolve a especificação do 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 a qual a especificação do vetor é obtida.
column_name	Opcional	O nome da coluna na qual filtrar a tabela antes de devolver a especificação. Se o nome da coluna for especificado, são devolvidas as especificações que contêm nomes de colunas de texto ou vetoriais que correspondem a este nome de coluna.

Valor devolvido

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

vector_assist.modify_spec

Modifica uma especificação de vetor existente. 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 do vetor que definir.
table_name	Obrigatório?	O nome da tabela a usar na configuração da carga de trabalho de vetores.
schema_name	Opcional	O esquema que contém a tabela a usar na carga de trabalho vetorial. 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 as incorporações de vetores. Esta coluna é obrigatória se estiver a usar mais do que uma coluna de vetor e o text_column_name não estiver declarado. Se estiver a usar apenas uma coluna de vetor, este parâmetro é opcional.
text_column_name	Opcional ou obrigatório	O nome da coluna de texto. Se a sua carga de trabalho vetorial exigir a geração de incorporações a partir de uma coluna de texto, este parâmetro é obrigatório. Esta coluna é obrigatória se o parâmetro vector_column_name for NULL e não existirem outras colunas de vetores. Este parâmetro usa a extensão google_ml_integration para gerar incorporações a partir da coluna de texto fornecida.
vector_index_type	Opcional	O tipo de índice vetorial. Os valores aceitáveis incluem: HNSW IVFFlat SCANN
embeddings_available	Opcional	Um valor booleano que verifica se existem incorporações de vetores na tabela selecionada. Este campo está definido como FALSE se não forem detetadas colunas de vetores e o parâmetro text_column_name estiver definido.
embedding_model	Opcional ou obrigatório	O ID do modelo de google_ml.models a usar para gerar as incorporações. Este campo é opcional, exceto se o parâmetro embeddings_available for 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 usar para comparar o vetor. Os valores aceitáveis incluem cosine, ip, l2 ou l1.
quantization	Opcional	A quantização para os índices de vetores. 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	A capacidade de memorização alvo para consultas de vetores padrão.
target_top_k	Opcional	Os valores correspondentes principais de K a obter para o cálculo da capacidade de memorização. Este valor é usado se o parâmetro target_recall for especificado.
tune_vector_index	Opcional	Ajusta os índices vetoriais na sua carga de trabalho. Se estiver ativado, o vetor assist ajusta automaticamente o índice de vetores ou a consulta de pesquisa através da especificação de vetores e calcula os parâmetros ideais da base de dados e do índice. Os valores aceitáveis incluem TRUE ou FALSE.

Valor devolvido

Devolve uma tabela atualizada de recomendações que têm de ser aplicadas para configurar a carga de trabalho vetorial pedida. Cada linha é uma única recomendação que contém uma consulta SQL executável e uma explicação detalhada do motivo pelo qual deve aplicar a recomendação. A recomendação pode ser aplicada através da 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 através deste ID.
vector_spec_id	Texto	O ID da especificação do vetor associada à recomendação.
table_name	Texto	O nome da tabela associado à recomendação.
schema_name	Texto	O nome do esquema que contém a tabela especificada.
query	Texto	A consulta SQL executável a ser executada para alcançar o resultado da recomendação.
recommendation	Texto	A explicação da recomendação, incluindo o resultado esperado assim que a recomendação for aplicada. Esta coluna também contém o motivo e a justificação da recomendação. Pode usar este contexto para ajustar a consulta conforme necessário e regenerar as recomendações.
applied	Booleano	Mostra se a recomendação foi aplicada.
modified	Booleano	Mostra se a recomendação foi modificada pelo utilizador.
created_at	Indicação de tempo com fuso horário	A hora em que a recomendação foi gerada.

vector_assist.get_recommendations

Devolve recomendações associadas a um vetor específico spec_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
spec_id	Obrigatório?	Recebe recomendações para o vetor especificado spec_id.

Valor devolvido

Devolve uma tabela de recomendações pedidas.

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 através deste ID.
vector_spec_id	Texto	O ID da especificação do vetor associada à recomendação.
table_name	Texto	O nome da tabela associado à recomendação.
schema_name	Texto	O nome do esquema que contém a tabela especificada.
query	Texto	A consulta SQL executável a ser executada para alcançar o resultado da recomendação.
recommendation	Texto	A explicação da recomendação, incluindo o resultado esperado assim que a recomendação for aplicada. Esta coluna também contém o motivo e a justificação da recomendação. Pode usar este contexto para ajustar a consulta conforme necessário e regenerar as recomendações.
applied	Booleano	Mostra se a recomendação foi aplicada.
modified	Booleano	Mostra se a recomendação foi modificada pelo utilizador.
created_at	Indicação de tempo com fuso horário	A hora em que a recomendação foi gerada.

vector_assist.apply_recommendation

Aplica uma única recomendação através do 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 vetorial a aplicar.

Valor devolvido

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

Se a assistência vetorial não conseguir aplicar a recomendação, apresenta uma mensagem de erro em caso de falha.

vector_assist.apply_spec

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

Tem de especificar um spec_id ou um 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 para o vetor fornecido spec_id.
table_name	Opcional	Aplica todas as recomendações para a tabela especificada.
schema_name	Opcional	O esquema que contém a tabela especificada.
column_name	Opcional	Identifica o text_column_name ou o vector_column_name a usar se a tabela contiver várias especificações de vetores.

Valor devolvido

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

Se a assistência vetorial não conseguir aplicar a recomendação, apresenta uma mensagem de erro em caso de falha.

vector_assist.modify_recommendation

Modifica a consulta para uma recomendação específica e define o campo modified na tabela vector_assist.RECOMMENDATIONS para a 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 modificar.
modified_query	Obrigatório?	Uma consulta SQL modificada pelo utilizador para a recomendação.

Valor devolvido

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

Se a assistência vetorial não conseguir atualizar a recomendação, apresenta uma mensagem de erro em caso de falha.

vector_assist.generate_query

Gera uma consulta de pesquisa vetorial otimizada com base na especificação vetorial definida e nos parâmetros de pesquisa. Esta função pode ajustar o valor ef_search para cumprir o valor 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 o qual gerar a consulta.
table_name	Opcional	Especifica o nome da tabela para gerar a consulta de pesquisa se o elemento spec_id não for fornecido. Se uma tabela contiver várias especificações, o parâmetro devolve um erro.
column_name	Opcional	Especifica o nome da coluna para gerar a consulta de pesquisa se o elemento spec_id não for fornecido. Se a coluna contiver várias especificações, o parâmetro devolve 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 obter na consulta de saída. Para obter todas as colunas, defina este parâmetro como NULL.
search_text	Opcional	O texto de pesquisa para o qual gerar incorporações. Requer o elemento embedding_model na especificação do vetor. A incorporação é gerada através do modelo da especificação. Só pode definir o parâmetro search_text ou o parâmetro search_vector.
search_vector	Opcional	O vetor da consulta de pesquisa. Só pode definir o parâmetro search_text ou search_vector
top_k	Opcional	O número de vizinhos mais próximos a devolver.
filter_expressions	Opcional	As expressões de filtro a aplicar na consulta de pesquisa. Os filtros podem ser aplicados a campos na tabela, como preço < 100.
iterative_index_search	Opcional	Define se deve realizar uma pesquisa de índice iterativa para consultas filtradas.Este parâmetro substitui as definições na especificação do vetor.
target_recall	Opcional	A taxa de rejeição alvo apenas para a consulta de pesquisa. Este parâmetro substitui as definições na especificação do vetor e ajusta ef_search.

Valor devolvido

Devolve um texto que contém a consulta de pesquisa vetorial para os parâmetros especificados. Esta consulta pode ser executada ou guardada para execução posterior.

vector_assist.evaluate_query_recall

Avalia a capacidade de recall do índice de vetores para uma determinada consulta. Esta função usa as configurações da base de dados e do índice numa 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 a capacidade de memorização tem de ser avaliada. Esta consulta deve ser uma pgvector consulta ANN.
vector_search_configurations	Opcional	As configurações que podem ser definidas para a consulta de ANN. Este parâmetro tem de estar no formato JSON.

Valor devolvido

Devolve uma tabela que avalia a capacidade de memorização do índice de vetores para a consulta especificada.

A tabela contém as seguintes colunas:

Nome da coluna	Tipo	Descrição
recall	Flutuante	A percentagem de vetores que o índice devolve, que são verdadeiros vizinhos mais próximos. Esta métrica é usada para quantificar a qualidade da pesquisa. Esta função permite ajustar os parâmetros para devolver os resultados de recolha de consultas de vetores esperados.
ann_execution_time	Flutuante	O tempo que uma consulta vetorial demora a ser executada através de análises de índice.
ground_truth_execution_time	Flutuante	O tempo que a consulta demora a ser executada através de uma análise sequencial.

Exemplo

O exemplo seguinte avalia a capacidade de memorização para 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}'
);