企业官网建设流程全解析

Agent Lightning：约 3,500 行核心 Python 的轻量级 Agentic RL 训练框架——架构、安装与三组件实践

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

Agent Lightning 是微软开源的 Agentic RL（智能体强化学习）基础设施，其 v1.0 版本以"简洁为第一原则"，用约 3,500 行核心 Python 代码实现了一套完整的训练系统。本文以仓库 README 为主线，深入拆解它的三大组件（Trainer、API Gateway、Rollout Controller）的源码实现、安装配置方式与实战示例体系，读完你可以掌握如何用真实 Agent harness 零改动接入 RL 训练、如何配置 API 网关与控制器，以及如何在本地或 Kubernetes 上跑通端到端训练流程。

项目定位与核心特性

Agent Lightning 的核心主张是"用真实的 Agent harness 训练 Agent"：Agent 通过 Agent Lightning v1.0 的代理（proxy）与模型交互，代码零改动，同时把工具、上下文、控制流和环境都保留在训练回路中。README 列出的四大特性是：

• 约 3,500 行核心 Python：项目把简洁当作第一设计原则。从源码结构看，agentlightning/包下的 Python 代码总量（含 verl 集成层）实测约为 4,350 行，其中最大的文件是 trainer.py（771 行）、rollout_adapter.py（563 行）和 agl_rollout_manager.py（543 行），体量确实轻量。
• 与真实 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、kr8s（Kubernetes 客户端）、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 创建 rollout，Controller 启动 Agent，Gateway 把交互过程转化为训练数据，而 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，几个值得注意的实现细节：

1. 参数重写：ProxyRouter.prepare_body()会把上游请求重写为网关配置指定的model、温度（train/val 模式分开），并强制注入return_token_ids: True——通过 OpenAI 兼容 API 直接返回 token ID，避免训练侧重新分词（retokenization）带来的漂移问题；训练模式下还根据include_log_probs附加logprobs: True。
2. 前缀缓存友好的路由：select_server()用sha256(rollout_id)对上游服务器池取模，稳定地把每个 rollout 钉在一个端点上，以复用 vLLM 前缀缓存。
3. 上游重试：最多 6 次尝试，仅对 408/409/429 和 5xx 状态码重试，指数退避（0.5s 起步、上限 8s，并带 0.75–1.25 随机抖动）；超时最终抛出 504，传输错误抛出 502。
4. 事件捕获：每次转发都会调用record_event()落一条model_request事件，包含完整请求/响应体、模型与版本、延迟、HTTP 状态、重试次数、usage 与 finish_reason——这正是"把交互转化为训练数据"的落点，Trainer 后续从这些事件聚合出轨迹。
5. 暂停机制：ProxyPauseState支持在权重更新窗口暂停转发，暂停时返回 429 +Retry-After+X-Agl-Paused: true，并统计 in-flight 请求数，这是异步训练 pause/drain 流程的基础（详见异步训练文档）。
6. 限制：流式响应（stream: true）会直接返回 400，训练链路只支持非流式。

Gateway 的默认配置在 server.yaml：

host: 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 两种方式运行 Agent

Controller 负责消费 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 Job（Pod），通过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 可以确认两处定制：

1. 使用AgentLightningRayPPOTrainer（RayPPOTrainer的子类）驱动 rollout，通过 Agent Lightning HTTP API 而不是原生 verl 的 agent loop worker；
2. 支持预加载的内存数据集（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_key：Trainer 访问 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/目录：

仓库内置了六个由浅入深的端到端示例（文档与代码一一对应）：

每个示例目录都提供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 AgentFlow（Flow-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 预期，大多数贡献需要签署 CLA（Contributor 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