向量輔助函式參照

選取文件版本： 18.4.0

• 目前 (18.4.0)
• 18.4.0
• 18.3.0
• 18.1.1
• 18.1.0

請參考下列詳細的向量輔助函式，簡化 AlloyDB Omni 向量工作負載。

vector_assist.define_spec

定義新的向量規格 (vector spec)，並傳回提升向量工作負載所需的建議。這項函式會套用使用者提供的規格來產生建議。

注意： 這項函式是長時間執行的作業 (LRO)。如果您使用的用戶端有逾時限制 (例如 AlloyDB Omni Studio 的逾時限制為 5 分鐘)，函式呼叫可能會終止。如要解決這個問題，您可以提高逾時門檻，或是複製您使用的資料表，只保留部分資料，以符合逾時規定。

函式

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;

參數

參數	是否必要	說明
spec_id	選用，如未提供，系統會自動生成	您定義的向量規格專屬 ID。
table_name	必填	用於向量工作負載設定的資料表名稱。
schema_name	選用	這個結構定義包含要用於向量工作負載的資料表。系統會根據結構定義搜尋路徑，自動推論結構定義。
vector_column_name	查看說明	含有向量嵌入的資料欄名稱。 如果使用多個向量資料欄，且未宣告 text_column_name，則必須提供這個資料欄。如果只使用一個向量資料欄，則可選擇是否要提供這個參數。
text_column_name	查看說明	文字資料欄的名稱。如果向量工作負載需要從文字資料欄生成嵌入，則必須提供這個參數。 如果 vector_column_name 參數為 NULL，且沒有其他向量資料欄，則必須提供這個資料欄。 這個參數會使用 google_ml_integration 擴充功能，從指定的文字欄產生嵌入。
vector_index_type	選用	向量索引的類型。可接受的值包括： (預設) HNSW IVFFlat
embeddings_available	選用	布林值，用於檢查所選資料表中是否存在向量嵌入。如果未偵測到任何向量資料欄，且已設定 text_column_name 參數，這個欄位會設為 FALSE。
embedding_model	查看說明	用於生成嵌入的模型 ID。除非 embeddings_available 參數為 FALSE 或 NULL，否則這個欄位為選填。預設值為 text-embedding-005。
num_vectors	選用	資料表中的向量數量。
dismensionality	選用	指定向量的維度。
distance_func	選用	用來比較向量的距離函式。可接受的值包括： cosine：如果 quantization 未設為 bit，則為預設值 ip l2 l1 jaccard hamming：當 quantization 設為 bit 時的預設值
quantization	選用	向量索引的量化。可接受的值包括： none：當 dimensionality 小於 2000 時的預設值 halfvec：dimensionality 介於 2000 和 4000 之間時的預設值 bit：dimensionality 大於 4,000 時的預設值
prefilter_column_names	選用	建議為指定資料欄建立索引，以便預先篩選。這可能有助於提高對資料欄套用高選擇性篩選器的查詢效能。
memory_budget_kb	選用	建立索引時的記憶體上限 (以 KB 為單位)。預設值為執行個體記憶體的 60%。
target_recall	選用	標準向量查詢的目標召回率。
target_top_k	選用	要擷取的 Top-K 比對值，用於計算召回率。 如果指定 target_recall 參數，系統就會使用這個值。
tune_vector_index	選用	調整工作負載中的向量索引。啟用後，向量輔助功能會使用向量規格，自動調整向量索引和搜尋查詢，以達到目標喚回度，並計算最佳資料庫和索引參數。可接受的值包括： (預設) FALSE：僅調整搜尋 (ef_search) 參數。系統會使用預設的索引建構時間 (m、ef_construction) 參數值。 TRUE：調整搜尋和索引建構時間參數。

傳回值

傳回建議表格，其中包含新建立的向量規格 ID。

vector_assist.list_specs

傳回指定資料表和資料欄的目前向量規格。

函式

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

參數

參數	是否必要	說明
table_name	必填	要擷取向量規格的資料表名稱。
column_name	選用	在傳回規格前，用於篩選資料表的資料欄名稱。如果指定資料欄名稱，系統會傳回文字或向量資料欄名稱與這個資料欄名稱相符的規格。

傳回值

傳回指定資料表的規格表，並視需要傳回資料欄名稱。

vector_assist.modify_spec

修改現有的向量規格。修改向量規格後，系統會根據新規格重新產生相關建議。

函式

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

參數

參數	是否必要	說明
spec_id	必填	您定義的向量規格專屬 ID。
table_name	必填	用於向量工作負載設定的資料表名稱。
schema_name	選用	這個結構定義包含要用於向量工作負載的資料表。系統會根據結構定義搜尋路徑，自動推論結構定義。
vector_column_name	查看說明	含有向量嵌入的資料欄名稱。 如果使用多個向量資料欄，且未宣告 text_column_name，則必須提供這個資料欄。如果只使用一個向量資料欄，則可選擇是否要提供這個參數。
text_column_name	查看說明	文字資料欄的名稱。如果向量工作負載需要從文字資料欄生成嵌入，則必須提供這個參數。 如果 vector_column_name 參數為 NULL，且沒有其他向量資料欄，則必須提供這個資料欄。 這個參數會使用 google_ml_integration 擴充功能，從指定的文字欄產生嵌入。
vector_index_type	選用	向量索引的類型。可接受的值包括： HNSW IVFFlat
embeddings_available	選用	布林值，用於檢查所選資料表中是否存在向量嵌入。如果未偵測到任何向量資料欄，且已設定 text_column_name 參數，這個欄位會設為 FALSE。
embedding_model	查看說明	用於生成嵌入的模型 ID。除非 embeddings_available 參數為 FALSE 或 NULL，否則這個欄位為選填。預設值為 text-embedding-005。
num_vectors	選用	資料表中的向量數量。
dismensionality	選用	指定向量的維度。
distance_func	選用	用來比較向量的距離函式。可接受的值包括 cosine、ip、l2 或 l1。
quantization	選用	向量索引的量化。可接受的值包括 none、halfvec 或 bit。
prefilter_column_names	選用	識別可在向量搜尋查詢中預先篩選的資料欄。
memory_budget_kb	選用	建立索引時的記憶體用量上限 (以 KB 為單位)。
target_recall	選用	標準向量查詢的目標召回率。
target_top_k	選用	要擷取的 Top-K 比對值，用於計算召回率。 如果指定 target_recall 參數，系統就會使用這個值。
tune_vector_index	選用	調整工作負載中的向量索引。如果啟用，向量輔助功能會使用向量規格，自動調整向量索引或搜尋查詢，並計算最佳資料庫和索引參數。可接受的值包括 TRUE 或 FALSE。

傳回值

傳回更新後的建議表格。

vector_assist.get_recommendations

傳回與特定向量 spec_id 相關聯的建議。

函式

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

參數

參數	是否必要	說明
spec_id	必填	取得指定向量 spec_id 的建議。

傳回值

傳回建議表，其中列出設定所要求向量工作負載時必須套用的建議。每列都是一項建議，內含可執行的 SQL 查詢，以及套用建議的原因詳細說明。您可以使用 apply_recommendation() 函式套用建議。

建議表格包含下列資料欄：

資料欄名稱	類型	說明
recommendation_id	文字	建議的 ID。系統會使用這個 ID 套用最佳化建議。
vector_spec_id	文字	與建議相關聯的向量規格 ID。
table_name	文字	與建議相關聯的資料表名稱。
schema_name	文字	包含指定資料表的結構定義名稱。
query	文字	要執行的 SQL 查詢，可達到建議的結果。
recommendation	文字	最佳化建議的說明，包括採用建議後預期的結果。這個資料欄也會包含建議的原因和理由。您可以視需要使用這項背景資訊調整查詢，並重新生成建議。
applied	布林值	顯示是否已套用最佳化建議。
modified	布林值	顯示使用者是否已修改建議。
created_at	時間戳記 (含時區)	生成建議的時間。

vector_assist.apply_recommendation

使用 recommendation_id 套用單一建議。

函式

CREATE OR REPLACE FUNCTION vector_assist.apply_recommendation (
    recommendation_id TEXT
)
RETURNS BOOLEAN;

參數

參數	是否必要	說明
recommenation_id	必填	要套用的向量建議 ID。

傳回值

傳回布林值，確認是否已成功套用建議，並將 vector_assist.RECOMMENDATIONS 資料表欄 applied 更新為 TRUE。

如果 Vector Assist 無法套用建議，則會顯示錯誤訊息。

vector_assist.apply_spec

套用與特定向量 spec_id 或資料表名稱相關聯的所有建議。這項函式會檢查所有建議，並對每項建議執行 vector_assist.apply_recommendation 函式。

注意： 這項函式是長時間執行的作業 (LRO)。如果您使用的用戶端設有逾時時間 (例如 AlloyDB Omni Studio 的逾時時間為 5 分鐘)，函式呼叫可能會遭到終止。如要緩解這個問題，您可以提高逾時門檻，或複製正在使用的資料表，並只保留部分資料，以符合逾時規定。

函式

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;

參數

您必須指定 spec_id 或 table_name，才能執行函式。

參數	是否必要	說明
spec_id	選用	為指定向量 spec_id 套用所有最佳化建議。
table_name	選用	套用指定資料表的所有建議。
schema_name	選用	包含指定資料表的結構定義。
column_name	選用	如果表格包含多個向量規格，這個屬性會識別要使用的 text_column_name 或 vector_column_name。

傳回值

傳回布林值，確認是否已成功套用所有最佳化建議，並將 vector_assist.RECOMMENDATIONS 資料表欄 applied 中的值設為 TRUE，適用於所有最佳化建議。

如果 Vector Assist 無法套用建議，則會顯示錯誤訊息。

vector_assist.modify_recommendation

修改特定建議的查詢，並將相關建議的 vector_assist.RECOMMENDATIONS 表格中 modified 欄位設為 TRUE。

函式

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

參數

參數	是否必要	說明
recommendation_id	必填	要修改的建議 ID。
modified_query	必填	使用者修改的建議 SQL 查詢。

傳回值

傳回布林值，確認建議是否已成功更新，並將 vector_assist.RECOMMENDATIONS 資料表欄 modified 設為 TRUE。

如果向量輔助無法更新建議，就會在失敗時顯示錯誤訊息。

vector_assist.generate_query

根據定義的向量規格和搜尋參數，生成最佳化的向量搜尋查詢。如果適用，這個函式可能會調整 ef_search 值，以符合設定的 target_recall。

函式

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

參數

您必須指定 spec_id 或 table_name，才能執行函式。

參數	是否必要	說明
spec_id	選用	指定要生成查詢的 spec_id。
table_name	選用	指定要產生搜尋查詢的資料表名稱 (如果未提供 spec_id)。如果資料表包含多個規格，則參數會傳回錯誤。
column_name	選用	如果未提供 spec_id，請指定要產生搜尋查詢的資料欄名稱。如果資料欄包含多個規格，參數會傳回錯誤。column_name 可能是 text_column_name 或 vector_column_name。
output_column_name	選用	要在輸出查詢中擷取的資料欄名稱。如要擷取所有資料欄，請將這個參數設為 NULL。
search_text	選用	要生成嵌入的搜尋文字。系統會使用規格中的 embedding_model 生成嵌入。您只能設定 search_text 或 search_vector 參數。
search_vector	選用	搜尋查詢的向量。您只能設定 search_text 或 search_vector 參數
top_k	選用	要傳回的最近鄰數量。
filter_expressions	選用	要在搜尋查詢中套用的篩選運算式。篩選器可以套用至資料表中的欄位，例如價格 < 100。
iterative_index_search	選用	設定是否要對篩選過的查詢執行疊代索引搜尋。
target_recall	選用	僅限搜尋查詢的目標檢索。如果已設定，函式可能會在找到更佳的值時，傳回 ef_search 的建議。

傳回值

傳回文字，其中包含指定參數的向量搜尋查詢。如果指定 target_recall，且系統找到更合適的值，則可能也會包含 ef_search 的建議。您可以執行這項查詢，或儲存起來稍後執行。

vector_assist.evaluate_query_recall

評估特定查詢的向量索引喚回度。這項函式會使用 JSON 字串中的資料庫和索引設定做為輸入內容。

函式

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

參數

參數	是否必要	說明
ann_query	必填	需要評估召回率的 SQL 查詢。這項查詢應為 pgvector ANN 查詢。
vector_search_configurations	選用	可為 ANN 查詢設定的配置。這項參數必須採用 JSON 格式。

傳回值

傳回資料表，評估指定查詢的向量索引喚回度。

資料表包含下列資料欄：

資料欄名稱	類型	說明
recall	浮點值	索引傳回的向量百分比，這些向量是真正的最近鄰。這項指標可用於量化搜尋品質。 這項函式可讓您調整參數，傳回預期的向量查詢喚回度結果。
ann_execution_time	浮點值	使用索引掃描執行向量查詢所需的時間。
ground_truth_execution_time	浮點值	使用依序掃描執行查詢所需的時間。
index_type	文字	向量索引類型，例如 HNSW。

範例

以下範例會評估 HNSW 索引的召回率，並覆寫 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}'
);