5分钟跑通 MO-Gymnasium:从 pip 安装到第一个向量奖励的完整指南
5分钟跑通 MO-Gymnasium:从 pip 安装到第一个向量奖励的完整指南
MO-Gymnasium 是一款开源 Python 多目标强化学习环境库(Multi-objective Gymnasium environments for reinforcement learning)。它遵循标准 Gymnasium API,但 step() 返回的是 numpy 向量奖励,让你能直接研究"效率 vs 速度""收益 vs 风险"这类多目标权衡问题。本指南带你 5 分钟完成 pip 安装并跑通第一个向量奖励。
为什么需要 MO-Gymnasium?
传统 Gymnasium 环境的奖励是标量(一个数),而真实任务往往有多个互相冲突的目标:
- 🐆 HalfCheetah 跑得快(Velocity)vs 省能量(Energy efficiency)
- 🌑 登月着陆器省燃料(Fuel)vs 落点准(Accuracy)
- ⛏️ Minecart 挖到矿(Progress)vs 少撞墙(Crash)
MO-Gymnasium 提供 20+ 个标准多目标环境(含 MORL 文献经典环境与 MuJoCo 多目标版本),让算法对比在统一 API 下进行,方便复现与评测。
第一步:pip 一键安装 MO-Gymnasium
环境要求 Python ≥ 3.11(详见 pyproject.toml)。基础安装只需一条命令:
pip install mo-gymnasium
基础包不含所有环境家族的重依赖(部分依赖在个别系统上安装困难),可按需加装:
# 只装 MuJoCo 系列依赖
pip install "mo-gymnasium[mujoco]"
# 装齐全部环境依赖
pip install "mo-gymnasium[all]"
依赖分组清单可在 pyproject.toml 中查看,官方安装说明见 docs/introduction/install.md。
安装后花 10 秒验证一下:
import mo_gymnasium as mo_gym
print(mo_gym.__version__) # 1.3.2
第二步:认识核心区别——向量奖励 vector_reward
MO-Gymnasium 与 Gymnasium 的 API 几乎一致,唯一关键差异是 step() 返回的奖励是 numpy 数组(源码入口:mo_gymnasium/init.py):
import gymnasium as gym
import mo_gymnasium as mo_gym
import numpy as np
# 创建环境,用法和 Gymnasium 一样
env = mo_gym.make('fishwood-v0')
obs, info = env.reset()
# step 返回 5 元组,reward 是向量而非标量
next_obs, vector_reward, terminated, truncated, info = env.step(0)
print(vector_reward) # 形如 [1. 0.],2 个目标各得一份奖励
以 fishwood-v0 为例 🎣:
小鱼夫只能在钓鱼和砍柴之间切换,两个目标互斥:
| 奖励分量 | 含义 |
|---|---|
| 0 | 拿到木头的概率奖励(woodproba) |
| 1 | 钓到鱼的概率奖励(fishproba) |
环境定义见 mo_gymnasium/envs/fishwood/fishwood.py,其中 reward_space 声明了 2 维奖励,reset() 返回 (obs, info) 元组。
第三步:用 LinearReward 标量化多目标
大多数现有单目标算法只认标量奖励。MO-Gymnasium 内置 LinearReward 包装器,把奖励向量与权重做点积,得到加权标量(实现见 mo_gymnasium/wrappers/wrappers.py):
env = mo_gym.make('minecart-v0')
# 用权重 [0.8, 0.2, 0.2] 标量化 3 个目标
env = mo_gym.wrappers.LinearReward(env, weight=np.array([0.8, 0.2, 0.2]))
💡 改变 weight 即可探索不同权衡点,例如 [1, 0, 0] 只追进度、[0, 1, 1] 更重安全。原向量奖励仍可通过 info["vector_reward"] 取回。
进阶:MOSyncVectorEnv 批量执行多个环境
训练时通常需要并行多个环境。MO-Gymnasium 提供专为向量奖励定制的向量化环境(源码:mo_gymnasium/wrappers/vector/wrappers.py):
from mo_gymnasium.wrappers.vector import MOSyncVectorEnv
envs = MOSyncVectorEnv([
lambda: mo_gym.make("deep-sea-treasure-v0") for _ in range(4)
])
obs, infos = envs.reset()
obs, rewards, terminateds, truncateds, infos = envs.step(envs.action_space.sample())
print(rewards) # shape (4, 2):4 个环境 × 2 个目标的向量奖励
另外,MONormalizeReward 可对指定分量做移动平均归一化,稳定训练(mo_gymnasium/wrappers/wrappers.py)。
常用多目标环境速查
| 环境 ID | 目标维度 | 说明 |
|---|---|---|
fishwood-v0 |
2 | 钓鱼 vs 砍柴入门玩具环境 |
deep-sea-treasure-v0 |
2 | 经典寻宝 vs 深度风险 |
mo-mountaincar-v0 |
2 | 多目标山车(含 3d/timemove 变体) |
mo-mountaincarcontinuous-v0 |
2 | 连续动作版山车 |
mo-halfcheetah-v5 |
2 | MuJoCo 半猫(速度 vs 能耗) |
mo-lunar-lander-v3 |
2 | 登月着陆(省燃料 vs 落点准) |
minecart-v0 |
3 | 挖矿进度 / 撞墙 / 时间 |
更多环境(four-room-v0、water-reservoir-v0、mo-humanoid-v5 等)注册在 mo_gymnasium/envs/init.py,全部环境文档见 docs/environments/classical.md 与 docs/environments/mujoco.md。
下一步:继续深入
- 📓 官方演示 Notebook,从安装到完整训练流程:mo_gymnasium_demo.ipynb
- 📖 API 用法说明:docs/introduction/api.md
- 🧩 包装器文档:docs/wrappers/wrappers.md、docs/wrappers/vector_wrappers.md
- ✅ 环境可用性测试:tests/test_envs.py
- 📝 环境严格版本号管理(
-v0、-v5后缀),保证实验可复现,详见 README.md
至此,从 pip install mo-gymnasium 到拿到第一个 vector_reward,你已经掌握了 MO-Gymnasium 的核心工作流:make → reset → step → 读取向量奖励 → 按需标量化。快去挑一个多目标环境,开始你的 MORL 之旅吧!🚀



