多智能体强化学习价值分解算法解析：VDN、QMIX、QTRAN与QPLEX实战对比

简介这份基于Python的多智能体强化学习资源聚焦VDN、QMIX、QTRAN、QPLEX四种经典价值分解算法面向AI课程大作业、期末设计以及多智能体方向初学者的源码与模型文件合集。压缩包共131个文件含36个py算法源码、25个pkl模型文件和29个npy数据文件、18张png训练结果图另附TensorBoard事件、PDF说明与XML配置等整体约9.05MB。目前已有343人学习下载。资源内实现MultiAgentController、SMAC环境封装、ReplayBuffer等关键模块清晰展示了Agent生成、动作选取、经验回放和混合网络训练流程对应模型文件可直接加载查看效果适合对照论文理解算法细节也能作为课程实验或二次开发的脚手架。1. 多智能体强化学习里的 Value Decomposition 家族为什么一个仓库看四套算法在真实的 MARL 项目里团队协作的难点往往不是“单个智能体学不会”而是“每个智能体都学到了自己局部的正确策略合在一起全局却崩了”。VDN、QMIX、QTRAN、QPLEX 这四个算法解决的是同一个问题——如何从全局奖励里拆出每个智能体的贡献同时保证联合动作的选取是最优的。它们不是四种不同用途的工具而是一条从简单到复杂的价值分解进化链VDN 做加法分解QMIX 用单调网络拟合隐式分解QTRAN 放弃单调约束换可分解性QPLEX 用优势函数分解同时保留表达力。这次我基于 Python 把这四套算法在 SMAC星际争霸多智能体挑战环境上完整跑通源码结构和训练好的模型文件都整理好了。这套代码解决的实际问题是你在自己的任务里拿到的是全局奖励但十几个智能体各自该为这个奖励承担多少责任没人告诉你。四个算法分别用不同的数学假设去逼近这个“信用分配”你只要替换一个类就能对比不同分配方式在你环境上的效果。适合正在做多智能体控制、路径规划、或回合制团队对抗任务的工程师也适合刚读完论文但不知道代码怎么组织的研究生。2. 环境与任务建模多智能体强化学习在 SMAC 上的通用数据流2.1 为什么选 SMAC 而不是自建环境SMAC 是 MARL 领域用得最多的验证环境它把《星际争霸2》的战斗场景封装成了 Gym 风格接口每个单位是一个学习智能体每一步能选择 move、attack、stop 等离散动作观测来自单位的相对坐标、血量、护盾、武器冷却等特征。选择它可以省掉自建环境里最贵的部分物理仿真和对手策略。常见做法是用smac_env包加载地图比如 3m三个 marine 打三个 marine和 8m八个打八个。3m 是最小闭环——地图小、单位少算法半小时就能收敛适合调试8m 更接近真实协作场景单位多导致联合动作空间膨胀能明显拉开四个算法的差距。底层用pysc2通信但建议你在导入环境后先跑一个随机策略的 100 步确认游戏客户端能正常启动再进入算法开发。2.2 观测空间与动作空间的统一封装四个算法共用同一套环境接口这样对比实验才有意义。我把环境返回的原始数据做了一层标准化处理统一输出为obs所有智能体的观测拼接、actions所有智能体上一步动作的 one-hot、state全局状态中心化训练时用、reward全局奖励标量、done回合结束标志和avail_actions每个智能体的合法动作掩码。import numpy as np from smac.env import StarCraft2Env def make_env(map_name3m, seed0): env StarCraft2Env(map_namemap_name, seedseed) env_info env.get_env_info() n_agents env_info[n_agents] n_actions env_info[n_actions] state_shape env_info[state_shape] obs_shape env_info[obs_shape] def reset(): obs, state env.reset() avail_actions [] for agent_id in range(n_agents): avail_actions.append(env.get_avail_agent_actions(agent_id)) return obs, state, avail_actions def step(actions): reward, done, _ env.step(actions) obs env.get_obs() state env.get_state() avail_actions [] for agent_id in range(n_agents): avail_actions.append(env.get_avail_agent_actions(agent_id)) return obs, state, reward, done, avail_actions return env, reset, step, env_info, n_agents, n_actions, state_shape, obs_shape2.3 经验回放里必须存哪些字段多智能体经验回放和单智能体有一个关键区别每条经验必须保存当时的全局状态state和每个智能体的合法动作掩码avail_actions。原因在于 QMIX、QTRAN、QPLEX 的损失函数里都要用全局状态做条件输入混合网络要从全局状态里学习分解结构而avail_actions用于在计算目标 Q 值时把非法动作掩掉防止智能体学习到“选择不能执行的动作”。我初始化一个ReplayBuffer类容量默认 5000 条 episode每条存 5 个数组观测序列、动作序列、奖励序列、下一观测序列、终止标志外加 state 和 avail_actions。采样时随机抽取 batch 的 episode 索引再把整段 episode 数据沿时间维展开成 transition 级别这样 RNN 才能按时间步做反向传播。3. VDN 与 QMIX 的实现从加法分解到单调混合网络3.1 VDN 的核心逻辑与代码结构VDN 的假设是整个团队的联合动作价值等于每个智能体单独动作价值的和$Q_{tot} \sum_i Q_i(\tau_i, a_i)$。这个假设极度简化但它奠定了价值分解的框架。实现上只需要一个 DRQN 网络为每个智能体输出局部 Q 值再把所有智能体的 Q 值相加得到联合 Q 值用这个联合 Q 值和全局奖励计算 TD 误差。import torch import torch.nn as nn import torch.nn.functional as F class RNNAgent(nn.Module): def __init__(self, input_shape, n_actions, rnn_hidden_dim64): super().__init__() self.fc1 nn.Linear(input_shape, rnn_hidden_dim) self.rnn nn.GRUCell(rnn_hidden_dim, rnn_hidden_dim) self.fc2 nn.Linear(rnn_hidden_dim, n_actions) def forward(self, obs, hidden_state): x F.relu(self.fc1(obs)) h self.rnn(x, hidden_state) q self.fc2(h) return q, h class VDN(nn.Module): def __init__(self, input_shape, n_actions, n_agents): super().__init__() self.agents RNNAgent(input_shape, n_actions) self.n_agents n_agents def forward(self, obs, hidden_states): # obs: (batch, n_agents, obs_shape) q_values [] next_hidden [] for i in range(self.n_agents): q_i, h_i self.agents(obs[:, i], hidden_states[:, i]) q_values.append(q_i) next_hidden.append(h_i) q_tot sum(q_values) # 直接把局部Q值相加 return q_tot, torch.stack(next_hidden, dim1)VDN 的参数约束非常少训练容易稳定因为加法不会改变 Q 值的量纲。但它有一个致命短板只能表达加法可分解的联合价值。如果两个智能体的协作产生了 112 的效应VDN 无法捕捉因为它没有混合层去建模智能体之间的非线性交互。3.2 QMIX 的混合网络单调性约束与实现细节QMIX 在 VDN 基础上加了一个混合网络用全局状态作为输入学习局部 Q 值和联合 Q 值之间的非线性映射但限制这个映射对每个局部 Q 值的偏导必须非负。这个约束保证了全局最优动作和局部最优动作的一致性——如果每个智能体选了自己 Q 值最大的动作联合起来就是全局最优。这就是允许非线性表达的同时维持可分解性的关键设计。class QMixNet(nn.Module): def __init__(self, n_agents, state_shape, mixing_embed_dim32): super().__init__() self.n_agents n_agents self.mixing_embed_dim mixing_embed_dim # 超网络根据全局状态生成混合网络的权重和偏置 self.hyper_w1 nn.Sequential( nn.Linear(state_shape, mixing_embed_dim), nn.ReLU(), nn.Linear(mixing_embed_dim, n_agents * mixing_embed_dim) ) self.hyper_w2 nn.Sequential( nn.Linear(state_shape, mixing_embed_dim), nn.ReLU(), nn.Linear(mixing_embed_dim, mixing_embed_dim) ) self.hyper_b1 nn.Linear(state_shape, mixing_embed_dim) self.hyper_b2 nn.Sequential( nn.Linear(state_shape, mixing_embed_dim), nn.ReLU(), nn.Linear(mixing_embed_dim, 1) ) def forward(self, q_values, states): # q_values: (batch, n_agents)states: (batch, state_shape) batch_size q_values.size(0) states states.reshape(batch_size, -1) w1 torch.abs(self.hyper_w1(states)).reshape(batch_size, self.n_agents, self.mixing_embed_dim) b1 self.hyper_b1(states).reshape(batch_size, 1, self.mixing_embed_dim) hidden F.elu(torch.bmm(q_values.unsqueeze(1), w1) b1) w2 torch.abs(self.hyper_w2(states)).reshape(batch_size, self.mixing_embed_dim, 1) b2 self.hyper_b2(states).reshape(batch_size, 1, 1) q_tot torch.bmm(hidden, w2) b2 return q_tot.squeeze(1).squeeze(1)3.3 单调性约束的两个必调参数上面代码里最容易踩坑的是torch.abs()强制权重非负。这个操作保证了 $\partial Q_{tot}/\partial Q_i \geq 0$是 QMIX 成立的前提。两个参数直接影响训练质量。第一个是混合网络隐层维度mixing_embed_dim 建议 32 起步地图规模到 8m 以上再调到 64。太小表达力不足QMIX 比 VDN 的优势体现不出来太大容易过拟合到训练地图。第二个是超网络的隐层维度hypernet_embed 论文里写 64 是安全的SMAC 上基本不需要调。如果你在自建环境上发现 QMIX 不收敛先检查w1和w2是不是真的非负——有时候你会为了训练稳定给权重加 L2 正则但 L2 直接作用在超网络输出上会破坏单调性。3.4 QMIX 的完整训练步骤与损失计算def train_qmix(batch, model, target_model, optimizer, gamma0.99): obs batch[obs] # (batch, episode_len, n_agents, obs_shape) actions batch[actions] rewards batch[reward] # (batch, episode_len) states batch[state] avail_actions batch[avail_actions] terminated batch[terminated] batch_size, episode_len, n_agents, _ obs.shape hidden_states torch.zeros(batch_size, n_agents, 64) target_hidden torch.zeros(batch_size, n_agents, 64) q_tot_list [] target_q_tot_list [] for t in range(episode_len): # 当前时刻的局部Q值 q_values, hidden_states model.agents(obs[:, t], hidden_states) # 选择执行动作对应的Q值 action_onehot F.one_hot(actions[:, t], num_classesmodel.n_actions) q_selected (q_values * action_onehot).sum(dim-1) q_tot model.mixing_net(q_selected, states[:, t]) q_tot_list.append(q_tot) # 目标网络计算下一时刻 with torch.no_grad(): target_q, target_hidden target_model.agents(obs[:, t 1] if t 1 episode_len else obs[:, t], target_hidden) target_q[avail_actions[:, t 1] 0] -1e10 # 掩蔽非法动作 target_q_max target_q.max(dim-1).values target_q_tot target_model.mixing_net(target_q_max, states[:, t 1] if t 1 episode_len else states[:, t]) target_q_tot_list.append(target_q_tot) q_tot torch.stack(q_tot_list, dim1) target_q_tot torch.stack(target_q_tot_list, dim1) rewards rewards.unsqueeze(-1) terminated terminated.unsqueeze(-1) targets rewards gamma * (1 - terminated) * target_q_tot td_error q_tot - targets.detach() loss (td_error ** 2).mean() optimizer.zero_grad() loss.backward() grad_norm torch.nn.utils.clip_grad_norm_(model.parameters(), 10) optimizer.step() return loss.item(), grad_norm这段代码有几个细节值得留意。目标网络用的是“当前时刻的下一观测”来估计下一步 Q 值但因为 SMAC 是回合制环境episode 最后一步没有下一观测代码里用t1越界时回退到当前 obs配合 terminated 把最后一步的目标置零避免让最后一步的经验污染训练。avail_actions 0的位置填-1e10而不是-inf因为-inf会通过 max 操作反向传播 NaN。TD 损失用的是 MSE方向是单智能体 DQN 的直接扩展。4. QTRAN 与 QPLEX 的实现打破单调性假设后的新结构4.1 QTRAN 为什么能处理非单调场景QMIX 的单调约束虽然保证了最优动作一致性但也排除了很多真实场景。比如“两个智能体协作搬重物一个人搬不动必须两人同时搬”这种非线性协作的联合 Q 值就不是单调可分解的。QTRAN 的核心思想是放弃对局部 Q 值加限制转而用两个额外的条件把联合 Q 值和局部 Q 值联系起来一个全局约束保证联合最优对应局部最优一个局部约束放松到逐点用 softplus 将偏差转化为损失项。class QTRAN(nn.Module): def __init__(self, input_shape, n_actions, n_agents, state_shape): super().__init__() self.n_agents n_agents self.n_actions n_actions # 局部Q网络每个智能体独立 self.agents RNNAgent(input_shape, n_actions) # 联合Q网络直接输入拼接的局部Q值 self.joint_q nn.Sequential( nn.Linear(n_agents * n_actions, 256), nn.ReLU(), nn.Linear(256, 256), nn.ReLU(), nn.Linear(256, 1) ) # 状态价值网络 self.v nn.Sequential( nn.Linear(state_shape, 256), nn.ReLU(), nn.Linear(256, 256), nn.ReLU(), nn.Linear(256, 1) ) def forward(self, obs, hidden_states, actions_onehot, states): q_values [] for i in range(self.n_agents): q_i, h_i self.agents(obs[:, i], hidden_states[:, i]) q_values.append(q_i) q_actions torch.stack(q_values, dim1) # (batch, n_agents, n_actions) q_selected (q_actions * actions_onehot).sum(dim-1) # (batch, n_agents) # Q_tot: 把局部Q值拼接起来过联合网络 q_concat q_actions.reshape(-1, self.n_agents * self.n_actions) q_tot self.joint_q(q_concat) v_tot self.v(states) return q_actions, q_selected, q_tot, v_totQTRAN 的损失有三个部分最优动作的 TD 差、局部 Q 值与联合 Q 值的一致性损失、以及一个软约束损失。实现 QTRAN 时最容易犯的错误是忘记把局部 Q 值做归一化再拼接到联合网络里因为不同智能体的 Q 值量纲可能差异很大直接拼接会导致联合网络对不同智能体产生偏见。4.2 QPLEX 的优势函数分解实现与 QTRAN 的差异QPLEX 是目前这个家族里表达能力最强的算法它把 QMIX 单调约束的严格形式放到了优势函数上——联合优势函数可以分解为每个智能体优势函数的加权和权重由注意力机制生成。这样做的好处是权重可以为负所以不再强制单调却仍然能保证联合最优与局部最优的一致性。我在 SMAC 上实测QPLEX 在 5m_vs_6m 这种需要丰富战术配合的场景下收敛速度和最终胜率都优于 QTRAN。QPLEX 实现上和 QTRAN 最大的差异是引入了一个 Duplex 网络结构先算每个智能体的局部 Q 值和局部优势值再通过一个注意力混合网络用全局状态计算权重把局部优势值加权组合成联合优势值。联合 Q 值等于联合价值 V(τ) 加上联合优势函数 A而 V(τ) 用类似 QMIX 的混合网络生成。注意力机制是关键——它决定了哪些智能体的优势值对全局贡献更大这是它比 QTRAN 灵活的本质原因。4.3 QTRAN 与 QPLEX 在超参数上的两个差异点QTRAN 的 loss 权重系数需要单独设置论文建议联合 Q 的一致性损失权重 lambda 设为 1.0但我在 8m 地图上发现 0.5 更稳定太大容易让局部 Q 网络失真。QPLEX 则不需要额外调这个权重它天然把分解约束融进了网络结构但需要设置注意力头的数量建议用 4 个头起步。另一个差异是目标网络更新的软硬程度。QTRAN 对目标网络的更新频率比较敏感硬更新每 200 步换一次更稳QPLEX 可以接受软更新tau 取 0.005。我建议你不管跑哪个算法都先在 3m 地图上验证能收敛再去动这些参数。5. 训练脚本与模型文件组织一个仓库管理四种算法的完整工程5.1 项目目录结构与统一训练入口一套好的 MARL 代码库最容易出问题的地方是算法逻辑与训练流程耦合。我把四个算法都实现了“同一个接口”训练脚本只调用model.forward()和model.loss()不关心具体是哪个算法。marl_value_decomposition/ ├── algo/ │ ├── __init__.py │ ├── vdn.py │ ├── qmix.py │ ├── qtran.py │ └── qplex.py ├── envs/ │ ├── __init__.py │ └── smac_wrapper.py ├── runner.py ├── train.py ├── evaluate.py └── config/ ├── vdn.yaml ├── qmix.yaml ├── qtran.yaml └── qplex.yaml5.2 用配置文件切换算法的实现方式import yaml import argparse from algo.vdn import VDN from algo.qmix import QMIX from algo.qtran import QTRAN from algo.qplex import QPLEX ALGO_DICT { vdn: VDN, qmix: QMIX, qtran: QTRAN, qplex: QPLEX, } def load_config(algo_name, config_path): with open(f{config_path}/{algo_name}.yaml, r) as f: config yaml.safe_load(f) return config def build_model(config, env_info): algo_class ALGO_DICT[config[algo]] model algo_class( input_shapeenv_info[obs_shape], n_actionsenv_info[n_actions], n_agentsenv_info[n_agents], state_shapeenv_info[state_shape], rnn_hidden_dimconfig[rnn_hidden_dim], ) return model if __name__ __main__: parser argparse.ArgumentParser() parser.add_argument(--algo, typestr, defaultqmix) parser.add_argument(--config, typestr, defaultconfig) args parser.parse_args() config load_config(args.algo, args.config) env, reset, step, env_info, n_agents, n_actions, state_shape, obs_shape make_env( map_nameconfig[map_name] ) model build_model(config, env_info)5.3 模型文件的保存、加载与断点续训四个算法的模型结构差异很大但保存方式统一用 PyTorch 的 state_dict外加一个元信息字典记录算法名、地图名、当前 epsilon 值和训练步数。这个元信息很关键——断点续训时如果 epsilon 从头开始探索率会在训练中期突然跳高直接打乱学习进度。def save_model(model, optimizer, step, epsilon, algo_name, map_name, save_path): torch.save({ model_state_dict: model.state_dict(), optimizer_state_dict: optimizer.state_dict(), step: step, epsilon: epsilon, algo: algo_name, map: map_name, }, save_path) def load_model(model, optimizer, load_path): checkpoint torch.load(load_path, map_locationcpu) model.load_state_dict(checkpoint[model_state_dict]) if optimizer is not None: optimizer.load_state_dict(checkpoint[optimizer_state_dict]) return checkpoint[step], checkpoint[epsilon]保存时需要检查 GPU 显存占用SMAC 地图到 8m 时一个 batch 的经验数据可能占用 2GB 显存。我一般用 CUDA_VISIBLE_DEVICES 指定单卡混合精度训练四个算法里 QTRAN 最容易 OOM因为它联合 Q 网络会把所有智能体的 Q 值展开成矩阵输入。模型文件按algo_map_step.pt的格式命名每 1000 步存一个检查点、每 5000 步存一个中间最优模型方便后面对比不同训练阶段的策略表现。6. 多智能体强化学习训练中的避坑指南与常见问题排查6.1 环境无法启动SMAC 客户端路径与版本问题现象运行make_env报错Map not found或者SC2Env初始化卡住。原因SMAC 依赖 StarCraft II 客户端环境变量SC2PATH没有指向客户端根目录或者 4.10 版本和某些地图不兼容。解决在启动脚本里显式设置os.environ[SC2PATH] /path/to/StarCraftII同时用pip install smac配套的pysc2版本不要单独更新 pysc2。地图文件放在客户端Maps/SMAC_Maps目录每种地图需要确认文件确实存在。6.2 训练 loss 不降或 NaN全局状态归一化问题现象QMIX 训练 500 步后 loss 停在某个值不动或者直接出现 NaN。原因全局状态state的特征量纲差异太大比如坐标是几十、血量是几百、冷却时间是个位数混合网络的超网络直接把这些数值塞进全连接层大数值特征导致梯度爆炸。解决把state做 min-max 归一化或者单独对每个特征做标准化更简单的做法是加载环境信息时把 state 除以一个固定值缩放让所有特征落在 0 到 1 之间。特别注意 8m 地图里每个单位的血量在训练初期变化剧烈必须用固定统计量不能用 running mean否则非平稳性会破坏混合网络学习。6.3 多智能体强化学习评估时胜率抖动大只看最后几局现象评估阶段胜率在 40% 到 90% 之间剧烈跳动无法判断算法优劣。原因SMAC 的对手策略是固定的但战斗过程随机性很大——单位的初始位置有微小抖动攻击判定有暴击导致单局结果方差极高。解决评估时必须跑够 32 局以上取平均胜率而且要固定评估时的随机种子。我一般每 1000 训练步评估一次每次 32 局记录胜率和平均回报。四个算法对比时所有算法要在完全相同的种子集合下评估否则你看到的差距可能只是随机偏差。已经有模型文件的同学可以直接跑 evaluate.py 做离线评估不需要再训练。6.4 动作掩码忘掉导致训练到非法动作现象训练一个小时后智能体频繁选择“攻击空气”或“移动到地图外”胜率反而比随机策略还低。原因在计算目标 Q 值时没有使用avail_actions掩码智能体学会了选择不可执行动作的高 Q 值而实际执行时环境会忽略或报错。解决务必在目标网络的输出上做掩码处理把非法动作对应的 Q 值置为-1e10注意不要用-inf。另外在计算当前 Q 值的损失时也要用执行动作的 one-hot 向量做点乘这样反向传播只更新实际执行动作的 Q 值否则未执行动作的 Q 值也会被拉低导致策略退化。6.5 学习率与 batch size 的四算法推荐配置VDN 用 0.0005 的学习率、batch size 32 最稳因为它结构简单过大的学习率会导致局部 Q 值震荡。QMIX 推荐 0.001 搭配 batch size 32混合网络的超网络需要足够的数据量来稳定收敛。QTRAN 建议降到 0.0003它的联合 Q 网络和局部 Q 网络同时训练学习率过高直接训练发散。QPLEX 用 0.0005 加 batch size 64注意力机制需要更大的 batch 才能学到稳定的权重分配。四套算法在 3m 地图上收敛步数从 3000 到 8000 不等QTRAN 最慢但表达力确实强于 VDN 和 QMIX。6.6 显存不足的替代方案减小 episode 缓冲长度如果 8m 地图训练时 OOM最常见的是把每个 episode 的缓冲长度从默认 300 步缩短到 150 步。战斗场景一般 200 步内结束超过 300 步属于劣势局截断不会损失有效经验。同时减小 RNN 隐层维度从 64 到 32四个算法的性能损失在 3m 上不超过 5 个胜率点但显存占用能降一半。7. 从单算法跑通到四算法对照我常用的实验管理习惯与验证方法四个算法全部跑通之后真正的价值在于横向比较。我在每个实验目录下自动记录一份 summary.csv内容包含算法名、地图、训练步数、最终胜率、平均回报、模型文件路径和配置文件内容。这个习惯让我复盘时不用翻代码就能知道每个模型文件是哪次实验产生的。具体做法是在训练主循环里每隔 1000 步写一行记录训练结束时把最佳模型路径和超参数一起写进 summary。对比实验必须遵守三个原则相同的随机种子集合、相同的评估局数、相同的经验回放容量。四套算法对经验回放容量的敏感度不同QTRAN 需要更大的回放池才能稳定如果回放池太小它会忘掉早期的经验导致过拟合近期数据。验证阶段除了看胜率还有一个特别有用的指标——智能体的行为多样性。在 8m 地图上我会定时保存每个智能体的动作分布直方图。QMIX 常出现的现象是 8 个智能体全部选择同一个攻击目标这在战术上是错的。这时候即使胜率没崩你也应该检查是不是单调性约束导致所有局部 Q 值同涨同跌失去了差异化分工。遇到这种情况把 reward shaping 加上——对分散攻击不同目标的动作组合给额外小奖励往往能立刻改善行为多样性。我的个人习惯是优先跑 VDN 和 QMIX 做基线确认环境与数据处理没问题后再跑 QTRAN 和 QPLEX。这样就算后两个算法踩坑我也能通过对比基线快速定位是自己代码的问题还是算法本身不收敛。希望这个流程能帮你少走我当初的弯路。本文还有配套的精品资源点击获取