智能体工程 · 11g
文档换了版本,缓存还能沿用哪一份?
读完能做的判断:用同一快照追踪资料、索引与缓存键,区分新证据和旧命中。
11g · 缓存与索引一致性实验
⏱ 阅读约 32 分钟 · 动手实践另计
本章保留教学代码、路径说明与历史验证结论;完整实验工程和运行记录未随本站及公开仓库分发。命令用于说明调用方式,复现需自行准备对应实现、数据与环境。
一句话带走:缓存命中只说明过去保存过一个结果;能否交给现在的用户,还要核对身份、当前语料、版本与权限。
实验目标
- 用三层表解释缓存命中为什么仍要查当前原文。
- 运行 demo,找到 cold、hit、expired 和 corpus_changed。
- 从失败发布与并发撤权测试中找出已验证的条件和仍未锁住的时间窗口。
本章承接查询改写与多轮检索实验,示例工作目录记作 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 写事务内再次核对语料、插入完整快照、更新活动指针并提交。这样不会出现“指针已经是新版,向量只写了一半”。
向量计算在事务之前,期间语料可能改变。事务内核对负责发现这个窗口;变化时明确抛出 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 原理按上述官方文档校核。