研究日期：2026年6月13日
研究对象：modernc.org/sqlite/vec（sqlite-vec 纯 Go 绑定）
一、项目概述
sqlite-vec 是 Alex Garcia (asg017) 开发的 SQLite 向量搜索扩展，定位为 sqlite-vss 的继任者。核心设计哲学："足够快"（fast enough）+ 无处不在（run anywhere）。
⚠️ 重要提醒：目前仍处于 pre-v1 阶段，API 存在破坏性变更风险，不建议直接用于生产环境关键路径。
二、Go 语言绑定方案对比
sqlite-vec 在 Go 生态中提供 三种 集成方案：
纯 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 三种查询计划
四、支持的向量类型与距离度量
4.1 向量类型
4.2 距离度量
五、索引算法详解
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;
七、与主流向量数据库对比
独特优势
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
八、适用场景评估矩阵
九、总结与建议
核心优势
1.
最轻量的向量搜索方案 — 一个
.db 文件搞定一切
2.
真正的"到处运行" — 全平台覆盖
3.
SQL 原生混合查询 — 远超专用向量数据库
4.
纯 Go 无依赖 — 告别 CGO 之痛
核心风险
1.
pre-v1 不稳定 — API 可能大变
2.
单机天花板 — 百亿级转向 Milvus
3.
性能非最强 — "fast enough" 定位
建议
参考资料
- 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
