简介这是一份面向强化学习入门到进阶者的完整资料包覆盖马尔可夫决策过程、表格型方法、策略梯度、DQN、PPO、演员-评论家、DDPG等主流算法并配有悬崖寻路、CartPole-v0、Pendulum-v0三个可运行项目案例兼顾理论讲解与代码实践适合自学、教学和项目起步。压缩包共223个文件大小约173.43MB以Python脚本、Jupyter Notebook、PNG图表、Markdown笔记、npy数据、模型权重pt/pth及少量PDF为主其中py源码可直接运行notebook便于分步调试图片用于展示训练曲线与结果目录按章节和项目组织方便按需查阅。目前已有678人学习或下载过这份资料包。内容涵盖稀疏奖励、模仿学习、连续动作控制等进阶主题并给出训练记录、Q-table等中间结果可用于对照调参、复现算法和排查收敛问题。1. 强化学习从基础到进阶这套码源齐全的资源包到底该怎么啃拿到一份打着强化学习从基础到进阶旗号、又带全系列超详细算法码源齐全的压缩包很多人的第一反应是解压、看目录、跑一个 demo然后就没有然后了。这个方向的真实门槛不在能不能看懂 Q-Learning而在环境搭建、算法调试、复现结果这三件事上资源包只能给你一个起点。这篇笔记就顺着这类码源包的典型结构讲清楚怎么把码源齐全变成我能改、我能调、我能复现而不是让文件在硬盘里吃灰。适合刚啃完 David Silver 那套课程、准备动手写代码的入门者也适合需要在 DQN、PPO 这些主流算法之间快速切换做对比实验的工程师。2. 拿到码源先别跑目录盘点和环境搭建的三步走2.1 全系列码源包的典型目录结构先分清能跑和能改解压这类压缩包之后第一步不是去看算法实现而是花十分钟把目录结构盘清楚。绝大多数流传的强化学习码源包内部会按算法家族分目录常见的有tabular/表格型方法、dqn/、pg/策略梯度、actor_critic/、multi_agent/多智能体这几类外加一个envs/或environments/放自定义环境最外层可能有requirements.txt或者environment.yml。先区分两类文件带train.py、main.py、run_*.py的是可以直接跑的入口带agent.py、model.py、buffer.py的是需要被 import 的模块也就是你后续要改的核心。我一般会先打开每个子目录下的 README 或注释头把算法版本和依赖框架标出来。这一步能避免后面最大的坑同一个包里DQN 用的是 PyTorchPPO 用的却是 TensorFlow两套环境混在一起安装依赖时会互相打架。另一个需要留意的点是环境版本。老一点的码源包gym还是 0.21 或者 0.26 的 APICartPole 的env.reset()返回的是单个状态新版本的gymnasium返回的是(observation, info)元组。这直接决定你后面要不要改代码。2.2 用 Python 虚拟环境隔离依赖最省事的强化学习环境搭建不要直接往系统 Python 里装包。强化学习项目对gym、numpy、torch的版本极其敏感一个项目的gym升到 0.26 可能另一个项目的代码就废了。常见做法是给这个码源包单独建一个虚拟环境如果项目里有environment.yml或requirements.txt优先用它来建。没有的话就按算法依赖的最小集来装。# 创建独立环境Python 版本按码源注释里的要求来拿不准就选 3.8 或 3.9 conda create -n rl_practice python3.9 -y conda activate rl_practice # 安装核心依赖torch 建议用 CPU 版把训练流程先跑通再换 CUDA 版 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu pip install gymnasium pip install matplotlib pandas tqdm这里把gymnasium和gym分开列出来是有原因的。新一点的强化学习环境封装基本都迁移到了gymnasium而老码源里写的是import gym。如果项目代码里 import 的是gym但环境里只装了gymnasium那import gym一样能过——gymnasium做了兼容但前提是你用pip install gymnasium而不是老版本的gym。反过来如果码源里用了gym独有的一些老 API安装gym0.21可能是更稳妥的选择。这个判断要看你盘的目录里代码到底写的什么。2.3 用最小脚本验证环境能通别等训练到一半才报错环境装完先跑一个烟雾测试确认gym环境能创建、能 step而不是直接跑完整训练。这一步能拦住大量问题版本不兼容、依赖缺失、渲染后端没装。一个最简单的验证脚本长这样# smoke_test.py验证 gym 环境与 numpy/torch 基础依赖可用 import gymnasium as gym import numpy as np import torch env gym.make(CartPole-v1, render_modeNone) obs, info env.reset(seed42) # 新版 gymnasium API返回 (observation, info) print(obs shape:, obs.shape) print(obs dtype:, obs.dtype) done False total_reward 0 step 0 while not done and step 200: action env.action_space.sample() # 随机策略先验证环境能正常交互 obs, reward, terminated, truncated, info env.step(action) total_reward reward done terminated or truncated step 1 print(frandom policy reward: {total_reward}) # 确认 torch 能正常做张量运算 x torch.tensor(np.random.randn(4, 128), dtypetorch.float32) print(torch tensor:, x.shape)这段脚本的逻辑很简单创建环境、随机采样动作、跑 200 步看环境是否正常返回。值得关注的是reset和step的返回结构新版gymnasium的reset返回(obs, info)step返回四个值老版gym的reset直接返回obsstep返回四个值但没有truncated。如果你的码源代码跟这个脚本对不上说明它写的是老 API需要做适配而不是去改环境。参数说明render_modeNone表示不开启渲染训练时千万别开否则画面渲染会拖慢训练速度好几倍seed42给环境和随机策略定了种子保证每次跑出来的随机轨迹一致方便后面调试时对比。3. 从表格型到深度强化学习按案例把算法主线串起来3.1 表格型方法Q-Learning 和 Sarsa 是理解一切的基础码源包里最先值得吃的算法是 Q-Learning。它是 off-policy 的代表也是后面 DQN 的直接前身。在环境状态空间有限比如 FrozenLake 这类格子世界时Q 表就是一张二维数组行是状态列是动作更新公式靠的是贝尔曼方程。很多初学者觉得 Q-Learning 太简单直接跳过去看 DQN这是这方向最容易走的弯路——DQN 的 target network、experience replay 全都是围绕用神经网络替代 Q 表展开的不理解 Q 表怎么查、怎么更新后面看 DQN 代码就像看天书。# q_learning.pyFrozenLake 上的 Q-Learning 核心更新逻辑 import gymnasium as gym import numpy as np env gym.make(FrozenLake-v1, is_slipperyTrue, map_name4x4) n_states env.observation_space.n n_actions env.action_space.n q_table np.zeros((n_states, n_actions)) alpha 0.1 # 学习率每次更新时新信息覆盖旧信息的比例 gamma 0.99 # 折扣因子未来奖励的衰减程度 epsilon 1.0 # 探索率初始时几乎全部随机探索 epsilon_min 0.01 epsilon_decay 0.999 for episode in range(5000): obs, info env.reset() done False total_reward 0 while not done: # epsilon-greedy以 epsilon 概率随机探索否则选当前 Q 值最大的动作 if np.random.rand() epsilon: action env.action_space.sample() else: action np.argmax(q_table[obs]) n_obs, reward, terminated, truncated, info env.step(action) done terminated or truncated # Q 值更新当前 Q 加上 学习率 * (实际奖励 折扣因子 * 下一状态最大Q - 当前Q) q_table[obs, action] alpha * ( reward gamma * np.max(q_table[n_obs]) - q_table[obs, action] ) obs n_obs total_reward reward epsilon max(epsilon_min, epsilon * epsilon_decay) if episode % 500 0: print(fepisode {episode}, epsilon {epsilon:.3f}, reward {total_reward})这段代码的关键在q_table[obs, action]的更新那一行它把当前 Q 值往实际奖励 下一状态最大 Q 值的方向拉了一步alpha控制拉的幅度。参数说明里最值得调的是gamma在 FrozenLake 这种每一步都可能有随机滑动的环境里gamma别设成 1.0否则 Q 值会发散。epsilon_decay设成 0.999 是让前期多做探索如果收敛太慢可以把衰减系数调小到 0.99但对应地训练步数也要缩短。3.2 DQN 系列经验回放和目标网络是两根支柱从 Q-Learning 跳到 DQN核心变化就两件事一是用深度神经网络拟合 Q 函数二是引入经验回放池和目标网络。经验回放解决的是样本相关性问题——强化学习采集到的连续 transition 之间高度相关直接按顺序训练会让网络在一批数据上反复打转目标网络解决的是训练不稳定问题——如果 Q 网络的参数每步都在变那目标值也在变优化目标一直在移动很难收敛。# dqn_buffer.py经验回放池的核心实现 import random import numpy as np from collections import deque class ReplayBuffer: def __init__(self, capacity10000): self.buffer deque(maxlencapacity) # 超容量自动弹出最老的样本 self.capacity capacity def push(self, state, action, reward, next_state, done): # 统一存成元组每个元素是单个 transition self.buffer.append((state, action, reward, next_state, done)) def sample(self, batch_size64): # 随机均匀采样打破时间相关性 batch random.sample(self.buffer, batch_size) states, actions, rewards, next_states, dones zip(*batch) return ( np.array(states, dtypenp.float32), np.array(actions, dtypenp.int64), np.array(rewards, dtypenp.float32), np.array(next_states, dtypenp.float32), np.array(dones, dtypenp.float32), ) def __len__(self): return len(self.buffer)deque(maxlencapacity)是这个实现里最省心的设计缓冲区满了以后新样本会自动顶掉最老的样本不需要手动管理索引。batch_size是训练时最常调的参数64 是多数环境里表现稳定的起点环境状态如果是图像输入比如 Ataribatch_size往往要降到 32因为单张图的张量就很大显存撑不住。采样方式这里用的是均匀随机采样码源包里如果看到带优先级的版本那就是 PERPrioritized Experience Replay它会让TD 误差大的样本更容易被抽到收敛更快但实现复杂度也高一个档次。目标网络的更新方式也是码源里差异最大的地方之一。常见做法是每 N 步把评估网络的参数直接复制给目标网络N 通常取 1000 或 2000也有用 Polyak 软更新的公式是target_param tau * eval_param (1 - tau) * target_param这里的tau一般取 0.005 或 0.01。硬更新简单粗暴但会有周期性波动软更新平滑但调起来需要多试几个tau值。3.3 Policy Gradient 到 PPO连续控制场景的主流选择DQN 系算法输出的是每个动作的 Q 值动作空间必须是离散的。做机器人控制、自动驾驶这类连续动作任务就得转到策略梯度家族。码源包里 Policy Gradient、Actor-Critic、PPO 这三个通常是放在一起的理解顺序也是这个递进关系。REINFORCE 算法的问题在于方差大一个 episode 的累积回报可能从几十到几千梯度估计极不稳定Actor-Critic 引入一个 Critic 网络来估计状态价值把回报的基线从整段回报均值换成了当前状态的预期价值方差立刻降一截PPO 则在 Actor-Critic 之上加了 clipped surrogate objective限制每次策略更新的幅度防止一步更新太大把策略推崩。# ppo_loss.pyPPO 的 clipped surrogate loss 核心计算逻辑 import torch import torch.nn.functional as F def compute_ppo_loss(log_probs, old_log_probs, advantages, epsilon0.2): # log_probs: 当前策略下动作的对数概率 # old_log_probs: 旧策略下动作的对数概率训练前先存下来 # advantages: 优势函数估计GAE 或单步 TD 误差均可 ratio torch.exp(log_probs - old_log_probs) # 未裁剪的 surrogate objective surr1 ratio * advantages # 裁剪后的 surrogate objectiveepsilon 控制更新幅度上限 surr2 torch.clamp(ratio, 1.0 - epsilon, 1.0 epsilon) * advantages # 取两者的最小值保证更新方向是至少不差于原策略 loss -torch.min(surr1, surr2).mean() return lossepsilon是这个 loss 里最核心的超参数默认 0.2 是 PPO 原论文里的设定实践下来大多数场景不用改。但如果你的任务奖励非常稀疏策略更新很容易一步走太远这时把epsilon降到 0.1 会更稳。ratio大于 1 说明新策略在这个状态下更可能选这个动作小于 1 则相反——裁剪的作用就是当ratio超出[0.8, 1.2]区间时梯度被截断防止一次更新把策略改得面目全非。码源包里跑 PPO 时advantages怎么算是个大分水岭。做得粗糙的版本直接用单步 TD 误差当优势简单但方差大做得规范的会实现 GAEGeneralized Advantage Estimation核心参数是lambda默认 0.95它控制偏差和方差的权衡——lambda越接近 1方差越大但偏差越小越接近 0偏差越大但方差越小。在 PPO 里lambda通常和epsilon一起调先固定epsilon0.2扫lambda的[0.9, 0.95, 0.99]。3.4 多智能体与离线强化学习进阶部分的看点码源包标着全系列的大概率会包含多智能体强化学习MARL和离线强化学习这两块这也是检索热词里 IQL、MADDPG、MAPPO 指向的部分。多智能体的核心难点在于环境是非平稳的——每个智能体的策略都在变对其他智能体来说环境就在不断变化直接套单智能体算法很难收敛。MADDPG 的思路是给每个智能体配一个中心化的 Critic训练时 Critic 能看到所有智能体的动作和状态但执行时 Actor 只看自己的局部观测。MAPPO 则是把 PPO 直接搬到多智能体场景靠参数共享和全局状态 Critic 来缓解非平稳问题。离线强化学习的场景不太一样训练数据不是实时采的而是来自一个固定的历史数据集你不能再跟环境交互。IQLImplicit Q-Learning这类算法的关键是不去估计超出数据集分布的动作价值它用 expectile regression 来避免 OOD 动作的 Q 值被高估。这个方向对数学功底的要求比前面所有算法都高码源包里如果带了论文复现的代码一般配套的也有数据集加载脚本。我的建议是入门阶段先跑通 MADDPG 在多智能体环境里的训练流程理解中心化训练、去中心化执行这个设计哲学IQL 则优先读代码里的loss部分和expectile参数expectile一般取 0.7 到 0.9它控制对高 Q 值样本的拟合权重。4. 让案例真正在自己机器上跑起来的三个关键组件4.1 经验回放池的容量与采样策略参数要这么设码源自带的经验回放池实现一般比较简单但超参数设置不合理训练曲线就是一条直线。容量capacity的默认值在 10000 到 100000 之间都有具体取多少要看状态表示的维度。CartPole 这种低维状态10000 容量足够Atari 这种图像输入典型设置是 500000 甚至 1000000因为图像帧的样本量大太小的池子存不下足够的多样性。采样策略上均匀采样是绝大多数状况下的安全起点。如果你发现训练早期 Q 值波动剧烈或者 Loss 曲线出现周期性尖峰再去考虑 PER。PER 的代码改动其实不大就是给每条样本加一个priority字段采样时按优先级概率抽同时用重要性采样权重修正偏差。但在改之前先确认你已经做过下面这步把batch_size从 64 调到 128把learning_rate从默认的 1e-3 降到 5e-4很多不收敛其实只是学习率太大导致 Loss 震荡。4.2 奖励设计和折扣因子的联动收敛快慢的隐藏开关强化学习项目里最玄学的部分是奖励设计。码源包里的环境自带奖励函数但你自己做应用时奖励函数几乎总是要重新写的。这里有一个经常被忽略的联动关系gamma和奖励稀疏度必须一起考虑。gamma越大智能体越看重远期收益但如果奖励是稀疏的走很多步才给一次奖励大的gamma会导致早期的 Q 值估计几乎全是零训练极慢。反过来gamma太小智能体变成短视学会了贪眼前的策略。我处理这个联动的一般做法是先把gamma固定在 0.99然后改奖励的稠密度——给每个 step 加一个小的负奖励比如 -0.01引导智能体尽快完成任务或者给接近目标的状态加 shaping reward。如果奖励密度改完还是收敛慢再回头调gamma每次按 0.01 的步长往下降看训练曲线的变化。注意改了奖励函数之后最优策略本身也会变不能只盯着收敛速度看还要看最终策略是否符合你的预期。4.3 随机种子与训练日志能不能复现全靠这两样复现性是强化学习工程里的老难题。同一份代码换一台机器跑训练曲线可能差很多同一个机器不设随机种子两次跑出来的结果也可能完全不同。所以拿到码源后的第一件事是确认代码里有没有全局设置随机种子。没有的话自己补上# seed_everything.py在训练脚本最开头调用统一控制所有随机源 import random import numpy as np import torch def seed_everything(seed42): random.seed(seed) # Python 内置随机 np.random.seed(seed) # NumPy 随机 torch.manual_seed(seed) # PyTorch CPU 随机 if torch.cuda.is_available(): torch.cuda.manual_seed_all(seed) # PyTorch GPU 随机 # 关闭 cuDNN 的自动优化该优化会导致训练结果不可复现 torch.backends.cudnn.deterministic True torch.backends.cudnn.benchmark Falsecudnn.deterministic True这行是关键它在图像输入类环境里尤其重要。cuDNN 默认会选最快的卷积算法但这个选择过程是随机的导致两次训练结果不一致。注意打开确定性后训练速度会略微下降这是为了可复现性付出的代价通常在可接受范围内。benchmark False是配套设置让 cuDNN 不去做运行时算法搜索。训练日志方面不要只打 episode 平均 reward 就完事。我建议至少记录四类信息每个 episode 的 reward、当前的epsilon或learning_rate这类衰减型参数、Critic 网络的 Loss 均值、以及 Q 值的均值或最大值。这几个指标能帮你区分策略在变好但 reward 还没体现和策略已经崩了。码源包里如果自带logger模块最好没有的话就用tqdm加csv就够了别一上来就上 TensorBoard增加心智负担。5. 复现码源时的高频翻车点现象、原因与处理5.1gym环境创建失败报ModuleNotFoundError或ValueError现象运行gym.make(CartPole-v0)直接报错提示没有这个环境或者版本不匹配。原因老码源里写的是CartPole-v0、MountainCar-v0这种老环境 ID新版gymnasium已经把它们移除了只剩CartPole-v1这类 v1 版本。封装名从gym到gymnasium的迁移也是同样的坑。解决先pip list | grep gym看装的是哪个包。如果是gymnasium把代码里的环境 ID 从-v0改成-v1再把env.reset()的返回改成接收(obs, info)元组。如果码源里用了很多老 API那干脆pip install gym0.21并在同一个虚拟环境里不装gymnasium避免两个包互相干扰。5.2 训练 Loss 不降反升曲线从头到尾是向上的现象DQN 的 Loss 在前几百步不但没下降反而一路走高reward 也是负的。原因最常见的是学习率过大Q 值更新一步跨太远Loss 在最优值附近反复震荡甚至发散。其次是对gamma设了 1.0 而且环境是稀疏奖励的Q 值不断累积未来奖励导致数值膨胀。解决先把学习率降到1e-4量级重跑一遍这一步能排除大多数问题。再把gamma从 0.99 往下调到 0.95观察 Q 值的最大绝对值是否还在增长。还有一个容易忽略的点Loss 的绝对值本身不代表策略好坏DQN 的 Loss 大往往意味着 Q 值在剧烈调整要同时看 episode reward 是否在涨。如果 reward 在涨而 Loss 在涨这是正常现象不用管。5.3 训练时显存溢出或 CUDA 报错CUDA out of memory现象训练跑到一半PyTorch 报CUDA out of memory或者干脆在torch.cuda.is_available()返回 False 的情况下硬跑 GPU 代码报AssertionError。原因码源包默认按 GPU 场景编写batch_size和网络隐藏层尺寸可能设置得偏大或者你机器上 PyTorch 装的是 CPU 版但代码里无条件调用了.cuda()。解决先用torch.cuda.is_available()确认当前环境是否真的有可用的 GPU。如果只是显存不够把batch_size从 64 降到 32 或 16同时把网络隐藏层维度从 256 降到 128显存占用能直接减一半还多。代码里所有.cuda()调用改成条件式的device torch.device(cuda if torch.cuda.is_available() else cpu) model QNetwork(...).to(device)这行代码的巧妙之处在于它把设备选择写成了一个自适应逻辑换机器不用改代码。Tensor 也要记得.to(device)否则模型在 GPU、数据在 CPU会报 device mismatch 错误。5.4 多智能体项目训练特别慢一个 step 要好几秒现象跑 MADDPG 或 MAPPO 时每一步都要等很久训练 1000 个 episode 可能要几个小时。原因多智能体环境的 step 本身就要串行更新所有智能体的动作比单智能体慢是正常的但如果你发现慢得离谱通常是代码里每个 step 都重新创建了环境或者日志对象或者渲染模式没有关掉。解决先确认环境创建是一次性的写在__init__或main函数里而不是放在 episode 循环内部。再检查gym.make的render_mode如果是human或者rgb_array在纯训练场景下务必改成None。最后考虑用torch.no_grad()包住数据收集阶段的 forward 计算——动作选择和 Q 值计算都不需要梯度PyTorch 不开梯度图能快 20% 到 30%。这是码源包里很少做优化的一个点很多人忽略。5.5 老代码在新 API 上报错reset返回结果对不上现象代码里写obs env.reset()环境一跑就报ValueError: too many values to unpack。原因老版gym的env.reset()只返回obs新版gymnasium返回(obs, info)元组。码源如果是 2022 年之前写的大概率是前者如果你的环境是 2023 年后装的默认装的是后者。解决统一改成obs, info env.reset()并把env.step的返回值从四个改成五个——新版 step 返回(obs, reward, terminated, truncated, info)把done terminated or truncated合并成一个布尔值后面所有判断done的地方就都能复用。这个适配大概要花半小时但能让老码源在 2024 年的环境上重新跑起来很值。6. 把码源改造成自己的实验框架一个能省半年时间的做法码源包真正值钱的地方不在于某一行算法实现得多么精妙而在于它提供了一个可以横向对比的算法集合。我拿到这类资源包后的最后一件事是抽出一个统一的 Agent 接口把所有算法套进同一个模板里跑对比实验。这个习惯帮我避开了后续很多重复劳动。# base_agent.py统一所有算法的接口模板 class BaseAgent: def __init__(self, state_dim, action_dim, config): self.state_dim state_dim self.action_dim action_dim self.config config self.logs {episode_reward: [], loss: []} def select_action(self, state): # 训练时根据策略选择动作含探索 raise NotImplementedError def update(self, batch): # 从经验池采样一批数据并更新网络参数 raise NotImplementedError def save(self, path): # 保存模型权重 raise NotImplementedError def load(self, path): # 加载模型权重用于后续评估或继续训练 raise NotImplementedError把 DQN、PPO、MADDPG 都实现成这个接口你的对比实验就从每个算法跑一遍训练、手动改超参变成了写一个统一训练循环换 Agent 实现和配置字典就能跑。配置用字典管理{algorithm: dqn, batch_size: 64, gamma: 0.99}这种形式每个实验的配置直接存成 JSON 文件跟训练曲线放在一起以后想追溯某个结果是怎么来的打开 JSON 就一目了然。我踩过最狠的坑是某次对比实验跑完一周发现两组实验的gamma一个设了 0.99、一个设了 0.9而我没有记录配置结果曲线没法解释。从那以后我养成了两个习惯一是所有实验配置必须落盘二是每个算法跑完必须用相同种子的评估流程测一遍真实性能而不是直接用训练过程的 reward 曲线下结论。训练曲线的上下波动可能来自探索噪声只有固定种子、关闭探索的评估才能反映算法的真实水平。希望这些经验对你有帮助。本文还有配套的精品资源点击获取