Q-Learning Matlab实战：带注释源码与调参避坑指南

简介一份带详细注释的 Q-Learning MATLAB 源代码文档通过“王子寻找公主”的网格游戏演示无模型环境下的强化学习决策过程覆盖从环境建模、奖赏设定到策略评估与路径规划的完整链路适合机器学习初学者和算法课程学生对照代码理解 Q 值迭代思想。资源包为单个 doc 文档大小仅 33KB无需解压多个文件代码中完整定义了可移动矩阵 TT、奖赏矩阵 R、全零 Q 矩阵、折扣因子 gamma 与 epsilon-greedy 策略选择概率并按贝尔曼方程逐步更新 Q 值逐段附有中文注释。文档还演示了训练循环中如何随机化初始状态并避开障碍物每隔 100 次迭代输出训练进度训练结束后可根据 Q 矩阵从任意起点规划到达公主的最优路径。整个案例以趣味游戏承载抽象算法运行或修改奖励值、gamma 等参数即可直观观察学习效果也便于迁移到其他强化学习问题。该资源已有 1378 人学习下载。1. Q-Learning 源代码及注释(matlab).doc一份带注释的文档为什么比代码仓库更值钱做强化学习入门的人十有八九都经历过这个场面GitHub 上找到一个 Q-Learning 仓库代码只有几十行跑起来却一脸懵ε 是干嘛的Q 表为什么要这样更新回合结束的标志在哪全得靠猜。而这几年实验室和课程群里流传的一份「Q-Learning 源代码及注释(matlab).doc」恰恰反着来——它先把原理写在注释里再把代码段嵌在注释中间读起来像一份带运行逻辑的教材。对于想真正搞懂 Q-Learning 而不是只为了交作业的人来说这种老派但完整的注释型文档反而比一堆零散的 .m 文件更实用。我照着这份文档的思路在 Matlab 里重写并跑通了一个走迷宫的例子后面会把完整代码、参数设置和踩过的坑都拆开讲。这份笔记适合三类人一是正在学强化学习、被各种公式劝退的初学者二是要用 Matlab 做课程设计或毕业设计、需要一份能讲清楚的代码基底的同学三是想把 Q-Learning 从「能跑」推进到「会调」的工程师。核心就一件事——把 Q-Learning 的值迭代逻辑在黑匣子里拆开让你看得见每一步在算什么。2. 先看懂更新公式再谈写代码Q-Learning 的 Matlab 实现骨架2.1 Q 表、奖励函数和 Bellman 方程三个名词对应什么数据结构Q-Learning 的整个算法压缩成一句话维护一张「状态-动作」价值表每次交互后用实际得到的奖励和下一状态的最大 Q 值来修正当前估计。这里的关键是它属于离策略off-policy更新即行为策略用来探索的 ε-greedy和目标策略用来更新的 max Q可以是不同的。理解这一点后面的代码才不会写歪。对应的 Matlab 数据结构非常直接Q 表一个二维矩阵行数等于状态数列数等于动作数。如果状态是网格坐标可以把二维坐标压成一维索引Q(s, a) 就是矩阵第 s 行第 a 列。奖励函数不需要单独写函数文件通常用一个 reward_map 矩阵或 switch-case 分支处理命中终点给正奖励撞墙给负奖励普通移动给一个小惩罚。Bellman 更新Q(s,a) Q(s,a) alpha * (r gamma * max(Q(s,:)) - Q(s,a))。注意括号里的顺序r gamma * max 是 TD 目标减去当前 Q 值是 TD 误差乘 alpha 再累加。这个公式是整个算法的唯一心脏。一旦把这三个名词对应到矩阵、标量和一条更新语句上Q-Learning 就从一个算法变成了一个「循环 查表 改表」的程序。很多人卡住不是因为公式难而是没想清楚 Q 表在每一步具体被哪个变量索引了。2.2 为什么 Matlab 写 Q-Learning 比 Python 更顺手矩阵索引语言的优势Q-Learning 的代码量本身很小Python 写也就几十行但 Matlab 有个天然优势——它的矩阵索引和自然数下标让「状态压缩」变得几乎不用动脑。Python 里你可能会纠结用 tuple 做字典键还是自己写一个 encode 函数而 Matlab 里直接 s (row - 1) * cols col 就完事解码同理。另外Matlab 的画图能力让「看 Q 表收敛」这件事变得非常直观。imagesc(Q) 一画一个 episode 结束后刷新一次能看到亮色区域逐渐向终点路径靠拢。用 Python 你得先搭 matplotlib再处理 imshow 和 colorbar 的刷新逻辑。对于学习阶段的人来说省掉的这些琐碎时间都应该花在理解 ε-greedy 和 γ 的互相作用上。不过也要说句公道话Matlab 的 for 循环确实慢如果状态空间超过几万建议改成向量化或直接转 Python NumPy。但本文讨论的走迷宫和格子世界几千状态以内 Matlab 完全够用跑 1000 个 episode 也就是几秒钟的事。2.3 最小可运行的 Q-Learning 主循环代码先跑起来下面这段代码是一个 5x5 网格世界的最简实现起点在左下角(5,1)终点在右上角(1,5)。动作空间是上下左右撞墙不移动并给予 -1 的惩罚。先跑通这个再替换成你自己的场景。%% Q-Learning 最小实现 - 5x5 网格 clear; close all; clc; % 环境参数 rows 5; cols 5; start_state (rows - 1) * cols 1; % 左下角 goal_state 1 * cols 5; % 右上角 % 算法参数 alpha 0.1; % 学习率 gamma 0.9; % 折扣因子 epsilon 0.3; % 初始探索率 min_epsilon 0.01; decay_rate 0.995; % Q表初始化状态数 x 动作数 num_actions 4; % 上、下、左、右 Q zeros(rows * cols, num_actions); % 动作编码1上, 2下, 3左, 4右 % 状态编码s (row-1)*cols col num_episodes 500; reward_per_episode zeros(num_episodes, 1); for episode 1:num_episodes % 每次episode重置到起点 s start_state; % 注意这里不能用 号后面解释 total_reward 0; while true % 1. 选择动作epsilon-greedy if rand() epsilon a randi(num_actions); else [~, a] max(Q(s, :)); end % 2. 执行动作得到下一状态和奖励 [s_next, r] step_environment(s, a, rows, cols, goal_state); % 3. 更新Q值 max_q_next max(Q(s_next, :)); Q(s, a) Q(s, a) alpha * (r gamma * max_q_next - Q(s, a)); % 4. 状态转移 s s_next; total_reward total_reward r; % 5. 终止条件到达终点或步数超限 if s goal_state break; end end % 衰减epsilon epsilon max(min_epsilon, epsilon * decay_rate); reward_per_episode(episode) total_reward; end % 绘制收敛曲线 figure; plot(reward_per_episode); xlabel(Episode); ylabel(Total Reward); title(Q-Learning 训练收敛曲线); % 环境函数根据状态和动作返回下一状态和奖励 function [s_next, r] step_environment(s, a, rows, cols, goal_state) % 解码当前行列 row ceil(s / cols); col mod(s - 1, cols) 1; % 先假设原地不动撞墙情况 s_next s; r -1; % 基础惩罚促使找最短路径 % 根据动作更新坐标 if a 1 row 1 % 上 row row - 1; elseif a 2 row rows % 下 row row 1; elseif a 3 col 1 % 左 col col - 1; elseif a 4 col cols % 右 col col 1; end % 重新编码状态 s_next (row - 1) * cols col; % 到达终点给大奖励 if s_next goal_state r 10; end end这段代码已经可以直接运行。注意step_environment函数被定义在脚本末尾Matlab R2016b 之后都支持这种做法如果你用的是老版本需要把函数单独存成同名 .m 文件。参数说明alpha 设 0.1 是经典兼顾稳定性与收敛速度的值gamma 设 0.9 意味着智能体更看重近期奖励如果加大到 0.99它会更愿意为了远期回报忍受暂时负奖励但在小地图上区分度不大epsilon 初始 0.3、衰减率 0.995在 500 个 episode 后约等于 0.01也就是后期基本纯贪心。reward 里普通步给 -1、终点给 10 是一个很关键的设计——如果不给每步惩罚智能体找到终点后无法区分「最短路径」和「绕路」因为绕路也能在最后拿到 10 分。3. 把「Q-Learning 源代码及注释(matlab).doc」的注释思路还原成工程代码3.1 注释应该写在哪不是写在行尾而是写在决策分支之前这份文档的注释风格有一个明显特点它不为每行代码做行尾注释而是在每个逻辑块前面用一段话解释「这一步在算什么、为什么这样算、出问题时看哪里」。这个习惯非常值得学。行尾注释只适合解释参数含义而前置注释应该回答算法意图。举个例子上面代码中的 epsilon-greedy 分支注释不应该只写「随机选动作」而应该写% epsilon-greedy以epsilon概率随机探索否则选择当前最优动作。 % 注意探索是为了防止Q表陷入局部最优衰减速率决定探索转利用的时机。再看 Q 值更新那一行新手最容易问「为什么 max(Q(s_next,:)) 不用考虑当前动作」因为 Q-Learning 是离策略算法更新时假设下一步会采取最优动作不管你实际下一步会怎么走。这个注释写清楚了比读十篇文章都管用。3.2 模块化拆分环境函数、策略函数、训练主循环分离文档里给的是连续代码但实际工程化时建议拆成三个文件或三个 cell 块。原因是调试体验完全不同——环境换了策略换了主循环不用动主循环要加可视化策略和环境都不用动。这也符合 Matlab 的 cell 模式用 %% 分隔即可。我习惯的拆分方式如下environment.m输入当前状态和动作输出下一状态和奖励。这是唯一需要改的地方换场景就改这个。policy_epsilon_greedy.m输入 Q 表、当前状态、epsilon输出动作。训练时用测试时换成贪婪策略。train_qlearning.m主脚本负责循环、Q 表更新、epsilon 衰减、收敛曲线绘制。这种拆分对课程设计答辩特别重要老师问「环境变了你的代码要改哪里」你直接说「只改 environment.m」比指着一大坨代码解释半天要清爽得多。%% 拆分后的策略函数 function a policy_epsilon_greedy(Q, s, epsilon) % 以epsilon概率随机探索否则取Q值最大的动作 if rand() epsilon a randi(size(Q, 2)); else [~, a] max(Q(s, :)); end end这里的size(Q, 2)是动作数写死的 4 只在初始化时出现一次后续策略、更新逻辑都从 Q 表的形状推断这样换到 6 动作的连续控制任务时整个代码只需要改环境函数和初始化。3.3 训练过程可视化实时看 Q 表怎么长出路径很多人不看 Q 表收敛过程只看最后的总奖励曲线这样其实会漏掉很多信息。总奖励曲线只能告诉你「有没有在变好」但 Q 表热力图能告诉你「策略是不是绕了远路」「有没有在终点周围形成高价值区域」。%% 实时绘制 Q 表热力图在主循环内每 20 个 episode 刷新一次 if mod(episode, 20) 0 subplot(1, 2, 1); imagesc(Q); colorbar; title([Q Table at Episode , num2str(episode)]); subplot(1, 2, 2); % 将Q表转成策略图 [~, policy] max(Q, [], 2); policy_grid reshape(policy, rows, cols); imagesc(policy_grid); title(当前贪心策略); drawnow; enddrawnow是 Matlab 刷新图窗的关键不加的话循环跑完了图才一次性出现。策略图里每个格子显示的是该状态下 Q 值最大的动作编号颜色一致的区域就是智能体学出来的路径走廊。如果出现策略图在终点附近形成「来回震荡」的色块说明 gamma 或 alpha 搭配有问题后面避坑章节会细说。3.4 收敛判断停止条件不应该是「跑完 n 个 episode」文档里给的停止条件可能是固定 episode 数但工程上应该加一个「早停」逻辑连续 M 个 episode 的最优路径长度不再变化就认为收敛。这个逻辑用代码写很简单但能省掉大量无意义的训练时间。%% 早停逻辑记录最近20个episode的最短步数 window_size 20; shortest_steps_in_window min(steps_per_episode(max(1, end-window_size1):end)); if shortest_steps_in_window optimal_steps fprintf(在第 %d 个 episode 收敛\n, episode); break; end这里的optimal_steps需要事先知道走迷宫场景可以直接用迪杰斯特拉算出来如果是任意环境可以先跑一个上限步数比如 200代替。早停不是必须的但养成这个习惯后你会发现换到大状态空间时训练时间从「永远跑不完」变成「可接受」。4. Matlab 里的中文注释与文档编码3 个必踩的坑4.1 中文注释乱码文件编码与 locale 的战争很多人在网上找代码下下来一打开中文注释全变成了乱码。这基本是编码问题——这份 .doc 文档里如果有中文注释转换到 .m 文件时要特别留意。Matlab 在中文 Windows 上默认使用 GBK/GB2312 编码读取 .m 文件而现代编辑器VS Code、Notepad默认写 UTF-8。两者一碰撞注释就是一堆锟斤拷。解决方式有两条用 Matlab 编辑器打开.m文件后如果乱码执行edit命令打开文件然后在「预设项 - 编辑器/调试器 - 语言」里把文件编码切换为 UTF-8再重新打开。更省事的做法在.m文件第一行加上%#encoding utf-8注释强制 Matlab 按 UTF-8 读取。这个技巧在老版本上非常关键。%#encoding utf-8 % 强制使用 UTF-8 编码避免中文注释在中文版 Windows 上乱码注意%#encoding必须放在文件的第一个有效行前面不能有空行或其他代码。如果你的团队协作环境中有人用 Mac 有人用 Windows这个声明几乎能根治所有注释乱码。4.2 函数文件里不能用clear all否则工作区变量被清空这坑特别容易出现在「从脚本改成函数」的过程中。脚本里写clear all没毛病但放进函数后一旦执行会把整个工作区的变量全清掉包括你在主脚本里已经算好的参数。更麻烦的是如果函数内部用了global变量声明clear all还会把这些全局变量也干掉直接导致后续调用静默失败。现象是函数运行没报错但回到主脚本发现所有变量都没了episode 循环还没跑完就出错。原因就是clear的作用域是全局的函数内部调用它也会清空基础工作区。解决函数开头一律不写clear只用clc清屏。如果需要确保函数内局部状态干净在函数入口重新初始化响应的局部变量即可。function [Q, reward_history] train_qlearning(env_params, algo_params) % 不要在这里写 clear all会清空调用者的工作区 % 只初始化本函数需要的局部变量 rows env_params.rows; cols env_params.cols; ... end4.3rand()每次都重新播种导致训练不可复现调试 Q-Learning 时最需要的是可复现性——同一份代码同一个参数跑出来的结果应该一样否则你没法判断改动是变好了还是随机噪声。Matlab 默认每次启动rand的种子不同所以连续两次运行结果不一样。解决方法是训练脚本开头加上rng(42)固定随机数生成器种子。注意用rng(42)而不是老的rand(seed, 42)前者控制的是整个随机数生成器包括randi、randn后者只控制rand。%% 固定随机种子保证实验可复现 rng(42);还有一个容易被忽略的细节如果你的环境函数内部也用了randi比如随机初始化格子位置那么种子固定后环境初始化的随机性也被固定了这可能导致「训练结果好是因为环境恰好简单」的错觉。严谨的实验应该固定三次不同的种子跑三遍取平均而不是单次结果。4.4 在.doc文档里的代码复制到.m文件后的隐形换行符问题从 Word 或 WPS 的.doc里复制代码到 Matlab 编辑器经常出现「整段代码粘在一起」或「执行时报错Invalid text character」。原因是 Word 里的换行符是软回车\r而 Matlab 要的是 Unix 换行\n。肉眼看不出来但一运行就报错。解决做法复制前先把文档里的代码粘贴到 Notepad 或 VS Code 里右下角把行尾序列切换成 LF全选复制回 Matlab。或者更彻底一点直接手动把整个函数重新敲一遍——写代码的过程本身也可以帮你理解文档里的逻辑也算因祸得福。5. Q-Learning 调参避坑指南从「能跑」到「跑得好」的 4 个实战记录5.1 学习率 alpha 设太大会震荡不收敛现象训练曲线上总奖励在 -800 到 100 之间大幅震荡1000 个 episode 后依然没有收窄趋势。Q 表热力图看路径区域忽亮忽暗高价值区域无法稳定。原因alpha 0.9 时每次新样本对 Q 值的修正幅度太大TD 误差的随机性被直接放大。尤其在奖励稀疏的环境里只在终点给正奖励前期大部分样本的 r 都是负的大 alpha 会让 Q 表在负值和偶尔的正值之间剧烈摇摆。解决把 alpha 降到 0.1 到 0.2 之间。如果状态空间很大可以进一步用递减 alpha 方案前期快学习后期微调。实现如下alpha_t alpha / (1 episode / 100); Q(s, a) Q(s, a) alpha_t * (r gamma * max_q_next - Q(s, a));注意递减 alpha 要谨慎使用——它本质上是牺牲后期的学习能力来换取稳定性。如果你准备在训练后半段更换环境参数比如加入动态障碍物递减 alpha 会让智能体学不动新变化。5.2 gamma 设成 1.0 导致策略变成「无限绕路」现象智能体到了终点附近却开始绕圈总步数持续居高不下Q 表在终点邻域的状态中朝远离终点的动作也有很高 Q 值。原因gamma 1.0 意味着未来奖励不打折智能体认为「绕 10 步再到达终点」和「直接到达终点」价值完全一样——因为反正最终都能拿到 10 分。每步惩罚如果是 0它就没有动力走最短路径。这个问题在 gamma 接近 1、步惩罚为 0 时非常隐蔽。解决两个办法任选。一是把 gamma 降到 0.9 到 0.95让远期奖励有一定折扣二是不改 gamma但把每步的奖励改成 -0.1 或 -1人为惩罚路径长度。这两个本质上是同一个效果——让「早到达」变得更有价值。推荐第二种因为 gamma 还影响 TD 目标的方差太低的 gamma 会让算法过于短视。5.3 epsilon 衰减太快导致探索不足、学出一个残缺路径现象训练早期前 100 个 episodeQ 表有进展但 200 个 episode 后策略固定为一条「绕远路」无论怎么增加 episode 数都不改变。从热力图看未探索区域的 Q 值始终为 0。原因epsilon 从 0.5 按 0.9 的衰减率下降到第 20 个 episode 就剩 0.03基本全是贪心决策。这条被固定的路径一旦是次优的后面的学习完全无法发现更短的路径——因为永远没有动作去尝试新的方向。解决把衰减率从 0.9 改成 0.995 或 0.999让探索期拉长到 300-500 个 episode。更好的做法是基于「连续多少个 episode 路径长度无改善」来动态降 epsilon if mod(episode, 10) 0 mean(steps_recent) best_mean_steps epsilon max(min_epsilon, epsilon * 0.9); end这个方案的好处是训练前期如果进展快epsilon 降得快如果卡住了epsilon 维持在较高水平保证持续探索。5.4 奖励函数正负比例失衡导致「出发即终点」的偷懒行为现象智能体学到的策略是「第一步就撞墙拿 -1」因为每次撞墙后的状态不变Q(s, 撞墙) 逐渐收敛到一个不那么差的固定值而探索其他方向的风险不定。Q 表里某些边缘状态的撞墙动作 Q 值甚至高于移动动作。原因奖励设置里普通移动 -0.1撞墙 -0.1终点 10。看似合理但撞墙有一个隐蔽优势——状态不变所以你不需要承担后续不确定性。在状态不变的情况下Q 值会快速收敛到一个确定值而移动到新区域需要长期探索才见效益。理论上 gamma 大于 0 时这不是最优但前期探索不足时这个短期确定收益会被过高估计。解决给撞墙更重的惩罚比如 -2或者撞墙时直接结束回合terminal state。后者在机器人路径规划里更常见但迷宫场景里会释放太多负奖励样本。更推荐的做法是把终点正奖励提高到 50普通步惩罚降到 -0.05拉大比值。经验法则正奖励绝对值 / 每步惩罚绝对值至少应该在 50:1 以上。6. 进阶技巧用 Sarsa 对比验证你的 Q-Learning 实现是否正确验证 Q-Learning 代码写没写对不需要看论文也不需要调一堆指标。最可靠的方法是把 Q-Learning 换成 Sarsa用同一套环境、同一套参数跑对比两条收敛曲线的形态差异。Sarsa 是 Q-Learning 的「同策略版本」更新公式只差一处% Q-Learning离策略 Q(s, a) Q(s, a) alpha * (r gamma * max(Q(s_next, :)) - Q(s, a)); % Sarsa同策略 a_next policy_epsilon_greedy(Q, s_next, epsilon); % 先选下一步动作 Q(s, a) Q(s, a) alpha * (r gamma * Q(s_next, a_next) - Q(s, a));差别就在更新时用的「下一状态的价值」——Q-Learning 用的是下一状态所有动作里的最大值Sarsa 用的是下一状态按当前策略含探索实际会执行的动作值。在 epsilon 大于零时Sarsa 的更新更保守因为它把探索的随机性也计入价值估计。表现为Sarsa 的收敛曲线更平滑但最终总奖励略低Q-Learning 前期波动大但最终找到更优路径。如果你跑出来的两条曲线没有上述分化或者 Q-Learning 反而比 Sarsa 收敛更快更平滑那大概率是代码里max(Q(s_next, :))写成了Q(s_next, a)——也就是你把离策略写成了同策略。还有一个验证技巧训练结束后把 epsilon 设为 0用纯贪心策略从起点走一遍打印每一步的状态和动作。肉眼检查这条轨迹是不是合理解——不该穿墙、不该回头、不该在某个状态原地踏步。这一步能发现 Q 表数值上的细微错误尤其是状态编码和解码函数写反的情况。最后说一个我在工程里养成的习惯每次改完参数先跑一个 100-episode 的快速实验记录 Q 表的 L2 范数和最短路径步数再和上一次实验对比。这两个数字比总奖励曲线更能敏感地反映改动方向对错。如果你也想把 Q-Learning 往深度方向走把 Q 表换成神经网络的 DQN 也是从这份代码基底上改出去的——Q 表查表变成网络前向计算更新公式的 TD 目标部分完全不变。希望帮到你。本文还有配套的精品资源点击获取