rl
v0.6.0: compiled losses and partial steps
ドキュメント| Tensordict |特徴|例、チュートリアル、デモ|引用|インストール|質問をする|貢献
Torchrlは、Pytorchのオープンソース補強学習（RL）ライブラリです。
図書館のより厳選された説明については、完全な論文を読んでください。
開始するチュートリアルを確認して、ライブラリの基本機能をすばやく強化してください！
Torchrlのドキュメントはこちらをご覧ください。チュートリアルとAPIリファレンスが含まれています。
Torchrlは、コードをデバッグするか、単にRLの基本を学ぶのに役立つRLナレッジベースも提供します。ここでそれをチェックしてください。
ライブラリをよりよく知るために、いくつかの入門ビデオがあります。それらをチェックしてください。
Torchrlはドメインに依存しているため、多くの異なる分野で使用できます。ここにいくつかの例があります：
TensorDictを使用して、簡素化されたポータブルRLコードベースを作成しますRLアルゴリズムは非常に不均一であり、設定全体でコードベースをリサイクルするのは難しい場合があります（たとえば、オンラインからオフライン、状態ベースからピクセルベースの学習まで）。 Torchrlは、RLコードベースを合理化するために使用できる便利なデータ構造（1）であるTensorDictを通じてこの問題を解決します。このツールを使用すると、 100行未満のコードで完全なPPOトレーニングスクリプトを書くことができます！
import torch
from tensordict . nn import TensorDictModule
from tensordict . nn . distributions import NormalParamExtractor
from torch import nn
from torchrl . collectors import SyncDataCollector
from torchrl . data . replay_buffers import TensorDictReplayBuffer ,
LazyTensorStorage , SamplerWithoutReplacement
from torchrl . envs . libs . gym import GymEnv
from torchrl . modules import ProbabilisticActor , ValueOperator , TanhNormal
from torchrl . objectives import ClipPPOLoss
from torchrl . objectives . value import GAE
env = GymEnv ( "Pendulum-v1" )
model = TensorDictModule (
nn . Sequential (
nn . Linear ( 3 , 128 ), nn . Tanh (),
nn . Linear ( 128 , 128 ), nn . Tanh (),
nn . Linear ( 128 , 128 ), nn . Tanh (),
nn . Linear ( 128 , 2 ),
NormalParamExtractor ()
),
in_keys = [ "observation" ],
out_keys = [ "loc" , "scale" ]
)
critic = ValueOperator (
nn . Sequential (
nn . Linear ( 3 , 128 ), nn . Tanh (),
nn . Linear ( 128 , 128 ), nn . Tanh (),
nn . Linear ( 128 , 128 ), nn . Tanh (),
nn . Linear ( 128 , 1 ),
),
in_keys = [ "observation" ],
)
actor = ProbabilisticActor (
model ,
in_keys = [ "loc" , "scale" ],
distribution_class = TanhNormal ,
distribution_kwargs = { "low" : - 1.0 , "high" : 1.0 },
return_log_prob = True
)
buffer = TensorDictReplayBuffer (
storage = LazyTensorStorage ( 1000 ),
sampler = SamplerWithoutReplacement (),
batch_size = 50 ,
)
collector = SyncDataCollector (
env ,
actor ,
frames_per_batch = 1000 ,
total_frames = 1_000_000 ,
)
loss_fn = ClipPPOLoss ( actor , critic )
adv_fn = GAE ( value_network = critic , average_gae = True , gamma = 0.99 , lmbda = 0.95 )
optim = torch . optim . Adam ( loss_fn . parameters (), lr = 2e-4 )
for data in collector : # collect data
for epoch in range ( 10 ):
adv_fn ( data ) # compute advantage
buffer . extend ( data )
for sample in buffer : # consume data
loss_vals = loss_fn ( sample )
loss_val = sum (
value for key , value in loss_vals . items () if
key . startswith ( "loss" )
)
loss_val . backward ()
optim . step ()
optim . zero_grad ()
print ( f"avg reward: { data [ 'next' , 'reward' ]. mean (). item (): 4.4f } " )環境APIがTensordictに依存して、ロールアウト実行中にある関数から別の関数にデータを伝達する方法の例を示します。 
TensorDict使用すると、環境、モデル、アルゴリズム全体でコードを簡単に再使用できます。
たとえば、Torchrlでロールアウトをコーディングする方法は次のとおりです。
- obs, done = env.reset()
+ tensordict = env.reset()
policy = SafeModule(
model,
in_keys=["observation_pixels", "observation_vector"],
out_keys=["action"],
)
out = []
for i in range(n_steps):
- action, log_prob = policy(obs)
- next_obs, reward, done, info = env.step(action)
- out.append((obs, next_obs, action, log_prob, reward, done))
- obs = next_obs
+ tensordict = policy(tensordict)
+ tensordict = env.step(tensordict)
+ out.append(tensordict)
+ tensordict = step_mdp(tensordict) # renames next_observation_* keys to observation_*
- obs, next_obs, action, log_prob, reward, done = [torch.stack(vals, 0) for vals in zip(*out)]
+ out = torch.stack(out, 0) # TensorDict supports multiple tensor operationsこれを使用して、Torchrlは、モジュール、ENV、コレクター、リプレイバッファー、ライブラリの損失の入力 /出力署名を抽象化し、すべてのプリミティブを設定全体で簡単にリサイクルできるようにします。
Torchrlのオフポリシートレーニングループの別の例を次に示します（データコレクター、リプレイバッファー、損失、およびオプティマイザーがインスタンス化されていると仮定して）：
- for i, (obs, next_obs, action, hidden_state, reward, done) in enumerate(collector):
+ for i, tensordict in enumerate(collector):
- replay_buffer.add((obs, next_obs, action, log_prob, reward, done))
+ replay_buffer.add(tensordict)
for j in range(num_optim_steps):
- obs, next_obs, action, hidden_state, reward, done = replay_buffer.sample(batch_size)
- loss = loss_fn(obs, next_obs, action, hidden_state, reward, done)
+ tensordict = replay_buffer.sample(batch_size)
+ loss = loss_fn(tensordict)
loss.backward()
optim.step()
optim.zero_grad()このトレーニングループは、データの構造に関する最小限の数の仮定を作成するため、アルゴリズム全体で再利用できます。
Tensordictは、そのデバイスと形状（Tensordictの形状、またはバッチサイズの形状）での複数のテンソル操作をサポートしています。
# stack and cat
tensordict = torch . stack ( list_of_tensordicts , 0 )
tensordict = torch . cat ( list_of_tensordicts , 0 )
# reshape
tensordict = tensordict . view ( - 1 )
tensordict = tensordict . permute ( 0 , 2 , 1 )
tensordict = tensordict . unsqueeze ( - 1 )
tensordict = tensordict . squeeze ( - 1 )
# indexing
tensordict = tensordict [: 2 ]
tensordict [:, 2 ] = sub_tensordict
# device and memory location
tensordict . cuda ()
tensordict . to ( "cuda:1" )
tensordict . share_memory_ () Tensordictには、モデルを記述するために必要なものすべてを含む専用のtensordict.nnモジュールが付属しています。そして、それはfunctorchとtorch.compile互換です！
transformer_model = nn.Transformer(nhead=16, num_encoder_layers=12)
+ td_module = SafeModule(transformer_model, in_keys=["src", "tgt"], out_keys=["out"])
src = torch.rand((10, 32, 512))
tgt = torch.rand((20, 32, 512))
+ tensordict = TensorDict({"src": src, "tgt": tgt}, batch_size=[20, 32])
- out = transformer_model(src, tgt)
+ td_module(tensordict)
+ out = tensordict["out"] TensorDictSequentialクラスは、 nn.Moduleインスタンスの分岐シーケンスを非常にモジュール式の方法で可能にします。たとえば、エンコーダーブロックとデコーダーブロックを使用したトランスの実装は次のとおりです。
encoder_module = TransformerEncoder (...)
encoder = TensorDictSequential ( encoder_module , in_keys = [ "src" , "src_mask" ], out_keys = [ "memory" ])
decoder_module = TransformerDecoder (...)
decoder = TensorDictModule ( decoder_module , in_keys = [ "tgt" , "memory" ], out_keys = [ "output" ])
transformer = TensorDictSequential ( encoder , decoder )
assert transformer . in_keys == [ "src" , "src_mask" , "tgt" ]
assert transformer . out_keys == [ "memory" , "output" ] TensorDictSequential 、目的の入力 /出力キーのセットを照会することにより、サブグラフを分離できます。
transformer . select_subsequence ( out_keys = [ "memory" ]) # returns the encoder
transformer . select_subsequence ( in_keys = [ "tgt" , "memory" ]) # returns the decoder詳細については、Tensordictチュートリアルを確認してください！
一般的なライブラリ（Openai Gym、Deepmind Control Labなど） （1）およびステートレス実行（モデルベースの環境など）をサポートする環境の共通インターフェイス。バッチ付き環境コンテナは、並列実行を可能にします（2） 。テンソル仕様クラスの一般的なPytorch-Firstクラスも提供されています。 Torchrlの環境APIはシンプルですが、厳格で具体的です。詳細については、ドキュメントとチュートリアルを確認してください！
env_make = lambda : GymEnv ( "Pendulum-v1" , from_pixels = True )
env_parallel = ParallelEnv ( 4 , env_make ) # creates 4 envs in parallel
tensordict = env_parallel . rollout ( max_steps = 20 , policy = None ) # random rollout (no policy given)
assert tensordict . shape == [ 4 , 20 ] # 4 envs, 20 steps rollout
env_parallel . action_spec . is_in ( tensordict [ "action" ]) # spec check returns True同期または非同期的に機能するマルチプロセスおよび分散データコレクター（2） 。 Tensordictを使用することにより、Torchrlのトレーニングループは、監視された学習の定期的なトレーニングループに非常に似ています（「Dataloader」 - 読み取りデータコレクター - はオンザフライで変更されます）：
env_make = lambda : GymEnv ( "Pendulum-v1" , from_pixels = True )
collector = MultiaSyncDataCollector (
[ env_make , env_make ],
policy = policy ,
devices = [ "cuda:0" , "cuda:0" ],
total_frames = 10000 ,
frames_per_batch = 50 ,
...
)
for i , tensordict_data in enumerate ( collector ):
loss = loss_module ( tensordict_data )
loss . backward ()
optim . step ()
optim . zero_grad ()
collector . update_policy_weights_ ()分散コレクターの例を確認して、Torchrlを使用した超高速データ収集の詳細をご覧ください。
モジュール化されたストレージを備えた効率的（2）および汎用（1）リプレイバッファー：
storage = LazyMemmapStorage ( # memory-mapped (physical) storage
cfg . buffer_size ,
scratch_dir = "/tmp/"
)
buffer = TensorDictPrioritizedReplayBuffer (
alpha = 0.7 ,
beta = 0.5 ,
collate_fn = lambda x : x ,
pin_memory = device != torch . device ( "cpu" ),
prefetch = 10 , # multi-threaded sampling
storage = storage
)リプレイバッファーは、オフラインRLの一般的なデータセットの周りのラッパーとしても提供されます。
from torchrl . data . replay_buffers import SamplerWithoutReplacement
from torchrl . data . datasets . d4rl import D4RLExperienceReplay
data = D4RLExperienceReplay (
"maze2d-open-v0" ,
split_trajs = True ,
batch_size = 128 ,
sampler = SamplerWithoutReplacement ( drop_last = True ),
)
for sample in data : # or alternatively sample = data.sample()
fun ( sample )クロスライブラリー環境は、デバイスで実行され、ベクトル化された方法で実行され、エージェントが使用する環境から出てくるデータを処理および準備する（2）変換します。
env_make = lambda : GymEnv ( "Pendulum-v1" , from_pixels = True )
env_base = ParallelEnv ( 4 , env_make , device = "cuda:0" ) # creates 4 envs in parallel
env = TransformedEnv (
env_base ,
Compose (
ToTensorImage (),
ObservationNorm ( loc = 0.5 , scale = 1.0 )), # executes the transforms once and on device
)
tensordict = env . reset ()
assert tensordict . device == torch . device ( "cuda:0" )その他の変換には、報酬スケーリング（ RewardScaling ）、形状操作（テンソルの連結、未切断など）、連続操作の連結（ CatFrames ）、サイズ変更（ Resize ）などが含まれます。
他のライブラリとは異なり、変換はリストとして積み重なっています（互いに包まれていません）。これにより、自由に追加して削除できます。
env . insert_transform ( 0 , NoopResetEnv ()) # inserts the NoopResetEnv transform at the index 0それにもかかわらず、Transformsは親環境で操作にアクセスして実行できます。
transform = env . transform [ 1 ] # gathers the second transform of the list
parent_env = transform . parent # returns the base environment of the second transform, i.e. the base env + the first transform分散学習のためのさまざまなツール（メモリマッピングテンソルなど） （2） ;
さまざまなアーキテクチャとモデル（例：Actor-Critic） （1） ：
# create an nn.Module
common_module = ConvNet (
bias_last_layer = True ,
depth = None ,
num_cells = [ 32 , 64 , 64 ],
kernel_sizes = [ 8 , 4 , 3 ],
strides = [ 4 , 2 , 1 ],
)
# Wrap it in a SafeModule, indicating what key to read in and where to
# write out the output
common_module = SafeModule (
common_module ,
in_keys = [ "pixels" ],
out_keys = [ "hidden" ],
)
# Wrap the policy module in NormalParamsWrapper, such that the output
# tensor is split in loc and scale, and scale is mapped onto a positive space
policy_module = SafeModule (
NormalParamsWrapper (
MLP ( num_cells = [ 64 , 64 ], out_features = 32 , activation = nn . ELU )
),
in_keys = [ "hidden" ],
out_keys = [ "loc" , "scale" ],
)
# Use a SafeProbabilisticTensorDictSequential to combine the SafeModule with a
# SafeProbabilisticModule, indicating how to build the
# torch.distribution.Distribution object and what to do with it
policy_module = SafeProbabilisticTensorDictSequential ( # stochastic policy
policy_module ,
SafeProbabilisticModule (
in_keys = [ "loc" , "scale" ],
out_keys = "action" ,
distribution_class = TanhNormal ,
),
)
value_module = MLP (
num_cells = [ 64 , 64 ],
out_features = 1 ,
activation = nn . ELU ,
)
# Wrap the policy and value funciton in a common module
actor_value = ActorValueOperator ( common_module , policy_module , value_module )
# standalone policy from this
standalone_policy = actor_value . get_policy_operator ()探索ラッパーとモジュールは、探索と搾取の間に簡単に交換する（1） ：
policy_explore = EGreedyWrapper ( policy )
with set_exploration_type ( ExplorationType . RANDOM ):
tensordict = policy_explore ( tensordict ) # will use eps-greedy
with set_exploration_type ( ExplorationType . DETERMINISTIC ):
tensordict = policy_explore ( tensordict ) # will not use eps-greedy一連の効率的な損失モジュールと高度にベクトル化された機能的リターンとアドバンテージ計算。
from torchrl . objectives import DQNLoss
loss_module = DQNLoss ( value_network = value_network , gamma = 0.99 )
tensordict = replay_buffer . sample ( batch_size )
loss = loss_module ( tensordict ) from torchrl . objectives . value . functional import vec_td_lambda_return_estimate
advantage = vec_td_lambda_return_estimate ( gamma , lmbda , next_state_value , reward , done , terminated )前述のトレーニングループを実行する一般的なトレーナークラス（1） 。フックメカニズムを通じて、いつでもロギングまたはデータ変換操作もサポートします。
展開されている環境に対応するモデルを構築するためのさまざまなレシピ。
ライブラリに機能がないと感じた場合は、問題を提出してください！新機能に貢献したい場合は、貢献と貢献ページの呼び出しを確認してください。
一連の最先端の実装には、説明的な目的があります。
| アルゴリズム | サポートをコンパイル** | TensordictフリーAPI | モジュラー損失 | 連続的で離散 |
| DQN | 1.9x | + | Na | +（Action -DiscreTizer Transformを通じて） |
| DDPG | 1.87x | + | + | - （連続のみ） |
| IQL | 3.22x | + | + | + |
| CQL | 2.68X | + | + | + |
| TD3 | 2.27x | + | + | - （連続のみ） |
| TD3+BC | テストされていない | + | + | - （連続のみ） |
| A2c | 2.67x | + | - | + |
| PPO | 2.42x | + | - | + |
| サック | 2.62x | + | - | + |
| redq | 2.28X | + | - | - （連続のみ） |
| Dreamer V1 | テストされていない | + | +（異なるクラス） | - （連続のみ） |
| 意思決定トランス | テストされていない | + | Na | - （連続のみ） |
| Crossq | テストされていない | + | + | - （連続のみ） |
| ゲイル | テストされていない | + | Na | + |
| インパラ | テストされていない | + | - | + |
| IQL（Marl） | テストされていない | + | + | + |
| DDPG（Marl） | テストされていない | + | + | - （連続のみ） |
| PPO（Marl） | テストされていない | + | - | + |
| qmix-vdn（marl） | テストされていない | + | Na | + |
| サック（マール） | テストされていない | + | - | + |
| rlhf | Na | + | Na | Na |
**数値は、CPUで実行されたときの熱心モードと比較して、予想されるスピードアップを示します。数値は、アーキテクチャとデバイスによって異なる場合があります。
そして、もっとたくさん！
おもちゃコードのスニペットとトレーニングスクリプトを表示するコード例も利用できます
さまざまな構成設定の処理の詳細については、Examples Directoryを確認してください。
また、図書館ができることの感覚を与えるチュートリアルとデモも提供しています。
Torchrlを使用している場合は、このBibtexエントリを参照して、この作業を引用してください。
@misc{bou2023torchrl,
title={TorchRL: A data-driven decision-making library for PyTorch},
author={Albert Bou and Matteo Bettini and Sebastian Dittert and Vikash Kumar and Shagun Sodhani and Xiaomeng Yang and Gianni De Fabritiis and Vincent Moens},
year={2023},
eprint={2306.00577},
archivePrefix={arXiv},
primaryClass={cs.LG}
}
パッケージがインストールされるコンドラ環境を作成します。
conda create --name torch_rl python=3.9
conda activate torch_rl
Pytorch
作成したいFunctorchの使用に応じて、最新の（毎晩）PytorchリリースまたはPytorchの最新バージョンをインストールすることをお勧めします。 pip3またはその他の特別なインストール手順を含むコマンドの詳細なリストについては、こちらをご覧ください。
Torchrl
最新の安定したリリースを使用してインストールできます
pip3 install torchrlこれは、Linux、Windows 10、およびOSX（Intelまたはシリコンチップ）で動作するはずです。特定のWindowsマシン（Windows 11）で、ライブラリをローカルにインストールする必要があります（以下を参照）。
毎晩のビルドを介してインストールできます
pip3 install torchrl-nightly現在、LinuxおよびOSX（Intel）マシンのみに出荷されています。重要なことに、毎晩のビルドには、Pytorchの毎晩のビルドも必要です。
追加の依存関係をインストールするには、電話してください
pip3 install " torchrl[atari,dm_control,gym_continuous,rendering,tests,utils,marl,open_spiel,checkpointing] "またはこれらのサブセット。
ライブラリをローカルにインストールすることもできます。 3つの主な理由がこれを動機付けることができます：
ライブラリをローカルにインストールするには、リポジトリのクローニングから始めます。
git clone https://github.com/pytorch/rlそして、ビルドに使用するブランチまたはタグをチェックすることを忘れないでください：
git checkout v0.4.0 Torchrlリポジトリをクローン化したディレクトリに移動してインストールします（ ninjaをインストールした後）
cd /path/to/torchrl/
pip3 install ninja -U
python setup.py developまた、ホイールを構築して、使用を使用して同僚に配布することもできます
python setup.py bdist_wheelあなたのホイールはそこに保管されます./dist/torchrl<name>.whl
pip install torchrl < name > .whl警告：残念ながら、 pip3 install -e .現在機能していません。これを修正するための貢献は大歓迎です！
M1マシンでは、これはPytorchの毎晩のビルドですぐに機能するはずです。 MACOS M1でのこのアーティファクトの生成が正しく機能しないか、実行中にメッセージ(mach-o file, but is an incompatible architecture (have 'x86_64', need 'arm64e'))が表示されます。
ARCHFLAGS="-arch arm64" python setup.py develop
迅速な正気チェックを実行するには、そのディレクトリ（例： cd ~/実行して）を離れ、ライブラリをインポートしてみてください。
python -c "import torchrl"
これにより、警告やエラーを返さないでください。
オプションの依存関係
Torchrlを作成する使用法に応じて、次のライブラリをインストールできます。
# diverse
pip3 install tqdm tensorboard "hydra-core>=1.1" hydra-submitit-launcher
# rendering
pip3 install moviepy
# deepmind control suite
pip3 install dm_control
# gym, atari games
pip3 install "gym[atari]" "gym[accept-rom-license]" pygame
# tests
pip3 install pytest pyyaml pytest-instafail
# tensorboard
pip3 install tensorboard
# wandb
pip3 install wandb
トラブルシューティング
ModuleNotFoundError: No module named 'torchrl._torchrlが発生しない場合（またはC ++バイナリをロードできないことを示す警告）、C ++拡張機能がインストールされていないか、見つからなかったことを意味します。
developモードにインストールされていない場合、次のコードスニペットはエラーを返す必要があります。 cd ~/path/to/rl/repo
python -c 'from torchrl.envs.libs.gym import GymEnv'
python setup.py develop後にログを確認してください。一般的な原因の1つは、G ++/C ++バージョンの矛盾および/またはninjaライブラリの問題です。 wget https://raw.githubusercontent.com/pytorch/pytorch/master/torch/utils/collect_env.py
python collect_env.py
OS: macOS *** (arm64)
OS: macOS **** (x86_64)
バージョン化の問題は、タイプundefined symbolなどのエラーメッセージを引き起こす可能性があります。これらについては、完全な説明と提案された回避策については、バージョンの問題文書を参照してください。
ライブラリでバグを見つけた場合は、このレポで問題を提起してください。
PytorchのRLに関するより一般的な質問がある場合は、Pytorchフォーラムに投稿してください。
Torchrlへの内部コラボレーションは大歓迎です！お気軽にフォークして、問題やPRを提出してください。ここで詳細な貢献ガイドを確認できます。上記のように、公開貢献のリストはこちらにあります。
貢献者は、コミット前のフックをインストールすることをお勧めします（ pre-commit installを使用）。コードがローカルでコミットされている場合、事前コミットは関連する問題を確認します。 commitコマンドへのappending -nによってチェックを無効にすることができます： git commit -m <commit message> -n
このライブラリは、Pytorchベータ機能としてリリースされます。 BCの破壊的な変更は発生する可能性がありますが、数回のリリースサイクルの後、非推奨保証で導入されます。
Torchrlは、MITライセンスに基づいてライセンスされています。詳細については、ライセンスを参照してください。
