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_5

---

2. 最终环境概况

本次配置平台为 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
GPU：NVIDIA 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 安装 Git

EPyMARL、SMACv2 和 SMAClite 都需要从 GitHub 获取源码，因此需要安装 Git。

可以用 Conda 安装：

conda install git -y

也可以安装 Git for Windows。

安装后检查：

git --version

---

4. 安装 StarCraft II

SMACv2 底层依赖 StarCraft II，因此需要先安装 StarCraft II。

本文中的安装路径为：

D:\Software\StarCraft II

建议设置环境变量 SC2PATH：

setx SC2PATH "D:\Software\StarCraft II"

设置后关闭当前终端，重新打开。

检查：

echo %SC2PATH%

期望输出：

D:\Software\StarCraft II

---

5. 安装 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 python=3.10 -y
conda activate epymarl_smacv2

升级基础工具：

python -m pip install --upgrade pip setuptools wheel

---

7. 安装 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.x+cu128
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 git+https://github.com/oxwhirl/smacv2.git

安装后验证：

python -c "import smacv2; print('smacv2 import ok')"

如果能正常输出：

smacv2 import ok

说明 Python 包安装完成。

---

9. 固定关键依赖版本

为了减少 PySC2、SMACv2 和 EPyMARL 的兼容性问题，建议固定以下依赖：

pip install numpy==1.24.4 protobuf==3.20.3 scipy==1.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.1

---

10. 测试 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_name="protoss_5_vs_5",
    debug=False,
)

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

克隆 EPyMARL：

git clone https://github.com/uoe-agents/epymarl.git
cd epymarl

安装依赖：

pip install -r requirements.txt

如果后续提示缺少某些包，可以补充安装：

pip install sacred pyyaml matplotlib pandas tensorboard pygame

---

12. 安装 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\epymarl

---

13. 第一次运行 EPyMARL + SMACv2

官方 EPyMARL 支持 sc2v2 环境配置，可以通过 --env-config=sc2v2 运行 SMACv2。官方示例也使用类似：

python src/main.py --config=qmix --env-config=sc2v2 with env_args.map_name="protoss_5_vs_5"

这一形式运行 SMACv2 任务。(GitHub)

首先运行短训练：

python src/main.py --config=qmix --env-config=sc2v2 with env_args.map_name="protoss_5_vs_5" t_max=10000 test_interval=2000

如果看到类似输出：

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-config=sc2v2

并不是 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 输出异常。

正确做法是在命令前加入：

--capture=no

最终命令为：

python src/main.py --capture=no --config=qmix --env-config=sc2v2 with env_args.map_name="protoss_5_vs_5" t_max=10000 test_interval=2000

成功后日志中会出现：

[DEBUG] pymarl Using capture mode "no"

此后训练能够正常完成，不再出现大量 --- Logging error ---。最终成功日志中出现了 Using capture mode "no"、Finished Training 和 Completed after 0:05:09。

注意，不要使用：

capture_mode="no"

这种写法会被 EPyMARL 识别为实验配置项，可能报：

ConfigAddedError: Added new config entry that is not used anywhere

正确写法是：

--capture=no

---

17. 处理 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(timeout=1)
        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(timeout=1)
        # print("Thread joined")

# print("Exiting script")

保留线程清理逻辑，只关闭退出阶段的终端输出。

不过在已经使用：

--capture=no

之后，这类问题通常不会再出现。

---

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 --capture=no --config=qmix --env-config=sc2v2 with env_args.map_name="protoss_5_vs_5" t_max=10000 test_interval=2000

更长一点的测试：

python src/main.py --capture=no --config=qmix --env-config=sc2v2 with env_args.map_name="protoss_5_vs_5" t_max=200000 test_interval=10000

如果要测试 VDN：

python src/main.py --capture=no --config=vdn --env-config=sc2v2 with env_args.map_name="protoss_5_vs_5" t_max=200000 test_interval=10000

如果要测试 IQL：

python src/main.py --capture=no --config=iql --env-config=sc2v2 with env_args.map_name="protoss_5_vs_5" t_max=200000 test_interval=10000

---

20. 当前已完成的配置检查表

检查项	状态
Conda 环境创建	已完成
PyTorch CUDA 安装	已完成
SMACv2 安装	已完成
StarCraft II 路径识别	已完成
32x32_flat.SC2Map 地图配置	已完成
SMACv2 独立 script 测试	已通过
EPyMARL 安装	已完成
SMAClite 缺失问题	已处理
QMIX + sc2v2 启动	已通过
Sacred fd 捕获日志错误	已通过 --capture=no 规避
训练结果保存	已生成 results/sacred 记录
QMIX 短训练	已完成

---

21. 总结

本次配置的核心流程是：

安装 StarCraft II
        ↓
配置 SC2PATH
        ↓
放置 SMACv2 专用地图 32x32_flat.SC2Map
        ↓
创建 epymarl_smacv2 Conda 环境
        ↓
安装 PyTorch CUDA
        ↓
从 GitHub 安装 SMACv2
        ↓
安装 EPyMARL
        ↓
补充安装 SMAClite
        ↓
运行 QMIX + sc2v2
        ↓
使用 --capture=no 解决 Windows Sacred 日志捕获问题

最终成功命令为：

python src/main.py --capture=no --config=qmix --env-config=sc2v2 with env_args.map_name="protoss_5_vs_5" t_max=10000 test_interval=2000

当终端出现：

Using capture mode "no"
Finished Training
Completed after ...

即可确认 Windows 下 SMACv2 + EPyMARL + PyTorch CUDA 的训练链路已经配置完成。