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: trueActor 前向时计算熵便于监控策略探索性actor_rollout_ref.rollout.mode: asyncrollout 服务器以异步模式运行与训练器通过 API Gateway 协作。连接 API Gateway第一组配置用于把训练器接入 Agent Lightning API Gateway键默认值说明agentlightning.agl_base_urlhttp://localhost:8080Rollout 管理器使用的 Gateway 地址。agentlightning.agl_keyBearer 密钥必须与 API Gateway 和 Controller 配置一致。请确保运行训练器的机器能够访问agentlightning.agl_base_url指定的 Gatewayagl_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_datasettrain_dataset, val_datasetval_dataset)run_ppo要求train_dataset与val_dataset均为非空的内存序列每个元素按类 JSON 对象读取训练器创建 rollout 时列表中的每个元素就成为该 rollout 的input字段Controller 再把input中的字段映射进 Agent 的环境变量或 Kubernetes Job 模板。这一机制在源码中的实现链路清晰可查entrypoint.py 的run_ppo先断言两个数据集非空初始化 Ray 集群并用worker_process_setup_hook在每个 Ray worker 进程中注册自定义策略损失agentlightning.verl.per_rollout_loss.register_in_worker随后把数据集包装为LoadedDataset交给AgentLightningRayPPOTrainerdataset.py 的LoadedDataset继承verl的RLHFDataset但跳过文件读取初始化直接用HuggingFaceDataset.from_list从内存序列构造dataframe并显式关闭filter_overlong_prompts。Rollout 执行模式Controller 支持local与k8s两种执行模式配置好对应小节后Controller 会按其当前运行模式读取相应配置。键默认值说明agentlightning.local.agent_classnulllocal 模式下由 Controller 导入并启动的 Agent 完整限定类名。agentlightning.local.env_map{}将环境变量名映射到 rolloutinput的字段。agentlightning.k8s.job_template_pathnullK8s 模式下 Controller 使用的 Jinja Kubernetes Job 模板路径。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 模板并把其文本包含进每个 rolloutController 用对应 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.pytrajectory前缀的 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 以本次 promptresponse 的精确 token 序列开头”时自动合并相邻调用。调用之间新增的 token如工具观察结果会作为上下文保留但在策略损失中被 mask 掉一旦精确 token 前缀连续性被破坏聚合器就另起一条训练行而不是合并不兼容的调用。源码中该判断位于 rollout_adapter.pyids_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的内容则被截断到配置长度样本保留。丢弃与截断的行数通过以下指标上报 WBtraining/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限制每次调用的 promptdata.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: 2Rollout 级 Advantagealgorithm.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 中核实normalize_advantages_by_rollout训练器在 trainer.py 中按rollout_id_list把每行 advantage 除以“该 rollout 的总有效 token 数 × 批内训练行数”使每个 rollout 对整个批次的贡献被均摊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 对齐或该上限而丢弃的样本数通过以下 WB 指标上报training/n_sample_dropped/same_rewardtraining/n_sample_dropped/random异步训练Agent Lightning 支持 collocated 异步 rollout 采集即 rollout 生成与模型更新共享同一 GPU 池未完成的 rollout 组可结转到后续 stepagentlightning: 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。配置速查表键默认值作用algorithm.enable_rollout_level_advantagetrue在 rollout 级别计算 advantage 并广播到各训练行。agentlightning.agl_base_urlhttp://localhost:8080API Gateway 地址。agentlightning.agl_keyGateway/Controller/训练器三方一致的 Bearer 密钥。agentlightning.hooksnull可选RolloutHooks模块路径启动时调用on_startup。agentlightning.rollout_timeout_seconds1800单个 rollout 的最大执行秒数超时判失败。agentlightning.local.agent_class/env_mapnull/{}local 模式的 Agent 类与 input 字段到环境变量的映射。agentlightning.k8s.job_template_pathnullK8s 模式的 Jinja Job 模板路径。agentlightning.reward_fillna_value0.0Agent 未上报最终 reward 时的填充值RolloutAdapter._fillna_reward。agentlightning.max_ppo_update_timesnull单批最大 PPO mini-batch 更新次数建议2。agentlightning.trace_aggregator.leveltrajectorytrajectory合并多轮或transition每次调用独立成行。agentlightning.trace_aggregator.trajectory_max_prompt_length2048trajectory 模式下初始 prompt 上限超限标记丢弃。agentlightning.trace_aggregator.trajectory_max_response_length8192trajectory 模式下初始 prompt 之后全部内容上限超限截断。agentlightning.async_rollout.enabled/async_train_batch_sizefalse/null开启 collocated 异步采集活跃组数须大于data.train_batch_size。actor_rollout_ref.actor.policy_loss.loss_modeper_rollout_meanrollout 级归一化的策略损失。以上各键的权威定义均位于 config.yaml实际取值以当前仓库版本为准若升级到新的 verl 上游版本ppo_trainer基线配置中的原有选项依旧按常规生效。【免费下载链接】agent-lightningThe absolute trainer to light up AI agents.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-lightning创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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: trueActor 前向时计算熵便于监控策略探索性actor_rollout_ref.rollout.mode: asyncrollout 服务器以异步模式运行与训练器通过 API Gateway 协作。连接 API Gateway第一组配置用于把训练器接入 Agent Lightning API Gateway键默认值说明agentlightning.agl_base_urlhttp://localhost:8080Rollout 管理器使用的 Gateway 地址。agentlightning.agl_keyBearer 密钥必须与 API Gateway 和 Controller 配置一致。请确保运行训练器的机器能够访问agentlightning.agl_base_url指定的 Gatewayagl_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_datasettrain_dataset, val_datasetval_dataset)run_ppo要求train_dataset与val_dataset均为非空的内存序列每个元素按类 JSON 对象读取训练器创建 rollout 时列表中的每个元素就成为该 rollout 的input字段Controller 再把input中的字段映射进 Agent 的环境变量或 Kubernetes Job 模板。这一机制在源码中的实现链路清晰可查entrypoint.py 的run_ppo先断言两个数据集非空初始化 Ray 集群并用worker_process_setup_hook在每个 Ray worker 进程中注册自定义策略损失agentlightning.verl.per_rollout_loss.register_in_worker随后把数据集包装为LoadedDataset交给AgentLightningRayPPOTrainerdataset.py 的LoadedDataset继承verl的RLHFDataset但跳过文件读取初始化直接用HuggingFaceDataset.from_list从内存序列构造dataframe并显式关闭filter_overlong_prompts。Rollout 执行模式Controller 支持local与k8s两种执行模式配置好对应小节后Controller 会按其当前运行模式读取相应配置。键默认值说明agentlightning.local.agent_classnulllocal 模式下由 Controller 导入并启动的 Agent 完整限定类名。agentlightning.local.env_map{}将环境变量名映射到 rolloutinput的字段。agentlightning.k8s.job_template_pathnullK8s 模式下 Controller 使用的 Jinja Kubernetes Job 模板路径。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 模板并把其文本包含进每个 rolloutController 用对应 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.pytrajectory前缀的 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 以本次 promptresponse 的精确 token 序列开头”时自动合并相邻调用。调用之间新增的 token如工具观察结果会作为上下文保留但在策略损失中被 mask 掉一旦精确 token 前缀连续性被破坏聚合器就另起一条训练行而不是合并不兼容的调用。源码中该判断位于 rollout_adapter.pyids_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的内容则被截断到配置长度样本保留。丢弃与截断的行数通过以下指标上报 WBtraining/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限制每次调用的 promptdata.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: 2Rollout 级 Advantagealgorithm.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 中核实normalize_advantages_by_rollout训练器在 trainer.py 中按rollout_id_list把每行 advantage 除以“该 rollout 的总有效 token 数 × 批内训练行数”使每个 rollout 对整个批次的贡献被均摊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 对齐或该上限而丢弃的样本数通过以下 WB 指标上报training/n_sample_dropped/same_rewardtraining/n_sample_dropped/random异步训练Agent Lightning 支持 collocated 异步 rollout 采集即 rollout 生成与模型更新共享同一 GPU 池未完成的 rollout 组可结转到后续 stepagentlightning: 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。配置速查表键默认值作用algorithm.enable_rollout_level_advantagetrue在 rollout 级别计算 advantage 并广播到各训练行。agentlightning.agl_base_urlhttp://localhost:8080API Gateway 地址。agentlightning.agl_keyGateway/Controller/训练器三方一致的 Bearer 密钥。agentlightning.hooksnull可选RolloutHooks模块路径启动时调用on_startup。agentlightning.rollout_timeout_seconds1800单个 rollout 的最大执行秒数超时判失败。agentlightning.local.agent_class/env_mapnull/{}local 模式的 Agent 类与 input 字段到环境变量的映射。agentlightning.k8s.job_template_pathnullK8s 模式的 Jinja Job 模板路径。agentlightning.reward_fillna_value0.0Agent 未上报最终 reward 时的填充值RolloutAdapter._fillna_reward。agentlightning.max_ppo_update_timesnull单批最大 PPO mini-batch 更新次数建议2。agentlightning.trace_aggregator.leveltrajectorytrajectory合并多轮或transition每次调用独立成行。agentlightning.trace_aggregator.trajectory_max_prompt_length2048trajectory 模式下初始 prompt 上限超限标记丢弃。agentlightning.trace_aggregator.trajectory_max_response_length8192trajectory 模式下初始 prompt 之后全部内容上限超限截断。agentlightning.async_rollout.enabled/async_train_batch_sizefalse/null开启 collocated 异步采集活跃组数须大于data.train_batch_size。actor_rollout_ref.actor.policy_loss.loss_modeper_rollout_meanrollout 级归一化的策略损失。以上各键的权威定义均位于 config.yaml实际取值以当前仓库版本为准若升级到新的 verl 上游版本ppo_trainer基线配置中的原有选项依旧按常规生效。【免费下载链接】agent-lightningThe absolute trainer to light up AI agents.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-lightning创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
