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

研究日期：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