強化学習デモ：迷路問題

Q-Learningアルゴリズムを使用して迷路を解く強化学習エージェントのインタラクティブなデモアプリケーションです。Streamlitを使用してWeb上で学習過程を可視化できます。

特徴

• インタラクティブな学習: パラメータをリアルタイムで調整して学習プロセスを観察
• 可視化: 迷路環境、Q値ヒートマップ、学習統計グラフ
• アニメーション: 学習済みエージェントの最適経路をステップバイステップで表示
• Q-Learning: シンプルで理解しやすい強化学習アルゴリズム

デモ

アプリケーションでは以下の機能を提供します：

• 10×10のグリッド迷路環境
• 学習率、割引率、探索率などのパラメータ調整
• エピソードごとの累積報酬とステップ数の可視化
• Q値のヒートマップと最適方策の矢印表示
• 学習済みエージェントのデモ再生

セットアップ

必要要件

• Python 3.11以上
• uv (高速Pythonパッケージマネージャー)

uvのインストール

macOS/Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

環境構築

# プロジェクトディレクトリに移動
cd rl-maze-demo

# 依存関係をインストール
uv sync

実行方法

# srcディレクトリに移動してStreamlitアプリを起動
cd src
uv run streamlit run app.py

または、プロジェクトルートから実行する場合：

# Streamlitアプリを起動（srcディレクトリを指定）
cd src && uv run streamlit run app.py

ブラウザが自動的に開き、アプリケーションが表示されます（通常は http://localhost:8501）。

使い方

1. パラメータ設定: サイドバーで学習パラメータを調整

   • 学習率 (α): Q値の更新速度を制御
   • 割引率 (γ): 将来の報酬の重要度を制御
   • 探索率 (ε): ランダム探索の確率を制御
   • エピソード数: 学習の反復回数

2. 学習開始: 「学習開始」ボタンをクリック

   • 進捗バーで学習の進行状況を確認
   • 完了後、Q値ヒートマップと統計が表示されます

3. 結果確認:

   • 迷路ビューでスタート(S)とゴール(G)を確認
   • Q値ヒートマップで学習された価値を確認
   • 統計グラフで学習の収束を確認

4. デモ再生: 「最適経路を表示」ボタンで学習済みエージェントの動きを確認

   • 速度スライダーでアニメーション速度を調整可能

プロジェクト構造

rl-maze-demo/
├── .python-version          # Python バージョン固定
├── pyproject.toml           # uv 設定ファイル
├── README.md                # このファイル
├── src/
│   ├── __init__.py
│   ├── app.py              # Streamlit メインアプリ
│   ├── environment.py      # 迷路環境クラス
│   ├── agent.py            # Q-Learning エージェント
│   └── visualizer.py       # 可視化ユーティリティ
└── .claude/
    └── mcp.json            # MCP サーバー設定

MCP（Model Context Protocol）サーバー

このプロジェクトでは、Claude Codeの開発効率を向上させるために以下のMCPサーバーを設定しています。

設定済みサーバー

1. serena - IDE Assistant

   • ソース: git+https://github.com/oraios/serena
   • 機能: ファイル操作、ドキュメント検索、プロジェクト構造の把握
   • コンテキスト: ide-assistant

2. filesystem - ファイルシステム操作

   • パッケージ: @modelcontextprotocol/server-filesystem
   • 機能: プロジェクトディレクトリのセキュアなファイル操作
   • 対象: /home/user/test-maze-claude-code

3. memory - ナレッジグラフ

   • パッケージ: @modelcontextprotocol/server-memory
   • 機能: 会話間での情報の永続化、コンテキストの記憶

MCP設定ファイル

設定は .claude/mcp.json で管理されています。Claude Codeを起動すると、これらのMCPサーバーが自動的に起動し、mcp__プレフィックスで始まるツールとして利用可能になります。

Q-Learningについて

Q-Learningは、モデルフリーの強化学習アルゴリズムで、エージェントが環境との相互作用を通じて最適な行動方策を学習します。

Q値更新式

Q(s,a) ← Q(s,a) + α[r + γ max Q(s',a') - Q(s,a)]

• Q(s,a): 状態sで行動aを取った時の価値
• α: 学習率
• r: 即時報酬
• γ: 割引率
• s': 次の状態

報酬系

• ゴール到達: +100
• 壁衝突: -10
• 通常移動: -1

この報酬設定により、エージェントは最短経路でゴールに到達することを学習します。

技術スタック

• Python: 3.11+
• Streamlit: Webアプリケーションフレームワーク
• NumPy: 数値計算
• Matplotlib: 静的可視化
• Plotly: インタラクティブグラフ
• Pandas: データ処理
• uv: パッケージ管理

カスタマイズ

迷路サイズの変更

src/app.pyの以下の行を変更してください：

st.session_state.env = MazeEnvironment(size=10, wall_ratio=0.2)

• size: グリッドサイズ (デフォルト: 10)
• wall_ratio: 壁の割合 (デフォルト: 0.2 = 20%)

報酬の調整

src/environment.pyのstepメソッド内で報酬値を変更できます。

ライセンス

このプロジェクトはデモ目的で作成されています。

参考文献

• Watkins, C.J.C.H. (1989). "Learning from Delayed Rewards"
• Sutton, R. S., & Barto, A. G. (2018). "Reinforcement Learning: An Introduction"