MapTR环境搭建与问题解决全指南

1. MapTR 训练与测试环境搭建全流程解析

作为一名长期从事自动驾驶感知算法开发的工程师，我在本地环境部署MapTR模型时遇到了不少挑战。MapTR作为BEV（Bird's Eye View）多任务感知框架中的佼佼者，其环境配置和运行调试过程颇具代表性。本文将详细记录我从零开始搭建MapTR训练和测试环境的全过程，包括问题定位思路和解决方案。

1.1 基础环境准备

首先需要配置conda环境，这是保证依赖隔离的关键步骤。我使用的是Python 3.8和PyTorch 1.9.0的组合，这个版本经过验证与MapTR兼容性较好：

bash复制conda create -n maptr python=3.8 -y
conda activate maptr
pip install torch==1.9.0+cu111 torchvision==0.10.0+cu111 -f https://download.pytorch.org/whl/torch_stable.html

注意：CUDA版本需要与本地显卡驱动匹配。如果使用较新的显卡（如RTX 30系列），可能需要升级驱动或使用更高版本的PyTorch。

接下来安装MMDetection3D和相关依赖。MapTR基于MMDetection3D框架开发，因此需要先安装基础框架：

bash复制pip install mmcv-full==1.6.0 -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9.0/index.html
pip install mmdet==2.25.0 mmsegmentation==0.25.0
git clone https://github.com/open-mmlab/mmdetection3d.git
cd mmdetection3d
pip install -v -e .

1.2 数据集准备

MapTR主要针对nuScenes数据集进行训练和评估。下载nuScenes数据集后，需要按照特定格式进行预处理：

bash复制python tools/create_data.py nuscenes --root-path ./data/nuscenes --out-dir ./data/nuscenes --extra-tag nuscenes

这个步骤会生成以下关键文件：

• nuscenes_infos_train.pkl
• nuscenes_infos_val.pkl
• nuscenes_map_anns_train.json
• nuscenes_map_anns_val.json

常见问题：如果遇到"KeyError: 'map_ann_file'"，可能是因为map标注文件生成失败。可以手动检查data/nuscenes目录下是否存在map_anns文件。

2. 训练过程中的关键问题与解决方案

2.1 TensorBoard兼容性问题

首次运行训练命令时，遇到了TensorBoard相关的兼容性问题：

bash复制./tools/dist_train.sh ./projects/configs/maptr/maptr_tiny_r50_24e.py 1

错误表现为torch.utils.tensorboard与setuptools/distutils的版本冲突。经过分析，发现这个问题源于TensorBoard不是MapTR的核心依赖，可以安全移除。

解决方案：修改default_runtime.py和maptr_tiny_r50_24e.py中的log配置，移除TensorBoardLoggerHook：

python复制# 修改前
log_config = dict(
    interval=50,
    hooks=[
        dict(type='TextLoggerHook'),
        dict(type='TensorboardLoggerHook')
    ])

# 修改后
log_config = dict(
    interval=50,
    hooks=[
        dict(type='TextLoggerHook')
    ])

这个修改确保了训练可以正常启动，而不会在hooks初始化阶段崩溃。

2.2 数据集注册失败问题

第二个典型问题是CustomNuScenesLocalMapDataset未注册的错误：

code复制KeyError: 'CustomNuScenesLocalMapDataset is not in the dataset registry'

这个问题源于OpenMMLab的Registry机制要求——定义类的模块必须在构建数据集前被导入。仅依赖plugin=True有时导入顺序不稳定。

解决方案：在MapTR配置中添加custom_imports，强制导入dataset模块：

python复制custom_imports = dict(
    imports=['projects.mmdet3d_plugin.datasets.nuscenes_map_dataset'],
    allow_failed_imports=False)

这个修改确保了数据集类在构建前已经正确注册。

2.3 评估阶段崩溃问题

训练过程中，当达到epoch边界进行evaluation时，会出现AttributeError: 'Tensor' object has no attribute 'gravity_center'错误。这是因为MapTR输出的是vector-map结构，而默认评估器期望的是3D box对象。

临时解决方案：禁用训练中的评估功能：

python复制# 修改前
evaluation = dict(interval=2, pipeline=test_pipeline, metric='chamfer')

# 修改后
evaluation = None

同时需要修改训练API，支持evaluation为None的情况：

python复制# 修改前
if validate:
    eval_cfg = cfg.get('evaluation', {})
    ...

# 修改后
if validate and cfg.get('evaluation', None) is not None:
    eval_cfg = cfg.get('evaluation', {})
    ...

这个修改让训练可以完整跑完24个epoch，而不会在评估阶段崩溃。

3. 测试环节的问题修复与优化

3.1 评估路径错误问题

测试时使用以下命令：

bash复制./tools/dist_test_map.sh ./projects/configs/maptr/maptr_tiny_r50_24e.py ./work_dirs/maptr_tiny_r50_24e/latest.pth 1 --eval chamfer

虽然指定了--eval chamfer，但实际执行路径仍会走到nuScenes 3D box的评估逻辑，导致崩溃。

根本解决方案：重写nuscenes_map_dataset.py中的评估逻辑：

1. 修改evaluate()方法默认参数：

python复制def evaluate(self, results, metric='chamfer', ..., result_names=['map_results'], ...):
    # MapTR produces vector-map predictions
    result_files, tmp_dir = self.format_results(results, jsonfile_prefix)

2. 实现_evaluate_map_single()方法处理map-specific评估。

3.2 结果收集问题

多卡测试时，原始代码只收集bbox_results，会丢失MapTR的map输出。

解决方案：修改custom_multi_gpu_test()，增加对map_results的收集：

python复制if 'map_results' in result:
    map_results.append(result['map_results'])

3.3 其他兼容性问题

1. checkpoint警告：修复geometry_kernel_attention.py中的grid_offsets持久化设置：

python复制register_buffer('grid_offsets', ..., persistent=True)

2. Shapely警告：在tpfp_chamfer.py中优化STRtree使用：

python复制if hasattr(tree, 'query_bulk'):
    tree.query_bulk(...)
else:
    tree.query(...)

4. 经验总结与最佳实践

经过这一轮问题修复，我总结了以下几点关键经验：

1. 环境隔离至关重要：使用conda创建独立环境，并严格记录各软件包版本。MapTR对版本敏感，特别是PyTorch和MMCV的兼容性。

2. 分阶段验证：建议按照以下顺序验证：

   • 先确保训练能启动（不要求完整跑完）
   • 然后解决评估阶段问题
   • 最后处理测试环节的细节

3. 日志分析技巧：遇到错误时，重点关注：

   • 错误发生前的最后几条日志
   • 堆栈跟踪中的关键模块和行号
   • 涉及的数据结构和属性访问

4. MapTR特有的注意事项：

   • 确保数据集生成时包含map标注文件
   • 评估指标要明确指定为chamfer或iou
   • 测试时使用dist_test_map.sh而非普通测试脚本

5. 性能优化建议：

   • 训练时可适当降低batch size以避免OOM
   • 测试时启用--eval-options fast_eval=True加速评估
   • 使用--cfg-options model.pretrained=None从头训练

这套解决方案不仅适用于MapTR，对于其他基于MMDetection3D的BEV感知模型也有参考价值。特别是在处理自定义数据集和评估指标时，类似的修改思路可以复用。