简介一份基于MATLAB的Q-Learning完整源代码及逐行注释文档面向想通过具体案例理解经典强化学习算法的初学者。内容以16×1网格世界中的王子寻公主游戏为背景涵盖环境可移动矩阵TT、奖赏矩阵R、折扣因子gamma、epsilon-greedy策略以及贝尔曼方程驱动的Q值更新过程并附带训练循环与最优路径规划逻辑。资源压缩包共1个doc文件大小仅33KB轻量易读适合对照代码边学边调试。目前已有1378人浏览学习适合机器学习入门者用于夯实强化学习核心概念。通过这份资料读者能掌握Q-learning从环境建模、动作定义到策略选择与Q表迭代的完整流程同时理解如何用矩阵运算高效实现强化学习小案例。1. 拿到 Q-Learning 的 MATLAB 源码与注释文档后先别急着复制运行很多人第一次接触 Q-Learning是从课程 PPT 里的三行伪代码开始的初始化 Q 表、按 epsilon-greedy 选动作、用贝尔曼方程更新。可真到了 MATLAB 环境里行列编号怎么映射、动作怎么定义、奖励函数怎么设、绘图验证怎么做每一步都能卡掉一批人。一份带注释的 Q-Learning 源代码文档价值不只是让你少敲一遍键盘而是把状态、动作、奖励、Q 表更新这套抽象概念落成一段能逐行阅读、逐行修改的 MATLAB 代码。适合三类人做强化学习课程作业的学生、要复现基线算法的研究生、以及想快速把网格世界改成自定义场景的从业者。拿到手不要全选复制然后直接运行那样大概率会在报错和翻车之间反复横跳。先把文档当说明书读透后面能省掉一整个晚上的排错时间。2. Q-Learning 的 MATLAB 实现结构拆解主循环、Q 表更新与奖励设计2.1 一份 .doc 里的源码该先读哪三部分主循环、Q 值更新、奖励注释拿到这份文档时不要从头第一行就开始读。老式的 .doc 工程笔记通常有大量排版痕迹逐行读很容易被注释和空行带着走偏。我一般会先搜索三个关键词把代码块的骨架找出来。第一个是主循环。Q-Learning 的标准实现里一定有一个 episode 循环常见写法是for episode 1:maxEpisode或者while ~done里面再套一个单步 while。这个循环是整个代码的骨架所有更新都发生在它内部。第二个是 Q 值更新那一行特征非常明显公式里同时出现alpha、gamma、max(Q(...))三个元素。找到这行你就找到了这份源码的灵魂。第三个是奖励函数可能在主函数里也可能单独抽成一个子函数特征是出现reward 或者r 。很多注释文档喜欢把奖励写在环境函数里如果你只盯着主程序看会漏掉一半信息。读的顺序建议是先看主循环判断代码执行了几回合、什么时候跳出再看 Q 表更新公式确认是标准 Q-Learning 还是 Sarsa 变体最后看奖励函数搞清楚每个状态转移能拿多少分。这三部分读完整份源码的意图基本就清楚了剩下的细节都是在这三个骨架上的填充。2.2 把伪代码翻译成 MATLAB一个 5×5 网格世界的最小可运行骨架如果这份文档里的代码结构比较零散或者你想验证自己的理解是否正确最可靠的做法是自己搭一个最小网格世界。下面这段骨架是我常用的起点它不依赖任何工具箱纯基础 MATLAB 就能跑。状态空间是 5×5 的网格一共 25 个状态编号从 1 到 25动作空间是 4 个方向上、右、下、左。起点在状态 1目标在状态 25其他格子没有陷阱先跑通逻辑再说。% 参数区改参数只动这里 nRows 5; nCols 5; nState nRows * nCols; % 25 个状态 nAction 4; % 动作 1-上 2-右 3-下 4-左 Q zeros(nState, nAction); % Q 表行是状态列是动作 alpha 0.1; % 学习率决定新经验覆盖旧估计的幅度 gamma 0.9; % 折扣因子远期奖励的折现系数 epsilon 0.1; % 探索率每次选择随机动作的概率 maxEpisode 500; % 训练多少轮 maxStep 200; % 每轮最多走多少步防止死循环 episodeSteps zeros(maxEpisode, 1); % 记录每轮步数用于画学习曲线 % 训练主循环 for episode 1:maxEpisode s 1; % 起点状态编号 1 t 0; while t maxStep % 动作选择epsilon-greedy 策略 if rand epsilon a randi(nAction); % 探索随机动作 else [~, a] max(Q(s, :)); % 利用取当前状态 Q 值最大的动作 end % 与环境交互得到下一状态和奖励 [sNext, reward] stepGrid(s, a, nRows, nCols); % Q 值更新时序差分TD更新的标准形式 Q(s, a) Q(s, a) alpha * (reward gamma * max(Q(sNext, :)) - Q(s, a)); s sNext; t t 1; if s nState % 到达终点状态 25 break; end end episodeSteps(episode) t; end % 环境函数状态转移与奖励 function [sNext, reward] stepGrid(s, a, nRows, nCols) row ceil(s / nCols); % 由状态编号反算行号 col mod(s - 1, nCols) 1; % 由状态编号反算列号 switch a case 1, row max(row - 1, 1); % 上不能越界 case 2, col min(col 1, nCols); % 右 case 3, row min(row 1, nRows); % 下 case 4, col max(col - 1, 1); % 左 end sNext (row - 1) * nCols col; % 转回一维编号 if sNext nRows * nCols reward 1; % 到达终点给正奖励 else reward -0.01; % 每走一步的小惩罚促使智能体少绕路 end end这段代码里的核心是Q(s, a) Q(s, a) alpha * (reward gamma * max(Q(sNext, :)) - Q(s, a))。括号里的reward gamma * max(Q(sNext, :))是目标值它由“当前这一步拿到的奖励”和“下一个状态里所有动作的最大 Q 估计”两部分组成这就是贝尔曼最优方程在离散场景下的落地写法。Q(s, a)减去目标值的差叫时序差分误差乘以 alpha 后再加到原值上完成一次更新。参数方面alpha 取 0.1 在 25 个状态的小网格里比较稳健不会因为单步更新太猛导致 Q 表震荡。gamma 取 0.9 表示智能体更看重未来一段时间内的收益而不是只看眼前一步。epsilon 取 0.1 表示每步有 10% 的概率完全随机探索剩下 90% 按当前 Q 表行动。如果把网格改成 8×8 或者加入陷阱建议把 maxStep 提到 300epsilon 初始值提到 0.3否则早期探索不足Q 表的区分度建立不起来。2.3 数据流先于细节动手前用四条流向给注释做索引代码能跑之后再回头看这份文档的注释效率会高很多。我会用四条数据流去给注释做索引而不是按行号顺序读。第一条是状态流。从s 1开始经过sNext转换再在循环末尾s sNext完成状态迁移。注释里凡是解释“状态编号”和“状态转移”的地方都属于这条流。第二条是奖励流。奖励从环境函数的return出来进入 Q 值更新的目标值。观察奖励的取值范围能直接判断这份代码的激励设计是否合理。第三条是 Q 值流。Q 表什么时候初始化、什么时候被读取、什么时候被更新注释里的“更新公式”标记通常就落在这里。第四条是性能流也就是episodeSteps这类记录数组它不参与决策只用于事后画学习曲线。用这四条流去读注释你会发现文档里大部分注释都可以归入其中一个类别。真正需要精读的只有两条奖励流的取值逻辑以及 Q 值流的更新时机。其他注释哪怕写得再多也只是辅助理解不影响你后续改代码。3. 复现一份 Q-Learning 源码前先搭 MATLAB 环境并跑通三条基线3.1 从 .doc 到 .mMATLAB 环境检查与代码提取的四个注意点这份文档的载体是 .doc不是 .m 文件所以第一步是把代码从文档里清洗出来。这里有几个高频坑我基本每次帮人排查都能遇到。第一个坑是格式残留。Word 里复制出来的代码经常带制表符、行号和列表项目符号直接粘进 MATLAB Editor 后编辑器会把这些字符当成无效文本常见的报错是“意外的 MATLAB 运算符”。解决办法先粘到一个纯文本编辑器里把行号、制表符全去掉再粘进 MATLAB Editor。第二个坑是全角引号。中文输入法状态下写的注释里经常混入全角引号MATLAB 解析到这些字符会认为字符串没有正常闭合报错位置往往离真正的错误点很远。用一次全局替换把全角引号换回半角。第三个坑是编码问题。老机器上生成的 .doc 内容可能是 GBK 编码直接复制到新版 MATLAB Editor 里中文注释会乱码。如果你习惯先用 VS Code 清洗文本注意右下角编码选择统一转成 UTF-8 再保存为 .m 文件。第四个坑是文件名。保存成 .m 文件时不要用中文名MATLAB 对函数文件的中文文件名支持不完善容易出现奇怪的行为。文件名最好是QLearningDemo.m这种纯英文。环境检查方面先看一下当前 MATLAB 主版本和工具箱情况命令行里输入ver运行结果会列出版本号和所有已安装工具箱。这份 Q-Learning 源码通常不需要专门装强化学习工具箱只要基础 MATLAB 能运行函数和绘图就行。如果文档里出现了绘制热力图的代码确认有imagesc或heatmap即可这两个函数在基础包和 Statistics Toolbox 里都能用。版本太老的话注意一点2014 年之前的部分绘图参数和字符串处理方式与新版不同语句报错后优先查fprintf格式化串。3.2 三条跑通基线固定随机种子、步数上限、按 episode 记录回报代码清洗完、环境确认没问题之后先别忙着加功能而是跑通三条基线。这三条基线决定你后面调参时看到的现象可不可信。第一条基线是固定随机种子。Q-Learning 的动作选择里有rand每次运行的结果天然不同。如果不固定种子两次运行的学习曲线看起来完全不一样你根本分不清改参数是变好了还是随机波动。我一般会在训练脚本第一行加rng(0)这样每次运行都能复现同一套随机序列。注意不要用rng shuffle那会让种子随机化复现目的达不到。第二条基线是设置步数上限。网格世界里有一种常见情况智能体在两个格子之间反复横跳永远到不了终点。如果没有步数上限这个 episode 会一直跑下去拖死整个训练。maxStep 200在 5×5 网格里是足够宽的上限正常学会走通只需要十几步给到 200 只是用来兜底。第三条基线是按 episode 记录步数或累计奖励。训练结束后画一条episodeSteps随 episode 变化的学习曲线这是判断收敛最直观的依据。rng(0); % 固定随机种子保证实验可复现 maxStep 200; % 步数上限防止单回合死循环 episodeSteps zeros(maxEpisode, 1); for episode 1:maxEpisode s 1; t 0; while t maxStep % 这里填写动作选择、Q 值更新、状态迁移 t t 1; if s nState break; end end episodeSteps(episode) t; % 每 100 轮打印一次进度方便观察训练过程 if mod(episode, 100) 0 fprintf(episode %3d | steps %3d\n, episode, t); end end % 画学习曲线步数从高到低说明在收敛 plot(episodeSteps, LineWidth, 1.2); xlabel(episode); ylabel(steps to goal);这段代码的含义是只要把随机种子固定住那么每次运行episodeSteps曲线的主趋势都应该一致。fprintf那行很值得保留它能在训练进行中直接把步数打出来不用等全部跑完再画图。曲线的粗细和波动能透露很多信息如果曲线尾部是一条平坦的锯齿线说明智能体已经学会走最短路径如果尾部还是一条高值曲线并且锯齿幅度很大说明探索率没有处理好或者奖励设计有问题。3.3 源码注释的四个关键位置参数区、动作选择、Q 值更新、可视化带注释的源码之所以比裸代码值钱是因为注释直接标出了修改点和理解点。我在读这类文档时只关注四个位置其它注释都只是背景板。第一个是参数区。好的工程注释一定会在参数区写明“改这里就能改变智能体行为”比如alpha、gamma、epsilon、maxEpisode、maxStep集中放在一起。看到这种结构调参时只需要锁定这一段。第二个是动作选择区。这里通常有if rand epsilon的分支注释注释会说明探索和利用的关系。想改成纯贪心策略、想改成功 UCB 策略都从这里下手。第三个是 Q 值更新区。这是注释密度最高的地方也是判断源码作者是否真正理解 Q-Learning 的关键。如果注释能清楚写出“目标值 奖励 折扣 × 下一状态最优估计”说明代码可信度较高如果这里没有注释后面排错成本会很高。第四个是可视化区。这对实验验证很重要注释会提示你画的是 Q 表热力图还是学习曲线。读这四个位置时我会顺手做一件事给参数区的注释前加一行日期和目的比如% 2025-06-01: alpha 从 0.1 调到 0.15观察收敛速度。这相当于给自己留后悔药改坏了还能按照记录改回来。不需要用 doxygen 那种重型注释风格Q-Learning 这种规模的小脚本参数区三行、更新区三行、可视化区两行足够后续接手的人快速定位。4. alpha、gamma、epsilon 三个参数决定 Q-Learning 能不能收敛参数表与调参路线4.1 三个超参数各管什么学习率、折扣因子、探索率很多初学者把调参当成玄学本质上是因为没搞清楚每个参数管的是哪一段计算。Q 值更新公式里总共就三个外部参数它们的作用范围非常清晰可以先用一张表把参数和失效表现对应起来。参数典型范围作用位置失效表现alpha 学习率0.05 ~ 0.3Q 值更新公式的乘法系数过大时 Q 表震荡单步奖励主导决策过小时前几百轮几乎看不到学习效果gamma 折扣因子0.8 ~ 0.99目标值中的远期奖励权重过小时只看眼前学成“近视眼”过大时收敛变慢且容易受终端状态处理影响epsilon 探索率0.05 ~ 0.3动作选择分支的随机概率过高时曲线一直降不下来过低且不衰减时早熟后期最优动作被锁死在局部alpha 管的是“新经验覆盖旧估计的速度”。网格世界里单步更新的目标值受当前奖励影响很大alpha 太大时某一次走到陷阱的坏经验会直接把 Q 值打到很低下一次同样状态下另一个动作的优势变得特别明显整体曲线就会剧烈锯齿。gamma 管的是“智能体有没有远见”。gamma 太小比如 0.5 以下智能体更愿意选择眼前回报高但整体路长的动作gamma 接近 1 时所有时间步的奖励权重近乎相同训练会慢但策略更偏向全局最优。epsilon 管的是“探索和利用的平衡”它不是梯度参数不会影响 Q 值计算本身但会强烈影响 Q 表区分度的建立速度。这三个参数在海量开源代码里以alpha 0.1, gamma 0.9, epsilon 0.1的组合最常见但不是因为它理论最优而是因为它在 5×5、10×10 这类小网格里最容易一次跑通。换环境后这三个值一定要重调。4.2 参数失效的三种典型形态与对应调整实际训练里参数失效不是报错而是现象异常。我总结过三种最常出现的形态。形态一是学习曲线全程锯齿且单轮步数在极大值和极小值之间来回跳。这多半是 alpha 偏大导致的。时序差分更新不同于梯度下降它每步都在用单个样本地更新alpha 太大会让当前这步的奖励过度反映到 Q 值里。调试方向把 alpha 从 0.1 降到 0.05观察曲线毛刺是否变小。形态二是学习曲线降到某个平台后就不再下降步数停留在一条水平线上。这通常是 epsilon 高且不衰减导致的。Q-Learning 在训练后期应该逐渐减少探索因为 Q 表已经接近最优再随机走反而拉高平均步数。后文会给出 epsilon 衰减的两种常用写法。形态三是步数最终降下去了但路径明显绕路。比如起点在左上角终点在右下角明明可以走右和下两种动作智能体却先往上绕一圈。原因通常是 gamma 偏小智能体对“未来两步会有奖励”这件事不敏感只惩罚眼前步数于是选择了一条即时步数少但整体更长的路。把 gamma 从 0.9 调整到 0.95 或 0.99 能明显改善。这三种形态对应的是三个独立参数所以调参时可以逐个试不要同时动两个参数否则出问题了根本定位不到原因。4.3 调参路线图先用冒险参数跑通再做 epsilon 衰减与 alpha 微调调参要分阶段走我常用的路线是四步。第一步先把参数设成冒险组合alpha 0.2, gamma 0.9, epsilon 0.3。这个组合学习速度快、探索充分缺点是后期不稳定但它的价值在于让你在最短时间内看到学习曲线“从高到低”的整体趋势。如果冒进参数都跑不出下降趋势问题多半在奖励函数或状态转移代码而不是参数本身。第二步实现 epsilon 衰减。衰减有两种常见做法线性衰减和指数衰减。线性衰减是epsilon max(epsilon - 0.001, 0.05)每个 episode 后执行指数衰减是epsilon max(epsilon * 0.99, 0.05)。指数衰减前期降得快、后期平缓在小网格里更实用。这段代码放在 episode 循环的末尾% 探索率随时间衰减前期多探索后期多利用 epsilon max(epsilon * 0.99, 0.05);第三步固定 gamma 和 epsilon单独扫 alpha。把 alpha 从 0.05 到 0.25 每隔 0.05 设一组每组都固定同一个随机种子跑一遍然后把五条学习曲线画在一张图上。选择那条“中段下降最快、末段波动最小”的曲线对应的 alpha。这个过程看起来像网格搜索但实际上只需要肉眼对比五条曲线就能判断。第四步把每组实验的参数和结论记录到注释头里。这一步看似简单却是以后改代码时最重要的抗遗忘手段。% 实验记录 % 2025-06-01 alpha0.15 gamma0.9 epsilon0.3-0.05 曲线 250 轮收敛到 12 步 % 2025-06-01 alpha0.2 gamma0.9 epsilon0.3 曲线 180 轮后开始锯齿Q-Learning 的调参确实有一点玄学成分那是因为环境随机性和状态转移方式千差万别但有了实验记录玄学就变成了可复现的工程经验。5. 复现这份 Q-Learning 源码的五个避坑记录现象、原因与解决顺序5.1 问题一Q 表初始化后前几百步全是随机动作学习曲线锯齿严重现象是训练刚开始的前 200 轮智能体的行为看上去没有学习迹象步数曲线像是随机游走的噪声。原因是 Q 表初始化为全零时max(Q(s, :))对每个动作的评估值都相同epsilon-greedy的利用分支其实退化成了另一种随机选择等于一直在随机探索。解决方法是不要急着调大 alpha而是先确认探索足够充分把 epsilon 初始值从 0.1 提到 0.3让前 200 轮能覆盖更多动作组合。如果场景比较复杂还可以给 Q 表做微小的非零初始化比如Q 0.01 * rand(nState, nAction)让每个动作在一开始就有一点区分度。但要注意非零初始化幅度要小否则会给 Q 值引入不必要的偏置。5.2 问题二奖励数值跨度过大Q 值更新被单步回报淹没现象是训练能跑完但学习曲线要么剧烈跳动要么看上去“瞬间收敛”。原因是奖励函数给的数值太大了比如终点 100、陷阱 -100。单步走路的惩罚是 -0.01一旦踩中陷阱reward的一项 -100 直接把时序差分误差拉满Q 值更新被单步奖励主导前面积累的估计被彻底覆盖。解决方法是把奖励压缩到小数值区间。刚开始学这个算法时我习惯用终点 1、陷阱 -1、普通步 -0.01 这种设计。这样奖励的绝对数值都在个位数以内单步更新对 Q 表的修改是渐进的曲线平滑很多也更容易观察参数改变带来的实际影响。5.3 问题三随机种子和绘图开销让“收敛判断”失真现象是同一套代码跑两次学习曲线趋势一致但数值不同或者你总觉得“没收敛”。原因是没有固定随机种子每次运行的随机路径天然有差异。另一个隐蔽原因是绘图函数开销过大如果你在训练循环内部调用plot或drawnow做实时可视化训练时间被绘图拖慢而且tic/toc计时会把绘图时间也算进去导致你拿耗时去比较不同算法时结果失真。解决方法是把训练主循环和可视化严格分开训练结束后单独画图。计时对比只针对训练主循环。随机种子固定用rng(0)不要用rng(default)后者在部分版本里只重置到默认状态而非固定数值。5.4 问题四离散状态假设被直接套到连续场景状态不收敛现象是有人把这份网格世界代码直接搬到连续坐标的机器人路径规划里结果状态编号根本算不出来或者训练曲线长时间停滞。原因是 Q-Learning 天然面向离散状态和离散动作连续坐标场景必须先离散化代码里的s和sNext充其量是离散编号不包含连续坐标的语义。解决方法是做栅格化。把连续坐标轴按固定步长切分比如每 0.1 米一格然后把连续坐标映射到最近的栅格编号。栅格越细状态数越多Q 表越大存储和训练时间都会上升。更合理的做法是先粗栅格化跑通逻辑再逐步加密格子看精度是否提升。5.5 问题五版本差异与中文引号让老代码在新版 MATLAB 上报错现象是代码从 .doc 复制出来后在 R2020 之后的版本上报错报错位置在字符串拼接或者显示相关的行。原因有两类一是从文档复制时带入了中文字符集的问题特别是中文全角引号混在字符串里二是老版本代码习惯用strcat拼接字符串新版中对 char 和 string 的混用行为有调整格式化输出也可能出现不一致。解决方法是统一使用fprintf加格式符%d、%s输出不要用strcat做混合拼接检查所有中文字符半角化引号保存 .m 文件时统一用 UTF-8。按这个顺序处理版本差异相关的报错基本都能消除。6. 把源码升级成自己的实验台Q 表热力图验证和三种扩展方向训练跑通之后不要只盯着学习曲线看。学习曲线只是“过程指标”真正能证明智能体学到了什么的是 Q 表本身。我习惯用热力图做验证% 画每个状态的最大 Q 值热力图观察高值区域的分布 figure; imagesc(reshape(max(Q, [], 2), nRows, nCols)); colorbar; title(Max Q-Value per State);这张图能直接看出高 Q 值区域是否集中在终点附近。如果终点周围 Q 值最高起点周围最低说明值函数学得有层次。另一个更实用的验证是把最优动作画成方向箭头[~, a] max(Q, [], 2)拿到每个状态的最优动作后在网格上用quiver画出从状态中心指向动作方向的箭头看到箭头从起点一路指向终点且无环才是真正学对了。基于这份源码做扩展我建议从三个方向入手。第一改成 Sarsa把更新公式里的max(Q(sNext, :))替换成实际执行动作对应的Q(sNext, aNext)对比两种算法在学习速度和策略稳定性上的差别。第二加入随机障碍每次 episode 重新生成陷阱位置观察同一份 Q-Learning 代码在多随机环境下的学习曲线这是评估算法泛化能力最便宜的方式。第三做连续场景栅格化把网格换成二维连续坐标按固定步长离散化奖励里加入路径长度或能耗项这能直接把这份入门代码改造成路径规划实验台。我自己的教训是早期做实验时把终点奖励调到 100学习曲线漂亮得不像话后来画出 Q 表热力图才发现起点附近的最优动作指向陷阱方向因为巨大的单步奖励把整个 Q 表都冲偏了。所以现在每改一次奖励设计我都会强制自己重画一次热力图。这种带注释的源码文档如果按照先读结构、再跑基线、然后调参、最后验证的顺序过一遍基本能把复现失败的概率压到很低。希望帮到你。本文还有配套的精品资源点击获取