MAGAIL4AutoDrive

1.1 环境搭建

环境核心代码封装于Env文件夹，通过运行run_multiagent_env.py即可启动多智能体交互环境，该脚本的核心功能为读取各智能体（车辆）的动作指令，并将其传入env.step()方法中完成仿真执行。

性能优化版本： 针对原始版本FPS低（15帧）和CPU利用率不足的问题，已提供多个优化版本：

• run_multiagent_env_fast.py - 激光雷达优化版（30-60 FPS，2-4倍提升）⭐推荐
• run_multiagent_env_parallel.py - 多进程并行版（300-600 steps/s总吞吐量，充分利用多核CPU）⭐⭐推荐
• 详见 Env/QUICK_START.md 快速使用指南

当前已初步实现Env.senario_env.MultiAgentScenarioEnv.reset()车辆生成函数，具体逻辑如下：首先读取专家数据集中各车辆的初始位姿信息；随后对原始数据进行清洗，剔除车辆 Agent 实例信息，记录核心参数（车辆 ID、初始生成位置、朝向角、生成时间戳、目标终点坐标）；最后调用_spawn_controlled_agents()函数，依据清洗后的参数在指定时间、指定位置生成搭载自动驾驶算法的可控车辆。

✅ 已解决：车辆生成位置偏差问题

• 问题描述：部分车辆生成于草坪、停车场等非车道区域，原因是专家数据记录误差或停车场特殊标注
• 解决方案：实现了_is_position_on_lane()车道区域检测机制和_filter_valid_spawn_positions()过滤函数
  • 检测逻辑：通过point_on_lane()判断位置是否在车道上，支持容差参数（默认3米）处理边界情况
  • 双重检测：优先使用精确检测，失败时使用容差范围检测，确保车道边缘车辆不被误过滤
  • 自动过滤：在reset()时自动过滤非车道区域车辆，并输出过滤统计信息
• 配置参数：
  • filter_offroad_vehicles=True：启用/禁用车道过滤功能
  • lane_tolerance=3.0：车道检测容差（米），可根据场景调整
  • max_controlled_vehicles=10：限制最大车辆数（可选）
• 使用示例：在环境配置中设置上述参数即可自动启用，运行时会显示过滤信息（如"过滤5辆，保留45辆"）

1.2 观测获取

观测信息采集功能通过Env.senario_env.MultiAgentScenarioEnv._get_all_obs()函数实现，该函数支持遍历所有可控车辆并采集多维度观测数据，当前已实现的观测维度包括：车辆实时位置坐标、朝向角、行驶速度、雷达扫描点云（含障碍物与车道线特征）、导航信息（因场景复杂度较低，暂采用目标终点坐标直接作为导航输入）。

✅ 已解决：红绿灯信息采集问题

• 问题描述：
  • 问题1：部分红绿灯状态值为None，导致异常或错误判断
  • 问题2：车道分段设计时，部分区域车辆无法匹配到红绿灯
• 解决方案：实现了_get_traffic_light_state()优化方法，采用多级检测策略
  • 方法1（优先）：从车辆导航模块vehicle.navigation.current_lane获取当前车道，直接查询红绿灯状态（高效，自动处理车道分段）
  • 方法2（兜底）：遍历所有车道，通过point_on_lane()判断车辆位置，查找对应红绿灯（处理导航失败情况）
  • 异常处理：对状态为None的情况返回0（无红绿灯），所有异常均有try-except保护，确保不会中断程序
  • 返回值规范：0=无红绿灯/未知, 1=绿灯, 2=黄灯, 3=红灯
• 优势：双重保障机制，优先用高效方法，失败时自动切换到兜底方案，确保所有场景都能正确获取红绿灯信息

1.3 算法模块

本方案的核心创新点在于对 GAIL 算法的判别器进行改进，使其适配多智能体场景下 “输入长度动态变化”（车辆数量不固定）的特性，实现对整体交互场景的分类判断，进而满足多智能体自动驾驶环境的训练需求。算法核心代码封装于Algorithm.bert.Bert类，具体实现逻辑如下：

1. 输入层处理：输入数据为维度(N, input_dim)的矩阵（其中N为当前场景车辆数量，input_dim为单车辆固定观测维度），初始化Bert类时需设置input_dim，确保输入维度匹配；
2. 嵌入层与位置编码：通过projection线性投影层将单车辆观测维度映射至预设的嵌入维度（embed_dim），随后叠加可学习的位置编码（pos_embed），以捕捉观测序列的时序与空间关联信息；
3. Transformer 特征提取：嵌入后的特征向量输入至多层Transformer网络（层数由num_layers参数控制），完成高阶特征交互与抽象；
4. 分类头设计：提供两种特征聚合与分类方案：若开启CLS模式，在嵌入层前拼接 1 个可学习的CLS标记，最终取CLS标记对应的特征向量输入全连接层完成分类；若关闭CLS模式，则对Transformer输出的所有车辆特征向量进行序列维度均值池化，再将池化后的全局特征输入全连接层。分类器支持可选的Tanh激活函数，以适配不同场景下的输出分布需求。

1.4 动作执行

在当前环境测试阶段，暂沿用腾达的动作执行框架：为每辆可控车辆分配独立的policy模型，将单车辆观测数据输入对应policy得到动作指令后，传入env.step()完成仿真；同时在before_step阶段调用_set_action()函数，将动作指令绑定至车辆实例，最终由 MetaDrive 仿真系统完成物理动力学计算与场景渲染。

后续优化方向为构建 "参数共享式统一模型框架"，具体设计如下：所有车辆共用 1 个policy模型，通过参数共享机制实现模型的全局统一维护。该框架具备三重优势：一是避免多车辆独立模型带来的训练偏差（如不同模型训练程度不一致）；二是解决车辆数量动态变化时的模型管理问题（车辆新增无需额外初始化模型，车辆减少不丢失模型训练信息）；三是支持动作指令的并行计算，可显著提升每一步决策的迭代效率，适配大规模多智能体交互场景的训练需求。

---

问题解决总结

✅ 已完成的优化

1. 车辆生成位置偏差 - 实现车道区域检测和自动过滤，配置参数：filter_offroad_vehicles, lane_tolerance, max_controlled_vehicles
2. 红绿灯信息采集 - 采用双重检测策略（导航模块+遍历兜底），处理None状态和车道分段问题
3. 性能优化 - 提供多个优化版本（fast/parallel），FPS从15提升到30-60，支持多进程充分利用CPU

🧪 测试方法

# 测试车道过滤和红绿灯检测
python Env/test_lane_filter.py

# 运行标准版本（带过滤）
python Env/run_multiagent_env.py

# 运行高性能版本
python Env/run_multiagent_env_fast.py

📝 配置示例

config = {
    # 车道过滤
    "filter_offroad_vehicles": True,  # 启用车道过滤
    "lane_tolerance": 3.0,  # 容差范围（米）
    "max_controlled_vehicles": 10,  # 最大车辆数
    # 其他配置...
}