把资料保存到数据库,重启后还能找到
建立SQLite文档库,观察事务、文档分块与索引同步。
服务要回答报销问题,先要有资料。我们把三份资料保存到磁盘上的数据库文件:差旅报销制度、系统权限申请和生产事故响应。程序关掉再启动,资料仍然存在,这就是持久化。
SQLite 是一个随程序使用的数据库引擎。Python 自带 sqlite3 模块,数据库保存在一个文件里。它适合我们先把数据链路做通,安装步骤也少。
文档、片段和索引分别装什么
一份文档可能很长,检索时通常先把它拆成小片段。每段保留原文、标题和文档编号,回答引用时就能找回出处。
索引帮助程序更快找到包含关键词的片段,像书后的关键词索引。我们使用SQLite的全文检索扩展FTS5;它根据词项寻找资料,给候选排序。
| 字段 | 用来做什么 | 例子 |
|---|---|---|
| tenant | 资料属于哪个团队 | alpha |
| document_id | 同一份文档的稳定编号 | travel |
| chunk_id | 文档里的一段 | travel:0 |
| title / text | 标题与原文 | 差旅制度 / 住宿限额… |
| tokens | 供全文索引搜索的词项 | 住宿、宿费… |
这里每400个字符分成一段。好处是容易观察,代价是可能切开一句话;处理长制度时,可以进一步改为按段落或标题切分。
保存存储模块
在上一节的 agentdepth-kb 目录中,新建 storage.py。这个模块负责创建数据库、保存资料、删除资料和查询。先看完整实现,随后按数据流读其中三个位置。
"""SQLite 是事实来源,FTS5 索引由同一事务内的触发器维护。"""
import re
import sqlite3
from contextlib import contextmanager
from pathlib import Path
def terms(text):
# 中文按双字滑窗切词;这是可解释的关键词匹配,不是语义理解。
result = []
for word in re.findall(r"[\u4e00-\u9fff]+|[a-zA-Z0-9_]+", text.lower()):
if re.fullmatch(r"[\u4e00-\u9fff]+", word):
result.extend(word[i:i + 2] for i in range(max(1, len(word) - 1)))
else:
result.append(word)
return list(dict.fromkeys(result))
class Store:
def __init__(self, path):
self.path = str(path)
Path(path).parent.mkdir(parents=True, exist_ok=True)
with self.connect() as db:
db.executescript("""
CREATE TABLE IF NOT EXISTS chunks (
id INTEGER PRIMARY KEY, tenant TEXT NOT NULL,
document_id TEXT NOT NULL, chunk_id TEXT NOT NULL,
title TEXT NOT NULL, text TEXT NOT NULL, tokens TEXT NOT NULL,
UNIQUE(tenant, chunk_id)
);
CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts
USING fts5(tokens, content='chunks', content_rowid='id');
CREATE TRIGGER IF NOT EXISTS chunks_ai AFTER INSERT ON chunks BEGIN
INSERT INTO chunks_fts(rowid,tokens) VALUES(new.id,new.tokens);
END;
CREATE TRIGGER IF NOT EXISTS chunks_ad AFTER DELETE ON chunks BEGIN
INSERT INTO chunks_fts(chunks_fts,rowid,tokens)
VALUES('delete',old.id,old.tokens);
END;
""")
@contextmanager
def connect(self):
db = sqlite3.connect(self.path, timeout=10)
db.row_factory = sqlite3.Row
try:
with db:
yield db
finally:
db.close()
def put(self, tenant, document_id, title, text):
# 先删旧片段再插新片段;任一步失败,整个事务回滚。
pieces = [text[i:i + 400] for i in range(0, len(text), 400)]
with self.connect() as db:
db.execute("DELETE FROM chunks WHERE tenant=? AND document_id=?",
(tenant, document_id))
for index, piece in enumerate(pieces):
db.execute("INSERT INTO chunks(tenant,document_id,chunk_id,title,text,tokens) "
"VALUES(?,?,?,?,?,?)", (tenant, document_id,
f"{document_id}:{index}", title, piece,
" ".join(terms(title + " " + piece))))
return len(pieces)
def delete(self, tenant, document_id):
with self.connect() as db:
return db.execute("DELETE FROM chunks WHERE tenant=? AND document_id=?",
(tenant, document_id)).rowcount
def search(self, tenant, query, limit):
words = terms(query)
if not words:
return []
expression = " OR ".join('"' + word + '"' for word in words)
with self.connect() as db:
rows = db.execute("""
SELECT c.document_id,c.chunk_id,c.title,c.text,bm25(chunks_fts) AS rank
FROM chunks_fts JOIN chunks c ON c.id=chunks_fts.rowid
WHERE chunks_fts MATCH ? AND c.tenant=?
ORDER BY rank,c.chunk_id LIMIT ?
""", (expression, tenant, limit)).fetchall()
return [dict(row) for row in rows]Store 表示一个资料库。创建它时传入数据库文件位置;put 保存文档,已有相同编号时更新;delete 删除当前团队的文档;search 搜索当前团队的资料。
事务把几次数据库操作当成一个整体。本例更新文档时先删除旧片段,再写入新片段。两步都成功才提交,中间失败就回滚,保留原来的文档。FTS5索引通过触发器同步增删,避免正文改了但搜索还返回旧内容。
? 是SQL参数占位符。文档内容作为参数交给数据库,和SQL语句本身分开处理。
导入三份资料
新建 seed.py:
"""直接写入本地 SQLite;重复运行覆盖同 ID,无需先启动服务。"""
import os
from pathlib import Path
from storage import Store
DOCUMENTS = [
("travel", "差旅报销制度", "差旅报销须在出差结束后30天内提交。住宿发票须附酒店账单。"),
("access", "系统权限申请", "系统权限申请须由直属主管审批,再由运维开通。离职当天撤销权限。"),
("incident", "生产事故响应", "生产事故由值班工程师先止损,再通知负责人。恢复后两个工作日内完成复盘。"),
]
def seed():
store = Store(os.getenv("KB_DB_PATH") or Path(__file__).parent / "data" / "kb.sqlite3")
for doc_id, title, text in DOCUMENTS:
count = store.put("alpha", doc_id, title, text)
print(f"写入 {doc_id}: {count} 个片段")
if __name__ == "__main__":
seed()在已激活环境的终端中执行:
python seed.py写入 travel: 1 个片段
写入 access: 1 个片段
写入 incident: 1 个片段执行后,目录里会出现 data/kb.sqlite3。再运行一次导入脚本,相同文档会更新到相同编号,片段数量不会因为重复导入不断增长。
亲眼观察更新和删除
保存为 storage_check.py:
from storage import Store
# 单独使用一个数据库,避免覆盖后面问答项目的资料。
store = Store("data/storage-check.sqlite3")
store.put("alpha", "travel", "差旅制度", "住宿费用每天上限500元。")
print("第一次:", store.search("alpha", "住宿", 3)[0]["text"])
# 新建对象模拟重新打开数据库,资料仍然在磁盘上。
reopened = Store("data/storage-check.sqlite3")
print("重新打开:", reopened.search("alpha", "住宿", 3)[0]["text"])
reopened.put("alpha", "travel", "差旅制度", "住宿费用每天上限600元。")
print("更新后:", reopened.search("alpha", "住宿", 3)[0]["text"])
reopened.delete("alpha", "travel")
print("删除后:", reopened.search("alpha", "住宿", 3))运行:
python storage_check.py第一次: 住宿费用每天上限500元。
重新打开: 住宿费用每天上限500元。
更新后: 住宿费用每天上限600元。
删除后: []最后的空列表表示索引里也没有这份资料了。数据库保存的不只是一次运行的结果,还承接后续更新与删除。
若创建数据库时报 no such module: fts5,当前Python连接的SQLite未包含全文检索扩展。安装包含FTS5的Python发行版后,在该解释器下重建虚拟环境;可以用下面的命令检查:
python -c "import sqlite3; c=sqlite3.connect(':memory:'); c.execute('CREATE VIRTUAL TABLE probe USING fts5(text)'); print('FTS5 ready')"课后练习展开习题收起习题
练习:同编号是否会覆盖另一个团队?
在 storage_check.py 中,为 beta 团队添加同样编号的 travel,内容写“住宿费用每天上限800元”。然后删除alpha的文档,再搜索beta的资料。
参考操作与结果
store.put("beta", "travel", "差旅制度", "住宿费用每天上限800元。")
store.delete("alpha", "travel")
print(store.search("beta", "住宿", 3)[0]["text"])结果是“住宿费用每天上限800元。”。SQL的删除条件同时包含团队和文档编号。服务接口还需要确认用户属于哪个团队,第四节会把这个入口接好。
进一步了解全文索引,可查阅 SQLite FTS5文档。