《AI Agent 技术原理与架构·运行时、协议与系统架构》8.2 版本仲裁与 TTL 过期

记忆层要防两件事:旧写入覆盖新写入,过期数据被当成新鲜。版本仲裁用递增版本号拒绝过时写入并留下拒绝日志;TTL 过期让读取方明确拿到 None 而不是陈旧的记忆。实验用带版本号与过期时间的 ConsistentStore 演示拒绝日志、TTL 生效前后的读取差异,说明一致性是记忆层的写纪律而不是可选项。

以下版本号与 TTL 的数值均为教学假设,不构成对任何真实系统、供应商或生产环境的承诺。30 秒的过期是演示用的数值,真实系统按记忆用途配置,但"旧写入不得覆盖新写入、过期数据读出来必须是 None"这一条不变。

8.1 讲了怎么找记忆,这一节讲记忆怎么"防旧"。记忆层有两个隐蔽的敌人:旧写入覆盖新写入,过期数据被当成新鲜。版本仲裁挡住第一个,TTL 挡住第二个。两者都是写纪律——一致性不是可选项,是记忆层成立的前提。

旧写入不得覆盖新写入

多个智能体可能同时写同一条记忆。没有版本,最后一个写入的赢——但最后写入的不一定是最新的,可能是带着旧快照的迟来者。版本仲裁的规则很简单:每条记忆带递增版本号,写入时版本号必须大于当前版本,否则拒绝。

写入当前版本裁决
第 1 版(v1)无接受
第 2 版(v2)v1接受
迟到的第 1 版(v1)v2拒绝

被拒绝不是静默消失。 拒绝要留日志,写入方要能知道"我的写被仲裁掉了"。模块里的 rejected_log 记录每次被拒的键与版本,这就是可观测性——仲裁不是黑盒,每次裁决都有迹可循。

TTL:过期就是不存在

记忆不该永生。一次会话的记忆、一条临时结论,过了有效期就该不可见。TTL 的语义要绝对明确:读一个已过期的键,返回 None,而不是返回陈旧的记忆。 返回旧值是最危险的——下游拿到过期数据当作新鲜去决策,问题就藏在看不见的地方。

TTL 生效前后的对比要能量化:

时刻操作结果
t0写入 v2,TTL 30 秒正常读:第二版:浅色模式
t0+30读取None
t0+30存活条目只剩 1 条(另一条已过期)

最小实验:版本仲裁与 TTL 生效

实验提供 ConsistentStore:put 校验版本并拒绝过时写入,get 在 TTL 过期后返回 None,live_entries 只统计未过期条目。

# file: agp_lab/memory_consistency.py | write
# tier: 3
# verify: python3 -m unittest tests.test_memory_consistency
"""记忆一致性:版本仲裁、TTL 与过期读取。

记忆条目被多个写入者并发修改时,用版本号仲裁:旧版本写入被拒绝,
避免覆盖新数据。条目带 TTL,读取时对过期条目判定为"不存在"。
本模块演示版本冲突、TTL 过期与写者数量对一致性的影响。
"""
from __future__ import annotations

import time
from dataclasses import dataclass
from typing import Any


@dataclass(frozen=True)
class MemoryRecord:
    key: str
    value: str
    version: int
    updated_at: float
    expires_at: float | None = None


class ConsistentStore:
    """带版本仲裁与 TTL 的记忆存储。"""

    def __init__(self) -> None:
        self.records: dict[str, MemoryRecord] = {}
        self.rejected: list[tuple[str, int]] = []

    def put(self, key: str, value: str, version: int, ttl: float | None,
            now: float) -> MemoryRecord | None:
        current = self.records.get(key)
        if current is not None and version < current.version:
            self.rejected.append((key, version))
            return None
        expires = None if ttl is None else now + ttl
        record = MemoryRecord(key, value, version, now, expires)
        self.records[key] = record
        return record

    def get(self, key: str, now: float) -> MemoryRecord | None:
        record = self.records.get(key)
        if record is None:
            return None
        if record.expires_at is not None and now >= record.expires_at:
            return None
        return record

    def live_entries(self, now: float) -> int:
        return sum(1 for record in self.records.values()
                   if record.expires_at is None or now < record.expires_at)


def demo() -> dict[str, Any]:
    store = ConsistentStore()
    t0 = 1000.0
    store.put("pref", "第一版:暗色模式", version=1, ttl=None, now=t0)
    store.put("pref", "第二版:浅色模式", version=2, ttl=50.0, now=t0)
    stale = store.put("pref", "第三版:旧写者", version=1, ttl=None, now=t0 + 1)
    live_before = store.get("pref", t0 + 10)
    after_ttl = store.get("pref", t0 + 60)
    store.put("temp", "临时便签", version=1, ttl=20.0, now=t0)
    live_entries = store.live_entries(t0 + 30)
    return {
        "stale_write_rejected": stale,
        "rejected_log": store.rejected,
        "live_value_before_ttl": live_before.value if live_before else None,
        "read_after_ttl": after_ttl,
        "live_entries_at_t0_plus_30": live_entries,
    }


if __name__ == "__main__":
    for key, value in demo().items():
        print(f"{key}: {value}")

运行:

cd private/labs/agp-lab
python3 -m agp_lab.memory_consistency

输出:

stale_write_rejected: None
rejected_log: [('pref', 1)]
live_value_before_ttl: 第二版:浅色模式
read_after_ttl: None
live_entries_at_t0_plus_30: 1

五条输出对应五件事:

  1. stale_write_rejected:迟到的 v1 写入被拒绝,读出的仍是 v2。版本仲裁让"旧覆盖新"不可能发生——结果是 None 是因为返回的是被拒绝前的状态。
  2. rejected_log:拒绝留下了 ('pref', 1) 这条记录。被拒有迹可循,后续审计能回答"谁被谁挡住了"。
  3. live_value_before_ttl:TTL 生效前读的是"第二版:浅色模式"。过期前的读取一切正常,问题只出现在过期之后。
  4. read_after_ttl:过了 30 秒,读取返回 None。过期就是不存在,而不是返回旧值。
  5. live_entries_at_t0_plus_30:到点后只剩 1 条存活。TTL 在批量视角下同样生效——计数会把过期条目排除。

一个值得点破的细节:read_after_ttl: None 才是正确的行为。很多实现图省事,过期后返回最后写入的值——看起来"还有数据",实际上把陈旧数据当新鲜喂给了决策。返回 None 是让"不知道"变得可见,调用方被迫处理"记忆不可用",而不是无意中用到旧数据。

版本与 TTL 的组合

版本仲裁管"新旧",TTL 管"死活",两者正交且要同时生效。一条记忆可能版本新但已过期(改得晚、活得短),也可能版本旧但还没过期(改得早、活得久)。一致性是两条纪律一起检查:先看死没死(TTL),再看新旧(版本)。

记忆状态版本TTL读取结果
新鲜新未过期返回
陈旧但存活旧未过期返回(但要警惕)
新但过期新已过期None
陈旧且过期旧已过期None

TTL 的"T"要跟记忆的用途绑定:临时结论几秒就过期,用户偏好可以存活整个会话,长期知识库根本不过期。TTL 是记忆语义的一部分,不是统一的默认值——把"多久算旧"写进记忆类型,而不是写进一个全局常量。

时钟与仲裁

版本仲裁依赖"版本号单调递增"。真实系统里版本号可以来自本地计数、中央序号或带时钟的混合方案。混合方案要小心时钟回拨——服务器时钟回拨会让"时间戳更大"误判成"版本更新"。用逻辑时钟(单调计数器)比用墙上时钟更稳,逻辑时钟不受回拨影响。

版本来源优点风险
本地计数简单多副本不统一
中央序号全局有序单点
逻辑时钟不回拨需要额外实现

与 8.1、8.3 的接口

一致性不是孤立规则,它与检索和隐私连在一起。版本仲裁保护 8.1 的索引:一次写入更新三套索引,如果写入被仲裁拒绝,索引也绝不能更新——先裁决、后索引,顺序颠倒会让被拒的写入泄漏进检索结果。TTL 与 8.3 的软删配合:过期是时间到了自动不可见,软删是主动标"不可见但未删除",两者共享同一个"不可见"的语义,只是触发源不同。

多副本的版本

单机版本仲裁简单,多副本就难了。每个副本有自己的版本号,谁的大? 副本 A 收到 v1 的写入,副本 B 也收到 v1——它们以为都是最新,其实来自不同的源。多副本版本要靠全局序号或向量时钟:每条写入带来源标记,仲裁时比较来源而非本地计数。

方案优点代价
本地计数简单多副本不统一
全局序号全局有序单点
向量时钟无中心复杂

向量时钟的仲裁规则:版本 A 是否先于 B,要比较两个来源的向量——所有来源都不超过且至少一个严格更小的,A 才先于 B。并行更新则不可比较,要靠业务合并。多副本一致性的核心是把"不可比较"暴露出来,而不是假装有个全局顺序。

锁与版本的取舍

版本仲裁和锁是两种并发控制。锁让写入串行——谁拿到锁谁写,天然无冲突,但吞吐低;版本仲裁允许并行写——冲突靠版本号拒绝,吞吐高但可能浪费(写被拒)。取舍看写入冲突频率:冲突少用版本仲裁,冲突多用锁。

方式冲突处理吞吐适用
锁串行杜绝冲突低冲突频繁
版本仲裁拒绝并重试高冲突稀疏

记忆层通常是读多写少,版本仲裁更合适——写入冲突本就少见,锁的串行代价不值得。但"合适"要实测:如果实测冲突率升高,就要切到锁或分片降低冲突。

仲裁失败的回退

版本仲裁的拒绝要有回退路径。写被拒后,写入方要么重试(拉最新版本再写),要么放弃(接受数据已更新)。重试要读最新值、基于新值重算再写,这是"写后读"的模式;放弃则要通知调用方"你的修改没生效"。

路径动作适用
重试拉新版本、重算、重写基于旧值的计算
放弃接受现状、报告未生效幂等且不重要
合并把冲突内容合并可合并的场景

回退路径要写进架构——版本仲裁只负责"拒绝",拒绝之后怎么办是另一个决策。没有回退路径,被拒的写入方只能原地打转。

架构判据

版本与 TTL 是否合格,用五条判据检查:

判据合格的样子不合格的样子
拒绝旧写低版本写入被拒最后写入者赢
拒绝留痕每次拒绝有日志仲裁静默发生
过期即 None过期读返回 None返回陈旧记忆
TTL 按用途配置每条记忆有自己的有效期全局统一 TTL
先裁决后索引被拒写入不进索引被拒内容泄漏到检索

判据第一条是"版本必须真拦得住",判据第三条才是关键:过期返回 None 是让"不知道"可见,返回旧值是埋雷。判据第五条是 8.1 与 8.2 的接缝——仲裁与索引的先后顺序错了,一致性就从源头破功。

小结

  • 版本仲裁用递增版本号拒绝旧写入,被拒绝必须留日志。
  • TTL 的语义是"过期就是不存在":读取返回 None,不返回陈旧记忆。
  • 版本管新旧、TTL 管死活,两者正交,先查死活再看新旧。
  • TTL 按记忆用途配置,不是全局常量。
  • 仲裁先于索引:被拒的写入绝不能进入检索结构。

阅读导航:上一节:8.1 向量、倒排与图存储 · 下一节:8.3 审计、软删与清除 。

常见错误与边界

  1. 让最后写入者赢。 没有版本仲裁,迟到的旧快照会覆盖新数据。
  2. 仲裁静默发生。 被拒写入不留日志,审计时无从查起。
  3. 过期返回旧值。 把陈旧记忆当新鲜喂给决策,问题藏在看不见的地方。
  4. 全局统一 TTL。 临时结论和长期知识库有效期不同,TTL 要按用途配置。
  5. 被拒内容进索引。 先裁决后索引,否则一致性从源头破功。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图