Stable Baselines3（SB3）是一个基于 PyTorch 的强化学习算法库，提供可靠的强化学习算法实现。该技能为使用 SB3 统一 API 训练强化学习智能体、创建自定义环境、实现回调以及优化训练工作流提供指导。
版本与安装
资料显示当前上游版本为 SB3 2.8.0（2026 年 4 月），文档地址为 stable-baselines3.readthedocs.io。该技能针对 stable-baselines3 2.8.0 测试，要求 Python 3.10+（2.8.0 已放弃 3.9）以及 PyTorch >= 2.3。
基础安装：uv pip install "stable-baselines3>=2.8" 带额外依赖（TensorBoard、Atari 的 ale-py 等）：uv pip install "stable-baselines3[extra]>=2.8" 在 zsh 中需给方括号加引号：uv pip install 'stable-baselines3[extra]>=2.8' MuJoCo 连续控制基准：uv pip install "gymnasium[mujoco]" 可通过 import stable_baselines3; print(stable_baselines3.version) 检查版本。
相关项目
SB3-Contrib：实验性算法（MaskablePPO、CrossQ、QR-DQN、RecurrentPPO），为独立的 sb3-contrib 包。 RL Baselines3 Zoo：预训练智能体、超参数与训练脚本。 SBX：SB3 的 JAX 实现，适合偏好 JAX 而非 PyTorch 的用户。
主要能力
一、训练强化学习智能体
基本训练模式为：用 gym.make 创建环境，初始化算法（如 PPO("MlpPolicy", env, verbose=1)），调用 model.learn(total_timesteps=10000) 训练，再用 model.save 保存、PPO.load 加载。注意事项包括：total_timesteps 是下界，实际训练可能因批次收集而超出；model.load() 应作为静态方法使用，而非在已有实例上调用；回放缓冲区不会随模型保存以节省空间。算法选择方面：PPO/A2C 为通用算法，支持所有动作空间类型，适合多进程；SAC/TD3 用于连续控制，属于离策略、样本高效；DQN 用于离散动作、离策略；HER 用于目标条件任务。
二、自定义环境
自定义环境必须继承 gymnasium.Env 并实现 init（定义 action_space 与 observation_space）、reset(seed, options)、step(action)（返回 observation、reward、terminated、truncated、info）、render()（可选）、close()。关键约束：图像观测必须为 [0, 255] 范围内的 np.uint8；尽可能使用通道优先格式（channels, height, width）；SB3 会自动将图像除以 255 归一化，若已预归一化需在 policy_kwargs 中设置 normalize_images=False；SB3 不支持 start!=0 的 Discrete 或 MultiDiscrete 空间。可用 stable_baselines3.common.env_checker 的 check_env(env, warn=True) 进行验证。
三、向量化环境
向量化环境并行运行多个环境实例，加速训练并启用某些包装器（帧堆叠、归一化）。类型包括 DummyVecEnv（当前进程顺序执行，适合轻量环境）与 SubprocVecEnv（跨进程并行，适合计算密集环境）。可用 make_vec_env("CartPole-v1", n_envs=4, vec_env_cls=SubprocVecEnv) 快速创建。离策略算法（SAC、TD3、DQN）配合多环境时，设置 gradient_steps=-1 可在每个环境步执行一次梯度更新。API 差异：reset() 只返回观测（info 在 vec_env.reset_infos 中）；step() 返回 4 元组 (obs, rewards, dones, infos) 而非 5 元组；回合结束后环境自动重置；终止观测可通过 infos[env_idx]["terminal_observation"] 获取。
四、回调
回调用于监控指标、保存检查点、实现早停与自定义训练逻辑，无需修改核心算法。常见回调包括 EvalCallback（定期评估并保存最佳模型）、CheckpointCallback（按间隔保存检查点）、StopTrainingOnRewardThreshold（达到目标奖励时停止）、ProgressBarCallback（显示训练进度与耗时）。自定义回调继承 BaseCallback，可实现 _on_training_start、_on_step（返回 False 停止训练）、_on_rollout_end，并可访问 self.model、self.num_timesteps、self.training_env。多个回调可用 CallbackList 串联。
五、模型持久化与检查
可保存模型、保存归一化统计（VecNormalize）、加载模型与归一化统计。参数访问可通过 model.get_parameters()、model.set_parameters(params) 以及 model.policy.state_dict()。
六、评估与录制
评估可使用 stable_baselines3.common.evaluation 的 evaluate_policy(model, env, n_eval_episodes=10, deterministic=True)，返回平均奖励与标准差。视频录制可使用 VecVideoRecorder 包装环境，设置 record_video_trigger 与 video_length。
七、高级功能
学习率调度：定义 linear_schedule 函数，progress_remaining 从 1 到 0，传入 learning_rate。多输入策略：观测为字典（如图像与传感器数据组合）时使用 "MultiInputPolicy"。后见之明经验回放：SAC 配合 HerReplayBuffer，可设置 n_sampled_goal 与 goal_selection_strategy。TensorBoard 集成：设置 tensorboard_log 路径。
工作流指引
启动新强化学习项目的步骤：定义问题（观测空间、动作空间、奖励结构）；选择算法；创建或适配环境；训练前始终运行 check_env() 验证环境；以训练脚本模板为起点；添加评估与检查点回调；考虑向量化环境优化性能；评估并迭代。常见问题包括内存错误（减小 buffer_size 或减少并行环境数）、训练缓慢（考虑 SubprocVecEnv）、训练不稳定（尝试不同算法、调参或检查奖励缩放）、导入错误（确保已安装 stable-baselines3）。
资源
脚本包括 train_rl_agent.py（完整训练脚本模板）、evaluate_agent.py（评估与视频录制模板）、custom_env_template.py（自定义 Gym 环境模板）。参考文档包括 algorithms.md（算法对比与选择）、custom_environments.md（自定义环境创建）、callbacks.md（回调系统）、vectorized_envs.md（向量化环境与包装器）。
智能体操作流程
检查环境：确认 Python 环境与库版本，检查数据形状、类型与缺失值。确定输入：从数据或用户处确认格式、标识符与参数，对影响结果的取值应询问而非猜测。先运行小版本：在样本或单折上运行，检查运行时间与内存。使用上述说明与参考执行完整任务。验证结果：使用留出数据、固定随机种子与合适指标，检查泄漏，报告不确定性（置信区间、多种子标准差）。报告：说明运行内容（版本、命令、参数）、已检查项与仍不确定项。
异常处理
内存不足或执行极慢时：子采样、使用分块或惰性计算、减小模型规模，并告知用户改动。若说明中的函数、标志或端点在已安装版本中缺失：查阅已安装版本自身文档（help()、--help、官方文档），适配并告知用户，绝不臆造 API。若必需输入、标识符或参数不明确：询问用户，或在运行前明确说明假设。
完整性规则
绝不捏造结果、参数、标识符、引用或统计。若无法运行或验证，应明确说明。绝不报告本次会话未计算的指标；展示产生每个数字的代码路径。将此处版本相关细节视为可能过时，应针对已安装版本的官方文档进行确认。涉及花钱、消耗共享 GPU 或云配额、触碰个人或患者数据、或不可撤销的操作前应先询问。