Azure ML环境中安装GitHub detectron2包的正确方法及问题排查

Detectron2的安装对PyTorch、CUDA版本有严格依赖，直接通过简单的pip install git+链接或修改Dockerfile很容易因为依赖不匹配、缺失系统依赖导致安装不完整，出现ModuleNotFoundError。以下是正确的实现方式和你可能踩的坑：

方法一：自定义Dockerfile构建环境（推荐） #

Dockerfile能精准控制依赖版本，避免编译失败：

1. 选对基础镜像：使用Azure ML官方的PyTorch curated镜像，确保PyTorch和CUDA版本与Detectron2兼容（比如最新版Detectron2支持PyTorch 1.10+、CUDA 10.2+），示例基础镜像：

   FROM mcr.microsoft.com/azureml/openmpi4.1.0-cuda11.8-cudnn8-ubuntu22.04
   

2. 添加系统依赖：Detectron2编译需要基础编译工具和OpenCV，在Dockerfile中加入：

   RUN apt-get update && apt-get install -y --no-install-recommends \
       git \
       build-essential \
       libopencv-dev \
       && rm -rf /var/lib/apt/lists/*
   

3. 安装指定版本的Detectron2：匹配基础镜像的PyTorch版本，比如对应PyTorch 2.0+可指定v0.6分支：

   RUN pip install git+https://github.com/facebookresearch/detectron2.git@v0.6#egg=detectron2
   

4. 注册Azure ML环境：用Python SDK或Azure ML Studio上传Dockerfile，将镜像注册为工作区环境。

方法二：用requirements.txt配合Azure ML环境 #

如果不想写Dockerfile，必须先锁定依赖版本：

1. 编写requirements.txt：先指定匹配的PyTorch、torchvision版本，再添加Detectron2的Git链接：

   torch>=2.0.0
   torchvision>=0.15.0
   git+https://github.com/facebookresearch/detectron2.git@v0.6
   

2. 创建并注册环境：指定Azure ML的PyTorch curated镜像作为基础，加载requirements：

   from azureml.core import Environment
   
   env = Environment.from_pip_requirements(
       name="detectron2-pip-env",
       file_path="./requirements.txt"
   )
   env.docker.base_image = "mcr.microsoft.com/azureml/openmpi4.1.0-cuda11.8-cudnn8-ubuntu22.04"
   env.register(workspace=ws)
   

你之前的操作错误点 #

• 版本不兼容：Azure ML curated环境的PyTorch/CUDA版本与你安装的Detectron2不匹配，导致编译失败，表面显示安装成功但实际模块缺失。
• 缺少系统依赖：Dockerfile中未添加build-essential、libopencv-dev等编译必需的系统包，Detectron2安装不完整。
• requirements.txt未锁定前置依赖：直接添加Detectron2的Git链接，未指定匹配的PyTorch版本，pip可能安装不兼容的PyTorch，导致Detectron2无法正常编译。

验证环境有效性 #

提交任务前，可在Compute Instance上测试：
创建使用自定义环境的Compute Instance，打开终端运行：

python -c "from detectron2.utils import comm; print('Detectron2 imported successfully')"

无报错则说明环境正常。

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