1. 一百篇文档的私域知识库为什么我最后选了 SQLite 而不是向量数据库很多人一提到私域知识库脑子里第一反应就是上一套向量数据库Milvus、Qdrant、Chroma 挨个试一遍再配个 Embedding 服务搞一套 RAG 流水线。我一开始也是这么想的直到我把需求摊开来看文档总量一百篇出头单篇平均三五千字总文本量撑死几十万字查询频率是我自己偶尔问一下并发量约等于零。这种规模下再去部署一个独立的向量数据库服务纯属给自己找麻烦。私域知识库这个词听起来唬人拆开看其实就三件事把文档切块存起来、把每块转成向量、查询时按语义相似度把最相关的块捞出来。前两件事是离线的一次性工作第三件事是在线查询。一百篇文档的向量总量按每篇切 20 块算也就两千条左右每条向量 768 维或 1024 维用 float32 存下来不过几 MB 到十几 MB。这个数据量别说向量数据库了连内存都塞不满。所以真正的问题不是用哪个向量数据库而是我能不能不引入额外服务。SQLite 本身就是单文件、零配置、跨平台的嵌入式数据库Python、Node、Go、C# 全都有成熟驱动随手一个.db文件拷走就能用。如果能让 SQLite 直接支持向量检索那整个知识库就是一个文件加一段脚本部署成本直接归零。sqlite-vec就是干这个的——它是一个 SQLite 扩展把向量列和向量相似度查询能力直接塞进 SQL 里。我实测下来的结论很直接一百篇文档以内的私域知识库SQLite sqlite-vec 是性价比最高的方案没有之一。它不需要你懂分布式不需要你维护服务进程不需要你处理网络分区一个文件搞定存储和检索。代价是它不适合百万级向量、不适合高并发、不适合复杂的过滤加向量混合查询——但这些恰恰不是小规模私域知识库的痛点。这篇文章我会把整套方案拆开讲sqlite-vec 到底怎么工作、环境怎么搭、文档怎么切、向量怎么存、查询怎么写、踩过哪些坑、性能边界在哪。如果你手上正好有几十到一两百篇文档想做成能语义检索的知识库这套东西可以直接抄作业。2. sqlite-vec 到底往 SQLite 里塞了什么2.1 它不是SQLite 的向量数据库而是一个虚拟表扩展先把概念理清楚不然后面全是糊涂账。sqlite-vec 是一个 SQLite 扩展extension加载之后你就能用CREATE VIRTUAL TABLE建一种特殊的表这种表里可以存向量并且支持用MATCH语法做相似度查询。它的定位和 FTS5SQLite 全文检索扩展是同一层级的东西——都是给 SQLite 加一种新的索引和查询能力。它内部实现的是一个虚拟表模块核心表结构大概长这样CREATE VIRTUAL TABLE vec_chunks USING vec0( chunk_id INTEGER PRIMARY KEY, embedding FLOAT[768] );vec0是它注册的虚拟表类型FLOAT[768]声明了向量维度。建好之后插入就是普通的 INSERT查询用MATCH加k N的语法SELECT chunk_id, distance FROM vec_chunks WHERE embedding MATCH ? ORDER BY distance LIMIT 5;这里的?是你查询文本转出来的向量。distance是算出来的距离值默认是 L2 距离也可以配成余弦距离。整个查询走的是 sqlite-vec 内部的向量索引不是全表扫描。2.2 向量在 SQLite 里是怎么存的这是很多人好奇的点。SQLite 原生只有 INTEGER、REAL、TEXT、BLOB、NULL 五种存储类型没有数组类型。sqlite-vec 的做法是把向量序列化成紧凑的二进制 BLOB 存进去读取时再反序列化成浮点数组。FLOAT[768]这个声明告诉扩展这个列每条数据是 768 个 32 位浮点数也就是 3072 字节。为什么用 float32 而不是 float64因为向量检索对精度没那么敏感float32 已经足够表达语义方向而且存储和计算都省一半。768 维 float32 是 3KB两千条就是 6MB加上索引开销也就十几 MB一个文件轻松装下。注意维度必须和你的 Embedding 模型输出严格一致。用 768 维的模型建了FLOAT[768]的表就不能往里插 1024 维的向量会直接报错。换模型等于重建表这个后面会讲怎么平滑迁移。2.3 距离度量L2 还是余弦别选错sqlite-vec 支持几种距离度量最常用的是 L2欧氏距离和余弦距离。这里有个容易踩的坑很多 Embedding 模型输出的向量是归一化过的模长为 1这种情况下 L2 距离和余弦距离是等价的排序结果完全一样。但如果你的向量没归一化两者就会有差异。我的建议是先确认你的 Embedding 模型是否输出归一化向量。OpenAI 的 text-embedding 系列是归一化的很多开源模型如 bge 系列默认也归一化。如果归一化了直接用默认的 L2 就行省事。如果没归一化要么在入库前自己归一化要么在 sqlite-vec 里显式指定余弦距离。别混着用否则检索结果会莫名其妙地偏。2.4 它和真·向量数据库的能力差距在哪说句公道话sqlite-vec 和 Milvus、Qdrant 这类专业向量数据库比差距是实打实的能力维度sqlite-vec专业向量数据库向量规模十万级以内舒适千万到十亿级并发查询单进程低并发高并发分布式索引类型暴力/基础近似HNSW、IVF、PQ 等丰富混合过滤支持但性能一般原生支持性能好运维成本零需要部署和维护数据持久化单文件需要配置存储看这张表就明白了sqlite-vec 的短板全在规模和并发上而这两点对一百篇文档的私域知识库来说根本不是问题。反过来它的长板——零运维、单文件、嵌入式——恰恰是小规模场景最需要的。选型不是选最强的是选最匹配的。3. 从零搭一套能跑的知识库环境、切块、入库3.1 环境准备Python 路线最省心sqlite-vec 官方提供了 Python 包安装就一行pip install sqlite-vec它自带编译好的扩展不需要你本地有 C 编译器。Python 内置的sqlite3模块默认不允许加载扩展需要手动开启import sqlite3 import sqlite_vec db sqlite3.connect(knowledge.db) db.enable_load_extension(True) sqlite_vec.load(db) db.enable_load_extension(False) # 验证扩展是否加载成功 version db.execute(SELECT vec_version()).fetchone() print(version)如果打印出版本号说明扩展加载成功。这一步是很多新手卡住的地方——enable_load_extension不开后面所有vec0相关的操作都会报 no such module。Embedding 模型我推荐用sentence-transformers加载本地的 bge-small-zh 或 bge-base-zh中文效果好768 维完全离线不依赖任何外部 API。装起来也简单pip install sentence-transformersfrom sentence_transformers import SentenceTransformer model SentenceTransformer(BAAI/bge-base-zh-v1.5) vec model.encode(这是一段测试文本, normalize_embeddingsTrue) print(vec.shape) # (768,)normalize_embeddingsTrue这个参数很关键它保证输出向量是归一化的这样后面用 L2 距离就等于余弦相似度省去手动处理的麻烦。3.2 文档切块别迷信固定长度切块chunking是知识库质量的第一道分水岭。我见过太多人直接按 500 字一刀切结果把一句话从中间劈开检索出来的片段读都读不通。一百篇文档的规模你完全有条件切得讲究一点。我的做法是按语义边界切再按长度兜底。具体来说优先按段落切一个自然段作为一个块如果段落超过 800 字再考虑拆分。拆分时优先在句号、问号、分号处断开不要从句子中间切。每个块保留 50 到 100 字的重叠overlap避免跨块的语义被切断。块太短比如少于 50 字就合并到相邻块避免产生大量无意义的碎片。用代码表达大概是这样import re def split_text(text, max_len800, min_len50, overlap80): # 先按段落切 paragraphs [p.strip() for p in text.split(\n) if p.strip()] chunks [] buffer for para in paragraphs: if len(buffer) len(para) max_len: buffer para \n else: if buffer: chunks.append(buffer.strip()) # 段落本身超长按句子再切 if len(para) max_len: sentences re.split(r(?[。]), para) sub for s in sentences: if len(sub) len(s) max_len: sub s else: chunks.append(sub.strip()) sub s if sub: chunks.append(sub.strip()) buffer else: buffer para \n if buffer: chunks.append(buffer.strip()) # 合并过短的块 merged [] for c in chunks: if merged and len(c) min_len: merged[-1] \n c else: merged.append(c) return merged这段代码不完美但比无脑定长切强太多。实测下来一百篇文档切出来大概一千五到两千五百个块正好落在 sqlite-vec 的舒适区。提示切块时最好把文档标题、章节标题也拼进块的开头比如【文档标题】正文内容。这样检索时标题信息也参与语义匹配召回质量会明显提升。这是我从实际使用中总结出来的小技巧成本几乎为零效果立竿见影。3.3 建表与入库一次搞定元数据和向量知识库不能只存向量还得存原文、来源、块序号这些元数据否则检索出来你不知道这段话出自哪篇文档。我的做法是建两张表一张普通表存元数据和原文一张虚拟表存向量用 chunk_id 关联。db.execute( CREATE TABLE IF NOT EXISTS chunks ( id INTEGER PRIMARY KEY AUTOINCREMENT, doc_title TEXT, chunk_index INTEGER, content TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ) ) db.execute( CREATE VIRTUAL TABLE IF NOT EXISTS vec_chunks USING vec0( chunk_id INTEGER PRIMARY KEY, embedding FLOAT[768] ) )入库时先插普通表拿到自增 id再用这个 id 插向量表def add_chunk(title, index, content, embedding): cur db.execute( INSERT INTO chunks (doc_title, chunk_index, content) VALUES (?, ?, ?), (title, index, content) ) chunk_id cur.lastrowid db.execute( INSERT INTO vec_chunks (chunk_id, embedding) VALUES (?, ?), (chunk_id, embedding.tobytes()) ) return chunk_id注意向量要用.tobytes()转成二进制再传直接传 numpy 数组会报错。这是 sqlite-vec 的接口约定第一次用容易踩。批量入库时记得用事务包起来两千条数据一次性提交比逐条提交快一个数量级with db: for title, idx, content in all_chunks: emb model.encode(content, normalize_embeddingsTrue) add_chunk(title, idx, content, emb)4. 查询链路从一句话到最相关的几个块4.1 基础查询MATCH 加 k 值查询的核心就一句 SQLdef search(query, top_k5): q_vec model.encode(query, normalize_embeddingsTrue) rows db.execute( SELECT c.id, c.doc_title, c.content, v.distance FROM vec_chunks v JOIN chunks c ON c.id v.chunk_id WHERE v.embedding MATCH ? AND k ? ORDER BY v.distance , (q_vec.tobytes(), top_k)).fetchall() return rows这里k ?是 sqlite-vec 的语法要求必须显式指定返回多少条候选。它内部会先按向量索引捞出 k 条再和普通表 JOIN 拿元数据。ORDER BY v.distance保证结果按相似度从近到远排。实测下来两千个块的库单次查询在几十毫秒级别完全够用。这个速度对个人知识库来说已经是秒回体验了。4.2 距离值怎么解读别只看排序很多人只关心排序不关心距离值本身。但距离值其实能告诉你很多信息。以归一化向量的 L2 距离为例距离范围是 0 到 2距离接近 0几乎完全相同的语义。距离 0.3 到 0.6语义相关通常是好的召回。距离 0.8 到 1.2弱相关可能是沾边但不精准。距离大于 1.4基本不相关属于噪声。我一般会设一个阈值比如距离大于 1.0 的结果直接丢掉避免把不相关的内容喂给后续处理。这个阈值不是固定的得根据你的模型和语料实测调整。bge 系列模型在中文语料上相关内容的距离通常落在 0.3 到 0.7 之间。注意不同模型的向量空间尺度不一样阈值不能跨模型套用。换模型必须重新标定阈值否则要么召回太少要么噪声太多。4.3 混合检索向量加关键词效果更稳纯向量检索有个通病对专有名词、型号、代码标识符这类字面精确匹配的需求不敏感。比如你问sqlite-vec 的 vec0 怎么建表向量检索可能召回一堆讲 SQLite 扩展的泛泛内容但真正包含 vec0 这个词的块反而排不到前面。解决办法是混合检索向量召回一批关键词FTS5召回一批然后做结果融合。SQLite 自带 FTS5 扩展正好用上db.execute( CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5( content, contentchunks, content_rowidid ) )查询时两路并行用 RRFReciprocal Rank Fusion融合排名def hybrid_search(query, top_k5): vec_results search(query, top_k20) fts_results db.execute( SELECT c.id, c.doc_title, c.content FROM chunks_fts f JOIN chunks c ON c.id f.rowid WHERE chunks_fts MATCH ? LIMIT 20 , (query,)).fetchall() scores {} for rank, r in enumerate(vec_results): scores[r[0]] scores.get(r[0], 0) 1 / (60 rank) for rank, r in enumerate(fts_results): scores[r[0]] scores.get(r[0], 0) 1 / (60 rank) ranked sorted(scores.items(), keylambda x: -x[1])[:top_k] return rankedRRF 的常数 60 是经验值来自信息检索领域的经典做法不用纠结。这套混合检索实测下来对专有名词类查询的召回质量提升非常明显而且实现成本很低值得加上。4.4 把检索结果拼成上下文喂给大模型知识库检索出来只是第一步最终要喂给大模型生成回答。拼接上下文时有两个细节要注意第一给每个块标上来源比如[来源文档A 第3段]这样模型引用时能说清楚出处也方便你自己核对。第二控制总长度。一百篇文档的库top 5 的块加起来可能就两三千字加上问题本身完全在主流模型的上下文窗口内。但如果你的块切得大就要注意别超限。我的经验是 top 5 到 top 8 比较合适再多边际收益递减还容易引入噪声。拼接模板大概这样def build_prompt(query, results): context \n\n.join( f[来源{r[1]} 第{r[2]}段]\n{r[3]} for r in results ) return f基于以下资料回答问题如果资料中没有相关信息请直接说明。 资料 {context} 问题{query} 5. 踩过的坑维度、性能、迁移和那些文档没写的事5.1 维度不匹配换模型等于重建表这是最容易踩、也最疼的坑。sqlite-vec 的虚拟表在创建时就固定了向量维度FLOAT[768]就是 768 维插 1024 维的向量直接报错。如果你一开始用 bge-base768 维后来想换成 bge-large1024 维没法直接改表结构只能建一张新的vec_chunks_new维度写 1024。用新模型把所有文档重新编码一遍插进新表。删掉旧表把新表改名。好在元数据表chunks不用动只需要重算向量。一百篇文档重算一遍也就几分钟的事成本可接受。但如果你有几千篇就要提前想清楚模型选型别中途换来换去。提示如果实在拿不准用哪个模型可以先建一个维度较大的表比如 1024小维度向量补零到 1024 也能插进去。但补零会稀释语义检索质量会下降只适合临时过渡不建议长期用。5.2 性能拐点什么时候该换方案我做过一组实测在同一台普通笔记本上用 bge-base 模型不同规模下的查询耗时大致如下向量条数单次查询耗时体验评价50010-20ms秒回200030-60ms秒回10000150-300ms可接受500001-2s开始卡2000005s不可用这个数据说明sqlite-vec 的舒适区在一万条向量以内也就是大概五百到一千篇文档的规模。超过这个量查询延迟会明显上升因为它的索引能力有限很多情况下退化成近似暴力扫描。一百篇文档对应两千条左右向量妥妥在舒适区。如果你未来文档量会涨到几千篇要么定期归档旧文档要么到时候再迁移到专业向量数据库。但别为了未来可能提前上重型方案那是过度设计。5.3 数据库文件加密SQLite 原生不支持得靠扩展热词里有人问sqlite 数据库文件能否加密这个问题在私域知识库场景下很现实——你的文档可能包含敏感内容.db文件被人拷走就全泄露了。SQLite 原生不支持加密需要靠 SQLCipher 这类扩展。但 SQLCipher 和 sqlite-vec 能不能共存取决于你的编译方式Python 生态里同时用这两个扩展比较麻烦。我的实际做法是文件系统层面加密。把.db文件放在加密磁盘或加密目录里靠操作系统或磁盘加密工具保护。这样不用改数据库代码sqlite-vec 照常用。对于个人私域知识库这个方案足够也最省事。5.4 备份和迁移单文件的好处这时候体现出来了SQLite 最大的好处就是单文件。备份就是复制文件cp knowledge.db knowledge_backup_20250101.db迁移就是拷到另一台机器装好 Python 和 sqlite-vec直接打开就能用。没有任何服务要启停没有配置文件要同步没有数据目录要挂载。这种一个文件走天下的体验是任何客户端-服务端架构的向量数据库都给不了的。但要注意一点复制文件前确保没有正在进行的写操作。SQLite 默认是 WAL 模式的话还有-wal和-shm两个附属文件复制时要一起带上或者先执行PRAGMA wal_checkpoint(TRUNCATE)把 WAL 合并回主文件再复制。这个细节不注意备份出来的文件可能缺数据。6. 一百篇文档之外这套方案还能怎么长6.1 增量更新新文档进来怎么处理知识库不是一次建完就完事新文档会不断进来。增量更新的逻辑很简单新文档切块、编码、插入已有的块不动。因为 sqlite-vec 的向量表是按 chunk_id 主键存的新块拿到新 id不会影响旧块。但有个问题如果某篇旧文档更新了你得先删掉它的旧块再插新块。删除时两张表都要删def delete_doc(title): ids [r[0] for r in db.execute( SELECT id FROM chunks WHERE doc_title ?, (title,) ).fetchall()] for cid in ids: db.execute(DELETE FROM vec_chunks WHERE chunk_id ?, (cid,)) db.execute(DELETE FROM chunks WHERE id ?, (cid,))注意虚拟表的删除语法和普通表一样用 DELETE但条件列必须是主键或索引列别用复杂条件性能会差。6.2 多模态扩展图片和表格怎么办纯文本知识库好办但实际文档里常有图片和表格。一百篇文档的规模我的建议是别搞复杂的多模态向量用文本描述 占位的方式处理表格转成 Markdown 文本直接当普通块处理。图片用一句话描述它的内容把描述文本当块存原图路径存在元数据里。检索命中图片描述时把原图路径一并返回需要时再打开看。这样整个检索链路还是纯文本向量简单可靠。真要做图文联合检索那是另一个量级的工程一百篇文档不值得。6.3 检索质量调优几个立竿见影的手段如果你觉得检索结果不够准按这个顺序排查和优化第一检查切块质量。把检索出来的块打印出来读一遍如果块本身读不通、语义不完整那再好的模型也救不了。切块是地基。第二加查询改写。用户的问题往往口语化直接编码效果一般。可以用大模型把问题改写成更规范的检索语句或者生成几个同义问法分别检索再融合。这一步对召回率提升很明显。第三加混合检索。前面讲的向量加 FTS5 融合对专有名词类查询是刚需。第四调 top_k 和阈值。top_k 太小会漏太大会引入噪声。阈值太严会漏召回太松会进噪声。这两个参数得在你的实际语料上试出来没有万能值。第五换更强的 Embedding 模型。如果前面都做了还不满意再考虑换模型。bge-large 比 bge-base 强但维度从 768 涨到 1024存储和计算都增加要权衡。6.4 什么时候该果断放弃 SQLite 方案说了这么多好处也得说清楚它的边界。出现下面这些情况就该考虑迁移了文档量超过一千篇或者向量条数超过五万查询延迟开始影响体验。需要多用户并发查询SQLite 的写锁会成为瓶颈。需要复杂的元数据过滤加向量检索混合查询sqlite-vec 的过滤能力有限。需要分布式部署或高可用单文件架构天然做不到。但反过来说如果你就是一个人用、文档一百篇上下、查询偶尔发生那这套方案能陪你很久而且维护成本几乎为零。选型这件事匹配比先进重要得多。我在实际使用中最大的体会是小规模私域知识库的瓶颈从来不在技术选型而在文档质量和切块策略。工具再强切出来的块读不通检索结果就是垃圾。与其纠结用哪个向量数据库不如花时间把文档整理干净、把切块逻辑调好。SQLite sqlite-vec 给了你一个足够好的起点剩下的功夫在数据本身。