💡 灯笼

Lantern 是一个开源的 PostgreSQL 数据库扩展，用于存储向量数据、生成嵌入并向量搜索操作提供支持。

它为向量列提供了一种名为 lantern_hnsw 的新索引类型，能够加速 ORDER BY ... LIMIT 查询。

Lantern 基于 usearch 构建并使用，这是一个单头文件的先进 HNSW 实现。

🔧 快速安装

如果你还没有 PostgreSQL，可以使用 Lantern 的 Docker 镜像 来快速上手：

docker run --pull=always --rm -p 5432:5432 -e "POSTGRES_USER=$USER" -e "POSTGRES_PASSWORD=postgres" -v ./lantern_data:/var/lib/postgresql/data lanterndata/lantern:latest-pg15

然后，你可以通过 postgresql://$USER:postgres@localhost/postgres 连接到数据库。

使用 homebrew 安装 Lantern：

brew tap lanterndata/lantern
brew install lantern && lantern_install

你也可以从我们的 预编译二进制文件 中通过一个简单的 make install 命令将 Lantern 安装到现有的 PostgreSQL 上。

此外，你还可以使用 Replit 一键体验 Lantern。

🔧 从源码构建 Lantern 并集成到现有 PostgreSQL

先决条件：

cmake 版本：>=3.3
gcc && g++ 版本：构建可移植二进制时 >=11，而在新硬件上或使用 CPU 特定向量化时 >=12
PostgreSQL 11、12、13、14、15 或 16
对应版本的 PostgreSQL 开发包（postgresql-server-dev-$version）

在新硬件上或使用 CPU 特定向量化构建 Lantern：

git clone --recursive https://github.com/lanterndata/lantern.git
cd lantern
cmake -DMARCH_NATIVE=ON -S lantern_hnsw -B build
make -C build install -j

构建可移植的 Lantern 二进制文件：

git clone --recursive https://github.com/lanterndata/lantern.git
cd lantern
cmake -DMARCH_NATIVE=OFF -S lantern_hnsw -B build
make -C build install -j

📖 如何使用 Lantern

Lantern 保留了标准的 PostgreSQL 接口，因此与 PostgreSQL 生态系统中的所有常用工具兼容。

首先，在 SQL 中启用 Lantern（例如通过 psql shell）：

CREATE EXTENSION lantern;

注意：执行上述命令后，Lantern 扩展仅在当前 PostgreSQL 数据库中可用（单个 PostgreSQL 实例可能包含多个数据库）。当连接到其他数据库时，请确保也为该数据库运行上述命令。例如：

CREATE DATABASE newdb;
\c newdb
CREATE EXTENSION lantern;

创建一个包含向量列的表，并插入数据：

CREATE TABLE small_world (id integer, vector real[3]);
INSERT INTO small_world (id, vector) VALUES (0, '{0,0,0}'), (1, '{0,0,1}');

通过 lantern_hnsw 在表上创建 HNSW 索引：

CREATE INDEX ON small_world USING lantern_hnsw (vector);

根据你的向量数据自定义 lantern_hnsw 索引参数，例如距离函数（如 dist_l2sq_ops）、索引构建参数和索引搜索参数。

CREATE INDEX ON small_world USING lantern_hnsw (vector dist_l2sq_ops)
WITH (M=2, ef_construction=10, ef=4, dim=3);

开始查询数据：

SET enable_seqscan = false;
SELECT id, l2sq_dist(vector, ARRAY[0,0,0]) AS dist
FROM small_world ORDER BY vector <-> ARRAY[0,0,0] LIMIT 1;

关于运算符和运算符类的说明

Lantern 支持多种距离函数用于索引。

有 3 种可用的运算符：<->（l2sq）、<=>（余弦）、<+>（汉明）。

在创建索引时，可以使用以下四种已定义的运算符类：

• dist_l2sq_ops：real[] 类型的默认值。
• dist_vec_l2sq_ops：vector 类型的默认值。
• dist_cos_ops：适用于 real[] 类型。
• dist_vec_cos_ops：适用于 vector 类型。
• dist_hamming_ops：适用于 integer[] 类型。

索引构建参数

M、ef 和 ef_construction 参数控制着 HNSW 算法在你特定用例中的性能。

• 通常，较低的 M 和 ef_construction 可以加快索引创建速度，但会降低召回率。
• 较低的 M 和 ef 则能提高搜索速度并减少共享缓冲区命中次数，但同样会牺牲召回率。这些参数的调整需要根据你的具体用例进行实验。

其他事项

• 如果你之前克隆过 Lantern，并希望更新代码，请运行 git pull && git submodule update --recursive。

⭐️ 功能特性

• 为常见场景生成嵌入（CLIP 模型、Hugging Face 模型、自定义模型）。
• 与 pgvector 的数据类型兼容，因此使用 pgvector 的用户可以无缝切换到 Lantern。
• 通过外部索引器实现并行索引创建。
• 能够在数据库服务器之外生成索引图。
• 支持在数据库外并在另一个实例中创建索引，从而避免中断数据库工作流程。
• 提供一系列辅助函数，帮助优化你的工作流程。

🏎️ 性能表现

重要要点：

• 我们主要关注三个关键指标：CREATE INDEX 时间、SELECT 吞吐量和 SELECT 延迟。
• 在所有这些指标上，Lantern 的表现均与 pgvector 和 pg_embedding（Neon）持平或更优。
• 我们计划继续优化性能，以确保 Lantern 成为性能最佳的数据库解决方案。

🗺️ 路线图

• 云托管版 Lantern - 请在此 注册
• 针对您的 CPU 优化的硬件加速距离度量，实现更快的查询
• 面向不同行业的应用构建模板和指南
• 更多嵌入生成工具（支持第三方模型 API、更多本地模型）
• 支持嵌入的版本控制与 A/B 测试
• 自动调优的索引类型，可自动选择合适的创建参数
• 支持 1 字节和 2 字节向量元素，以及高达 8000 维的向量（PR #19）
• 如需新功能，请发送邮件至 support@lantern.dev

📚 资源

• GitHub 问题：用于报告 Lantern 的 bug 或问题
• 需要支持？请联系 support@lantern.dev。我们很乐意帮助您排查问题，并就如何将 Lantern 应用于您的场景提供建议。
• 我们欢迎社区贡献！欢迎您随时提交 issue 或 pull request。如果您联系 support@lantern.dev，我们将为您找到适合的公开 issue 或项目。

Lantern 快速上手指南

Lantern 是一个开源的 PostgreSQL 数据库扩展，专为存储向量数据、生成嵌入（Embeddings）以及执行向量搜索操作而设计。它引入了 lantern_hnsw 索引类型，显著提升了向量查询性能。

环境准备

在开始之前，请确保满足以下系统要求和依赖：

• 操作系统: Linux, macOS (支持 Homebrew), 或任何支持 Docker 的环境。
• PostgreSQL 版本: 11, 12, 13, 14, 15 或 16。
• 编译依赖 (仅源码安装需要):
  • CMake 版本: >= 3.3
  • GCC & G++ 版本: >= 11 (构建通用二进制文件), >= 12 (针对新硬件或 CPU 特定向量化优化)
  • PostgreSQL 开发包: postgresql-server-dev-$version

安装步骤

您可以选择以下任一方式快速安装 Lantern：

方式一：使用 Docker (推荐，最快捷)

如果您尚未安装 PostgreSQL，可以使用 Docker 一键启动包含 Lantern 的环境：

docker run --pull=always --rm -p 5432:5432 -e "POSTGRES_USER=$USER" -e "POSTGRES_PASSWORD=postgres" -v ./lantern_data:/var/lib/postgresql/data lanterndata/lantern:latest-pg15

启动后，连接字符串为：postgresql://$USER:postgres@localhost/postgres

方式二：使用 Homebrew (macOS)

brew tap lanterndata/lantern
brew install lantern && lantern_install

方式三：在线体验 (Replit)

无需本地环境，点击即可在浏览器中运行： Run on Replit

方式四：源码编译 (适用于现有 PostgreSQL 实例)

若需在现有的 PostgreSQL 上编译安装，请执行以下步骤：

1. 克隆代码库

git clone --recursive https://github.com/lanterndata/lantern.git
cd lantern

2. 编译与安装

• 针对新硬件优化 (开启 CPU 特定向量化):

  cmake -DMARCH_NATIVE=ON -S lantern_hnsw -B build
  make -C build install -j
  

• 构建通用二进制文件 (便携版):

  cmake -DMARCH_NATIVE=OFF -S lantern_hnsw -B build
  make -C build install -j
  

基本使用

Lantern 完全兼容标准 PostgreSQL 接口。以下是核心操作流程：

1. 启用扩展

连接到数据库后，首先启用 Lantern 扩展。注意：每个数据库实例都需要单独执行此命令。

CREATE EXTENSION lantern;

如果创建了新数据库，需切换并重新启用：

CREATE DATABASE newdb;
\c newdb
CREATE EXTENSION lantern;

2. 创建表并插入数据

创建一个包含向量列的表，并插入测试数据：

CREATE TABLE small_world (id integer, vector real[3]);
INSERT INTO small_world (id, vector) VALUES (0, '{0,0,0}'), (1, '{0,0,1}');

3. 创建向量索引

使用 lantern_hnsw 创建索引以加速查询。您可以自定义距离函数和构建参数：

-- 基础用法
CREATE INDEX ON small_world USING lantern_hnsw (vector);

-- 高级用法：指定距离函数 (L2 平方距离) 和调整参数
CREATE INDEX ON small_world USING lantern_hnsw (vector dist_l2sq_ops)
WITH (M=2, ef_construction=10, ef=4, dim=3);

常用算子类说明：

• dist_l2sq_ops: 适用于 real[] 类型 (默认)
• dist_vec_l2sq_ops: 适用于 vector 类型
• dist_cos_ops: 余弦距离，适用于 real[]
• dist_hamming_ops: 汉明距离，适用于 integer[]

4. 执行向量搜索查询

关闭顺序扫描以强制使用索引，然后执行最近邻搜索：

SET enable_seqscan = false;

SELECT id, l2sq_dist(vector, ARRAY[0,0,0]) AS dist
FROM small_world 
ORDER BY vector <-> ARRAY[0,0,0] 
LIMIT 1;

支持的搜索算子：

• <->: L2 平方距离 (Euclidean squared)
• <=>: 余弦距离 (Cosine)
• <+>: 汉明距离 (Hamming)