Riferimento per l'assistenza vettoriale

MySQL   |  PostgreSQL   |  SQL Server

Anteprima — Vector Assist

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. Puoi accedere ai dati personali per questa funzionalità come indicato nell' Addendum per il trattamento dei dati Cloud, fatti salvi gli obblighi e le restrizioni all'interno dell'accordo che regola l'accesso a Google Cloud. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni delle fasi di lancio.

Questa pagina fornisce informazioni dettagliate su tutte le funzioni di assistenza vettoriale disponibili e sui relativi parametri obbligatori e facoltativi.

vector_assist.define_spec

Definisce una nuova specifica del vettore o specifica del vettore e restituisce i suggerimenti necessari per aumentare il carico di lavoro del vettore. Questa funzione applica le specifiche fornite dall'utente per generare i consigli.

Funzione

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;

Parametri

Parametro	Obbligatorio?	Descrizione
spec_id	Obbligatorio (generato automaticamente)	Un ID univoco per la specifica del vettore che definisci.
table_name	Obbligatorio?	Il nome della tabella da utilizzare nella configurazione del workload vettoriale.
schema_name	Facoltativo	Lo schema contenente la tabella da utilizzare nel workload vettoriale. Lo schema viene dedotto automaticamente in base al percorso di ricerca dello schema.
vector_column_name	Obbligatorio o facoltativo	Il nome della colonna contenente gli embedding vettoriali. Questa colonna è obbligatoria se utilizzi più di una colonna vettoriale e text_column_name non è dichiarato. Se utilizzi una sola colonna vettoriale, questo parametro è facoltativo.
text_column_name	Obbligatorio o facoltativo	Il nome della colonna di testo. Se il tuo workload vettoriale richiede la generazione di incorporamenti da una colonna di testo, questo parametro è obbligatorio. Questa colonna è obbligatoria se il parametro vector_column_name è NULL e non sono presenti altre colonne vettoriali. Questo parametro utilizza l'estensione google_ml_integration per generare incorporamenti dalla colonna di testo specificata.
vector_index_type	Facoltativo	Il tipo di indice vettoriale. I valori accettabili includono: HNSW IVFFlat SCANN
embeddings_available	Facoltativo	Un valore booleano che verifica se gli incorporamenti vettoriali esistono nella tabella selezionata. Questo campo è impostato su FALSE se non vengono rilevate colonne vettoriali e il parametro text_column_name è impostato.
embedding_model	Obbligatorio o facoltativo	L'ID modello di google_ml.models da utilizzare per generare gli embedding. Questo campo è facoltativo, a meno che il parametro embeddings_available non sia FALSE o NULL.
num_vectors	Facoltativo	Il numero di vettori nella tabella.
dismensionality	Facoltativo	La dimensione dei vettori specificati.
distance_func	Facoltativo	La funzione di distanza da utilizzare per confrontare il vettore. I valori accettabili includono cosine, ip, l2 o l1.
quantization	Facoltativo	La quantizzazione per gli indici dei vettori. I valori accettabili includono none, halfvec o bit.
prefilter_column_names	Facoltativo	Crea un indice per la colonna specificata per il prefiltraggio. Ciò potrebbe contribuire a migliorare il rendimento delle query con un filtro di selettività elevata sulla colonna.
memory_budget_kb	Facoltativo	La memoria massima (in KB) per la creazione dell'indice.
target_recall	Facoltativo	Il richiamo target per le query sui vettori standard.
target_top_k	Facoltativo	I primi K valori corrispondenti da recuperare per il calcolo del richiamo. Questo valore viene utilizzato se viene specificato il parametro target_recall.
tune_vector_index	Facoltativo	Ottimizza gli indici vettoriali nel tuo workload. Se abilitata, l'assistenza vettoriale sintonizza automaticamente l'indice vettoriale o la query di ricerca utilizzando la specifica del vettore e calcola i parametri ottimali del database e dell'indice. I valori accettabili includono TRUE o FALSE.

Valore restituito

Restituisce una tabella di consigli che devono essere applicati per configurare il workload vettoriale richiesto. Ogni riga è un singolo consiglio che contiene una query SQL eseguibile e una spiegazione dettagliata del motivo per cui applicare il consiglio. Il consiglio può essere applicato utilizzando la funzione apply_recommendation().

Nota: questa funzione è un'operazione a lunga esecuzione (LRO). Se utilizzi un client con un timeout (ad esempio Cloud SQL Studio con un timeout di 5 minuti), la chiamata di funzione potrebbe essere terminata. Per risolvere questo problema, puoi aumentare la soglia di timeout o creare una copia della tabella che stai utilizzando con solo un sottoinsieme di dati per soddisfare i requisiti di timeout.

La tabella dei consigli contiene le seguenti colonne:

Nome colonna	Tipo	Descrizione
recommendation_id	Testo	L'ID del consiglio. Il suggerimento viene applicato utilizzando questo ID.
vector_spec_id	Testo	L'ID della specifica del vettore associata al consiglio.
table_name	Testo	Il nome della tabella associata al suggerimento.
schema_name	Testo	Il nome dello schema contenente la tabella specificata.
query	Testo	La query SQL eseguibile da eseguire per ottenere il risultato del suggerimento.
recommendation	Testo	La spiegazione del consiglio, incluso il risultato previsto una volta applicato. Questa colonna contiene anche il motivo e la logica del suggerimento. Puoi utilizzare questo contesto per perfezionare la query in base alle esigenze e rigenerare i consigli.
applied	Booleano	Indica se il consiglio è stato applicato.
modified	Booleano	Indica se il consiglio è stato modificato dall'utente.
created_at	Timestamp con fuso orario	L'ora in cui è stato generato il consiglio nel formato timestamp with time zone. Ad esempio, 2024-07-18 09:00:00-08.

vector_assist.list_specs

Restituisce la specifica del vettore corrente per una determinata tabella e colonna.

Funzione

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

Parametri

Parametro	Obbligatorio?	Descrizione
table_name	Obbligatorio?	Il nome della tabella per cui viene recuperata la specifica del vettore.
column_name	Facoltativo	Il nome della colonna su cui filtrare la tabella prima di restituire la specifica. Se il nome della colonna è specificato, vengono restituite le specifiche che contengono nomi di colonne di testo o vettoriali che corrispondono a questo nome di colonna.

Valore restituito

Restituisce una tabella di specifiche per la tabella specificata e, facoltativamente, il nome della colonna.

vector_assist.modify_spec

Modifica una specifica vettoriale esistente. Quando la specifica vettoriale viene modificata, i suggerimenti associati vengono rigenerati in base alle nuove specifiche.

Funzione

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

Parametri

Parametro	Obbligatorio?	Descrizione
spec_id	Obbligatorio (generato automaticamente)	Un ID univoco per la specifica del vettore che definisci.
table_name	Obbligatorio?	Il nome della tabella da utilizzare nella configurazione del workload vettoriale.
schema_name	Facoltativo	Lo schema contenente la tabella da utilizzare nel workload vettoriale. Lo schema viene dedotto automaticamente in base al percorso di ricerca dello schema.
vector_column_name	Obbligatorio o facoltativo	Il nome della colonna contenente gli embedding vettoriali. Questa colonna è obbligatoria se utilizzi più di una colonna vettoriale e text_column_name non è dichiarato. Se utilizzi una sola colonna vettoriale, questo parametro è facoltativo.
text_column_name	Obbligatorio o facoltativo	Il nome della colonna di testo. Se il tuo workload vettoriale richiede la generazione di incorporamenti da una colonna di testo, questo parametro è obbligatorio. Questa colonna è obbligatoria se il parametro vector_column_name è NULL e non sono presenti altre colonne vettoriali. Questo parametro utilizza l'estensione google_ml_integration per generare incorporamenti dalla colonna di testo specificata.
vector_index_type	Facoltativo	Il tipo di indice vettoriale. I valori accettabili includono: HNSW IVFFlat SCANN
embeddings_available	Facoltativo	Un valore booleano che verifica se gli incorporamenti vettoriali esistono nella tabella selezionata. Questo campo è impostato su FALSE se non vengono rilevate colonne vettoriali e il parametro text_column_name è impostato.
embedding_model	Obbligatorio o facoltativo	L'ID modello di google_ml.models da utilizzare per generare gli embedding. Questo campo è facoltativo, a meno che il parametro embeddings_available non sia FALSE o NULL.
num_vectors	Facoltativo	Il numero di vettori nella tabella.
dismensionality	Facoltativo	La dimensione dei vettori specificati.
distance_func	Facoltativo	La funzione di distanza da utilizzare per confrontare il vettore. I valori accettabili includono cosine, ip, l2 o l1.
quantization	Facoltativo	La quantizzazione per gli indici dei vettori. I valori accettabili includono none, halfvec o bit.
prefilter_column_names	Facoltativo	Identifica le colonne rese disponibili per il prefiltraggio nelle query di ricerca vettoriale.
memory_budget_kb	Facoltativo	La memoria massima (in KB) per la creazione dell'indice.
target_recall	Facoltativo	Il richiamo target per le query sui vettori standard.
target_top_k	Facoltativo	I primi K valori corrispondenti da recuperare per il calcolo del richiamo. Questo valore viene utilizzato se viene specificato il parametro target_recall.
tune_vector_index	Facoltativo	Ottimizza gli indici vettoriali nel tuo workload. Se abilitata, l'assistenza vettoriale sintonizza automaticamente l'indice vettoriale o la query di ricerca utilizzando la specifica del vettore e calcola i parametri ottimali del database e dell'indice. I valori accettabili includono TRUE o FALSE.

Valore restituito

Restituisce una tabella aggiornata di consigli che devono essere applicati per configurare il carico di lavoro vettoriale richiesto. Ogni riga è un singolo consiglio che contiene una query SQL eseguibile e una spiegazione dettagliata del motivo per cui applicare il consiglio. Il consiglio può essere applicato utilizzando la funzione apply_recommendation().

La tabella dei consigli contiene le seguenti colonne:

Nome colonna	Tipo	Descrizione
recommendation_id	Testo	L'ID del consiglio. Il suggerimento viene applicato utilizzando questo ID.
vector_spec_id	Testo	L'ID della specifica del vettore associata al consiglio.
table_name	Testo	Il nome della tabella associata al suggerimento.
schema_name	Testo	Il nome dello schema contenente la tabella specificata.
query	Testo	La query SQL eseguibile da eseguire per ottenere il risultato del suggerimento.
recommendation	Testo	La spiegazione del consiglio, incluso il risultato previsto una volta applicato. Questa colonna contiene anche il motivo e la logica del suggerimento. Puoi utilizzare questo contesto per perfezionare la query in base alle esigenze e rigenerare i consigli.
applied	Booleano	Indica se il consiglio è stato applicato.
modified	Booleano	Indica se il consiglio è stato modificato dall'utente.
created_at	Timestamp con fuso orario	L'ora in cui è stato generato il consiglio.

vector_assist.get_recommendations

Restituisce i consigli associati a un vettore specifico spec_id.

Funzione

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

Parametri

Parametro	Obbligatorio?	Descrizione
spec_id	Obbligatorio?	Recupera i suggerimenti per il vettore specificato spec_id.

Valore restituito

Restituisce una tabella dei consigli richiesti.

La tabella dei consigli contiene le seguenti colonne:

Nome colonna	Tipo	Descrizione
recommendation_id	Testo	L'ID del consiglio. Il suggerimento viene applicato utilizzando questo ID.
vector_spec_id	Testo	L'ID della specifica del vettore associata al consiglio.
table_name	Testo	Il nome della tabella associata al suggerimento.
schema_name	Testo	Il nome dello schema contenente la tabella specificata.
query	Testo	La query SQL eseguibile da eseguire per ottenere il risultato del suggerimento.
recommendation	Testo	La spiegazione del consiglio, incluso il risultato previsto una volta applicato. Questa colonna contiene anche il motivo e la logica del suggerimento. Puoi utilizzare questo contesto per perfezionare la query in base alle esigenze e rigenerare i consigli.
applied	Booleano	Indica se il consiglio è stato applicato.
modified	Booleano	Indica se il consiglio è stato modificato dall'utente.
created_at	Timestamp con fuso orario	L'ora in cui è stato generato il consiglio.

vector_assist.apply_recommendation

Applica un singolo consiglio utilizzando recommendation_id.

Funzione

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

Parametri

Parametro	Obbligatorio?	Descrizione
recommenation_id	Obbligatorio?	L'ID del suggerimento vettoriale da applicare.

Valore restituito

Restituisce un valore booleano che conferma se un suggerimento è stato applicato correttamente e aggiorna la colonna della tabella vector_assist.RECOMMENDATIONS applied a TRUE.

Se l'assistenza vettoriale non riesce ad applicare il suggerimento, viene visualizzato un messaggio di errore.

vector_assist.apply_spec

Applica tutti i consigli associati a un vettore spec_id o a un nome di tabella specifico. Questa funzione esamina tutti i suggerimenti ed esegue la funzione vector_assist.apply_recommendation su ciascun suggerimento.

Devi specificare spec_id o table_name per eseguire la funzione.

Funzione

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;

Parametri

Parametro	Obbligatorio?	Descrizione
spec_id	Facoltativo	Applica tutti i consigli per il vettore specificato spec_id.
table_name	Facoltativo	Applica tutti i suggerimenti per la tabella specificata.
schema_name	Facoltativo	Lo schema contenente la tabella specificata.
column_name	Facoltativo	Identifica text_column_name o vector_column_name da utilizzare se la tabella contiene più specifiche del vettore.

Valore restituito

Restituisce un valore booleano che conferma se tutti i consigli sono stati applicati correttamente e imposta il valore nella colonna della tabella vector_assist.RECOMMENDATIONS applied su TRUE per tutti i consigli.

Se l'assistenza vettoriale non riesce ad applicare il suggerimento, viene visualizzato un messaggio di errore.

vector_assist.modify_recommendation

Modifica la query per un suggerimento specifico e imposta il campo modified nella tabella vector_assist.RECOMMENDATIONS per il suggerimento associato su TRUE.

Funzione

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

Parametri

Parametro	Obbligatorio?	Descrizione
recommendation_id	Obbligatorio?	L'ID del consiglio da modificare.
modified_query	Obbligatorio?	Una query SQL modificata dall'utente per il suggerimento.

Valore restituito

Restituisce un valore booleano che conferma se un suggerimento è stato aggiornato correttamente e imposta la colonna della tabella vector_assist.RECOMMENDATIONS modified su TRUE.

Se l'assistenza vettoriale non riesce ad aggiornare il consiglio, viene visualizzato un messaggio di errore in caso di errore.

vector_assist.generate_query

Genera una query di ricerca vettoriale ottimizzata in base alla specifica del vettore definita e ai parametri di ricerca. Questa funzione potrebbe modificare il valore di ef_search per soddisfare il valore di target_recall impostato, se applicabile.

Funzione

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

Parametri

Parametro	Obbligatorio?	Descrizione
spec_id	Facoltativo	Specifica il spec_id per cui generare la query.
table_name	Facoltativo	Specifica il nome della tabella per generare la query di ricerca se spec_id non è fornito. Se una tabella contiene più specifiche, il parametro restituisce un errore.
column_name	Facoltativo	Specifica il nome della colonna per generare la query di ricerca se spec_id non viene fornito. Se la colonna contiene più specifiche, il parametro restituisce un errore. column_name potrebbe essere text_column_name o vector_column_name.
output_column_name	Facoltativo	I nomi delle colonne da recuperare nella query di output. Per recuperare tutte le colonne, imposta questo parametro su NULL.
search_text	Facoltativo	Il testo di ricerca per cui generare gli incorporamenti. Richiede embedding_model nella specifica del vettore. L'embedding viene generato utilizzando il modello della specifica. Puoi impostare solo il parametro search_text o search_vector.
search_vector	Facoltativo	Il vettore per la query di ricerca. Puoi impostare solo il parametro search_text o search_vector
top_k	Facoltativo	Il numero di vicini più vicini da restituire.
filter_expressions	Facoltativo	Le espressioni di filtro da applicare nella query di ricerca. I filtri possono essere applicati ai campi della tabella, ad esempio prezzo < 100.
iterative_index_search	Facoltativo	Imposta se eseguire la ricerca iterativa dell'indice per le query filtrate.Questo parametro sostituisce le impostazioni nella specifica del vettore.
target_recall	Facoltativo	Il richiamo target solo per la query di ricerca. Questo parametro sostituisce le impostazioni nella specifica del vettore e regola ef_search.

Valore restituito

Restituisce un testo contenente la query di ricerca vettoriale per i parametri specificati. Questa query può essere eseguita o salvata per essere eseguita in un secondo momento.

vector_assist.evaluate_query_recall

Valuta il richiamo dell'indice vettoriale per una determinata query. Questa funzione utilizza come input le configurazioni di database e indice in una stringa JSON.

Funzione

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

Parametri

Parametro	Obbligatorio?	Descrizione
ann_query	Obbligatorio?	La query SQL per la quale deve essere valutato il richiamo. Questa query deve essere una query pgvector ANN.
vector_search_configurations	Facoltativo	Le configurazioni che possono essere impostate per la query ANN. Questo parametro deve essere in formato JSON.

Valore restituito

Restituisce una tabella che valuta il richiamo dell'indice vettoriale per la query specificata.

La tabella contiene le seguenti colonne:

Nome colonna	Tipo	Descrizione
recall	Numero in virgola mobile	La percentuale di vettori restituiti dall'indice che sono i vicini più prossimi effettivi. Questa metrica viene utilizzata per quantificare la qualità della ricerca. Questa funzione consente di ottimizzare i parametri per restituire i risultati di recupero della query vettoriale previsti.
ann_execution_time	Numero in virgola mobile	Il tempo necessario per eseguire una query vettoriale utilizzando le scansioni dell'indice.
ground_truth_execution_time	Numero in virgola mobile	Il tempo necessario per l'esecuzione della query utilizzando una scansione sequenziale.

Esempio

L'esempio seguente valuta il richiamo per un indice HNSW e sostituisce il parametro di configurazione 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}'
);