sqlite-vec 向量数据库支持深度研究报告

研究日期:2026年6月13日 研究对象:modernc.org/sqlite/vec(sqlite-vec 纯 Go 绑定)

目录
  1. 一、项目概述
  2. 二、Go 语言绑定方案对比
  3. 纯 Go 方案(你代码中的方案)
  4. 三、核心架构:vec0 虚拟表
  5. 3.1 影子表系统(Shadow Tables)
  6. 3.2 三种查询计划
  7. 四、支持的向量类型与距离度量
  8. 4.1 向量类型
  9. 4.2 距离度量
  10. 五、索引算法详解
  11. 5.1 Flat(暴力扫描)
  12. 5.2 IVF(倒排文件索引)
  13. 5.3 DiskANN
  14. 5.4 Rescore(重排序)
  15. 调优参数
  16. 六、vec0 虚拟表完整语法
  17. 建表 DDL
  18. 数据操作
  19. 七、与主流向量数据库对比
  20. 独特优势
  21. 明显短板
  22. 八、适用场景评估矩阵
  23. 九、总结与建议
  24. 核心优势
  25. 核心风险
  26. 建议
  27. 参考资料
研究日期:2026年6月13日
研究对象:modernc.org/sqlite/vec(sqlite-vec 纯 Go 绑定)

一、项目概述

sqlite-vec 是 Alex Garcia (asg017) 开发的 SQLite 向量搜索扩展,定位为 sqlite-vss 的继任者。核心设计哲学:"足够快"(fast enough)+ 无处不在(run anywhere)。

属性值
GitHubasg017/sqlite-vec
Stars7,700+
许可证Apache-2.0 / MIT 双许可
主语言C (58.3%), Python (36.5%)
当前版本v0.1.10-alpha.4 (pre-v1)
主要赞助Mozilla (Builders 项目), Fly.io, Turso, SQLite Cloud
⚠️ 重要提醒:目前仍处于 pre-v1 阶段,API 存在破坏性变更风险,不建议直接用于生产环境关键路径。

二、Go 语言绑定方案对比

sqlite-vec 在 Go 生态中提供 三种 集成方案:

方案驱动库依赖内存编译
CGOmattn/go-sqlite3需 CGO + C 编译器小首次慢,后续缓存
WASMncruces/go-sqlite3无 CGO(内嵌 WASM SQLite)大快
纯 Go (modernc) ✅modernc.org/sqlite零 CGO,零外部依赖小快

纯 Go 方案(你代码中的方案)

import (
    "database/sql"
    _ "modernc.org/sqlite"      // 纯 Go SQLite
    _ "modernc.org/sqlite/vec"   // 纯 Go 向量扩展
)
  • 维护者:Jan Mercl (cznic),GitLab 仓库 gitlab.com/cznic/sqlite
  • 实现方式:C 原版 sqlite-vec → Go 机器翻译(通过 libc.TLS 桥接)
  • 当前版本:v1.52.0(2026-06-06 发布)
  • 优势:无需 C 编译器,零外部依赖,内存小于 WASM 方案,部署最简单
  • 劣势:API 为底层机器翻译(X 前缀函数),文档覆盖不如原版
你代码中的方案是目前 Go 生态中 部署最简单、依赖最干净 的选择。

三、核心架构:vec0 虚拟表

3.1 影子表系统(Shadow Tables)

vec0 虚拟表在底层由 6 类影子表支撑(以 xyz 为前缀):

xyz_chunks          → 块元数据 (chunk_id, size, validity, rowids)
xyz_rowids          → rowid 到 chunk 的映射
xyz_vector_chunksNN → 向量 BLOB 存储
xyz_auxiliary       → 辅助列数据
xyz_metadatachunksNN → 二进制元数据
xyz_metadatatextNN  → 文本元数据

设计要点:

  • 向量以 chunk(块)为单位组织,而非逐行存储,利于批量 I/O
  • page_size 和 chunk_size 可调优(较大 page_size 如 32768 可通过改善顺序 I/O 降低 KNN 延迟)
  • NN 后缀暗示支持多索引/多列扩展

3.2 三种查询计划

计划idxStr header说明
FULLSCAN'1'全表暴力扫描
POINT'2'按 rowid/id 精确点查
KNN'3'K 近邻近似搜索(核心功能)

四、支持的向量类型与距离度量

4.1 向量类型

类型声明语法存储用途
float32float[384]4 bytes/元素主流 embedding(OpenAI, BGE, etc.)
int8int8[384]1 byte/元素量化向量,存储压缩
bitbit[384]1 bit/元素二值向量,Hamming 距离

4.2 距离度量

函数距离类型适用场景
vec_distance_L2(embedding, query)欧几里得距离 (L2)通用相似搜索
vec_distance_cosine(embedding, query)余弦距离语义相似度(归一化后等价于内积)

五、索引算法详解

sqlite-vec 支持 四种 索引/搜索模式:

5.1 Flat(暴力扫描)

默认模式,无索引,遍历所有 chunk 计算距离 → 100% 召回,O(N) 复杂度 → 适合 <10 万向量的小规模场景

5.2 IVF(倒排文件索引)

基于 K-Means 聚类中心构建倒排索引 → 搜索时只扫描少量聚类中心内的向量 → 适合 10 万-100 万级别

5.3 DiskANN

基于图的近似最近邻搜索,面向 SSD 优化 → Vamana 图索引算法 → 低内存占用,高磁盘效率 → 适合大规模(百万+)场景

5.4 Rescore(重排序)

量化扫描 → 浮点精度重排序的两阶段流水线 → 先粗筛(量化距离),后精排(浮点距离) → 平衡速度与精度

调优参数

chunk_size = 128 | 256 | 1024 | 2048    -- vec0 专用
page_size  = 16384 | 32768              -- SQLite 标准 pragma


六、vec0 虚拟表完整语法

建表 DDL

CREATE VIRTUAL TABLE vec_items USING vec0(
    id INTEGER PRIMARY KEY,
    embedding float[384],
    +tenant_id text partition key,
    +title text,
    +is_published boolean,
    chunk_size=1024
);

数据操作

-- 插入
INSERT INTO vec_items (id, embedding) VALUES (1, vec_f32('[0.1, 0.2, ...]'));

-- KNN 搜索
SELECT id, vec_distance_L2(embedding, vec_f32('[0.12, 0.21, ...]')) AS dist
FROM vec_items ORDER BY dist LIMIT 5;

-- 混合查询
SELECT id, distance FROM vec_items
WHERE embedding MATCH vec_f32('[...]') AND is_published = true
ORDER BY distance LIMIT 10;

-- 删除与更新
DELETE FROM vec_items WHERE id = 1;
UPDATE vec_items SET embedding = vec_f32('[...]') WHERE id = 1;


七、与主流向量数据库对比

维度sqlite-vecpgvectorChromaDBMilvusQdrant
架构嵌入式扩展PostgreSQL 扩展独立服务独立分布式独立服务
部署复杂度⭐ 零配置⭐⭐ 需 PG⭐⭐ pip install⭐⭐⭐⭐ K8s⭐⭐⭐ Docker
向量规模百万级百万-千万级百万级十亿级十亿级
索引算法Flat, IVF, DiskANNIVFFlat, HNSWHNSWIVF, HNSW 等 11 种HNSW
混合查询✅ SQL + 向量✅ SQL + 向量⚠️ 有限✅ 丰富✅ 丰富
分布式❌ 单机⚠️ 通过 PG 实现❌ 单机✅ 原生✅ 原生
WASM/浏览器✅❌❌❌❌

独特优势

1. 唯一的 WASM 向量搜索方案 — 可在浏览器中运行,支持纯前端 RAG 2. 零依赖部署 — 嵌入式 AI 应用首选 3. SQL 原生混合查询 — 向量搜索 + SQL 过滤 + JOIN 一把梭 4. RISC-V/ARM 全兼容 — 纯 C/Go 实现,交叉编译无障碍 5. 单文件数据库 — 备份迁移只需复制一个文件

明显短板

1. 无分布式 — 无法横向扩展 2. 无 GPU 加速 — 纯 CPU 计算 3. pre-v1 不稳定 — API 可能变更 4. 社区生态较小 — 运维支持不如 Milvus/Qdrant


八、适用场景评估矩阵

场景推荐度理由
本地 RAG 应用⭐⭐⭐⭐⭐零部署,SQL 混合查询
边缘设备/IoT⭐⭐⭐⭐⭐ARM/RISC-V 全兼容
浏览器端 AI⭐⭐⭐⭐⭐WASM 支持,唯一选择
Serverless 函数⭐⭐⭐⭐⭐单文件数据库
原型验证⭐⭐⭐⭐⭐快速集成
移动端 App⭐⭐⭐⭐嵌入式,离线可用
小团队产品⭐⭐⭐⭐十万级向量够用
中型 SaaS 服务⭐⭐⭐百万级可用
大型企业级搜索⭐⭐数十亿级不如 Milvus

九、总结与建议

核心优势

1. 最轻量的向量搜索方案 — 一个 .db 文件搞定一切 2. 真正的"到处运行" — 全平台覆盖 3. SQL 原生混合查询 — 远超专用向量数据库 4. 纯 Go 无依赖 — 告别 CGO 之痛

核心风险

1. pre-v1 不稳定 — API 可能大变 2. 单机天花板 — 百亿级转向 Milvus 3. 性能非最强 — "fast enough" 定位

建议

你的情况建议
原型/PoC/个人项目无脑入
小团队产品(万-十万级向量)适合,锁定版本
中型服务(百万级向量)可先上,备好迁移方案
大型生产(千万+)直接上 Milvus/Qdrant
需要浏览器端向量搜索唯一选择

参考资料

  • GitHub: https://github.com/asg017/sqlite-vec
  • 官方文档: https://alexgarcia.xyz/sqlite-vec/
  • Go Bindings: https://alexgarcia.xyz/sqlite-vec/go.html
  • modernc.org/sqlite/vec: https://pkg.go.dev/modernc.org/sqlite/vec
👍 1

想参与讨论或点赞?登录后使用完整功能

讨论回复(0)

暂无回复,登录后可参与讨论
合作

智谱 GLM-5 已上线

在智谱开放平台 BigModel.cn 打造 AI 应用。新一代旗舰模型 GLM-5 在推理、代码、智能体综合能力达到开源模型 SOTA。

领取 2000万 Tokens