以下数字为教学示例,不构成对任何真实模型或供应商训练结果的承诺。
Agent 出错时,日志里通常只有一句“任务失败”。团队想知道:模型看到了哪段上下文、检索返回了什么、工具调用参数是什么、执行结果是什么。没有这些,排查只能靠猜;有了这些,才能把一次失败变成可重演的案例。
记录与回放(record/replay)就是为这件事设计的:运行时记录关键事件,事后按相同顺序重放,逐步比对差异。它不是“把日志存下来”那么简单,关键在于记录什么、记录多细、回放时哪些东西可以重算、哪些必须固定。
最小事件集
一个 Agent 请求至少包含五类事件:
| 事件 | 内容 | 作用 |
|---|---|---|
| request | 用户输入、系统提示、参数 | 确定起点 |
| model | 模型版本、采样参数、输出 | 复现生成 |
| retrieval | 查询、索引版本、返回片段 | 复现证据 |
| tool | 工具名、参数、返回、状态 | 复现动作 |
| output | 最终答案、引用、状态 | 复现结果 |
这五类构成“最小可解释集”。少任何一类,回放都会缺一块:没有 retrieval,不知道模型基于什么回答;没有 tool,不知道动作是否执行;没有 model,无法判断是提示问题还是模型变化。
事件之间要能对齐。最简单的方式是给每个事件一个步骤号,按顺序排列;复杂系统可以用 trace ID + span ID,把并行的检索和工具调用组织成树。
摘要还是全文
记录全文最忠实,但成本高、隐私风险大。记录摘要(哈希)便宜,但只能判断“是否相同”,无法还原内容。
实际系统通常分层:
| 层 | 内容 | 保留期 |
|---|---|---|
| 摘要 | 哈希、长度、版本 | 长期 |
| 结构化 | 参数、状态、引用 ID | 中期 |
| 全文 | 提示、检索片段、工具返回 | 短期/脱敏 |
摘要用于回归比对,结构化用于排障,全文用于深度复现。三层按需保留,而不是全部长期保存。涉及个人信息的内容应该在写入前脱敏,而不是事后删除。
最小实验:完整性、首个差异与状态
下面的实验定义五类必需事件,检查记录是否完整,逐步骤比对录制与实时事件,并报告首个差异位置。
# file: agp_lab/record_replay.py | write
# tier: 3
# verify: python3 -m unittest tests.test_record_replay
"""Record/Replay:记录最小事件集,按步骤比对重放。"""
from __future__ import annotations
from dataclasses import dataclass
@dataclass(frozen=True)
class Event:
step: int
kind: str
digest: str
REQUIRED = ("request", "model", "retrieval", "tool", "output")
def completeness(events: list[Event]) -> dict[str, bool]:
present = {event.kind for event in events}
return {kind: kind in present for kind in REQUIRED}
def first_mismatch(recorded: list[Event], live: list[Event]) -> int | None:
for index, (expected, actual) in enumerate(zip(recorded, live)):
if expected != actual:
return index
if len(recorded) != len(live):
return min(len(recorded), len(live))
return None
def replay_status(recorded: list[Event], live: list[Event]) -> str:
missing = [kind for kind, ok in completeness(recorded).items() if not ok]
if missing:
return f"incomplete:{','.join(missing)}"
mismatch = first_mismatch(recorded, live)
return "ok" if mismatch is None else f"mismatch@{mismatch}"
if __name__ == "__main__":
recorded = [
Event(0, "request", "a1"),
Event(1, "model", "b2"),
Event(2, "retrieval", "c3"),
Event(3, "tool", "d4"),
Event(4, "output", "e5"),
]
live_ok = list(recorded)
live_bad = list(recorded)
live_bad[2] = Event(2, "retrieval", "c9")
print("completeness:", completeness(recorded))
print("ok:", replay_status(recorded, live_ok))
print("bad:", replay_status(recorded, live_bad))
print("missing:", replay_status(recorded[:3], recorded[:3]))
运行:
cd private/labs/agp-lab
python3 -m agp_lab.record_replay
输出:
completeness: {'request': True, 'model': True, 'retrieval': True, 'tool': True, 'output': True}
ok: ok
bad: mismatch@2
missing: incomplete:tool,output
第一条记录包含五类事件,完整性全部为 True,回放状态是 ok。第二条把第 2 步的检索摘要从 c3 改成 c9,回放报告 mismatch@2,直接指出差异发生在检索步骤,而不是让团队从头猜。
第三条只记录了前三步,缺少 tool 和 output,状态是 incomplete:tool,output。完整性检查先于比对:记录本身不完整时,比对结果没有意义,系统应该明确报告“缺什么”,而不是给出一个看似通过的 ok。
这个实验用的是摘要比对,所以它能回答“是否相同”,不能回答“为什么不同”。真正的排障还需要结构化字段和全文;摘要的作用是快速定位到哪一步,再展开那一层的细节。
回放的三种模式
| 模式 | 做法 | 适用 |
|---|---|---|
| 全录制回放 | 模型、检索、工具全部用录制结果 | 精确复现、审计 |
| 部分回放 | 固定检索和工具,重跑模型 | 调试提示与模型 |
| 重算回放 | 只固定输入,全部重算 | 评测与回归 |
全录制回放最稳定,但只能复现“当时发生了什么”,不能回答“如果换个提示会怎样”。部分回放固定外部依赖,重跑模型,适合调试生成逻辑。重算回放最接近真实运行,但受非确定性影响,适合同口径评测而不是逐字节比对。
选择模式取决于问题。排查“模型为什么选了错误的工具”,应该固定检索和工具返回,只重跑模型;排查“检索是否返回了正确片段”,应该固定查询和索引,只重跑检索。
副作用:回放不能重复执行
回放工具调用时,绝对不能真的再执行一次。录制里“删除文件成功”,回放时再删一次可能失败,也可能删掉别的东西;录制里“发送邮件成功”,回放时再发一次就是事故。
处理方式有三种:
- Mock:回放时用录制返回替代真实调用,不产生副作用;
- Dry-run:调用真实接口的预演模式,只校验参数;
- 隔离环境:在沙箱里执行,副作用随环境销毁。
默认应该是 Mock。只有明确需要验证真实集成时,才在隔离环境里 dry-run;生产环境永远不应该对录制的写操作做真实重放。
隐私与合规
事件日志很容易变成隐私泄露源:
- 用户输入可能包含个人信息;
- 检索片段可能包含内部文档;
- 工具参数可能包含凭据;
- 模型输出可能包含敏感结论。
记录前应该做字段级脱敏:手机号、邮箱、身份证号、密钥用占位符替换;需要保留可关联性时,用带盐哈希而不是明文。访问日志本身也要有权限控制,不能“为了排障”让所有人可读。
回放与回归测试
录制的事件可以直接变成回归测试集:
- 用录制的 request + retrieval + tool 作为固定输入;
- 重跑模型,比对 output 的语义是否一致;
- 对关键案例,比对工具调用序列和参数;
- 把差异分类为“预期变化”和“回归”。
这样,线上失败可以沉淀为测试,而不是修完就忘。测试集应该覆盖正常路径、边界输入和已知失败案例;只录成功案例,回归测试会漏掉最重要的部分。
架构含义
记录与回放对架构有四个直接约束:
- 事件模型统一。 五类事件有统一 schema,能按 trace 关联。
- 分层保留。 摘要长期、结构化中期、全文短期并脱敏。
- 回放模式可选。 全录制、部分、重算,按问题选择。
- 副作用隔离。 回放默认 Mock,写操作永不真实重放。
第 1 条是基础。如果请求、检索、工具各自打日志,格式不同、ID 不通,事后无法拼出一次完整运行;统一事件模型让回放成为可能,而不是一次考古。
架构判据
| 判据 | 合格的样子 | 不合格的样子 |
|---|---|---|
| 事件完整 | 五类事件齐全 | 只有最终输出 |
| 可对齐 | trace/step ID 贯穿 | 日志各写各的 |
| 分层保留 | 摘要/结构化/全文 | 全存或全丢 |
| 回放安全 | 默认 Mock | 重放真实写操作 |
| 隐私可控 | 写入前脱敏 | 明文长期保存 |
这些判据里,“回放安全”是底线。一次误重放的删除或转账,造成的损失可能远大于它想排查的 bug;默认 Mock 应该是不可协商的设计。
一个失败排查的例子
用户报告 Agent 把订单取消了。回放记录显示:
- request:用户说“帮我看看订单状态”;
- retrieval:返回订单详情,其中包含“取消订单”按钮的文本;
- model:模型选择调用
cancel_order; - tool:调用成功;
- output:模型回复“已为您查询”。
问题出在第 2 步到第 3 步:检索把按钮文本带进了上下文,模型把“看到按钮”误解为“用户想取消”。有了事件记录,团队可以定位到“检索内容包含可执行文案”这个模式,进而在提示或检索过滤中修复,而不是笼统地加强“不要取消订单”。
这个例子也说明,记录的价值不只是复现,还包括发现系统性的上下文污染。
如何评测记录质量
| 指标 | 含义 |
|---|---|
| 完整率 | 五类事件齐全的请求比例 |
| 可回放率 | 能在固定环境下重跑的比例 |
| 差异定位率 | 回放能定位到具体步骤的比例 |
| 脱敏覆盖率 | 敏感字段被处理的比例 |
| 存储成本 | 每请求的事件体积 |
完整率和可回放率是基础;差异定位率决定排障效率;脱敏覆盖率是合规底线;存储成本决定能保留多久。几个指标要一起看,不能为了完整率无限存全文。
小结
- 记录与回放把一次运行拆成 request、model、retrieval、tool、output 五类事件。
- 摘要用于比对,结构化用于排障,全文用于深度复现;三层分层保留并脱敏。
- 回放有全录制、部分、重算三种模式,按问题选择。
- 工具副作用必须隔离,回放默认 Mock,写操作永不真实重放。
- 录制可以沉淀为回归测试,覆盖正常、边界和已知失败案例。
- 事件模型统一、trace 可对齐,回放才不是考古。
阅读导航:上一节:11.1 非确定性的来源:采样、并发与浮点 · 下一节:11.3 回放的边界:哪些能复现,哪些不能 。
常见错误与边界
- 只记录最终输出。 没有中间事件,无法定位问题出在检索、模型还是工具。
- 日志各写各的。 格式不统一、ID 不通,事后拼不出一次完整运行。
- 重放真实写操作。 删除、转账、发信绝不能在回放时真实执行。
- 明文长期保存。 用户输入和工具参数可能含敏感信息,写入前应脱敏。
- 只录成功案例。 回归测试缺少失败样本,最重要的路径没有被覆盖。
- 把摘要当全文。 哈希只能判断是否相同,不能解释为什么不同。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。