深入 MO-Gymnasium 源码:向量奖励如何在 Gymnasium API 中被优雅扩展

原创2026-10-13 19:23:381,764 阅读

深入 MO-Gymnasium 源码:向量奖励如何在 Gymnasium API 中被优雅扩展

MO-Gymnasium 是一个开源的 Python 多目标强化学习(MORL)库,它在完全兼容 Gymnasium API 的前提下,把每个环境 step 返回的标量奖励替换成 numpy 向量奖励(vector rewards),让学习算法能同时优化多个相互冲突的目标,例如"跑得更快"和"少耗燃料"。

本文带你在不改动原有 API 五元组的前提下,看懂 MO-Gymnasium 源码里这套扩展是如何被设计出来的:环境如何声明奖励向量、make 工厂函数为什么被重写、LinearReward 包装器如何把向量奖励折叠回标量,以及向量化环境如何处理批量奖励矩阵。

MO-Gymnasium 项目标题图:面向多目标强化学习的 Gymnasium 环境库

1. 背景:标量奖励装不下"多目标"

传统强化学习环境每步只返回一个数(标量奖励)。但真实问题往往有多个目标:省燃料、跑得快、少撞车……把它们硬加成一个数,就丢失了"目标之间如何权衡"的信息。

MO-Gymnasium 的思路很简单:五元组结构 (obs, reward, terminated, truncated, info) 原封不动,只是 reward 从 float 变成 np.ndarray。算法侧拿到的是"每步多个目标的即时得分",想用哪个目标、如何加权,完全交给使用者或包装器决定。

项目内置了 13 个环境家族,全部遵循这一约定,环境清单与注册逻辑见 mo_gymnasium/envs/init.py。

以经典的渔夫问题 FishWood 为例(源码:fishwood.py):智能体只能在"钓鱼"和"砍柴"之间切换,奖励向量恰好是两个分量——钓到的鱼和砍到的柴,互不替代:

FishWood 多目标强化学习环境截图:智能体在钓鱼与砍柴两个目标间权衡

2. 环境端扩展:reward_space 与 reward_dim 两个约定

打开任何一个 MO 环境,__init__ 里都会多出两行"自报家门"的代码,这是理解整个项目的第一把钥匙:

  • reward_space:一个一维的 spaces.Box,描述奖励向量的维度、上下界与 dtype;
  • reward_dim:奖励向量的长度(整数)。

以连续山车环境为例(continuous_mountain_car.py):

self.reward_space = spaces.Box(low=np.array([-1.0, -1.0]), high=np.array([0.0, 0.0]), dtype=np.float32)
self.reward_dim = 2

step 中则把两个目标分别写进向量的两个槽位(第 54-62 行):

reward = np.zeros(2, dtype=np.float32)
if terminated:
    reward[0] = 0.0
else:
    reward[0] = -1.0            # 目标0:时间惩罚
reward[1] = -math.pow(action[0], 2)  # 目标1:燃料消耗
return self.state, reward, terminated, False, {}

不同环境的向量维度可以任意不同,维度只是"目标的数量":

环境 奖励维度 目标含义(摘自环境文档)
mo-mountaincar-v0 2 时间惩罚、移动惩罚
deep-sea-treasure-v0 2 宝藏价值、时间惩罚(源码)
minecart-v0 3 两种矿石收益、燃料消耗(源码)
mo-lunar-lander-v0 4 落点结果、shaping 奖励、主/副发动机燃料(源码)

对经典环境的"MO 化"通常很轻:子类继承原 Gymnasium 环境,只重写奖励逻辑。比如 MuJoco 半猎豹(half_cheetah_v5.py)直接调用 super().step(),再取出 x_velocity 与控制代价,把原来合成好的标量"拆开"成 2 维向量。

MO-Gymnasium 半猎豹多目标强化学习环境演示动图:向量奖励同时覆盖前进速度与能量消耗

3. 入口扩展:make 工厂函数为什么要重写

pip install mo-gymnasium 后,标准用法只多了一行 import:

import gymnasium as gym
import mo_gymnasium as mo_gym

env = mo_gym.make("minecart-v0")
obs, info = env.reset()
next_obs, vector_reward, terminated, truncated, info = env.step(action)  # vector_reward 是 numpy 数组

mo_gym.make 的实现在 mo_gymnasium/utils.py,只有 20 行,但它藏着一个关键细节:

def make(env_name: str, disable_env_checker: bool = True, **kwargs) -> gym.Env:
    """Disable env checker, as it requires the reward to be a scalar."""
    return gym.make(env_name, disable_env_checker=disable_env_checker, **kwargs)

注意签名默认 disable_env_checker=True:Gymnasium 官方的环境校验器 env_checker 会断言"奖励必须是标量",而 MO 环境的奖励天生是向量,所以 MO-Gymnasium 在入口层就默认关掉校验器,否则 make 会直接报错。这也是"优雅"的体现——兼容性问题在工厂函数层面一次性解决,用户无感。

而环境本身的注册走的是 Gymnasium 原生机制:每个环境包的 __init__.py 里调用 register(id=..., entry_point=..., max_episode_steps=...)。例如 mo_gymnasium/envs/minecart/init.py 注册了 minecart-v0,同一环境类还能通过不同 kwargs 注册出多个变体(如 RGB 观测版 minecart-rgb-v0)。注册完成后,mo_gym.make 内部实际还是复用 gym.make 的注册表完成实例化——扩展的是行为,不是体系。

4. 包装器扩展:把向量"用回去"的五种姿势

向量奖励给算法带来的是"自由",但也意味着:如果我的算法只认标量奖励怎么办?MO-Gymnasium 的答案是一组 MO 版包装器,统一从 mo_gymnasium/wrappers/init.py 导出,文档见 docs/wrappers/wrappers.md。

LinearReward:线性标量化,一键回到标量 API

核心包装器 LinearReward(wrappers.py)把奖励向量和一个权重向量做点积,输出标量:

env = mo_gym.wrappers.LinearReward(env, weight=np.array([0.8, 0.2, 0.2]))

它的 step 做了三件事(第 72-77 行):

  1. 向下取回向量奖励,计算 np.dot(reward, self.w) 得到标量返回;
  2. 把原始向量塞进 info["vector_reward"]——信息不丢失,后续仍可做多目标分析;
  3. 把权重快照放进 info["reward_weights"],方便记录日志。

还支持 set_weight 热更新权重,不改环境、不重建包装器,只需一行就能切换偏好方向。

MONormalizeReward 与 MOClipReward:只作用于"某一个"目标

Gymnasium 原生的 NormalizeReward/ClipReward 直接改写标量,搬到向量奖励上必须指定"改第几维"。MO 版通过 idx 参数精确定位(wrappers.py):

norm_env = MONormalizeReward(env, idx=0)   # 只归一化第 0 个奖励分量

值得注意的是配套的内部函数 _check_reward_index(第 17-36 行):它在包装时就用 env.unwrapped.reward_space 校验 idx 是否越界,把错误提前暴露在参数上,而不是让它在后续 step 里从 numpy 深处冒出来。MOClipReward(第 161-197 行)同理,还额外检查了 min_r > max_r 这种会让 np.clip 静默失效的坑。

MORecordEpisodeStatistics:统计量升级为向量

标准 RecordEpisodeStatistics 记录的是标量累计回报;MO 版(第 200-297 行)把 episode_returns 初始化为 np.zeros(self.rewards_shape),每步累加整个向量,并在回合结束时额外提供折扣累计回报 dr(第 252-255 行):

self.disc_episode_returns += rewards * np.repeat(self.gamma**self.episode_lengths, self.reward_dim)

info["episode"] 因此变成 {"r": 向量累计, "dr": 向量折扣累计, "l": 长度, "t": 耗时}——训练曲线可以直接画"帕累托前沿"了。

完整包装器一览:

包装器 作用 位置
LinearReward 加权点积标量化,保留向量于 info wrappers.py
MONormalizeReward 按 idx 归一化单一分量 wrappers.py
MOClipReward 按 idx 裁剪单一分量 wrappers.py
MORecordEpisodeStatistics 回合统计升级为向量 + 折扣回报 wrappers.py
MOMaxAndSkipObservation 帧跳过 + 最大帧合并(Atari 风格) wrappers.py

5. 再上一层:向量化环境的批量奖励矩阵

把多个环境并行跑是 RL 训练的标配,此时奖励不再是 (dim,) 向量,而是 (num_envs, dim) 二维矩阵。MO 版向量化环境放在 mo_gymnasium/wrappers/vector/wrappers.py,同样"继承原生类、只改奖励相关部分":

MOSyncVectorEnv(第 31-118 行)在构造时把内部奖励缓冲区从一维改成两维(第 69-76 行):

self.reward_space = self.envs[0].unwrapped.reward_space
self._rewards = np.zeros((self.num_envs, self.reward_space.shape[0]), dtype=np.float32)

autoreset 时把该行的奖励清零为"目标数量的 0 向量"(第 91 行),其余流程与 Gymnasium 原生实现一致。

MOAsyncVectorEnv(第 252-356 行)更进一步:多进程 worker(_mo_async_worker)里 autoreset 帧同样用 np.zeros(reward_space.shape<a href="https://link.gitcode.com/i/e92f2ae18d305f8c5ac5a3a68c33f99d" target="_blank">0]) 占位([第 156-160 行);主进程的 step_wait 在收集各进程结果后,用 concatenate(self.reward_space, rewards, self.rewards) 把奖励按 space 拼接成 (num_envs, dim) 矩阵(第 343-347 行)。配套的向量版 MORecordEpisodeStatistics(第 359-481 行)则以 (num_envs, reward_dim) 形状管理各子环境的累计与折扣回报。

6. 总结:三处改动,撑起一套 MORL 标准 API

回看全文,MO-Gymnasium 对 Gymnasium API 的扩展可以压缩成一张"改动清单":

层级 扩展点 位置
环境约定 新增 reward_space / reward_dim,step 返回向量 envs/
入口工厂 make 默认关闭标量校验器 utils.py
包装器 LinearReward、MONormalizeReward、MOClipReward、MORecordEpisodeStatistics 等 wrappers.py
向量化 MOSyncVectorEnv / MOAsyncVectorEnv 的批量奖励矩阵 vector/wrappers.py

设计上的几个亮点值得借鉴:

  • 加法式扩展:不改五元组顺序、不新增返回位,只用"约定 + 继承 + 重写局部方法",老代码迁移成本极低;
  • 信息无损:标量化后仍通过 info["vector_reward"] 保留原始向量,随时可以回溯多目标分析;
  • 防御性校验前置:_check_reward_index、gamma/epsilon/skip 等参数在构造时即校验,错误信息直指参数名;
  • 版本严格化:所有环境带 -v0 类后缀,行为变更即升版,保证多目标实验可复现。

上手体验可以看官方演示 Notebook mo_gymnasium_demo.ipynb,环境逐个介绍见 docs/environments/mujoco.md 与 docs/environments/classical.md。理解了这套"向量奖励 + 标准 API"的组合拳,你就可以在任何 MORL 算法中,把 MO-Gymnasium 当作训练基准直接接入了。

登录后查看全文
MO-Gymnasium