sqlite-vec 实战在 SQLite 里跑向量搜索从建表到 KNN 检索一篇讲清含避坑速查【免费下载链接】sqlite-vecA vector search SQLite extension that runs anywhere!项目地址: https://gitcode.com/GitHub_Trending/sq/sqlite-vecsqlite-vec 是一个纯 C 编写的 SQLite 扩展它让任何能跑 SQLite 的环境——服务器、浏览器 WASM、树莓派——直接具备向量相似度搜索能力不用额外部署 Elasticsearch、Milvus 这类专门组件。它解决的核心痛点是做本地 AI 应用、边缘设备或小规模 RAG 时为几百条到几百万条向量单独维护一套向量数据库运维成本远超数据本身的价值。它适合的对象很明确Python/Node/Go/Rust 里已经有 SQLite 数据层、又想让按语义找相似这件事和原有 SQL 活在同一个文件里的开发者。一个真实场景你在给笔记 App 做语义搜索功能用户本地有 2 万条笔记的 embedding。传统做法是把向量同步到云端向量库断网就歇菜或者在本地起一个 chroma 服务多一个进程、多一个端口、多一份持久化要操心。sqlite-vec 的做法是embedding 直接存在你已有的那个.db文件里MATCH一条 SQL 就出结果和存业务数据是同一个连接、同一个事务。⚡ 最短路径上手3 分钟跑通向量检索环境要求一行带过Python 3.9或任意语言 一个支持 load_extension 的 SQLite不需要任何额外服务。先装包。PyPI 上的sqlite-vec同时提供预编译的扩展二进制和加载逻辑装完即用pip install sqlite-vec下面是完整的最小可运行示例跑完你会看到 top-3 相似结果。整段代码的关键在serialize_f32sqlite-vec 收向量有两种格式JSON 字符串和紧凑二进制这里用二进制省 4 倍体积、也避免解析开销。import sqlite3, struct import sqlite_vec def serialize_f32(v): # 紧凑二进制4维 float32 只占 16 字节 return struct.pack(f{len(v)}f, *v) db sqlite3.connect(:memory:) db.enable_load_extension(True) # SQLite 默认禁止加载扩展必须显式打开 sqlite_vec.load(db) # 加载 vec0 虚拟表实现和标量函数 # 建表声明向量列的元素类型和维度这是全库唯一的schema db.execute(CREATE VIRTUAL TABLE vec_items USING vec0(embedding float[4])) with db: # 一个事务批量写入 for rowid, vec in [(1, [0.1]*4), (2, [0.2]*4), (3, [0.3]*4), (4, [0.4]*4), (5, [0.5]*4)]: db.execute(INSERT INTO vec_items(rowid, embedding) VALUES (?, ?), (rowid, serialize_f32(vec))) # KNN 检索MATCH 触发向量搜索distance 是内置输出列 rows db.execute( SELECT rowid, distance FROM vec_items WHERE embedding MATCH ? ORDER BY distance LIMIT 3, (serialize_f32([0.3, 0.3, 0.3, 0.3]),), ).fetchall() print(rows) # [(3, 0.0), (2, ~0.18), (4, ~0.18)]不想要 Python 生态的话Nodenpm install sqlite-vec、Ruby、Rust、Go 都有等价包甚至可以直接编译仓库里的单文件 sqlite-vec.c 静态链进任何 C 项目。 数据生命周期建表 → 写入 → 检索建表只需一行 SQLvec0是虚拟表向量实际存在若干影子表里ARCHITECTURE.md 有完整的影子表结构但对外你只需要关心这张逻辑表CREATE VIRTUAL TABLE vec_documents USING vec0( document_id integer primary key, -- 主键列检索时用来 JOIN 回业务表 contents_embedding float[768] -- 向量列默认 L2 距离 );为什么主键列这么重要vec0 里不建议塞大段业务文本检索出document_id后 JOIN 回真正的documents表取原文这才是官方推荐的组织方式见 site/features/knn.md。如果确实想省掉 JOIN可以用辅助列CREATE VIRTUAL TABLE vec_chunks USING vec0( contents_embedding float[1024], contents text -- 前缀 辅助列只 SELECT 不参与 WHERE );辅助列适合常出现在 SELECT、从不出现在 WHERE的大字段原文、URL、图片 BLOB。反过来如果你要在 KNN 时按标签/评分过滤就用普通声明的元数据列——它们会被索引可以直接进WHERE。写入JSON 或二进制二选一-- 两种格式都合法JSON 调试方便二进制省空间 INSERT INTO vec_documents(rowid, document_id, contents_embedding) VALUES (1, 1, [-0.2, 0.25, 0.34, ...]); -- JSON INSERT INTO vec_documents(rowid, document_id, contents_embedding) VALUES (2, 2, vec_f32([0.44, -0.50, 0.35, ...])); -- 二进制关键在查询向量的格式不必和表里存储的格式一致混着来也没问题但向量维度必须和建表声明的一致维度不匹配直接报 mismatch 错误。检索MATCH 一行 SQL 出 KNNSELECT d.id, d.contents, m.distance FROM ( SELECT document_id, distance FROM vec_documents WHERE contents_embedding MATCH :query AND k 10 -- 关键k 让引擎只算 top-10早停全表扫描 ) m JOIN documents d ON d.id m.document_id;关键在k 10它告诉引擎只需要前 10 个配合元数据过滤时尤其重要——不带k的写法会让引擎先把全表算完再截断有过滤条件时慢一个量级。SQLite 3.41 也可以写LIMIT 10低版本只能靠k。想要余弦相似度建表时加一个参数即可CREATE VIRTUAL TABLE vec_documents USING vec0( document_id integer primary key, contents_embedding float[768] distance_metriccosine -- 默认是 L2 ); 性能取舍三条建议各带适用条件1. 量化压缩float32 → int8体积砍到 1/4embedding 模型默认吐 float32768 维就是 3KB/条。用vec_quantize(int8, ...)压成 1 字节/元素float16 是 2 字节INSERT INTO vec_items(rowid, embedding) SELECT rowid, vec_quantize(int8, embedding) FROM raw_embeddings;适用条件百万级以上向量、磁盘或内存吃紧。代价召回精度有轻微损失对找完全一样的这类需求要实测确认。2. 分区键查询模式天然按租户/时间切分时才用CREATE VIRTUAL TABLE vec_documents USING vec0( document_id integer primary key, user_id integer partition key, -- 索引按 user_id 分片 contents_embedding float[1024] ); -- 查询时用 约束引擎只扫该分片 SELECT ... WHERE contents_embedding MATCH :query AND k 20 AND user_id 123;适用条件每条查询都带强分区约束每用户只搜自己的。硬指标每个唯一 key 值下至少几百条向量。每用户只有十几条笔记就按 user 分片等于把索引切碎KNN 反而变慢——退而求其次用organization_id或按年这种粗粒度 key。3. 元数据过滤走 vec0别在外面套 WHERESELECT document_id, distance FROM vec_documents WHERE contents_embedding MATCH :query AND k 5 AND genre scifi AND mean_rating 3.5;适用条件过滤列是 vec0 表里的元数据列且只用 ! 这六个比较运算符。代价元数据列最多 16 个、类型只支持 TEXT/INTEGER/FLOAT/BOOLEAN把过滤条件写在 vec0 外层子查询外面再 JOIN 过滤等于放弃了引擎的原生过滤路径。️ 避坑速查现象原因解法not authorized/ 扩展加载失败运行时没开启load_extension或路径指向了别的平台的二进制Python 里db.enable_load_extension(True)后再 load确认扩展文件与当前 OS/架构匹配LIMIT 10没有提速甚至报错SQLite 3.41 不支持在 vec0 上用 LIMIT 截断 KNN改写AND k 10维度 mismatch 报错查询向量维度 ≠ 建表声明的float[N]查 embedding 生成侧的维度或重建表维度是建表时定死的JSON 写入体积膨胀字符串里每个数带符号位和引号是二进制的约 4 倍生产写入统一用vec_f32()/ 二进制序列化元数据 WHERE 不生效或报错用了LIKE、IS NULL、IN等不支持的运算符只保留 ! 布尔列只能用和!加了分区键后查询变慢分片过度每个 key 值下向量太少换更粗粒度的 key或去掉分区键升级后 SQL 突然不兼容项目仍是 pre-v1API 会破坏性变更锁定版本升级前跑一遍 tests/ 里的回归用例 适用边界什么时候该用它什么时候别用适合单文件、单进程场景本地 AI 助手、移动端/嵌入式设备、桌面工具向量数据和业务数据同库同事务中小规模向量检索几千到百万级条KNN 延迟在毫秒到几十毫秒量级完全够用需要在向量结果上叠加 SQL 能力元数据过滤、JOIN 业务表、混合 BM25 全文搜索浏览器端 WASM 环境——这是几乎其他向量库都进不去的地方不适合千万级以上、多节点水平扩展的检索——它是单文件存储没有分片复制这个规模该上专门的向量数据库高频随机更新向量 低延迟读同时要求的场景删除/重建影子表有放大代价需要向量库自带 embedding 推理、GPU 加速的场景——sqlite-vec 只负责存储和检索embedding 生成在库外完成现在就可以做的一件事在你项目里pip install sqlite-vec拿上文那个 30 行的最小示例把[0.1]*4换成你现有业务里任意一批真实 embedding 跑一遍——能出 top-3就说明你的 SQLite 数据层已经具备语义搜索能力了。【免费下载链接】sqlite-vecA vector search SQLite extension that runs anywhere!项目地址: https://gitcode.com/GitHub_Trending/sq/sqlite-vec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
