HW5 编程解析：三种离线 RL 算法的实现与调参

0. 这份作业在考什么

前四份作业里，智能体都可以自己去环境里试错。HW5 把这条路彻底封死：给你一个固定的数据集 $\mathcal{D} = \{(s, a, r, s')\}$，训练期间一次环境交互都不许做，只有评估的时候才把策略放进模拟器里跑 15 个 episode。这个约束一加上，前面所有算法立刻全部失效——原因只有一个：分布偏移（distributional shift）。

三种算法就是第 17、18 讲讲过的三条解法路线，这份作业让你把它们全部写一遍：

把这三条路线摆在一起，它们的差别可以压缩成一句话：

作业要动手验证的理论结论有四条，后面每一条都有对应的实验数字：

1. 期望回归（expectile regression）的 $\tau$ 真的在 SARSA 和 Bellman 最优之间插值。§5.2 的消融里 $\tau = 0.5$ 的成功率是严格的 0.0%，$\tau = 0.7$ 和 $0.9$ 都能学会——不对称权重不是调参技巧，是 IQL 的全部内容。
2. 行为约束系数 $\alpha$ 存在一个窄的最优区间。SAC+BC 在 $\alpha \in \{30, 100, 300, 1000\}$ 上的最好成功率是 46.7% → 100% → 100% → 93.3%（且末期崩到 26.7%）。
3. 动作 MSE 应该随 $\alpha$ 单调下降。这是作业 PDF 明确推荐的调参诊断量，实测 0.0499 → 0.0467 → 0.0413 → 0.0397，单调成立。
4. $q_{\min}$ 应该落在 $-\frac{1}{1-\gamma} = -100$ 与 0 之间，cube-single 上大约 $-50 \ldots -70$。实测落进这个带子里的两个 $\alpha$，恰好就是唯二打到 100% 的两个。

1. 代码结构、共享组件与张量形状链条

1.1 目录与职责

1.2 三份代码共享的组件

1.3 张量形状链条

这是最容易卡住的地方。以 cube-single（动作维 $|A| = 5$）、batch $B = 256$ 为例，从 replay buffer 采样开始一路走到损失：

2. SAC+BC：最直接的策略约束（3 处 TODO）

2.1 TODO 1 — update_q：两处刻意的「反 SAC」改动

要求。作业 PDF 的式 (1)(2)：

PDF 在这里写了两句很容易被略过的话：「We omit the entropy term in the Bellman backup (deviating from the original SAC algorithm)」和「We also use the average (instead of the minimum) of the two target Q values」。这两句都是刻意偏离在线 SAC 的，必须照做。

实现。

with torch.no_grad():
    next_actions = self.actor(next_observations).sample()      # (B, |A|)
    next_qs = self.target_critic(next_observations, next_actions)  # (2, B)
    next_q = next_qs.mean(dim=0)                               # (B,)  ← 平均，不是 min
    target_q = rewards + self.discount * (1.0 - dones) * next_q

q = self.critic(observations, actions)                          # (2, B)
loss = torch.mean((q - target_q.unsqueeze(0)) ** 2)

self.critic_optimizer.zero_grad()
loss.backward()
self.critic_optimizer.step()

逐块看：no_grad 包住整个目标计算，这样 $a'$、$\bar Q$、$y$ 都不带图；critic 损失里用 sample() 而不是 rsample()——因为这里根本不需要梯度穿过动作，用 rsample 也能跑但白建一次图。target_q.unsqueeze(0) 把 (B,) 变成 (1, B)，与 (2, B) 广播；torch.mean 同时对集成维和 batch 维取平均，相当于把 PDF 里的 $\sum_i$ 换成了 $\frac12\sum_i$——常数因子被 Adam 吸收，不影响任何结论。

2.2 TODO 2 — update_actor：三项相加，每一项都有坑

要求。PDF 式 (3)：

三项的分工：第一项最大化 $Q$（RL 的部分），第二项把策略拉回数据集动作（约束的部分），第三项是熵项（最大熵 RL 的部分，第 13 讲）。$\alpha$ 就是整个算法唯一真正重要的超参。

实现。

dist = self.actor(observations)
actor_actions = dist.rsample()                      # (B, |A|)，tanh 之后已在 (-1, 1)
log_probs = dist.log_prob(actor_actions)            # (B,)，已含 tanh 修正

qs = self.critic(observations, actor_actions)       # (2, B)
q_loss = -qs.mean(dim=0).mean()

mses = torch.mean((actor_actions - actions) ** 2, dim=-1)   # (B,)  ← mean，不是 sum
bc_loss = self.alpha * mses.mean()

entropy_loss = (self.beta().detach() * log_probs).mean()    # ← detach

loss = q_loss + bc_loss + entropy_loss

坑一：rsample() 而不是 sample()

$Q$ 项和 BC 项都需要梯度穿过动作本身：$\nabla_\theta Q(s, a^\pi_\theta)$ 只有在 $a^\pi$ 是 $\theta$ 的可微函数时才存在。sample() 返回的张量脱离了计算图，loss.backward() 不会报错——因为 log_probs 那一项仍然带图，梯度非零——但 actor 只会收到熵项的梯度。具体后果：策略会朝着「熵最大」的方向漂，$\sigma$ 一路涨，动作趋近均匀分布，成功率恒为 0，而 total_loss 依然在下降。注意反过来在 update_q 里就该用 sample()：那里整段在 no_grad 下。

坑二：动作维上 mean 还是 sum

PDF 写的是 $\frac{1}{|A|}\|a^\pi - a\|_2^2$，也就是 torch.mean(..., dim=-1)。如果写成 torch.sum，等价于把 $\alpha$ 乘上 $|A|$——cube-single 是 5，antsoccer 是 8。具体后果：你按 PDF 建议的 $\{30, 100, 300, 1000\}$ 网格去搜，实际搜到的是 $\{150, 500, 1500, 5000\}$，整个网格右移了一格，最好的那个 $\alpha$ 落在网格外面，你会得出「SAC+BC 在这个任务上不行」的错误结论。PDF 的 tip 里专门写了这个 factor-of-$|A|$ 警告。本文用 mean，所以 PDF 的建议网格可以直接用。

坑三：$\beta$ 必须 detach

self.beta() 是 LogParam.forward()，返回 log_param.exp()——一个带图的节点。如果不 detach，update_actor 里的 loss.backward() 会把梯度写进 beta.log_param.grad。在当前的更新顺序下（update_actor → update_beta，而 update_beta 开头会 zero_grad()）它恰好无害；但这是一个真正的定时炸弹：一旦有人调换更新顺序、或者加了梯度累积，$\beta$ 就会同时收到「对偶梯度」和「actor 梯度」两份，朝着「熵项系数越小越好」的方向跑，最终 $\beta \to 0$，最大熵 RL 退化成普通 RL。写一个 .detach() 的成本是 9 个字符。

2.3 tanh-高斯的 log-prob：不要自己手写

SAC 的动作要落在 $[-1, 1]$，做法是对高斯样本 $u$ 施加 $a = \tanh(u)$。变量替换后密度要乘上 Jacobian 的倒数：

很多人会在 actor 损失里手写这个修正项。不用写。make_tanh_transformed 构造的是 Independent(TransformedDistribution(Normal, TanhTransform), 1)，而 TransformedDistribution.log_prob 内部已经减掉了 log-Jacobian。手动再减一次，等于把修正项算了两遍，$\log\pi$ 系统性偏小，熵估计偏大，对偶梯度会把 $\beta$ 推向错误的平衡点。

怎么验证。test_tanh_gaussian_log_prob_correction 把分布返回的 log_prob 和闭式的 $\log\mathcal{N}(u) - \sum\log(1-\tanh^2 u)$ 对比到 1e-3，并额外断言修正量严格为正——因为 $|1 - \tanh^2 u| \lt 1$，取 log 是负数，减去负数就是加，squash 把密度压缩到有限区间必然抬高密度值。这条正负号断言能一眼抓住「符号写反」。

2.4 TODO 3 — update_target_critic：Polyak 更新

with torch.no_grad():
    for target_param, param in zip(
        self.target_critic.parameters(), self.critic.parameters()
    ):
        target_param.lerp_(param.detach(), self.target_update_rate)

lerp_(end, weight) 的语义正是 self += weight * (end - self)，展开就是 $(1-\rho)\bar\theta + \rho\theta$，一行搞定且是 in-place 的（不会新建张量，也不会把 target 参数换成一个非叶子节点）。方向写反（$\rho$ 乘在 target 上）会让目标网络几乎等于在线网络，自举失去稳定性，$Q$ 在几千步内发散；忘了 no_grad 会让 in-place 操作触发 autograd 报错或悄悄把 target 参数接进图里。

怎么验证。test_polyak_update_all_agents 把 $\rho$ 临时设成 0.25，断言 target == 0.75 * target_before + 0.25 * online，并且在线网络的参数一个字节都没变。第二条断言是关键：如果你不小心把 lerp_ 写在了 param 上（参数顺序反了），第一条可能还能过，第二条一定挂。

3. IQL 之一：把 max 藏进损失函数里（TODO 4）

3.1 TODO 4 — iql_expectile_loss：整份作业最值得想清楚的 10 行

要求。PDF 式 (6) 写作 $L(V) = \E_{(s,a)\sim\mathcal{D}}\big[\ell_2^\tau\big(V(s) - \min_i \bar Q_i(s,a)\big)\big]$，其中 $\ell_2^\tau(x) = |\tau - \mathbb{1}(x \gt 0)|\,x^2$，$\tau \in [0.5, 1)$。PDF 的原话是「the asymmetric expectile loss approximates the maximum operator over actions in the Bellman backup」——这句话是整个 IQL 的全部内容，但它没有解释为什么。

两个极端立刻可以读出来：

• $\tau = 0.5$。两侧权重相等，平衡条件退化成 $\E[Q - V] = 0$，即 $V = \E[Q]$，恰好是均值。同时损失本身变成 $0.5 \cdot (Q-V)^2$，就是半个 MSE。此时的备份是 $Q(s,a) \leftarrow r + \gamma\,\E_{a'\sim\beta}[Q(s',a')]$——这是行为策略的策略评估，也就是 SARSA。整个过程里没有任何东西被最大化。
• $\tau \to 1$。$Q \lt V$ 那一侧的残差权重 $1-\tau \to 0$，几乎免费；$Q \gt V$ 那一侧仍然被完整惩罚。于是 $V$ 会被一路顶高，直到几乎没有样本落在它上面为止，即 $V \to \max_{a \in \text{supp}(\beta)} Q(s,a)$。这是一个限制在数据支撑集内的 Bellman 最优备份。

把它跑一遍：一张表说明一切

光看推导容易半信半疑。取一组固定样本 $\{-5, -1, 0, 0.5, 2, 3, 3.5, 10\}$（均值 $1.6250$，最大值 $10$），用 Adam 直接对标量 $V$ 最小化 $\E[\ell_2^\tau(Q - V)]$，得到：

实现。

@staticmethod
def iql_expectile_loss(adv: torch.Tensor, expectile: float) -> torch.Tensor:
    weight = torch.where(
        adv > 0,
        torch.full_like(adv, expectile),
        torch.full_like(adv, 1.0 - expectile),
    )
    return weight * adv.pow(2)

参数 adv 就是 $u = Q - V$。torch.where 逐元素选权重；full_like 保证 dtype/device 一致（直接写 Python 浮点在 torch.compile 下也能跑，但会多一次隐式提升）。返回逐元素的损失而不是标量，让调用方决定怎么聚合——这样这个函数才能被单元测试直接喂一个手工张量。

怎么验证。四条断言层层递进，任何一条挂了都能定位到具体的错法：

4. IQL 之二：三个损失、AWR 与更新顺序（TODO 5–8）

4.1 TODO 5 — update_v：$V$ 必须拟合目标 critic

with torch.no_grad():
    target_q = self.target_critic(observations, actions).min(dim=0).values  # (2,B) -> (B,)

v = self.value(observations)                                    # (B,)
loss = self.iql_expectile_loss(target_q - v, self.expectile).mean()

三个细节：

• 用 target_critic 而不是 critic。PDF 的式 (6) 写的是 $\bar Q_i$。如果用在线 critic，$V$ 和 $Q$ 会在同一个梯度步内互相追逐：$V$ 拟合 $Q$、$Q$ 又自举 $V$，两条曲线一起漂移，$q_{\min}$ 会缓慢单调发散。目标网络的 200 步滞后正是用来打断这个环路的。
• 集成维取 min。这里的 $\min$ 是双 $Q$ 的常规悲观估计，和 IQL 的核心思想无关，不要和期望分位的 max 搞混。
• min(dim=0).values：torch.min(dim=) 返回 (values, indices) 具名元组，忘了 .values 会把一个元组塞进减法里，报错倒是立刻能看见。

4.2 TODO 6 — update_q：全篇最关键的一个「没有」

with torch.no_grad():
    next_v = self.value(next_observations)                       # (B,)
    target_q = rewards + self.discount * (1.0 - dones) * next_v  # (B,)

q = self.critic(observations, actions)                           # (2, B)
loss = torch.mean((q - target_q.unsqueeze(0)) ** 2)

怎么验证。这条性质可以被直接断言，而不是只靠读代码相信。test_iql_never_queries_the_critic_with_ood_actions 用一个 spy 包住 target_critic.forward，记录下 update_v 期间它见过的每一个动作张量，然后断言：（1）只被调用了一次；（2）那一次拿到的动作与 batch 里的 actions allclose。这个测试之所以有价值，是因为「不小心多查询了一次分布外动作」在训练日志里完全看不出来——损失照降、$Q$ 值照样在合理区间，只是成功率上不去。

另外两条测试锁住 done 掩码：test_iql_q_target_is_reward_at_terminal 把 $V(s')$ 强行设成 1000，然后断言终止样本上 $Q \to r$（精确到容差内）——掩码只要没生效，1000 这个量级立刻穿帮；test_iql_q_target_uses_discounted_v_when_not_terminal 断言非终止样本上 $Q \to r + \gamma V(s')$，抓的是「把掩码加反」。

4.3 TODO 7 — update_actor：AWR 策略抽取，以及 clamp 到底加在哪

要求。PDF 式 (7)(8)：

PDF 的措辞是「Clipping the exponentiated advantages is crucial in preventing excessively large weights from dominating the policy loss」，并给了 $M = 100$。

权重为什么会爆炸，以及该 clamp 哪一层

fp32 的最大值约 $3.4\times10^{38}$，而 $e^{88.7} \approx 3.4\times10^{38}$。也就是说 $\alpha A \gt 88$ 时 exp 直接溢出成 inf。训练早期 $Q$ 和 $V$ 都还没校准，$|A|$ 到几十是家常便饭，$\alpha = 10$ 时 $\alpha A$ 轻松破百。

现在是关键问题：clamp 应该套在指数上，还是套在指数函数的结果上？

实现。

AWR_MAX_WEIGHT = 100.0

@staticmethod
def awr_weight(adv, alpha, max_weight=AWR_MAX_WEIGHT):
    # clamp 指数，不是 clamp 指数函数的结果
    return torch.exp(torch.clamp(alpha * adv, max=math.log(max_weight)))

# update_actor
with torch.no_grad():
    q = self.critic(observations, actions).min(dim=0).values   # (B,)
    v = self.value(observations)                                # (B,)
    adv = q - v                                                 # (B,)
    weights = self.awr_weight(adv, self.alpha)                  # (B,)

dist = self.actor(observations)
log_probs = dist.log_prob(actions)          # (B,)，注意是数据集动作的 log-prob
loss = -(weights * log_probs).mean()

怎么验证。四条断言：test_awr_weights_nonnegative_monotone_and_clamped 检查权重非负、对 $A$ 严格递增、$A = 0$ 时恰为 1、等于 $\min(e^{\alpha A}, 100)$、并在大 $A$ 处饱和到 100；test_awr_alpha_zero_is_behavioral_cloning 检查 $\alpha = 0$ 时权重全为 1（此时 IQL 就是纯 BC，这是理论上的边界情形）；test_iql_actor_loss_is_finite_with_extreme_advantages 直接喂 $A = 10^4$，断言损失有限——这一条是专门用来抓「clamp 加错层」的，因为 clamp(exp(...)) 的写法在 $A = 10^4$ 时前向可能还侥幸活着，但只要下游有归一化就必挂；test_iql_actor_moves_toward_high_advantage_actions 是端到端的：造一批同状态、不同动作、优势有高有低的数据，跑若干步，断言策略均值确实朝高优势那一簇移动。

4.4 TODO 8 — Polyak，以及三个容易忽略的约定

Polyak 更新与 §2.4 完全一致，不再重复。剩下三件事：

1. 优势用在线 critic 还是目标 critic。PDF 的式 (8) 写的是 $\min_i Q_i$（在线网络），而 IQL 官方实现用的是目标网络。本文跟随 PDF 用 self.critic 并 detach。两者差别就是 200 步的 Polyak 滞后，在这个任务上测不出来。但注意 update_v 必须用目标网络（§4.1），两处不能混。
2. 更新顺序是 update_v → update_q → update_actor，最后 Polyak。update_q 消费的是本步刚更新过的 $V$。反过来先更新 $Q$ 再更新 $V$ 也能跑，但 $V$ 会永远落后 $Q$ 一步，收敛略慢。
3. IQL 的 actor 是固定 $\sigma = 1$ 的高斯，而且没有 tanh。iql_config 里 Policy(..., fixed_std=True)。于是 $\log\pi(a\mid s) = -\frac12\|a - \mu(s)\|^2 + \text{const}$，AWR 损失字面上就是一个加权 MSE 回归。这也意味着 $\mu(s)$ 没有任何东西把它约束在 $[-1,1]$ 内——get_action 在评估时做 torch.clamp(action, -1, 1) 兜底。

5. FQL：流策略 + 单步蒸馏（TODO 9–14）

5.1 为什么不能直接做 FBRAC

最自然的想法叫 FBRAC：把 SAC+BC 的 BC 项换成流匹配（flow matching）项，然后把流策略 $\pi_v(s,z)$（一次 10 步 Euler ODE 求解）直接塞进 $Q$ 里去最大化。问题在于，$\pi_v$ 是 10 次网络前向的复合，$\nabla_v Q(s, \pi_v(s,z))$ 要穿过全部 10 步——这就是时间反向传播（BPTT），需要连乘 (层数 × ODE 步数) 个 Jacobian，既贵又病态。

5.2 TODO 9–11 — 三个损失

阶段一：行为流匹配（rectified flow / 线性概率路径）。

目标速度为什么恰好是 $a - z$？因为路径是线性的：$\frac{\mathrm{d}\tilde a}{\mathrm{d}t} = \frac{\mathrm{d}}{\mathrm{d}t}\big[(1-t)z + ta\big] = a - z$，与 $t$ 无关。$t=0$ 给纯噪声，$t=1$ 给数据动作。

noise = torch.randn_like(actions)
t = torch.rand((actions.shape[0], 1), device=actions.device)   # (B, 1)，不是 (B,)
noisy_actions, target_velocity = self.flow_interpolation(noise, actions, t)
pred_velocity = self.bc_actor(observations, noisy_actions, t)
loss = torch.mean((pred_velocity - target_velocity) ** 2)

阶段二：critic，备份里用单步策略（不是流策略）：$y = r + \gamma(1-d)\cdot\frac12\sum_j \bar Q_j(s', \mathrm{clip}(\pi_\omega(s', z)))$，同样取平均而非 min。

阶段三：单步策略。

noise = torch.randn_like(actions)
onestep_actions = self.onestep_actor(observations, noise)   # 不 clip
with torch.no_grad():
    flow_actions = self.get_bc_action(observations, noise)  # 同一个 z！no_grad
distill_loss = self.alpha * torch.mean((onestep_actions - flow_actions) ** 2)

clipped_actions = torch.clamp(onestep_actions, -1, 1)       # 喂 critic 的要 clip
q_loss = -self.critic(observations, clipped_actions).mean(dim=0).mean()
loss = distill_loss + q_loss

两个策略必须共享同一个 $z$。这才让蒸馏变成逐样本的映射匹配而不是分布匹配——单步网络因此能继承流策略的多模态性（同一个 $s$、不同的 $z$ 落到不同的模态上）。若各自采一个 $z$，蒸馏项就退化成「让 $\pi_\omega$ 输出流策略的均值」，多模态被抹平，FQL 相对 SAC+BC 的全部优势消失。

5.3 那条「clip 加三处、不加第四处」的规则

5.4 TODO 12–13 — Euler 积分与评估动作

action = noise
dt = 1.0 / self.flow_steps
for i in range(self.flow_steps):                 # i = 0 .. F-1
    t = torch.full((*action.shape[:-1], 1), i * dt, ...)
    action = action + dt * self.bc_actor(observations, action, t)
return torch.clamp(action, -1, 1)

时间网格必须是 $t_i = i/F$，$i = 0,\dots,F-1$（含 0、不含 1）。从 $t = 1/F$ 开始、或者跑 $F+1$ 步，都会悄悄给策略引入偏置——不报错、不发散，只是分布偏了。test_fql_euler_uses_times_from_0_to_1_exclusive 用一个记录型 vector field 抓下每次调用的 $t$，断言 $F=5$ 时序列恰好是 [0, 0.2, 0.4, 0.6, 0.8]；test_fql_euler_integration_is_exact_for_a_constant_field 令 $v \equiv c$（此时精确解是 $z + c$ 且 Euler 无误差），断言等式成立到 1e-6。

评估要采样，不要取 mode。SAC+BC 和 IQL 评估时取分布的众数；FQL 的 get_action 每次重新采一个 $z \sim \mathcal{N}(0,I)$。因为这个策略的全部表达力都住在 $z$ 里，取「众数」（$z = 0$）会把多模态直接压成一个点。另外：make_onestep_actor 建的也是 VectorFieldPolicy，调用 onestep_actor(obs, z) 时 times=None，模块内部会填 0——所以它实质上就是一个在 $[s, z, 0]$ 上的 MLP。

no_grad 包住 ODE 展开是 FQL 的立身之本：梯度一旦通过蒸馏目标流回 $v$，BPTT 就回来了，算法就白设计了。

怎么验证这一整套。流匹配部分有一串层层收紧的断言：test_flow_interpolation_shapes_and_endpoints 同时检查形状、$t=1$ 时插值就是数据动作、$t=0$ 时就是噪声、目标速度与 $t$ 无关，并用有限差分数值验证 $\mathrm{d}\tilde a/\mathrm{d}t$ 确实等于回归目标——这一条能抓住「把 $(1-t)$ 和 $t$ 写反」这种最常见的错误（写反之后端点会互换，但损失照样收敛，只是采样出来的动作分布是噪声而不是动作）。test_fql_bc_flow_learns_a_deterministic_action 是端到端的：造一份动作恒为常数的数据集，训完之后从任意噪声出发积分 ODE，都必须还原出那个常数。test_fql_distillation_pulls_onestep_toward_flow 断言蒸馏项确实在缩小单步策略与流策略之间的差距；test_fql_q_term_pushes_actions_up 令 $\alpha = 0$，此时损失只剩纯 $Q$ 最大化，动作应当一路饱和到 $+1$——这条反过来确认了「$\alpha$ 就是那个把策略拴在数据上的唯一绳子」。

6. 实验与结果

统一设置：cube-single-play-singletask-task1-v0，seed 0，batch 256，4×256 tanh MLP，Adam $3\times10^{-4}$，$\gamma=0.99$，$\rho=0.005$，每个评估点跑 15 个 episode；RTX 5080 上 5–6 个 run 并行，各约 65–90 it/s。

6.1 全部结果

7. 最有教学价值的一张图：expectile 消融

7.1 SAC+BC 对 $\alpha$ 极度敏感

为什么 $q_{\min}$ 是第二个好用的诊断量。奖励只取 $\{-1, 0\}$，所以 $Q$ 理论上被夹在 $[-\frac{1}{1-\gamma}, 0] = [-100, 0]$ 之间；PDF 说 cube-single 这种短时域任务上 $q_{\min}$ 应该收敛到 $-50 \ldots -70$。实测：$\alpha=30 \to -38.9$（太浅：策略太自由，价值没有充分传播）；$\alpha=100 \to -51.8$ ✓；$\alpha=300 \to -65.2$ ✓；$\alpha=1000 \to -89.0$（越过了带子，逼近 −100，说明过度约束、几乎退化成纯 BC）。落在带内的两个 $\alpha$，恰好就是唯二打到 100% 的两个。这不是事后凑数——它意味着你可以在只跑几万步、还看不出成功率差异的时候，就用 $q_{\min}$ 提前判断 $\alpha$ 选对没有。

7.2 IQL 对 $\alpha$ 不敏感，而且原因很干净

7.3 FQL

不要从 60K 的 run 对 FQL 下任何最终结论。60K 是预算的 6%，而 FQL 是三者中起步最慢的（20K 时 7%，此时 SAC+BC 已 87%）。这个慢是可以预期的：单步策略的上限是它蒸馏的那个 BC 流策略，而流策略需要时间先把行为分布拟合出来。$\alpha=100$ 在 30/40/50/60K 处是 33% → 40% → 53% → 80%，趋势指向 80% 的目标，但趋势不是证据。

8. 踩坑记录

• 单元测试里的 @torch.compile。所有 update_* 方法都带这个装饰器。在 CPU 上为一个 2 层 32 单元的测试网络做编译，开销远大于测试本身。在 tests/test_hw5.py 顶部加 torch._dynamo.config.disable = True 让它们走 eager，26 个测试约 90 秒跑完。调试真实训练时也可以临时关掉（PDF 里也这么建议）。
• 瓶颈是 GPU 而不是 CPU，尽管网络很小。6 个 run 并行就把单卡打到 92% 利用率，再加进程不会更快，每个 run 约 85 it/s。所以「4 个 run 并行」这个建议是有道理的。
• 数据集大但下载快：三个 ogbench 任务共 859 MB，一分钟内下完。开跑前务必确认 rewards ∈ {−1, 0}、masks ∈ {0, 1}，因为 dones = 1 - masks 极易搞反，而它的失败模式是静默的。

9. 自测清单

9.1 写完代码、还没开跑之前

• ☐ uv run python tests/test_hw5.py 26/26 全过。任何一条挂了都不要开 GPU。
• ☐ 三个 agent 的 update_target_critic 都用了 lerp_(param, rho) 且包在 no_grad 里；测试断言在线网络参数未变。
• ☐ SAC+BC 的 actor 用 rsample()，critic 的 next action 用 sample() 且在 no_grad 下。
• ☐ BC 项在动作维上取 mean 而非 sum（否则 PDF 的 $\alpha$ 网格整体错位 $|A|$ 倍）。
• ☐ SAC+BC 熵项里的 self.beta() 有 .detach()。
• ☐ 没有手写 tanh 的 log-det 修正（TransformedDistribution 已经做了）。
• ☐ SAC+BC / FQL 的备份都用 average 而不是 min 的目标 $Q$。
• ☐ IQL 的 update_v 用 target critic，update_actor 的优势用 online critic（PDF 式 8）。
• ☐ IQL 的 update_q 里没有任何一行在调用 actor。
• ☐ AWR 的 clamp 加在指数上：exp(clamp(alpha*adv, max=log(100)))。
• ☐ AWR 的 log_prob 传的是数据集动作，不是采样动作。
• ☐ FQL 的 Euler 时间网格是 $0, 1/F, \dots, (F-1)/F$，共 $F$ 步。
• ☐ FQL 的两个策略在 update_onestep_actor 里共享同一个 $z$。
• ☐ FQL 的 clip 加在三处（流策略输出、喂 critic 的单步输出、评估输出），蒸馏项里没有。
• ☐ FQL 的 ODE 展开包在 no_grad 里。
• ☐ FQL 的 get_action 每次重新采 $z$（不是固定 $z=0$）。

9.2 跑起来之后的前 20K 步

• ☐ q_max 应趋近 0，q_min 应落在 $[-100, 0]$ 内。跑到 $-1$ 附近说明 done 掩码反了；跑出 $-100$ 以下说明掩码漏了或备份发散。
• ☐ cube-single 上 q_min 的合理落点是 $-50 \ldots -70$。偏浅（$>-40$）说明 $\alpha$ 太小，偏深（$<-85$）说明 $\alpha$ 太大。
• ☐ 扫 $\alpha$ 时，action MSE 必须随 $\alpha$ 单调下降。不单调 = BC 项没接对。
• ☐ IQL 的 actor/weight_mean 在 $10^{-3} \sim 10^{-1}$ 是正常的（$\tau=0.9$ 下大多数动作优势为负），不要当成 bug 去改。weight_max 长期贴 100 才要警惕。
• ☐ 所有指标都是有限值。出现 nan 第一个怀疑 AWR 的 clamp 层级。
• ☐ 先在 antmaze-medium 上调试：正确实现 + 好的 $\alpha$，SAC+BC 应在 100K 步内超过 80%，IQL 在 200K 步内超过 60%，FQL 在 200K 步内超过 80%。这比在 cube-single 上盲调快得多。

9.3 写报告时

• ☐ 至少 3 个 $\alpha$ 的曲线（cube-single），SAC+BC / IQL / FQL 各一组。
• ☐ IQL 那一问要用 1–2 句话回答「最好性能」和「对 $\alpha$ 的敏感性」两件事——参考 §7.2 的解耦解释。
• ☐ 如果你的 run 没跑满 1M 步，就写清楚跑到了多少步。本文的做法是在每张图的标题里标出实际步数，并单独用一个警告框列出未达标与未运行的项。截断的结果仍然有价值，但把它说成 1M 的结果就没有价值了。