在手机上翻三年前记的一条笔记,只记得"大概讲连接池泄漏",关键词搜索帮不上忙——语义搜索才救得了场。一提语义搜索,多数教程直接上 Milvus、Qdrant 这类常驻服务,可手机、浏览器插件、树莓派上根本没有那样的运行环境。好在还有一条轻量路线:SQLite 加一个向量扩展 sqlite-vec,一个数据库文件就能完成从入库到检索的全流程。
本文介绍 sqlite-vec 的定位与出身、安装加载、vec0 虚拟表的建表与插入、KNN 查询语法与能力边界,最后用百行内的 Python 实现一个本地笔记语义搜索。全文按"场景 → 概述 → 安装 → 建表 → 查询 → 边界 → 实战"组织。
1、端侧语义搜索的场景
语义搜索的套路早已固定:把文本喂给 Embedding 模型得到向量,查询时把问题也变成向量,再找出距离最近的 K 条,即 KNN 检索。难点从来不在算法,而在向量存在哪、怎么查。
服务端方案一抓一把:pgvector、Qdrant、Milvus、Chroma。但它们都预设了服务器、常驻进程与网络连通,端侧场景恰恰相反:
- 手机笔记 App:离线可用,数据不能出设备
- 浏览器插件:只有页面环境,WebAssembly 是唯一运行时
- 树莓派与家用小主机:内存以百 MB 计,跑不动常驻服务
- 桌面离线工具:不想为搜索功能附带一个数据库服务
这些场景里,SQLite 是公认的端侧之王:单文件、零配置、零运维,进程内嵌入没有网络开销;从 Android、iOS 到 Windows、macOS、Linux 全平台原生支持,还能编译成 WebAssembly 跑进浏览器。既然数据本来就存在 SQLite 里,向量检索最自然的落点也是 SQLite——sqlite-vec 补的就是这块拼图。
还要注意一个前提:端侧语义搜索要闭环,Embedding 模型也得在本地跑。如今这不再是障碍——几百 MB 的多语言小模型在手机上毫秒级出向量,浏览器里还能借 WebGPU 加速。模型轻了,检索侧再拖一个数据库服务就非常突兀,组件越少、越贴近 SQLite,端侧工程越简单。
2、sqlite-vec 是什么
sqlite-vec 是 Alex Garcia 开发的 SQLite 向量检索扩展,GitHub 仓库的官方定位是"一个能跑在任何地方的极小、足够快的向量检索扩展"。三个标签概括它的气质:纯 C 实现、零第三方依赖、单文件分发。
它在 vec0 虚拟表中存取向量,支持 float32、int8、bit 三种向量类型,并附带一组 vec_ 前缀的 SQL 标量函数。项目由 Mozilla Builders 资助,Fly.io、Turso 等公司赞助,官方提供 Python、Node.js、Go、Rust、Ruby 等语言绑定,官方文档持续更新。
生态位上它也站得很正:vec0 是标准的 SQLite 虚拟表,数据落在普通 shadow 表里,事务、备份、只读打开等机制一切照旧——备份整个向量库就是复制一个文件;它还能与内置全文检索 FTS5 同库共存,关键词与语义两路检索在同一个连接里就能完成,这是很多独立向量库给不了的体验。
sqlite-vec 不是凭空出现的,它是 sqlite-vss 的继任者。sqlite-vss 是同一作者更早的尝试,底层直接绑定 Meta 的 FAISS 库:FAISS 功能强大但体量重,绑定它导致扩展编译复杂、平台覆盖差,浏览器与移动端基本无缘,该项目已停止维护。sqlite-vec 推倒重来:扔掉 FAISS,用纯 C 手写向量存储与距离计算,并做 SIMD 加速,换来"SQLite 能跑的地方它就能跑"。代价是放弃 FAISS 现成的 ANN 索引,稳定版只做暴力扫描,这个取舍第 6 节细说。两代扩展对比如下:
| 维度 | sqlite-vss | sqlite-vec |
|---|---|---|
| 底层实现 | C++ 绑定 FAISS | 纯 C,零依赖 |
| 检索方式 | FAISS ANN 索引 | 暴力扫描加 SIMD |
| 平台覆盖 | 桌面平台为主 | 全平台含浏览器与移动端 |
| 维护状态 | 已停止维护 | pre-v1,仍在演进 |
一句话总结:vss 用重量换检索性能,sqlite-vec 用性能换便携,端侧要的正是后者。
注意:官方 README 明确提示 sqlite-vec 处于 pre-v1 阶段,版本间可能有破坏性变更,生产使用要锁定版本号。
3、安装与加载
最方便的入口是 Python 绑定,pip 包内置了各平台预编译好的扩展文件:
pip install sqlite-vec
装好后,加载只需三步:打开扩展加载开关、调用 load、再关掉开关。
import sqlite3
import sqlite_vec
db = sqlite3.connect("notes.db")
db.enable_load_extension(True)
sqlite_vec.load(db) # 注册 vec0 虚拟表与 vec_ 系列函数
db.enable_load_extension(False)
print(db.execute("select vec_version()").fetchone()[0])
sqlite_vec.load() 会自动定位包内的扩展并注入连接;vec_version() 用来确认加载成功与版本号。不走 Python 时,可以到 Releases 页面下载对应平台的 loadable 包,解压得到 vec0 动态库后在 sqlite3 命令行加载。以 Linux x86_64 为例:
curl -L -o vec0.tar.gz \
https://github.com/asg017/sqlite-vec/releases/download/v0.1.6/sqlite-vec-0.1.6-loadable-linux-x86_64.tar.gz
tar -xzf vec0.tar.gz
sqlite3 notes.db
两个环境细节容易踩坑。其一,macOS 自带的 Python 与 sqlite3 默认禁用扩展加载,遇到 AttributeError 报错时改用 Homebrew 版 Python 即可;其二,部分功能依赖较新的 SQLite,官方建议 3.41 及以上,可用 sqlite3.sqlite_version 检查当前版本。
4、建表与插入
向量的家是 vec0 虚拟表。下面在 sqlite3 命令行里建一张演示表并插入四条 8 维向量:
.load ./vec0
-- float[8] 表示 8 维 float32 向量列
create virtual table vec_examples using vec0(
sample_embedding float[8]
);
insert into vec_examples(rowid, sample_embedding) values
(1, '[-0.200, 0.250, 0.341, -0.211, 0.645, 0.935, -0.316, -0.924]'),
(2, '[0.443, -0.501, 0.355, -0.771, 0.707, -0.708, -0.185, 0.362]'),
(3, '[0.716, -0.927, 0.134, 0.052, -0.669, 0.793, -0.634, -0.162]'),
(4, '[-0.710, 0.330, 0.656, 0.041, -0.990, 0.726, 0.385, -0.958]');
建表语句有四个要点:
- 向量列类型是"类型加维度",float、int8、bit 三选一
- 演示用 JSON 字符串,生产用二进制 BLOB,Python 侧以 serialize_float32() 打包
- 一张 vec0 表可声明多个向量列,v0.1.6 起支持 metadata 等辅助列
- rowid 是向量主键,正文放普通表、按 rowid 关联
生产路径的细节值得展开一句:NumPy 数组要记得 .astype(np.float32) 再绑定,因为很多模型输出 float64;metadata 列与 partition key 列则把"按用户、按时间过滤"收进同一张 vec0 表,减少多表对齐的麻烦。
5、KNN 查询
检索是一条再普通不过的 SELECT:
select rowid, distance
from vec_examples
where sample_embedding match '[0.890, 0.544, 0.825, 0.961, 0.358, 0.0196, 0.521, 0.175]'
order by distance
limit 2;
match 挂在向量列上接收查询向量,上述语句返回距离最近的 2 条,输出如下:
rowid distance
----- --------------------
2 2.38687372207642
1 2.38978505134583
这条语句由四个固定部件组成:match 接收查询向量;distance 是虚拟表自动产出的伪列,默认 L2 欧氏距离,越小越近;order by distance 与 limit k 是固定搭配,共同构成 KNN 语义;查询向量同样支持参数绑定,实战里传入 BLOB 即可。需要余弦语义时,把入库与查询向量都归一化后再用 L2,或直接调用 vec_distance_cosine() 手工计算。
一个容易翻车的细节:查询向量必须与建表维度一致,且来自同一个 Embedding 模型。换模型等于换向量空间,旧数据全部失效,正确做法是新建一张对应维度的 vec0 表、重新入库后整体切换,而不是新旧混存。
6、能力边界与量化
用 sqlite-vec 前必须想清楚它的边界。稳定版的检索策略只有一种:暴力扫描——对全表每个向量算一次距离再排序,靠 SIMD 与紧凑存储把常数压小。它没有 HNSW、IVF 这类 ANN 索引,作者在 Hacker News 讨论中也坦言最初只做全量扫描;官方 ANN 跟踪 Issue同样直白:数据量再往上,即使有量化帮忙,暴力扫描也不再可行。
量化的作用正是给暴力扫描减负。官方提供 vec_quantize_binary(),把向量压成单比特位图:384 维 float 向量从 1536 字节降到 48 字节,内存占用与扫描成本同步缩水;列类型直接声明 bit[384] 或 int8[384] 也能存量化向量。二进制量化指南给出的典型打法是二进制粗筛、再回原向量精排。
再算一笔内存账,感受量化与内存能力的现状:向量存在磁盘上的 shadow 表里,暴力扫描时流式读取,无需把整库载入内存。以 10 万条 768 维向量为例,float32 原始存储约 300 MB,压成 bit 后不到 10 MB——后者放在树莓派甚至浏览器里都毫无压力,这正是端侧最看重的性质。截至 2026 年 11 月的能力现状如下:
| 能力项 | 稳定版 v0.1.6 | v0.2.0-alpha 预发布 |
|---|---|---|
| 检索算法 | 暴力扫描 | 增加实验性 ANN 索引 |
| 量化支持 | int8 与 bit 向量 | 同左 |
| 元数据过滤 | metadata 列 | 同左 |
| 适用规模 | 十万级向量以内 | 视索引实现而定 |
规模感可以这么建:个人笔记、聊天记录、收藏夹这类端侧数据通常在几千到十万级之间,正好落在暴力扫描的舒适区,毫秒到几十毫秒级返回;到百万级就该盯 v0.2.0 预发布引入的实验性索引(IVF、DiskANN、rescore),或直接换服务端方案。另外要留意维护节奏:上游仓库更新放缓,社区出现了 vlasky/sqlite-vec 等分支,选型时以官方 Releases 与文档口径为准。
7、本地笔记语义搜索实战
目标:把一堆 Markdown 笔记切块、向量化、存进一个 notes.db,再按语义检索。整体链路如下:
建模采用双表分工:chunks 普通表存正文与来源路径,chunks_vec 虚拟表只存向量,两边用 rowid 对齐。Embedding 选本地的 paraphrase-multilingual-MiniLM-L12-v2,384 维、中文可用;追求更小体积可换 bge-small-zh-v1.5,此时建表维度改成 float[512]。先把两个依赖装上:
pip install sqlite-vec sentence-transformers
sentence-transformers 首次运行会下载模型,之后全程离线。入库脚本如下:
import glob
import sqlite3
import sqlite_vec
from sqlite_vec import serialize_float32
from sentence_transformers import SentenceTransformer
model = SentenceTransformer("paraphrase-multilingual-MiniLM-L12-v2")
db = sqlite3.connect("notes.db")
db.enable_load_extension(True)
sqlite_vec.load(db)
db.enable_load_extension(False)
db.execute("create virtual table if not exists chunks_vec using vec0(embedding float[384])")
db.execute("create table if not exists chunks(id integer primary key, path text, body text)")
for path in glob.glob("notes/**/*.md", recursive=True):
text = open(path, encoding="utf-8").read()
for piece in (text[i:i + 400] for i in range(0, len(text), 400)):
emb = serialize_float32(model.encode(piece))
cur = db.execute("insert into chunks(path, body) values(?, ?)", (path, piece))
db.execute("insert into chunks_vec(rowid, embedding) values(?, ?)",
(cur.lastrowid, emb))
db.commit()
脚本逻辑很直白:每篇笔记按 400 字符切块,逐块编码成 384 维向量;serialize_float32() 把模型输出打包成 BLOB;两次插入用 lastrowid 保持向量与正文的对应关系。检索端只要拿到查询向量,一条 join 就能把语义最近的笔记找回来:
query = "数据库连接池泄漏怎么排查"
emb = serialize_float32(model.encode(query))
rows = db.execute(
"""
select c.path, c.body, v.distance
from chunks_vec v
join chunks c on c.id = v.rowid
where v.embedding match ?
order by v.distance
limit 5
""",
[emb],
).fetchall()
for path, body, dist in rows:
print(f"{dist:6.3f} {path} {body[:36]}")
查询向量通过参数绑定传入 BLOB,KNN 结果与 chunks 表 join 出正文,limit 5 即 Top-5。想要更准的召回,可以再加一路 FTS5 全文检索:关键词命中一批、向量召回一批,按距离与关键词得分合并重排,同一个连接里就能完成混合检索。整个系统没有服务进程、没有网络请求:一个 notes.db 文件拷到手机或塞进 App,语义检索能力就随身携带了。
8、总结
sqlite-vec 用纯 C 与零依赖换来了"SQLite 能跑它就能跑"的便携性,以 vec0 虚拟表加一条 MATCH 查询的低门槛 API,把向量检索装进了单文件数据库。它的边界同样清晰:稳定版只有暴力扫描,适用十万级以内的端侧数据,更大规模要等 v0.2.0 的实验性 ANN 或转向服务端方案;pre-v1 的版本状态也要求生产使用时锁定版本。对于手机笔记、浏览器插件、树莓派这类离线、小规模、重隐私的场景,建议把 sqlite-vec 作为语义搜索的默认起点,先用几十行脚本跑通,再按规模决定要不要升级方案。
留三个练习巩固:
- 给实战的双表加 metadata 列,实现只在指定目录的笔记里检索
- 用 vec_quantize_binary() 入库 bit[384] 向量,对比量化前后的内存与召回
- 把 notes.db 搬进 sql.js,做一个纯浏览器的语义搜索页面


