Verl 单异步 DAPO 训练

交互式启动流程

启动训练服务前，Agent 必须按以下顺序询问用户：

1. 容器选择

检测到以下容器：
  [1] jins ( 运行中)
  [2] 创建新容器

请选择容器 (1/2):

2. 代理配置（如创建新容器或网络问题）

请提供代理配置（如不需要请回复"无"）：
  http_proxy: ?
  https_proxy: ?

3. 特性选择

是否有自定义特性需求？(回复"默认"使用默认配置)

性能特性（默认全开）:
  - flash_attn: Flash Attention 加速
  - dynamic_batch: 动态 Batch Size
  - remove_padding: Remove Padding 优化
  - gradient_checkpointing: 梯度检查点

显存特性（默认关闭，OOM 时自动开启）:
  - offload: 参数/优化器卸载
  - recompute: 重计算

可选特性:
  - prefix_cache: Prefix Cache
  - chunked_prefill: Chunked Prefill

4. SwanLab 配置（如未配置）

SwanLab 监控配置：
  Host: ?
  API Key: ?

快速开始

# 方式 1: 快速启动脚本 (推荐)
CONTAINER=jins TRAIN_STEPS=100 \
SWANLAB_HOST=http://10.143.2.129:8000 \
SWANLAB_API_KEY=your-key \
bash scripts/quick_start.sh

# 方式 2: 分步执行
# 2.1 训练前检查
bash scripts/preflight_check.sh

# 2.2 启动单异步 DAPO 训练 (使用默认特性进行训练)
export TRAIN_STEPS=4
bash scripts/run_dapo.sh

# 2.3 启动 One-Step-Off-Policy 训练
export TRAIN_STEPS=4
bash scripts/run_one_step_off_policy.sh

One-Step-Off-Policy 训练

One-Step-Off-Policy 是资源隔离的单异步训练模式，Trainer 和 Rollout 使用独立的 GPU 组。

# 基本用法
export TRAIN_STEPS=100
export TRAINER_GPUS=4
export ROLLOUT_GPUS=4
bash scripts/run_one_step_off_policy.sh

# 启用 offload 特性
export ENABLE_OFFLOAD=True
bash scripts/run_one_step_off_policy.sh

# FSDP2 框架
export FRAMEWORK=fsdp
bash scripts/run_one_step_off_policy.sh

配置参数:

变量	默认值	说明
FRAMEWORK	megatron	框架 (megatron/fsdp)
TRAINER_GPUS	4	训练 GPU 数
ROLLOUT_GPUS	4	Rollout GPU 数
MAX_RESPONSE_LENGTH	8192	最大响应长度
ENABLE_OFFLOAD	False	是否启用 offload

SwanLab 配置

SwanLab 配置由 swanlab-setup skill 提供，common.sh 启动时自动加载。详见 swanlab-setup skill 的 SKILL.md。

配置按优先级自动获取：环境变量 > 配置文件 > 交互式输入

# 环境变量（推荐）
export SWANLAB_HOST="http://your-swanlab-host:8000"
export SWANLAB_API_KEY="your-api-key"

重要：必须在 trainer.logger 参数中包含 "swanlab" 才能启用监控：

# 正确的 logger 配置（启用 SwanLab 监控）
trainer.logger='["console", "swanlab"]'

# 仅控制台输出（不启用监控）
trainer.logger='["console"]'

SwanLab 环境变量会自动被 verl tracking 模块读取：

• SWANLAB_API_KEY: API 密钥
• SWANLAB_LOG_DIR: 日志目录 (默认: swanlog)
• SWANLAB_MODE: 模式 (cloud/local, 默认: cloud)

代理配置

export http_proxy="http://your-proxy:8080"
export https_proxy="http://your-proxy:8080"

训练监控策略

启动后行为:

1. 输出 SwanLab 链接供用户自行查看
2. 后台静默运行，不实时推送进度
3. 仅在错误时通知用户（OOM、崩溃、配置错误等）

用户自行监控命令:

# 查看当前进度
docker exec {container} grep "Training Progress" /verl/train.log | tail -1

# 实时跟踪日志
docker exec {container} tail -f /verl/train.log

# 检查是否出错
docker exec {container} grep -E "Error|error|OOM|Exception" /verl/train.log | tail -10

特性管理策略

特性分类

类型	特性	默认状态	说明
性能特性	flash_attn	✅ 默认开	Flash Attention 加速
性能特性	dynamic_batch	✅ 默认开	动态 Batch Size
性能特性	remove_padding	✅ 默认开	Remove Padding 优化
性能特性	gradient_checkpointing	✅ 默认开	梯度检查点
显存特性	offload	❌ 默认关	参数/优化器卸载 (OOM 时自动追加)
显存特性	recompute	❌ 默认关	重计算 (OOM 时自动追加)
可选特性	prefix_cache	❌ 默认关	Prefix Cache
可选特性	chunked_prefill	❌ 默认关	Chunked Prefill

特性优先级

用户显式指定 > 默认性能特性 > OOM 自动追加显存特性

重要：

• 用户未指定时 → 使用默认性能特性（全开）
• OOM 时 → 自动追加显存特性（即使用户指定了其他特性）
• 用户显式指定的特性永不移除，只在 OOM 时追加

OOM 自动恢复流程

启动训练 (默认性能特性)
    ↓
OOM 错误?
    ├─ 是 → 追加 offload → 重试
    │   └─ 仍 OOM → 追加 recompute → 重试
    │       └─ 仍 OOM → 报告失败，建议调整参数
    └─ 否 → 训练成功（静默完成）

配置参数

环境变量

变量	默认值	说明
FRAMEWORK	megatron	框架 (megatron/fsdp)
MODEL_PATH	Qwen3-8B	模型路径
TRAIN_FILE	dapo-math-17k.parquet	训练数据
VAL_FILE	aime-2024.parquet	验证数据
TRAIN_STEPS	100	训练步数
TRAINER_GPUS	4	训练 GPU 数
ROLLOUT_GPUS	4	Rollout GPU 数
USER_FEATURES	(空)	用户显式指定特性，逗号分隔
MAX_OOM_RETRIES	2	OOM 最大重试次数
SWANLAB_HOST	(从配置获取)	SwanLab 服务器地址
SWANLAB_API_KEY	(从配置获取)	SwanLab API 密钥

详细参考

• 完整工作流程: See references/workflow.md
• 参数详解: See references/params.md
• 故障排查: See references/troubleshooting.md