AReaL CLI 实战指南统一管理训练、推理与 Agent 服务的命令行入口【免费下载链接】AReaLThe RL Bridge for LLM-based Agent Applications. Made Simple Flexible.项目地址: https://gitcode.com/GitHub_Trending/are/AReaLAReaL 在 2.0 微服务架构下提供了areal操作者 CLI通过train、inf、agent三个顶层子命令组分别覆盖训练实验、本机推理服务和本机 Agent 服务的启动与管理。本文以官方文档 docs/zh/best_practices/cli_guide.md 为主体结合 CLI 源码 areal/v2/cli 与配置解析实现 areal/api/cli_args.py完整讲解三个子命令组的用法、生命周期模型、配置文件与源码级实现原理读完后你可以直接上手跑通一条训练实验、拉起一个带 SGLang 后端的推理服务、并部署一套多副本的 Agent 服务。三个顶层子命令组训练、推理、AgentarealCLI 的三个子命令组各自对应一种服务形态入口在 areal/v2/cli/cli.py 中通过cli.add_command(agent)、cli.add_command(inf)、cli.add_command(train)注册areal train— 解析实验 driver 与配置文件转发 hydra 覆盖参数将控制权交给训练脚本。它不管理训练进程的生命周期只做「找到 driver、加载配置、透传参数」三件事刻意保持无状态。areal inf— 启动并管理本机上的推理服务gateway、router、model worker、data proxy负责注册模型、查看状态、管理日志与清理。areal agent— 启动并管理本机上的 agent 服务gateway、router、N 对 worker />result fn(argv) if isinstance(result, int): return result return 0用法与参数说明areal train run \ --config path/to/experiment.yaml \ --driver module.path:func \ [hydra-override-1 hydra-override-2 ...]flag / arg是否必填说明--config是实验 YAML 路径文件必须存在CLI 会执行exists检查--driver是driver 入口形如module.path:func冒号分隔尾部位置参数否原样转发给 driver通常是 hydra 风格的keyvalue覆盖参数run_cmd启用了context_settings{ignore_unknown_options: True}——尾部位置参数可以包含--xxx形式的选项CLI 不会去解析它们而是原样转发给 driver。实现上尾部参数通过click.argument(overrides, nargs-1, typeclick.UNPROCESSED)接收--config则声明为typeclick.Path(existsTrue, dir_okayFalse, path_typePath)文件不存在时由 click 直接拦截报错。典型示例运行 GSM8K GRPO最常见的 baselineareal train run \ --config examples/math/gsm8k_grpo.yaml \ --driver examples.math.gsm8k_rl:main \ experiment_namegsm8k_grpo_test \ trial_namet1运行 SFTareal train run \ --config examples/math/gsm8k_sft.yaml \ --driver examples.math.gsm8k_sft:main对应的实验配置与 driver 脚本都位于 examples/math 目录例如 examples/math/gsm8k_grpo.yaml 与 examples/math/gsm8k_rl.py。Driver 函数约定CLI 用单个参数argv: list[str]调用 driver因此 driver 长这样def main(args: list[str]) - int | None: config, _ load_expr_config(args, GRPOConfig) # 或任意其他 *Config dataclass ... return 0load_expr_config位于 areal.api.cli_args实现见该文件load_expr_config定义处约 areal/api/cli_args.py#L4240。它自己消费args识别--config后面的 YAML 路径将剩余的keyvalue作为 hydra 覆盖合并进 config dataclass。也就是说hydra 解析是由 driver 完成而不是由 CLI 完成。其内部流程是parse_cli_args解析原始 argv →to_structured_cfg将 DictConfig 结构化到目标 dataclass →OmegaConf.to_object转回 Python 对象随后还会把解析结果以config.yaml形式保存到StatsLogger的日志目录save_config敏感字段会被redact_sensitive_config脱敏。编写新 driver 的最小模板from areal.api.cli_args import GRPOConfig, load_expr_config from areal import PPOTrainer def main(args): config, _ load_expr_config(args, GRPOConfig) with PPOTrainer(config, train_dataset..., valid_dataset...) as trainer: trainer.train(workflow..., workflow_kwargs{...}) return 0Hydra 覆盖参数所有使用load_expr_config解析参数的 driver 都支持 hydra 风格覆盖。常见覆盖目标# 实验 / trial 命名 experiment_namemy_run trial_namet1 # 集群规模 cluster.n_nodes4 cluster.n_gpus_per_node8 # 训练超参 actor.optimizer.lr5e-6 total_train_epochs20 # rollout backend rollout.backendsglang:d2p1t2 rollout.max_concurrent_rollouts128 # 数据集 train_dataset.batch_size256CLI不会校验这些 key 是否合法driver 加载配置时 hydra 会报告未知字段。值得注意的是actor.optimizer.lr这类点分路径会命中OptimizerConfig中的lr、warmup_steps_proportion、warmup_steps等字段见 areal/api/cli_args.py 中OptimizerConfigdataclass 定义默认lr1e-3、warmup_steps_proportion0.001且当warmup_steps与比例同时显式配置时以warmup_steps为准并给出警告。退出码约定场景退出码driver 返回int直接使用其返回值driver 返回None/ 其他0--driver不包含:UsageErrorclick 默认 2--driver引用的模块无法导入ClickException1--driver引用的函数不在模块上ClickException1--config路径不存在click 的existsTrue捕获2driver 内部抛出的异常CLI 不做捕获——走 Python 默认行为打印 traceback、退出进程。尚未实现areal train目前只实现了run命令定义见 areal/v2/cli/training/commands/run.py。下列子命令是合理的未来扩展但当前版本未包含areal train ps/status/stop—— 训练任务生命周期管理需要先引入训练服务的状态概念。推理服务 CLIareal infareal inf用于在本机启动并管理 AReaL 推理服务。它会启动 gateway/router、注册模型、查看服务状态、管理日志。基础概念一个推理服务通常包含以下组件gateway对外提供 OpenAI 兼容 API 与 RL API。router维护「模型 → worker />export AREAL_HOME/path/to/areal-home从源码 areal/v2/cli/inference/commands/run.py 看run启动时会依次拉起 router 与 gatewayrouter 固定绑定127.0.0.1随机端口gateway 绑定用户指定的 host/port并把TaskHandle进程 PID、端口、GPU 设备持久化到ServiceState同时把模型列表持久化到ModelState。启动过程中的健康检查由wait_client_health完成默认--launch-timeout 30.0秒等待 gateway/health注册模型时默认--model-health-timeout 600.0秒等待模型服务器就绪。启动服务启动一个空的推理服务areal inf run \ --service default \ --host 127.0.0.1 \ --port 8080 \ --admin-api-key areal-admin-key \ --scheduler local \ --detach--scheduler用于选择 worker />areal inf ps areal inf status --service defaultps展示服务列表status深入到 gateway、router、data-proxy、worker 等各组件的状态。列出已注册的模型areal inf models --service default注册模型register让 CLI 启动一个本地推理后端并配一个>areal inf register \ --service default \ --model-name qwen-local \ --backend sglang:d1 \ --model-path Qwen/Qwen2.5-7B-Instruct \ --tokenizer-path Qwen/Qwen2.5-7B-Instruct \ --engine-args --mem-fraction-static 0.8 \ --proxy-args --request-timeout 120 --chat-template-type hf--engine-args是一个 shell 风格字符串原样转发给 sglang / vllm 的 worker 进程--proxy-args是>areal inf run \ --service default \ --port 8080 \ --admin-api-key areal-admin-key \ --model qwen-local \ --backend sglang:d1 \ --model-path Qwen/Qwen2.5-7B-Instruct \ --engine-args --mem-fraction-static 0.8 \ --proxy-args --request-timeout 120 --chat-template-type hf \ --detach注意--model相关的注册参数--backend等只在指定了--model时才合法否则run会抛出UsageError(model registration flags require --model.)。普通推理请求模型注册好后可以直接调用 gateway 的 OpenAI 兼容接口curl -sS http://127.0.0.1:8080/v1/chat/completions \ -H Authorization: Bearer areal-admin-key \ -H Content-Type: application/json \ -d { model: qwen-local, messages: [ {role: user, content: Hi, give me a quick intro to AReaL.} ], max_tokens: 128 }日志与清理查看日志areal inf logs --service default --component gateway -f areal inf logs --service default --component router -f areal inf logs --service default --component qwen-local-worker-0 -f areal inf logs --service default --component qwen-local-data-proxy-0 -f每个模型的 worker />areal inf deregister --service default --model-name qwen-local停止服务areal inf stop --service default强制停止areal inf stop --service default --force配置文件areal inf会从下面这个默认配置文件读取默认值~/.areal/inf/config.toml也可以另外传入配置文件areal inf --config ./inf.toml run --service default --detach示例[default] service default [launch] gateway_host 127.0.0.1 gateway_port 8080 routing_strategy round_robin [scheduler] type local [register.internal] backend sglang:d1 model_health_timeout 600 engine_args --mem-fraction-static 0.8 proxy_args --request-timeout 120 --chat-template-type hfAgent 服务 CLIareal agentareal agent用于在本机启动一组 agent 服务进程gateway / router N 对 worker />export AREAL_HOME/path/to/areal-home从源码 areal/v2/cli/agent/commands/run.py 看do_run首先强制校验--agent必填缺失抛UsageError(--agent is required)随后通过launch_agent_stack一次性拉起整条栈gateway router N 对 worker/proxy并把ServiceState保存到磁盘。若拉起过程中任何组件失败ServiceHTTPError/ServiceUnreachable/RuntimeError/ValueError会kill_pids清理已启动的进程并抛出ClickException。启动服务最小启动——一对 (worker, proxy)areal agent run \ --service default \ --agent my_package.my_agent.MyAgent \ --num-pairs 1 \ --admin-api-key areal-agent-admin--agent是必填项是 worker 进程用来加载 agent 类的导入路径。清除残留状态并强制启动areal agent run --service default --agent ... --force与areal inf run一样--force会先以 5 秒宽限期替换旧状态否则拒绝重复启动。其余可选参数及默认值--setup-timeout 120.0组件就绪等待、--health-poll-interval 5.0、--drain-timeout 30.0下线排空、--session-timeout 1800.0会话超时、--log-level info。查看服务状态列出本机所有 agent 服务areal agent ps areal agent ps --all # 包含 stale 行 areal agent ps --json输出列SERVICE / STATUS / GATEWAY / AGENT。查看单个服务里每个组件的健康状况areal agent status --service default输出包含 gateway、router以及每对 worker proxy。--watch模式按间隔刷新默认 2 秒areal agent status --service default --watch --interval 1JSON 模式方便与 jq 配合areal agent status --service default --json | jq .pairs[].worker与服务通信CLI不负责应用如何跟服务交互——应用直接打 gateway 的 HTTP 接口即可。status命令可以告诉你 gateway URLGATEWAY_URL$(areal agent status --service default --json | jq -r .gateway.url) echo gateway at $GATEWAY_URL应用带上--admin-api-key或从 gateway 拿到的 session key向该 URL 发请求。日志每个组件都有独立日志文件areal agent logs --service default --component gateway -f areal agent logs --service default --component router -f areal agent logs --service default --component worker-0 -f areal agent logs --service default --component proxy-0 -f命名约定gateway/router服务级单例。worker-i/proxy-i第 i 对 pair 的 worker />areal agent stop --service default默认是两阶段关闭先 SIGTERM等--grace-period10 秒再 SIGKILL。立即 SIGKILLareal agent stop --service default --force--keep-state保留状态文件杀掉进程但磁盘上的svc.json保留areal agent stop --service default --keep-state配置文件areal agent启动时会读取~/.areal/agent/config.toml作为默认值也可以另外传入配置文件areal agent --config ./my-agent.toml run --service default --agent ...示例[default] service default admin_api_key areal-agent-admin log_level info [run] agent my_package.my_agent.MyAgent num_pairs 2 setup_timeout 120 health_poll_interval 5 drain_timeout 30 session_timeout 1800优先级CLI 参数 通过--config传入的 TOML ~/.areal/agent/config.toml 内置默认值。尚未实现当前areal agent不包含会话级 CLI 操作开启会话 / 设置奖励 / 导出轨迹——这类操作与应用耦合很紧由应用直接调用 gateway HTTP 处理。自动故障恢复 / 心跳监控——status是按需查询不会持续观察组件健康。worker 死掉后需要用户运行status或看日志才能发现。分布式调度——只在本机启动本地进程k8s / slurm 等超出当前 CLI 的范围。小结一条命令链贯通三种服务形态arealCLI 的设计遵循「操作者工具」定位训练侧保持无状态、只做 driver 配置的封装与透传hydra 覆盖解析完全下沉到 driver 侧load_expr_config推理与 Agent 侧则共享完整的生命周期管理run/ps/status/logs/stopAREAL_HOME状态目录 TOML 配置优先级区别仅在于inf面向无状态模型推理gateway router worker contenteditable="false">【免费下载链接】AReaLThe RL Bridge for LLM-based Agent Applications. Made Simple Flexible.项目地址: https://gitcode.com/GitHub_Trending/are/AReaL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考