2026/9/13 12:28:06
FEATURED · 精选文章 
Agent Lightning Calc-X 实战单 GPU 训练数学推理 Agent 的完整配置与 Local/K8s 双模式解析【免费下载链接】agent-lightningThe absolute trainer to light up AI agents.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-lightning本文围绕 Agent Lightning 仓库中的 Calc-X 示例examples/calc_x/展开讲解如何基于verl与 Agent Lightning v1.0用单张 A100 80GB 在Qwen/Qwen2.5-1.5B-Instruct上训练一个数学推理 Agent。读完本文你将掌握该示例的数据准备、依赖安装、Local 与 K8sMinikube两种 Controller 模式下的启动流程、同步/异步训练配置并能从源码层面理解 Agent 如何调用 MCP 计算工具、如何上报 reward、以及训练入口如何合并 VERL 与 Agent Lightning 的配置。一、Calc-X 示例定位与总体架构Calc-X 是一个刻意保持轻量级的 POCProof-of-Concept示例它只用 1× A100 80GB 即可运行训练目标是在 Calc-X 数据集上学会使用计算器解决数学问题。Agent 本体采用AutoGen MCP calculator 工具模型通过mcp-server-calculator提供的计算器能力进行多步计算最终把答案写入规定格式由评估脚本与标准答案比对后得到 0/1 奖励。该示例同时覆盖 Agent Lightning 的两类 Controller 模式这也是它作为入门示例的价值所在K8s 模式以 Minikube 提供最小化 Kubernetes 环境每次 Agent rollout 都作为一个 Kubernetes Job 运行在生产级编排下Local 模式Agent rollout 直接以本地子进程运行不依赖任何 Kubernetes 环境两种模式均同时支持**同步sync与异步async**两种 Trainer 模式。一个 rollout 的完整链路是VERL 训练器Ray 集群内→ Agent Lightning Serveragl-server→ Controlleragl-controllerLocal 或 K8s Runner→ Agent 进程K8s Job 或本地多进程→ Agent 通过 OpenAI 兼容接口代理到被训练模型多轮调用工具 → Agent 将 reward 事件 POST 回 Server → 训练侧按 rollout 聚合为 GRPO 训练信号。二、数据准备从仓库文档看官方数据文件需要从外部数据源Google Drive链接见文档原文下载calc-x-data.zip解压到examples/calc_x/data/cd examples/calc_x unzip data/calc-x-data.zip -d data/解压后应得到四个数据集文件data/train.parquetdata/test.parquetdata/test_mini.parquetdata/sample.jsonl仓库中已包含examples/calc_x/data/sample.jsonl可以看到样本结构每条记录含id、question、chain参考的计算器调用链、result标准答案与source字段例如{id: ape210k__00469689, question: How many degrees of 75° can form a right angle?, result: 15, source: calc}训练入口train_calc_agent.py使用 HuggingFacedatasets的from_parquet读取 parquet 文件QUESTION/RESULT两个字段会经由配置中的env_map注入到 Agent 环境变量见第五节而sample.jsonl可用于快速查看数据形态。三、Agent 实现AutoGen MCP 计算器工具Agent 入口文件是 calc_agent.py整个Agent.run()流程可以概括为五步读取环境变量从QUESTION、RESULT、AGL_KEY、AGL_EVENT_URL、AGL_OPENAI_BASE_URL五个环境变量获取题目、标准答案、Agent Lightning 鉴权 key、事件上报地址与 OpenAI 兼容推理端点。其中AGL_OPENAI_BASE_URL指向 AGL Server 的代理端点——注意rollout 期间 Agent 调用的是正在被训练的模型而非某个固定的外部 LLM挂载 MCP 计算器通过StdioServerParams以 stdio 方式拉起python -m mcp_server_calculator读取超时 120 秒并用McpWorkbench管理其生命周期构建 AutoGen 助手OpenAIChatCompletionClient使用modelauto并显式声明function_calling: True、max_retries6AssistantAgent开启reflect_on_tool_useTrue即每次工具调用后会进行一次反思这对多步计算任务的稳定性有直接影响执行与超时控制任务字符串为f{question} {output_format}其中output_format要求模型把最终答案写成### ANSWER: answer ###格式整个agent.run被asyncio.wait_for(..., timeout300.0)包裹单样本最长 300 秒解析答案并上报 reward用正则r###\s*ANSWER:\s*(.?)(\s*###|$)从最后一条消息提取答案与标准答案通过scalar_are_results_same(answer, result, 1e-2)比对数值容差 1%得到 1.0/0.0 的奖励然后httpx.post到AGL_EVENT_URLhttpx.post( event_url, json{event_type: reward, data: {value: reward}}, headers{Authorization: fBearer {agl_key}}, timeout10.0, ).raise_for_status()如果正则没有匹配到则退化为把整条最后消息作为答案参与比对——这是一个值得注意的容错设计格式不完美不必然得 0 分答案语义正确仍可得分。数值比对逻辑奖励计算的实现位于 eval_utils.py注释中说明该逻辑改编自 Calc-X 官方仓库的gadgets/metrics.py依赖sympy。核心函数scalar_are_results_same(pred_result, true_result, rel_tol)按三层顺序判断字符串精确相等去空格后直接判对若标准答案是单选选项A/B/C等字母则把两边都归一化后做选项匹配否则用sympy.parse_expr把两侧解析为浮点数math.isclose(..., rel_tol1e-2)做相对误差 1% 内的数值比较能正确处理2/3与0.666667这类同一数值的两种写法。四、训练入口train_calc_agent.py 的配置体系训练脚本 train_calc_agent.py 采用 Hydra/OmegaConf 构建完整配置其build_config()的逻辑值得细看先用importlib.resources.files(agentlightning.verl)定位包内配置目录compose(config_nameconfig)加载基础配置 agentlightning/verl/config.yaml——该文件通过 Hydrasearchpath引用pkg://verl/trainer/config并defaults引入 verl 的ppo_trainer因此 VERL 的 PPO 全量默认参数都在底层再把示例专属的verl_default_config()覆盖项合并上去最后支持命令行 dotlist 覆盖parse_known_args收集即bash run_local.sh trainer.total_epochs3这类用法是可行的。命令行参数参数默认值说明--train-filedata/train.parquet训练数据 parquet 路径--val-filedata/test.parquet验证数据 parquet 路径--modelNone回落到Qwen/Qwen2.5-1.5B-InstructHF 模型 id 或本地路径--agl-base-urlhttp://localhost:8181Agent Lightning Server 地址--agl-keycalcx-dev-key训练器使用的 API key--run-nameNone追加到trainer.experiment_name的后缀--async关闭启用异步 rollout并把async_train_batch_size自动设为train_batch_size × 2关键 VERL/GRPO 配置verl_default_config示例内置的覆盖项集中在几个点GRPO 估计器 关闭 KL、单 GPU 显存优化、rollout 走 vLLM 并启用 hermes 工具解析algorithm: { adv_estimator: grpo, use_kl_in_reward: False, }, data: { train_batch_size: 32, max_prompt_length: 4096, max_response_length: 2048, }, actor_rollout_ref: { rollout: { tensor_model_parallel_size: 1, # 单卡 n: 4, # 每题采样 4 条轨迹 multi_turn: {format: hermes}, name: vllm, gpu_memory_utilization: 0.6, # 给训练侧留显存 engine_kwargs: {vllm: { enable_auto_tool_choice: True, tool_call_parser: hermes, # 与 hermes 多轮格式配套 }}, }, actor: { ppo_mini_batch_size: 32, optim: {lr: 1e-6}, use_kl_loss: False, kl_loss_coef: 0.0, entropy_coeff: 0, clip_ratio_low: 0.2, clip_ratio_high: 0.3, fsdp_config: {param_offload: True, optimizer_offload: True}, }, model: { path: Qwen/Qwen2.5-1.5B-Instruct, use_remove_padding: True, enable_gradient_checkpointing: True, }, }, trainer: { n_gpus_per_node: 1, total_epochs: 2, save_freq: 64, test_freq: 10, nnodes: 1, logger: [console, wandb], },param_offload/optimizer_offloadgpu_memory_utilization0.6 梯度检查点这一组合正是1.5B 模型单卡同时容纳 vLLM rollout 与 FSDP 训练的关键。agentlightning 专属配置块示例为agentlightning块配置了agentlightning: { agl_base_url: http://localhost:8181, agl_key: calcx-dev-key, rollout_timeout_seconds: 300, # 与 Agent 内 300s 超时就绪对齐 async_rollout: { enabled: False, async_train_batch_size: 64, # --async 时被改写为 2× train_batch_size }, local: { agent_class: examples.calc_x.calc_agent.Agent, env_map: { QUESTION: input.question, RESULT: input.result, }, }, k8s: { job_template_path: str(example_dir / job-template.yaml), }, },对照基础配置 agentlightning/verl/config.yaml 可以看到这些项的缺省行为默认rollout_timeout_seconds为 1800而 Calc-X 收紧到 300与 Agent 内部asyncio.wait_for(timeout300.0)保持一致local.agent_classenv_map是 Local Runner 的挂载点类路径 数据集字段到环境变量的映射k8s.job_template_path则是 K8s Runner 创建 Job 时的模板基础配置还包含reward_fillna_value: 0.0Agent 未上报 reward 时的填充值与trace_aggregator轨迹聚合级别等示例未覆盖它们沿用默认。训练最终通过run_ppo(config, train_dataset, val_dataset)启动该入口定义在 agentlightning/verl/entrypoint.py它包装了 verl 的 PPO Ray 初始化使用AgentLightningRayPPOTrainerRayPPOTrainer子类让 rollout 走 Agent Lightning HTTP API 而非原版 VERL agent loop worker并在 Ray worker 进程中注册per_rollout_loss自定义损失——对应基础配置中的policy_loss.loss_mode: per_rollout_mean与enable_rollout_level_advantage: true。五、Local 模式一键启动与自动清理Local 模式的前提是项目虚拟环境已激活并额外安装 Agent 运行依赖source .venv/bin/activate uv pip install \ openai \ httpx \ sympy \ autogen-agentchat \ autogen-ext[openai] \ mcp1.11.0,2 \ mcp-server-calculator然后启动训练source .venv/bin/activate cd examples/calc_x bash run_local.shrun_local.sh 的完整流程set -euo pipefail定义常量AGL_SERVER_PORT8181、AGL_KEYdummy、日志写入/tmp/agl-server-时间戳-PID.log与/tmp/agl-controller-*.logcleanup 函数并trap到 EXIT/INT/TERM脚本退出无论成功、失败还是 Ctrl-C都会执行pkill -f agl-server、pkill -f agl-controller、ray stop --force实现启动即清理启动前也会先执行一次 cleanup避免残留进程占用 8181 端口设置 PYTHONPATH 为仓库根目录REPO_ROOT保证examples.calc_x.calc_agent这类类路径可被导入ray start --head --dashboard-host0.0.0.0拉起 Ray head 节点VERL 训练依赖 Ray启动agl-serverport8181 keydummy default_proxy.model_nameQwen/Qwen2.5-1.5B-Instruct随后以curl -sf http://localhost:8181/healthz轮询最多 60 秒等待就绪启动agl-controllerrunner_typelocal连接agl_server.url/key前台运行训练python train_calc_agent.py --agl-base-url ... --agl-key dummy --run-name local $$会把额外参数透传给训练脚本如--async或 Hydra dotlist 覆盖。如文档所述Local 模式下agl-controller以多进程方式直接拉起examples.calc_x.calc_agent.Agent实例跑 rollout每个实例按env_map注入QUESTION/RESULT并按 rollout 上下文获得AGL_KEY、AGL_EVENT_URL、AGL_OPENAI_BASE_URL。六、K8s 模式Minikube 上的最小化 Kubernetes 工作流K8s 模式演示的是生产形态的 rollout 编排Agent 不在本机跑而是以 Kubernetes Job 的形式运行。示例选择 Minikube 作为最小集群文档明确提示生产部署应将 Minikube 替换为生产级 K8s 集群。前置要求已安装docker与minikube然后source .venv/bin/activate cd examples/calc_x bash run_minikube.shrun_minikube.sh 在 Local 脚本基础上多了三类步骤其余8181 端口、healthz 轮询、ray head、前台训练完全一致cleanup 增加minikube stop脚本退出时同时停掉 Minikube重建并启动单节点集群minikube delete -p minikube后执行minikube start --memory65536 --cpus16 --driverdocker——64GB 内存是文档强调的硬性要求否则 Minikube 可能因内存不足被 kill构建 Agent 镜像minikube image build -t calc-x-agent:dev -f Dockerfile .把 Agent 代码直接打进集群节点镜像免去拉取Controller 改用 K8s Runnerrunner_typek8s且agl_server.url指向http://host.minikube.internal:8181集群内访问宿主机的入口并附加k8s_runner.ttl_after_finished600Job 结束 600 秒后由 Controller 回收训练命令以--run-name minikube运行其余参数同样支持透传。Agent 镜像与 Job 模板镜像由 Dockerfile 构建基于python:3.12-slim安装与 Local 模式一致的依赖openai、httpx、sympy、autogen-agentchat、autogen-ext[openai]、mcp1.10.0、mcp-server-calculator把calc_agent.py与eval_utils.py拷入/app并通过compileall预编译与timeout 3 python -m mcp_server_calculator的能启动即通过自检保证镜像里 MCP 计算器可用。每次 rollout 创建的 Job 由 job-template.yaml 模板化生成apiVersion: batch/v1 kind: Job metadata: name: auto spec: backoffLimit: 0 template: spec: restartPolicy: Never containers: - name: agent image: calc-x-agent:dev command: [python, /app/calc_agent.py] imagePullPolicy: Never # 镜像已在节点本地无需拉取 env: - name: QUESTION value: {{ input.question | yaml_escape }} - name: RESULT value: {{ input.result | yaml_escape }} resources: requests: cpu: 200m memory: 256Mi模板中的{{ input.question | yaml_escape }}、{{ input.result | yaml_escape }}是 Jinja 占位符由 K8s Runner 在创建 Job 时按每条样本的数据集字段填充与 Local 模式env_map的语义一致QUESTION/RESULT来自样本的question/result字段backoffLimit: 0restartPolicy: Never使失败不重试保证 rollout 结果与轨迹语义一一对应。七、同步与异步训练模式两种模式的差异全部收敛在agentlightning.async_rollout配置块与--async开关上同步模式默认async_rollout.enabledFalse一个 batch 的 rollout 全部完成后才进入 PPO 更新行为可预测、复现性最好异步模式追加--async启动bash run_local.sh --asyncbuild_config会把async_rollout.enabled置为True并把async_train_batch_size设为train_batch_size × 2 64同时在experiment_name上追加async标记如calc_x_async_local方便在 wandb 中区分实验。异步模式下 rollout 与训练重叠推进以更多在途 rollout 换取吞吐提升。需要注意的前提训练器需要能访问agl_base_url默认http://localhost:8181--agl-key必须与agl-server启动时使用的key一致脚本中为dummy训练配置默认calcx-dev-key脚本会显式传dummy覆盖使用logger: [console, wandb]时需自行配置 wandb 环境否则可点覆盖为trainer.loggerconsole。八、实操要点与排查建议端口与残留两个脚本都固定使用 8181 端口并内置启动前清理若训练卡死在 healthz 轮询最多 60 秒优先检查 8181 是否被占用、/tmp/agl-server-*.log是否报错Minikube 内存K8s 模式必须保证--memory6553664GBCPU 建议 16 核--driverdocker超时对齐rollout_timeout_seconds300、Agent 内asyncio.wait_for300与 MCPread_timeout_seconds120是三层超时若题目难度导致超时率升高应同步放宽而非只改其一数据字段契约Agent 只依赖样本的question与result两个字段由env_map与 Job 模板共同约定更换数据集时需保证同名字段存在K8s 资源请求偏小Job 模板只请求 200m CPU / 256Mi 内存这是合理的——Agent 进程只做 API 调用与 MCP stdio 子进程计算全部发生在被训练模型一侧。小结Calc-X 示例用最小的资源单卡、1.5B 模型把 Agent Lightning 的核心闭环演示完整数据以 parquet/jsonl 提供 →train_calc_agent.py以 Hydra 合并 VERL 基础配置与示例覆盖项 →run_ppo启动 Ray AgentLightningRayPPOTrainer →agl-server/agl-controller按 Local 或 K8s Runner 把 AutoGenMCP Agent 跑起来 → reward 事件回传并按 GRPO 更新策略。想继续深入可以沿着本文引用的 run_local.sh、train_calc_agent.py、agentlightning/verl/entrypoint.py 与 agentlightning/verl/config.yaml 阅读对应实现。【免费下载链接】agent-lightningThe absolute trainer to light up AI agents.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-lightning创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Agent Lightning Calc-X 实战：单 GPU 训练数学推理 Agent 的完整配置与 Local/K8s 双模式解析
Agent Lightning Calc-X 实战单 GPU 训练数学推理 Agent 的完整配置与 Local/K8s 双模式解析【免费下载链接】agent-lightningThe absolute trainer to light up AI agents.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-lightning本文围绕 Agent Lightning 仓库中的 Calc-X 示例examples/calc_x/展开讲解如何基于verl与 Agent Lightning v1.0用单张 A100 80GB 在Qwen/Qwen2.5-1.5B-Instruct上训练一个数学推理 Agent。读完本文你将掌握该示例的数据准备、依赖安装、Local 与 K8sMinikube两种 Controller 模式下的启动流程、同步/异步训练配置并能从源码层面理解 Agent 如何调用 MCP 计算工具、如何上报 reward、以及训练入口如何合并 VERL 与 Agent Lightning 的配置。一、Calc-X 示例定位与总体架构Calc-X 是一个刻意保持轻量级的 POCProof-of-Concept示例它只用 1× A100 80GB 即可运行训练目标是在 Calc-X 数据集上学会使用计算器解决数学问题。Agent 本体采用AutoGen MCP calculator 工具模型通过mcp-server-calculator提供的计算器能力进行多步计算最终把答案写入规定格式由评估脚本与标准答案比对后得到 0/1 奖励。该示例同时覆盖 Agent Lightning 的两类 Controller 模式这也是它作为入门示例的价值所在K8s 模式以 Minikube 提供最小化 Kubernetes 环境每次 Agent rollout 都作为一个 Kubernetes Job 运行在生产级编排下Local 模式Agent rollout 直接以本地子进程运行不依赖任何 Kubernetes 环境两种模式均同时支持**同步sync与异步async**两种 Trainer 模式。一个 rollout 的完整链路是VERL 训练器Ray 集群内→ Agent Lightning Serveragl-server→ Controlleragl-controllerLocal 或 K8s Runner→ Agent 进程K8s Job 或本地多进程→ Agent 通过 OpenAI 兼容接口代理到被训练模型多轮调用工具 → Agent 将 reward 事件 POST 回 Server → 训练侧按 rollout 聚合为 GRPO 训练信号。二、数据准备从仓库文档看官方数据文件需要从外部数据源Google Drive链接见文档原文下载calc-x-data.zip解压到examples/calc_x/data/cd examples/calc_x unzip data/calc-x-data.zip -d data/解压后应得到四个数据集文件data/train.parquetdata/test.parquetdata/test_mini.parquetdata/sample.jsonl仓库中已包含examples/calc_x/data/sample.jsonl可以看到样本结构每条记录含id、question、chain参考的计算器调用链、result标准答案与source字段例如{id: ape210k__00469689, question: How many degrees of 75° can form a right angle?, result: 15, source: calc}训练入口train_calc_agent.py使用 HuggingFacedatasets的from_parquet读取 parquet 文件QUESTION/RESULT两个字段会经由配置中的env_map注入到 Agent 环境变量见第五节而sample.jsonl可用于快速查看数据形态。三、Agent 实现AutoGen MCP 计算器工具Agent 入口文件是 calc_agent.py整个Agent.run()流程可以概括为五步读取环境变量从QUESTION、RESULT、AGL_KEY、AGL_EVENT_URL、AGL_OPENAI_BASE_URL五个环境变量获取题目、标准答案、Agent Lightning 鉴权 key、事件上报地址与 OpenAI 兼容推理端点。其中AGL_OPENAI_BASE_URL指向 AGL Server 的代理端点——注意rollout 期间 Agent 调用的是正在被训练的模型而非某个固定的外部 LLM挂载 MCP 计算器通过StdioServerParams以 stdio 方式拉起python -m mcp_server_calculator读取超时 120 秒并用McpWorkbench管理其生命周期构建 AutoGen 助手OpenAIChatCompletionClient使用modelauto并显式声明function_calling: True、max_retries6AssistantAgent开启reflect_on_tool_useTrue即每次工具调用后会进行一次反思这对多步计算任务的稳定性有直接影响执行与超时控制任务字符串为f{question} {output_format}其中output_format要求模型把最终答案写成### ANSWER: answer ###格式整个agent.run被asyncio.wait_for(..., timeout300.0)包裹单样本最长 300 秒解析答案并上报 reward用正则r###\s*ANSWER:\s*(.?)(\s*###|$)从最后一条消息提取答案与标准答案通过scalar_are_results_same(answer, result, 1e-2)比对数值容差 1%得到 1.0/0.0 的奖励然后httpx.post到AGL_EVENT_URLhttpx.post( event_url, json{event_type: reward, data: {value: reward}}, headers{Authorization: fBearer {agl_key}}, timeout10.0, ).raise_for_status()如果正则没有匹配到则退化为把整条最后消息作为答案参与比对——这是一个值得注意的容错设计格式不完美不必然得 0 分答案语义正确仍可得分。数值比对逻辑奖励计算的实现位于 eval_utils.py注释中说明该逻辑改编自 Calc-X 官方仓库的gadgets/metrics.py依赖sympy。核心函数scalar_are_results_same(pred_result, true_result, rel_tol)按三层顺序判断字符串精确相等去空格后直接判对若标准答案是单选选项A/B/C等字母则把两边都归一化后做选项匹配否则用sympy.parse_expr把两侧解析为浮点数math.isclose(..., rel_tol1e-2)做相对误差 1% 内的数值比较能正确处理2/3与0.666667这类同一数值的两种写法。四、训练入口train_calc_agent.py 的配置体系训练脚本 train_calc_agent.py 采用 Hydra/OmegaConf 构建完整配置其build_config()的逻辑值得细看先用importlib.resources.files(agentlightning.verl)定位包内配置目录compose(config_nameconfig)加载基础配置 agentlightning/verl/config.yaml——该文件通过 Hydrasearchpath引用pkg://verl/trainer/config并defaults引入 verl 的ppo_trainer因此 VERL 的 PPO 全量默认参数都在底层再把示例专属的verl_default_config()覆盖项合并上去最后支持命令行 dotlist 覆盖parse_known_args收集即bash run_local.sh trainer.total_epochs3这类用法是可行的。命令行参数参数默认值说明--train-filedata/train.parquet训练数据 parquet 路径--val-filedata/test.parquet验证数据 parquet 路径--modelNone回落到Qwen/Qwen2.5-1.5B-InstructHF 模型 id 或本地路径--agl-base-urlhttp://localhost:8181Agent Lightning Server 地址--agl-keycalcx-dev-key训练器使用的 API key--run-nameNone追加到trainer.experiment_name的后缀--async关闭启用异步 rollout并把async_train_batch_size自动设为train_batch_size × 2关键 VERL/GRPO 配置verl_default_config示例内置的覆盖项集中在几个点GRPO 估计器 关闭 KL、单 GPU 显存优化、rollout 走 vLLM 并启用 hermes 工具解析algorithm: { adv_estimator: grpo, use_kl_in_reward: False, }, data: { train_batch_size: 32, max_prompt_length: 4096, max_response_length: 2048, }, actor_rollout_ref: { rollout: { tensor_model_parallel_size: 1, # 单卡 n: 4, # 每题采样 4 条轨迹 multi_turn: {format: hermes}, name: vllm, gpu_memory_utilization: 0.6, # 给训练侧留显存 engine_kwargs: {vllm: { enable_auto_tool_choice: True, tool_call_parser: hermes, # 与 hermes 多轮格式配套 }}, }, actor: { ppo_mini_batch_size: 32, optim: {lr: 1e-6}, use_kl_loss: False, kl_loss_coef: 0.0, entropy_coeff: 0, clip_ratio_low: 0.2, clip_ratio_high: 0.3, fsdp_config: {param_offload: True, optimizer_offload: True}, }, model: { path: Qwen/Qwen2.5-1.5B-Instruct, use_remove_padding: True, enable_gradient_checkpointing: True, }, }, trainer: { n_gpus_per_node: 1, total_epochs: 2, save_freq: 64, test_freq: 10, nnodes: 1, logger: [console, wandb], },param_offload/optimizer_offloadgpu_memory_utilization0.6 梯度检查点这一组合正是1.5B 模型单卡同时容纳 vLLM rollout 与 FSDP 训练的关键。agentlightning 专属配置块示例为agentlightning块配置了agentlightning: { agl_base_url: http://localhost:8181, agl_key: calcx-dev-key, rollout_timeout_seconds: 300, # 与 Agent 内 300s 超时就绪对齐 async_rollout: { enabled: False, async_train_batch_size: 64, # --async 时被改写为 2× train_batch_size }, local: { agent_class: examples.calc_x.calc_agent.Agent, env_map: { QUESTION: input.question, RESULT: input.result, }, }, k8s: { job_template_path: str(example_dir / job-template.yaml), }, },对照基础配置 agentlightning/verl/config.yaml 可以看到这些项的缺省行为默认rollout_timeout_seconds为 1800而 Calc-X 收紧到 300与 Agent 内部asyncio.wait_for(timeout300.0)保持一致local.agent_classenv_map是 Local Runner 的挂载点类路径 数据集字段到环境变量的映射k8s.job_template_path则是 K8s Runner 创建 Job 时的模板基础配置还包含reward_fillna_value: 0.0Agent 未上报 reward 时的填充值与trace_aggregator轨迹聚合级别等示例未覆盖它们沿用默认。训练最终通过run_ppo(config, train_dataset, val_dataset)启动该入口定义在 agentlightning/verl/entrypoint.py它包装了 verl 的 PPO Ray 初始化使用AgentLightningRayPPOTrainerRayPPOTrainer子类让 rollout 走 Agent Lightning HTTP API 而非原版 VERL agent loop worker并在 Ray worker 进程中注册per_rollout_loss自定义损失——对应基础配置中的policy_loss.loss_mode: per_rollout_mean与enable_rollout_level_advantage: true。五、Local 模式一键启动与自动清理Local 模式的前提是项目虚拟环境已激活并额外安装 Agent 运行依赖source .venv/bin/activate uv pip install \ openai \ httpx \ sympy \ autogen-agentchat \ autogen-ext[openai] \ mcp1.11.0,2 \ mcp-server-calculator然后启动训练source .venv/bin/activate cd examples/calc_x bash run_local.shrun_local.sh 的完整流程set -euo pipefail定义常量AGL_SERVER_PORT8181、AGL_KEYdummy、日志写入/tmp/agl-server-时间戳-PID.log与/tmp/agl-controller-*.logcleanup 函数并trap到 EXIT/INT/TERM脚本退出无论成功、失败还是 Ctrl-C都会执行pkill -f agl-server、pkill -f agl-controller、ray stop --force实现启动即清理启动前也会先执行一次 cleanup避免残留进程占用 8181 端口设置 PYTHONPATH 为仓库根目录REPO_ROOT保证examples.calc_x.calc_agent这类类路径可被导入ray start --head --dashboard-host0.0.0.0拉起 Ray head 节点VERL 训练依赖 Ray启动agl-serverport8181 keydummy default_proxy.model_nameQwen/Qwen2.5-1.5B-Instruct随后以curl -sf http://localhost:8181/healthz轮询最多 60 秒等待就绪启动agl-controllerrunner_typelocal连接agl_server.url/key前台运行训练python train_calc_agent.py --agl-base-url ... --agl-key dummy --run-name local $$会把额外参数透传给训练脚本如--async或 Hydra dotlist 覆盖。如文档所述Local 模式下agl-controller以多进程方式直接拉起examples.calc_x.calc_agent.Agent实例跑 rollout每个实例按env_map注入QUESTION/RESULT并按 rollout 上下文获得AGL_KEY、AGL_EVENT_URL、AGL_OPENAI_BASE_URL。六、K8s 模式Minikube 上的最小化 Kubernetes 工作流K8s 模式演示的是生产形态的 rollout 编排Agent 不在本机跑而是以 Kubernetes Job 的形式运行。示例选择 Minikube 作为最小集群文档明确提示生产部署应将 Minikube 替换为生产级 K8s 集群。前置要求已安装docker与minikube然后source .venv/bin/activate cd examples/calc_x bash run_minikube.shrun_minikube.sh 在 Local 脚本基础上多了三类步骤其余8181 端口、healthz 轮询、ray head、前台训练完全一致cleanup 增加minikube stop脚本退出时同时停掉 Minikube重建并启动单节点集群minikube delete -p minikube后执行minikube start --memory65536 --cpus16 --driverdocker——64GB 内存是文档强调的硬性要求否则 Minikube 可能因内存不足被 kill构建 Agent 镜像minikube image build -t calc-x-agent:dev -f Dockerfile .把 Agent 代码直接打进集群节点镜像免去拉取Controller 改用 K8s Runnerrunner_typek8s且agl_server.url指向http://host.minikube.internal:8181集群内访问宿主机的入口并附加k8s_runner.ttl_after_finished600Job 结束 600 秒后由 Controller 回收训练命令以--run-name minikube运行其余参数同样支持透传。Agent 镜像与 Job 模板镜像由 Dockerfile 构建基于python:3.12-slim安装与 Local 模式一致的依赖openai、httpx、sympy、autogen-agentchat、autogen-ext[openai]、mcp1.10.0、mcp-server-calculator把calc_agent.py与eval_utils.py拷入/app并通过compileall预编译与timeout 3 python -m mcp_server_calculator的能启动即通过自检保证镜像里 MCP 计算器可用。每次 rollout 创建的 Job 由 job-template.yaml 模板化生成apiVersion: batch/v1 kind: Job metadata: name: auto spec: backoffLimit: 0 template: spec: restartPolicy: Never containers: - name: agent image: calc-x-agent:dev command: [python, /app/calc_agent.py] imagePullPolicy: Never # 镜像已在节点本地无需拉取 env: - name: QUESTION value: {{ input.question | yaml_escape }} - name: RESULT value: {{ input.result | yaml_escape }} resources: requests: cpu: 200m memory: 256Mi模板中的{{ input.question | yaml_escape }}、{{ input.result | yaml_escape }}是 Jinja 占位符由 K8s Runner 在创建 Job 时按每条样本的数据集字段填充与 Local 模式env_map的语义一致QUESTION/RESULT来自样本的question/result字段backoffLimit: 0restartPolicy: Never使失败不重试保证 rollout 结果与轨迹语义一一对应。七、同步与异步训练模式两种模式的差异全部收敛在agentlightning.async_rollout配置块与--async开关上同步模式默认async_rollout.enabledFalse一个 batch 的 rollout 全部完成后才进入 PPO 更新行为可预测、复现性最好异步模式追加--async启动bash run_local.sh --asyncbuild_config会把async_rollout.enabled置为True并把async_train_batch_size设为train_batch_size × 2 64同时在experiment_name上追加async标记如calc_x_async_local方便在 wandb 中区分实验。异步模式下 rollout 与训练重叠推进以更多在途 rollout 换取吞吐提升。需要注意的前提训练器需要能访问agl_base_url默认http://localhost:8181--agl-key必须与agl-server启动时使用的key一致脚本中为dummy训练配置默认calcx-dev-key脚本会显式传dummy覆盖使用logger: [console, wandb]时需自行配置 wandb 环境否则可点覆盖为trainer.loggerconsole。八、实操要点与排查建议端口与残留两个脚本都固定使用 8181 端口并内置启动前清理若训练卡死在 healthz 轮询最多 60 秒优先检查 8181 是否被占用、/tmp/agl-server-*.log是否报错Minikube 内存K8s 模式必须保证--memory6553664GBCPU 建议 16 核--driverdocker超时对齐rollout_timeout_seconds300、Agent 内asyncio.wait_for300与 MCPread_timeout_seconds120是三层超时若题目难度导致超时率升高应同步放宽而非只改其一数据字段契约Agent 只依赖样本的question与result两个字段由env_map与 Job 模板共同约定更换数据集时需保证同名字段存在K8s 资源请求偏小Job 模板只请求 200m CPU / 256Mi 内存这是合理的——Agent 进程只做 API 调用与 MCP stdio 子进程计算全部发生在被训练模型一侧。小结Calc-X 示例用最小的资源单卡、1.5B 模型把 Agent Lightning 的核心闭环演示完整数据以 parquet/jsonl 提供 →train_calc_agent.py以 Hydra 合并 VERL 基础配置与示例覆盖项 →run_ppo启动 Ray AgentLightningRayPPOTrainer →agl-server/agl-controller按 Local 或 K8s Runner 把 AutoGenMCP Agent 跑起来 → reward 事件回传并按 GRPO 更新策略。想继续深入可以沿着本文引用的 run_local.sh、train_calc_agent.py、agentlightning/verl/entrypoint.py 与 agentlightning/verl/config.yaml 阅读对应实现。【免费下载链接】agent-lightningThe absolute trainer to light up AI agents.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-lightning创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
