lakebase_vector

擴充 lakebase_vector 功能透過索引類型為 Lakebase lakebase_ann 新增了近似最近鄰(ANN)向量搜尋功能。 它是 pgvector 的可直接補充:相同的向量類型、距離運算子和查詢語法都能使用,且不需修改。

Install

首先,在專案設定 中啟用 Lakebase Search 。 然後安裝擴充功能:

CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;

關鍵字 CASCADE 會 pgvector 自動安裝為相依項目。

升級擴充與索引

新的 Lakebase Search 版本可以新增功能、修正與效能提升。 雖然 Lakebase Search 是作為 Lakebase 更新的一部分釋出,但它並非自動升級所有資料。 在 lakebase_vector中,有兩個東西分別升級,並攜帶彼此無關的版本號:

  • 擴充版本 是建立 SQL 物件 CREATE EXTENSION lakebase_vector 的版本,包括資料型別、函式、運算子及 lakebase_ann 索引存取方法。 此版本由 SELECT installed_version FROM pg_available_extensions WHERE name = 'lakebase_vector'。 ALTER EXTENSION lakebase_vector UPDATE 更新本版本。
  • 索引儲存格式 是索引在磁碟上的佈局 lakebase_ann 。 擴充功能可能會在更新中引入更新的索引儲存格式,解鎖更多功能並帶來更佳的效能。 所有新建立的索引會自動使用最新的儲存格式,而現有索引則可在有新儲存格式可用後升級為新格式 REINDEX INDEX CONCURRENTLY 。

升級並不急迫。 這個擴充功能相容於舊版本的 SQL 物件和索引儲存格式,但保持最新能讓你走在支援且效能最佳的路徑上,避免日後大規模遷移,因此方便時升級,而非無限期拖延。

Note

最新可用的擴充套件版本由 報告。SELECT default_version FROM pg_available_extensions WHERE name = 'lakebase_vector'

最新的儲存格式版本為 _2。 以下查詢會找到所有使用舊儲存格式的索引。 接著你可以用或REINDEX INDEX CONCURRENTLY:重建到最新的儲存格式REINDEX INDEX:

SELECT oid::regclass AS index, lakebase_ann_index_info(oid::regclass)::json ->> 'version' AS storage_format_version
FROM pg_class
WHERE relam = (SELECT oid FROM pg_am WHERE amname = 'lakebase_ann') AND relkind = 'i';

Note

REINDEX INDEX CONCURRENTLY 允許讀取和寫入繼續,但會花比較多時間。

快速入門

-- Create a table with a vector column
CREATE TABLE items (id BIGSERIAL PRIMARY KEY, embedding VECTOR(3));

-- Insert sample data
INSERT INTO items (embedding)
SELECT ARRAY[random(), random(), random()]::real[]
FROM generate_series(1, 1000);

-- Create a lakebase_ann index
CREATE INDEX items_embedding_idx ON items
  USING lakebase_ann (embedding vector_l2_ops);

-- Query using standard pgvector distance operators
SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 5;

從同步資料表填充

如果你是從 Unity Catalog 載入嵌入,而不是直接插入, 同步表格 可以在同步時將 lakehouse 嵌入欄位直接映射到 Postgres vector 欄位,而不是預設 JSONB 的映射。 請參閱 湖底搜尋的自訂類型映射。

設定索引

在索引建立時設定 build_mode 以控制準確度與速度的權衡:

  • standard (預設):平衡召回與索引建立時間。 大多數工作負載都用。
  • quality:提升回憶能力,但累積時間明顯較長。 只用於擁有最多五千萬向量的資料表。
CREATE INDEX ON items USING lakebase_ann (embedding vector_l2_ops)
WITH (build_mode = 'standard');

fast建置模式仍支援向下相容。

預設情況下, lakebase_ann 會根據表格的統計數據和索引的配置選擇清單。 設定 lists 為明確控制分割區佈局:

CREATE INDEX ON items USING lakebase_ann (embedding vector_l2_ops)
WITH (lists = '1000');

Index 建置時間

較大的可以 shared_buffers 大幅縮短指數建立時間。 Lakebase 僅在 較大的固定大小計算上實現此優化。 在優化索引建構前,先檢查目前的數值:

SHOW shared_buffers;

如果 shared_buffers 1 GB 或更少,建議在開始索引建置前暫時調整為較大的固定大小運算。

你也可以透過增加平行工作者的數量來加快索引的建立。

配置參數 max_parallel_maintenance_workers 設定可由單一工具指令(如 CREATE INDEX)啟動的最大平行工作者數量。

max_parallel_workers配置參數設定計算能支援平行運算的最大工作者數量。 超過此限制的數值 max_parallel_maintenance_workers 則無影響。

max_worker_processes組態參數設定計算器可支援的最大背景程序數量。 Lakebase 是根據運算大小來管理這個設定的。 超過此限制的數值 max_parallel_workers 則無影響。

SHOW max_worker_processes;
-- Set both values to the desired parallelism minus one.
SET max_parallel_workers = 15;
SET max_parallel_maintenance_workers = 15;

同時進行建置索引

CREATE INDEX CONCURRENTLY 並 REINDEX INDEX CONCURRENTLY 允許在建立或重建索引時繼續讀取與寫入:

CREATE INDEX CONCURRENTLY items_embedding_idx_concurrent ON items
  USING lakebase_ann (embedding vector_l2_ops);

REINDEX INDEX CONCURRENTLY items_embedding_idx_concurrent;

調音搜尋準確度

調整前,先呼叫lakebase_ann_index_info(index_name)取得索引、 listsdefault_probes、 default_epsilon 和 數值。

查詢時使用 lakebase_ann.probes 來控制搜尋的反轉檔案(IVF)分割區數量。 較高的數值能提升回憶,但代價是延遲。 預設值 'auto' 在兩者之間提供了平衡的取捨。 為了更細緻的控制,可以用來lakebase_ann_advise取得建議的探針數值。

的 probes 形狀必須與 的 lists形狀相符。 呼叫 lakebase_ann_index_info 以找到你的 lists 陣列,然後為一級索引設定一個值,或為兩級索引設兩個逗號分隔值:

lists 資料來源:索引資訊 probes 設定
[] (空的) ''
[222] '22'
[3333, 33333] '33, 333'

Note

在小型資料集中,使用 lakebase_ann 精確(平面)搜尋取代 IVF 分割,回 lakebase_ann_index_info 傳空值 lists 與 default_probes。 此時,讓 probes 為 ''。 當 lists 不空時, probes 形狀不符 lists 的值會產生錯誤。

-- Check your index's lists array first
SELECT lakebase_ann_index_info('items_embedding_idx');

-- Then set probes to match the shape of lists.
-- One-level index (single-value lists): set one value.
SET lakebase_ann.probes TO '10';

-- Two-level index: set two ascending comma-separated values, for example '10, 20'.
-- Flat index (empty lists): leave probes set to ''.

SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 10;

lakebase_ann.epsilon 控制有多少候選人會被重新排序,使用全精度距離。 數值越高,候選人重新排序越多,所需時間越長。 預設值 對 'auto' 大多數工作負載來說運作良好。 在小型資料集的平面搜尋中,仍 epsilon 能控制全精度重新排序。

lakebase_ann_advise lakebase_ann_tune lakebase_ann_latency、,且lakebase_ann_sample需要 lakebase_vector 1.1.2 及以上版本。 要檢查已安裝版本並更新擴充功能,請參見 「升級擴充功能與索引」。

lakebase_ann_advise 以回憶次數遞增的順序回傳候選 probes 值,從 0.5 到 0.9,步驟為 0.1,以及 0.91 到 0.99,步驟為 0.01。 每一列包含預估的召回時間以及預熱後測量的查詢延遲。 用你搜尋工作量中的真實查詢作為輸入。 如果無法取得,請從索引表中取樣向量。lakebase_ann_sample 以下範例展示了這兩種選項:

-- Option 1: real queries in a separate table
SELECT probes, recall, avg_ms, p50_ms, p95_ms
FROM lakebase_ann_advise(
  'items_embedding_idx'::regclass,
  ARRAY(
    SELECT embedding FROM queries
    WHERE embedding IS NOT NULL
    LIMIT 512
  )
);

-- Option 2: sampled from the indexed table
-- NULL::items specifies items as the table to sample from.
SELECT probes, recall, avg_ms, p50_ms, p95_ms
FROM lakebase_ann_advise(
  'items_embedding_idx'::regclass,
  ARRAY(
    SELECT embedding FROM lakebase_ann_sample(NULL::items, 512)
    WHERE embedding IS NOT NULL
  )
);
Column Description
probes 一個 lakebase_ann.probes 值。
recall 範例查詢的預估recall@10。
avg_ms、p50_ms、p95_ms 單一查詢的平均、中位數和第95百分位延遲以毫秒計。

選擇最快符合回憶目標的列,然後套用其 probes 值:

SET lakebase_ann.probes TO '10';

對於設定 lakebase_ann.epsilon 為 的 1.9前十名查詢,會估計回溯和延遲,這可能與你的實際查詢不同。 在使用某個 probes 值之前,如果可能的話,先確認其在工作負載上的召回率和延遲。

若索引為空listslakebase_ann_advise,則無列回傳,因為沒有可調的。

在大型索引上,通話 lakebase_ann_advise 時間可能超過20分鐘。 查詢向量越多,呼叫速度變慢。 從 512 個查詢向量開始,以平衡回憶準確度與執行時間。

lakebase_ann_advise 呼叫 lakebase_ann_tune 以取得建議 probes 值,然後 lakebase_ann_latency 測量延遲。 你也可以單獨使用其中一種lakebase_ann_tunelakebase_ann_latency。 參見 效用函數。

lakebase_ann_advise 並 lakebase_ann_tune 要求索引資料表為資料表層級 SELECT ,若該資料表中的角色適用列 級安全性(RLS ),則回傳錯誤。 lakebase_ann_sample 並套 lakebase_ann_latency 用 RLS 政策,只讀取你角色能看到的列。

預濾波器

預設情況下,Postgres 會在 ANN 索引回傳候選列後套用非向量濾鏡條件。 允許 lakebase_ann.prefilter 在全精度距離重新排序前評估這些條件:

SET lakebase_ann.prefilter TO on;

SELECT * FROM items
WHERE id % 100 = 0
ORDER BY embedding <-> '[3,1,2]'
LIMIT 10;

預過濾最好是在篩選器便宜且能去除大部分資料列時。 對於匹配多列或需要昂貴計算的過濾器,則不關閉,因為在索引內評估過濾器會增加開銷。

指數預熱

計算開始後,將 lakebase_ann_prewarm 索引中經常存取的部分載入記憶體。 該 scope 參數接受以下值:

  • search (預設值):預熱用於搜尋的全部熱區。
  • routing:只預熱路由結構。 此選項較快,且對大型指數提供更佳的成本效益取捨。
-- Prewarm the full search scope
SELECT lakebase_ann_prewarm('items_embedding_idx');

-- Prewarm only routing structures
SELECT lakebase_ann_prewarm('items_embedding_idx', scope => 'routing');

運算子類別

距離度量 操作員類別 查詢運算子
L2(歐幾里得) vector_l2_ops <->
負內積 vector_ip_ops <#>
餘弦相似性 vector_cosine_ops <=>

選擇與你嵌入訓練方式相符的運算子類別,並使用相同的指標作為索引和查詢:

  • vector_cosine_ops (<=>) 是餘弦相似度。 大多數文字嵌入都用它。 這是最常見的選擇。
  • vector_l2_ops (<->) 是歐幾里得(L2)距離。 當絕對空間距離很重要且向量未正規化時,才會用它。
  • vector_ip_ops (<#>) 是負內積。 當向量預正規化為單位長度時使用。 對於單位向量,內積等於餘弦相似度,通常速度更快。

索引選項參考

Option 類型 預設 Description
build_mode 字串 'standard' 控制準確度與速度的權衡。 'quality'為了更好的回憶,但代價是要做得更長的索引。 'fast' 仍支援向下相容。
lists 字串 'auto' 設定試管嬰兒的分割區佈局。 當 'auto',擴展則根據表格的統計量和索引的配置選擇一個值。 為單一整數,如 '1000' 一級索引,或兩個遞增逗號分隔整數,如 '100, 1000' 兩級索引。

GUC 參考

參數 類型 預設 Description
lakebase_ann.probes 字串 'auto' 每個層級要掃描多少個試管嬰兒分區。 較高的數值能提升回憶,但代價是延遲。 該形狀必須與 中的lakebase_ann_index_info陣列相符lists。
lakebase_ann.epsilon 字串 'auto' 控制有多少候選人會被重新排序,使用全精度距離。 數值越高,候選人重新排序越多,所需時間越長。
lakebase_ann.prefilter 列舉 off 在全精度距離重新排序前,評估非向量濾波器。 有效值為 on 和 off。 最適合用便宜的濾波器,能去除大部分候選列。

公用程式函數

功能 Returns Description
lakebase_ann_prewarm(regclass, scope text DEFAULT 'search') 無效 將頻繁存取的索引資料載入記憶體。 有效的 scope 值為 search 和 routing。
lakebase_ann_index_info(regclass) 收發簡訊 回傳索引元資料以 JSON 文字呈現,包括 version、 lists、 default_probes和 default_epsilon。
lakebase_ann_advise(regclass, vector[] \| halfvec[]) TABLE(probes text, recall real, avg_ms real, p50_ms real, p95_ms real) 建議 lakebase_ann.probes 樣本查詢向量的值,並附有估計recall@10及測量延遲。 需要索引表層級 SELECT 的表格。 當RLS適用於你的職務時,不支援。 需要 lakebase_vector 1.1.2 及以上版本。
lakebase_ann_tune(regclass, vector[] \| halfvec[]) TABLE(probes text, recall real) 建議 lakebase_ann.probes 樣本查詢向量的值,並估計recall@10。 需要索引表層級 SELECT 的表格。 當RLS適用於你的職務時,不支援。 需要 lakebase_vector 1.1.2 及以上版本。
lakebase_ann_latency(regclass, text[], vector[] \| halfvec[]) TABLE(probes text, avg_ms real, p50_ms real, p95_ms real) 衡量陣列中每個 lakebase_ann.probes 值 text[] 索引的平均、中位數及第 95 百分位查詢延遲。 需要 lakebase_vector 1.1.2 及以上版本。
lakebase_ann_sample(NULL::<table>, sample_size integer DEFAULT 128) SETOF 資料表的列類型 從指定的NULL::<table>表格中取樣至最多的列。sample_size 需要 lakebase_vector 1.1.2 及以上版本。

下一步