Skip to content
项目

VexDB-THU/VexDB-Lite has 2,318 GitHub stars and 359 forks. GitHot measured 0 stars in 24 hours, -1 in 7 days, and -4 in 15 days. Last checked 2026-11-20 18:44 UTC. Last push 2026-11-06.

这些数字如何统计

实测星标增长

24小时
0
7天
-1
15天
-4
1个月
正在收集历史

各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。

关于

A cross-platform vector database, which can be integrated into existing databases as a plugin.

数据

README.zh.md

原文

VexDB

English | 中文

VexDB-Lite 是一个数据库能力扩展,提供 PostgreSQL、DuckDB 和 SQLite 三种适配形式,共享同一套 graph_index 图索引算法、SIMD 距离分发和 PQ/RaBitQ 量化内核。SQLite 版还内置 VexFS 文件能力,让同一个数据库同时保存普通表、向量索引和文件。

DuckDB 扩展详见 vexdb_duckdb/README.md。
本根 README 只做项目级综述与构建总览。


1. 组件概览

1.1 PostgreSQL:vexdb_lite

当前能力:

  • floatvector(N) 向量类型
  • 距离函数与运算符:
    • l2_distance(<->)
    • cosine_distance(<=>)
    • inner_product(负内积/最大内积检索用 <~>)
  • 标量工具:vector_dims()、vector_norm()、l2_normalize()、vexdb_index_info()
  • CREATE INDEX ... USING vexdb_graph
  • 索引参数:m、ef_construction、parallel_workers、quantizer(pq / rabitq)、pq_m 和 memory_mode
  • PQ 与 RaBitQ 编码存储;memory_mode='compact' 要求量化实际启用,不能静默回退为索引端原始向量存储
  • 优化器生成 Index Scan,执行器走 ANN 索引检索
  • 共享内存向量缓存、并行建索引
  • 运行参数:vexdb.ef_search、vexdb.vec_architecture

1.2 DuckDB:vexdb_lite

详见 vexdb_duckdb/README.md。当前能力:

  • FLOAT[N] 向量列上的 GRAPH_INDEX
  • 距离函数与运算符:
    • l2_distance(<->)
    • cosine_distance(<=>)
    • inner_product(负内积/最大内积检索用 <~>)
  • 标量工具:vector_dims()、l2_normalize()、vexdb_version()、vexdb_index_info()
  • CREATE INDEX ... USING GRAPH_INDEX (vec),查询支持 WHERE 过滤
  • 索引参数:m、ef_construction、parallel_workers、quantizer(pq / rabitq)和 pq_m
  • PQ 与 RaBitQ 支持索引端 memory_mode='compact'
  • 优化器生成 VEXDB_INDEX_SCAN
  • 向量缓存、并行建索引
  • 运行参数:vexdb_ef_search、vexdb_brute_force_threshold、vexdb_pq_search_mode、vexdb_pq_refine_k_factor

1.3 SQLite:统一的 VexDB-Lite

macOS 统一包一次安装即可获得:

  • vexdb:自带 SQLite 3.45.3,无需手动 .load;
  • GRAPH_INDEX 和向量距离函数;
  • VexFS 文件、目录、历史版本、恢复、SHA-256 和只读完整性检查;
  • vexdb fs ... 文件命令,含数据库批量 grep 和可选 FTS5 trigram 索引,兼容入口为 vexfs ...;
  • VexFS FSKit extension,启用后可用原生 ls、cat、grep、cp、mv。
vexdb agent.db
vexdb agent.db "SELECT vexdb_l2_distance('[1,2]', '[4,6]');"
vexdb fs --db agent.db write /notes/hello.txt
vexdb fs --db agent.db grep -n hello /notes
vexdb fs --db agent.db check
vexdb fs --db agent.db index enable
vexdb fs --db agent.db mount ~/VexDB

文本索引默认关闭,不增加普通写入开销;未开启索引或宿主没有 FTS5 时,grep 自动使用 单连接数据库扫描。

统一 macOS 技术预览包通过 bash agent_files/macos/package_preview.sh 构建。


2. 产品能力矩阵

2.2 PG拓展对比 (pgvector vs vexdb-lite vs VexDB)

分类 功能 描述 pgvector vexdb-lite(开源版) VexDB(商用版)
Graph Index graph_index 完全自研高性能图索引,融合多种图索引优势,全场景适用 ❌ ✅ ✅
距离计算 距离计算函数模板分发 内联距离计算函数,编译时优化 ❌ ✅ ✅
缓存 vector buffer 通用向量缓存,全场景适用 ❌ ✅ ✅
缓存 bulk buffer 全内存向量缓存,内存充足场景下最大加速 ❌ ❌ ✅
缓存 缓存异步 IO 内存受限场景下加速磁盘到缓存数据读取 ❌ ❌ ✅
数据类型 floatvector 标准 float32 向量类型 ✅ ✅ ✅
数据类型 halfvector 半精度 float16 向量类型 ✅ 🟡 ✅
数据类型 int8vector int8 向量类型 ❌ 🟡 ✅
量化 PQ 量化 编码压缩与可选精排;速度取决于数据、过滤和配置 ❌ ✅ ✅
量化 RaBitQ 量化 编码估距与图搜索,支持索引端压缩存储 ❌ ✅ ✅
量化 量化自动开启 后台自动开启量化,支持空表建量化索引 ❌ ❌ ✅
图索引增强 图索引异步插入 多写少读场景下快速入库 ❌ ❌ ✅
图索引增强 图挂桶功能 小规格机器承载大规模向量检索 ❌ ❌ ✅
图索引增强 子图构建索引 内存不足场景下仍保持使用内存构建索引,加快构建速度 ❌ ❌ ✅
高可用 主备高可用 支持主备同步与备份恢复 ✅ ❌ ✅
运维 并行 vacuum 并行加速索引清理回收 ❌ ❌ ✅

2.2 DuckDB 扩展对比(DuckDB VSS vs VexDB-Lite)

分类 功能 描述 DuckDB VSS VexDB-Lite (vexdb_lite)
索引 图索引 VSS:HNSW;VexDB:graph_index(自研融合图索引) ✅ ✅
距离计算 SIMD 分发 内联距离计算函数,编译时优化 ❌ ✅
量化 PQ 量化 内存受限场景下的向量压缩 ❌ ✅
量化 RaBitQ 量化 编码图搜索与可选的索引端压缩存储 ❌ ✅
缓存 缓存管理 磁盘到内存向量缓存 ❌ ✅
运维 索引压缩 回收软删除条目的空间 ✅ ❌
搜索 过滤 ANN 搜索 可显式启用标量与图/PQ联合执行;默认精确过滤 ❌ 🟡
持久化 磁盘持久化 重启后无需重建索引 ✅† ✅

† VSS 持久化为实验性功能——WAL 恢复未实现,异常关机可能导致索引损坏。VexDB-Lite 通过 DuckDB 标准序列化机制持久化。


✅ 已支持 · 🟡 即将支持 · ❌ 开源版不含

3. PostgreSQL 语法示例

3.1 安装与建表

CREATE EXTENSION vexdb_lite;

CREATE TABLE items (
    id  BIGSERIAL PRIMARY KEY,
    vec floatvector(128)
);

INSERT INTO items (vec) VALUES
    ('[0.10, 0.20, 0.30]'),
    ('[0.40, 0.50, 0.60]');

3.2 建索引

CREATE INDEX idx_items_vec
ON items
USING vexdb_graph (vec floatvector_l2_ops)
WITH (
    m = 16,
    ef_construction = 64
);

3.2.1 PQ 量化索引(v1)

启用 PQ 可将索引存储压缩约 16×。当前 v1 版本的使用规约:

SET maintenance_work_mem = '2GB';   -- 必需,低于 1GB 会自动回落 普通图索引
CREATE INDEX idx_pq ON items
USING vexdb_graph (vec floatvector_l2_ops)
WITH (quantizer = 'pq', pq_m = 4);

v1 已知限制:

  • maintenance_work_mem < 1GB 时 PQ 自动回落 普通图索引(带 NOTICE 提示)
  • PQ 索引支持 build 后的 INSERT / UPDATE / DELETE 路径,新增向量会按已训练 codebook 写入 PQ code
  • parallel build × PQ:PG parallel worker 只在磁盘构建阶段参与,PQ 训练仍在 leader 进程内完成

核对索引状态:

SELECT indexname, use_pq, pq_m FROM vexdb_index_info()
WHERE indexname = 'idx_pq';

3.3 ANN 查询

SET vexdb.ef_search = 100;
SET enable_seqscan = off;

SELECT id, vec <-> '[0.15, 0.25, 0.35]' AS dist
FROM items
ORDER BY vec <-> '[0.15, 0.25, 0.35]'
LIMIT 10;

3.4 其他距离

SELECT id
FROM items
ORDER BY vec <~> '[0.15, 0.25, 0.35]'
LIMIT 10;

SELECT id
FROM items
ORDER BY vec <=> '[0.15, 0.25, 0.35]'
LIMIT 10;

4. DuckDB 语法示例

4.1 加载扩展

LOAD '/path/to/vexdb_lite.duckdb_extension';
SELECT vexdb_version();

Python 侧常见用法:

import duckdb

con = duckdb.connect(config={"allow_unsigned_extensions": "true"})
con.execute("LOAD '/path/to/vexdb_lite.duckdb_extension'")

4.2 建表与建索引

CREATE TABLE items (
    id       INTEGER,
    category VARCHAR,
    vec      FLOAT[128]
);

CREATE INDEX idx_items_vec
ON items
USING GRAPH_INDEX (vec)
WITH (
    metric = 'l2',
    m = 16,
    ef_construction = 64
);

4.3 ANN 查询

SET vexdb_ef_search = 100;

SELECT id
FROM items
ORDER BY l2_distance(vec, [0.15, 0.25, 0.35]::FLOAT[3])
LIMIT 10;

4.4 过滤索引示例

CREATE INDEX idx_items_vec_meta
ON items
USING GRAPH_INDEX (vec);

SELECT id
FROM items
WHERE category = 'book'
ORDER BY l2_distance(vec, [0.15, 0.25, 0.35]::FLOAT[3])
LIMIT 10;

4.5 其他距离函数

SELECT inner_product([1.0, 0.0]::FLOAT[2], [0.5, 0.5]::FLOAT[2]);
SELECT cosine_distance([1.0, 0.0]::FLOAT[2], [0.5, 0.5]::FLOAT[2]);
SELECT vector_dims([1.0, 2.0, 3.0]::FLOAT[3]);
SELECT l2_normalize([3.0, 4.0]::FLOAT[2]);
SELECT * FROM vexdb_index_info();

5. 构建方法

预编译产物(推荐):见 GitHub Releases 下载 vex-duckdb-linux-<arch>.tar.gz / vexdb_lite-linux-<arch>-pg19.tar.gz,无需本地编译。

从源码构建:每个子项目的 README 有详细步骤:

跨架构批量打包(项目内部发版用):

bash scripts/release.sh build              # 远程 x86 + ARM 各 build 一份 → dist/
bash scripts/release.sh package            # 打 tarball + SHA256SUMS → dist/release/
bash scripts/release.sh upload v0.1.0      # gh release upload

4.1 构建 PostgreSQL 版本

依赖

  • PostgreSQL 16 ~ 19(已适配 PG 16/17/18/19;主验证平台为 19devel)
  • CMake ≥ 3.14
  • C++17 编译器(GCC 9+ / Clang 10+)

编译 PostgreSQL(release 示例)

cd /path/to/postgresql-19-source
./configure \
  --prefix=/opt/postgresql-19rel-install \
  --without-icu \
  --without-readline \
  --without-zlib \
  CFLAGS="-O3 -DNDEBUG"
make -j$(nproc)
make install

编译 vexdb_lite

cd /path/to/VexDB-Lite
export PG_CONFIG=/opt/postgresql-19rel-install/bin/pg_config
cmake -S vexdb_pg -B build/pg -DCMAKE_BUILD_TYPE=Release
cmake --build build/pg -j$(nproc)
cmake --install build/pg

启动前配置

postgresql.conf 至少需要:

shared_preload_libraries = 'vexdb_lite'

重启实例后:

CREATE EXTENSION vexdb_lite;

4.2 构建 DuckDB 版本

推荐方式:使用 build_duck.sh(封装了 DuckDB clone、cmake 配置、编译、元数据处理全流程)

bash build_duck.sh setup   # 首次:clone DuckDB v1.5.2 并 cmake configure
bash build_duck.sh build   # 编译扩展(增量)

生成物:build/duck/v1.5.2/build/extension/vexdb_lite/vexdb_lite.duckdb_extension

依赖

  • CMake ≥ 3.28,< 4.x
  • C++17 编译器(GCC 9+ 或 Clang 10+)
  • Git

说明

DuckDB 扩展需嵌入 DuckDB 源码树编译,无法单独 cmake -B build vexdb_duckdb/。build_duck.sh 自动处理以下步骤:

  1. clone DuckDB v1.5.2 源码
  2. 写入 extension_config_local.cmake 注册 vexdb_lite 扩展
  3. 运行 cmake + cmake --build
  4. 处理扩展元数据 footer(DuckDB 发版格式要求)

运行测试

DuckDB 扩展测试

bash build_duck.sh build          # 构建扩展
bash tests/spec/_lib/docker/run_duckdb.sh test  # 本地运行全量 spec,不需要 Docker

PostgreSQL 插件测试

python3 tests/spec/_lib/render.py --engine pg --out build/spec
BUILDX_EXTRA_ARGS='--build-arg PG_GIT_TAG=REL_19_STABLE' bash tests/spec/_lib/docker/run_pg.sh build
bash tests/spec/_lib/docker/run_pg.sh test      # 需要 Docker

先用 python3 -m pip install -r tests/spec/requirements.txt 安装渲染依赖。SQLite 构建与测试入口为 bash build_sqlite.sh test。测试文件位于 tests/spec/,当前 CI 范围见 状态说明。


7. 测试结果

数据集:SIFT-1M 128 维,m=16,ef_construction=128。列含义:QPS(reads=1) / QPS(reads=16) / Recall@10。

测试环境:Intel Core Ultra 7-265K(20c/20t,3.9 GHz)/ 16 GB DDR5 / x86_64 Linux

7.1 与 pgvector / VSS 对比(x86_64)

ef_search = 50

系统 QPS (r=1) QPS (r=16) Recall@10
pgvector 507.9 7153.5 96.22%
vexdb_lite (PostgreSQL) 994.7 12084.6 95.97%
vexdb_lite (DuckDB) 717.5 8667.8 95.06%
duckdb-vss 496.1 5360.9 94.07%

ef_search = 100

系统 QPS (r=1) QPS (r=16) Recall@10
pgvector 313.4 4272.5 98.82%
vexdb_lite (PostgreSQL) 618.5 7883.1 98.62%
vexdb_lite (DuckDB) 547.2 5379.1 98.40%
duckdb-vss 405.2 4433.3 98.04%

ef_search = 200

系统 QPS (r=1) QPS (r=16) Recall@10
pgvector 193.1 2694.1 99.66%
vexdb_lite (PostgreSQL) 421.3 5038.0 99.58%
vexdb_lite (DuckDB) 383.6 4298.8 99.53%
duckdb-vss 321.9 3809.3 99.42%

8. 当前已知限制

PostgreSQL

  • 支持 PostgreSQL 16 ~ 19,当前主验证平台是 PostgreSQL 19

DuckDB

  • 扩展必须与 DuckDB 运行时版本完全匹配。
  • 距离计算在运行时选择 CPU 架构,可用 vexdb_simd_arch() 查看实际结果。

7. 仓库结构

目录 说明
common/ 三端共享内核:图索引算法、SIMD 距离分发、量化器(PQ/RaBitQ)、模板容器
vexdb_pg/ PostgreSQL 扩展:索引 AM、构建、搜索、DML、WAL、距离分发入口
vexdb_duckdb/ DuckDB 扩展:索引生命周期、优化器改写、距离函数 → README
vexdb_sqlite/ SQLite GRAPH_INDEX、距离函数、VexFS SQL
agent_files/ 文件命令、版本、快照和挂载适配
documentation/ 功能文档、构建指南、当前 CI 范围
tests/spec/ 基于 YAML 的 spec 测试(shared / pg / duckdb / sqlite / opengauss)
scripts/ 构建、发版、打包脚本
thirdparties/ 第三方依赖(patched Boost)

社区

渠道 说明
GitHub Issues Bug 反馈与功能建议
GitHub Discussions 提问、提案与功能讨论
Discord 实时交流、答疑解惑
官方微信社群 扫码加入,见 vexdb.com/community,中文社区互助

License

MIT License. 详见 LICENSE。