Stable Baselines3

Overview

Stable Baselines3（SB3）は、PyTorchベースのライブラリで、強化学習アルゴリズムの信頼性の高い実装を提供しています。このスキルは、RLエージェントの訓練、カスタム環境の作成、コールバックの実装、および SB3の統一 APIを用いた訓練ワークフローの最適化に関する包括的なガイダンスを提供します。

Core Capabilities

1. RLエージェントの訓練

基本的な訓練パターン：

import gymnasium as gym
from stable_baselines3 import PPO

# Create environment
env = gym.make("CartPole-v1")

# Initialize agent
model = PPO("MlpPolicy", env, verbose=1)

# Train the agent
model.learn(total_timesteps=10000)

# Save the model
model.save("ppo_cartpole")

# Load the model (without prior instantiation)
model = PPO.load("ppo_cartpole", env=env)

重要な注意：

• total_timestepsは下限値です。バッチ収集のため、実際の訓練はこれを超えることがあります
• model.load()は静的メソッドとして使用し、既存インスタンス上で使用しないでください
• リプレイバッファはスペース節約のため、モデルとともに保存されません

アルゴリズムの選択： アルゴリズムの詳細な特性と選択ガイダンスについては references/algorithms.md を参照してください。クイックリファレンス：

• PPO/A2C: 汎用、すべてのアクション空間タイプに対応、マルチプロセッシングに最適
• SAC/TD3: 連続制御、オフポリシー、サンプル効率的
• DQN: 離散アクション、オフポリシー
• HER: 目標条件付きタスク

ベストプラクティスを含む完全な訓練テンプレートについては、scripts/train_rl_agent.py を参照してください。

2. カスタム環境

要件： カスタム環境は gymnasium.Env を継承し、以下を実装する必要があります：

• __init__(): action_space と observation_space を定義
• reset(seed, options): 初期観測と info dict を返す
• 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 スペースをサポートしていません

検証：

from stable_baselines3.common.env_checker import check_env

check_env(env, warn=True)

完全なカスタム環境テンプレートについては scripts/custom_env_template.py を参照してください。包括的なガイダンスについては references/custom_environments.md を参照してください。

3. ベクトル化環境

目的： ベクトル化環境は複数の環境インスタンスを並列に実行し、訓練を加速し、特定のラッパー（フレームスタッキング、正規化）を有効にします。

タイプ：

• DummyVecEnv: 現在のプロセスで順序実行（軽量環境向け）
• SubprocVecEnv: プロセス間の並列実行（計算集約的な環境向け）

クイックセットアップ：

from stable_baselines3.common.env_util import make_vec_env

# Create 4 parallel environments
env = make_vec_env("CartPole-v1", n_envs=4, vec_env_cls=SubprocVecEnv)

model = PPO("MlpPolicy", env, verbose=1)
model.learn(total_timesteps=25000)

オフポリシー最適化： オフポリシーアルゴリズム（SAC、TD3、DQN）で複数環境を使用する場合、gradient_steps=-1 を設定して、環境ステップあたり 1つの勾配更新を実行し、ウォールクロック時間とサンプル効率のバランスを取ります。

API の違い：

• reset() は観測のみを返します（info は vec_env.reset_infos で利用可能）
• step() は 4タプルを返します：5タプルではなく (obs, rewards, dones, infos)
• エピソード後、環境は自動的にリセットされます
• ターミナル観測は infos[env_idx]["terminal_observation"] 経由で利用可能です

詳細については、references/vectorized_envs.md を参照してください。ラッパーと高度な使用方法について説明しています。

4. モニタリングと制御のためのコールバック

目的： コールバックにより、コアアルゴリズムを変更することなく、メトリクスのモニタリング、チェックポイントの保存、早期停止の実装、カスタム訓練ロジックが可能になります。

一般的なコールバック：

• EvalCallback: 定期的に評価し、最良モデルを保存
• CheckpointCallback: 一定間隔でモデルチェックポイントを保存
• StopTrainingOnRewardThreshold: ターゲット報酬に達したら停止
• ProgressBarCallback: タイミング付きで訓練進行状況を表示

カスタムコールバック構造：

from stable_baselines3.common.callbacks import BaseCallback

class CustomCallback(BaseCallback):
    def _on_training_start(self):
        # Called before first rollout
        pass

    def _on_step(self):
        # Called after each environment step
        # Return False to stop training
        return True

    def _on_rollout_end(self):
        # Called at end of rollout
        pass

利用可能な属性：

• self.model: RLアルゴリズムインスタンス
• self.num_timesteps: 合計環境ステップ
• self.training_env: 訓練環境

コールバックの連鎖：

from stable_baselines3.common.callbacks import CallbackList

callback = CallbackList([eval_callback, checkpoint_callback, custom_callback])
model.learn(total_timesteps=10000, callback=callback)

包括的なコールバックドキュメントについては、references/callbacks.md を参照してください。

5. モデルの永続化と検査

保存と読み込み：

# Save model
model.save("model_name")

# Save normalization statistics (if using VecNormalize)
vec_env.save("vec_normalize.pkl")

# Load model
model = PPO.load("model_name", env=env)

# Load normalization statistics
vec_env = VecNormalize.load("vec_normalize.pkl", vec_env)

パラメータアクセス：

# Get parameters
params = model.get_parameters()

# Set parameters
model.set_parameters(params)

# Access PyTorch state dict
state_dict = model.policy.state_dict()

6. 評価と記録

評価：

from stable_baselines3.common.evaluation import evaluate_policy

mean_reward, std_reward = evaluate_policy(
    model,
    env,
    n_eval_episodes=10,
    deterministic=True
)

ビデオ記録：

from stable_baselines3.common.vec_env import VecVideoRecorder

# Wrap environment with video recorder
env = VecVideoRecorder(
    env,
    "videos/",
    record_video_trigger=lambda x: x % 2000 == 0,
    video_length=200
)

完全な評価と記録テンプレートについては、scripts/evaluate_agent.py を参照してください。

7. 高度な機能

学習率スケジュール：

def linear_schedule(initial_value):
    def func(progress_remaining):
        # progress_remaining goes from 1 to 0
        return progress_remaining * initial_value
    return func

model = PPO("MlpPolicy", env, learning_rate=linear_schedule(0.001))

マルチ入力ポリシー（Dict 観測）：

model = PPO("MultiInputPolicy", env, verbose=1)

観測が辞書である場合に使用します（例：画像とセンサデータを組み合わせる）。

Hindsight Experience Replay：

from stable_baselines3 import SAC, HerReplayBuffer

model = SAC(
    "MultiInputPolicy",
    env,
    replay_buffer_class=HerReplayBuffer,
    replay_buffer_kwargs=dict(
        n_sampled_goal=4,
        goal_selection_strategy="future",
    ),
)

TensorBoard統合：

model = PPO("MlpPolicy", env, tensorboard_log="./tensorboard/")
model.learn(total_timesteps=10000)

ワークフローガイダンス

新しい RLプロジェクトの開始：

1. 問題を定義する: 観測空間、アクション空間、報酬構造を特定
2. アルゴリズムを選択する: 選択ガイダンスについては references/algorithms.md を使用
3. 環境を作成/適応させる: 必要に応じて scripts/custom_env_template.py を使用
4. 環境を検証する: 訓練前に必ず check_env() を実行
5. 訓練をセットアップする: スターティングテンプレートとして scripts/train_rl_agent.py を使用
6. モニタリングを追加する: 評価とチェックポイント用のコールバックを実装
7. パフォーマンスを最適化する: 速度向上のためにベクトル化環境の使用を検討
8. 評価と反復する: 評価には scripts/evaluate_agent.py を使用

一般的な問題：

• メモリエラー: オフポリシーアルゴリズムの buffer_size を削減するか、並列環境の数を減らす
• 遅い訓練: 並列環境用に SubprocVecEnv を検討
• 不安定な訓練: 異なるアルゴリズムを試すか、ハイパーパラメータを調整するか、報酬スケーリングを確認
• インポートエラー: stable_baselines3 がインストールされていることを確認：uv pip install stable-baselines3[extra]

リソース

scripts/

• train_rl_agent.py: ベストプラクティス付き完全な訓練スクリプトテンプレート
• evaluate_agent.py: エージェント評価とビデオ記録テンプレート
• custom_env_template.py: カスタム Gym 環境テンプレート

references/

• algorithms.md: アルゴリズムの詳細比較と選択ガイド
• custom_environments.md: カスタム環境作成の包括的なガイド
• callbacks.md: コールバックシステムの完全なリファレンス
• vectorized_envs.md: ベクトル化環境の使用とラッパー

インストール

# Basic installation
uv pip install stable-baselines3

# With extra dependencies (Tensorboard, etc.)
uv pip install stable-baselines3[extra]