以下数字与运行结果均为教学示例,不构成对任何真实系统或供应商的承诺。三条 rollout 的奖励、步长与字段配置只用于展示计算方式。
上一节把 Agent 写成 POMDP:状态、观测、动作、转移、奖励与信念。形式模型回答“应该怎么决策”,这一节回答一个更工程的问题:一次运行结束后,系统到底留下了什么?
很多人把这个问题等同于“有没有日志”。日志通常记录的是系统事件:请求进来了、工具调用了、返回 200 了。轨迹要记录的是决策序列:在第几步、看到了什么、基于什么选择了哪个动作、得到什么奖励、为什么停下来。两者有交集,但不是一回事。只有日志,你无法回答“为什么这次选了重启而不是扩容”;只有轨迹,你才能做策略评估、失败归因和重放。
轨迹的最小结构
一条轨迹可以写成有序的转移序列:
$$
\tau = (o_0, a_0, r_1, o_1, a_1, r_2, \ldots, o_T, a_T, r_{T+1})
$$
其中 $o_t$ 是第 $t$ 步的观测,$a_t$ 是动作,$r_{t+1}$ 是动作之后的奖励,$T$ 是终止步。这个序列看起来简单,但每一项都有容易忽略的语义:
| 元素 | 含义 | 常见误记 |
|---|---|---|
| 观测 | Agent 实际收到的内容 | 记成环境真实状态 |
| 动作 | 经过解析与校验后的动作 | 记成模型原始输出 |
| 奖励 | 该步的可计算反馈 | 只在最后记一个总分 |
| 终止 | 停止原因与停止层 | 只记“结束” |
第一行最容易被忽略。工具返回“订单不存在”,可能是真的不存在,也可能是权限过滤、超时重试或缓存未命中。轨迹记录的是 Agent 看到的观测,不是数据库里的真相。把两者混为一谈,事后复盘会得出错误结论。
第二行同样重要。模型可能输出了 restart_service,但运行时因为审批缺失把它改写成了 ask_for_approval。轨迹应该记录真正执行的动作,同时保留原始建议。只记其中一个,都无法解释“模型想做什么”和“系统实际做了什么”之间的差异。
Rollout 记录字段
一个可用的 rollout 记录至少包含四组字段:
| 组 | 字段 | 回答的问题 | 缺失后果 |
|---|---|---|---|
| 身份 | run_id、trace_id | 这是哪次运行 | 无法关联日志与工单 |
| 版本 | policy_version、prompt_version、model_id | 当时用的是什么策略 | 无法判断改动是否生效 |
| 随机性 | seed、temperature、sampling_params | 为什么两次运行不同 | 只能做统计比较,不能精确重放 |
| 语义 | 每步的观测、动作、奖励、done、stop_reason | 决策链是什么 | 只能审计结果,不能复现过程 |
这四组字段对应四种用途:身份用于对账,版本用于回归,随机性用于复现,语义用于归因。很多团队只记身份和结果,然后在事故复盘时发现最关键的那一步没有记录。
还有一个字段不在表里,但必须显式声明:外部副作用。转账、发邮件、删除文件、重启服务,这些动作一旦发生就无法撤销。带副作用的轨迹,无论字段多完整,都只能做到审计,不能做到“重跑一次看看会不会一样”。
折扣回报
给定一条轨迹,最常用的标量是折扣回报:
$$
G = \sum_{t=0}^{T} \gamma^t r_{t+1}, \quad 0 \le \gamma \le 1
$$
$\gamma$ 越接近 1,越看重长期收益;越接近 0,越看重眼前反馈。折扣不是为了数学好看,它表达两个工程事实:
- 时间有价值。 同样的成功,早一步完成比晚十步完成更好,因为延迟本身有成本。
- 远期的估计更不可信。 步数越多,环境变化、上下文丢失和误差累积越严重,远期奖励的权重应该更低。
折扣回报也有边界。它把多维奖励压成一个标量,适合比较策略,不适合解释失败。一个任务可能总分不低,但中间有一次高风险动作;折扣回报会把这次动作平均掉。所以轨迹里既要保留总回报,也要保留逐步奖励和风险事件。
最小实验:三条 rollout
实验用三条固定轨迹,分别代表三类典型记录:
run-w1-001:检索问答,字段完整,无副作用;run-w2-001:代码修复,缺少seed;run-w3-001:运维处置,缺少policy_version,其中一步观测未记录,且有外部副作用。
每条轨迹计算未折扣总奖励、$\gamma=0.9$ 的折扣回报、可重放等级和缺失字段。代码同时演示了“记录完整”和“记录可用”不是同一件事。
# file: agp_lab/policy_rollout.py | write
# tier: 3
# verify: python3 -m unittest tests.test_policy_rollout
"""Rollout 与轨迹:一次运行留下什么,以及它能被重放到哪一步。
一条轨迹是 (observation, action, reward) 的有序序列。记录不只是日志:
字段缺失会改变这条轨迹能回答的问题。本模块用三个确定性 rollout 演示
折扣回报的计算,以及 policy_version、seed、stop_reason 等字段缺失时
可重放性如何降级。
"""
from __future__ import annotations
from dataclasses import dataclass
DEFAULT_GAMMA = 0.9
@dataclass(frozen=True)
class Step:
observation: str | None
action: str | None
reward: float
done: bool = False
@dataclass(frozen=True)
class Rollout:
run_id: str
policy_version: str | None
seed: int | None
steps: tuple[Step, ...]
stop_reason: str | None
external_side_effect: bool = False
def discounted_return(steps: tuple[Step, ...], gamma: float = DEFAULT_GAMMA) -> float:
"""按 gamma 折扣累加每一步奖励。"""
if not 0.0 <= gamma <= 1.0:
raise ValueError("gamma 必须在 [0, 1] 内")
return sum((gamma ** index) * step.reward for index, step in enumerate(steps))
def undiscounted_return(steps: tuple[Step, ...]) -> float:
"""不做折扣的总奖励,用于看清折扣带来的差异。"""
return sum(step.reward for step in steps)
def missing_fields(rollout: Rollout) -> tuple[str, ...]:
"""列出重跑这条轨迹所需的缺失字段。"""
gaps: list[str] = []
if rollout.policy_version is None:
gaps.append("policy_version")
if rollout.seed is None:
gaps.append("seed")
if rollout.stop_reason is None:
gaps.append("stop_reason")
for index, step in enumerate(rollout.steps):
if step.observation is None:
gaps.append(f"step[{index}].observation")
if step.action is None:
gaps.append(f"step[{index}].action")
return tuple(gaps)
def replay_level(rollout: Rollout) -> str:
"""把一条记录分成 exact / statistical / audit-only 三档。"""
if rollout.external_side_effect:
return "audit-only"
if rollout.policy_version is None or rollout.seed is None:
return "audit-only"
for step in rollout.steps:
if step.observation is None or step.action is None:
return "audit-only"
if rollout.stop_reason is None:
return "statistical"
return "exact"
def goal_reached(steps: tuple[Step, ...]) -> bool:
"""轨迹是否以 done 标记结束;没有 done 的轨迹只能靠 stop_reason 解释。"""
return bool(steps) and steps[-1].done
@dataclass(frozen=True)
class Row:
run_id: str
step_count: int
total_reward: float
discounted: float
replay: str
gaps: tuple[str, ...]
def analysis_table(rollouts: tuple[Rollout, ...], gamma: float = DEFAULT_GAMMA) -> list[Row]:
"""为每条 rollout 计算回报与可重放性。"""
rows: list[Row] = []
for rollout in rollouts:
rows.append(
Row(
run_id=rollout.run_id,
step_count=len(rollout.steps),
total_reward=undiscounted_return(rollout.steps),
discounted=discounted_return(rollout.steps, gamma),
replay=replay_level(rollout),
gaps=missing_fields(rollout),
)
)
return rows
ROLLOUTS = (
Rollout(
run_id="run-w1-001",
policy_version="policy-7",
seed=11,
steps=(
Step("query:refund-policy", "search", 0.0),
Step("doc-42", "read", 0.2),
Step("answer-with-citation", "answer", 1.0, True),
),
stop_reason="answered",
),
Rollout(
run_id="run-w2-001",
policy_version="policy-7",
seed=None,
steps=(
Step("test-failed", "edit", -0.2),
Step("test-failed", "edit", -0.2),
Step("tests-passed", "finish", 1.0, True),
),
stop_reason="tests_passed",
),
Rollout(
run_id="run-w3-001",
policy_version=None,
seed=3,
steps=(
Step("alert:5xx", "restart", 0.0),
Step(None, "health_check", 1.0, True),
),
stop_reason="restarted",
external_side_effect=True,
),
)
if __name__ == "__main__":
print(f"{'run':<12}{'steps':>6}{'reward':>8}{'discount':>10} {'replay':<12}gaps")
for row in analysis_table(ROLLOUTS):
gaps = ",".join(row.gaps) if row.gaps else "-"
print(
f"{row.run_id:<12}{row.step_count:>6}{row.total_reward:>8.2f}"
f"{row.discounted:>10.3f} {row.replay:<12}{gaps}"
)
运行:
cd private/labs/agp-lab
python3 -m agp_lab.policy_rollout
输出:
run steps reward discount replay gaps
run-w1-001 3 1.20 0.990 exact -
run-w2-001 3 0.60 0.430 audit-only seed
run-w3-001 2 1.00 0.900 audit-only policy_version,step[1].observation
第一行是理想情况:三步、总奖励 1.20、折扣回报 0.990,字段齐全,判为精确重放。第三行值得注意:它的总奖励和折扣回报都不低,但可重放等级仍然是 audit-only。原因是 policy_version 缺失、第二步观测缺失,而且这次运行有外部副作用。回报高不代表记录可用,这是两个独立维度。
第二行的折扣回报从 0.60 降到 0.430,差距来自奖励出现得晚:前两步是负奖励,最后一步才完成。折扣会放大“晚成功”的代价,这也是长任务更怕拖延的原因。
run-w3-001 的缺失字段里没有列出“外部副作用”,因为副作用不是缺失字段,而是记录属性。即使把 policy_version 和观测补齐,只要副作用存在,它仍然只能审计。这一点在架构上必须单独建模,不能靠“字段补全”解决。
可重放性分级
把可重放性分成三档,比笼统承诺“可回放”更有用:
| 档位 | 条件 | 能回答的问题 | 典型任务 |
|---|---|---|---|
| 精确 | 版本、种子、每步观测与动作、停止原因齐全,无副作用 | 当时为什么选这个动作 | 离线评测、只读问答 |
| 统计 | 版本与种子齐全,但停止原因或部分观测缺失 | 改动是否让整体变差 | 有波动的生成任务 |
| 审计 | 缺版本或种子、观测缺失,或有外部副作用 | 当时发生了什么、谁批准了什么 | 写操作、不可逆处置 |
分档的意义在于:它决定测试怎么写。精确档可以做逐字节比对;统计档只能做区间评估;审计档只能做规则检查和人工复核。对审计档要求逐字节一致,测试会长期不稳定;对精确档只做人工抽查,又浪费了可复现性。
边界与失败模式
轨迹记录最常见的失败不是“没记”,而是“记了但不能用”:
- 只记工具名,不记参数。 知道调用了
restart,不知道重启的是哪个实例,等于没记。 - 只记模型输出,不记执行动作。 校验和改写被抹掉,无法解释最终副作用。
- 观测被截断但没有标记。 后 90% 的内容被截掉,事后看像是“工具只返回了这些”。
- 奖励延迟且没有中间信号。 只有最后一步有奖励,无法判断哪一步贡献最大。
- 停止原因缺失。 不知道是任务完成、步数耗尽还是用户取消,回归时无法区分。
- 副作用没有单独标记。 记录看起来完整,实际上根本不能重跑。
这些失败模式有一个共同点:它们在运行当天都不影响功能,只在复盘、评测和回归时暴露。也正因为如此,轨迹 schema 应该在系统设计阶段就定下来,而不是等事故之后补。
架构含义
轨迹对架构有四个直接约束:
- 轨迹是一等对象。 它不是日志系统的副产品,而是有独立 schema、独立保留策略和独立访问控制的记录。
- 追加写、不可变。 轨迹记录的是已经发生的事实,不能事后修改;需要更正时追加一条修订记录。
- 版本化 schema。 字段会随策略演进,读取方必须能处理旧版本;否则半年前的轨迹在新工具里打不开。
- 按用途分级保留。 精确档保留完整字段,审计档可以脱敏、抽样、缩短保留期,但关键动作与审批链不能丢。
这四条里,“按用途分级”最容易被预算压力推翻。团队常在存储成本上升时统一删字段,结果把审计档删成了不可用,把精确档删成了统计档。正确做法是先声明每条轨迹的用途,再决定保留什么。
架构判据
| 判据 | 合格的样子 | 不合格的样子 |
|---|---|---|
| 身份可关联 | run_id 能关联日志、工单与审批 | 只有时间戳 |
| 版本可追溯 | 记录策略、提示与模型版本 | 只记“用了最新模型” |
| 随机性可复现 | 种子与采样参数齐全 | 只说“温度没调” |
| 每步可归因 | 观测、动作、奖励、done 齐全 | 只有最终结果 |
| 副作用显式 | 单独标记不可逆动作 | 把写操作混在普通步骤里 |
| 用途分级 | 精确、统计、审计三档 | 全部承诺可回放 |
这六条可以直接变成轨迹 schema 的验收清单。它们不依赖具体框架,也不要求向量数据库或可观测性平台;一个追加写的 JSONL 文件加一套字段约定,就能满足大部分中小系统。
小结
- 轨迹是决策序列,不是系统日志;它记录观测、动作、奖励与停止原因。
- 观测是 Agent 看到的内容,不等于环境真实状态;动作是执行后的动作,不等于模型原始输出。
- 折扣回报把多维反馈压成标量,适合比较策略,不适合单独解释失败。
- 可重放性分精确、统计、审计三档;字段缺失和外部副作用都会让等级下降。
- 高回报不等于记录可用;奖励与可重放性是独立维度。
- 轨迹 schema 应该在设计阶段确定,并按用途分级保留。
阅读导航:上一节:1.1 Agent 的形式模型:POMDP、策略与信念 · 下一节:1.3 LLM 作为策略:提示是历史的有损压缩 。
常见错误与边界
- 把日志当轨迹。 日志记录系统事件,轨迹记录决策序列;两者字段和用途不同。
- 把观测当真相。 工具返回的空结果可能是权限过滤或超时,不是环境状态。
- 只记模型输出。 不记运行时校验与改写,就无法解释实际执行的动作。
- 用总奖励代替逐步奖励。 总分无法定位是哪一步导致了失败或风险。
- 忽略副作用标记。 有外部副作用的轨迹只能审计,补字段也不能变成可重放。
- 承诺所有轨迹可精确重放。 随机性、外部依赖和版本变化会让这个承诺失效;应按用途分级。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。