Agent Lightning Trainer 配置详解：verl 融合、Rollout 执行与 Trace 聚合调优

Agent Lightning Trainer 配置详解：verl 融合、Rollout 执行与 Trace 聚合调优

【免费下载链接】agent-lightningThe absolute trainer to light up AI agents.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-lightning

本篇指南系统讲解 Agent Lightning v1.0 的 Trainer 层配置：它如何叠加在verl的ppo_trainerHydra 配置之上、如何连接 API Gateway、如何以 local/K8s 两种模式驱动 Rollout 执行，以及 Trace Aggregator 如何把多轮 Agent 调用装配成训练样本。读完后，你可以完整复现训练入口的配置文件，理解每个agentlightning.*参数在源码中的实际生效路径，并根据任务特性在trajectory/transition两种聚合模式与 PPO 更新上限之间做出正确取舍。

完整默认配置

Agent Lightning v1.0 的配置是在verl的ppo_trainerHydra 配置之上叠加的。Hydra 入口定义在 config.yaml 中：通过hydra.searchpath引入pkg://verl/trainer/config，并在defaults中先加载上游ppo_trainer，再加载_self_，实现“上游全量可用 + Agent Lightning 增量覆盖”的合并策略。Agent Lightning 新增的完整默认配置如下：

algorithm: enable_rollout_level_advantage: true agentlightning: agl_base_url: http://localhost:8080 agl_key: "" hooks: null rollout_timeout_seconds: 1800 local: agent_class: null env_map: {} k8s: job_template_path: null reward_fillna_value: 0.0 max_ppo_update_times: null trace_aggregator: level: trajectory # transition | trajectory trajectory_max_prompt_length: 2048 trajectory_max_response_length: 8192 async_rollout: enabled: false async_train_batch_size: null actor_rollout_ref: actor: policy_loss: loss_mode: per_rollout_mean

运行时，上述配置与verl原始的ppo_trainer配置合并，上游已有选项保持可用并按常规生效。此外，实际的 config.yaml 还包含文档摘录之外的一组默认值，一并说明如下：

• data.filter_overlong_prompts: false：加载训练数据时不预先过滤超长 prompt，超长样本的处置交给后文的 Trace Aggregator（标记丢弃或截断）；
• actor_rollout_ref.actor.calculate_entropy: true：Actor 前向时计算熵，便于监控策略探索性；
• actor_rollout_ref.rollout.mode: async：rollout 服务器以异步模式运行，与训练器通过 API Gateway 协作。

连接 API Gateway

第一组配置用于把训练器接入 Agent Lightning API Gateway：

请确保运行训练器的机器能够访问agentlightning.agl_base_url指定的 Gateway；agl_key必须在训练器、API Gateway 和 Controller 三方配置中完全一致。

从源码看，该连接由 trainer.py 中的_ensure_agl_client惰性建立：它用agl_base_url、agl_key和 300 秒超时构造AgentLightningSyncClient，并在每个训练步骤调用 Gateway 的/proxy/pause、/proxy/state、/proxy/resume等接口协调推理暂停与恢复。此外，agentlightning.hooks（默认null）允许指定一个RolloutHooks模块路径，训练器启动时会加载并调用其on_startup()（见 trainer.py），用于在训练生命周期中注入自定义回调。

模型与数据配置

模型配置沿用标准verl的actor_rollout_ref.model设置，把actor_rollout_ref.model.path设为 Hugging Face 模型名或本地模型路径即可：

actor_rollout_ref: model: path: Qwen/Qwen2.5-1.5B-Instruct

在上游verl中，数据集通常通过data.train_files与data.val_files指定文件路径；Agent Lightning 则改为先加载文件、再把结果集直接传入run_ppo，从而获得更高的灵活性：只要数据能表示为 JSON 对象列表，任意数据集都可以传入。

from datasets import Dataset from agentlightning.verl.entrypoint import run_ppo train_dataset = Dataset.from_parquet("data/train.parquet").to_list() val_dataset = Dataset.from_parquet("data/test.parquet").to_list() run_ppo(config, train_dataset=train_dataset, val_dataset=val_dataset)

run_ppo要求train_dataset与val_dataset均为非空的内存序列，每个元素按类 JSON 对象读取；训练器创建 rollout 时，列表中的每个元素就成为该 rollout 的input字段，Controller 再把input中的字段映射进 Agent 的环境变量或 Kubernetes Job 模板。

这一机制在源码中的实现链路清晰可查：

1. entrypoint.py 的run_ppo先断言两个数据集非空，初始化 Ray 集群，并用worker_process_setup_hook在每个 Ray worker 进程中注册自定义策略损失（agentlightning.verl.per_rollout_loss.register_in_worker），随后把数据集包装为LoadedDataset交给AgentLightningRayPPOTrainer；
2. dataset.py 的LoadedDataset继承verl的RLHFDataset，但跳过文件读取初始化，直接用HuggingFaceDataset.from_list从内存序列构造dataframe，并显式关闭filter_overlong_prompts。

Rollout 执行模式

Controller 支持local与k8s两种执行模式：配置好对应小节后，Controller 会按其当前运行模式读取相应配置。

Local 模式

为每个 rollout 启动一个本地子进程，并设置 Agent 类与从数据行到环境变量的映射：

agentlightning: local: agent_class: examples.search_r1.agents.search_r1_agent.SearchR1Agent env_map: QUESTION: input.question GOLDEN_ANSWERS: input.golden_answers

此时 Controller 会导入SearchR1Agent，为每个 rollout 启动一个本地子进程，并依据该 rollout 的input对象设置QUESTION与GOLDEN_ANSWERS环境变量。env_map的取值形如input.<字段名>，即从 rollout 的input中取字段作为环境变量值。SearchR1Agent 即为该模式下的一个真实 Agent 实现。

K8s 模式

在 K8s 模式下提供一个能渲染为 Kubernetes Job YAML 清单的 Jinja 模板：

agentlightning: k8s: job_template_path: examples/calc_x/job-template.yaml

模板可以使用 rolloutinput中的值。例如 calc_x 的 Job 模板 将数据集行字段替换进环境变量：

env: - name: QUESTION value: {% raw %}{{ input.question | yaml_escape }}{% endraw %} - name: RESULT value: {% raw %}{{ input.result | yaml_escape }}{% endraw %}

训练器读取该 Jinja 模板并把其文本包含进每个 rollout；Controller 用对应 rollout 的input渲染模板，随后为每个 rollout 创建一个 Kubernetes Job。

执行超时

agentlightning.rollout_timeout_seconds设置两种模式下每个 rollout 的最大执行时间：Controller 使用该值，若 rollout 在配置秒数内未完成即标记为失败，默认值为1800。实际示例中会根据任务时长调低该值，例如 calc_x 训练脚本 设置rollout_timeout_seconds: 300，而 search_r1 训练脚本 保持1800。

Trace Aggregator

上图左侧是传统 agentic RL：每个 rollout 对应一条训练样本；右侧是 Agent Lightning：一个 rollout 可以对应多条训练样本。Rollout 期间，Gateway 把所有原始 LLM 调用收集为 prompt-response 对，Trace Aggregator 再用下述两种模式之一把它们装配成训练样本。训练器依据level选择长度上限的逻辑见 trainer.py：trajectory前缀的 level 使用trace_aggregator下的两个长度参数，其余情况回退到verl标准的data.max_prompt_length/data.max_response_length。

Trajectory 模式

trajectory是默认且推荐的模式：

agentlightning: trace_aggregator: level: trajectory trajectory_max_prompt_length: 2048 trajectory_max_response_length: 8192

聚合器在“下一次调用的 prompt 以本次 prompt+response 的精确 token 序列开头”时自动合并相邻调用。调用之间新增的 token（如工具观察结果）会作为上下文保留，但在策略损失中被 mask 掉；一旦精确 token 前缀连续性被破坏，聚合器就另起一条训练行，而不是合并不兼容的调用。源码中该判断位于 rollout_adapter.py：ids_startswith(prompt_ids, current_context)成立时，前缀之外的新增 token 被并入 response 且对应response_mask记 0（不计损失），模型生成的部分记 1；失败时则把当前累积段落成一条训练行并另起新段。

该模式下两个长度参数的作用：

• trajectory_max_prompt_length限制每条合并后训练行的初始 prompt 长度；
• trajectory_max_response_length限制初始 prompt 之后的全部内容，包括被并入 trajectory response 序列的后续各轮 prompt 与 response。

建议把trajectory_max_response_length设置得相对高一些，使其能容纳多轮内容而不被截断：取值需覆盖后续各轮 prompt 与 response 的预期合并长度，同时适配模型上下文窗口与可用 GPU 显存。

两类超限样本的处置方式不同，rollout_adapter.py 中可逐行验证：

• 初始 prompt 超过trajectory_max_prompt_length的训练行会被打标记，并从策略更新批次中丢弃；
• 超过trajectory_max_response_length的内容则被截断到配置长度，样本保留。

丢弃与截断的行数通过以下指标上报 W&B：

• training/n_sample_dropped/marked— 因 prompt 超出配置上限而丢弃的行数（训练器在 trainer.py 中按is_drop_mask统计）；
• training/n_truncated_sample— response 被截断到配置上限的行数。

Transition 模式

transition模式下，每次模型调用都成为一条独立的训练行，不进行任何合并：

agentlightning: trace_aggregator: level: transition data: max_prompt_length: 4096 max_response_length: 2048

该模式不使用trajectory_max_prompt_length与trajectory_max_response_length，而是使用verl针对单次 vLLM rollout 调用的标准数据上限：

• data.max_prompt_length限制每次调用的 prompt；
• data.max_response_length限制每次调用的 response。

当希望每次请求-响应调用都保持为独立训练样本时使用 transition 模式。

算法正确性配置

下面这组配置控制 rollout 数据如何参与优化：

algorithm: enable_rollout_level_advantage: true actor_rollout_ref: actor: policy_loss: loss_mode: per_rollout_mean agentlightning: max_ppo_update_times: 2

Rollout 级 Advantage

algorithm.enable_rollout_level_advantage: true表示在 rollout 级别计算 advantage，而不是在每条训练样本上独立计算。这一点很重要，因为 Trace Aggregator 之后，一个 rollout 可能产生数量不定的训练行。

rollout_level_advantage.py 给出了具体实现：训练器在 trainer.py 检测到该开关后，从每个 rollout 的行中取一条代表行，用verl标准compute_advantage在该代表子集上计算 advantage，再按response_mask把标量广播回该 rollout 的全部行；过程中还会校验同一 rollout 的行共享同一uid与同一 reward 总和，保证 rollout 级统计的有效性。

Per-rollout 均值损失

actor_rollout_ref.actor.policy_loss.loss_mode: per_rollout_mean在 rollout 级别归一化策略损失，避免某个 rollout 仅仅因为产生了更多训练行而获得更大的优化权重。

其机制由两部分组成，均可在 per_rollout_loss.py 中核实：

1. normalize_advantages_by_rollout：训练器在 trainer.py 中按rollout_id_list把每行 advantage 除以“该 rollout 的总有效 token 数 × 批内训练行数”，使每个 rollout 对整个批次的贡献被均摊；
2. @register_policy_loss("per_rollout_mean")注册的 compute_policy_loss_per_rollout_mean：在 verl 标准 clipped PPO 损失之上叠加双端裁剪（clip_ratio_low/clip_ratio_high/clip_ratio_c）与可选的 rollout 重要性采样权重，最终按masked_sum × dp_size聚合计为标量损失。

该损失函数通过 Ray 的worker_process_setup_hook在全部 Actor 进程中完成注册（见 entrypoint.py），保证分布式训练时各 worker 行为一致。关于 rollout 级 advantage 与损失归一化的动机和详细公式，可参见 Agent Lightning v1.0 技术报告。

最大 PPO 更新次数

在极端情况下，Trace Aggregator 可能从一个采集批次产生过多训练样本，从而推高 PPO 更新次数、影响训练稳定性。agentlightning.max_ppo_update_times限制单个批次执行的最大 PPO mini-batch 更新次数。

默认值为null，即不设显式上限：此时训练器使用当前 step 采集到的全部完整 PPO mini-batch，仅丢弃无法填满最后一个 mini-batch 的余数样本。

trainer.py 中的实现进一步揭示了丢弃策略：mini-batch 有效大小按ppo_mini_batch_size × rollout.n计算；当需要丢弃样本时，优先随机丢弃“组内 reward 完全相同”（对 advantage 无贡献）的样本，不足部分再随机丢弃其余样本。出于训练稳定性考虑，官方建议将其设为2，超出上限的样本在策略更新前被丢弃。因 mini-batch 对齐或该上限而丢弃的样本数通过以下 W&B 指标上报：

• training/n_sample_dropped/same_reward
• training/n_sample_dropped/random

异步训练

Agent Lightning 支持 collocated 异步 rollout 采集，即 rollout 生成与模型更新共享同一 GPU 池，未完成的 rollout 组可结转到后续 step：

agentlightning: async_rollout: enabled: true async_train_batch_size: 64

启用后必须同时设置async_train_batch_size：它是保持活跃状态的 prompt 组数量，必须严格大于data.train_batch_size（单次更新消费的已完成组数）。训练器构造函数对此有硬性校验，不满足会直接抛出ValueError（见 trainer.py）。

完整的配置项、运行行为与约束（包括 prompt 组的完整性保证、Gateway 暂停-排空机制、staleness 修正建议等）见 Asynchronous Training。

配置速查表

以上各键的权威定义均位于 config.yaml，实际取值以当前仓库版本为准；若升级到新的 verl 上游版本，ppo_trainer基线配置中的原有选项依旧按常规生效。

【免费下载链接】agent-lightningThe absolute trainer to light up AI agents.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-lightning