Skip to content

AGENTS.md

Latest commit

 

History

History
118 lines (90 loc) · 6.14 KB

AGENTS.md

File metadata and controls

118 lines (90 loc) · 6.14 KB
Raw

Relax

Relax 是一个基于 Ray Serve 的大模型强化学习训练框架，支持 Megatron 训练后端、SGLang 推理引擎、以及 GRPO/PPO/DAPO 等算法族。

Tech stack: Python 3.8+ · PyTorch · Megatron · SGLang · Ray / Ray Serve

Project Structure

relax/                   核心框架
├── core/                编排层 — 训练循环、服务基类、全局注册表
├── components/          组件层 — RL 服务组件（Ray Serve Deployment）
├── engine/              引擎层 — Rollout 数据生成、奖励计算、请求路由
├── backends/            后端层 — Megatron 训练后端、SGLang 推理引擎
├── distributed/         分布式层 — Ray 集群管理、分布式 Checkpoint
├── entrypoints/         入口层 — 训练入口脚本
└── utils/               基础设施 — 工具函数、指标监控、多模态处理
tests/                   测试（镜像 relax/ 层级）
├── backends/megatron/   Megatron 后端测试（权重转换等）
├── distributed/ray/     分布式 / Ray 测试（弹性伸缩等）
├── engine/rewards/      奖励函数测试
├── engine/rollout/      Rollout 引擎测试（预取、数据源等）
└── utils/               工具函数测试（HTTP、指标、流式数据集等）
transfer_queue/          分布式数据传输队列
examples/                用户级示例（deepeyes、OPD 等）
scripts/                 训练启动脚本 & 模型配置
configs/env.yaml         运行时环境配置

修改代码时重点关注：relax/utils/utils.py、relax/components/、relax/core/controller.py、relax/entrypoints/train.py。

Code Standards

  • Ruff 格式化，行宽 119，isort 管理导入（配置见 pyproject.toml）
  • relax/ 下所有 .py 须含版权头：# Copyright (c) 2026 Relax Authors. All Rights Reserved.
  • pre-commit 对 transfer_queue/ 排除大部分检查
  • 日志统一用 relax.utils.logging_utils.get_logger(__name__)，禁止 print / logging.getLogger
  • 显式类型注解；禁止通配导入（from x import *）；重型可选依赖放函数内导入
  • 热路径禁止 GPU-CPU 同步（.item()、.tolist()、print(tensor)）
  • 组合优于继承，层级 ≤ 2；偏好委托

Naming Conventions

类型 模式 示例
Service 类 @serve.deployment Actor, Rollout, Critic, GenRM
后端 Actor XxxTrainRayActor MegatronTrainRayActor
Actor 组 RayTrainGroup 管理一组训练 Ray Actor
Manager XxxManager RolloutManager, GenRMManager
Reward 函数 engine/rewards/xxx.py deepscaler.py, math_utils.py
数据源 XxxDataSource RolloutDataSource

Hard Rules

CRITICAL: 以下规则不可违反。

  • 禁止通配导入、硬编码密钥/路径/端点
  • 禁止跳过 pre-commit hooks
  • 禁止猜测集群配置或重建 CUDA/驱动栈
  • 调试时直接修改 scripts/training/ 下的训练脚本来调整参数，再通过 scripts/entrypoint/ray-job.sh 提交
  • 禁止做与目标无关的代码改动，如 code format 等
  • 集成测试需要多节点 GPU 硬件——必须显式说明跳过原因
  • 修改前先读相关文件；提交前跑 pre-commit run --all-files
  • 遵循最小变更原则：只碰需求直接涉及的文件和行

Ask First

修改以下内容前必须先征求确认：

  • relax/utils/arguments.py 或 relax/backends/megatron/arguments.py 的参数解析
  • 新增依赖
  • Controller / Service / Launcher 逻辑
  • 删除或重命名公开 API

不确定时，留 TODO(agent) 注释并在回复中说明约束。

Development Workflow

pip install -r requirements.txt
pre-commit run --all-files           # lint + format（等同 make format）
pytest tests/                        # 测试
  • 提交遵循 Conventional Commits（feat:, fix:, docs:），详见 git-commit skill
  • 仅创建本地 commit，不 push
  • 测试命名：test_<module>_<behavior>()，GPU 测试用 @pytest.mark.skipif 优雅跳过

Distributed Code Rules

作用域：relax/backends/**、relax/distributed/ray/**、relax/distributed/checkpoint_service/**

  • 禁止在模块级创建全局进程组；始终显式传 process_group
  • dist.get_rank(group) 而非 dist.get_rank()
  • all-reduce 所有 rank 必须调用；broadcast 显式 src；barrier 仅用于调试
  • 调试环境变量：TORCH_DISTRIBUTED_DEBUG=DETAIL, NCCL_DEBUG=INFO, CUDA_LAUNCH_BLOCKING=1

Configuration & Launching

训练通过 relax/utils/arguments.py 的命令行参数配置（扩展 Megatron-LM 解析器）。

Domain experts & skills

Fire the appropriate expert subagent or load a skill based on what you're working on. Experts are read-only consultants with deep domain knowledge; skills are step-by-step implementation guides.

Working on... Fire subagent Load skill
Megatron backend (TP/PP/CP/EP) megatron-expert
RL algorithms (GRPO/PPO/DAPO/GSPO/SAPO) algorithm-expert
Task Launch & service deployment launcher-expert
Ray framework (Core, Serve, Jobs, placement) ray-expert
Development & code changes ray-expert dev
Distributed training hang debugging ray-expert debug-hang
Code review of git changes -- code-review
Creating new skills -- creating-skills
Git commits -- git-commit

How to fire an expert: task(subagent_type="megatron-expert", load_skills=[], run_in_background=true, prompt="...")