Stable Baselines3

Visão Geral

Stable Baselines3 (SB3) é uma biblioteca baseada em PyTorch que fornece implementações confiáveis de algoritmos de aprendizado por reforço. Esta habilidade oferece orientação abrangente para treinar agentes de RL, criar ambientes personalizados, implementar callbacks e otimizar fluxos de trabalho de treinamento usando a API unificada do SB3.

Versão atual: SB3 2.9.0 (15 de junho de 2026). Documentação: stable-baselines3.readthedocs.io.

Instalação

Testado com stable-baselines3 2.9.0. Requer Python 3.10+ (3.9 foi removido em 2.8.0) e PyTorch >= 2.8.

# Basic installation
uv pip install "stable-baselines3==2.9.0"

# With extra dependencies (TensorBoard, ale-py for Atari, etc.)
uv pip install "stable-baselines3[extra]==2.9.0"

A versão 2.9.0 suporta Gymnasium >=0.29.1,<2.0; esta revisão utilizou Gymnasium 1.3.0, PyTorch 2.14.1 e Python 3.13 em CPU. pandas/matplotlib são agora opcionais. A instalação requer rede, a menos que os pacotes estejam em cache; o treinamento local de RL não precisa de credenciais ou endpoints de serviço.

No zsh, coloque os colchetes entre aspas: uv pip install 'stable-baselines3[extra]==2.9.0'.

Para benchmarks de controle contínuo MuJoCo:

uv pip install "gymnasium[mujoco]"

Verifique sua versão:

import stable_baselines3
print(stable_baselines3.__version__)

Projetos Relacionados

• SB3-Contrib: algoritmos experimentais (MaskablePPO, CrossQ, QR-DQN, RecurrentPPO) — pacote sb3-contrib separado
• RL Baselines3 Zoo: agentes pré-treinados, hiperparâmetros, scripts de treinamento
• SBX: SB3 + implementações JAX para usuários que preferem JAX ao PyTorch

Capacidades Principais

1. Treinando Agentes de RL

Padrão Básico de Treinamento:

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, device="cpu", seed=0)

# 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, device="cpu")
env.close()

Observações Importantes:

• total_timesteps é um limite inferior; o treinamento real pode exceder isso devido à coleta de lotes
• Chame o método de classe PPO.load(...) e mantenha o novo modelo retornado
• O buffer de replay NÃO é salvo com o modelo para economizar espaço

Seleção de Algoritmo: Use references/algorithms.md para características detalhadas do algoritmo e orientação de seleção. Referência rápida:

• PPO/A2C: Uso geral, suporta ações Box, Discrete, flat MultiDiscrete e MultiBinary, bom para multiprocessamento
• SAC/TD3: Controle contínuo, off-policy, eficiente em amostras
• DQN: Ações discretas, off-policy
• HER: Estratégia de buffer de replay para tarefas off-policy condicionadas por objetivo

Veja scripts/train_rl_agent.py para um template de treinamento completo com as melhores práticas.

2. Ambientes Personalizados

Requisitos: Ambientes personalizados devem herdar de gymnasium.Env e implementar:

• __init__(): Definir action_space e observation_space
• reset(seed, options): Retornar observação inicial e dicionário info
• step(action): Retornar observação, recompensa, terminated, truncated, info
• render(): Visualização (opcional)
• close(): Limpar recursos

Restrições Chave:

• O pré-processamento padrão de imagem CNN espera np.uint8 no intervalo [0, 255]
• Use o formato channel-first sempre que possível (canais, altura, largura)
• O SB3 normaliza imagens automaticamente dividindo por 255
• Para imagens float pré-normalizadas, use layout channel-first e policy_kwargs={"normalize_images": False}
• O SB3 NÃO suporta espaços Discrete ou MultiDiscrete com start!=0

Validação:

from stable_baselines3.common.env_checker import check_env

check_env(env, warn=True)

Veja o template e o guia de ambientes. O template agora observa as coordenadas do agente e do objetivo aleatório, formato (4,); checkpoints de formato antigo (2,) exigem retreinamento. gym.make("CustomEnv-v0") adiciona o limite de tempo de 100 passos; CustomEnv() direto não adiciona. check_env verifica a consistência da API, não a suficiência de Markov, a correção da recompensa ou a aprendibilidade.

…