Agent Lightning：约 3,500 行核心 Python 的轻量级 Agentic RL 训练框架——架构、安装与三组件实践
发布时间：2026/9/13 23:56:59 作者：尧图编辑部 阅读量：1,286
Agent Lightning约 3,500 行核心 Python 的轻量级 Agentic RL 训练框架——架构、安装与三组件实践【免费下载链接】agent-lightningThe absolute trainer to light up AI agents.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-lightningAgent Lightning 是微软开源的 Agentic RL智能体强化学习基础设施其 v1.0 版本以简洁为第一原则用约 3,500 行核心 Python 代码实现了一套完整的训练系统。本文以仓库 README 为主线深入拆解它的三大组件Trainer、API Gateway、Rollout Controller的源码实现、安装配置方式与实战示例体系读完你可以掌握如何用真实 Agent harness 零改动接入 RL 训练、如何配置 API 网关与控制器以及如何在本地或 Kubernetes 上跑通端到端训练流程。项目定位与核心特性Agent Lightning 的核心主张是用真实的 Agent harness 训练 AgentAgent 通过 Agent Lightning v1.0 的代理proxy与模型交互代码零改动同时把工具、上下文、控制流和环境都保留在训练回路中。README 列出的四大特性是约 3,500 行核心 Python项目把简洁当作第一设计原则。从源码结构看agentlightning/包下的 Python 代码总量含 verl 集成层实测约为 4,350 行其中最大的文件是 trainer.py771 行、rollout_adapter.py563 行和 agl_rollout_manager.py543 行体量确实轻量。与真实 harness 无缝衔接Agent 侧只需把模型请求指向 Agent Lightning 的代理端点工具调用、多轮对话、环境交互全部照常运行。原生 Kubernetes 支持Agent 可以直接以 Kubernetes Job 的方式运行不依赖外部沙箱服务。完整编码 Agent 训练案例仅用 6K 训练样本端到端的 Qwen3.5-9B 工作流将 SWE-bench Verified 从 41.8% 提升到 56.4%提升 14.6 个百分点仓库同时开源了包括数据清洗、防止 reward-hacking 和训练脚本在内的完整流水线见 examples/swe_smith。注意版本前提Agent Lightning 在 v1.0 经历了完全重构本文所有内容均基于 v1.0 架构v0.x 及更早的旧版本与本文描述的三组件架构不兼容需查看官方仓库的历史分支。安装与环境README 给出了在 CUDA 13.0 机器上的示例安装命令cd this-repo uv sync bash scripts/setup_verl.sh 0.8.0 cu130其中uv sync基于 pyproject.toml 同步基础依赖。该文件声明项目名为agentlightning、版本1.0.0要求Python 3.12核心依赖包括fastapi、uvicorn、pydantic、httpx、hydra-core、omegaconf、structlog、kr8sKubernetes 客户端、pyyaml等scripts/setup_verl.sh 0.8.0 cu130负责安装verlGPU 训练栈0.8.0 版本、cu130 CUDA 构建参数即 verl 版本与 CUDA 工具链版本不同机器需按实际 CUDA 版本调整。安装完成后pyproject.toml 中的[project.scripts]段注册了两个可执行入口对应架构中的两大独立进程agl-server agentlightning.server.__main__:main agl-controller agentlightning.controller.__main__:main即 API Gateway 通过agl-server启动Rollout Controller 通过agl-controller启动Trainer 则通过 verl 入口启动见下文架构部分。更详细的环境搭建与 GPU 栈说明见 安装指南。架构三个轻量组件如何协作Agent Lightning v1.0 保持了极简的训练架构只包含三个轻量组件组件职责对应源码位置Trainer运行verl和 vLLM构建训练样本更新策略agentlightning/verlAPI Gateway代理模型请求捕获训练数据agentlightning/serverRollout Controller在本地或 Kubernetes 上运行 Agentagentlightning/controller三者协作关系为Trainer 创建 rolloutController 启动 AgentGateway 把交互过程转化为训练数据而 Agent 继续运行在其真实的 harness 中。下面按组件展开源码级的实现要点。API Gateway代理模型请求并捕获训练数据Gateway 是一个 FastAPI 应用。从 app.py 可以看到应用通过create_app()创建lifespan 中初始化ProxyPauseState暂停状态、ProxyRouter代理路由和带 300 秒超时的httpx.AsyncClient/healthz健康检查接口不鉴权/api下的 rollouts、events、models 路由与代理路由都要求 Bearer API Key 认证未设置 key 时会记录authentication disabled警告明确提示不用于生产环境认证同时支持Authorization: Bearer key与x-api-key两种头见app.py的_build_auth_dependency。代理的核心逻辑在 proxy.py几个值得注意的实现细节参数重写ProxyRouter.prepare_body()会把上游请求重写为网关配置指定的model、温度train/val 模式分开并强制注入return_token_ids: True——通过 OpenAI 兼容 API 直接返回 token ID避免训练侧重新分词retokenization带来的漂移问题训练模式下还根据include_log_probs附加logprobs: True。前缀缓存友好的路由select_server()用sha256(rollout_id)对上游服务器池取模稳定地把每个 rollout 钉在一个端点上以复用 vLLM 前缀缓存。上游重试最多 6 次尝试仅对 408/409/429 和 5xx 状态码重试指数退避0.5s 起步、上限 8s并带 0.75–1.25 随机抖动超时最终抛出 504传输错误抛出 502。事件捕获每次转发都会调用record_event()落一条model_request事件包含完整请求/响应体、模型与版本、延迟、HTTP 状态、重试次数、usage 与 finish_reason——这正是把交互转化为训练数据的落点Trainer 后续从这些事件聚合出轨迹。暂停机制ProxyPauseState支持在权重更新窗口暂停转发暂停时返回 429 Retry-AfterX-Agl-Paused: true并统计 in-flight 请求数这是异步训练 pause/drain 流程的基础详见异步训练文档。限制流式响应stream: true会直接返回 400训练链路只支持非流式。Gateway 的默认配置在 server.yamlhost: 0.0.0.0 port: 8080 key: default_proxy: model_name: Qwen/Qwen2.5-7B-Instruct include_log_probs: True train: temperature: 1 val: temperature: 0.7即默认监听 8080 端口、默认代理到Qwen/Qwen2.5-7B-Instruct训练温度 1、验证温度 0.7。完整参数说明见 API Gateway 配置文档。Rollout Controller本地或 Kubernetes Job 两种方式运行 AgentController 负责消费 Gateway 中的 rollout 任务并拉起 Agent。默认配置 controller.yaml 展示了全部关键参数runner_type: k8s # k8s | local agl_server: url: http://localhost:8080 # Agent Pod 可达的外部 URL不设置则回退到 agl_server.url # minikube docker driver 示例agent_url: http://host.minikube.internal:8080 agent_url: null key: k8s_runner: namespace: default ttl_after_finished: 1200 max_jobs_per_minute: 100 poll_interval: 5 local_runner: maximum_size: 50 poll_interval: 10两种运行器各有实现本地运行器local_reconciler.py以进程方式直接拉起local.agent_class指定的 Agent 类受maximum_size控制并发上限Kubernetes 运行器k8s_reconciler.py把每个 rollout 物化为一个 Kubernetes JobPod通过ttl_after_finished自动清理已完成 Job用max_jobs_per_minute限流配合agent_url解决 Pod 回连宿主机的网络问题kr8s库提供 K8s 客户端能力。这种 reconcile 模式意味着 Controller 是目标状态驱动的它轮询 Gateway 的 rollout 状态保证应有 N 个运行中的 Agent Job实际不足则补齐。相关设计图见官方文档中的控制器调和示意图完整说明见 Controller 配置文档。Trainer基于 verl 的 PPO 训练循环Trainer 组件把 rollout 编排接管到 Agent Lightning 的 HTTP API 中。从 entrypoint.py 的模块 docstring 可以确认两处定制使用AgentLightningRayPPOTrainerRayPPOTrainer的子类驱动 rollout通过 Agent Lightning HTTP API 而不是原生 verl 的 agent loop worker支持预加载的内存数据集LoadedDataset。run_ppo()的调用链是初始化 Ray并在每个 Ray worker 进程中通过worker_process_setup_hook注册自定义 policy lossagentlightning.verl.per_rollout_loss.register_in_worker→ 复用 verl 的TaskRunner完成 worker 组建与配置校验 → 实例化AgentLightningRayPPOTrainer并执行trainer.fit()。Trainer 与 Gateway 之间通过 rollout_adapter.py 的AgentLightningSyncClient/AgentLightningAsyncClient见 client.py内置带指数退避的重试 POST通信。Trainer 侧默认配置 verl/config.yaml 中agentlightning段是核心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: calculate_entropy: true policy_loss: loss_mode: per_rollout_mean rollout: mode: async关键项含义agl_base_url/agl_keyTrainer 访问 API Gateway 的地址与密钥trace_aggregator.level轨迹聚合粒度transition单步或trajectory整条轨迹默认对应仓库提供的 轨迹级聚合实现 与 per_rollout_loss 实现async_rollout.enabled是否启用 colocated 异步采集含 pause/drain默认关闭policy_loss.loss_mode: per_rollout_mean按 rollout 取均值的自定义损失与per_rollout_loss.py中的注册逻辑对应。verl 集成与 trace 聚合的完整讲解见 Trainer 配置文档。训练结果官方在多个实用训练域上评估了 v1.0包括 Search R1、LLM-in-Sandbox 和 Coding Agent纯 RL 在三个域上均带来显著提升其中最具代表性的是编码 Agent 案例6K 训练样本下 SWE-bench Verified 从 41.8% 提升至 56.4%。对应的完整流水线数据清洗、reward-hacking 防护、训练脚本、镜像拉取工具见 examples/swe_smith包括 train_smith_agent.py、pull_images.py 与 swe_smith_chat_template.jinja 等文件。文档导航与示例体系README 把文档组织为基础篇 配置篇 示例篇三层全部位于docs/目录文档内容安装指南基础环境与verlGPU 栈快速上手本地首次运行与端到端流程基础概念组件、rollout、事件与轨迹Trainer 配置verl集成与 trace 聚合API Gateway 配置网关与模型代理设置Controller 配置本地与 Kubernetes 运行器异步训练Collocated 异步采集与 pause/drain仓库内置了六个由浅入深的端到端示例文档与代码一一对应示例说明Calc-XPOC 数学推理示例基于 AutoGen 与 MCP 计算器工具单卡即可运行代码见 examples/calc_xGSM8KPOC 小学数学推理示例代码见 examples/gsm8kScienceWorld文本环境中的交互式科学任务代码见 examples/science_worldSearch-R1多轮检索与推理 Agent含检索服务端与数据加工脚本代码见 examples/search_r1LLM-in-Sandbox带计算机操作与代码执行工具的通用 Agent代码见 examples/llm-in-sandboxCoding Agent用仓库测试训练的编码 Agent代码见 examples/swe_smith每个示例目录都提供run_local.sh或run.sh脚本与对应的训练入口脚本读者可以从最小算力要求的 Calc-X 起步逐步过渡到 Kubernetes 部署的复杂示例。生态、引用与许可README 还汇总了围绕 Agent Lightning 的公开技术文章包括官方博客轨迹级聚合加速训练、vLLM 博客通过 OpenAI 兼容 API 返回 token ID 以避免 retokenization 漂移——与上文代理中return_token_ids: True的实现相互印证、arXiv 论文编号 2508.03680以及多篇 Medium 实践文章SQL 训练、与 Tinker 的集成等。社区方面DeepWerewolf狼人杀 Agent RL 案例、Stanford AgentFlowFlow-GRPO 多智能体框架、腾讯 Youtu-Agent基于修改分支验证至 128 卡 RL 训练等项目都构建在该框架之上。如果该框架对你的研究或项目有帮助README 提供了引用信息misc{luo2025agentlightningtrainai, title{Agent Lightning: Train ANY AI Agents with Reinforcement Learning}, author{Xufang Luo and Yuge Zhang and Zhiyuan He and Zilong Wang and Siyun Zhao and Dongsheng Li and Luna K. Qiu and Yuqing Yang}, year{2025}, eprint{2508.03680}, archivePrefix{arXiv}, primaryClass{cs.AI}, }贡献方面README 说明项目欢迎贡献要求阅读贡献指南了解环境搭建、分支规范与 PR 预期大多数贡献需要签署 CLAContributor License Agreement项目遵循微软开源行为准则。最后Agent Lightning v1.0 以MIT 许可证发布见 LICENSE并声明已通过微软 Responsible AI Standard 的评估与认证。小结Agent Lightning v1.0 的设计可以概括为三句话用verl vLLM 的 Trainer 负责算用零改动的 OpenAI 兼容代理 Gateway 负责收用本地/K8s 双模的 Controller 负责跑。得益于约 3,500 行核心代码的克制设计从 安装脚本、两份默认 配置 到六套完整示例整个框架的学习成本和二次开发成本都被压得很低——这也是它区别于重型 RL 训练框架的核心竞争力。【免费下载链接】agent-lightningThe absolute trainer to light up AI agents.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-lightning创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
尧图网站开发 