1. 背景说明SMACv2 是基于 StarCraft II 的多智能体强化学习测试环境。它不是一个完整的学习框架而是一个多智能体环境负责提供智能体观测、全局状态、可执行动作、奖励、终止信号和场景随机化机制。SMACv2 官方要求将32x32_flat.SC2Map放入SMAC_Maps地图目录这是 SMACv2 程序化生成场景所依赖的基础地图。(GitHub)EPyMARL 是 PyMARL 的扩展版本支持多种多智能体环境包括 SMAC、SMACv2、SMAClite、PettingZoo 和 VMAS 等。EPyMARL 官方也说明SMAC 和 SMACv2 需要本地 StarCraft II 安装和对应地图文件。(GitHub)本文记录在 Windows 平台上配置StarCraft II SMACv2 EPyMARL PyTorch CUDA QMIX 训练流程并最终成功运行QMIX SMACv2 protoss_5_vs_52. 最终环境概况本次配置平台为 Windows核心组件如下操作系统Windows Conda 环境名epymarl_smacv2 StarCraft II 路径D:\Software\StarCraft II EPyMARL 路径D:\HANXU\MARL\epymarl SMACv2 地图路径D:\Software\StarCraft II\Maps\SMAC_Maps\32x32_flat.SC2Map GPUNVIDIA GeForce RTX 5080已验证的关键结果SMACv2 script 测试通过 EPyMARL 能够启动 sc2v2 环境 StarCraft II 能够被 PySC2 调用 QMIX 能够完成短训练 Sacred 日志捕获问题已绕过最终成功运行日志中包含[DEBUG] pymarl Using capture mode no [INFO] my_main Finished Training [INFO] pymarl Completed after 0:05:09这说明训练链路已经完整跑通。3. 安装前准备3.1 安装 Anaconda本文使用 Conda 管理 Python 环境。安装完成后后续所有命令建议在 Anaconda Prompt 或 Conda Prompt 中执行。3.2 安装 GitEPyMARL、SMACv2 和 SMAClite 都需要从 GitHub 获取源码因此需要安装 Git。可以用 Conda 安装conda install git -y也可以安装 Git for Windows。安装后检查git --version4. 安装 StarCraft IISMACv2 底层依赖 StarCraft II因此需要先安装 StarCraft II。本文中的安装路径为D:\Software\StarCraft II建议设置环境变量SC2PATHsetx SC2PATH D:\Software\StarCraft II设置后关闭当前终端重新打开。检查echo %SC2PATH%期望输出D:\Software\StarCraft II5. 安装 SMACv2 地图SMACv2 需要专用基础地图32x32_flat.SC2Map注意这个文件不是普通 SMAC 地图包中的3m、8m、2s3z等固定任务地图。SMACv2 官方明确要求32x32_flat.SC2Map位于SMAC_Maps文件夹中。(GitHub)最终目录结构应为D:\Software\StarCraft II └── Maps └── SMAC_Maps └── 32x32_flat.SC2Map检查地图是否存在dir D:\Software\StarCraft II\Maps\SMAC_Maps\32x32_flat.SC2Map如果路径正确能够看到该.SC2Map文件。6. 新建 Conda 环境为了避免破坏已有环境建议新建专用环境conda create -n epymarl_smacv2 python3.10 -y conda activate epymarl_smacv2升级基础工具python -m pip install --upgrade pip setuptools wheel7. 安装 PyTorch CUDA本文最终使用的是带 CUDA 的 PyTorch。PyTorch 官方提供 CUDA 12.8 的 pip 安装通道。(PyTorch)根据实际环境可以使用pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128安装完成后验证python -c import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))期望输出类似2.x.xcu128 True NVIDIA GeForce RTX 5080只要torch.cuda.is_available()为True说明 PyTorch 已经可以调用 GPU。8. 安装 SMACv2不要使用pip install smacv2该命令可能出现ERROR: Could not find a version that satisfies the requirement smacv2正确方式是从官方 GitHub 仓库安装pip install githttps://github.com/oxwhirl/smacv2.git安装后验证python -c import smacv2; print(smacv2 import ok)如果能正常输出smacv2 import ok说明 Python 包安装完成。9. 固定关键依赖版本为了减少 PySC2、SMACv2 和 EPyMARL 的兼容性问题建议固定以下依赖pip install numpy1.24.4 protobuf3.20.3 scipy1.10.1验证python -c import numpy, google.protobuf, scipy; print(numpy.__version__); print(google.protobuf.__version__); print(scipy.__version__)期望输出1.24.4 3.20.3 1.10.110. 测试 SMACv2 是否能独立运行可以使用一个简单脚本测试 SMACv2 环境是否能启动。示例脚本from smacv2.env.starcraft2.wrapper import StarCraftCapabilityEnvWrapper env StarCraftCapabilityEnvWrapper( capability_config{ n_units: 5, n_enemies: 5, team_gen: { dist_type: weighted_teams, unit_types: [stalker, zealot, colossus], weights: [0.45, 0.45, 0.10], observe: True, }, start_positions: { dist_type: surrounded_and_reflect, p: 0.5, n_enemies: 5, map_x: 32, map_y: 32, }, }, map_nameprotoss_5_vs_5, debugFalse, ) env.reset() terminated False episode_reward 0 while not terminated: actions [] for agent_id in range(env.n_agents): avail_actions env.get_avail_agent_actions(agent_id) valid_actions [i for i, available in enumerate(avail_actions) if available] actions.append(valid_actions[0]) reward, terminated, info env.step(actions) episode_reward reward print(Episode reward:, episode_reward) print(Info:, info) env.close()运行python C:\Users\hx313\PyCharmMiscProject\script.py如果能够正常结束说明SMACv2 包可用 StarCraft II 可启动 SC2PATH 正确 32x32_flat.SC2Map 地图正确11. 安装 EPyMARL创建项目目录cd /d D:\HANXU mkdir MARL cd /d D:\HANXU\MARL克隆 EPyMARLgit clone https://github.com/uoe-agents/epymarl.git cd epymarl安装依赖pip install -r requirements.txt如果后续提示缺少某些包可以补充安装pip install sacred pyyaml matplotlib pandas tensorboard pygame12. 安装 SMAClite第一次运行 EPyMARL 时可能会出现ModuleNotFoundError: No module named smaclite这是因为 EPyMARL 在环境注册时导入了 SMAClite 相关模块。即使当前运行的是sc2v2也可能需要安装smaclite。处理方式cd /d D:\HANXU\MARL git clone https://github.com/uoe-agents/smaclite.git cd smaclite pip install .验证python -c import smaclite; print(smaclite import ok)然后回到 EPyMARL 目录cd /d D:\HANXU\MARL\epymarl13. 第一次运行 EPyMARL SMACv2官方 EPyMARL 支持sc2v2环境配置可以通过--env-configsc2v2运行 SMACv2。官方示例也使用类似python src/main.py --configqmix --env-configsc2v2 with env_args.map_nameprotoss_5_vs_5这一形式运行 SMACv2 任务。(GitHub)首先运行短训练python src/main.py --configqmix --env-configsc2v2 with env_args.map_nameprotoss_5_vs_5 t_max10000 test_interval2000如果看到类似输出Beginning training for 10000 timesteps Launching SC2 t_env: 2000 / 10000 t_env: 4000 / 10000 Finished Training说明训练流程已经启动并完成。14. 处理 PettingZoo 和 VMAS 警告运行时可能出现PettingZoo is not installed, so these environments will not be available VMAS is not installed, so these environments will not be available这些警告可以忽略。原因是当前运行的是--env-configsc2v2并不是 PettingZoo 或 VMAS 环境。不建议为了消除警告而立即安装pip install pettingzoo pip install vmas[gymnasium]因为这些包可能引入新的依赖变化反而破坏当前已经跑通的 SMACv2 训练环境。15. 处理 PyTorch indexing 警告运行时可能出现Using a non-tuple sequence for multidimensional indexing is deprecated对应文件通常是D:\HANXU\MARL\epymarl\src\components\episode_buffer.py这是因为 EPyMARL 旧代码中存在类似target[k][_slices]新版 PyTorch 会提示未来可能需要改成target[k][tuple(_slices)]当前它只是警告不影响训练。短期可以忽略。后续如果长期使用较新版本 PyTorch可以再统一修改episode_buffer.py中的索引写法。16. 处理 Sacred 日志捕获问题第一次成功训练时终端中可能大量出现--- Logging error ---甚至在训练结束阶段出现OSError: [WinError 1] 函数不正确。这不是训练失败而是 Sacred 的输出捕获模式和 Windows 输出流之间存在兼容问题。Sacred 会捕获程序输出并写入results/sacred默认可能使用capture mode fd在 Windows Conda PySC2 StarCraft II 子进程组合下fd捕获模式容易导致 logging 输出异常。正确做法是在命令前加入--captureno最终命令为python src/main.py --captureno --configqmix --env-configsc2v2 with env_args.map_nameprotoss_5_vs_5 t_max10000 test_interval2000成功后日志中会出现[DEBUG] pymarl Using capture mode no此后训练能够正常完成不再出现大量--- Logging error ---。最终成功日志中出现了Using capture mode no、Finished Training和Completed after 0:05:09。注意不要使用capture_modeno这种写法会被 EPyMARL 识别为实验配置项可能报ConfigAddedError: Added new config entry that is not used anywhere正确写法是--captureno17. 处理 run.py 末尾 print 报错如果仍然出现OSError: [WinError 1] 函数不正确。并且报错位置在D:\HANXU\MARL\epymarl\src\run.py例如print(Exiting Main) print(Stopping all threads) print(Exiting script)可以将退出阶段的print()注释掉。打开D:\HANXU\MARL\epymarl\src\run.py将类似代码print(Stopping all threads) for t in threading.enumerate(): if t.name ! MainThread: print(Thread {} is alive! Is daemon: {}.format(t.name, t.daemon)) t.join(timeout1) print(Thread joined) print(Exiting script)改为# print(Stopping all threads) for t in threading.enumerate(): if t.name ! MainThread: # print(Thread {} is alive! Is daemon: {}.format(t.name, t.daemon)) t.join(timeout1) # print(Thread joined) # print(Exiting script)保留线程清理逻辑只关闭退出阶段的终端输出。不过在已经使用--captureno之后这类问题通常不会再出现。18. 检查实验结果是否保存EPyMARL 使用 Sacred 保存实验记录默认保存路径为D:\HANXU\MARL\epymarl\results\sacred查看目录dir results\sacred会看到数字编号目录例如1 2 3 4进入最新编号dir results\sacred\4通常应包含config.json cout.txt metrics.json run.json这些文件分别记录实验配置、终端输出、训练指标和运行状态。19. 最终推荐运行命令后续所有 SMACv2 训练建议统一使用以下格式cd /d D:\HANXU\MARL\epymarl conda activate epymarl_smacv2 python src/main.py --captureno --configqmix --env-configsc2v2 with env_args.map_nameprotoss_5_vs_5 t_max10000 test_interval2000更长一点的测试python src/main.py --captureno --configqmix --env-configsc2v2 with env_args.map_nameprotoss_5_vs_5 t_max200000 test_interval10000如果要测试 VDNpython src/main.py --captureno --configvdn --env-configsc2v2 with env_args.map_nameprotoss_5_vs_5 t_max200000 test_interval10000如果要测试 IQLpython src/main.py --captureno --configiql --env-configsc2v2 with env_args.map_nameprotoss_5_vs_5 t_max200000 test_interval1000020. 当前已完成的配置检查表检查项状态Conda 环境创建已完成PyTorch CUDA 安装已完成SMACv2 安装已完成StarCraft II 路径识别已完成32x32_flat.SC2Map地图配置已完成SMACv2 独立 script 测试已通过EPyMARL 安装已完成SMAClite 缺失问题已处理QMIX sc2v2 启动已通过Sacredfd捕获日志错误已通过--captureno规避训练结果保存已生成results/sacred记录QMIX 短训练已完成21. 总结本次配置的核心流程是安装 StarCraft II ↓ 配置 SC2PATH ↓ 放置 SMACv2 专用地图 32x32_flat.SC2Map ↓ 创建 epymarl_smacv2 Conda 环境 ↓ 安装 PyTorch CUDA ↓ 从 GitHub 安装 SMACv2 ↓ 安装 EPyMARL ↓ 补充安装 SMAClite ↓ 运行 QMIX sc2v2 ↓ 使用 --captureno 解决 Windows Sacred 日志捕获问题最终成功命令为python src/main.py --captureno --configqmix --env-configsc2v2 with env_args.map_nameprotoss_5_vs_5 t_max10000 test_interval2000当终端出现Using capture mode no Finished Training Completed after ...即可确认Windows 下 SMACv2 EPyMARL PyTorch CUDA 的训练链路已经配置完成。
