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

> 研究日期：2026年6月13日 > 研究对象：modernc.org/sqlite/vec（sqlite-vec 纯 Go 绑定）

---

一、项目概述

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

属性	值
GitHub	asg017/sqlite-vec
Stars	7,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 生态中提供三种集成方案：

方案	驱动库	依赖	内存	编译
CGO	`mattn/go-sqlite3`	需 CGO + C 编译器	小	首次慢，后续缓存
WASM	`ncruces/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 向量类型

类型	声明语法	存储	用途
float32	`float[384]`	4 bytes/元素	主流 embedding（OpenAI, BGE, etc.）
int8	`int8[384]`	1 byte/元素	量化向量，存储压缩
bit	`bit[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-vec	pgvector	ChromaDB	Milvus	Qdrant
架构	嵌入式扩展	PostgreSQL 扩展	独立服务	独立分布式	独立服务
部署复杂度	⭐ 零配置	⭐⭐ 需 PG	⭐⭐ pip install	⭐⭐⭐⭐ K8s	⭐⭐⭐ Docker
向量规模	百万级	百万-千万级	百万级	十亿级	十亿级
索引算法	Flat, IVF, DiskANN	IVFFlat, HNSW	HNSW	IVF, 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