强化学习入门：Stable Baselines3环境配置完整指南

做强化学习实验，我见过太多人卡在第一步：不是算法理解不了，而是Baselines3的环境配置死活搞不定。有人装完库一import就报错，有人gym环境创建失败，有人折腾一整天发现是Python版本不对。这个系列第一篇，我想把Baselines3环境配置这件事彻底讲明白，包括每个关键决定背后的原因、踩过的坑、以及我现在固定使用的操作流。

这篇文章适合两类人：一类是刚接触强化学习、想尽快跑通PPO或DQN做实验的初学者；另一类是已经能跑demo，但经常被环境问题打断、想系统梳理一遍配置逻辑的进阶玩家。我会按“先理解再动手”的顺序来写，不直接甩命令。

1. 动手之前先想清楚：一套强化学习环境到底由什么组成

1.1 一个强化学习实验环境的最小闭环

在输入安装命令之前，先抛开Baselines3这个具体的名字，看看一个强化学习训练脚本运行时到底需要哪些组件。

任何一个基于Baselines3的最小训练闭环，都包含四部分：Python解释器、数值计算引擎、环境交互接口、算法实现库。Python解释器是载体，负责运行脚本；数值计算引擎提供张量计算和自动求导，训练神经网络全靠它，通常就是PyTorch；环境交互接口负责提供“状态-动作-奖励”的世界，在Baselines3生态里最常见的是一条叫Gymnasium的库；算法实现库就是Baselines3本身，它负责把PPO、DQN、SAC这些算法的训练流程封装好，让你不用从头写。

很多人装环境只盯着最后一层，结果前面的基础没打好，后面全是连锁反应。我在不少机器上见过诡异的配置：Python 3.13配了很老的PyTorch，或者Gymnasium版本和Baselines3完全不兼容。搞清楚这个结构之后，排查问题就知道该往哪里看了。

1.2 为什么Baselines3适合作为入门和实验主力

Baselines3（社区经常简称SB3）是我个人最推荐的算法库，核心原因是它把“算法逻辑”和“工程细节”分得很开。你只需要定义环境和一个模型对象，就能开始训练；同时它的代码又足够规范，想深入看某个算法时能直接读源码。

对比过其他方案之后你会明白它的优势：自己手写PPO源码虽然能加深理解，但调试成本高，一晚上可能全花在数值稳定性上；而Baselines3封装好的稳定实现，能让你把精力聚焦在问题本身。实验效果不理想时，可以先用它的默认参数跑一版基线，再做修改。这比从零造轮子靠谱得多。

需要提醒的是，Baselines3不是万能的。它目前没有原生支持某些最新算法，另外如果你的场景需要大量定制化网络结构，改造难度会大一些。但作为入门和常规实验，它的性价比非常高。

1.3 版本选择要先定基调：Python和PyTorch先对齐

所有配置问题的根源，几乎都是版本搭配问题。现在Baselines3要求Python 3.8以上，PyTorch要求2.x以上较稳妥。我的建议是：新机器直接上Python 3.10，这是目前兼容性最均衡的版本，相关的预编译包最全，遇到奇奇怪怪编译问题的概率最低。

PyTorch方面，CPU训练装CPU版，有NVIDIA显卡再考虑CUDA版。确定显卡驱动支持什么CUDA版本，再去PyTorch官网选对应版本。不要贪新，不要看到最新的就装，稳定性优先。下面这张表是我实测比较省心的搭配方案，供参考：

2. 从零开始的安装实录：推荐路径与避坑操作

2.1 先建一个干净虚拟环境，别污染系统Python

我强烈建议用conda或venv创建独立环境，不要让所有项目共享同一个Python。原因不是洁癖，而是不同项目的依赖经常相互冲突。今天要装的这套东西牵涉多层的包，如果没有隔离，很可能影响到你机器上其它项目。

我一般用conda来创建环境，因为它处理Python版本切换比较省事。打开终端执行：

conda create -n rl-env python=3.10 -y conda activate rl-env

这里要说明的是，等conda激活完成后，你当前Shell前面会出现环境名。后续所有安装和运行实验都在这同一个环境里做。如果你中途打开了新的终端，需要重新执行activate。很多新手遇到“明明装好了却提示找不到包”，就是因为激活了另一个环境。

如果机器上没装conda，直接使用Python官方的venv也可以，只是Python版本需要在创建时就对号入座：

python3.10 -m venv rl-env source rl-env/bin/activate

2.2 安装PyTorch：先确认CUDA情况再决定选项

安装PyTorch是整个环节里最容易出错的一步，关键在于很多人不看自己的机器就直接复制粘贴了GPU命令。先做一件事：确认有没有NVIDIA独立显卡和可用驱动。终端里执行nvidia-smi，如果有输出，说明可以走CUDA路线；如果提示找不到命令，大概率是没有或没装驱动，老老实实用CPU版。

无GPU机器直接用CPU版：

pip install torch torchvision torchaudio

有GPU的机器，不要直接装默认版本，去PyTorch官网根据自己的CUDA版本选对应命令。这里有个常见的误区：torch.cuda.is_available()返回False，很多人以为PyTorch没装好，其实是装了CPU版或者CUDA版和驱动不匹配。判断这个问题的标准动作是先看nvidia-smi里显示的CUDA版本，再决定PyTorch对应的CUDA版本。

另外我想特别提醒：在纯CPU机器上用小网络跑CartPole和LunarLander这类简单环境，训练速度完全够用，新手不需要为了“感觉专业”非要去搞GPU。等真正处理图像输入和连续控制任务时，再考虑CUDA也不迟。

2.3 安装Gymnasium和Baselines3

环境激活、PyTorch搞定之后，剩下的安装就非常简单了。直接执行：

pip install gymnasium pip install stable-baselines3 pip install tensorboard

Gymnasium是强化学习环境的标准接口库，提供了CartPole、MountainCar、LunarLander这些内置环境，也定义了环境交互的统一API。Baselines3依赖它来创建和交互训练环境。Tensorboard是训练日志可视化工具，虽然它不直接影响训练，但几乎是我实验流程里的标配。

安装完成后，可以顺手把常用依赖文件能力也装了，后面录制训练视频、做可视化评估时能用到：pip install moviepy imageio。不装也能跑，但用到时再回头补，不如一次到位。

2.4 验证安装的最小脚本

装完之后别急着写训练逻辑，先跑一个最小验证脚本，确保每一层组件都是通的。下面这个脚本只会创建环境、构建模型、执行极少步数的训练，时间开销很小：

import gymnasium as gym from stable_baselines3 import PPO print("gymnasium version:", gym.__version__) env = gym.make("CartPole-v1", render_mode=None) model = PPO("MlpPolicy", env, verbose=0) model.learn(total_timesteps=256) print("environment ok, SB3 ok")

如果脚本能顺利打印出gymnasium版本号和最后的ok提示，说明环境配置基本过关。这里有两个容易出现的细节：第一次导入时可能伴随一些FutureWarning或DeprecationWarning，这大多是无害的，不用紧张；verbose=0表示不打印训练过程，这里只是为了静默验证，正式训练时可以改成一个正整数。

3. 首次运行时的自检与常见报错排查

3.1 第一步自检：导入与版本打印

如果你运行验证脚本时出了错，先做分层排查，不要一上来就卸载重装。第一步先检查最外层算法库能否导入：

python -c "import stable_baselines3; print(stable_baselines3.__version__)"

如果能导入，说明包本体没坏，问题大概率出在环境层或数值计算层。再检查：

python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"

这一步能看出PyTorch是否正常，以及CUDA是否可用。最后检查import gymnasium。用这种自底向上的方式逐层隔离，比胡乱重装要高效得多。

3.2 gym包名和gymnasium的历史坑

很多新手遇到的第一个报错是：ModuleNotFoundError: No module named 'gym'，或者代码里明明写了gym，但运行的组件却在找gymnasium。这就是强化学习库里一次著名换代的阴影：以前大家都用gym，后来该生态被接管并改名成gymnasium，API虽然很接近，但包名完全分了家。

Baselines3新版依赖的是gymnasium，但某些老代码、第三方教程或旧版代码里还在写import gym。解决办法只有一个：不要混装，不要在一个环境里同时用新版gym和gymnasium的关键API调用。写新代码就用gymnasium，如果你的参考项目很老、必须用gym，那就把Baselines3的版本降到还兼容老gym的版本，然后整体统一。最怕的是两个包递归依赖，你今天修好一个，明天又冒出一个，局面会越来越乱。

3.3 环境创建失败与Atari相关报错

gym.make("CartPole-v1")跑通了，不代表你能玩转所有环境。常见的一个坑是跑Atari环境时报错如下：

No version of the game environment is installed, you can install with `pip install gymnasium[atari]`

这个报错其实已经提示得很明显，但很多人还是会重复尝试。问题在于gymnasium把不同环境拆成了附加包，Atari相关依赖不是默认安装的。需要执行：

pip install gymnasium[atari]

有些版本的API要求同时指定render_mode参数，比如gym.make("ALE/Breakout-v5", render_mode="rgb_array")。还有个别游戏需要额外的ROM文件，这就是另一个层面的许可问题了，新手暂时不需要深究，先用CartPole、LunarLander这些无附加依赖的环境入门即可。

3.4 CUDA看起来正常，但训练根本不走GPU

有人torch.cuda.is_available()明明返回True，启动训练时却发现GPU利用率一直是0%，或者干脆“using cpu device”。这时先看模型构建和训练时的device设置。Baselines3的自动设备选择逻辑比较保守，如果你没显式指定device，在部分环境下会默认落到CPU。手动指定一下：

model = PPO("MlpPolicy", env, verbose=1, device="cuda" if torch.cuda.is_available() else "cpu")

如果显式指定了cuda但仍报错，再回看nvidia-smi的驱动版本和PyTorch编译的CUDA版本是否配对。还有一种被忽略的情况：你用了远程服务器，但PyTorch跑在Docker等容器里，容器没有挂载GPU，代码层面自然看不到。这种问题排查用nvidia-smi在容器内外各执行一次就能定位。

4. 跑通之后的环境进阶配置

4.1 使用向量化环境提升训练效率

Baselines3的核心设计里有一个概念叫“向量化环境”（Vectorized Env），它一次跑多个环境副本，采样效率比单环境高很多。安装时你可能没有注意到，但几乎所有正经实验都会用到它。

建议把官网推荐的make_vec_env作为标配。示例写法：

from stable_baselines3.common.env_util import make_vec_env env = make_vec_env("CartPole-v1", n_envs=4, seed=42) model = PPO("MlpPolicy", env, verbose=1) model.learn(total_timesteps=100_000)

这里n_envs=4表示同时并行跑4个环境。为什么需要这样？因为强化学习中算法每次更新前要采集一批样本，单环境采样一万步要花很久，并行环境能把同样时间内的样本量提上去。新手容易忽略的是，使用make_vec_env后，原来的单环境包装逻辑会变，比如后续要检查观测数据，需要进到.envs[0]里面，不要拿外面包着一层的VecEnv直接当普通环境用。

4.2 训练过程的可视化和录像

没有可视化的强化学习实验是不完整的。Baselines3官方提供了方便的记录回调，可以配合Tensorboard使用：

from stable_baselines3.common.callbacks import TensorboardCallback model = PPO("MlpPolicy", env, verbose=1, tensorboard_log="./tb_logs/") model.learn(total_timesteps=50_000, callback=TensorboardCallback())

Tensorboard是必须提的，因为强化学习训练曲线能直观告诉你算法有没有在学习。启动方式是tensorboard --logdir=./tb_logs/，然后在浏览器里看reward曲线。如果你发现曲线纹丝不动，先别怀疑代码，可能是环境奖励稀疏、超参不合适，或者本来就是这种环境的正常现象。

想“看到”训练好的智能体实际表现，可以拍摄视频。Baselines3官方有base_record_video和VideoRecorder这类辅助工具。不过从我的经验来看，最省心的录制路径是用gymnasium自己的RecordVideo包装器，参数量少，成品是mp4文件，分享起来也方便。

4.3 固定随机种子的习惯

强化学习实验跑十次可能得出十种结果，这是正常的，但为了复现和对比，固定随机种子是必修课。Baselines3提供了非常顺手的方法：

from stable_baselines3.common.utils import set_random_seed set_random_seed(42) env = make_vec_env("CartPole-v1", n_envs=4, seed=42) model = PPO("MlpPolicy", env, verbose=1, seed=42)

这里的逻辑是把Python标准库随机数、NumPy随机数、PyTorch随机数都统一固定，连环境内部的随机源也一并固定。只有这样才能保证“同样的代码每次跑出来的曲线趋势一致”。写实验笔记时，把seed值记下来是基本素养，否则后续调参很容易被随机性误导。

4.4 依赖管理的冻结策略

环境配置好之后，最容易后悔的一件事是“随手升级了某个包”。我见过很多人今天pip install --upgrade一下，第二天Baselines3就跑不起来了。解决思路很朴素：把你跑通实验时所有关键包的版本号记录下来。

创建requirements.txt：

python = 3.10 torch == 2.1.2 gymnasium == 0.29.1 stable-baselines3 == 2.2.1 numpy == 1.26.4

之后无论是换机器还是重新部署，都用这份清单来还原环境，而不是“最新版全家桶”。很多让人抓狂的兼容问题，本质上都是“版本漂移”造成的。

5. 我踩过的几个配置坑，以及现在的固定操作流

5.1 值得记录的“反面教材”

我第一次配置Baselines3时，直接用系统Python 3.8，在全局环境里东装一个西装一个，结果某天一个项目需要升级NumPy，Baselines3对我报了一堆类型错误。那种错最难查，因为报错分散在底层库里面，不看堆栈完全找不到是版本冲突。后来我把所有项目都迁移到独立环境，这类问题就几乎消失了。

第二个坑是关于Python版本。有段时间我为了尝鲜用了Python 3.13，结果gymnasium的某些预编译轮子还没有对应的，直接现场跑源码编译，最后还因为编译器版本失败。从那以后我给自己定了一个原则：强化学习相关项目统一Python 3.10，不追新，除非有特别明确的需要。

第三个坑和CUDA有关。我喜欢在服务器上跑实验，但服务器上每个账户的驱动环境经常不一样，再加上有的环境里CUDA变量没有正确暴露，导致PyTorch认为机器不支持GPU。后来我会在每次装完PyTorch后立刻跑一次torch.cuda.is_available()作为自检，并且把这一步固定写进自己的环境配置检查清单里。

5.2 我现在固定使用的一套操作流

兜了这么多圈子，我把现在新机器上配置Baselines3环境的步骤固定成以下标准流程，每次直接照做，出错率极低：

1. 创建conda环境，指定Python 3.10。
2. 激活环境，先用nvidia-smi确认显卡和CUDA状态。
3. 根据“是否有可用GPU”选择合适的PyTorch安装命令，安装完成后立即用一行脚本验证torch.cuda.is_available()。
4. 统一执行pip install gymnasium stable-baselines3 tensorboard，不单独乱装环境附加包。
5. 跑一次最小验证脚本，确认可以完成32步以内的训练。
6. 导出pip freeze > requirements.txt，把环境固化成文件。
7. 后续涉及新项目时，在新环境里用pip install -r requirements.txt还原。

这套流程看起来很普通，但关键在于每一步都有对应的验证动作。环境配置这种工作，最怕的就是“感觉装完了”就开跑，报错才回头排查。前置的验证步骤能避免花费大量时间在模糊排查上。

5.3 配置告一段落后的临别提醒

环境配置只是强化学习实战的入场券，我见过太多人花费一周解决配置问题，却在真正开始调参时失去了耐心。请务必记住：这套环境的价值是让你更快地产出实验结论，而不是用来反复折腾安装。如果配置过程中某个问题卡住超过两小时，我的建议是果断删掉环境重新来一遍，按本文的固定流程走，往往比继续深挖一个莫名报错更快。

以后在这个系列里，我会基于这套环境继续写策略训练、超参数调优、自定义环境和实际应用案例。环境这块打好地基，后面的内容才能真正跑起来。