lakebase_vector

该 lakebase_vector 扩展通过 lakebase_ann 索引类型向 Lakebase 添加近似近邻 (ANN) 向量搜索。 它是 pgvector 的下拉配套:相同的矢量类型、距离运算符和查询语法工作,无需修改。

Install

首先,在项目设置中 启用 Lakebase 搜索 。 然后安装扩展:

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对象和索引存储格式,但保持最新能让你走在支持且性能最佳的路径上,避免了后续大规模迁移,因此方便时升级,而非无限期推迟。

注释

最新可用的扩展版本由 报告。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';

注释

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 目录加载嵌入,而不是直接插入, 同步表 可以在同步时将 Lakehouse 嵌入列直接映射到 Postgres vector 列,而不是默认 JSONB 映射。 参见湖 底搜索的自定义类型映射。

配置索引

在索引创建时设置 build_mode ,以控制准确性/速度权衡:

  • standard (默认):平衡召回和索引构建时间。 用于大多数工作负荷。
  • quality:提升回忆能力,但积累时间显著延长。 只用于拥有最多5000万个向量的表格。
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');

索引构建时间

更大的 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_probesdefault_epsilon值。

在查询时使用 lakebase_ann.probes 以控制搜索的倒置文件(IVF)分区数量。 更高的值能提高召回率,但代价是延迟的降低。 默认值 'auto' 在两者之间提供了平衡的权衡。 为了更细致的控制,可以用来lakebase_ann_advise获取推荐探针数值。

的 probes 形状必须与的 lists形状相匹配。 调用 lakebase_ann_index_info 以找到你的 lists 数组,然后为一级索引设置一个值,或为两级索引设置两个逗号分隔值:

lists 从索引信息 probes 设置为
[] (空) ''
[222] '22'
[3333, 33333] '33, 333'

注释

在小数据集上,使用lakebase_ann精确(平面)搜索代替试管婴儿划分,返回lakebase_ann_index_info空和listsdefault_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_samplelakebase_vector 1.1.2及以上版本。 要查看已安装版本并更新扩展,请参见 “升级扩展和索引”。

lakebase_ann_advise 回忆顺序由0.5到0.9,步进为0.1,从0.91到0.99,按0.01步返回候选 probes 值。 每一行都包含预估的回忆时间和预热后测量的查询延迟。 用你搜索工作量中的真实查询作为输入。 如果无法使用,则从索引表中采样向量。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
  )
);
列 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 值之前,如果可能的话,先核实其调用率和工作负载延迟。

如果索引为空 lists, lakebase_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 (<#>) 是负内积。 当向量预规范化为单位长度时使用它。 对于单位向量,内部积等于余弦相似性,通常更快。

索引选项参考

选项 类型 违约 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。 它最适合用便宜的过滤器,去除大部分候选行。

实用函数

Function 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及以上版本。

后续步骤