AgentRL
AgentRL 是面向 LLM/VLM 的分布式强化学习与监督微调训练栈，覆盖采样、训练、推理服务和数据库存储全链路，支持 FSDP2/TP/PP/EP、SGLang 推理和 MongoDB/MinIO 作为数据后端。
- 快速上手：提供一键依赖安装与导入自检脚本。
- 多训练范式：内置 SFT、GRPO/GSPO/MINIRL/CISPO，支持同步与异步采样。
- 可扩展采样：通过任务/轨迹文档模型和
AsyncSampler快速定制采样流程。 - 分布式友好：训练、推理、采样均支持多节点多卡并行，带显存释放与服务热启逻辑。
核心特性 (Key Features)
🧩 极简代码设计 (Minimalist Codebase)
遵循极简代码哲学，核心实现仅 7 个文件、约 1000 行代码。代码结构清晰、逻辑直观，极大降低了认知负载，非常适合学术研究、二次开发及快速验证新想法（MVP）。
🔌 原生智能体接入 (Native Agent Integration)
将智能体构建抽象为 API 级可组合接口。用户可像调用服务一样灵活定义智能体的观测、动作与上下文管理逻辑，只需遵循标准 ChatCompletions 格式即可无缝接入 RL 训练。这种设计消除了繁琐的适配层，显著降低了多轮智能体的开发与迭代成本。
🏗️ 训推完全解耦 (Decoupled Architecture)
采用训练与采样完全解耦的设计。训练组件仅流式消费轨迹数据，不依赖采样过程的生命周期。采样端支持独立启动、停止、扩展和重启，为异构集群部署提供了极高的灵活性与可扩展性。
⚡ 全异步流水线 (Fully Asynchronous Pipeline)
支持在同一 GPU 上并发运行异步采样和训练管道，显著提升硬件资源利用率。可启用框架内置轨迹新鲜度控制和重要性权重约束机制，有效缓解全异步场景下的 Off-Policy 分布漂移，确保训练稳定性。
🚀 极致性能与并行加速 (Performance & Acceleration)
- 前缀自动合并 (Auto-Prefix Merging)：引入类似推理端 KV Cache 的训练侧计算复用机制。系统统一管理多轮轨迹中的共享上下文，将 ReAct 等逐步推理型智能体的多次计算压缩为单次前向传播，大幅减少冗余计算并提升训练效率。
- 原生并行支持：全面支持 PyTorch 原生并行生态，兼容 FSDP2、Tensor Parallel (TP)、Context Parallel (CP) 等多种策略，具备 128K+ Tokens 的超长上下文训练能力。
🔍 全链路数据审计 (Full-Link Auditability)
构建可信的数据闭环，所有采样请求、模型响应、环境反馈及训练过程均以结构化格式持久化存储。支持开发者查询任意历史轨迹、回溯多轮交互决策并定位异常样本，显著降低大规模异步训练系统的调试成本。
目录导航
- 代码入口：src/main.py
- 配置定义：src/configs.py
- 训练核心：src/training
- 采样与任务流：src/rollout
- 数据库/存储模型：src/databases
- 示例/数据：assets
- SFT 指南：docs/sft.md
- RL/GRPO 指南：docs/rl.md
- 采样与任务定制：docs/sampling.md
快速开始
- 安装依赖（必要，推荐使用 uv）
uv init
uv pip install -r requirements.txt --no-build-isolation
- 基础自检（无 GPU 亦可）
python -c "import sys; sys.path.insert(0, 'src'); import models, sampler; print('All dependencies working')"
- 可选验证
- GPU：
python tests/dtensor_bench.py --world-size 1 --warmup 1 - 数据库：
timeout 10 python tests/mongo_connection_test.py
- 最小化启动示例（单机多卡，需按环境填写模型/数据库）
torchrun --nproc_per_node=8 src/main.py \
--model_name_or_path /path/to/model \
--output_dir output/demo \
--db_connection_string "mongodb://user:pwd@host:27017" \
--enable_sampling true \
--loss_calculater GRPO \
--per_device_train_batch_size 1 --gradient_accumulation_steps 8 \
--learning_rate 2e-6 --num_train_epochs 1
更多模式与参数见下文及子文档。
训练模式速览
- 监督微调 (SFT)：关闭采样、使用 CrossEntropy，支持从数据库或本地 JSON/JSONL 读取。docs/sft.md
- 强化学习 / GRPO/GSPO/MINIRL/CISPO：开启采样，推理服务按 TP 组拉起，轨迹存入 Mongo/MinIO。docs/rl.md
- 自定义采样策略：继承
AsyncSampler自定义run与evaluate_record，或新增任务类型。docs/sampling.md
数据与流程
- 任务/轨迹模型：
Task → DispatchedSamplingTask → Record → DBRecordData，均由 Beanie ODM 管理，定义在 src/databases。 - 采样流程：在训练中，TP 组主进程启动 SGLang 推理子进程，接受任务、生成响应并写回数据库；训练侧从
DBIterableDataset动态拉取样本。 - 动态批处理：可开启
dynamic_batching，按max_prompt_tokens合并样本以提高吞吐。
配置要点（节选）
- 路径与模型：
model_name_or_path,model_init_kwargs,processor_name - 并行与内存：
tp_size,pp_size,ep_size,cp_size,inf_tp_size,inf_ep_size,inf_mem_ratio,cpu_ram_efficient_loading,loss_seq_chunk_size,activation_offloading - 采样：
enable_sampling,sync_sampling,num_generations,max_new_tokens,target_concurrency,max_concurrent_samples_per_process - 数据：
train_file,max_prompt_tokens,dynamic_batching,max_trained_count,retrained_interval,minimal_advantage,drop_zero_advantage - 优化与损失：
loss_calculater（GRPO/GSPO/MINIRL/CISPO/CrossEntropy）,learning_rate,epsilon,epsilon_higher,beta1,beta2,importance_weight_cap_ratio - 存储：
db_connection_string,enable_oss,oss_connection_string
完整参数说明见 src/configs.py 注释。
开发与验证建议
- 变更后优先跑导入自检；GPU/DB 可用时再跑相应测试。
- 大模型训练前先用小步长或少量样本验证分布式配置。
- 采样/训练长作业请预留充足超时（构建依赖 10+ 分钟、训练可达小时级）。
已知补丁与注意事项
- SGLang 相关补丁集中在 src/training/inference.py，包含 tokenizer detokenize 及子进程管理等修复；如使用最新 SGLang，部分补丁可忽略但建议保持一致性。
- 如果使用自定义
Task/Record结构，请确保 Mongo 索引与文档模型同步更新。
许可证
本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。