使用Ray RLLib 2.50.1实现PPO多智能体时遇KeyError: 'advantages'

常见原因及修复步骤 #

1. 检查Policy Mapping配置 #

确保所有智能体都被正确映射到对应的policy，PPO需要为每个参与训练的agent生成优势数据。如果存在未映射的agent，会导致数据结构缺失advantages字段。

# 正确的policy mapping示例
def policy_mapping_fn(agent_id, episode, **kwargs):
    # 根据agent_id分配policy，确保所有agent都被覆盖
    if agent_id.startswith("player"):
        return "player_policy"
    elif agent_id.startswith("enemy"):
        return "enemy_policy"
    else:
        raise ValueError(f"Unknown agent_id: {agent_id}")

2. 验证环境的观测/动作空间 #

确保每个agent的观测空间是连续或离散的有效空间，且与policy模型的输入匹配。错误的空间定义会导致PPO无法正确采样和计算优势。

# 示例：正确定义多智能体空间
from ray.rllib.env.multi_agent_env import MultiAgentEnv
from gymnasium.spaces import Box, Discrete

class MyMARLEnv(MultiAgentEnv):
    def __init__(self):
        super().__init__()
        # 为每个agent类型定义正确的空间
        self.observation_space = Box(low=-1.0, high=1.0, shape=(10,))
        self.action_space = Discrete(4)

3. 检查PPO训练配置 #

确保开启GAE（广义优势估计），这是PPO计算advantages的核心。如果手动关闭了use_gae，需要手动处理优势计算逻辑，否则会触发KeyError。

# 正确的PPO配置示例
config = (
    PPOConfig()
    .environment(env=MyMARLEnv)
    .framework("torch")
    .multi_agent(
        policies={"player_policy", "enemy_policy"},
        policy_mapping_fn=policy_mapping_fn,
    )
    .training(
        use_gae=True,  # 必须开启，否则PPO不会计算advantages
        gamma=0.99,
        lambda_=0.95,
    )
)

4. 确认自定义模型返回Value输出 #

如果使用了自定义模型，必须确保模型同时返回动作分布和value函数输出。PPO依赖value输出计算优势，缺失的话会导致advantages字段未生成。

# 自定义模型示例（PyTorch）
from ray.rllib.models.torch.torch_modelv2 import TorchModelV2
import torch.nn as nn

class CustomModel(TorchModelV2, nn.Module):
    def __init__(self, obs_space, action_space, num_outputs, model_config, name):
        TorchModelV2.__init__(self, obs_space, action_space, num_outputs, model_config, name)
        nn.Module.__init__(self)
        self.fc = nn.Sequential(
            nn.Linear(obs_space.shape[0], 64),
            nn.ReLU(),
            nn.Linear(64, 64),
            nn.ReLU()
        )
        self.action_layer = nn.Linear(64, num_outputs)
        self.value_layer = nn.Linear(64, 1)  # 必须存在value输出层

    def forward(self, input_dict, state, seq_lens):
        features = self.fc(input_dict["obs"])
        action_logits = self.action_layer(features)
        self._value_out = self.value_layer(features)
        return action_logits, state

    def value_function(self):
        return self._value_out.flatten()  # 必须实现value_function方法

5. 检查数据采样流程 #

如果自定义了采样逻辑，确保每个采样批次包含完整的obs, actions, rewards, dones等字段，PPO需要这些数据来计算优势。避免过滤或修改采样数据导致advantages无法被生成。

内容的提问来源于stack exchange，提问作者geniusadven