简介：本资源是一份面向强化学习初学者与MATLAB实践者的DQN算法教学实现，聚焦CartPole经典控制任务，帮助读者从零理解并动手复现深度Q网络的核心机制。压缩包共3个MATLAB源文件（.m），总大小仅4KB，轻量精炼：其中CartPole.m构建物理环境与状态转移逻辑，DQNLearn.m实现含经验回放、目标网络更新与ε-greedy策略的完整训练流程，test.m提供一键运行与性能可视化接口。已有2180人学习下载，说明其在教学适配性与代码可读性上获得广泛认可。读者可直接运行调试，清晰观察Q值收敛过程、小车-杆平衡效果及训练曲线变化；代码结构模块分明、注释充分，省略了复杂工程封装，专注呈现DQN四大关键组件——神经网络Q函数近似、经验回放缓冲区、双网络架构设计与探索-利用权衡逻辑，是掌握强化学习MATLAB落地的优质入门范例。
1. 为什么在 MATLAB 里手撸 DQN 解 CartPole，不是“重复造轮子”，而是看清强化学习黑匣子的第一步
CartPole 是强化学习入门的“Hello World”，但多数人卡在 PyTorch/TensorFlow 的自动微分、经验回放队列、目标网络软更新这些抽象封装里——调通了，却说不清为什么gamma=0.99就比0.95稳，为什么batch_size=64在 MATLAB 里跑着跑着就内存溢出，更别说调试 Q 值震荡时到底哪一层权重在发疯。而用 MATLAB 自主搭建 DQN，不是为了和 Python 比快，而是用它天然的矩阵运算直觉、实时可视化能力和断点调试深度，把 DQN 的每个神经元、每条转移轨迹、每次 target-Q 计算都摊开在眼前。我带过的某高校课程设计小组里，7 个学生中 5 个在 Python 版本上反复调参失败后，转用 MATLAB 从零实现 DQN，3 天内跑通并画出 Q 值收敛曲线；剩下 2 个坚持用现成库的，直到结题前夜还在查RuntimeError: expected scalar type Float but found Double。这不是工具之争，是理解路径之争：当你亲手写完targetQ = r + gamma * max(Q_target(s',a'))这行代码，并在 Workspace 里逐帧观察s'对应的Q_target输出矩阵如何跳变，CartPole 就不再是玩具环境，而是你脑中的动态系统模型。适合正在啃《Reinforcement Learning: An Introduction》第 6 章、被伪代码绕晕，或需要把强化学习模块嵌入已有 MATLAB 工业仿真链路的工程师。
2. 从环境建模到网络定义：MATLAB DQN 四大核心组件的落地选择
DQN 不是“一个函数调用”，而是四个强耦合模块的协同：环境交互接口、经验回放缓冲区、主 Q 网络与目标 Q 网络、以及策略执行逻辑。MATLAB 没有现成的replay_buffer类，但它的结构体数组（struct array）和containers.Map能以极低心智负担实现高效采样；没有torch.no_grad()，但eval模式配合dlfeval可精准控制梯度流。下面拆解每个组件的 MATLAB 原生实现逻辑，不依赖 Deep Learning Toolbox 的高级封装，只用基础语法+深度学习工具箱最小集。
2.1 CartPole 环境的纯 MATLAB 实现：脱离 OpenAI Gym 的轻量级建模
MATLAB 官方 Reinforcement Learning Toolbox 提供rlCartPoleEnv，但它隐藏了状态转移细节。为彻底掌控，我们用物理方程重写：
function [nextState, reward, isDone, info] = cartpole_step(state, action) % state: [x, x_dot, theta, theta_dot] —— 4维列向量 % action: 0 (left) or 1 (right) % 返回 next_state, reward, isDone, info（含角度超限标志） % 物理参数（与OpenAI Gym v0一致） g = 9.8; M = 1.0; m = 0.1; l = 0.5; F = 10; tau = 0.02; % 时间步长 % 动作力：action=0 → -F；action=1 → +F force = (action == 1) * F - (action == 0) * F; % 核心动力学方程（推导自拉格朗日力学，已验证数值稳定性） cos_theta = cos(state(3)); sin_theta = sin(state(3)); temp = (force + m*l*state(4)^2*sin_theta) / (M + m); theta_acc = (g*sin_theta - cos_theta*temp) / (l*(4/3 - m*cos_theta^2/(M+m))); x_acc = temp - m*l*theta_acc*cos_theta/(M+m); % 欧拉积分更新（tau=0.02对应Gym默认dt） nextState = state + tau * [state(2); x_acc; state(4); theta_acc]; % 奖励设计：存活即+1，倒下即0（与Gym一致） reward = 1.0; isDone = false; if abs(nextState(3)) > 12*pi/180 || abs(nextState(1)) > 2.4 isDone = true; reward = 0; end info = struct('theta_limit_exceeded', abs(nextState(3)) > 12*pi/180, ... 'x_limit_exceeded', abs(nextState(1)) > 2.4); end关键说明：
- 此函数完全替代
step()，无需安装任何第三方包；tau=0.02是硬编码时间步，必须与 Gym v0 对齐，否则训练会发散；- 角度单位统一用弧度（MATLAB trig 函数默认），输入
12*pi/180而非12，这是新手最常翻车的点；info结构体用于后续 debug：当训练崩溃时，可快速定位是杆先倒还是车先出轨。
2.2 经验回放缓冲区：用结构体数组实现 O(1) 存储 + 随机采样
Python 用deque+random.sample，MATLAB 用预分配结构体数组 +randperm更直观：
classdef ReplayBuffer properties (SetAccess = private) buffer capacity size pointer end methods function obj = ReplayBuffer(capacity) obj.capacity = capacity; obj.size = 0; obj.pointer = 0; % 预分配结构体数组：避免运行时扩容抖动 obj.buffer(1:capacity) = struct('state', [], 'action', [], 'reward', [], 'next_state', [], 'done', []); end function add(obj, state, action, reward, next_state, done) obj.pointer = mod(obj.pointer, obj.capacity) + 1; obj.buffer(obj.pointer).state = state; obj.buffer(obj.pointer).action = action; obj.buffer(obj.pointer).reward = reward; obj.buffer(obj.pointer).next_state = next_state; obj.buffer(obj.pointer).done = done; if obj.size < obj.capacity obj.size = obj.size + 1; end end function [batch_states, batch_actions, batch_rewards, batch_next_states, batch_dones] = sample(obj, batch_size) if obj.size < batch_size error('Not enough samples in buffer. Current size: %d, requested: %d', obj.size, batch_size); end % 随机索引：用 randperm 而非 randi，避免重复索引（虽概率低但影响收敛） idx = randperm(obj.size, batch_size); batch_states = zeros(4, batch_size); % [x,x_dot,theta,theta_dot] × N batch_actions = zeros(1, batch_size); batch_rewards = zeros(1, batch_size); batch_next_states = zeros(4, batch_size); batch_dones = false(1, batch_size); for i = 1:batch_size b = obj.buffer(idx(i)); batch_states(:,i) = b.state; batch_actions(i) = b.action; batch_rewards(i) = b.reward; batch_next_states(:,i) = b.next_state; batch_dones(i) = b.done; end end end end参数说明：
capacity=10000是经验值：太小（<5000）导致样本相关性高，太大（>50000）显存吃紧（MATLAB 单精度矩阵占优）；sample()中randperm(obj.size, batch_size)比randi([1,obj.size], 1, batch_size)更可靠——后者可能抽到相同索引，造成 batch 内样本重复，Q 值更新方向偏差；- 所有状态向量强制为列向量（
state是 4×1），保证后续dlarray输入维度一致，这是 MATLAB 深度学习链路的隐式契约。
2.3 主网络与目标网络：用 dlnetwork 构建双 Q 网络并同步权重
DQN 的灵魂在于 target network 的延迟更新。MATLAB 用dlnetwork定义网络，再用net = dlnetwork(layers)创建实例，关键在权重同步逻辑：
% 定义共享层结构（输入4维，输出2维动作Q值） layers = [ featureInputLayer(4, 'Normalization','none', 'Name','input') fullyConnectedLayer(128, 'Name','fc1') reluLayer('Name','relu1') fullyConnectedLayer(128, 'Name','fc2') reluLayer('Name','relu2') fullyConnectedLayer(2, 'Name','output') % 2个动作：0(left),1(right) ]; % 创建主网络和目标网络（独立实例！） mainNet = dlnetwork(layers); targetNet = dlnetwork(layers); % 初始化权重：确保两网络初始Q值分布一致（否则early training bias） mainNet = initialize(mainNet); targetNet = initialize(targetNet); % 权重同步函数：每 C 步调用一次 function update_target_network(mainNet, targetNet, tau) % tau=1.0 表示硬更新（常用），tau<1.0 为软更新（较少用） if nargin < 3 || isempty(tau), tau = 1.0; end mainParams = learnableParameters(mainNet); targetParams = learnableParameters(targetNet); for i = 1:length(mainParams) targetParams(i).Value = tau * mainParams(i).Value + (1-tau) * targetParams(i).Value; end targetNet = setLearnableParameters(targetNet, targetParams); end逻辑说明：
dlnetwork是 MATLAB 深度学习工具箱的核心类，比旧版feedforwardnet更适配 DQN 的动态计算图；initialize()必须显式调用，否则dlnetwork权重为零，Q 值全为 0，agent 永远无法区分动作优劣；tau=1.0（硬更新）是 CartPole 场景首选：目标网络每C=10步完全复制主网络权重，简单有效；若用软更新（tau=0.001），需更多迭代才能稳定，不推荐初学者；- 同步操作必须在
dlfeval外进行——dlfeval内部是自动微分上下文，不能修改网络参数。
2.4 ε-贪心策略：MATLAB 中最易调试的动作选择逻辑
Python 用np.random.rand() < eps，MATLAB 用rand < eps，但关键在eps的衰减策略：
function action = select_action(state, net, eps, num_actions) % state: 4x1 列向量；net: dlnetwork；eps: 当前探索率；num_actions=2 if rand < eps action = randi([0, num_actions-1]); % 随机动作：0 or 1 else % 前向推理：注意输入必须是 dlarray 且指定格式 'CB' dlState = dlarray(state, 'CB'); % 'C'=channel, 'B'=batch —— MATLAB 强制要求 qValues = predict(net, dlState); % 输出 2x1 dlarray [~, actionIdx] = max(extractdata(qValues)); % 取最大Q值索引 action = actionIdx - 1; % 转为 0-based end end参数说明：
dlarray(state, 'CB')是硬性要求：MATLABdlnetwork默认按'CB'格式处理输入，'C'是特征维度（4），'B'是 batch 维度（1），错写成'BC'会报错Invalid input format；extractdata()是取出dlarray数值的唯一安全方式，不可直接qValues(1)；eps初始设1.0，线性衰减至0.01，总步数10000：eps = max(0.01, 1.0 - frame_idx/10000*0.99)，此衰减率在 CartPole 上收敛最快。
3. 训练循环与损失计算：MATLAB 特有的梯度管理与数值稳定性技巧
DQN 训练循环看似简单，但在 MATLAB 中需直面三个 Python 用户不会遇到的问题：1）dlgradient的闭包限制；2）dlfeval内部无法修改网络参数；3）mean squared error在dlarray下的维度陷阱。下面给出完整、可粘贴的训练主循环，并逐行解释 MATLAB 特有约束。
3.1 主训练循环：分离前向、反向、参数更新三阶段
% ===== 初始化 ===== env = @(s,a) cartpole_step(s,a); % 环境函数句柄 buffer = ReplayBuffer(10000); mainNet = dlnetwork(layers); targetNet = dlnetwork(layers); mainNet = initialize(mainNet); targetNet = initialize(targetNet); gamma = 0.99; batch_size = 64; C = 10; % target update period total_steps = 0; frame_idx = 0; % ===== 主循环 ===== for episode = 1:500 state = [0; 0; 0; 0]; % reset to upright episode_reward = 0; done = false; while ~done && episode_reward < 200 % max step per episode frame_idx = frame_idx + 1; total_steps = total_steps + 1; % Step 1: 选择动作（ε-greedy） eps = max(0.01, 1.0 - frame_idx/10000*0.99); action = select_action(state, mainNet, eps, 2); % Step 2: 与环境交互 [next_state, reward, done, ~] = env(state, action); episode_reward = episode_reward + reward; % Step 3: 存入缓冲区 buffer.add(state, action, reward, next_state, done); % Step 4: 若缓冲区足够，开始训练 if buffer.size >= batch_size % 采样 batch [b_s, b_a, b_r, b_ns, b_d] = buffer.sample(batch_size); % Step 5: 计算 loss（关键：dlfeval 内部只做前向+梯度，不更新） [loss, gradients] = dlfeval(@compute_loss, mainNet, targetNet, ... b_s, b_a, b_r, b_ns, b_d, gamma); % Step 6: 外部更新主网络权重（dlfeval 外！） mainNet = dlupdate(@sgd_update, mainNet, gradients, ... 'LearnRate', 1e-3); % Step 7: 定期同步目标网络（硬更新） if mod(frame_idx, C) == 0 targetNet = update_target_network(mainNet, targetNet, 1.0); end end state = next_state; end fprintf('Episode %d: Reward = %.1f, Eps = %.3f\n', episode, episode_reward, eps); end关键逻辑说明：
dlfeval(@compute_loss, ...)是 MATLAB 深度学习的唯一正向+反向入口，所有dlgradient必须在此函数内调用；dlupdate()必须在dlfeval外执行，且传入gradients（由dlfeval返回），这是 MATLAB 与 PyTorchoptimizer.step()的根本差异；mod(frame_idx, C) == 0控制目标网络更新频率，C=10是 CartPole 最佳实践：太频繁（C=1）导致 target Q 波动大，太稀疏（C=100）则学习缓慢；episode_reward < 200是终止条件：CartPole 最高奖励为 200，达到即视为 solved。
3.2 损失函数 compute_loss：MATLAB 中最易出错的 dlarray 维度处理
function [loss, gradients] = compute_loss(net, target_net, s, a, r, ns, d, gamma) % s: 4xN, a: 1xN, r: 1xN, ns: 4xN, d: 1xN (logical), gamma: scalar % 返回 loss (scalar) 和 gradients (struct) % Step 1: 主网络前向，提取当前状态Q值 dlS = dlarray(s, 'CB'); % 4xN → 'CB' 格式 q_values = predict(net, dlS); % 输出 2xN dlarray % Step 2: 提取所选动作的Q值：用 a 索引 q_values 的第1维 % MATLAB 索引：q_values(a+1, :) —— 因 a 是 0/1，而索引从1开始 batch_indices = a + 1; % 转为 1-based q_current = gather(q_values(sub2ind([2, size(q_values,2)], batch_indices, 1:size(q_values,2)))); % Step 3: 目标网络前向，计算 max Q'(s',a') dlNS = dlarray(ns, 'CB'); q_target_next = predict(target_net, dlNS); % 2xN % 取每列最大值：max over action dim (dim=1) [~, max_actions] = max(extractdata(q_target_next), [], 1); q_target_max = gather(q_target_next(sub2ind([2, size(q_target_next,2)], max_actions, 1:size(q_target_next,2)))); % Step 4: 构建 target Q = r + gamma * (1-d) * q_target_max % 注意：d 是 logical，需转 double 且广播 target_q = r + gamma * double(~d) .* q_target_max; % Step 5: MSE loss（关键：q_current 和 target_q 必须同尺寸） loss = mean((q_current - target_q).^2); % Step 6: 计算梯度（对 net 的 learnable parameters） gradients = dlgradient(loss, net.Learnables); end血泪经验提示：
sub2ind([2,N], batch_indices, 1:N)是 MATLAB 索引q_values的唯一正确方式：q_values(a+1,:)会报错，因a是向量，MATLAB 不支持向量化逻辑索引；gather()必须调用：dlarray的梯度计算需原始数值，extractdata()只能用于 inference，gather()才返回可参与 loss 计算的double；double(~d)是关键：d是 logical 向量，~d仍是 logical，但乘法需 numeric，漏掉double()会导致gamma * ~d全为 0 或 1，Q 值爆炸；mean(...)计算标量 loss，若用sum()会因 batch_size 变化导致学习率失效。
3.3 优化器更新函数 sgd_update：MATLAB 中的手动梯度下降
function updatedParam = sgd_update(param, gradient, varargin) % param: learnable parameter (dlarray) % gradient: corresponding gradient (dlarray) % varargin: {'LearnRate', lr} p = inputParser; addRequired(p, 'param', @isaDLArray); addRequired(p, 'gradient', @isaDLArray); addParameter(p, 'LearnRate', 1e-3, @isscalar); parse(p, param, gradient, varargin{:}); lr = p.Results.LearnRate; updatedParam = param - lr * gradient; end function tf = isaDLArray(x) tf = isa(x, 'dlarray'); end为什么不用内置 optimizer？
MATLABadamOptimizer等需trainingOptions，与dlfeval流程不兼容；手动 SGD 虽原始，但完全可控——比如可加入梯度裁剪：gradient = min(max(gradient, -1), 1)，这是 CartPole 训练稳定的后悔药。
4. 避坑指南：MATLAB DQN 训练中 4 个真实翻车现场与解法
MATLAB 的报错信息往往晦涩，比如Invalid input format不告诉你哪一行错了。以下是我在某跨平台系统项目中踩过的坑，每一条都附带复现条件、根因和一招解决。
4.1 现象：dlfeval报错 “Invalid input format” —— 根因是dlarray格式写错
- 现象：
predict(net, dlarray(s,'CB'))在dlfeval内报错，但单独运行无问题； - 原因：
s是 4×N 矩阵，但dlarray(s,'CB')要求s是 4×N，而实际s可能是 N×4（因buffer.sample返回batch_states是 4×N，但若你误用transpose就会翻车）； - 解决：在
compute_loss开头加断言assert(size(s,1)==4, 'State must be 4xN')，并打印size(s)；永远用dlarray(s, 'CB')，勿用'BC'。
4.2 现象：Q 值持续为 NaN，训练 10 步后全挂
- 现象：
episode_reward从第 3 轮开始突降为 0，q_values输出NaN； - 原因：
gamma * q_target_max中q_target_max有Inf（因max_actions索引越界，q_target_next为 2×N，但max_actions生成了 3）； - 解决：
[~, max_actions] = max(extractdata(q_target_next), [], 1)后加检查：assert(all(max_actions <= 2), 'max_actions exceed action space')；根源是q_target_next初始化异常，initialize()必须调用。
4.3 现象：训练奖励卡在 20-30 不涨，Q 值震荡剧烈
- 现象：
episode_reward在 25 上下波动，plot(q_values(1,:))显示锯齿状； - 原因：
eps衰减过慢（如frame_idx/50000），导致后期仍高概率随机动作，Q 值无法收敛； - 解决：改用
eps = max(0.01, 1.0 - min(frame_idx,10000)/10000*0.99)，硬截断衰减步数；或改用指数衰减eps = 0.99^frame_idx。
4.4 现象：内存爆满，MATLAB 崩溃退出
- 现象：运行到
frame_idx≈5000时，MATLAB 提示Out of memory； - 原因：
ReplayBuffer中state存为double（8 字节），4×10000×8 = 320KB，但若误存为single未声明，MATLAB 默认double；更致命的是dlarray在dlfeval内未clear中间变量； - 解决：1）
buffer.add(single(state), ...)强制单精度；2）在compute_loss末尾加clear dlS dlNS q_values q_target_next；3）ReplayBuffer容量设为10000而非50000。
提示：所有
assert语句在正式部署时可注释，但调试阶段必须开启——MATLAB 的assert不影响性能，是比try-catch更轻量的防御式编程。
5. 可视化验证与进阶技巧：用 MATLAB 的天然优势锁定收敛证据
训练完成只是开始，MATLAB 的真正价值在于把黑箱变成白盒。下面给出三个不可替代的验证手段：实时 Q 值热力图、策略轨迹动画、以及梯度流可视化。它们不增加训练负担，却能让你一眼看穿 DQN 是否真学到了策略。
5.1 实时 Q 值热力图：监控策略演化过程
CartPole 的状态空间可离散化为网格，绘制(theta, x)平面上两个动作的 Q 值差Q(1)-Q(0)，红色表示倾向右推，蓝色表示左推：
function plot_q_heatmap(net, title_str) theta_grid = linspace(-12*pi/180, 12*pi/180, 50); x_grid = linspace(-2.4, 2.4, 50); [Theta, X] = meshgrid(theta_grid, x_grid); % 构造状态矩阵：4x(N) —— [x; 0; theta; 0]（固定速度为0） S = zeros(4, numel(Theta)); S(1,:) = X(:)'; % x S(3,:) = Theta(:)'; % theta % 预测 Q 值 dlS = dlarray(S, 'CB'); q_vals = predict(net, dlS); % 2xN q_diff = extractdata(q_vals(1,:) - q_vals(2,:)); % Q(right) - Q(left) Q_diff = reshape(q_diff, size(Theta)); figure('Name', title_str); imagesc(theta_grid*180/pi, x_grid, Q_diff); axis xy; colorbar; xlabel('Theta (deg)'); ylabel('X (m)'); title(sprintf('%s: Q(right)-Q(left)', title_str)); end % 在训练循环中每 50 episode 调用一次 if mod(episode, 50) == 0 plot_q_heatmap(mainNet, sprintf('Episode %d', episode)); end为什么这比 reward 曲线更可信？
- reward 可能偶然高（如随机撞上平衡），但 Q 热力图显示：当
theta>0（杆右偏）时Q_diff>0（倾向右推），theta<0时Q_diff<0（倾向左推），才是真正的物理直觉；- 若热力图始终为噪声，说明网络未学到规律，该停训检查
gamma或learning rate。
5.2 策略轨迹动画：用fanimator生成 CartPole 演示视频
MATLAB 的fanimator可导出 GIF，比 Python 的matplotlib.animation更流畅：
function animate_cartpole(net, max_steps) state = [0; 0; 0.05; 0]; % slight perturbation x_history = zeros(1, max_steps); theta_history = zeros(1, max_steps); for t = 1:max_steps x_history(t) = state(1); theta_history(t) = state(3); action = select_action(state, net, 0.01, 2); % greedy [~, ~, ~, state] = cartpole_step(state, action); end % 创建动画 ax = axes; fanim = fanimator(ax, @cartpole_frame, x_history, theta_history); play(fanim); % 导出 GIF（需 Image Processing Toolbox） writeAnimation(fanim, 'cartpole_demo.gif', 'FrameRate', 25); function cartpole_frame(fanim, x, theta, frame_num) % 绘制小车和杆 car_x = x(frame_num); pole_x = car_x + 0.5*sin(theta(frame_num)); pole_y = -0.5*cos(theta(frame_num)); plot([car_x-0.2, car_x+0.2], [0,0], 'k-', 'LineWidth', 3); % car line([car_x, pole_x], [0, pole_y], 'Color', 'r', 'LineWidth', 2); % pole axis([-3 3 -1 1]); axis equal; end end技巧：
fanimator的frame_num自动递增，无需手动for循环drawnow，生成 100 帧 GIF 仅需 2 秒。
5.3 梯度流可视化：用dlgradient的中间结果诊断网络瓶颈
在compute_loss中，dlgradient(loss, net.Learnables)返回各层梯度。我们可统计每层梯度的 L2 范数，判断是否梯度消失：
% 在 compute_loss 末尾添加： grad_norms = struct(); for i = 1:length(gradients) g = gradients(i).Value; grad_norms.(gradients(i).Name) = norm(g, 'fro'); end % 打印：fprintf('Grad norm %s: %.2e\n', fieldnames(grad_norms){i}, grad_norms.(fieldnames(grad_norms){i}));典型模式：
- 若
fc1梯度范数1e-8，而output层为1e-2，说明前层梯度消失，需换leakyReluLayer或增大学习率；- 若所有层梯度范数
>1e2，说明梯度爆炸，立即启用gradient = min(max(gradient,-1),1)裁剪。
我习惯在训练脚本开头加一句addpath('utils/')，把plot_q_heatmap、animate_cartpole、check_gradients封装成工具函数。这样每次新项目，只需run('train_dqn.m')，3 分钟内就能看到热力图从噪声变成清晰的决策边界——那种“啊，它真的懂了”的瞬间，是任何论文指标都给不了的踏实感。希望帮到你。
本文还有配套的精品资源，点击获取
