🏠 总目录📚 本教程 11g · 缓存与索引一致性实验 ← →

智能体工程 · 11g

文档换了版本,缓存还能沿用哪一份?

读完能做的判断:用同一快照追踪资料、索引与缓存键,区分新证据和旧命中。

11g · 缓存与索引一致性实验

⏱ 阅读约 32 分钟 · 动手实践另计

本章保留教学代码、路径说明与历史验证结论;完整实验工程和运行记录未随本站及公开仓库分发。命令用于说明调用方式,复现需自行准备对应实现、数据与环境。

一句话带走:缓存命中只说明过去保存过一个结果;能否交给现在的用户,还要核对身份、当前语料、版本与权限。

实验目标

本章承接查询改写与多轮检索实验,示例工作目录记作 knowledge-assistant。身份、语料与数据库都是原创教学数据,无需下载模型或调用付费接口。

设想梅上午查看“阀门检查”,得到一段步骤。下午管理员发布修订 2,并撤销了梅的阅读权限。上午的缓存行还在。“缓存命中”既不能证明步骤仍有效,也不能证明梅仍有权看。我们需要重复利用可计算的部分,同时让 SQLite 当前文档状态决定能否返回证据。

先分清三个对象

层 本例保存什么 有效性依据
原文与权限 core 的 documents / chunks,修订、状态、readers 可信入库与管理员维护;查询核对当前活动版本和权限
派生索引快照 片段 ID、教学向量、配置与语料指纹 可以从当前可见原文重建,活动指针只指完整快照
检索证据缓存 查询绑定、ID、修订、排名分数与过期时间 完整键、TTL 和当前状态复验;不能直接拿旧正文回答

记住这条依赖:当前原文与 ACL → 可重建的索引快照 → 有期限的证据引用。返回时再绕回第一层,用引用重新取当前正文。删掉派生表可以重建;删掉原文改变业务事实。

本例建立四张 cache_ 表:数据库标识、完整快照、活动指针和证据缓存。现有 core 表继续提供原文与权限,未改动其入库、删除或检索实现。向量、查询与哈希没有加密;哈希用于识别和失效,不是登录凭证或访问控制。Identity 由可信调用层提供,本模块不负责真实认证。

检查点 1. 缓存没有正文,是否就能跳过 ACL?

不能。旧引用也可能指向现在不可见的片段。查询仍要检查 scope、租户、subject 权限和活动修订;返回正文还要从当前可见语料重新取。

示例命令与记录格式

下面 cwd 都是示例目录 examples/knowledge-assistant,解释器需自行准备;此模块及测试只依赖标准库和已有 core。

python -m unittest test_cache_lab -v
python cache_lab.py

demo 默认在 .runtime/cache-日期-时间/ 保存 JSON 报告、失败记录、SQLite 数据库和原创 Markdown。输出路径必须是新的,已存在会退出 2 并报 output_already_exists。指定路径时给它新名字:

python cache_lab.py --output .runtime/my-cache-run-01

先检查四步:首次 cold;相同条件再次 hit;独立新 Python 进程读同库仍 hit;注入时钟推进到过期边界后 expired。没有为 TTL 等待一分钟,也没有靠 sleep 碰运气。

本轮实际报告在 validation/cache-demo-final-20261011/,共八步查询与一个预期发布失败。JSON 包含缓存原因、快照与语料指纹、前后计数、耗时以及配置/语料/代码哈希。报告正文是教学数据,不应照搬为真实用户证据日志策略。命中仍会读当前语料;单次小样本耗时不能用于加速比例、生产容量或质量结论。

检查点 2. 两次 hit 耗时不同,是否说明缓存坏了?

差异不足以推出问题。命中仍读取当前语料、校验快照与复验指针。先核对状态、指纹和权限,再设计独立重复性能实验;本章没有运行那种实验。

在 JSON 中标出一次命中、一次过期和一次语料变化,分别说明缓存曾保存了什么、当前还能使用什么。

缓存键必须包括新出现的证据

只用 query 会混合不同人的结果;加 tenant 仍可能混合同租户成员。只检查旧引用也不够:新增文档、权限扩大都可能带来更合适的证据,旧片段本身却没有变化。

键中的信息 漏掉的后果
数据库绝对路径与持久随机 ID 相同片段 ID 跨库或异位置复用
tenant、subject、排序后的 scopes 不同身份或权限范围混用
完整当前可见语料指纹 新资料、权限扩大、正文与修订变化不失效
解析/编码器版本、维度和配置 旧向量与新契约混用
查询、k、上下文字符预算 不同截取要求复用错误结果

完整指纹覆盖当前身份可见的全部片段、正文、修订、出处和 readers。不可见文档变得可见,会进入完整集合并改变指纹;只属于别人的新文档不影响当前人的集合。本例按身份建快照,不能用它的开销推算生产共享索引。

负缓存是最容易漏掉的例子。上午没有“轨道舱”,缓存保存空引用;下午新增清单。只查旧引用会得出“没有引用需要检查”,继续返回无证据。完整可见语料指纹让空结果失效,下一次才能找到新文档。demo 实际展示了这一步。

更改 parser_version 标签会触发缓存失效,但不会自动把源文档按新规则重新入库。实际解析算法变化,还要升级 core 版本、重新处理源文件并验证数据迁移。

检查点 3. 旧引用都仍可见,权限扩大为何要重算?

旧证据可见不代表结果仍完整。扩大权限后,新增可见资料可能更适合查询。完整指纹既处理旧证据失效,也处理新证据加入。

教学向量只验证契约

TeachingTokenHashEncoder 使用 core 分词,把 token 的 SHA-256 映射到固定桶、累计词频并归一化,默认 32 维。查询与片段向量逐个求点积、完整扫描排序。哈希桶会碰撞,不代表学会了语义。

为了让无词项证据的查询可解释,本例先以 BM25 > 0 的片段集合为门槛,再按教学点积排序。BM25 是词项门槛,点积不是置信度概率。mode 明确为 teaching_hash_exact_lexical_gate。

实验检查持久化向量的条数、维度、有限数和编码器指纹,以及配置变化是否失效。没有神经 embedding、cross-encoder、HNSW 图、ANN 召回率或百万向量规模测试。换成真实编码器后,还需验证权重版本、输入前缀、模型输出及独立查询质量,不能把缓存测试改名当作模型评测。

检查点 4. 维度正确、数值有限,是否证明模型质量?

只证明可以按当前存储和计算契约处理。质量需要独立查询、相关性标注和检索指标;本例是固定哈希计数器。

先建完整快照,再切指针

发布顺序是:读取完整可见语料并计算指纹;编码全部片段并校验;在一个 SQLite 写事务内再次核对语料、插入完整快照、更新活动指针并提交。这样不会出现“指针已经是新版,向量只写了一半”。

发布新快照时,怎样避免看到半个版本?先在事务外计算候选快照 S2,再在同一 SQLite 写事务内重新核对当前语料、插入完整快照 S2、切换活动指针并提交。失败则回滚,旧指针仍指 S1。旧指针保留只证明发布未切换,S1 若与当前权限或语料不符仍不可作答。这里只表示同库事务,不表示外部向量库或断电恢复已验证。 怎样避免发布半个索引版本? S1 / S2 是快照标识,不是原文修订号 ① 先准备候选 S2 读取可见语料 → 计算并校验全部向量 此时活动指针仍指 S1 ② 以下步骤放在同一写事务 重新核对完整可见语料是否变化 插入完整 S2,再切活动指针 → S2 全部成功 → COMMIT 期间检查失败 / 异常 → ROLLBACK 提交成功:S2 整体可见 不会先切指针、再补剩余向量 回滚:旧指针仍指 S1 保留旧指针 ≠ 允许旧证据回答 仍须符合当前语料、修订与权限 同库 SQLite 事务示意;外部向量库 需要另外设计发布与恢复协议。 未验证断电、硬重启或磁盘损坏。
S1/S2 是索引快照标识。完整快照与活动指针在同一 SQLite 事务内发布;回滚留下旧指针,但不授予旧证据继续作答的资格。 窄屏可在图内左右滑动查看完整图示。

向量计算在事务之前,期间语料可能改变。事务内核对负责发现这个窗口;变化时明确抛出 corpus_changed_before_publish。进入写事务后,另一个 core 写入者不能同时提交改动。

before_publish 故障钩子在新快照插入后、指针切换前抛出异常。真实 SQLite rollback 后,新快照不留存,旧指针不变。demo 失败前后都是两个快照、一个指针、三条证据;测试还读取指针确认其未变化。

但是保留旧指针不等于允许旧快照作答。当前原文可能已是修订 2,旧快照仍代表修订 1;不匹配时必须拒绝或成功重建。旧快照是诊断和回滚材料,不能绕过当前权限与修订。

core 使用 WAL。官方说明区分 WAL 与传统 rollback journal 的提交机制;这里仅测试进程内异常回滚和指针一致性,没有模拟断电、硬重启或磁盘损坏。SQLite WAL、原子提交说明是机制校核入口,文档原理不能代替本地未运行实验。

检查点 5. 发布失败,直接回退旧指针最稳妥吗?

先比较旧快照与现在的完整可见语料。不匹配时只能保留用于诊断,不能给用户旧证据,否则删除、撤权和新修订可能被容错回退绕过。

命中也要返回前复验

命中时检查当前身份 scope、完整可见语料、活动快照、配置与向量;再检查证据的校验和、绑定、引用、修订、有限分数和 TTL。缓存只保存 ID/revision/score,最终正文重新取自 core 当前可见语料,不返回未复验的旧候选诊断。

测试用两个 Event 控制真实并发撤权:读线程先命中,在返前钩子等待;主线程用另一 SQLite 连接提交 readers=[],再唤醒。最后完整指纹不同,读者丢弃旧引用并最多重做一次,实际返回空 context 和 changed_during_read,无需猜测线程时序。

另一个测试在返前发布不同维度的活动快照,读者必须发现指针变化。两轮都不稳定时明确报 corpus_unstable_before_return,没有无限重试。

最终复验之后,管理员仍可能在业务发送响应之前再次撤权。固定 Identity 不订阅 token 撤销;这里没有跨系统权限锁。若需要更严格时间边界,应定义授权快照、响应时点与传输协议,再专门验证。

检查点 6. Event 测试通过,能保证任意时刻撤权后都不发正文吗?

它证明复验之前提交的撤权会被发现,并排除旧证据。复验之后的未来变化和响应传输没有共同原子边界。

寿命、上限和清理分别负责什么

默认 TTL 60 秒,时钟可注入,now >= expires 即过期。时间必须有限非负;倒退到条目创建时间之前会明确失败。配置拒绝无穷 TTL、零寿命、布尔维度和非法上限。

证据默认全库最多 32 条,新写入按创建时间和键淘汰最旧项。各实例写入采用自身配置,这不是每租户存储配额。淘汰证据不删除原文;索引快照也不跟着条目上限一起消失。

撤权是逻辑失效,旧行可能还在盘上。证据留到 TTL/上限清理;未被活动指针引用的快照由显式 cleanup() 清理。当前指针可以留到下次请求重建,留存不代表有效。cleanup 只删自己 cache_ 表,demo 实际删五条证据和三个旧快照,原文仍是两个 documents、两个 chunks。

SQL DELETE 不是物理擦除,数据库/WAL/备份可能保留旧字节。物理删除需要另一套文件、日志、备份和密钥生命周期设计;本章只验证派生行逻辑清理。

检查点 7. TTL 很短,是否不再需要语料指纹?

仍需要。短寿命内也可能撤权、删除或修订。TTL 限制复用时间,指纹与当前权限检查处理事实变化;指纹也不能替代容量和旧行清理。

测试证据应该怎样读

本模块 25 个测试使用真实临时 SQLite,覆盖持久化与新进程命中、TTL、版本/配置变化、修订/删除、权限撤销/扩大、新文档、身份/数据库隔离、坏向量/缓存引用、发布故障、条目上限、派生表清理、并发撤权和指针切换。

RED 与失败日志也保留:最初缺实现的失败与真实无缓存基线上的五个行为失败分开记录;活动指针/编码器变化先观察到没有拒绝的失败再修正。demo 新进程检查曾出现缺字段 ERROR,修正检查后保存行为 RED,再完成实现。GREEN 只说明这些契约在本次环境成立,不是全仓库、真实模型或生产系统的验证。

外部向量库与 SQLite 指针不能共用这里的单事务。改用外部服务后,需要另行设计版本绑定、准备/发布、恢复与观察点。本章没有运行 Redis、分布式更新或 ANN 性能实验。

检查点 8. 下一项实验怎样才能讨论 ANN?

固定真实语料、查询、相关性标注和真实编码器版本,保留精确检索参考,再测 ANN 召回、时间分布、更新可见性和资源占用。本章的哈希桶全扫描无法提供这些结果。

走神救援

只记三个动作:命中读当前语料;发布先完整后切指针;返回前再核对。 再记:引用仍在不等于结果完整;撤权不等于物理擦除;异常回滚不等于断电恢复。

打开 JSON 后先比较前两步 key/snapshot/corpus,再找新增轨道舱后 corpus 为什么改变,最后核对失败前后计数与测试中的旧指针。完成这些即可结束本章,外部服务与更大模型留待独立实验。

来源与采用范围

模型版本管理系统的实现要点提供版本、元数据、回滚和权限问题;向量数据库选型对比引出持久化、精确扫描、ANN 与规模验证的区分。这里转换为本地原创实验,不复刻公司案例、收益数字或产品容量断言;SQLite 原理按上述官方文档校核。

打卡记录保存在你的浏览器里,首页能看到总进度