ARTICLE DETAIL

资讯详情

深耕网站建设、视觉设计与SEO优化的一线实战洞察。

Agent Lightning Controller 配置实践:用 Hydra 配置 k8s 与 local 两种 rollout 执行后端

Agent Lightning Controller 配置实践:用 Hydra 配置 k8s 与 local 两种 rollout 执行后端 Agent Lightning Controller 配置实践用 Hydra 配置 k8s 与 local 两种 rollout 执行后端【免费下载链接】agent-lightningThe absolute trainer to light up AI agents.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-lightningAgent Lightning 中的 Controller 负责把声明式的 rollout 翻译成真实的 Agent 执行它从 API Gateway 领取QUEUING状态的 rollout在 Kubernetes Job 或本地子进程中运行 Agent并把执行结果回写状态。本文基于docs/6-controller-configuration.md结合agentlightning/controller/下的入口、K8s 协调器与本地协调器源码完整讲解 Controller 的启动方式、Hydra 默认配置、命令行覆盖、两种 runner 的连接与限流参数以及 Agent 进程的最终注入机制帮助读者掌握可复制、可运行的 Controller 部署与调优方案。Controller 是什么、如何启动Controller 通过agl-controller命令启动。这个命令入口在 pyproject.toml 中注册[project.scripts] agl-server agentlightning.server.__main__:main agl-controller agentlightning.controller.__main__:main入口函数定义在 agentlightning/controller/main.py它是一个标准的 Hydra 应用hydra.main(version_baseNone, config_path../config, config_namecontroller) def main(config: DictConfig) - None: asyncio.run(_run_controller(config))从源码结构看启动流程分为三步Hydra 加载完整默认配置配置组目录为../config即 agentlightning/config/controller.yaml_run_controller用config.agl_server.url和config.agl_server.key创建AgentLightningAsyncClient作为访问 API Gateway 的通道根据config.runner_type分支k8s时导入K8sReconciler该路径在main.py 中是延迟导入若缺少kr8s会抛出提示安装 controller 依赖的RuntimeErrorlocal时导入LocalReconciler其它取值直接抛ValueError。此外入口还为SIGTERM/SIGINT注册了信号处理器main.py收到信号后调用reconciler.stop()优雅退出——对本地模式而言这意味着正在运行的 Agent 子进程会被终止并标记为 FAILED详见下文本地协调器部分。项目要求 Python ≥ 3.12并固定使用hydra-core1.3.2与omegaconf2.3.0见 pyproject.toml 的dependencies因此下述配置语法均以 Hydra 1.3 为准。完整默认配置Controller 的完整默认配置来自 agentlightning/config/controller.yaml全文如下runner_type: k8s agl_server: url: http://localhost: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其中runner_type是全局开关决定后四组参数中哪一组生效k8s模式读取k8s_runner.*local模式读取local_runner.*。其余配置对两种模式都生效尤其是agl_server.*。用 Hydra 命令行覆盖配置启动时可以用任意 Hydra 命令行参数覆盖配置中的任意一项无需修改 YAML 文件。例如切换到本地模式、指定 API Gateway 地址与鉴权 key、缩小进程池agl-controller \ runner_typelocal \ agl_server.urlhttp://localhost:8080 \ agl_server.key$AGL_KEY \ local_runner.maximum_size32这种覆盖方式与项目其它组件Trainer、API Gateway保持一致agl_server.key必须与 API Gateway 的 key 一致否则请求会被拒绝。runner_typek8s 与 local 二选一键默认值说明runner_typek8s本 Controller 实例使用的唯一执行后端k8s或local一个 Controller 实例同一时间只能运行一种模式不能混用。两种模式的执行语义为k8s 模式每个 rollout 运行为一个 Kubernetes Job。Controller 使用本机~/.kube/config的默认 Kubernetes 配置访问集群——从源码看协调器通过kr8s.asyncio.api()惰性初始化集群客户端见 k8s_reconciler.py这正是依赖默认 kubeconfig 的原因local 模式每个 rollout 运行在 Controller 所在机器上的一个本地子进程中多个 rollout 由进程池统一调度。连接 API Gateway两个 URL、一个 keyController 配置中包含两个 API Gateway URL对应两条不同的网络路径键默认值说明agl_server.urlhttp://localhost:8080Controller 自身使用的 API Gateway 地址agl_server.agent_urlnullAgent 使用的 API Gateway 地址为null时回退到agl_server.urlagl_server.keyController 与 Agent 共用的 Bearer key两者可达性的要求不同agl_server.url必须能从 Controller 进程访问因为 Controller 用它查询和打补丁/api/rolloutsagl_server.agent_url必须能从 Agent 进程或 Pod访问因为注入到 Agent 的 Gateway 代理地址和事件上报地址就是基于它拼出来的。大多数场景下agent_url保持null即可Agent 自动复用agl_server.url。只有当 Agent 无法通过agl_server.url到达 Gateway 时才需要单独设置——典型场景是 Minikube Docker driverController 跑在宿主机上Agent 跑在 Minikube 内部两者网络不通。此时 Controller 侧可用http://localhost:8080而 Agent 侧需要http://host.minikube.internal:8080访问同一个 Gatewaycontroller.yaml 中的注释也给出了这个示例。源码印证了这个回退逻辑构造 Job 时k8s_reconciler.py 以agent_url优先、url兜底的方式确定 Agent 侧基址agent_base_url str( controller_config.agl_server.get(agent_url, None) or controller_config.agl_server.url ).rstrip(/)本地模式同样如此local_reconciler.py 用self._config.agl_server.url拼接注入的环境变量。k8s_runnerJob 创建限流与完成清理键默认值说明k8s_runner.namespacedefaultJob 创建的命名空间k8s_runner.max_jobs_per_minute100Controller 每分钟最多创建的 Kubernetes Job 数k8s_runner.ttl_after_finished1200完成的 Job 被 Kubernetes 自动删除前保留的秒数k8s_runner.poll_interval5周期性对账循环的间隔秒数max_jobs_per_minute防止 Controller 在短时间内创建过多 Jobttl_after_finished防止已完成的 Job 堆积、压垮 Kubernetes API server。从源码看这两个参数的落地机制很明确限流采用 60 秒滑动窗口。K8sReconciler用一个deque记录每次成功创建 Job 的时间戳k8s_reconciler.py每次创建前先丢弃 60 秒常量JOB_CREATION_WINDOW_SECONDS 60之前的时间戳若窗口内计数达到max_jobs_per_minute则记录日志并延迟本轮创建——rollout 保持QUEUING状态等下一轮对账再来不会失败。若创建时遇到 422/Unprocessable/invalid等非法规格错误rollout 会被直接标记为FAILED并附带错误信息避免反复重试坏模板。TTL 直接写入 Job spec。build_job_spec 把ttl_after_finished写进spec.ttlSecondsAfterFinished同时强制backoffLimit: 0与restartPolicy: Never保证每个 rollout 只执行一次、失败不重试、完成后由集群自动清理。若 rollout 配置了timeout_seconds还会写入spec.activeDeadlineSeconds作为 K8s 侧的超时兜底。双循环架构。K8sReconciler.run()并发运行两个任务k8s_reconciler.py_periodic_reconcile_loop——按poll_interval轮询QUEUING/RUNNING状态的 rollout与集群中带app.kubernetes.io/managed-byagentlightning标签的 Job 对账为缺失的 QUEUING rollout 创建 Job发现 RUNNING rollout 对应的 Job 消失时标记为FAILEDJob disappeared_watch_jobs_loop——用kr8s.asyncio.watch监听 Job 的ADDED/MODIFIED事件Job 出现Complete/Failedcondition 时立即把 rollout 更新为SUCCEEDED/FAILEDwatch 中断后自动 5 秒重连。也就是说poll_interval影响的是新 rollout 何时被领取的延迟而完成事件主要由 watch 循环低延迟处理。local_runner本地进程池的并发与同步键默认值说明local_runner.maximum_size50Controller 机器上并发管理的 Agent 子进程数上限local_runner.poll_interval10本地进程与 rollout 状态自动同步检查的间隔秒数当进程池达到maximum_size时排队的 rollout 会等待容量释放。源码层面local_reconciler.py每轮_reconcile_once会拉取QUEUING/RUNNING状态、limit 50 的 rollout 列表统计存活子进程数returncode is None仅为QUEUING且未达maximum_size的 rollout 派生子进程发现RUNNING状态但本地无对应进程时例如 Controller 重启过标记FAILEDlocal subprocess is not running保证状态不会悬挂对已超时的子进程发送SIGKILL整个进程组并标记FAILEDlocal subprocess timed out。子进程本身以sys.executable -c方式启动一个 workerstart_new_sessionTrue使每个 Agent 处于独立进程组超时和 Controller 关闭时都能用os.killpg干净地连根终止local_reconciler.py。退出码为 0 则 rollout 标记SUCCEEDED否则FAILED并附带退出码Controller 收到停止信号时存活子进程会被终止并标记为FAILEDlocal controller shutdown最后做一次收尾对账。两种模式下 Agent 是如何被拉起的k8s 模式渲染 Jinja Job 模板。Trainer 配置中的agentlightning.k8s.job_template_path指定模板文件模板写法与示例见 docs/4-trainer-configuration.md 的 Rollout execution 小节仓库中 examples/calc_x/job-template.yaml 是一个可直接参考的完整示例。模板文本被 Trainer 读入并写入每个 rolloutController 侧的build_job_speck8s_reconciler.py负责最终渲染与装配用 rollout 的input和确定性job_nameagl-rollout-{rollout_id}渲染 Jinja 模板模板中可用的过滤器包括yaml_escape用于把输入安全地写进 YAML 字符串渲染结果必须是且仅是一个kind: Job的 YAML 文档否则报错补全metadata.name/metadata.namespace来自k8s_runner.namespace和管理标签app.kubernetes.io/managed-by、agentlightning/rollout-id、agentlightning/attempt-id供 watch 与对账反查向每个容器注入 rollout 专属的三个环境变量AGL_OPENAI_BASE_URL指向 Gateway 的该 rollout 代理路径含 train/val mode、AGL_EVENT_URL该 rollout 的事件上报端点和AGL_KEY。若模板里已定义同名变量则以 Controller 注入值覆盖。tests/controller/test_k8s_reconciler.py 在无集群环境下验证了上述行为断言标签集合、AGL_KEY注入以及AGL_OPENAI_BASE_URL中包含/rollout/test-id/attempt/0/mode/train/路径可以作为模板正确性的参照。local 模式agent_class env_map。Controller 从 rollout 中读取config.local.agent_class与config.local.env_map动态导入 Agent 类支持module.Class或module:Class两种写法在子进程中实例化并调用run()兼容同步与协程见 local_reconciler.py。env_map把环境变量名映射到 rolloutinput中的字段路径local_reconciler.py支持点路径如input.question以及列表索引如input.answers.0值为字符串时原样注入非字符串如列表、字典自动json.dumps后注入不可序列化时直接报错路径在input中找不到会抛出local.env_map path not found错误。例如 Trainer 侧配置agentlightning: local: agent_class: examples.search_r1.agents.search_r1_agent.SearchR1Agent env_map: QUESTION: input.question GOLDEN_ANSWERS: input.golden_answersController 就会为每个 rollout 导入SearchR1Agent、启动一个本地子进程并从该 rollout 的input中取出QUESTION、GOLDEN_ANSWERS环境变量。与 k8s 模式一样rollout 专属的AGL_OPENAI_BASE_URL、AGL_EVENT_URL、AGL_KEY会自动注入。适用前提与配置要点小结两种模式共用一套agl_server连接配置key需要与 API Gatewayagentlightning/config/server.yaml 中的key字段以及 Trainer 的agentlightning.agl_key保持完全一致k8s 模式要求 Controller 机器可读取~/.kube/config且对k8s_runner.namespace有 Job 操作权限local 模式则要求 Controller 机器上能直接导入并运行agent_class即 Agent 代码及其依赖必须安装在 Controller 环境里rollout 的timeout_secondsTrainer 配置中的agentlightning.rollout_timeout_seconds默认 1800在两种模式下都由 Controller 负责执行k8s 侧体现为activeDeadlineSecondslocal 侧体现为进程组SIGKILL默认值Job 限流 100/分钟、TTL 20 分钟、本地并发 50、本地轮询 10 秒是通用起点实际训练中可按集群 API server 负载与 Controller 机器 CPU/内存容量通过 Hydra 命令行参数逐项调整无需改动 YAML。参考文件docs/6-controller-configuration.md、agentlightning/config/controller.yaml、agentlightning/controller/main.py、agentlightning/controller/k8s_reconciler.py、agentlightning/controller/local_reconciler.py、tests/controller/test_k8s_reconciler.py。【免费下载链接】agent-lightningThe absolute trainer to light up AI agents.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-lightning创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表