stable-baselines3

Stable Baselines3

概要

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

現在のアップストリーム： 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 が必要です。

# Basic installation
uv pip install "stable-baselines3>=2.8"

# With extra dependencies (TensorBoard, ale-py for Atari, etc.)
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：PyTorch より JAX を使いたいユーザー向けの SB3 + JAX 実装

主な機能

1. RL エージェントのトレーニング

基本的なトレーニングパターン：

import gymnasium as gym
from stable_baselines3 import PPO

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

# Initialize agent (device="cpu" is often faster for MlpPolicy on small envs)
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 辞書を返します
• step(action)：観測値、報酬、terminated、truncated、info を返します
• render()：可視化（任意）
• close()：リソースを解放します

主な制約：

• 画像の観測値は [0, 255] の範囲の np.uint8 である必要があります
• 可能な場合は、チャネル優先形式（チャネル、高さ、幅）を使用します
• 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() は 5 要素タプルではなく、4 要素タプル (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)

観測が辞書形式の場合（画像とセンサーデータの組み合わせなど）に使用します。

ヒンドサイト・エクスペリエンス・リプレイ：

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]>=2.8'

リソース

scripts/

• train_rl_agent.py：ベストプラクティスを含むトレーニングスクリプトの完全なテンプレート
• evaluate_agent.py：エージェントの評価と動画記録のテンプレート
• custom_env_template.py：カスタムGym環境のテンプレート

references/

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

エージェントの操作手順

1. 環境を確認します。 Python 環境とライブラリのバージョン（python -c "import pkg; print(pkg.__version__)"）を確認し、データの形状、型、欠損値を調べます。
2. 入力を特定します。 データまたはユーザーに確認して、形式、識別子、パラメーターを確認します。結果が変わる値については推測せず、質問してください。
3. まず小規模に実行します。 最初にサンプルまたは単一のフォールドで実行し、実行時間とメモリを確認します。
4. 上記の指示と参考資料を使用して、タスク全体を実行します。
5. 結果を検証します。 ホールドアウトデータ、固定した乱数シード、適切な指標を使用し、データリークを確認して、不確実性（CI、シード間の標準偏差）を報告します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確認の点を明示します。

このような場合	対応方法
メモリ不足、または実行が非常に遅い場合	サブサンプリング、チャンク処理または遅延計算の使用、モデルサイズの縮小を行い、変更内容をユーザーに伝えます。
これらの指示にある関数、フラグ、エンドポイントがインストール済みバージョンに存在しない場合	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して対応し、そのことをユーザーに伝えます。API を捏造してはいけません。
必須の入力、識別子、パラメーターが曖昧な場合	ユーザーに質問するか、実行前に仮定を明示します。

インテグリティに関するルール

• 結果、パラメーター、識別子、引用、統計値を決して捏造してはいけません。実行または検証できない場合は、その旨を明確に伝えます。
• このセッションで計算していない指標を報告してはいけません。すべての数値について、その算出に使用したコードパスを示します。
• ここに記載されているバージョン固有の詳細は古くなっている可能性があるものとして扱い、インストール済みバージョンの公式ドキュメントで確認します。
• 金銭が発生する操作、共有 GPU やクラウドのクォータを消費する操作、個人データまたは患者データに触れる操作、元に戻せない操作を行う前に、必ず確認します。