VexDB-THU/VexDB-Lite
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 有详细步骤:
- DuckDB 扩展:vexdb_duckdb/README.md#构建
- PG 扩展:编译构建指南
跨架构批量打包(项目内部发版用):
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 自动处理以下步骤:
- clone DuckDB v1.5.2 源码
- 写入
extension_config_local.cmake注册 vexdb_lite 扩展 - 运行
cmake+cmake --build - 处理扩展元数据 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。