tianshou
v1.1.0
Tianshou (天授 天授) é uma biblioteca de aprendizado de reforço (RL) baseada em pytorch puro e ginásio. As principais características de Tianshou em uma olhada são:
Diferentemente de outras bibliotecas de aprendizado de reforço, que podem ter bases de código complexas, APIs de alto nível hostis ou não são otimizadas para velocidade, o Tianshou fornece uma estrutura modularizada de alto desempenho e interfaces amigáveis para criar agentes de aprendizado de reforço profundo. Mais um aspecto que diferencia Tianshou é sua generalidade: ele suporta RL online e offline, RL multi-agente e algoritmos baseados em modelo.
Tianshou visa permitir implementações concisas, tanto para pesquisadores quanto profissionais, sem sacrificar a flexibilidade.
Os algoritmos suportados incluem:
Outros recursos notáveis:
Em chinês, Tianshou significa divinamente ordenado, sendo derivado do dom de nascer. Tianshou é uma plataforma de aprendizado de reforço, e a natureza do RL não é aprender com os seres humanos. Portanto, levar "Tianshou" significa que não há professor para aprender, mas aprender por si mesmo por meio de interação constante com o meio ambiente.
“天授” 意指上天所授 ， 引申为与生具有的天赋。天授是强化学习平台 ， 而强化学习算法并不是向人类学习的 ， 所以取 “天授” 意思是没有老师来教 ， 而是自己通过跟环境不断交互来进行学习。
Atualmente, Tianshou está hospedado em Pypi e Conde-Forge. Requer python> = 3.11.
Para instalar a versão mais recente do Tianshou, a melhor maneira é clonar o repositório e instalá -lo com poesia (que você precisa instalar no seu sistema primeiro)
git clone [email protected]:thu-ml/tianshou.git
cd tianshou
poetry install Você também pode instalar os requisitos de desenvolvimento adicionando --with dev ou os extras para, por exemplo, Mujoco e aceleração da Envpool, acrescentando --extras "mujoco envpool"
Se você deseja instalar vários extras, certifique -se de incluí -los em um único comando. As chamadas seqüenciais para poetry install --extras xxx substituirão as instalações anteriores, deixando apenas os últimos extras especificados instalados. Ou você pode instalar todos os seguintes extras adicionando --all-extras .
Os extras disponíveis são:
atari (para ambientes Atari)box2d (para ambientes Box2D)classic_control (para ambientes clássicos de controle (discreto))mujoco (para ambientes mujoco)mujoco-py (para o Legacy Mujoco-Py Ambiente 1 )pybullet (para ambientes pybullets)robotics (para ambientes de ginásio-robótica)vizdoom (para ambientes Vizdoom)envpool (para integração Envpool)argparse (para poder executar os exemplos de API de alto nível)Caso contrário, você pode instalar o lançamento mais recente da Pypi (atualmente atrás do mestre) com o seguinte comando:
$ pip install tianshouSe você estiver usando o Anaconda ou Miniconda, pode instalar o Tianshou da conda-forge:
$ conda install tianshou -c conda-forgeAlternativamente à instalação da poesia, você também pode instalar a versão de origem mais recente através do GitHub:
$ pip install git+https://github.com/thu-ml/tianshou.git@master --upgradePor fim, você pode verificar a instalação através do seu console Python da seguinte forma:
import tianshou
print ( tianshou . __version__ )Se nenhum erro for relatado, você instalou com sucesso o Tianshou.
Os tutoriais e a documentação da API estão hospedados em tianshou.readthedocs.io.
Encontre scripts de exemplo no teste/ e exemplos/ pastas.
| Plataforma RL | Documentação | Cobertura de código | Dicas de tipo | Última atualização |
|---|---|---|---|---|
| Estável-Baselines3 | ✔️ | |||
| Ray/Rllib | ➖ (1) | ✔️ | ||
| Girando | ||||
| Dopamina | ||||
| ACME | ➖ (1) | ✔️ | ||
| Amostra de fábrica | ➖ | |||
| Tianshou | ✔️ |
(1): tem integração contínua, mas a taxa de cobertura não está disponível
Tianshou é rigorosamente testado. Em contraste com outras plataformas RL, nossos testes incluem o procedimento completo de treinamento de agentes para todos os algoritmos implementados . Nossos testes falhariam uma vez se algum dos agentes falhasse em atingir um nível consistente de desempenho em épocas limitadas. Nossos testes garantem, portanto, a reprodutibilidade. Confira a página Ações do Github para obter mais detalhes.
Os resultados da referência Atari e Mujoco podem ser encontrados nos exemplos/ Atari/ e exemplos/ mujoco/ pastas, respectivamente. Nossos resultados mujoco alcançam ou excedem o nível de desempenho da maioria dos benchmarks existentes.
Todos os algoritmos implementam a seguinte API altamente geral:
__init__ : inicialize a política;forward : Calcule ações com base em determinadas observações;process_buffer : Processe buffer inicial, que é útil para alguns algoritmos de aprendizado offlineprocess_fn : dados de pré-processamento do buffer de repetição (já que reformamos todos os algoritmos para reproduzir algoritmos baseados em buffers);learn : aprenda com um determinado lote de dados;post_process_fn : atualize o buffer de repetição do processo de aprendizado (por exemplo, buffer de reprodução priorizado precisa atualizar o peso);update : A interface principal para treinamento, ou seja, process_fn -> learn -> post_process_fn .A implementação desta API é suficiente para que um novo algoritmo seja aplicável no Tianshou, fazendo experimentos com novas abordagens particularmente diretas.
Tianshou fornece dois níveis de API:
A seguir, vamos considerar um exemplo de aplicativo usando o ambiente de ginásio Cartpole . Aplicaremos o algoritmo de aprendizado de rede Q Deep Q (DQN) usando as duas APIs.
Para começar, precisamos de algumas importações.
from tianshou . highlevel . config import SamplingConfig
from tianshou . highlevel . env import (
EnvFactoryRegistered ,
VectorEnvType ,
)
from tianshou . highlevel . experiment import DQNExperimentBuilder , ExperimentConfig
from tianshou . highlevel . params . policy_params import DQNParams
from tianshou . highlevel . trainer import (
EpochTestCallbackDQNSetEps ,
EpochTrainCallbackDQNSetEps ,
EpochStopCallbackRewardThreshold
) Na API de alto nível, a base para um experimento de RL é um ExperimentBuilder com o qual podemos construir o experimento que procuramos correr. Como queremos usar o DQN, usamos o DQNExperimentBuilder de especialização. As outras importações servem para fornecer opções de configuração para o nosso experimento.
A API de alto nível fornece semântica amplamente declarativa, ou seja, o código está quase exclusivamente preocupado com a configuração que controla o que fazer (e não como fazê-lo).
experiment = (
DQNExperimentBuilder (
EnvFactoryRegistered ( task = "CartPole-v1" , train_seed = 0 , test_seed = 0 , venv_type = VectorEnvType . DUMMY ),
ExperimentConfig (
persistence_enabled = False ,
watch = True ,
watch_render = 1 / 35 ,
watch_num_episodes = 100 ,
),
SamplingConfig (
num_epochs = 10 ,
step_per_epoch = 10000 ,
batch_size = 64 ,
num_train_envs = 10 ,
num_test_envs = 100 ,
buffer_size = 20000 ,
step_per_collect = 10 ,
update_per_step = 1 / 10 ,
),
)
. with_dqn_params (
DQNParams (
lr = 1e-3 ,
discount_factor = 0.9 ,
estimation_step = 3 ,
target_update_freq = 320 ,
),
)
. with_model_factory_default ( hidden_sizes = ( 64 , 64 ))
. with_epoch_train_callback ( EpochTrainCallbackDQNSetEps ( 0.3 ))
. with_epoch_test_callback ( EpochTestCallbackDQNSetEps ( 0.0 ))
. with_epoch_stop_callback ( EpochStopCallbackRewardThreshold ( 195 ))
. build ()
)
experiment . run ()O construtor de experimentos leva três argumentos:
watch=True ) para vários episódios ( watch_num_episodes=100 ). Desativamos a persistência, porque não queremos salvar registros de treinamento, o agente ou sua configuração para uso futuro.num_epochs=10 )step_per_epoch=10000 ). Cada época consiste em uma série de etapas de coleta de dados (lançamento) e etapas de treinamento. O parâmetro step_per_collect controla a quantidade de dados que são coletados em cada etapa da coleta e após cada etapa da coleta, realizamos uma etapa de treinamento, aplicando uma atualização baseada em gradiente com base em uma amostra de dados ( batch_size=64 ) retirado do buffer de dados que foram coletados. Para mais detalhes, consulte a documentação do SamplingConfig .Em seguida, continuamos a configurar alguns dos parâmetros do próprio algoritmo DQN e do modelo de rede neural que queremos usar. Um detalhe específico do DQN é o uso de retornos de chamada para configurar o parâmetro epsilon do algoritmo para exploração. Queremos usar a exploração aleatória durante os lançamentos (retorno de chamada do trem), mas não o fizemos ao avaliar o desempenho do agente nos ambientes de teste (retorno de chamada de teste).
Encontre o script em exemplos/discreto/discrete_dqn_hl.py. Aqui está uma corrida (com o tempo de treinamento interrompido):
Encontre muitas aplicações adicionais da API de alto nível nos examples/ pasta; Procure scripts terminando com _hl.py . Observe que a maioria desses exemplos requer o pacote extra argparse (instale -o adicionando --extras argparse ao invocar a poesia).
Vamos agora considerar um exemplo análogo na API processual. Encontre o script completo em exemplos/discreto/discrete_dqn.py.
Primeiro, importe alguns pacotes relevantes:
import gymnasium as gym
import torch
from torch . utils . tensorboard import SummaryWriter
import tianshou as tsDefina alguns hiper-parâmetros:
task = 'CartPole-v1'
lr , epoch , batch_size = 1e-3 , 10 , 64
train_num , test_num = 10 , 100
gamma , n_step , target_freq = 0.9 , 3 , 320
buffer_size = 20000
eps_train , eps_test = 0.1 , 0.05
step_per_epoch , step_per_collect = 10000 , 10Inicialize o Logger:
logger = ts . utils . TensorboardLogger ( SummaryWriter ( 'log/dqn' ))
# For other loggers, see https://tianshou.readthedocs.io/en/master/01_tutorials/05_logger.htmlFazer ambientes:
# You can also try SubprocVectorEnv, which will use parallelization
train_envs = ts . env . DummyVectorEnv ([ lambda : gym . make ( task ) for _ in range ( train_num )])
test_envs = ts . env . DummyVectorEnv ([ lambda : gym . make ( task ) for _ in range ( test_num )])Crie a rede e seu otimizador:
from tianshou . utils . net . common import Net
# Note: You can easily define other networks.
# See https://tianshou.readthedocs.io/en/master/01_tutorials/00_dqn.html#build-the-network
env = gym . make ( task , render_mode = "human" )
state_shape = env . observation_space . shape or env . observation_space . n
action_shape = env . action_space . shape or env . action_space . n
net = Net ( state_shape = state_shape , action_shape = action_shape , hidden_sizes = [ 128 , 128 , 128 ])
optim = torch . optim . Adam ( net . parameters (), lr = lr )Configure a política e os colecionadores:
policy = ts . policy . DQNPolicy (
model = net ,
optim = optim ,
discount_factor = gamma ,
action_space = env . action_space ,
estimation_step = n_step ,
target_update_freq = target_freq
)
train_collector = ts . data . Collector ( policy , train_envs , ts . data . VectorReplayBuffer ( buffer_size , train_num ), exploration_noise = True )
test_collector = ts . data . Collector ( policy , test_envs , exploration_noise = True ) # because DQN uses epsilon-greedy methodVamos treiná -lo:
result = ts . trainer . OffpolicyTrainer (
policy = policy ,
train_collector = train_collector ,
test_collector = test_collector ,
max_epoch = epoch ,
step_per_epoch = step_per_epoch ,
step_per_collect = step_per_collect ,
episode_per_test = test_num ,
batch_size = batch_size ,
update_per_step = 1 / step_per_collect ,
train_fn = lambda epoch , env_step : policy . set_eps ( eps_train ),
test_fn = lambda epoch , env_step : policy . set_eps ( eps_test ),
stop_fn = lambda mean_rewards : mean_rewards >= env . spec . reward_threshold ,
logger = logger ,
). run ()
print ( f"Finished training in { result . timing . total_time } seconds" ) Salvar/carregar a política treinada (é exatamente o mesmo que carregar uma torch.nn.module ):
torch . save ( policy . state_dict (), 'dqn.pth' )
policy . load_state_dict ( torch . load ( 'dqn.pth' ))Assista ao agente com 35 fps:
policy . eval ()
policy . set_eps ( eps_test )
collector = ts . data . Collector ( policy , env , exploration_noise = True )
collector . collect ( n_episode = 1 , render = 1 / 35 )Inspecione os dados salvos no Tensorboard:
$ tensorboard --logdir log/dqnLeia a documentação para uso avançado.
Tianshou ainda está em desenvolvimento. Outros algoritmos e recursos estão sendo adicionados continuamente, e sempre recebemos contribuições para ajudar a melhorar Tianshou. Se você deseja contribuir, consulte este link.
Se você achar útil o Tianshou, cite -o em suas publicações.
@article{tianshou,
author = {Jiayi Weng and Huayu Chen and Dong Yan and Kaichao You and Alexis Duburcq and Minghao Zhang and Yi Su and Hang Su and Jun Zhu},
title = {Tianshou: A Highly Modularized Deep Reinforcement Learning Library},
journal = {Journal of Machine Learning Research},
year = {2022},
volume = {23},
number = {267},
pages = {1--6},
url = {http://jmlr.org/papers/v23/21-1127.html}
}Tianshou é apoiado pelo Instituto Aplicado da Europa, que está comprometido em fornecer apoio e desenvolvimento de longo prazo.
Tianshou era anteriormente uma plataforma de aprendizado de reforço baseada no TensorFlow. Você pode conferir a filial priv para obter mais detalhes. Muito obrigado ao trabalho pioneiro de Haosheng Zou para Tianshou antes da versão 0.1.1.
Gostaríamos de agradecer a Tsail e Institute for Artificial Intelligence, a Universidade de Tsinghua por fornecer uma excelente plataforma de pesquisa de IA.
mujoco-py é um pacote herdado e não é recomendado para novos projetos. É incluído apenas para compatibilidade com projetos mais antigos. Observe também que pode haver problemas de compatibilidade com o MacOS mais recente que o Monterey. ↩
