WZH 的博客

强化学习基础公式全解析：从 Policy 到 Q-Learning

wzh — Sat, 22 Aug 2026 00:00:00 +0000

强化学习（Reinforcement Learning, RL）的核心是 agent 在环境（Environment）中通过试错（trial and error）学习最优策略。本文系统梳理 RL 最基础、最核心的公式，从 Policy、Return 出发，经过 V/Q 函数、Bellman 方程，最终到 TD 学习和 Q-Learning，形成一条完整的公式链。

1. 基础表示

Policy

策略定义了 agent 在给定状态下如何选择动作。

确定性策略：状态到动作的映射

$$ A_t = \pi(S_t), \qquad \pi: \mathcal S \to \mathcal A $$

随机策略：给定状态下的动作概率分布

$$ A_t \sim \pi(\cdot \mid S_t), \qquad \pi(a \mid s) = P(A_t = a \mid S_t = s) $$

其中 $\sum_{a \in \mathcal A} \pi(a \mid s) = 1$。随机策略是 RL 的一般形式，确定性策略可视为其退化情形。

Discounted Return

Return $G_t$ 是从时间 $t$ 开始累积的折扣奖励总和：

$$ G_t = R_{t+1} + \gamma R_{t+2} + \gamma^2 R_{t+3} + \cdots = \sum_{k=0}^{\infty} \gamma^k R_{t+k+1} $$

递归形式是最常用的表达：

$$ G_t = R_{t+1} + \gamma G_{t+1} $$

其中 $\gamma \in [0, 1]$ 是 discount factor。

RL Target

RL 的目标是找到一个策略，使期望折扣回报最大化：

$$ \pi^* = \arg\max_{\pi} \mathbb E_{\pi} \left[ \sum_{t=0}^{\infty} \gamma^t R_{t+1} \right] $$

2. $V^\pi$

状态价值函数 $V^\pi(s)$ 表示从状态 $s$ 出发，按照策略 $\pi$ 行动所能获得的期望 return。

期望形式：

$$ V^\pi(s) = \mathbb E_\pi \left[ G_t \mid S_t = s \right] $$

展开 return：

$$ V^\pi(s) = \mathbb E_\pi \left[ R_{t+1} + \gamma R_{t+2} + \gamma^2 R_{t+3} + \cdots \mid S_t = s \right] $$

按概率分布展开（离散情况）：

$$ V^\pi(s) = \sum_g g \cdot P_\pi(G_t = g \mid S_t = s) $$

Monte Carlo 估计：从状态 $s$ 采样 $N$ 条 rollout，取 return 的平均值：

$$ \hat V^\pi(s) = \frac{1}{N} \sum_{i=1}^N G_t^{(i)} \approx V^\pi(s) $$

$G_t$ 是一条具体 trajectory 的 return，而 $V^\pi(s)$ 是所有可能 returns 的期望。

3. $Q^\pi$

动作价值函数 $Q^\pi(s, a)$ 表示从状态 $s$ 开始，先执行动作 $a$，之后按策略 $\pi$ 行动所能获得的期望 return。

期望形式：

$$ Q^\pi(s, a) = \mathbb E_\pi \left[ G_t \mid S_t = s, A_t = a \right] $$

展开 return：

$$ Q^\pi(s, a) = \mathbb E_\pi \left[ R_{t+1} + \gamma R_{t+2} + \gamma^2 R_{t+3} + \cdots \mid S_t = s, A_t = a \right] $$

按概率分布展开：

$$ Q^\pi(s, a) = \sum_g g \cdot P_\pi(G_t = g \mid S_t = s, A_t = a) $$

Sampling：

$$ \hat Q^\pi(s, a) = \frac{1}{N} \sum_{i=1}^N G_t^{(i)} $$

其中 rollout 起点为 $(S_t = s, A_t = a)$，之后按 $\pi$ 行动。$Q^\pi$ 与 $V^\pi$ 的区别在于额外固定了第一步的 action。

4. $V^\pi$ 与 $Q^\pi$ 的关系

从 $Q^\pi$ 得到 $V^\pi$

$V^\pi(s)$ 是当前策略下所有动作价值的概率加权平均：

$$ V^\pi(s) = \mathbb E_{A \sim \pi(\cdot \mid s)} \left[ Q^\pi(s, A) \right] $$

离散动作展开：

$$ V^\pi(s) = \sum_{a \in \mathcal A} \pi(a \mid s) Q^\pi(s, a) $$

从 $V^\pi$ 得到 $Q^\pi$

固定当前 action，再对下一状态求期望：

$$ Q^\pi(s, a) = \mathbb E \left[ R_{t+1} + \gamma V^\pi(S_{t+1}) \mid S_t = s, A_t = a \right] $$

记期望即时奖励为 $R(s, a)$：

$$ Q^\pi(s, a) = R(s, a) + \gamma \mathbb E \left[ V^\pi(S_{t+1}) \mid s, a \right] $$

对下一状态展开：

$$ Q^\pi(s, a) = R(s, a) + \gamma \sum_{s' \in \mathcal S} P(s' \mid s, a) V^\pi(s') $$

若 reward 依赖于 $(s, a, s')$：

$$ Q^\pi(s, a) = \sum_{s'} P(s' \mid s, a) \left[ R(s, a, s') + \gamma V^\pi(s') \right] $$

$Q^\pi$ 直接递归到 $Q^\pi$

将 $V^\pi(s') = \sum_{a'} \pi(a' \mid s') Q^\pi(s', a')$ 代入：

$$ Q^\pi(s, a) = R(s, a) + \gamma \sum_{s'} P(s' \mid s, a) \sum_{a'} \pi(a' \mid s') Q^\pi(s', a') $$

或紧凑形式：

$$ Q^\pi(s, a) = \mathbb E_\pi \left[ R_{t+1} + \gamma Q^\pi(S_{t+1}, A_{t+1}) \mid S_t = s, A_t = a \right] $$

5. Bellman Expectation Equation

Bellman 方程的核心思想来自 $G_t = R_{t+1} + \gamma G_{t+1}$，将长期 return 改写为"一步奖励加下一状态价值"的递归形式。

$V^\pi$ 的 Bellman Expectation Equation

最紧凑的期望形式：

$$ V^\pi(s) = \mathbb E_\pi \left[ R_{t+1} + \gamma V^\pi(S_{t+1}) \mid S_t = s \right] $$

先展开 action：

$$ V^\pi(s) = \sum_a \pi(a \mid s) \left[ R(s, a) + \gamma \mathbb E_{S' \sim P(\cdot \mid s, a)} V^\pi(S') \right] $$

完全展开：

$$ V^\pi(s) = \sum_{a \in \mathcal A} \pi(a \mid s) \left[ R(s, a) + \gamma \sum_{s' \in \mathcal S} P(s' \mid s, a) V^\pi(s') \right] $$

使用 $R(s, a, s')$ 时：

$$ V^\pi(s) = \sum_a \pi(a \mid s) \sum_{s'} P(s' \mid s, a) \left[ R(s, a, s') + \gamma V^\pi(s') \right] $$

也可以写成 $V$-$Q$ 两层形式：

$$ V^\pi(s) = \sum_a \pi(a \mid s) Q^\pi(s, a), \qquad Q^\pi(s, a) = R(s, a) + \gamma \sum_{s'} P(s' \mid s, a) V^\pi(s') $$

$Q^\pi$ 的 Bellman Expectation Equation

期望形式：

$$ Q^\pi(s, a) = \mathbb E_\pi \left[ R_{t+1} + \gamma Q^\pi(S_{t+1}, A_{t+1}) \mid S_t = s, A_t = a \right] $$

完全展开：

$$ Q^\pi(s, a) = R(s, a) + \gamma \sum_{s'} P(s' \mid s, a) \sum_{a'} \pi(a' \mid s') Q^\pi(s', a') $$

6. Bellman Optimality Equation

Optimal Value Functions

最优状态价值

$$ V^*(s) = \max_\pi V^\pi(s) $$

与 optimal Q 的关系：

$$ V^*(s) = \max_{a \in \mathcal A} Q^*(s, a) $$

最优动作价值

$$ Q^*(s, a) = \max_\pi Q^\pi(s, a) $$

含义是：当前第一步 $a$ 已固定，从下一步开始采用最优策略。

与 Bellman Expectation Equation 结构对应，但将固定策略下的加权平均替换为 $\max$ 操作。

$V^*$ 形式

期望形式：

$$ V^*(s) = \max_a \mathbb E \left[ R_{t+1} + \gamma V^*(S_{t+1}) \mid S_t = s, A_t = a \right] $$

展开 transition：

$$ V^*(s) = \max_a \left[ R(s, a) + \gamma \sum_{s'} P(s' \mid s, a) V^*(s') \right] $$

$Q^*$ 形式

期望形式：

$$ Q^*(s, a) = \mathbb E \left[ R_{t+1} + \gamma \max_{a'} Q^*(S_{t+1}, a') \mid S_t = s, A_t = a \right] $$

展开 transition：

$$ Q^*(s, a) = R(s, a) + \gamma \sum_{s'} P(s' \mid s, a) \max_{a'} Q^*(s', a') $$

7. Advantage Function

Advantage 函数衡量某个动作相对于策略平均水平的优劣：

$$ A^\pi(s, a) = Q^\pi(s, a) - V^\pi(s) $$

等价地：

$$ Q^\pi(s, a) = V^\pi(s) + A^\pi(s, a) $$

由 $V^\pi(s) = \sum_a \pi(a \mid s) Q^\pi(s, a)$ 可得：

$$ \sum_a \pi(a \mid s) A^\pi(s, a) = 0 $$

即在策略自身的 action distribution 下，advantage 的期望为 0。

8. 从 Value 得到 Policy

普通 $Q$ 上的 greedy policy：

$$ \pi_Q(s) = \arg\max_a Q(s, a) $$

Optimal policy：

$$ \pi^*(s) = \arg\max_a Q^*(s, a) $$

核心对比：

$$ V^\pi(s) = \sum_a \pi(a \mid s) Q^\pi(s, a) \quad\Longleftrightarrow\quad V^*(s) = \max_a Q^*(s, a) $$

前者是 policy-weighted average，后者是 greedy maximum。

9. 动态规划、蒙特卡洛与时序差分

精确的 Bellman 方程包含期望运算，求解方式分为三类：已知模型的动态规划、无模型的蒙特卡洛采样、以及结合两者的时序差分学习。

动态规划

动态规划（Dynamic Programming, DP）假设已知完整的 MDP 模型（转移概率 $P$ 和奖励函数 $R$），利用 Bellman 期望方程迭代求解价值函数。

策略评估：反复应用 Bellman 期望方程，逐步逼近 $V^\pi$：

$$ V_{k+1}(s) = \sum_a \pi(a \mid s) \left[ R(s, a) + \gamma \sum_{s'} P(s' \mid s, a) V_k(s') \right] $$

策略迭代：交替进行策略评估和策略改进：

$$ \pi'(s) = \arg\max_a \left[ R(s, a) + \gamma \sum_{s'} P(s' \mid s, a) V^\pi(s') \right] $$

值迭代：直接使用 Bellman 最优方程迭代，不显式维护策略：

$$ V_{k+1}(s) = \max_a \left[ R(s, a) + \gamma \sum_{s'} P(s' \mid s, a) V_k(s') \right] $$

DP 的局限在于需要完整的环境模型，而多数实际问题中 $P$ 和 $R$ 未知。

蒙特卡洛

蒙特卡洛（Monte Carlo, MC）方法不需要环境模型，直接从完整 episode 的采样 return 中学习。从状态 $s$ 采样 $N$ 条 rollout，取 return 的平均值作为 $V^\pi(s)$ 的估计：

$$ \hat V^\pi(s) = \frac{1}{N} \sum_{i=1}^N G_t^{(i)} \approx V^\pi(s) $$

实际中通常采样多条 trajectory 做平均，以降低单条轨迹带来的高方差。当 $N$ 足够大时，$\hat V^\pi(s)$ 收敛到 $V^\pi(s)$。

增量更新形式是上述批平均的流式等价，每条新 episode 到达时：

$$ V(S_t) \leftarrow V(S_t) + \alpha \left[ G_t - V(S_t) \right] $$

其中 $G_t$ 是当前 episode 的折扣回报。MC 的估计是无偏的，但方差较大，且必须等到 episode 结束才能更新。

First-visit MC：每个 episode 中只对状态 $s$ 第一次出现时进行更新。

Every-visit MC：每个 episode 中每次出现状态 $s$ 都进行更新。

时序差分

时序差分（Temporal Difference, TD）结合了 DP 的 bootstrap 和 MC 的采样思想，不需要环境模型，也不需要等到 episode 结束：

Bellman expectation：

$$ V^\pi(s) = \mathbb E_\pi \left[ R_{t+1} + \gamma V^\pi(S_{t+1}) \mid S_t = s \right] $$

单样本 TD target：

$$ y_t^{\text{TD}} = R_{t+1} + \gamma V(S_{t+1}) $$

TD error：

$$ \delta_t = y_t^{\text{TD}} - V(S_t) = R_{t+1} + \gamma V(S_{t+1}) - V(S_t) $$

TD update：

$$ V(S_t) \leftarrow V(S_t) + \alpha \delta_t $$

完全写开：

$$ V(S_t) \leftarrow V(S_t) + \alpha \left[ R_{t+1} + \gamma V(S_{t+1}) - V(S_t) \right] $$

TD 的方差比 MC 低，但引入 bootstrap 带来了偏差。三种方法的核心区别在于：

方法	是否需要模型	是否需要完整 episode	Bootstrap
DP	是	否	是
MC	否	是	否
TD	否	否	是

10. Q-Learning

Q-Learning 以 Bellman optimality equation 为目标，而非 Bellman expectation equation。

目标方程

$$ Q^*(s, a) = \mathbb E \left[ R_{t+1} + \gamma \max_{a'} Q^*(S_{t+1}, a') \mid s, a \right] $$

Sample TD Target

$$ y_t^Q = R_{t+1} + \gamma \max_{a'} Q(S_{t+1}, a') $$

TD Error

$$ \delta_t = y_t^Q - Q(S_t, A_t) = R_{t+1} + \gamma \max_{a'} Q(S_{t+1}, a') - Q(S_t, A_t) $$

Q-Learning Update

$$ Q(S_t, A_t) \leftarrow Q(S_t, A_t) + \alpha \delta_t $$

完全写开：

$$ Q(S_t, A_t) \leftarrow Q(S_t, A_t) + \alpha \left[ R_{t+1} + \gamma \max_{a'} Q(S_{t+1}, a') - Q(S_t, A_t) \right] $$

四条公式的递进关系：

$$ \text{Bellman optimality equation} \;\to\; \text{sample target} \;\to\; \text{TD error} \;\to\; \text{update} $$

11. $\varepsilon$-Greedy 与 Off-Policy

$\varepsilon$-greedy 策略：以概率 $1-\varepsilon$ 选择贪心动作，以概率 $\varepsilon$ 随机探索。

若随机部分在所有 $|\mathcal A|$ 个动作中均匀采样：

$$ \pi_{\varepsilon}(a \mid s) = \begin{cases} 1 - \varepsilon + \dfrac{\varepsilon}{|\mathcal A|}, & a = \arg\max_{a'} Q(s, a') \\[6pt] \dfrac{\varepsilon}{|\mathcal A|}, & \text{otherwise} \end{cases} $$

Q-Learning 使用两套策略：

Behavior policy：$\varepsilon$-greedy（用于生成数据）
Target policy：$\arg\max_a Q(s, a)$（用于计算 target）

因此 Q-Learning 是 off-policy 算法：数据由探索性的 behavior policy 生成，但 target 使用 greedy policy。

12. Q-Learning 与 SARSA 的公式差异

Q-Learning（off-policy）：

$$ y_t^Q = R_{t+1} + \gamma \max_{a'} Q(S_{t+1}, a') $$$$ Q(S_t, A_t) \leftarrow Q(S_t, A_t) + \alpha \left[ R_{t+1} + \gamma \max_{a'} Q(S_{t+1}, a') - Q(S_t, A_t) \right] $$

SARSA（on-policy）：下一步动作由当前 behavior policy 实际采样

$$ A_{t+1} \sim \pi(\cdot \mid S_{t+1}) $$$$ y_t^{\text{SARSA}} = R_{t+1} + \gamma Q(S_{t+1}, A_{t+1}) $$$$ Q(S_t, A_t) \leftarrow Q(S_t, A_t) + \alpha \left[ R_{t+1} + \gamma Q(S_{t+1}, A_{t+1}) - Q(S_t, A_t) \right] $$

最核心的差别：

$$ \boxed{\text{Q-Learning: } \max_{a'} Q(S_{t+1}, a')} \qquad \boxed{\text{SARSA: } Q(S_{t+1}, A_{t+1}), \quad A_{t+1} \sim \pi} $$

前者对下一步做 greedy optimization，后者使用 behavior policy 实际选出的下一动作。这也是 off-policy 与 on-policy 差异在公式中的直接体现。

13. 核心公式关系图

如果只保留一组需要反复记忆的公式，就是 RL 的基础公式链：

$$ G_t = R_{t+1} + \gamma G_{t+1} $$$$ V^\pi(s) = \mathbb E_\pi[G_t \mid S_t = s] $$$$ Q^\pi(s, a) = \mathbb E_\pi[G_t \mid S_t = s, A_t = a] $$$$ V^\pi(s) = \sum_a \pi(a \mid s) Q^\pi(s, a) $$$$ Q^\pi(s, a) = R(s, a) + \gamma \sum_{s'} P(s' \mid s, a) V^\pi(s') $$$$ V^\pi(s) = \sum_a \pi(a \mid s) \left[ R(s, a) + \gamma \sum_{s'} P(s' \mid s, a) V^\pi(s') \right] $$$$ V^*(s) = \max_a Q^*(s, a) $$$$ Q^*(s, a) = \mathbb E \left[ R_{t+1} + \gamma \max_{a'} Q^*(S_{t+1}, a') \mid s, a \right] $$$$ A^\pi(s, a) = Q^\pi(s, a) - V^\pi(s) $$$$ \delta_t^V = R_{t+1} + \gamma V(S_{t+1}) - V(S_t) $$$$ \delta_t^Q = R_{t+1} + \gamma \max_{a'} Q(S_{t+1}, a') - Q(S_t, A_t) $$

从 Policy / Return → $V^\pi$ → $Q^\pi$ → Bellman Expectation → Bellman Optimality → TD → Q-Learning，构成了强化学习最基础、最核心的公式链条。

用 ComfyUI 生成图片和视频：从 Workflow 到集群部署

wzh — Sat, 22 Aug 2026 00:00:00 +0000

最近在集群上搭了一套 ComfyUI 环境，用 FLUX.2 生成图片，也准备了 MiniMax H3 的文生视频和图生视频 Workflow。整个过程比想象中有意思：它没有把所有参数塞进一个很长的配置文件，而是把模型、提示词、采样器、VAE 和输出等步骤做成一个个节点，再像拼积木一样把它们连起来。

这篇文章一方面介绍 ComfyUI 的基本概念和常见模块，另一方面也记录一下我自己的使用方式：在集群计算节点上申请 GPU 并运行 ComfyUI Server，通过 SSH 端口转发到 Mac，最后在本地浏览器里编辑和执行 Workflow。

ComfyUI 是什么？

ComfyUI 是一个基于节点图（node graph）的生成式 AI 工作流工具。官方把它定位为一个模块化的 AI 内容创作引擎，除了图片，也支持视频、音频、3D 等任务。

如果以前用过 Stable Diffusion WebUI，可能会习惯在一个页面里填写提示词、采样步数、分辨率，然后点击生成。ComfyUI 的思路不太一样：它把一次生成任务拆成很多可以连接、替换和复用的模块。

例如，一个最基本的文生图流程大致是：

加载模型
 ├── 文本编码器 ──> 编码正向/负向提示词 ──┐
 ├── 去噪模型 ────────────────────────────┤
 └── VAE ────────────────────────────────┐│
 ▼▼
空 Latent ───────────────────────────> KSampler
 │
 ▼
 VAE Decode
 │
 ▼
 Save Image

每个节点两侧都有输入输出接口，接口的颜色和类型需要对应。模型接到采样器的 model，提示词编码结果接到 positive 或 negative，采样器输出的 latent 再交给 VAE 解码。连线正确，数据就会沿着图向后流动。

这也是我觉得 ComfyUI 很好玩的地方。它不像在使用一个只有“生成”按钮的黑盒，更像是在桌面上搭一条小型生产线。简单任务可以只用几个节点，复杂任务则可以继续加入 LoRA、ControlNet、局部重绘、放大、补帧、视频编码等模块。

从最小的文生图 Workflow 开始

下面这张图来自 ComfyUI 官方的文生图基础教程。这是一个很典型的 Stable Diffusion 文生图 Workflow：左侧加载 checkpoint，中间准备提示词和 latent，KSampler 完成采样，最后通过 VAE Decode 和 Save Image 得到图片。

图里从 A 到 F 的六个部分分别是：

Load Checkpoint：加载模型，并输出 MODEL、CLIP 和 VAE。
Empty Latent Image：创建初始潜在空间，同时定义图片宽高和批量大小。
CLIP Text Encode：把正向、负向提示词转换成模型能够使用的条件。
KSampler：从噪声开始，按照提示词条件反复去噪。
VAE Decode：把 latent 解码成真正能看到的像素图像。
Save Image：预览并保存结果。

导入工作流有几种常用方式：

把包含 Workflow 元数据的 PNG 直接拖到画布中；
使用 Workflow -> Open 打开 Workflow JSON 或 PNG；
从 Workflow -> Browse Workflow Templates 选择官方模板；
把 GUI 格式的 JSON 放进 ComfyUI/user/default/workflows/，再从 Workflow 侧边栏打开。

我自己的 Workflow 单独留了一份在项目的 workflows/ 目录中，同时把日常需要在 WebUI 里直接打开的版本放到 ComfyUI 的用户工作流目录。这样既方便备份，也方便后面让 GPT 或 Codex 修改节点和模型路径。

几个最重要的模块

第一次看到 ComfyUI 的节点图可能会觉得线很多，但真正理解下面几个模块以后，大部分基础 Workflow 都能看懂。

去噪模型：UNet、DiT 和 MODEL

在传统 Stable Diffusion Workflow 里，经常会看到 UNet 这个名字。它是扩散过程中的去噪主干：输入某一步的噪声 latent、当前时间步和文本条件，预测应该如何减少噪声。KSampler 会反复调用它，逐步把随机噪声变成具有结构的图像。

不过需要注意，“UNet”在 ComfyUI 生态里有时也被当作去噪模型的习惯性统称。 FLUX.2、MiniMax H3 等较新的模型使用的是 Transformer/DiT 一类架构，并不等于经典 Stable Diffusion UNet。界面上仍可能通过 UNETLoader 加载，连接出去的类型通常也统一显示为 MODEL。理解 Workflow 时，把它看成“负责扩散去噪的主模型”更准确。

CLIP 与文本编码器

生成模型不能直接理解自然语言字符串，因此提示词要先经过文本编码器，变成一组语义向量，再作为 conditioning 送入采样流程。

SD1.5 的基础流程里常把这一部分叫作 CLIP Text Encode。新模型不一定只使用 CLIP，例如我的 FLUX.2 Workflow 使用 Mistral 系列文本编码器，MiniMax H3 使用 Qwen3-VL 32B 文本编码器。节点名称和底层模型会变化，但它们承担的核心职责相似：把“我想生成什么”转换成去噪模型能使用的条件。

传统文生图里通常有两路条件：

positive：希望画面中出现的主体、环境、风格、镜头和光线；
negative：希望模型避免的内容，例如模糊、错误肢体、文字水印等。

不同模型的提示词习惯并不完全相同。不能把 SD1.5 时代的“关键词堆叠”机械套到所有新模型上，有些新模型更适合完整、结构清楚的自然语言描述。

Latent：模型真正工作的“画布”

扩散模型通常不直接在完整 RGB 像素上反复去噪，而是在压缩后的潜在空间（latent space）中工作。可以把它理解成一张信息更紧凑的“草图”或“蓝图”。

文生图一般从随机 latent 开始；图生图则先用 VAE Encode 把输入图片压进 latent，再加入一定噪声后继续采样。因此图生图中的 denoise 很关键：数值越小越保留原图，越接近 1，模型自由发挥的程度越高。

KSampler：真正执行生成的核心

KSampler 是基础 Workflow 中最核心的节点之一。它接收：

去噪模型 model；
正向和负向条件；
初始 latent_image；
seed、steps、cfg、采样器和调度器等参数。

其中几个参数最值得记住：

参数	作用	实际理解
`seed`	初始化随机噪声	相同模型、参数和 seed 更容易复现结果
`steps`	去噪迭代次数	不是越高越好，超过模型合适范围只会更慢
`cfg`	提示词引导强度	太高可能让画面生硬或失真；不同模型推荐值差异很大
`sampler_name`	采样算法	决定每一步如何沿去噪轨迹更新
`scheduler`	噪声调度方式	决定时间步和噪声强度如何分配
`denoise`	去噪强度	文生图一般为 1；图生图常小于 1

如果 Workflow 使用的是 SamplerCustom、独立 Scheduler 和 Guider 节点，不必慌张，它只是把 KSampler 内部的几个步骤进一步拆开了，方便更细粒度地控制。

VAE Encode / Decode

VAE 是像素空间和潜在空间之间的桥梁：

VAE Encode：图片 → latent，常见于图生图、局部重绘和参考图流程；
VAE Decode：latent → 图片，是输出最终结果前的必要步骤。

视频模型也有类似的编解码过程，只不过 latent 多了时间维度。MiniMax H3 还把视频和音频分别交给 video VAE、audio VAE 处理，因此我的 H3 模型目录里会同时出现两套 VAE。

LoRA 与其他控制节点

LoRA 可以在不替换基础模型的情况下调整风格、角色或特定能力。ControlNet、参考图编码、遮罩和预处理器则会给生成过程增加姿态、边缘、深度或局部区域等约束。

这些模块正是节点式工作流的优势：不需要重写整条链路，只要把新模块接到合适的位置即可。

我使用的图片模型：FLUX.2 Dev FP8

这次图片生成使用的是 FLUX.2 Dev。官方的 FLUX.2 ComfyUI 教程提供了文生图和多参考图模板；我采用的是适合当前集群环境的 FP8 Workflow，主要文件如下：

ComfyUI/models/diffusion_models/flux2_dev_fp8mixed.safetensors
ComfyUI/models/text_encoders/mistral_3_small_flux2_fp8.safetensors
ComfyUI/models/vae/flux2-vae.safetensors
ComfyUI/models/loras/Flux2TurboComfyv2.safetensors

选择 FP8 的主要原因不是“量化后画质更好”，而是它在 A6000 和当前 PyTorch/CUDA 组合下更实用，可以减少显存、内存和加载压力。具体使用时仍然要在速度、显存占用和精度之间做取舍。

对应的图片 Workflow 可以概括成四个部分：

模型加载：加载 FLUX.2 diffusion model、Mistral 文本编码器、VAE 和可选 Turbo LoRA；
条件构造：编码提示词，准备分辨率、批量大小和初始 latent；
采样生成：设置 seed、steps、guidance 和 scheduler，执行去噪；
解码保存：通过 FLUX.2 VAE 解码，再预览或保存图片。

下面是 ComfyUI 官方 FLUX.2 文生图模板给出的示例结果：

我的 Workflow 文件名是：

workflows/image_flux2_fp8.json

打开以后最常修改的通常不是节点拓扑，而是提示词、分辨率、seed、采样参数以及 LoRA 强度。节点搭好以后，后续生成基本就是在同一张图上不断迭代。

我使用的视频模型：MiniMax H3

视频部分使用的是 MiniMax H3 FL2VA，准备了两条 Workflow：

workflows/video_minimax_h3_t2v_fp8_cluster.json
workflows/video_minimax_h3_i2v_fp8_cluster.json

T2V（Text to Video）：只有文本提示词，从噪声开始生成视频；
I2V（Image to Video）：增加一张起始图片，让画面主体和构图更可控。

我选择 FL2VA，是因为这一套权重可以覆盖文生视频和首帧/末帧条件视频。此次没有下载 Ref2VA，所以这套环境暂时不包含多参考图片、参考视频和参考音频驱动的 Workflow。

这里也记录一下当时的真实状态：模型下载、文件校验和 Workflow 改写已经完成，但 MiniMax H3 还没有实际完成一次生成验证。 所以这部分更准确地说是“已经准备就绪”，不等于整条 T2V/I2V 链路已经跑通。以后第一次成功生成后，还需要把实际耗时、显存峰值和最终参数补回来。

使用的主要模型文件是：

ComfyUI/models/diffusion_models/
 minimax_h3_fl2va_pruned_fp8_scaled.safetensors

ComfyUI/models/text_encoders/
 qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors

ComfyUI/models/vae/
 minimax_h3_video_vae_fp16.safetensors
 minimax_h3_audio_vae_fp32.safetensors

MiniMax H3 Workflow 比图片 Workflow 更长，但仍然可以按功能分区理解：

加载区：加载 H3 diffusion model、Qwen3-VL 文本编码器和视频/音频 VAE；
输入区：填写提示词，选择 T2V 或上传 I2V 首帧；
规格区：设置宽高、时长、帧率以及帧数等参数；
条件与采样区：将文本、图像和时间信息组成 conditioning，再执行视频 latent 的采样；
解码输出区：分别解码视频与音频，最后保存或封装输出文件。

视频的计算量远大于单张图片。分辨率、帧数和时长稍微增加，显存占用和生成时间都会明显上涨。第一次跑新 Workflow 时，最好先用较短时长和较低分辨率确认整条链路能够工作，再逐渐提高参数。

这次使用 pruned_fp8_scaled，是因为集群保留了 torch==2.5.1+cu121，而官方模板中的 pruned_int8_convrot 更适合较新的 PyTorch/cu130 组合。模型变体必须和硬件、驱动、PyTorch 以及 ComfyUI 版本一起考虑，不能只看文件名里哪个精度更低。

在集群上运行 ComfyUI

我的工作目录是：

/home/wangzh/personal/comfyui-lab

主要环境为：

ComfyUI: v0.30.2
Conda env: comfyui
PyTorch: 2.5.1+cu121
torchvision: 0.20.1+cu121
torchaudio: 2.5.1+cu121
GPU: NVIDIA A6000

之所以使用 ComfyUI v0.30.2，是因为 MiniMax H3 需要 0.30.0+；同时集群驱动是 NVIDIA 535 / CUDA 12.2，所以没有为了追新而强行升级整套 CUDA 依赖。

登录节点负责提交，计算节点负责生成

集群通常有登录节点和计算节点。比较合适的分工是：

登录节点：准备环境、下载模型、编辑脚本、提交和查看 Slurm 作业；
计算节点：获得 GPU 后，真正运行 ComfyUI Server 和模型推理。

也就是说，不应该在登录节点上直接占用 GPU 或长期跑推理服务。我的启动脚本是：

/home/wangzh/personal/comfyui-lab/scripts/run_comfyui_server.sbatch

脚本默认申请的资源包括：

partition=normal
account=wangzh
gpu=1
cpus-per-task=2
mem=120G
time=02:00:00
cluster port=48188
listen=127.0.0.1

例如要启动一个三小时的 ComfyUI 服务：

sbatch --time=03:00:00 \
 /home/wangzh/personal/comfyui-lab/scripts/run_comfyui_server.sbatch

作业开始后，ComfyUI 会在获得 GPU 的计算环境中监听 127.0.0.1:48188。只监听回环地址不会把服务直接暴露到公网或整个集群网络，后面通过 SSH 隧道访问即可。

从 Mac 建立 SSH 端口转发

我在 Mac 上使用的命令是：

ssh -N -L 28188:127.0.0.1:48188 A6000

然后在 Mac 浏览器中打开：

http://127.0.0.1:28188

这条命令可以拆开理解：

-N：只建立隧道，不在远端执行 shell 命令；
-L：创建本地端口转发；
28188：Mac 上监听的本地端口；
127.0.0.1:48188：从 SSH 远端视角访问的 ComfyUI 地址；
A6000：我在 SSH 配置里使用的主机别名。

整个访问链路可以理解为：

Mac 浏览器
 │ http://127.0.0.1:28188
 ▼
Mac 本地端口 28188
 │ SSH tunnel
 ▼
A6000 对应的远端环境
 │ 127.0.0.1:48188
 ▼
ComfyUI Server + Slurm GPU

这里有一个容易踩坑的地方：127.0.0.1:48188 是相对于 SSH 最终连接到的远端主机而言的。如果 A6000 只会登录到登录节点，而 ComfyUI 实际跑在另一台计算节点，那么还需要让 SSH 经过跳板机连接到计算节点，或者使用集群提供的二段转发脚本。我的环境里可以用项目中的脚本根据 job id 打印正确命令：

/home/wangzh/personal/comfyui-lab/scripts/print_tunnel_command.sh <job-id>

不同集群的网络策略不一样，最可靠的原则是：先确认 ComfyUI 到底在哪台主机监听，再让隧道的远端终点落到那台主机。

在 Mac WebUI 中实际操作

SSH 隧道建立以后，虽然浏览器开在 Mac 上，但所有模型加载和推理仍发生在集群 GPU 上。Mac 只负责显示 WebUI、上传输入、修改参数和查看结果，因此不需要本地拥有大显存。

我的日常操作大概是：

在登录节点提交 Slurm 作业，等待 GPU 分配；
确认 ComfyUI Server 已在计算节点启动；
在 Mac 上执行 SSH 端口转发；
打开 http://127.0.0.1:28188；
从 Workflow 面板加载 FLUX.2、H3 T2V 或 H3 I2V；
修改提示词、图片、分辨率、时长和采样参数；
点击 Queue，观察节点依次执行并等待输出；
保存满意的结果，同时保存对应 Workflow 和 seed。

如果一个节点变红，通常可以从三类问题开始排查：模型文件名不匹配、模型目录放错，或者 Workflow 引用了当前环境没有安装的自定义节点。模型很大时，还要留意系统内存、显存以及模型加载时间，不要看到页面暂时没响应就重复点击 Queue。

让 GPT 或 Codex 帮忙搭 Workflow

ComfyUI Workflow 本质上是 JSON，因此非常适合让 AI 帮忙做机械工作，例如：

根据现有 Workflow 替换模型文件名；
把 T2V Workflow 改成 I2V；
增加 LoRA、保存节点、预览节点或固定 seed；
整理节点位置和分组，让画布更容易读；
批量检查 Workflow 引用的模型是否真实存在；
生成不同显存配置对应的 Workflow 版本。

不过有两个细节需要说清楚。

第一，给 AI 的应该是 GUI Workflow JSON，而不是只供 API 调用的 prompt JSON。前者包含节点位置、连线、分组和控件值，才能在 WebUI 里正常显示为一张可编辑的节点图。

第二，文件中的模型名必须和 ComfyUI/models/... 下的实际文件名完全对应。我的 MiniMax H3 官方模板原本引用：

minimax_h3_fl2va_pruned_int8_convrot.safetensors

为了适配集群环境，两个 Workflow 都改成了：

minimax_h3_fl2va_pruned_fp8_scaled.safetensors

完成后把 JSON 放到 ComfyUI/user/default/workflows/，就可以在 WebUI 的 Workflow 列表中直接打开；也可以保存在项目目录，再通过 Workflow -> Open 导入。

AI 可以帮忙把积木搭好，但第一次执行仍然要人工检查模型版本、输入输出类型、分辨率、帧数和显存占用。一个 JSON 在结构上合法，不代表它一定适合当前机器。

一些实际使用建议

先跑通最小版本，再追求画质

第一次接触某个模型时，先用官方模板和默认参数跑通。确认模型能加载、采样器能执行、VAE 能解码、结果能保存之后，再增加 LoRA、参考图、放大和后处理。否则一开始堆太多节点，出错时很难知道问题在哪一段。

把 Workflow 和模型清单一起保存

只保存 JSON 不够。几个月后重新打开时，最常见的问题就是忘了它依赖哪个模型、模型应该放在哪个目录。最好同时记录：

ComfyUI 版本；
Workflow 文件；
模型文件名与目录；
PyTorch/CUDA 环境；
关键生成参数；
一张成功输出作为基准。

这次下载完成后，ComfyUI/models 大约占用了 95 GB。大模型环境很难靠“缺什么再随便下一个”来维护，提前写清清单会省掉很多时间。

图片记录 seed，视频先压低成本

图片生成中，满意的构图可以先固定 seed，再微调提示词和参数。视频则建议先降低时长和分辨率做预览，因为一次失败生成的成本远高于单张图片。确认动作、镜头和主体稳定以后，再提高规格输出最终版本。

不要盲目照搬参数

网上经常会看到“某个 sampler 最好”“steps 必须多少”“cfg 越高越听话”一类经验。它们往往只对某个具体模型和 Workflow 成立。Stable Diffusion、FLUX.2 和 MiniMax H3 的推荐参数可以完全不同，优先参考模型官方模板，再在自己的硬件上做小范围实验。

常用链接

总结

ComfyUI 的门槛主要来自第一眼看到的节点和连线，但它的核心逻辑其实很清楚：加载模型，准备条件，在 latent 中采样，再把结果解码并保存。 图片和视频的差别主要在模型、条件、latent 维度和输出编码，Workflow 的组织方式是相通的。

对我来说，集群上的这套用法也很舒服。GPU 和大模型留在服务器，Mac 只通过 SSH 隧道访问 WebUI；Workflow 可以交给 GPT 或 Codex 辅助搭建，自己则在浏览器里调整和试验。环境配置完成以后，生成图片和视频就不再是一串难以维护的命令，而是一张可以看见、可以修改、也可以保存下来的流程图。

从这个角度看，ComfyUI 最吸引人的地方可能不只是“能生成图片和视频”，而是它让生成过程本身也变成了一件可以观察和搭建的东西。

GSPO：Group Sequence Policy Optimization 详解

wzh — Tue, 18 Aug 2026 00:00:00 +0000

GSPO（Group Sequence Policy Optimization）是 Qwen 团队在 2025 年提出的一种用于 LLM 强化学习后训练的策略优化算法。它直接建立在 GRPO 的框架之上，但做了一个非常关键的改变：

GRPO 在 token level 计算 importance ratio 并进行 clipping；GSPO 将 importance ratio、clipping 和主要优化单位统一提升到了 sequence level。

因此，理解 GSPO 最重要的并不是记住一个新的 loss，而是理解这一变化：

$$ \boxed{ \text{token-level policy correction} \quad\longrightarrow\quad \text{sequence-level policy correction} } $$

Qwen 团队提出 GSPO 的主要目标，是解决大规模 LLM RL，特别是 长 CoT + MoE 模型训练过程中 GRPO 出现的高方差和训练不稳定问题。原论文报告 GSPO 相比 GRPO 有更好的训练稳定性和效率，并且不再需要 Qwen 此前为 MoE RL 引入的 Routing Replay。

1. GSPO 从哪里来？

从算法演化关系看，可以简单理解成：

$$ \boxed{ \text{PPO} \rightarrow \text{GRPO} \rightarrow \text{GSPO} } $$

但三者解决的问题不同。

1.1 PPO

对于一个 prompt：

$$ x $$

模型生成 response：

$$ y=(y_1,\dots,y_T) $$

语言模型定义：

$$ \pi_\theta(y|x) = \prod_{t=1}^{T} \pi_\theta(y_t|x,y_{<t}) $$

PPO 对每一个 token 定义 importance ratio：

$$ w_t(\theta) = \frac{ \pi_\theta(y_t|x,y_{<t}) }{ \pi_{\theta_{\mathrm{old}}}(y_t|x,y_{<t}) } $$

然后执行 clipped policy optimization：

$$ J_{\mathrm{PPO}}(\theta) = \mathbb{E} \left[ \frac1T \sum_{t=1}^{T} \min \left( w_t\hat A_t, \operatorname{clip}(w_t,1-\epsilon,1+\epsilon)\hat A_t \right) \right] $$

PPO 的重要特点是：

$$ \boxed{\text{token-level advantage}+\text{token-level ratio}} $$

其中 $(\hat A_t)$ 通常需要 Value Model / Critic 进行估计。对于 LLM，这意味着除了 Policy Model，通常还需要维护一个规模相当大的 Value Model，带来显著的计算和显存开销。

2. GRPO 做了什么？

GRPO 最重要的变化其实不是 importance ratio，而是：

$$ \boxed{\text{去掉 Value Model}} $$

对于同一个 prompt $(x)$，从 old policy 中采样 $(G)$ 个 response：

$$ y_1,\dots,y_G \sim \pi_{\theta_{\mathrm{old}}}(\cdot|x) $$

分别得到：

$$ r_1,\dots,r_G $$

然后使用组内 reward normalization：

$$ \hat A_i = \frac{ r_i-\operatorname{mean}(r_1,\dots,r_G) }{ \operatorname{std}(r_1,\dots,r_G) } $$

于是：

reward 高于组平均值：

$$ \hat A_i>0 $$

希望提高这个 response 的概率；

reward 低于组平均值：

$$ \hat A_i<0 $$

希望降低这个 response 的概率。

GRPO 的关键特点是：

一个 response 中的所有 token 都共享同一个 sequence-level advantage：

$$ \hat A_{i,t}=\hat A_i $$

但是它仍然为每个 token 计算独立 importance ratio：

$$ w_{i,t} = \frac{ \pi_\theta(y_{i,t}|x,y_{i,<t}) }{ \pi_{\theta_{\mathrm{old}}}(y_{i,t}|x,y_{i,<t}) } $$

所以 GRPO objective 是：

$$ J_{\mathrm{GRPO}}(\theta) = \mathbb{E} \left[ \frac1G \sum_{i=1}^{G} \frac1{|y_i|} \sum_{t=1}^{|y_i|} \min \left( w_{i,t}\hat A_i, \operatorname{clip}(w_{i,t},1-\epsilon,1+\epsilon)\hat A_i \right) \right] $$

也就是说：

$$ \boxed{ \text{sequence-level reward/advantage} + \text{token-level importance ratio} } $$

这正是 GSPO 认为有问题的地方。

3. GSPO 认为 GRPO 的核心问题是什么？

GSPO 论文提出了一个核心原则：

$$ \boxed{ \text{Unit of Optimization} \approx \text{Unit of Reward} } $$

即：

reward 如果是针对整条 sequence 给出的，那么用于 off-policy correction 和 clipping 的单位也应该对应整条 sequence。

GRPO 的 reward 是：

$$ r(x,y_i) $$

也就是说 verifier 实际评价的是：

$$ \boxed{\text{整个 response}} $$

例如数学 RLVR：

“最终答案对不对？”

reward 可能就是：

$$ r(x,y) = \begin{cases} 1 & \text{correct}\\ 0 & \text{wrong} \end{cases} $$

reward 并没有告诉模型：

token 37 是好的；
token 82 是坏的；
token 151 应该增加概率。

但是 GRPO 的 off-policy correction 却变成：

$$ w_{i,1},w_{i,2},\dots,w_{i,T} $$

即：

$$ \boxed{\text{一个 sequence reward，却产生了大量 token-wise importance weights}} $$

GSPO 作者认为，这会向 gradient 中引入大量没有可靠统计支撑的 token-level variance，且这种噪声随着 response 变长而累积。

这里需要一个准确性上的区分：

“token-level importance sampling 本身在强化学习中是不成立的”并不是一个普遍结论。 Per-decision importance sampling 在合适的 RL formulation 中完全可以有理论依据。

更准确地说：

这是 GSPO 作者针对当前 GRPO formulation 提出的批评：GRPO 给 sequence-level reward/advantage，却使用每个位置单独的一次 token sample 构造 token ratio 并直接用来重新加权梯度；他们认为这种设计在大规模 LLM RL 中会产生高方差和不稳定性。

这是 GSPO 论文的算法观点，而不应扩展成“所有 token-level IS 都是错误的”。

4. GSPO 的核心：Sequence-level Importance Ratio

对于 response：

$$ y_i=(y_{i,1},\dots,y_{i,T_i}) $$

完整 sequence probability：

$$ \pi_\theta(y_i|x) = \prod_{t=1}^{T_i} \pi_\theta(y_{i,t}|x,y_{i,<t}) $$

如果直接构造整个 trajectory 的 likelihood ratio：

$$ R_i = \frac{ \pi_\theta(y_i|x) }{ \pi_{\theta_{\mathrm{old}}}(y_i|x) } $$

那么：

$$ R_i = \prod_{t=1}^{T_i} \frac{ \pi_\theta(y_{i,t}|x,y_{i,<t}) }{ \pi_{\theta_{\mathrm{old}}}(y_{i,t}|x,y_{i,<t}) } $$

也就是：

$$ R_i = \prod_t w_{i,t} $$

但是这里立刻出现一个问题：

sequence 越长，product 的数值波动越严重。

例如：

$$ 1.01^{1000}\approx 20959 $$

即使每个 token 的概率只发生很小的变化，乘 1000 次以后整个 sequence ratio 都可能变得极端。

因此 GSPO 并不直接使用原始 trajectory ratio，而是使用长度归一化：

$$ \boxed{ s_i(\theta) = \left( \frac{ \pi_\theta(y_i|x) }{ \pi_{\theta_{\mathrm{old}}}(y_i|x) } \right)^{1/T_i} } $$

展开：

$$ s_i(\theta) = \left( \prod_{t=1}^{T_i}w_{i,t} \right)^{1/T_i} $$

也就是说：

$$ \boxed{ s_i = \operatorname{GeometricMean} (w_{i,1},\dots,w_{i,T_i}) } $$

或者在 log space：

$$ \boxed{ \log s_i = \frac1{T_i} \sum_{t=1}^{T_i} \left[ \log\pi_\theta(y_{i,t}|x,y_{i,<t}) - \log\pi_{\theta_{\mathrm{old}}}(y_{i,t}|x,y_{i,<t}) \right] } $$

最终：

$$ s_i = \exp(\log s_i) $$

这就是 GSPO 最核心的公式。

5. 为什么一定要做 Length Normalization？

如果直接：

$$ R_i = \frac{\pi_\theta(y_i|x)} {\pi_{\mathrm{old}}(y_i|x)} $$

那么不同长度 response 的 ratio 无法直接使用相同 clipping range。

例如两个 sequence 的平均 token probability change 完全相同：

$$ w_t=1.001 $$

但一个长度：

$$ T=100 $$

另一个：

$$ T=2000 $$

则：

$$ R_{100}=1.001^{100} $$

而：

$$ R_{2000}=1.001^{2000} $$

两者会出现非常大的差异。

但做 geometric mean 后：

$$ s = R^{1/T} 1.001 $$

于是：

$$ \boxed{\text{sequence length 对 importance ratio scale 的影响基本被消除}} $$

Qwen 论文明确指出，length normalization 的目的就是降低 variance，同时让不同长度 response 的 importance ratio 落在统一的 numerical range 中。

因此严格来说，GSPO 使用的是：

$$ \boxed{\text{length-normalized sequence likelihood ratio}} $$

而不是原始 importance sampling 中未经修改的：

$$ \frac{\pi_\theta(y|x)} {\pi_{\mathrm{old}}(y|x)} $$

这个区别很重要。

6. GSPO Objective

GSPO 保留了 GRPO 的 group advantage：

$$ \hat A_i = \frac{ r(x,y_i)-\operatorname{mean}_j r(x,y_j) }{ \operatorname{std}_j r(x,y_j) } $$

但是将 token ratio 替换成 sequence ratio：

$$ s_i(\theta) = \left( \frac{\pi_\theta(y_i|x)} {\pi_{\mathrm{old}}(y_i|x)} \right)^{1/T_i} $$

最终 objective：

$$ \boxed{ J_{\mathrm{GSPO}}(\theta) = \mathbb{E} \left[ \frac1G \sum_{i=1}^{G} \min \left( s_i(\theta)\hat A_i, \operatorname{clip} \left( s_i(\theta), 1-\epsilon, 1+\epsilon \right) \hat A_i \right) \right] } $$

与 GRPO 对比：

GRPO

$$ \frac1T \sum_t \min \left( w_{i,t}A_i, \operatorname{clip}(w_{i,t})A_i \right) $$

GSPO

$$ \min \left( s_iA_i, \operatorname{clip}(s_i)A_i \right) $$

所以最本质的变化就是：

$$ \boxed{ {w_{i,1},w_{i,2},\dots,w_{i,T}} \rightarrow s_i } $$

整条 sequence 只对应一个 importance ratio。

7. Sequence-level Clipping 到底是什么意思？

假设：

$$ \hat A_i>0 $$

说明这个 response 比同组其他 response 更好。

我们希望：

$$ \pi_\theta(y_i|x)\uparrow $$

如果：

$$ s_i>1+\epsilon $$

意味着 current policy 已经把这条 response 的相对概率提高得足够多。

于是：

$$ \operatorname{clip}(s_i) = 1+\epsilon $$

后续不再继续鼓励它。

反过来，如果：

$$ \hat A_i<0 $$

说明这是一个较差 response，我们希望：

$$ \pi_\theta(y_i|x)\downarrow $$

当：

$$ s_i<1-\epsilon $$

说明它已经被降低得足够多，于是停止进一步惩罚。

所以 PPO、GRPO 和 GSPO 都可以理解为：

$$ \boxed{\text{不要让一次 policy update 离 rollout policy 太远}} $$

区别只是这个“距离”在哪里判断：

$$ \begin{array}{c|c} \text{Algorithm} & \text{Clipping Granularity}\\ \hline \text{PPO} & Token\\ \text{GRPO} & Token\\ \text{GSPO} & Sequence \end{array} $$

8. GSPO 与 GRPO 最大的数学区别：Gradient Weight

这一部分实际上是理解 GSPO 最关键的地方。

先暂时忽略 clipping。

GSPO：

$$ J = s_i(\theta)\hat A_i $$

所以：

$$ \nabla_\theta J = \hat A_i\nabla_\theta s_i $$

利用：

$$ \nabla s=s\nabla\log s $$

得到：

$$ \nabla_\theta J = s_i\hat A_i \nabla_\theta\log s_i $$

而：

$$ \log s_i = \frac1{T_i} \sum_t \left( \log\pi_\theta(y_{i,t}|x,y_{i,<t}) - \log\pi_{\mathrm{old}}(\cdots) \right) $$

old policy 与 $(\theta)$ 无关，所以：

$$ \nabla_\theta\log s_i = \frac1{T_i} \sum_t \nabla_\theta \log\pi_\theta(y_{i,t}|x,y_{i,<t}) $$

最终：

$$ \boxed{ \nabla_\theta J_{\mathrm{GSPO}} = s_i\hat A_i \frac1{T_i} \sum_t \nabla_\theta \log\pi_\theta(y_{i,t}|x,y_{i,<t}) } $$

注意：

$$ s_i\hat A_i $$

对于这条 response 中所有 token 是完全相同的。

因此每个 token gradient：

$$ \nabla\log\pi_\theta(y_{i,t}|\cdots) $$

都获得同样的 sequence-level weight：

$$ \boxed{s_i\hat A_i} $$

9. 再看 GRPO 的 Gradient

GRPO：

$$ J = \frac1T \sum_t w_{i,t}\hat A_i $$

因此：

$$ \boxed{ \nabla_\theta J_{\mathrm{GRPO}} = \hat A_i \frac1T \sum_t w_{i,t} \nabla_\theta \log\pi_\theta(y_{i,t}|x,y_{i,<t}) } $$

这里最大的区别出现了。

GRPO：

$$ w_{i,1}, w_{i,2}, \dots, w_{i,T} $$

每个 token 的 gradient 权重都不一样：

$$ w_{i,t}\hat A_i $$

而 GSPO：

$$ s_i,s_i,\dots,s_i $$

所有 token 都使用：

$$ s_i\hat A_i $$

所以：

$$ \boxed{ \begin{aligned} \text{GRPO: }& w_{i,t}\hat A_i \nabla\log\pi_\theta(y_{i,t})\\[2mm] \text{GSPO: }& s_i\hat A_i \nabla\log\pi_\theta(y_{i,t}) \end{aligned} } $$

这实际上比单纯说“GSPO 是 sequence clipping”更能说明算法本质。

10. 一个直观例子

假设一条 response 有四个 token，对应 old policy → current policy 的 token ratios：

$$ [1.10,\ 0.90,\ 1.05,\ 0.95] $$

GRPO 会分别使用：

$$ 1.10,\quad0.90,\quad1.05,\quad0.95 $$

来 weight 四个 token 的 gradients。

而 GSPO：

$$ s = (1.10\times0.90\times1.05\times0.95)^{1/4} $$

大约为：

$$ s\approx0.997 $$

于是四个 token 都使用：

$$ 0.997\hat A $$

作为 sequence-level coefficient。

从整条 response 看：

$$ s\approx1 $$

意味着：

old policy 和 current policy 对这条完整 response 的平均 likelihood 基本没有变化。

GSPO 因此不会因为其中某一个 token 的 ratio 是 1.10、另一个是 0.90，就对不同 token 施加非常不同的 off-policy correction。

11. GSPO 其实非常接近一种 Sequence-level REINFORCE

这是从公式可以直接得到的一个理解。

考虑：

$$ \theta=\theta_{\mathrm{old}} $$

此时：

$$ s_i=1 $$

忽略 clipping：

$$ \nabla J_{\mathrm{GSPO}} = \hat A_i \frac1T \sum_t \nabla_\theta\log\pi_\theta(y_{i,t}|x,y_{i,<t}) $$

而：

$$ \sum_t \log\pi_\theta(y_{i,t}|x,y_{i,<t}) = \log\pi_\theta(y_i|x) $$

于是：

$$ \nabla J = \frac{\hat A_i}{T} \nabla_\theta \log\pi_\theta(y_i|x) $$

所以从这个角度，可以将 GSPO 理解为：

$$ \boxed{ \text{Group-normalized sequence REINFORCE} + \text{sequence-level off-policy correction} + \text{PPO-style clipping} } $$

其中 group baseline 来自同 prompt 的多个 sampled responses。

这个理解通常比单独记忆 GSPO loss 更容易把 GSPO 放到 RL 的整体框架里。

12. 为什么 GSPO 对 Long CoT 更稳定？

假设一个 reasoning response 有：

$$ T=8000 $$

个 tokens。

GRPO 会产生：

$$ 8000 $$

个不同的：

$$ w_t $$

因此 gradient 类似：

$$ \sum_{t=1}^{8000} w_t A\nabla\log\pi_t $$

其中某些：

$$ w_t\gg1 $$

某些：

$$ w_t\ll1 $$

而且不同 token 会单独触发 clipping。

随着 sequence 变长，这种 token-level variation 会不断累积。

GSPO 则先将它们压缩成：

$$ s = \exp \left( \frac1T \sum_t\log w_t \right) $$

然后：

$$ \nabla J \propto sA \frac1T \sum_t\nabla\log\pi_t $$

因此它实际上在问：

“current policy 整体上对这条 reasoning trajectory 的 likelihood 改变了多少？”

而不是：

“第 5387 个 token 的 probability 改了多少？”

对于只有 sequence-level verifier reward 的数学、代码等 RLVR 场景，这种 granularity 与 reward granularity 更自然地对齐。这正是 GSPO 的核心设计逻辑。

13. 为什么 GSPO 对 MoE 特别重要？

这是 GSPO 论文非常重要的一部分。

对于 Dense Transformer：

$$ x \rightarrow \text{固定的全部参数} $$

每次 forward 使用的 network structure 基本一致。

但对于 MoE：

$$ x_t \rightarrow \text{Router} \rightarrow \text{Expert}_{k_1},\text{Expert}_{k_2} $$

每个 token 激活哪些 experts 是动态的。

因此：

$$ \pi_{\mathrm{old}} $$

生成 rollout 时可能使用：

$$ E_3,E_7 $$

而做几次 gradient update 以后，同样的 token 在：

$$ \pi_\theta $$

里可能变成：

$$ E_2,E_7 $$

Qwen 在 Qwen3-30B-A3B-Base 上观察到：一次 RL gradient update 后，对于同一个 rollout sample，新旧 policy 激活的 experts 中大约有 10% 发生变化。

这会使：

$$ \frac{ \pi_\theta(y_t|x,y_{<t}) }{ \pi_{\mathrm{old}}(y_t|x,y_{<t}) } $$

发生明显波动。

问题不仅仅是参数改变了，而是：

$$ \boxed{\text{实际参与计算的 expert network 也可能改变}} $$

因此 token ratio 可能非常 noisy。

14. Routing Replay 是什么？

在 GSPO 之前，Qwen 为解决这个问题采用过 Routing Replay。

rollout 时记录：

$$ \pi_{\mathrm{old}} $$

每个 token 激活了哪些 experts。

计算 current policy probability 时，不允许 router 重新选择 experts，而是 replay old routing：

$$ \text{route}_{\theta} \leftarrow \text{route}_{\theta_{\mathrm{old}}} $$

于是比较：

$$ \pi_\theta(y_t) $$

与：

$$ \pi_{\mathrm{old}}(y_t) $$

时，两者使用相同的 expert topology。

这样：

$$ w_t = \frac{\pi_\theta(y_t)} {\pi_{\mathrm{old}}(y_t)} $$

会稳定很多。

论文实验中，GRPO 在 Qwen 的 MoE setting 下如果去掉 Routing Replay，training reward 明显恶化；加入 Routing Replay 后才可以正常训练。

但 Routing Replay 有代价：

rollout 需要额外缓存 routing information；
增加通信和 memory overhead；
training pipeline 更复杂；
current policy 不能完全自由使用当前 router；
一定程度上限制 MoE 自身动态 routing 的能力。

15. GSPO 为什么可以不需要 Routing Replay？

因为 GSPO 不关心单个 token：

$$ w_t $$

而只关心：

$$ s_i = \exp \left( \frac1T\sum_t\log w_t \right) $$

单个 token 因为 expert routing change 导致：

$$ w_t $$

突然变大或者变小，对整个 sequence 的影响会被 sequence aggregation 稀释。

例如：

$$ w= [ 1.00, 1.01, 0.99, 1.02, \boxed{1.30}, 1.00, 0.98,\dots ] $$

GRPO 会直接让：

$$ 1.30 $$

参与这个 token 的梯度。

GSPO 使用的是：

$$ \exp(\operatorname{mean}\log w_t) $$

如果 sequence 很长，一个 token 的异常值影响相对有限。

因此：

$$ \boxed{ \text{GSPO 对 individual token likelihood fluctuation 更不敏感} } $$

Qwen 的实验显示 GSPO 可以在不使用 Routing Replay 的情况下稳定训练其 MoE 模型。作者将这一点视为 GSPO 对大规模 MoE RL 最重要的优势之一。

这里同样需要保持表述准确：

实验表明 GSPO 在 Qwen 的 MoE RL setting 中解决了 Routing Replay 依赖；这不等价于已经证明所有 MoE、所有 RL pipeline 都绝不会出现 routing-related instability。

16. 一个非常反直觉的实验：GSPO Clip 得更多，反而训得更好

Qwen 论文里有一个很有意思的结果。

平均 clipping fraction：

$$ \text{GRPO}\approx0.0013 $$

而：

$$ \text{GSPO}\approx0.15 $$

也就是说，GSPO 大约有：

$$ 15% $$

的 tokens 因为所在 sequence 被 clipping，而 GRPO 只有大约：

$$ 0.13% $$

的 token 被 clip。

GSPO clipping 的数据明显更多。

但实验中 GSPO 的 training efficiency 反而更高。

作者据此认为：

GRPO 虽然“用了更多 token”，但其中相当一部分 token-level gradient signal 本身非常 noisy；GSPO 丢掉了更多 off-policy sequences，却留下了质量更可靠的 gradient。

所以：

$$ \boxed{ \text{More training tokens} \not\Rightarrow \text{Better gradient estimation} } $$

重要的是：

$$ \text{signal quality} $$

而不是单纯 sample utilization。

17. GSPO 的 Clip Range 和 GRPO 完全不是一个量级

这一点实现时非常重要。

Qwen 的实验中：

GSPO 使用 asymmetric clipping：

$$ \epsilon_{\mathrm{low}} = 3\times10^{-4} $$$$ \epsilon_{\mathrm{high}} = 4\times10^{-4} $$

大致就是：

$$ s_i \in [ 1-3\times10^{-4}, 1+4\times10^{-4} ] $$

而 GRPO 使用：

$$ 0.2,\quad0.27 $$

这种量级。

不要看到 GSPO 也是 PPO-style clipping，就直接照搬：

$$ \epsilon=0.2 $$

原因是两种 ratio 根本不是同一个量：

GRPO：

$$ w_t $$

GSPO：

$$ s= \exp \left( \operatorname{mean}_t\log w_t \right) $$

GSPO 的 sequence-normalized ratio 通常非常接近：

$$ 1 $$

所以 clipping range 会小几个数量级。

18. GSPO 完整训练流程

对于一个训练 batch：

Step 1：采样 Prompt

$$ x\sim\mathcal D $$

Step 2：Rollout

使用：

$$ \pi_{\theta_{\mathrm{old}}} $$

对同一个 prompt 生成 $(G)$ 条 response：

$$ y_1,\dots,y_G $$

Step 3：计算 Reward

例如数学 RLVR：

$$ r_i = \mathbb{1}[\text{answer correct}] $$

或者：

$$ r_i = r_{\mathrm{correct}} + r_{\mathrm{format}} +\cdots $$

Step 4：计算 Group Advantage

$$ \mu_r = \frac1G \sum_i r_i $$$$ \sigma_r = \operatorname{std}(r_1,\dots,r_G) $$$$ \hat A_i = \frac{r_i-\mu_r}{\sigma_r} $$

实践实现中还需要处理：

$$ \sigma_r=0 $$

的 degenerate group，例如所有 response 都正确或者全部错误。

Step 5：记录 Old-policy Log Probabilities

对于每个 token：

$$ \log p_{i,t}^{old} = \log \pi_{\theta_{\mathrm{old}}} (y_{i,t}|x,y_{i,<t}) $$

Step 6：Current Policy Forward

计算：

$$ \log p_{i,t}^{new} = \log \pi_\theta (y_{i,t}|x,y_{i,<t}) $$

Step 7：计算 Sequence Log Ratio

$$ \Delta_{i,t} = \log p_{i,t}^{new} \log p_{i,t}^{old} $$

然后：

$$ \log s_i = \frac1{T_i} \sum_t \Delta_{i,t} $$

Step 8：Exponentiate

$$ s_i = \exp(\log s_i) $$

Step 9：Sequence-level Clipping

$$ L_i = \min \left( s_i\hat A_i, \operatorname{clip} (s_i,1-\epsilon_l,1+\epsilon_h) \hat A_i \right) $$

Step 10：Aggregate

$$ J = \frac1G \sum_iL_i $$

训练代码通常写成需要 minimize 的 loss：

$$ \boxed{ L_{\mathrm{GSPO}} = -J_{\mathrm{GSPO}} } $$

Step 11：Backpropagation

因为：

$$ s_i = \exp \left( \frac1T \sum_t\log\pi_\theta(y_t|\cdots) -\text{constant} \right) $$

gradient 会自动传回每个 response token。

然后：

$$ \theta \leftarrow \theta+\eta\nabla_\theta J $$

完成 policy update。

19. 用伪代码看 GSPO

for prompts in dataloader:

 # -------------------------------------------------
 # 1. rollout with old policy
 # -------------------------------------------------
 responses = rollout(
 policy_old,
 prompts,
 num_generations=G,
 )

 # -------------------------------------------------
 # 2. rewards
 # -------------------------------------------------
 rewards = verifier(prompts, responses)

 # -------------------------------------------------
 # 3. group-relative advantages
 # -------------------------------------------------
 advantages = group_normalize(rewards)

 # -------------------------------------------------
 # 4. old log probs
 # -------------------------------------------------
 with torch.no_grad():
 old_logp = policy_old.log_probs(
 prompts,
 responses,
 )

 # -------------------------------------------------
 # 5. current log probs
 # -------------------------------------------------
 new_logp = policy.log_probs(
 prompts,
 responses,
 )

 # [B, T]
 token_log_ratio = new_logp - old_logp

 # -------------------------------------------------
 # 6. sequence-level ratio
 # -------------------------------------------------
 seq_log_ratio = masked_mean(
 token_log_ratio,
 response_mask,
 dim=-1,
 )

 seq_ratio = torch.exp(seq_log_ratio)

 # -------------------------------------------------
 # 7. GSPO clipping
 # -------------------------------------------------
 unclipped = seq_ratio * advantages

 clipped_ratio = torch.clamp(
 seq_ratio,
 1 - eps_low,
 1 + eps_high,
 )

 clipped = clipped_ratio * advantages

 objective = torch.minimum(
 unclipped,
 clipped,
 )

 # -------------------------------------------------
 # 8. optimize
 # -------------------------------------------------
 loss = -objective.mean()

 loss.backward()
 optimizer.step()

从实现层面看，GSPO 与 GRPO 的区别实际上非常集中：

GRPO：

ratio = exp(new_logp - old_logp) # [B, T]

然后 token-wise clip。

GSPO：

log_ratio = new_logp - old_logp
seq_log_ratio = mean(log_ratio, dim=response_tokens)
ratio = exp(seq_log_ratio) # [B]

然后 sequence-wise clip。

20. GSPO 并没有改变 Group Relative Advantage

这一点很容易混淆。

GSPO 并不是：

“把 GRPO 完全重新设计了一遍。”

实际上 GSPO 仍然保留：

$$ G\text{ responses / prompt} $$

以及：

$$ \hat A_i = \frac{r_i-\mu_r}{\sigma_r} $$

所以：

$$ \boxed{ \textbf{Group} } $$

这个部分基本继承自 GRPO。

GSPO 真正改变的是：

$$ \boxed{ \textbf{Sequence} } $$

也就是：

sequence likelihood ratio；
sequence clipping；
sequence optimization weighting。

所以它的名字非常准确：

$$ \boxed{ \underbrace{\text{Group}}_{\text{GRPO-style advantage}} + \underbrace{\text{Sequence}}_{\text{sequence importance ratio}} + \underbrace{\text{Policy Optimization}}_{\text{PPO-style clipped objective}} } $$

21. PPO、GRPO、GSPO 的核心对比

	PPO	GRPO	GSPO
Multiple responses/group	不要求	是	是
Value Model	需要	不需要	不需要
Advantage	token/state level	sequence group advantage	sequence group advantage
Reward granularity	sequence / process	通常 sequence	通常 sequence
Importance ratio	token	token	sequence
Ratio	(w_t)	(w_{i,t})	(s_i)
Clipping	token	token	sequence
同 sequence token gradient weight	不同	不同	相同
Long-CoT stability	—	较容易出现 ratio noise	更稳定
MoE routing sensitivity	—	高	明显降低
Routing Replay	—	Qwen MoE 中需要	不需要
Critic overhead	高	无	无

因此最简洁的关系是：

$$ \boxed{ \text{GRPO} = \text{Group Advantage} + \text{Token Ratio} } $$

而：

$$ \boxed{ \text{GSPO} = \text{Group Advantage} + \text{Sequence Ratio} } $$

22. GSPO-token 是什么？

GSPO 论文还提出了一个变体：

$$ \boxed{\text{GSPO-token}} $$

为什么还需要 token variant？

因为有些任务并不是只有 sequence-level credit。

例如 multi-turn agent：

Think
Action
Observation
Think
Action
Observation
...

可能希望：

$$ A_{i,t} $$

在不同 token 或不同阶段上不同。

普通 GSPO：

$$ A_{i,t}=A_i $$

所有 token 完全共享一个 advantage。

GSPO-token 为此定义：

$$ s_{i,t}(\theta) = \operatorname{sg}[s_i(\theta)] \cdot \frac{ \pi_\theta(y_{i,t}|x,y_{i,<t}) }{ \operatorname{sg} [ \pi_\theta(y_{i,t}|x,y_{i,<t}) ] } $$

其中：

$$ \operatorname{sg}[\cdot] $$

表示 stop-gradient / detach。

注意：

$$ \frac{ \pi_\theta }{ \operatorname{sg}[\pi_\theta] } $$

在数值上永远是：

$$ 1 $$

因此：

$$ s_{i,t} $$

numerically 等于：

$$ s_i $$

但 gradient 可以从对应 token 的：

$$ \pi_\theta(y_{i,t}) $$

向后传播。

于是 GSPO-token 可以使用：

$$ A_{i,t} $$

而不是：

$$ A_i $$

从而实现更细粒度 credit assignment。

如果设置：

$$ A_{i,t}=A_i $$

论文证明 GSPO-token 与普通 GSPO 在：

objective numerical value；
clipping condition；
theoretical gradient；

上都是等价的。

23. GSPO 对 RL Infrastructure 的潜在意义

现代 LLM RL 经常是：

Inference Engine
 ↓ rollout
SGLang / vLLM
 ↓
Training Engine
Megatron / FSDP / ...

问题是 inference engine 与 training engine 之间可能存在：

BF16 / FP8 difference；
kernel difference；
tensor parallel implementation difference；
MoE routing difference；
numerical precision difference。

于是：

$$ \log p_{\mathrm{inference}} $$

和：

$$ \log p_{\mathrm{training}} $$

可能存在微小偏差。

对于 GRPO：

$$ w_t = \exp( \log p_t^{new} - \log p_t^{old} ) $$

每一个 token 的微小误差都会直接进入：

$$ w_t $$

甚至改变 token 是否被 clipping。

因此很多 RL infrastructure 会：

rollout engine 负责生成，但 training engine 再 recompute 一次 old log probabilities。

GSPO 使用：

$$ \frac1T \sum_t (\log p_t^{new}-\log p_t^{old}) $$

单 token numerical mismatch 会被 sequence aggregation 平滑，因此 Qwen 认为 GSPO 对 inference/training engine 的 probability discrepancy 更 tolerant，有可能直接使用 inference engine 返回的 likelihood，而不再由 training engine recompute。

论文对此使用的是“makes it possible / potential”式表述，因此更准确的理解是：

$$ \boxed{ \text{GSPO 有潜力简化 rollout-training probability synchronization} } $$

而不是：

“GSPO 已经证明 old-logprob recomputation 永远都不需要。”

24. Qwen 的实验结果

原论文主要使用：

$$ \text{Qwen3-30B-A3B-Base} $$

构造 cold-start RL model。

评测包括：

AIME 2024；
LiveCodeBench；
CodeForces。

在相同 training compute 和 query consumption 下，GSPO 的 reward、AIME、LiveCodeBench 和 CodeForces performance curves 整体高于 GRPO + Routing Replay。

Qwen 同时表示 GSPO 被应用到了后续 Qwen3 系列模型的 RL 训练中。

不过原始 GSPO paper 本身只有 7 页，其 empirical evidence 主要集中在 Qwen 自己的大规模 MoE setting，因此不能从这篇论文单独推出：

$$ \text{GSPO 在所有 dense / MoE / task / scale 上都优于 GRPO} $$

更准确的结论应该是：

在 Qwen 报告的大规模长序列 MoE RL setting 中，GSPO 展现出了明显的稳定性和效率优势。

25. GSPO 的局限

GSPO 解决 GRPO 问题的方法非常直接：

$$ \boxed{ \text{不要相信单 token ratio，直接看整个 sequence} } $$

但这样也产生了另一端的问题：

25.1 一个坏 token 可能导致整条 sequence 被 clip

假设 sequence 大部分 token 很正常：

$$ w_t\approx1 $$

但存在几个 extreme token。

这些 token 会影响：

$$ s_i = \exp(\operatorname{mean}\log w_t) $$

一旦：

$$ s_i $$

越过 clipping boundary：

$$ \boxed{\text{整条 response 都停止贡献相应 gradient}} $$

而不是只 clip problematic tokens。

因此 GSPO 的 sequence coherence 很强，但 credit assignment 比 token-level 方法粗。

26. 这也是后来 SAPO、SSPO 等方法继续改 GSPO 的原因

截至 2026 年，GSPO 已经不是这一方向的终点。

Qwen 团队成员随后提出 SAPO（Soft Adaptive Policy Optimization），明确指出 GSPO 的 hard sequence clipping 存在这样的 trade-off：

当 sequence 中只有少量 token 非常 off-policy 时，GSPO 可能 suppress 整个 sequence 的 gradient。

SAPO 因此尝试做到：

$$ \boxed{ \text{sequence coherence} + \text{token adaptivity} } $$

通过 soft gating 而不是 GSPO 的 hard clipping，在保留 sequence-level stability 的同时尽量保留有效 token 的 gradient。

另一条路线是 SSPO（Subsentence-level Policy Optimization），将 optimization granularity 设在：

$$ \text{token} < \boxed{\text{subsentence}} < \text{sequence} $$

希望在 GRPO 和 GSPO 两种极端之间取得平衡。SSPO 作者的实验同样指出，GSPO 的整条 sequence clipping 可能降低 sampled data utilization。

因此从今天看，GSPO 真正重要的贡献可能并不只是某个具体 loss，而是提出了一个更一般的问题：

$$ \boxed{ \text{LLM RL 的 optimization granularity 应该是什么？} } $$

可以是：

$$ \text{Token} $$

也可以是：

$$ \text{Subsentence} $$

或者：

$$ \text{Reasoning Step} $$

或者：

$$ \text{Think-Action} $$

或者：

$$ \text{Whole Sequence} $$

这已经成为后续很多 RLVR / Agent RL 工作继续探索的设计维度。

27. 应该怎样真正理解 GSPO？

如果已经理解 PPO 和 GRPO，可以把 GSPO 压缩成下面这一条逻辑链。

GRPO：

$$ r(x,y) $$

产生：

$$ A(y) $$

但是 optimization 使用：

$$ w_t = \frac{\pi_\theta(y_t|y_{<t})} {\pi_{\mathrm{old}}(y_t|y_{<t})} $$

于是：

$$ \nabla J_{\mathrm{GRPO}} \sim A(y) \sum_t w_t \nabla\log\pi_\theta(y_t|y_{<t}) $$

GSPO 认为这里存在：

$$ \boxed{ \text{Reward granularity} \neq \text{Importance-weight granularity} } $$

于是将：

$$ w_t $$

替换成：

$$ s(y) = \left( \frac{\pi_\theta(y|x)} {\pi_{\mathrm{old}}(y|x)} \right)^{1/T} $$

得到：

$$ \nabla J_{\mathrm{GSPO}} \sim s(y)A(y) \frac1T \sum_t \nabla\log\pi_\theta(y_t|y_{<t}) $$

于是：

$$ \boxed{ \text{Reward} \rightarrow \text{Advantage} \rightarrow \text{Importance Ratio} \rightarrow \text{Clipping} } $$

全部围绕：

$$ \boxed{\text{sequence}} $$

这就是 GSPO 的核心。

28. 一张公式图记住 GSPO

$$ \boxed{ x \overset{\pi_{\theta_{\mathrm{old}}}}{\longrightarrow} {y_1,\dots,y_G} } $$

得到：

$$ \boxed{ r_1,\dots,r_G } $$

计算：

$$ \boxed{ A_i = \frac{r_i-\mu_r}{\sigma_r} } $$

然后对每条 sequence：

$$ \boxed{ \log s_i = \frac1{|y_i|} \sum_t \left( \log\pi_\theta(y_{i,t}) - \log\pi_{\mathrm{old}}(y_{i,t}) \right) } $$$$ \boxed{ s_i=e^{\log s_i} } $$

最后：

$$ \boxed{ J_{\mathrm{GSPO}} = \frac1G \sum_i \min \left( s_iA_i, \operatorname{clip}(s_i)A_i \right) } $$

其 gradient：

$$ \boxed{ \nabla J_{\mathrm{GSPO}} \propto \frac1G \sum_i s_iA_i \frac1{|y_i|} \sum_t \nabla\log\pi_\theta(y_{i,t}|x,y_{i,<t}) } $$

与 GRPO 唯一最关键的对比：

$$ \boxed{ \underbrace{w_{i,t}}_{\text{GRPO: token-specific}} \quad\longrightarrow\quad \underbrace{s_i}_{\text{GSPO: sequence-shared}} } $$

如果只记住 GSPO 的一个公式和一个思想，就记这一行。

PPTAgent 与 DeepPresenter：论文讲解、代码解析与 Agent Harness 架构

wzh — Sat, 15 Aug 2026 00:00:00 +0000

本文结合 paper/ 目录下的两篇论文（2501.03936.pdf — PPTAgent，2602.22839.pdf — DeepPresenter）、PPTAgent/ 仓库代码（pptagent/ 旧版核心库 + deeppresenter/ 当前运行时）以及 PPTea-main/ 评测/实验代码，对两代系统的生成流程、评测流程、Agent Harness 主循环与框架架构进行系统讲解，并与"直接让 CodeX/LLM 生成 PPT"的方式做对比。

1. 项目背景与两代系统总览

仓库 PPTAgent/（https://github.com/icip-cas/PPTAgent）包含两代论文的完整代码：

维度	PPTAgent	DeepPresenter
论文	“PPTAgent: Generating and Evaluating Presentations Beyond Text-to-Slides”（EMNLP 2025）	“DeepPresenter: Environment-Grounded Reflection for Agentic Presentation Generation”（ACL 2026）
arXiv 编号	2501.03936	2602.22839
核心思想	两阶段、基于编辑（edit-based）：先分析参考演示文稿提取布局与模式，再通过编辑动作修改参考幻灯片	双智能体 + 环境接地反思：Researcher 自主调研写文稿，Presenter 自由式设计 HTML 幻灯片，通过 `inspect` 观察渲染产物进行反思修正
生成范式	模板复用/编辑式：在已有 PPTX 参考模板上执行编辑 API	自由式（free-form）：从零写 HTML/CSS，渲染为图片再转 PPTX
依赖	参考演示文稿（reference presentation）+ 输入文档	用户指令 +（可选附件）+ 网络检索 + 工具环境
角色	planner / content_organizer / layout_selector / editor / coder / schema_extractor	Researcher（调研+文稿）、Presenter（视觉设计），可选 Planner、SubAgent
评测	PPTEval：Content / Design / Coherence 三维度（MLLM-as-a-judge）	Constraint（规则验证）/ Content / Style 三维度 + Diversity（Vendi Score），GPT-5 作为 judge
对应代码	`pptagent/`（旧版核心库）	`deeppresenter/`（当前运行时）+ `PPTea-main/sarl/`（评测）

时间线关系：PPTAgent 是 2025 年 1 月开源的初代系统（基于编辑 API 的两阶段方案）；DeepPresenter 是 2025 年 12 月发布的重构版（“Agentic” 方案），保留了 pptagent 作为 MCP server（pptagent-mcp）供新系统调用。deeppresenter/ 是当前的主产品面，pptagent/ 是仍在包内、但主要用于 MCP server 入口的旧核心库。

2. PPTAgent：两阶段编辑式生成

2.1 问题定义与核心思想

传统范式（text-to-slides） 把生成演示文稿当作"从文档做抽象式摘要"，用预定义规则或模板把 LLM 输出转成幻灯片：

S = {e1, e2, ..., en} = f(C) （公式 1：从内容 C 生成 n 个幻灯片元素）

其中每个元素要手动指定类型、内容、样式属性（如 (Textbox, "Hello", {border, size, position...})）。这种方式的缺陷：

需要手工指定样式属性，自动化困难；
输出文本密集、版式单调（图 1 右侧：Content: Tedious Text / Design: Boring layout / Coherence: Abrupt Start）。

PPTAgent 的核心洞察：人类制作 PPT 的流程通常是——挑选优秀的示例幻灯片作为参考，然后把关键内容总结并迁移到这些参考幻灯片上（Duarte, 2010）。因此 PPTAgent 把幻灯片生成分解为：

A = {a1, a2, ..., am} = g(C, Rj) （公式 2：给定内容 C 与第 j 个参考幻灯片 Rj，生成 m 个可执行编辑动作）

即：不是从零创建幻灯片，而是在参考幻灯片上执行一系列可执行的编辑动作（如 replace_span、replace_image 等），从而保留参考幻灯片精心设计的版式与风格。

论文的三大贡献：

PPTAgent：把自动演示文稿生成重新定义为"以参考演示文稿为引导的编辑式过程"；
PPTEval：三维度（Content / Design / Coherence）的评测框架；
发布 Zenodo10K 数据集（从 Zenodo 爬取的 10,448 份跨领域演示文稿）。

2.2 Stage I：Presentation Analysis（演示文稿分析）

对应代码：pptagent/induct.py（SlideInducter 类）与 pptagent/model_utils.py（聚类算法）。

目标：分析参考演示文稿，提取幻灯片的版面类型（functional type）与内容模式（content schema），为后续的参考选择与幻灯片生成提供指导。

Step 1：幻灯片分类（Slide Clustering）

幻灯片按功能分为两类：

结构型幻灯片（structural slides）：支撑演示文稿组织的（如开场、目录、章节页、结尾）；
内容型幻灯片（content slides）：传达具体信息的（如要点页）。

分类方法（论文 2.2 节）：

结构型：用 LLM 的长上下文能力分析整份演示文稿的文本，识别结构型幻灯片、标注其结构角色（Opening / TOC / Section Outline / Ending）并按功能分组。对应 induct.py 的 category_split()（induct.py:95-110），使用 prompts/category_split.txt，输出 functional_cluster（类别 → 幻灯片索引列表）与 content_slides_index。
内容型：把幻灯片转成图片，用 ViT 做分层聚类（hierarchical clustering）把相似版面聚到一起。对应 layout_split()（induct.py:112-151）：
1. 用 ViT（google/vit-base-patch16-224-in21k）对模板图片提取 embedding（get_image_embedding()）；
2. 按 (layout_name, content_type)（text/image）预分组；
3. 组内两两计算余弦相似度（images_cosine_similarity()）；
4. 用贪婪聚合聚类 get_cluster()（model_utils.py:291-345）聚类，相似度阈值 sim_bound=0.65（论文 Algorithm 1）——聚类前把文本替换为占位符 “a”、图片替换为纯色背景以只关注版面；
5. 每簇选 shape 最多的幻灯片作为模板幻灯片；
6. 用视觉模型（ASK_CATEGORY_PROMPT）生成一行版面模式描述（如 “One Large Left-Aligned Image with a Right-Aligned Text Block”），并追加 :text 或 :image 后缀。

Step 2：Schema 提取（Schema Extraction）

对每个版面，取其模板幻灯片，提取所有段落文本与图片描述，调用 schema_extractor 智能体生成结构化 JSON schema（content_induct()，induct.py:175-208）。每个元素用 (category, description, content) 表示，例如：

Category Description Data
Title Main title Sample Library
Date Date of the event 15 February 2018
Image Primary image to Picture: Children in a li-
illustrate the slide brary with ...

对应数据模型：pptagent/presentation/layout.py 中的 Element（name/data/type/suggested_characters/variable_length）与 Layout。Stage I 的最终产物是 slide_induction.json（见 scripts/template_induct.py 与 templates/*/slide_induction.json），包含每个版式的 elements、template_id、slides、functional_keys 与语言检测结果。

2.3 Stage II：Presentation Generation（演示文稿生成）

对应代码：pptagent/pptgen.py（PPTGen 抽象基类与 PPTAgent 具体实现）。

Step 1：大纲生成（Outline Generation）

用 LLM 生成结构化大纲（generate_outline()，pptgen.py:239-256），每个条目对应一张新幻灯片，包含：参考幻灯片（基于 Stage I 的功能描述选择）+ 该幻灯片相关的文档内容。大纲以结构化输出（Outline.response_model(source_doc)，见 response/outline.py）生成。

随后 _add_functional_layouts()（pptgen.py:267-318）自动插入结构型幻灯片：

TOC（目录）与 Opening（开场）插在位置 0；
Ending（结尾）插在最后；
每个新主题章节前插入 Section Outline（章节页）；
用 edit_distance 模糊匹配参考稿中对应的功能版式名。

Step 2：幻灯片生成（Slide Generation）——编辑式流水线

generate_slide()（pptgen.py:392-432）对大纲中的每个条目执行：

选择版面 _select_layout()（pptgen.py:434-467）：先用 content_organizer 从检索内容中提取关键点，再由 layout_selector 根据内容与图片匹配情况选择最佳版式（LayoutChoice.response_model(layouts) 结构化输出），文本内容选 :text 版式、含图片的选 :image 版式。
生成内容 _generate_content()（pptgen.py:469-491）：editor 智能体按照 schema 生成结构化内容（EditorOutput.response_model(elements)），再经 _validate_content()（pptgen.py:531-571）校验（图片是否存在、字符数是否超限，超长文本用 length_rewrite() 改写），最后 _generate_commands()（pptgen.py:573-589）把内容差异转成命令序列：对每个元素计算 quantity_change = len(new) - len(old)，产出 (element_name, type, quantity_change, old_data, new_data) 命令元组。
编辑幻灯片 _edit_slide()（pptgen.py:493-529）：这是自校正 REPL 循环——
- coder 智能体依据 API 文档（CodeExecutor.get_apis_docs() 内省 API 签名生成）与模板幻灯片的 HTML 表示，把命令翻译成 API 调用序列；
- CodeExecutor.execute_actions()（apis.py:127-203）用 eval(line, SAFE_EVAL_GLOBALS, ...) 逐行执行 API 调用（replace_paragraph、replace_image、del_paragraph、del_image、clone_paragraph），出错则返回 (api_lines, traceback) 作为反馈；
- LLM 分析反馈修正动作，最多重试 retry_times（默认 3）次，直到生成有效幻灯片。

编辑 API 与 HTML 渲染（CodeRender）

论文的关键设计之一：把参考幻灯片渲染成 HTML 表示（SlidePage.to_html()，presentation.py:193-216），比直接操作 PPTX 的 XML（1006 行冗长冗余，见论文 Figure 11）更精确直观，让 LLM 能理解元素结构并精确修改。

五个编辑 API（pptagent/apis.py）：

API	说明	实现位置
`replace_paragraph`	替换段落内容（markdown→HTML→TextBlock 富文本解析）	`apis.py:403-438`
`replace_image`	替换图片资源（等比缩放居中，表格图片转真表格）	`apis.py:441-473`
`del_paragraph`	删除段落	`apis.py:357-384`
`del_image`	删除图片元素	`apis.py:387-400`
`clone_paragraph`	复制段落（插入 XML 到末段之后）	`apis.py:476-512`

Closure 模式：编辑动作不直接应用到 PPTX，而是修改 SlidePage 表示并排队 Closure 对象（shapes.py:218-246），SlidePage.build() 时按 CLONE → REPLACE/STYLE → DELETE/POST_PROCESS → MERGE 的顺序执行（shapes.py:622-642）。这保证了删除段落时索引处理的正确性。

2.4 PPTEval 评测框架

对应代码：pptagent/ppteval/ppteval.py 与 pptagent/prompts/ppteval/*.txt。

PPTEval 采用 MLLM-as-a-judge 范式，评估三个维度（1-5 分制）：

维度	评分标准	评测对象	Prompt
Content	文本简洁、语法正确、有相关图片支撑	幻灯片级（逐页）	`ppteval_content.txt`
Design	配色和谐、版面可读、视觉元素（几何形状等）提升吸引力	幻灯片级（逐页）	`ppteval_style.txt`
Coherence	结构递进、包含必要的背景信息	整个演示文稿级	`ppteval_coherence.txt`

评测流程（ppteval.py）：

eval_slide()（ppteval.py:54-82）：对每张幻灯片图片，先用视觉模型生成内容描述（content_descriptor）与风格描述（style_descriptor），再用文本模型分别对描述评分（text_scorer / vision_scorer）。这种"感知（VLM）与判断（LLM）分离“的设计是 PPTEval 的关键。
eval_coherence()（ppteval.py:85-108）：提取整份演示文稿文本，先用 ppt_extractor 抽取幻灯片描述与背景元数据，再用 logic_scorer 评一致性。
聚合：Content/Design 取所有幻灯片的平均分，Coherence 为整体分。

与人类评分的一致性（论文 5.5 节）：招募 4 名研究生评 250 份演示文稿（50 份真实 + 200 份生成），Fleiss’ Kappa 平均 0.59；Pearson 相关 0.71、Spearman 相关 0.74，显著优于其他评测方法。

与传统指标对比（论文 Figure 7 热力图）：PPL 与 FID 与 Content/Design 几乎不相关（-0.02/-0.09），说明传统指标（PPL、ROUGE-L、FID）无法评估演示文稿质量——KCTV 拿到高 ROUGE-L（16.76）但低 Content（2.55），PPTAgent 则相反。

2.5 实验结果与消融

主结果（论文 Table 3，Qwen2.5_LM + Qwen2-VL_VM 配置）：

方法	SR(%)	Content	Design	Coherence	Avg
DocPres（规则）	–	2.98	2.37	3.28	2.87
KCTV（模板）	88.0	2.55	2.95	3.36	2.95
PPTAgent	95.0	3.28	3.27	4.48	3.67

消融（论文 Table 4）说明四个组件的贡献：

w/o CodeRender（用 Guo et al. 的表示替换 HTML 渲染）：SR 从 95.0% 掉到 74.6% —— HTML 渲染显著降低交互复杂度；
w/o Schema（去掉 schema 引导）：SR 从 95.0% 掉到 78.8% —— schema 对生成鲁棒性关键；
w/o Outline / w/o Structure：Coherence 从 4.48 掉到 3.36/3.45 —— 大纲与结构型幻灯片分析对连贯性至关重要；
自校正机制（论文 Figure 6）：所有模型都能修正超过一半的错误，GPT-4o 自校正能力最强。

3. DeepPresenter：环境接地反思的双智能体框架

3.1 动机与核心贡献

DeepPresenter 指出现有演示文稿智能体的两个根本缺陷：

依赖预定义工作流与固定模板（如 PPTAgent 的编辑式流程、KCTV 的模板填充），无法适应多样化的用户意图，产出文本密集、研究深度不足、视觉设计与叙事脱节的幻灯片；
内省式反思（introspective self-reflection）失效：智能体操作的是中间表示（HTML/markdown），而用户感知的是渲染后的产物。很多缺陷（图片断裂、元素溢出、低对比度）只在感知状态（渲染后的幻灯片）中显现，内省反思无法察觉。

三大贡献：

DeepPresenter：通过共享观察空间协调两个专职智能体（Researcher + Presenter）的智能体框架；
环境接地反思（Environment-Grounded Reflection）：把自校正建立在渲染后产物的感知状态上，而非内部信号上；
DeepPresenter-9B：用"外在验证（extrinsic verification）“合成的轨迹进行监督微调，小模型以极低代价接近大模型性能。

3.2 任务形式化

把演示文稿生成形式化为交互式智能体任务：给定指令 I 与配备工具库 T 和文件系统 F 的智能体环境 E，生成高质量演示文稿 P。生成过程是多步轨迹：

τ = {(r1, a1, o1), ..., (rT, aT, oT)}

每步：智能体生成推理轨迹 r_t，选择动作 a_t ∈ T，从 E 收到观察 o_t。轨迹分解为两个连续阶段：

τ = τ_R ∘ τ_P

τ_R：Researcher 轨迹；
τ_P：Presenter 轨迹。

两个智能体通过 F 通信：Researcher 把结构化文稿 M 和相关资产持久化到文件系统，Presenter 消费它们。

3.3 双智能体协作：Researcher + Presenter

Researcher Agent（对应 deeppresenter/agents/research.py + roles/Research.yaml）：

不遵循预定义工作流，而是自主规划探索：执行多步检索（search_web、search_images、search_papers、fetch_url）、文档解析（convert_to_markdown）、必要时创建辅助资产（image_generation、matplotlib 绘图）；
探索深度与策略适配用户意图：技术性演讲需要调研相关工作，大众向演讲更重可理解的例子与生动插图；
最终把内容组织成按叙事流排布的结构化 Markdown 文稿 M（用 --- 分页，图片本地化并相对路径引用），持久化到 F；
通过 inspect_manuscript 获取文稿诊断（页数、语言、图片资源可用性），最后调用 finalize 返回文稿路径。

Presenter Agent（对应 deeppresenter/agents/design.py + roles/Design.yaml）：

不填充预定义模板，而是从零生成幻灯片；
先制定全局设计计划（designplan：配色、字体、网格系统、字号规范），建立与主题共鸣的视觉基调（可持续主题用大地色系、学术教程用极简布局）；
把每张幻灯片生成为独立的 HTML 文件（slides/slide_01.html、slide_02.html…），遵循设计计划把文稿内容翻译成视觉元素；
每张幻灯片生成后调用 inspect_slide（渲染成像素图片）观察后渲染缺陷（溢出、重叠、低对比度），用 thinking（模型原生推理）规划针对性修改，然后 edit 修复；
全部完成后 finalize 返回幻灯片目录。

多智能体并行扩展（main.py 中 multiagent_mode）：父智能体可通过 delegate_subagent 本地工具把长文档/多主题调研、>=3 张幻灯片的批量生成并行委派给隔离工作区中的 SubAgent 实例（agents/subagent.py，max_turns=10），结果通过文件 + finalize 回传。论文 Figure 8(a) 的工具使用分析证实了角色分工：Researcher 大量使用 Retrieve 类工具（26.8%），Presenter 大量使用 File（40%）与 Reason（19.3%）类工具。

3.4 环境接地反思（Environment-Grounded Reflection）

这是 DeepPresenter 最核心的方法论创新（论文 Figure 2 对比）：

	自反思（Self-Reflection）	环境接地反思（Env-Grounded Reflection）
触发	不确定性（Uncertain ❓）	`inspect` 工具调用
输入	内部信号（无外部观察）	渲染后的幻灯片图像 / 文稿诊断
缺陷	发现不了后渲染缺陷（溢出、重叠、低对比度、断裂图片）	能发现

实现上是 inspect 工具作为显式的观察接口（deeppresenter/tools/reflect.py）：

inspect_slide(html_file, aspect_ratio)（reflect.py:28-62）：用 Node 管道（html2pptx）校验 HTML 合法性；若 REFLECTIVE_DESIGN（design_agent 是多模态且 heavy_reflect）开启，还用 Playwright 把 HTML 渲染为 PDF→JPEG，以 ImageContent（base64 JPEG）返回给多模态设计智能体，使其真正"看到"渲染后的幻灯片；
inspect_manuscript(md_file)（reflect.py:66-117）：解析 Markdown 文稿，统计页数、用 fastText LID 模型检测语言、校验所有图片引用（标记外链、缺失文件、缺失 alt 文本、重复使用），返回结构化诊断。

由此形成 observe（观察）→ reflect（反思）→ revise（修正） 闭环，观察结果与用户感知一致。

论文中的 think 工具并非一个注册的 MCP 工具，而是通过：

模型原生的 reasoning 字段（ChatMessage.reasoning，agent.py:183-186 保留）；
Agent Harness 本身的 think-act-observe 循环结构实现。

3.5 数据合成与轨迹蒸馏（DeepPresenter-9B）

为了在推理时降低闭源模型的高成本，DeepPresenter 训练了紧凑模型 DeepPresenter-9B。训练管线（论文 Figure 3）三步：

Step 1：任务构建（Query Construction） 从 PersonaHub、arXiv、FinePDFs-Edu 三来源构建 1,152 个任务（1,024 训练 + 128 评测）。每个任务附加可验证约束（页数、语言、宽高比），如：“I’m an English teacher… Please create a 14-slide presentation in 4:3 aspect ratio, with all content in Chinese."（统计见论文 Table 1：中英各半、三来源各半、自由/受限宽高比混合）。

Step 2：验证引导的轨迹合成（Verification-Guided Trajectory Synthesis） 关键问题：自验证偏差（self-verification bias）——智能体在自己产生的轨迹状态内评判自己的输出，验证与自我合理化纠缠，导致有缺陷的输出被接受。解决方案：外在验证（extrinsic verification）——在隔离上下文中产生验证信号。智能体调用 inspect 得到观察 o_t 后，独立的 critic 模型（论文用 Gemini-3-Pro，PPTea-main/sarl/coldstart/process_oversight.py 实现）基于 o_t 与中间产物做验证，输出识别缺陷（如低对比度）并给出可操作修改建议（如调整文字颜色）的推理轨迹，作为 think 调用注入智能体上下文，引导其修正后继续 rollout。论文 Figure 4 显示外在验证在各类缺陷（尤其是版面 layout 308 vs 212、渲染 render 101 vs 43）上检出数量远超自验证，说明自验证系统性漏检。

Step 3：轨迹过滤（Trajectory Filtering） 三级过滤（PPTea-main/sarl/evaluation/ 中的评分 + trajectory_collect.py 的阈值）：

规则验证约束符合度（页数/宽高比/语言）；
用 GLM-4.6 评估一致性，删除未按外在验证轨迹做对齐修改的（反思-动作不一致）轨迹；
用 GLM-4.6V 评估输出质量，过滤有关键缺陷（元素重叠、图片断裂）的轨迹。

最终 802 条轨迹通过过滤，在 GLM-4.6V-Flash 上用 MS-SWIFT 微调（batch 32、lr 1e-5、5 epochs、8×A800 约 80 GPU 小时），得到 DeepPresenter-9B。

论文 Figure 5 展示过滤前的失败分布：质量错误 43.0%（自由式生成难保质量）、环境错误 32.3%（长时程脆弱性：上下文溢出与基础设施故障）、约束违规 13.5%、一致性错误 11.2%。

3.6 实验结果

评测协议：128 个 held-out 任务，四个维度：

维度	方法
Constraint	规则验证：约束满足比例（页数/语言/宽高比），0-5 分
Content & Style	沿用 Zheng et al. (2025) 的 MLLM 评测框架，GPT-5 为 judge，0-5 分
Diversity	DINOv2 特征 + Vendi Score（特征相似矩阵的特征值熵），0-1

主结果（论文 Table 2）：

框架	模型	Constraint	Content	Style	Avg	Diversity
Gamma（商业）	–	4.93	4.08	4.08	4.36	0.52
PPTAgent	Gemini-3-Pro	4.22	3.09	4.30	3.87	0.19
KCTV	Claude-Sonnet-4.5	4.88	2.90	3.99	3.92	0.20
DeepPresenter	Gemini-3-Pro	4.70	4.25	4.37	4.44	0.79
DeepPresenter-9B	微调	4.77	3.52	4.29	4.19	0.53

要点：

DeepPresenter + Gemini-3-Pro 达到 SOTA（4.44），超过商业系统 Gamma（4.36）与所有开源基线；
Content 提升最大：Researcher 做意图自适应检索与综合，而非依赖固定工作流或用户提供材料；
Style 提升来自内容感知设计与环境接地反思；
Diversity 0.79 是模板方法的 2 倍以上（0.17-0.35），自由式生成带来视觉多样性；
DeepPresenter-9B 以 802 条轨迹达到 4.19，超过所有开源基线，接近 GPT-5（4.22）而成本低得多（论文 Figure 6 的帕累托前沿）。

消融（论文 Table 3，Gemini-3-Pro）：

w/o Grounded Reflection：4.44 → 4.32（关闭 inspect 后反思局限在渲染前产物）；
w/o Dual-Agent：4.44 → 4.04（双智能体把长时程执行分解为专业化子任务贡献显著）；
训练策略：w/o Trajectory Filtering 使 DeepPresenter-9B 从 4.19 → 4.03；extrinsic verification 带来比纯微调高 67% 的提升（Table 4：+0.20 vs +0.12）。

人类评估（附录 A.1，2 名研究生评 32 份）：DeepPresenter 4.22 vs PPTAgent 3.46 / KCTV 3.48 / Gamma 4.09，相对排序与自动评测一致。

4. 代码架构总览：两条代码路径

PPTAgent/ （仓库根目录）
├── deeppresenter/ ← 当前主产品面（Agentic 运行时）
│ ├── main.py ← AgentLoop 编排入口
│ ├── agents/ ← 智能体（agent.py 基类 + research/design/pptagent/planner/subagent）
│ ├── tools/ ← MCP 工具服务器（search/any2markdown/reflect/task/tool_agents）
│ ├── roles/ ← 角色定义（Research.yaml/Design.yaml/PPTAgent.yaml/Planner.yaml/SubAgent.yaml）
│ ├── utils/ ← 配置/常量/日志/webview/mineru/mcp_client
│ ├── html2pptx/ ← Node.js HTML→PPTX 转换管道
│ ├── cli/ ← Typer CLI（onboard/generate/serve/config/clean）
│ └── docker/ ← 沙箱 Docker 镜像与本地运行脚本
│
├── pptagent/ ← 旧版核心库（PPTAgent 论文的生成+评测）
│ ├── pptgen.py ← Stage II 生成流水线（PPTGen/PPTAgent）
│ ├── induct.py ← Stage I 版面归纳（SlideInducter）
│ ├── apis.py ← 编辑 API 与 CodeExecutor
│ ├── agent.py ← 通用 LLM 智能体（YAML 角色 + Jinja2）
│ ├── presentation/ ← PPTX 解析/HTML 渲染/Closure 构建
│ ├── document/ ← 文档解析（markdown→Document）
│ ├── ppteval/ ← PPTEval 评测框架
│ ├── roles/ prompts/ ← 角色与提示词模板
│ ├── mcp_server.py ← pptagent-mcp（模板式幻灯片生成 MCP server）
│ └── templates/ ← 预处理的参考模板（beamer/cip/default/hit/thu/ucas）
│
└── PPTea-main/ ← 评测/蒸馏实验基础设施（独立仓库，deeppresenter 是软链接）
└── sarl/
├── evaluation/ ← 各框架生成适配器 + 两阶段评分管线
├── coldstart/ ← SFT 轨迹收集与蒸馏训练
├── dataset/ ← 数据集构建（typings.py 数据模型）
└── analysis/ ← 论文图表（帕累托/工具使用/缺陷分布）

5. Agent Harness 主循环详解

Agent Harness（deeppresenter/agents/agent.py，462 行）是整个 DeepPresenter 的核心：一个通用的 think → act → observe ReAct 式工具调用循环，所有具体智能体（Research/Design/PPTAgent/Planner/SubAgent）都复用这个基类。

5.1 通用智能体基类 Agent

初始化（agent.py:57-136）：

从 roles/<ClassName>.yaml 加载角色配置（RoleConfig）：system prompt（分语言）、Jinja2 instruction 模板、use_model（用哪个 LLM 字段）、ToolSet（包含/排除哪些 MCP server 与工具）；
self.llm = config[role_config.use_model]（research_agent / design_agent / long_context_model）；
记录 context_window（默认 40k = CONTEXT_LENGTH_LIMIT 200k / max_context_folds 5）、max_context_turns（5）、max_turns（可选上限）；
_setup_toolset()（agent.py:138-155）从 agent_env 解析工具列表（"all" 展开为所有已连接 server，再减排除项），生成 OpenAI function-tool 字典列表；
拼接系统提示词：角色 system prompt + AGENT_PROMPT（环境描述与工具调用规则：充分探索、并行工具调用、每轮最多 7 个工具、截断策略）+ MA_RESEACHER_PROMPT/MA_RRESENTER_PROMPT（多智能体委派指南）+ OFFLINE_PROMPT（离线模式）+ CONTEXT_MODE_PROMPT（上下文折叠模式）；
初始化 chat_history = [SYSTEM 消息]。

5.2 action：LLM 思考与工具调用生成

action()（agent.py:191-240）——每一轮循环的 LLM 步骤：

递增 turn_count，执行 max_turns 上限（剩余 <2 轮时注入 “finish now” 提示）；
首次调用时把渲染好的 Jinja2 instruction 作为 USER 消息追加；
调用 self.llm.run(messages=self.chat_history, tools=self.tools) —— OpenAI 原生 function calling；
记录 token 用量到 self.cost 与 self.context_length；
把 assistant 消息（content + tool_calls + 可选的 reasoning）追加到历史并返回。

5.3 execute：工具执行与观察收集

execute()（agent.py:250-348）——每一轮循环的动作步骤：

取出 assistant 消息的 tool_calls，用 JSON schema 校验参数，强制 MAX_TOOLCALL_PER_TURN（默认 7）；
检测特殊工具 finalize：暂存其 outcome 参数与 finish_id，并注入 agent_name；
并行执行所有工具：asyncio.gather(self.agent_env.tool_execute(t)...)（agent.py:292）；
观察归一化：含图片的结果按模型类型格式化（Gemini/Qwen 转 role=USER，Claude 转 image+source.base64）；
观察追加到 chat_history，错误记录到 error_history；
若 finalize 被调用且其观察文本等于 outcome，返回 outcome 字符串（表示循环完成）；
上下文预算告警（agent.py:325-336）：context 超 50% 注入 HALF_BUDGET_NOTICE_MSG，超 80% 注入 URGENT_BUDGET_NOTICE_MSG；
上下文溢出处理（agent.py:341-347）：context_length > context_window 时，若启用折叠则 compact_history()，否则抛 RuntimeError；
返回 outcome 字符串或观察 ChatMessage 列表。

5.4 上下文管理与 compact_history

compact_history()（agent.py:356-401）——防止上下文溢出的核心机制：

保留 keep_head=10 + keep_tail=4 条消息，中间的折叠；
先保存完整历史（message_only=True）；
用 MEMORY_COMPACT_MSG（constants.py:154-184 的详细摘要指令）配合 self.chat_history + [summary_ask] 请求 LLM 总结；
LLM 的摘要消息（可能含 tool_calls）被执行；追加 CONTINUE_MSG（最后折叠时 LAST_ITER_MSG）；
重构历史为 head + tail + [summary_ask, summary_message, *observations]；
受 max_context_turns（5 次折叠）限制。

配套的 _split_history()（agent.py:403-421）保证 tool-call/tool-result 消息配对保持在 head 中，用 HIST_LOST_MSG 标记截断点。

5.5 loop：各智能体的主循环

loop()（agent.py:242-249）是抽象异步生成器，所有具体智能体实现它，但模式相同：

while True:
 agent_message = await self.action(**kwargs) # 思考 + 生成工具调用
 yield agent_message # 流式输出进度
 outcome = await self.execute(self.chat_history[-1].tool_calls) # 行动 + 观察
 if isinstance(outcome, list):
 for item in outcome:
 yield item # 流式输出观察
 else:
 yield outcome
 break # finalize → 循环结束

这是标准的 ReAct 式 harness：action（LLM）→ execute（工具）→ 观察 → 重复直到 finalize。

各具体智能体的 loop：

Research（research.py:8-24）：loop(req, outline_path) 跑通用循环，action 注入 deepresearch prompt + 附件 + 大纲路径；最终 finalize 返回 .md 文稿路径；
Design（design.py:5-20）：loop(req, markdown_file) 创建 slides/ 目录跑循环，while True 收到字符串 outcome 后跳出再 yield 一次（HTML 目录）；逐页 write + inspect_slide + 修复；
PPTAgent（pptagent.py:5-29）：loop(req, markdown_file) 通过 pptagent MCP 工具（list_templates/set_template/create_slide/write_slide/generate_slide）做模板式生成；
Planner（planner.py:8-48）：两阶段生成器——阶段 1 跑循环产出 outline JSON 路径；阶段 2 是交互式修订循环（feedback = yield outcome，CLI 通过 .asend(feedback) 推送修订指令，非空则追加为 USER 消息重新跑循环）；
SubAgent（subagent.py:46-51）：通用循环，从 Context 文件读委派任务，产出 deliverable 文件后 finalize。

6. Agent Harness 框架架构：模块与角色

6.1 编排层 AgentLoop（main.py）

deeppresenter/main.py（233 行）是顶层编排入口，AgentLoop.run() 是 async generator，逐步 yield 进度 ChatMessage 与最终产物路径。管线如下：

AgentLoop.run()
├── 1. 设置阶段（main.py:58-84）
│ ├── 可选校验 LLM
│ ├── 附件复制到 workspace/attachments/（request.copy_to_workspace）
│ ├── 写入 .input_request.json
│ ├── 打开 AgentEnv 异步上下文
│ └── [multiagent_mode] 注册 delegate_subagent 本地工具
│
├── 2. 可选 Planner 阶段（main.py:87-110）
│ └── planner.loop(request) → outline JSON（可交互修订）
│
├── 3. Research 阶段（main.py:112-139）
│ └── research_agent.loop(request, outline_path) → manuscript.md
│
├── 4. 生成阶段，按 convert_type 分支（main.py:141-221）
│ ├── PPTAGENT：PPTAgent.loop(request, md_file) → .pptx
│ └── DEEPPRESENTER：Design.loop(request, md_file) → slides/*.html
│ └── 导出：convert_html_to_pptx()（Node html2pptx）
│ └── 失败回退：PlaywrightConverter.convert_to_pdf → .pdf
│
└── 5. 收尾（main.py:222-224）
└── save_results() 写 intermediate_output.json（outline/manuscript/pptx/final 路径）

每个子阶段都 save_history() / save_results()（在 finally 中），日志写到 workspace/.history/deeppresenter-loop.log。

6.2 环境层 AgentEnv 与工具执行（env.py）

deeppresenter/agents/env.py（454 行）管理 MCP server、工具注册、沙箱与异步工具执行：

__init__（env.py:54-109）：加载 mcp.json 的 MCPServer 定义（离线模式跳过 network server），计算 docker-in-docker 的 HOST_WORKSPACE 卷映射，构建 envs 字典（WORKSPACE/HOST_WORKSPACE/WORKSPACE_ID/CONFIG_FILE/PACKAGE_DIR…）传给 MCPClient，避免全局环境变量污染；注册工具注册表（_local_tools/_tools_dict/_server_tools/_tool_to_server）；async_tool_mode 开启时注册 gather 工具；
__aenter__（env.py:228-266）：清理同名陈旧 docker 容器，并行连接所有 MCP server，缓存全部工具规格到 .tools.json；
__aexit__（env.py:268-300）：断开 server，写 tool_history.jsonl 与 tools_time_cost.json（工具调用的完整审计日志）；
register_tool（env.py:347-372）：把 Python 可调用对象注册为本地工具（用 FastMCP 的 typeadapter 从类型注解自动生成 JSON schema），用于 delegate_subagent 与 gather；
tool_execute（env.py:111-226）：统一工具执行路径——jsonschema 校验参数 → _execute_tool → 包装成 ChatMessage(role=TOOL)。结果截断（env.py:186-203）：文本超 TOOL_CUTOFF_LEN（4096 字符）在最后一个换行截断并附 CUTOFF_WARNING，全文保存到本地文件供 read_file 按偏移读取；图片结果转 image_url 块。记录每个工具耗时/成功/失败；
_execute_tool（env.py:403-423）异步工具模式：非白名单工具（gather/finalize/inspect_slide 除外）限时 5 秒，超时返回占位符并后台继续，智能体之后用 gather 收集结果——这允许智能体并行执行多个长时程任务。

工具调用路径：LLM 原生 function calling → Agent.execute → agent_env.tool_execute → 本地 Python 可调用或 MCPClient.session.call_tool（utils/mcp_client.py，stdio/SSE 子进程连接，MCP_CALL_TIMEOUT 默认 1800 秒）。

6.3 MCP 工具服务器（tools/）

每个文件是独立的 FastMCP server（按 mcp.json 以子进程启动），提供以下工具：

Server	类别	工具	说明
`Search`（`search.py`）	Retrieve	`search_web` / `search_images` / `fetch_url` / `download_file`	SerpAPI 优先、Tavily 备选；Playwright 渲染网页 + trafilatura/markdownify 提取；图片下载校验（WEBP→PNG）
`Any2Markdown`（`any2markdown.py`）	File	`convert_to_markdown`	PDF/DOCX 转 Markdown：MinerU（在线 API 或离线部署）或 MarkItDown；base64 图片落盘、链接改绝对路径、报告图片尺寸
`DeepPresenter`（`reflect.py`）	Reason	`inspect_slide` / `inspect_manuscript`	环境接地反思的两个观察接口（见 3.4 节）
`Task`（`task.py`）	Control	`finalize`	循环终止工具，按智能体类型做最终校验（Planner 要 .json；Research 要 .md 并重写图片绝对路径+注入宽高比到 alt；PPTAgent 要有效 .pptx；Design 要 slide_*.html 目录）
`ToolAgents`（`tool_agents.py`）	Create/Reason	`image_generation` / `image_caption` / `document_summary`	条件注册：配置了 t2i_model 才提供文生图；vision_model 提供图片分类+描述（Table/Chart/Logo + <50 词）；multiagent 模式提供长文档摘要
`pptagent`（`pptagent/mcp_server.py`）	模板生成	`list_templates` / `set_template` / `create_slide` / `write_slide` / `generate_slide` / `markdown_table_to_image` / `save_generated_slides`	旧版模板式生成，仅供 PPTAgent 智能体
`sandbox`（`docker/server.ts`）	File	`read_file` / `write_file` / `move_file` / `edit_file` / `create_directory` / `list_directory` / `execute_command`	DesktopCommanderMCP 沙箱（Docker 或本地 Node 进程），`execute_command` 使智能体成为"沙箱化代码智能体”（可跑 shell/python/node/渲染 mermaid），`docker/config.json` 屏蔽危险命令（format/mkfs/dd/useradd…）

工具按论文 Table 8 分为五类：Retrieve（信息获取）、File（文档操作）、Reason（检查与反思）、Control（任务管理）、Create（代码执行与资产生成）。

6.4 角色定义（roles/）

每个角色是一个 YAML，定义 system prompt（中英）、Jinja2 instruction 模板、use_model 与 toolset：

角色文件	智能体	模型	工具集亮点	指令要点
`Research.yaml`	Research	research_agent	除 pptagent 外所有 server；排除 inspect_slide	深度调研（广→窄）、信息美学、Markdown 文稿（`---` 分页、图片本地化）、inspect_manuscript、finalize 返回 .md
`Design.yaml`	Design	design_agent（多模态）	sandbox + delegate_subagent + inspect_slide + finalize	HTML/CSS 固定版式设计、global.css、逐页生成 + inspect_slide 质量检查、按宽高比固定 body 尺寸
`PPTAgent.yaml`	PPTAgent	research_agent	pptagent + sandbox + finalize	从 Markdown 做模板式生成、表格转图片、finalize 返回 .pptx
`Planner.yaml`	Planner	research_agent	除 tool_agents/deeppresenter 外所有；排除 search_images	设计 JSON 大纲 `{"slides":[{index,title,context}]}`、finalize 返回 .json
`SubAgent.yaml`	SubAgent	design_agent	除 pptagent 外所有；排除 delegate_subagent（禁递归）	从 Context 文件完成单个委派子任务、产出自包含 deliverable、finalize

附加动态提示词片段（utils/constants.py）：AGENT_PROMPT（环境描述+工具调用规则）、MA_RESEACHER_PROMPT/MA_RRESENTER_PROMPT（多智能体并行委派指南）、OFFLINE_PROMPT、CONTEXT_MODE_PROMPT、上下文预算告警与 MEMORY_COMPACT_MSG。

6.5 配置与常量（utils/）

utils/config.py：Endpoint（单端点，路由 litellm 或 AsyncOpenAI，支持 tool-calling/结构化输出/纯对话）、LLM（多端点交替重试 + 并发信号量 + 多模态自动检测 + generate_image + validate()）、DeepPresenterConfig（multiagent_mode/offline_mode/async_tool_mode/context_folding/context_window/max_context_folds/heavy_reflect + 三个 LLM 字段）；
utils/typings.py：Role（SYSTEM/USER/ASSISTANT/TOOL）、ChatMessage（统一消息模型，content 归一为 {type:text/image_url} 块列表）、ToolSet/RoleConfig、Cost、ConvertType（DEEPPRESENTER/PPTAGENT）、PowerPointType（16:9/4:3/A1-A4）、InputRequest（instruction/attachments/num_pages/template/powerpoint_type/convert_type/enable_planner/extra_info，copy_to_workspace 复制附件）；
utils/constants.py：全部可调常量（WORKSPACE_BASE、TOOL_CUTOFF_LEN=4096、MAX_TOOLCALL_PER_TURN=7、MAX_SUBAGENT_TURNS=10、CONTEXT_LENGTH_LIMIT=200k、MCP_CALL_TIMEOUT=1800s、PIXEL_MULTIPLE=16）；
utils/webview.py：PlaywrightConverter（共享 headless Chromium，HTML→按宽高比分页 PDF→pdf2image 栅格化为 slide_NN.jpg）与 convert_html_to_pptx（调 Node html2pptx_cli.js）；
utils/mineru_api.py：MinerU PDF 解析（在线 mineru.net API 或离线自部署端点）。

6.6 沙箱与 HTML→PPTX 转换

沙箱：DesktopCommanderMCP 的 Docker 镜像（docker/SandBox.Dockerfile）或集群本地模式（run_sandbox_local.sh，SLURM 无 Docker 环境下用本地 Node 进程），提供通用代码执行能力；
HTML→PPTX（html2pptx/）：Node CLI 用 pptxgenjs + 自定义 html2pptx.js 转换器，支持 16:9/4:3/A1-A4 布局、--validate/--soft 选项，依赖 playwright 与 sharp；
配置示例：config.yaml.example（LLM 块 + 模式开关）、mcp.json.example（7 个 MCP server，$VAR 占位符由 MCPServer._process_escape 从 AgentEnv.envs 解析）。

6.7 完整端到端流程图

pptagent generate "主题" -f 附件.pdf --planner
└─ CLI commands.generate → AgentLoop(config, request)
└─ AgentLoop.run()
├─ AgentEnv.__aenter__：并行连接 7 个 MCP server，缓存工具规格
├─ [enable_planner] Planner.loop：action/execute 循环 → outline.json → finalize
│ └─ CLI 交互式修订（_edit_outline：Rich 表格展示，y 批准或自然语言修订）
├─ Research.loop：action → [search_web, fetch_url, convert_to_markdown,
│ image_generation...] → execute（并行、4096 字符截断）→ 观察
│ → inspect_manuscript → finalize(manuscript.md)
│ [context >40k 触发 compact_history 摘要折叠]
├─ convert_type 分支：
│ ├─ PPTAGENT：PPTAgent.loop → list_templates → set_template
│ │ → create_slide → write_slide → generate_slide → finalize(.pptx)
│ └─ DEEPPRESENTER：Design.loop
│ → read manuscript → write global.css
│ → [逐页] write slide_NN.html → inspect_slide（渲染+校验；
│ heavy_reflect 时多模态智能体"看到"渲染 JPEG 并修复）
│ → finalize(slides/) [多智能体：delegate_subagent 并行生成]
└─ 导出：convert_html_to_pptx(slides/, out.pptx, 宽高比, soft)
└─ node html2pptx_cli.js → pptxgenjs → .pptx
[失败回退：PlaywrightConverter.convert_to_pdf → .pdf]

7. PPTea-main：评测与蒸馏实验基础设施

7.1 PPTea-main 是什么

PPTea-main 不是独立产品，而是 DeepPresenter 项目的实验/评测/蒸馏基础设施：

deeppresenter/ 是指向 ../PPTAgent/deeppresenter 的软链接；
sarl/ 包（0.1.0，docstring “SARL Package”）大量 import deeppresenter.* 与 pptagent.*；
它实现了 project-demand.md 描述的完整闭环：各 Agent Harness 生成 → Workspace 对齐 → PPTEval 评分 → 分析 → 轨迹蒸馏。

7.2 评测流程（两阶段评分管线）

PPTea-main/sarl/evaluation/ 提供各竞争框架的生成适配器：

文件	框架	机制
`deeppresenter_gen.py`	DeepPresenter	调 `deeppresenter.main.AgentLoop.run()`，写 `.datapoint.json` 后立即 `score_workspace()`
`codex_gen.py`	Codex CLI（GPT-5）	`codex exec --sandbox danger-full-access` + `pptx-generator` Skill（`../Deeppresenter-skills/skills/pptx-generator`），`verify_workspace_ready()` 校验 PPTea 兼容别名
`pptagent_gen.py`	PPTAgent（旧基线）	包装 `pptagent.pptgen.PPTAgent`，模板归纳生成，soffice 转 PDF
`gamma.py`	Gamma（商业）	Gamma 公开 REST API，轮询完成后下载 PDF
`kctv.py`	KCTV（基线）	两步 LLM：提取结构化 JSON → LaTeX，xelatex 渲染 PDF

Phase 1 —— Content & Style 评分（score_exp.py → score_workspace()）：

读 .datapoint.json 与 intermediate_output.json 找最终 PDF；
定位幻灯片图片目录 .slide_images-pdf-{stem}/slide_XX.jpg（所有框架的评测输入统一归一化为这个格式）；
校验 PPTea 文稿别名 .slides.md（必须等于 manuscript.md）；
确定性约束检查：dp.verify() 用 PyPDF 查页数、mediabox 查宽高比、fasttext LID 查语言 → 0-1 分 ×5；
逐页 VLM 评分（8 并发，GPT-5 多模态 judge）：
- content_descriptor 描述内容 → text_scorer 打 Content 分；
- style_descriptor 描述风格 → vision_scorer 打 Style 分；
写 slide_evals.json（逐页）与 evals.json（平均：constraint/content/style）。

Phase 2 —— 约束 VLM 评测（score_exp_complex.py → score_workspace_constraints()）：

仅对通过 Phase 1 阈值的 workspace 运行（默认 min_content=3.5 / min_style=3.5 / min_constraint=1.0）；
对 DataPoint 中的每个 Constraint（STYLE 类评估所有页，其余评估指定页），用 prompt/judge_constraints.txt VLM judge 判定 satisfied(1.0)/partially(0.5)/not(0.0)；
写 constraint_evals.json，更新 evals.json 的 constraint_vlm。

辅助评测设施：

divesity.py：DINOv2 特征 + Vendi Score 的幻灯片风格多样性指标（0-1）；
plot_score_dist.py：分数分布直方图（确定过滤阈值）；
review_server.py：FastAPI 人工审核面板（8080 端口，缩略图+分数网格、逐 workspace 审核、reasonable/partially/unreasonable 三档判定）；
finish_codex_benchmark.py：Codex workspace 的确定性终结器（校验语义产物存在、重跑 pptxgen html validate/render + convert + package，验证 PPTea 别名；明确拒绝合成内容，只做确定性渲染/转换/打包）。

7.3 数据模型与 Workspace 对齐

核心数据模型（sarl/dataset/typings.py）：

DataPoint: # 一个评测任务
 prompt: str # 用户指令
 language: "zh"|"en"
 source: "arXiv"|"finepdfs"|"personahub"|...
 aspect_ratio: PowerPointType # 16:9 | 4:3 | A1
 page_low, page_high: int # 页数约束
 attachments: list[str] # 附件路径
 constraints: list[Constraint] # 结构约束（STYLE/COVER/AGENDA/VISUAL_CHART/...）
 task_id: str # md5(prompt+attachments)[:8]

Workspace 对齐协议（所有框架必须产出）：

workspace/{task_id}/
.datapoint.json # 输入任务
.slides.md # == manuscript.md（PPTea 文稿别名）
manuscript.md # 完整幻灯片文稿
slide_manifest.json # 幻灯片结构清单
design-system.json # 品牌/排版配置
slides/global.css + slide_01.html... # HTML 幻灯片源码
renders/html/ slide_01.png + renders/pptx/ slide_01.png # 渲染截图
.slide_images-pdf-{stem}/slide_XX.jpg # 评测图片（评分唯一输入）
delivery/ presentation.pptx + presentation.pdf + source.zip # 最终交付
intermediate_output.json / run.json / qa/ / evals.json / slide_evals.json / constraint_evals.json

7.4 轨迹蒸馏与冷启动

sarl/coldstart/ 实现 SFT 蒸馏管线（把大模型 DeepPresenter 蒸馏为 Qwen3-VL-4B）：

trajectory_collect.py：把完成的 DeepPresenter workspace 转成 SFT 轨迹，应用质量过滤（constraint==1.0, content>=3.9, style>=3.9, constraint_vlm>=0.65），过滤重复输出、消息去重、注入合成 thinking 工具，导出 data/stage1/trajectories_*.json——评测分数闭环回到训练数据筛选；
coldstart.sh：Megatron SFT 训练 Qwen3-VL-4B-Instruct（4 GPU、TP=4、56K 上下文、3 epochs、lr 1e-5）；
process_oversight.py：外在验证/过程监督——VLM critic（vl_oversight）审查 Design Agent 的 HTML 幻灯片的版面/渲染/风格问题（severity 0-3）+ agent_watch 幻觉检测 + critic_follow 计划遵循检查（论文 3.2 节 extrinsic verification 的实现）；
sarl/analysis/efficiency.py：成本-性能帕累托图（论文 Figure 6 数据）。

8. 与直接让 CodeX 生成 PPT 的对比

8.1 直接 CodeX 方式的做法

“直接让 CodeX 生成 PPT，给他参考图附件"的做法是：把任务提示 + 参考图片作为附件给 CodeX，让它用通用编码能力（python-pptx / html / marp 等）直接写代码生成 PPTX。在我们的评测中，对应 codex_gen.py：codex exec --sandbox danger-full-access + pptx-generator Skill（把 DeepPresenter 流程蒸馏为 Codex 可用的 Skill 文档 + 确定性脚本）。

8.2 本质区别一：Research 与 Design 的解耦

DeepPresenter：两个专职智能体、两段轨迹、一个共享文件系统。

Researcher 用意图自适应策略做多步检索综合（web/图片/论文/附件解析），产出结构化文稿 M（页面/主题/证据/资产绑定）；
Presenter 在独立轨迹中基于 M 做内容驱动的视觉设计，每页 inspect 修复。

直接 CodeX：单一 agent 用统一上下文同时承担调研与设计。问题：

调研深度受上下文窗口限制，长文档/多主题调研容易浅尝辄止；
“调研"与"设计"互相抢占 token 预算，设计阶段上下文已接近极限（对应 DeepPresenter 论文统计的 32.3% 环境错误：上下文溢出）；
附件证据使用浅层：实测（experiment-codex-vs-deeppresenter-finalcheck-20260813.md）中 Codex 对 14 页试卷附件只做"题目级裁剪+通用标题+两条短要点”，而 DeepPresenter 把 955 行 Markdown 解析成概念级教学图（station model、seismogram S-P timing、subduction quakes…），3-4 条因果要点 + 与论点直接绑定的可读图。

8.3 本质区别二：环境接地反思 vs 内省反思

DeepPresenter 的 inspect_slide 把 HTML 渲染成像素图交给多模态智能体"亲眼看”，inspect_manuscript 给结构化诊断（页数/语言/资源缺失）。反思条件是渲染后的感知状态，与用户看到的一致，能发现：

后渲染缺陷（元素溢出、重叠、低对比度、断裂图片）；
图片路径前缀缺失（论文 Figure 2 例子：“fig1.jpg” missing “images/” prefix）。

直接 CodeX 的反思大多是内省式的：看自己的代码和中间文本（HTML/代码），“我觉得没问题”。问题：

自验证偏差（self-verification bias）：在自己的轨迹状态内评判自己的输出；
代码级合法（HTML 语法正确、布局坐标在界内）≠ 渲染级正确（溢出/重叠/可读性）；
实测中 Codex 的 QA 检查聚焦路径/可读性/转换成功，抓不到核心内容失败：“这个视觉真的支撑了本页论点吗？”

8.4 本质区别三：受控工具生态 vs 通用编码环境

DeepPresenter 提供 5 类 20+ 个受控 MCP 工具：

Retrieve（search_web/images/papers、fetch_url、document_analyze、image_caption）；
File（convert_to_markdown、read/write/move/edit/download_file、execute_command、目录管理）；
Reason（thinking、inspect_slide、inspect_manuscript）；
Control（todo_create/update/list、finalize）；
Create（image_generation）。

工具的语义边界明确（如 search_web 封装了检索+结果归一化）、有校验（finalize 按角色校验产物、download_file 校验图片格式与路径、工具输出 4096 字符截断+全文落盘）、有审计（tool_history.jsonl、tools_time_cost.json）、有沙箱（危险命令黑名单）。

直接 CodeX 只有一个通用 sandbox + 文件系统 + shell。能力等价但缺少：

语义化的检索工具（检索质量依赖模型自己拼 URL/API）；
专门的渲染观察接口（没有 inspect，只能靠写脚本截图再读，或干脆不检查）；
按角色约束的终止校验（finalize 的产物类型验证）；
上下文管理（工具截断、压缩折叠、预算告警）。

8.5 本质区别四：评测闭环

PPTAgent/DeepPresenter 自带评测框架（PPTEval / Constraint+Content+Style+Diversity），评测分数驱动实验迭代；
本项目的蒸馏管线（trajectory_collect.py）把评测分数作为 SFT 轨迹过滤阈值（constraint==1.0、content>=3.9、style>=3.9、constraint_vlm>=0.65），形成"评测→过滤→训练→再评测"闭环；
Codex 方式是通用 agent，没有与演示文稿语义绑定的评测反馈回路。

8.6 实测对比数据

12 样本实测（codex-skill-ppt-additional-analysis*.md）：

维度	Codex+Skill	DeepPresenter	差距
Content	2.62	4.33	主要差距（受众改写、证据选择、有意义的视觉）
Style	3.96	4.45	较小（页数/渲染/基本布局已不是瓶颈）

单样本细看（07bbf73b，14 页附件 deck）：

Codex 逐页 Content：4,3,3,2,2,3,2,2,2,2,2,2,2,3——中段大面积 2/5 塌陷；
DeepPresenter 逐页 Content：3,3,3,3,3,4,5,5,5,4,5,5,4,3——多数页 4-5/5；
Codex 页级样式 Style 4.0（结构有效、视觉一致），但"每页一个 PDF 裁剪图 + 通用证据标题 + 两条短要点”，视觉被评价为"小、难读、与页主题弱相关甚至离题”；
单页 A1 海报任务（c5cae881）两者打平（4.0/4.0/1.0）——因为单页合成任务无多页证据路由问题，Skill 足以匹配。

结论：直接 CodeX（即使配上 Skill）在"多页、附件密集、需要把附件内容转成教学产物"的任务上，与 DeepPresenter 的核心差距在语义内容质量（证据提取、论点-证据绑定、视觉信息增益），而非确定性约束或转换稳定性。

9. 从论文到代码的对应关系速查表

论文概念	代码位置
PPTAgent Stage I 幻灯片分类	`pptagent/induct.py:95-110`（category_split，`prompts/category_split.txt`）
PPTAgent Stage I 版面聚类	`pptagent/induct.py:112-151` + `model_utils.py:291-345`（get_cluster，sim_bound=0.65）
PPTAgent Stage I Schema 提取	`pptagent/induct.py:175-208`（content_induct）+ `presentation/layout.py`（Element/Layout）
PPTAgent Stage II 大纲生成	`pptagent/pptgen.py:239-318`（generate_outline + _add_functional_layouts）
PPTAgent Stage II 版面选择/内容生成	`pptgen.py:434-467` / `469-491`（_select_layout / _generate_content）
编辑 API	`pptagent/apis.py`（replace_paragraph/replace_image/del_paragraph/del_image/clone_paragraph）
自校正 REPL	`pptgen.py:493-529`（_edit_slide）+ `apis.py:127-203`（execute_actions）
HTML 渲染（CodeRender）	`pptagent/presentation/presentation.py:193-216`（SlidePage.to_html）+ `shapes.py`
Closure 延迟构建	`pptagent/presentation/shapes.py:218-246`（Closure）+ `presentation.py:122-144`（build）
PPTEval	`pptagent/ppteval/ppteval.py` + `prompts/ppteval/*.txt`（三维度 prompt）
多样性指标	`pptagent/ppteval/divesity.py`（Vendi Score）+ `sarl/evaluation/divesity.py`
Agent Harness 主循环	`deeppresenter/agents/agent.py`（action:191-240 / execute:250-348 / compact_history:356-401 / loop:242-249）
AgentLoop 编排	`deeppresenter/main.py:43-224`（run）
AgentEnv 与工具执行	`deeppresenter/agents/env.py`（tool_execute:111-226 / register_tool:347-372）
MCP 客户端	`deeppresenter/utils/mcp_client.py`
inspect_slide / inspect_manuscript	`deeppresenter/tools/reflect.py:28-62 / 66-117`
finalize 终止校验	`deeppresenter/tools/task.py:58-111`
角色定义	`deeppresenter/roles/*.yaml` + `utils/constants.py`（动态提示词片段）
上下文折叠	`agent.py:356-401`（compact_history）+ `constants.py:154-184`（MEMORY_COMPACT_MSG）
多智能体并行	`deeppresenter/agents/subagent.py`（delegate_subagent）+ `main.py:74-78`
HTML→PPTX	`deeppresenter/utils/webview.py:169-233` + `html2pptx/html2pptx_cli.js`
沙箱	`deeppresenter/docker/server.ts`（DesktopCommanderMCP）+ `run_sandbox_local.sh`
外在验证（extrinsic verification）	`PPTea-main/sarl/coldstart/process_oversight.py`（vl_oversight/agent_watch/critic_follow）
轨迹过滤/蒸馏	`sarl/coldstart/trajectory_collect.py` + `coldstart.sh`（Qwen3-VL-4B SFT）
评测两阶段管线	`sarl/evaluation/score_exp.py`（Phase 1）+ `score_exp_complex.py`（Phase 2）
约束验证	`sarl/dataset/typings.py`（DataPoint.verify）+ `prompt/judge_constraints.txt`
人工审核	`sarl/evaluation/review_server.py`（FastAPI）
Codex 基线	`sarl/evaluation/codex_gen.py` + `../Deeppresenter-skills/skills/pptx-generator`

10. 总结与启示

两代系统的演进主线：PPTAgent（2025）证明"编辑式生成 + 参考模板"能大幅超越纯摘要式生成，但受限于依赖参考演示文稿与固定工作流；DeepPresenter（2026）转向"双智能体 + 自由式生成 + 环境接地反思"，把生成从"模板填充"解放为"内容驱动的自主设计与修正"，并进一步用外在验证合成轨迹蒸馏出 9B 小模型。
Agent Harness 的本质：一个带上下文管理的 think-act-observe 工具调用循环（Agent.action → execute → 观察 → 直到 finalize），配上角色化提示词、MCP 工具生态、沙箱执行、上下文折叠、多智能体委派，就构成了 DeepPresenter 的通用智能体框架——这套框架不限于 PPT 生成，可复用于任意"长时程、工具密集、需要迭代反思"的任务。
与直接 CodeX 的差距不在"有没有 agent"，而在"agent 的观察与反思是否接地"：DeepPresenter 的 inspect 让智能体"亲眼看到"渲染产物，Researcher/Presenter 解耦让每段轨迹专注且上下文充足，受控工具 + finalize 校验让长时程执行可审计。这些正是直接 CodeX（哪怕配上 Skill）难以在通用环境中复现的。
对本项目的意义（project-demand.md）：把 DeepPresenter/PPTAgent 流程蒸馏为 pptx-generator Skill 供 Codex/CC 使用，本质上是在"通用 Agent Harness（Codex）“里重建 DeepPresenter 的关键机制：Workspace 对齐（.slides.md/.slide_images-pdf-* 归一化）、确定性管道（research/html/qa/convert/package）、评测对齐（pptx-evaluator + GPT-5）。实测表明机械对齐已达标（页数/渲染/打包），剩余差距集中在附件语义化与证据绑定——这正是 DeepPresenter 论文里 Researcher 环节（意图自适应检索 + 结构化文稿）与"证据有信息增益"评估准则的体现，也是下一步迭代（topic map、证据绑定 QA、对象级 PDF 裁剪）应聚焦的方向。

Use scp tool

wzh — Mon, 23 Dec 2024 00:00:00 +0000

Today I have to do the task to transfer the prepared data from one server to another. And I find that we can use the tool scp to transfer files between two different host or between server and local computer.

scp -r path/to/local usernameToObject@ObjectIp:ObjectPathToSave #recursively transfer files in the dir

#Some other command
scp file user@host:/path/to/file # copying a file to the remote system using scp command
scp user@host:/path/to/file /local/path/to/file # copying a file from the remote system using scp command

scp <options> source_path destination_path # if we just want to transfer files in the

-r # transfer directory 
-v # see the transfer details
-C # copy files with compression
-l 800 # limit bandwidth with 800
-p # preserving the original attributes of the copied files
-P # connection port
-q # hidden the output

Gkxx__的 .vscode

wzh — Fri, 23 Aug 2024 00:00:00 +0000

翻到已经结课的cs100，Update一下gkxx__的配置文件

~~你们已经长大了，应该学着自己写configure files了~~

All in .vscode

c_cpp_properties.json:

{
 "configurations": [
 {
 "name": "Win32",
 "compilerPath": "Your_Path\\mingw64\\bin\\gcc.exe",
 "cStandard": "c17",
 "cppStandard": "c++17",
 "intelliSenseMode": "windows-gcc-x64",
 "compilerArgs": [
 "-Wall",
 "-Wpedantic",
 "-Wextra"
 ]
 }
 ],
 "version": 4
}

settings.json:

{
 "files.associations": {
 "*.go": "go",
 "iostream": "cpp",
 "array": "cpp",
 "deque": "cpp",
 "string": "cpp",
 "unordered_map": "cpp",
 "vector": "cpp",
 "string_view": "cpp",
 "initializer_list": "cpp",
 "stdexcept": "cpp",
 "iosfwd": "cpp",
 "atomic": "cpp",
 "bit": "cpp",
 "*.tcc": "cpp",
 "cctype": "cpp",
 "clocale": "cpp",
 "cmath": "cpp",
 "compare": "cpp",
 "concepts": "cpp",
 "cstdarg": "cpp",
 "cstddef": "cpp",
 "cstdint": "cpp",
 "cstdio": "cpp",
 "cstdlib": "cpp",
 "cwchar": "cpp",
 "cwctype": "cpp",
 "exception": "cpp",
 "algorithm": "cpp",
 "functional": "cpp",
 "iterator": "cpp",
 "memory": "cpp",
 "memory_resource": "cpp",
 "numeric": "cpp",
 "optional": "cpp",
 "random": "cpp",
 "system_error": "cpp",
 "tuple": "cpp",
 "type_traits": "cpp",
 "utility": "cpp",
 "istream": "cpp",
 "limits": "cpp",
 "new": "cpp",
 "numbers": "cpp",
 "ostream": "cpp",
 "streambuf": "cpp",
 "typeinfo": "cpp",
 "stdbool.h": "c",
 "map": "cpp",
 "set": "cpp"
 }
}

tasks.json:

{
 "tasks": [
 {
 "type": "cppbuild",
 "label": "C/C++: gcc.exe 生成活动文件",
 "command": "Your_Path\\mingw64\\bin\\gcc.exe",
 "args": [
 "-fdiagnostics-color=always",
 "-g",
 "${file}",
 "-o",
 "${fileDirname}\\${fileBasenameNoExtension}.exe"
 ],
 "options": {
 "cwd": "${fileDirname}"
 },
 "problemMatcher": [
 "$gcc"
 ],
 "group": {
 "kind": "build",
 "isDefault": true
 },
 "detail": "调试器生成的任务。"
 }
 ],
 "version": "2.0.0"
}

由一个 docker search 产生的连锁反应

wzh — Thu, 22 Aug 2024 00:00:00 +0000

有时候菜的想发颠。

网络问题总是层出不穷，dns解析不了，docker无法拉取镜像源…

莫名其妙的改了VMware的虚拟网络设置和Ubuntu的Ip&DNS。结果一顿操作给干连不了网了，docker search <> 显示：

Error response from daemon: Get "https://index.docker.io/v1/search?q=nginx&n=25": dial tcp: lookup index.docker.io on 8.8.4.4:53: read udp 192.168.1.11:37017->8.8.4.4:53: i/o timeout

查询后发现需要配置镜像源：

vim /etc/docker/darmon.json
{
"registry-mirrors":[
"..."
]
}
# 重启一下
systemctl daemon-reloa
systemctl restart docker

经配置镜像源后问题似乎得到了…似乎产生了新的问题。 ping bing.com 显示ping: bing.com: Temporary failure in name resolution，经过查询是DNS解析问题，先通过vim /etc/resolv.conf配置了两个DNS：

nameserver 8.8.8.8
nameserver 8.8.4.4

嘿，结果不行。由于昨夜头脑比较混乱，第二天打开虚拟网络设置->for i in all network: delete->应用->还原默认设置->重新配置虚拟机的网络为"桥接"，参考stackoverflow，将answer中的DNS部分替换为上面的dns，结果成功ping成功，并且成功search到docker镜像，但是问题就像趵突泉的泉水一样，一直涌现，在docker pull <>拉取镜像的时候又提示超时：

error pulling image configuration: download failed after attempts=6: dial tcp <...>

这是为什么呢？明明可以search 却不能pull??能search说明是能够连接到docker hub的，但是pull的时候超时又说明访问有问题，经过排查后，借鉴这篇博客后，发现最终还是镜像源问题，更改镜像源后问题解决。

Use zsh terminal

wzh — Sun, 11 Aug 2024 00:00:00 +0000

One day I find that the terminal style between mine and other’s are different and I wonder how they do that, so, then I find zsh

Install zsh

sudo apt install zsh
#使用镜像源安装oh-my-zsh
sh -c "$(curl -fsSL https://gitee.com/mirrors/oh-my-zsh/raw/master/tools/install.sh)"
#编辑theme主题
vim ~/.zshrc
# ZSH_THEME="powerlevel10k/powerlevel10k"

We may also need to config windows terminal’s filesettings.json