ApexNav机器人导航框架复现环境搭建指南

1. ApexNav复现环境搭建全流程解析

ApexNav是一个基于视觉语言模型(VLM)的机器人导航框架，复现过程中需要处理多个依赖项的版本冲突问题。下面我将详细拆解完整安装流程，并标注每个环节可能遇到的坑点。

1.1 基础环境准备

首先需要安装系统级依赖库，这一步建议在系统原生环境中执行（非conda虚拟环境）：

bash复制sudo apt update
sudo apt-get install libarmadillo-dev libompl-dev

注意：libompl-dev是OMPL运动规划库的依赖，如果后续出现路径规划相关错误，需要检查这个包是否安装成功

1.2 Conda虚拟环境创建

项目提供了环境配置文件，但实际使用中发现需要额外调整：

bash复制conda env create -f apexnav_environment.yaml -y
conda activate apexnav

常见问题：

1. 如果conda报错找不到yaml文件，检查路径是否正确
2. 创建环境耗时较长（约15-30分钟），建议保持网络稳定

2. 关键组件安装与避坑指南

2.1 PyTorch版本选择

必须严格匹配CUDA版本，否则会导致后续Habitat Simulator报错：

bash复制pip install torch==2.5.0 torchvision==0.20.0 torchaudio==2.5.0 \
--index-url https://download.pytorch.org/whl/cu118

验证命令：

bash复制python -c "import torch; print(torch.cuda.is_available())"

实测发现：如果nvidia-smi显示的CUDA版本≥11.8，上述安装才能正常工作

2.2 视觉语言模型部署

Ollama的安装需要注意代理设置：

bash复制curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen3:8b

测试时如果卡住，可能需要配置镜像源：

bash复制export OLLAMA_HOST=0.0.0.0
ollama run qwen3:8b

2.3 目标检测模型准备

YOLOv7和GroundingDINO需要分别克隆：

bash复制git clone https://github.com/WongKinYiu/yolov7.git
git clone https://github.com/IDEA-Research/GroundingDINO.git

权重文件下载的坑点：

1. mobile_sam.pt可能因网络问题下载失败，可手动下载后放入指定路径
2. yolov7-e6e.pt文件较大（约150MB），建议使用wget的-c参数支持断点续传

3. Habitat模拟器安装特别说明

3.1 版本控制问题

必须严格指定版本号，否则API不兼容：

bash复制git clone https://github.com/facebookresearch/habitat-lab.git
cd habitat-lab; git checkout tags/v0.3.1;
pip install -e habitat-lab
pip install -e habitat-baselines

3.2 Numpy版本冲突

安装后立即执行：

bash复制pip uninstall numpy -y
pip install numpy==1.23.5

血泪教训：如果不降级numpy，会导致habitat_sim导入时报错"ImportError: numpy.core.multiarray failed to import"

4. 编译环境特殊处理方案

4.1 CMake隔离环境

Ubuntu 20.04默认CMake版本(3.16)过低，必须创建独立环境：

bash复制conda create -n cmake324 python=3.9 cmake=3.24 -c conda-forge

关键细节：

1. 必须指定-c conda-forge通道
2. 环境名称不要包含特殊字符
3. 激活环境后执行cmake --version验证

4.2 OSQP路径规划库

编译安装时需要特别注意：

bash复制git clone --recursive https://github.com/osqp/osqp.git
cd osqp/build
cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local

安装后检查：

bash复制sudo ldconfig
ls /usr/local/include/osqp.h  # 确认头文件存在

5. 项目编译与验证测试

5.1 ROS编译指令

在apexnav虚拟环境中执行：

bash复制catkin_make -DPYTHON_EXECUTABLE=/usr/bin/python3

常见错误处理：

1. 如果报Python版本错误，检查which python3路径
2. 缺少ROS包时，用rosdep install解决依赖

5.2 多终端测试流程

七个终端的启动顺序很重要：

1. 先启动视觉服务（端口12181-12184）
2. 再启动RViz可视化
3. 最后运行主算法

性能优化建议：

• 每个终端启动后等待5秒再启动下一个
• 使用tmux或screen管理多窗口

6. 数据集处理技巧

6.1 MP3D数据集获取

需要注册的解决方法：

1. 使用.edu邮箱申请更易通过
2. 下载链接有时效性，建议用wget直接下载
3. 文件较大（约50GB），预留足够磁盘空间

6.2 测试参数调整

评估脚本的实用参数组合：

bash复制# 内存不足时添加
export PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:128

# 单episode测试
python habitat_evaluation.py --dataset hm3dv2 test_epi_num=10 render_resolution="1024x768"

我在实际测试中发现：

• hm3dv1数据集对显存要求较低（约6GB）
• 需要视频输出时设置need_video=true，但会显著降低帧率

7. 典型错误解决方案速查表

最后分享一个实用技巧：在~/.bashrc中添加以下别名可以快速切换环境：

bash复制alias apexnav='conda activate apexnav && source ./devel/setup.bash'
alias cmake324='conda activate cmake324'