lakebase_vector

Important

此功能在 Beta 版中。 工作区管理员可以从 预览 页控制对此功能的访问。 请参阅 Manage Azure Databricks 预览版。

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

Install

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

CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;

关键字 CASCADE 自动安装 pgvector 为依赖项。

快速入门

-- 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 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：提升回忆能力，但需要更长时间积累。

CREATE INDEX ON items USING lakebase_ann (embedding vector_l2_ops)
WITH (build_mode = 'quality');

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 CONCURRENTLY 不停机的情况下重新生成：

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

REINDEX INDEX CONCURRENTLY items_embedding_ann;

优化搜索准确性

在优化之前，调用lakebase_ann_index_info(index_name)以获取索引和listsdefault_probesdefault_epsilon值。

在查询时使用 lakebase_ann.probes 以控制搜索多少IVF分区。 较高的值以查询速度为代价提高召回率。 默认值为 'auto'。 测试不同的数值以达到你的回忆目标。

的 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_ann');

-- 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 控制全精度重新排序。

预滤波器

默认情况下，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;

预过滤效果最好，因为过滤器评估成本低且能去除大部分行。 对于匹配多行或需要昂贵计算的过滤器，不要关闭，因为在索引内评估过滤器会增加开销。

运算符类

距离指标	运算符类	查询运算符
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)	无效	将索引加载到内存中，以消除第一个查询的冷启动延迟。
lakebase_ann_index_info(regclass)	文本消息	以文本的形式返回索引元数据，包括lists和 default_probesdefault_epsilon。

后续步骤

• lakebase_text
• Lakebase 搜索