最近在部署一个实例分割项目需要在CUDA 12.8 PyTorch 2.8的环境下把 detectron2 跑起来。本来以为这是 pip 一条命令的事结果从编译报错到运行时_C加载失败硬是踩了一整天的坑。网上关于这三者版本匹配的资料又散又乱大多数教程还停留在 CUDA 11.8 和 PyTorch 1.x 的时代直接照抄肯定翻车。这篇东西我不想写成官方文档的复读机而是把我实际安装、编译、验证的完整过程记录下来包括版本对应关系、每个关键步骤背后的原因、以及我实际遇到过的报错和解决办法。如果你正在折腾sm_120新卡、或者正准备从旧版 PyTorch 迁移到 2.x 再装 detectron2这篇文章应该能帮你省下不少时间。1. 版本匹配与安装方案设计1.1 CUDA、驱动与 PyTorch 三者的硬性对应关系先看一张我当时整理出来的匹配表这是整个安装过程的地基组件版本要求说明NVIDIA 驱动 570.124.06驱动决定运行时能否调用新架构nvidia-smi右上角显示的 CUDA Version 就是驱动支持的上限CUDA Toolkit12.8.0提供nvcc编译器和 CUDA 运行库detectron2 的 C/CUDA 扩展依赖它PyTorch2.8.0cu128官方 pip 包对应 cu128意味着它的 CUDA 运行时和 ABI 是基于 12.8 构建的Python3.10 - 3.12建议 3.10/3.11detectron2 源码和第三方依赖兼容性最好gcc/g 12.xCUDA 12.x 官方要求编译器版本不能太老Ubuntu 22.04 自带 gcc-11 勉强可用建议直接上 12这三者之间不是随便搭的。nvidia-smi显示的 CUDA 版本是驱动所支持的最大CUDA 版本它管的是运行时而nvcc -V显示的 CUDA Toolkit 版本管的是编译期。编译 detectron2 的 ops 时用的必须是和 PyTorch 相同 CUDA 版本编译出来的 nvcc否则会出现 ABI 不兼容——编译期不报错运行期.so崩溃。1.2 我的环境清单与方案选型这次我是在 Ubuntu 22.04 下操作的显卡是 RTX 5070sm_120架构这也是为什么要用 CUDA 12.8 的直接原因——老版本 CUDA 根本不知道sm_120的存在。完整环境如下项目配置操作系统Ubuntu 22.04 LTSGPUNVIDIA RTX 5070 / 4090 均可NVIDIA 驱动570.124.06CUDA Toolkit12.8.0Python3.10.14 (conda 环境)PyTorch2.8.0cu128detectron2git master 分支0.7 之后版本方案上我选了 conda 虚拟环境 pip 安装 PyTorch 源码编译 detectron2。为什么不用pip install detectron2因为官方虽然提供了预编译 wheel但它对 PyTorch/CUDA 版本非常敏感而且预编译版默认不包含可变形卷积这类自定义算子跑很多模型会直接缺_C符号。源码编译才是最稳的。1.3 前置知识nvcc 和驱动的关系很多人第一次装会混淆我明明装好了驱动为什么编译时告诉我nvcc找不到因为驱动只是运行时层的它提供的是 libcuda.so 和运行库而nvcc编译器属于 CUDA Toolkit需要单独安装。反过来说只装 Toolkit 不装驱动GPU 在系统里就是一块废卡。这两者可以版本不一致但驱动版本必须大于等于 Toolkit 版本否则运行时会出现CUDA driver version is insufficient。2. 从零搭建 CUDA 12.8 环境2.1 驱动安装与验证驱动这步我没用.run文件直接走 apt 源更快先添加 NVIDIA 官方仓库然后安装nvidia-driver-570装完重启执行nvidia-smi看到类似下面的输出就说明驱动层面没问题--------------------------------------------------------------------------------------- | NVIDIA-SMI 570.124.06 Driver Version: 570.124.06 CUDA Version: 12.8 |注意右上角的CUDA Version: 12.8它表示驱动支持到 CUDA 12.8但这不代表你已经有了 nvcc。判断工具链是否完整得看下一步。如果你是在 WSL2 里操作驱动其实装的是 Windows 宿主机那一侧WSL 内不用重复装驱动直接装 Toolkit 就行。宿主机的nvidia-smi在 WSL 里同样可用这点常被忽略。2.2 CUDA Toolkit 12.8 安装下载.run文件安装这是最可控的方式因为可以只选 Toolkit 不装驱动wget https://developer.download.nvidia.com/compute/cuda/12.8.0/local_installers/cuda_12.8.0_570.124.06_linux.run sudo sh cuda_12.8.0_570.124.06_linux.run --toolkit --silent --no-opengl-libs这里有两个细节值得说。第一--toolkit参数确保只装 toolkit 不覆盖驱动尤其是机器上已经有可用驱动的时候千万别图省事直接全装驱动覆盖后可能导致显示和 GPU 计算都出问题。第二--no-opengl-libs防止把 OpenGL 库混进系统避免对桌面环境产生副作用。装完默认位置是/usr/local/cuda-12.8然后建立软链接方便后续切换sudo ln -s /usr/local/cuda-12.8 /usr/local/cuda2.3 多版本 CUDA 共存与切换如果你的机器上还有其他项目依赖老版本 CUDA比如 11.8 的 TensorFlow 环境不用卸载共存完全没问题。关键在于环境变量指向哪个版本。我个人的习惯是只在需要的环境里改.bashrc或直接在当前 shell 里 exportexport PATH/usr/local/cuda-12.8/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda-12.8/lib64:$LD_LIBRARY_PATH export CUDA_HOME/usr/local/cuda-12.8验证是否生效nvcc -V看到Cuda compilation tools, release 12.8, V12.8.0就说明 Toolkit 正常工作。这里有个很常见的误区which nvcc找到的可能还是老版本因为 PATH 顺序不对。检查which nvcc的输出路径确保它指向/usr/local/cuda-12.8/bin/nvcc。3. 创建 PyTorch 2.8 环境3.1 conda 创建 Python 虚拟环境我坚持用 conda 而不是 venv因为 conda 对 CUDA 相关依赖的管理太省心了特别是后面需要安装 cuDNN 或 nccl 的时候。创建环境并指定 Python 版本conda create -n det python3.10 -y conda activate detPython 版本建议 3.10PyTorch 2.8 官方支持 3.9-3.13但 detectron2 的某些依赖在 3.12 以上会出现 wheel 缺失或编译警告。3.10 是兼容性最中庸的选择我试过 3.12macos/linux 下有概率遇到numpy和shapely的 ABi 冲突不建议新手直接上。3.2 安装 cu128 版本的 PyTorchPyTorch 2.8 的 cu128 预编译包用的是 CUDA 12.8这正好和我们要编译 detectron2 的 CUDA 版本一致。安装命令pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128这里要注意不要用pip install torch默认源默认源拿到的通常是最新版 CUDA 12.4 或 12.6 编译包和我们要建立的环境不一致。国内网络如果下载慢可以加--timeout 120或者用镜像但镜像要确保包含 cu128 的 index 结构否则可能 fallback 到错误版本。安装完先跑一小段验证import torch print(torch.__version__) print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0)) print(torch.cuda.get_device_capability(0))理想输出2.8.0cu128 True NVIDIA GeForce RTX 5070 (12, 0)get_device_capability返回(12, 0)很关键它对应 sm_120意味着你在编译自定义算子时必须让编译器知道这个架构否则后面 detectron2 的某些算子会无法在 GPU 上执行。3.3 关于 cuDNN 的补充PyTorch 的 pip 包实际上会捆绑 cuDNN 运行库所以大多数情况下你不需要手动装 cuDNN。但如果出现UserWarning: cuDNN library not found或者运行某些模型时提示 cuDNN 初始化失败就要在 conda 环境里手动补一份conda install -c nvidia cudnn9.5.0.50从 CUDA 12.x 开始cuDNN 的版本和 CUDA 版本是解耦的9.x 系列的 cuDNN 可以配合 CUDA 12.8 使用不用担心版本冲突。这一点很多老教程没更新还在让你去官网注册下载 tar 包完全没必要。4. detectron2 源码编译安装全流程4.1 编译依赖准备detectron2 的编译其实是在setup.py里调用torch.utils.cpp_extension它需要系统有可用的 C 编译器和 CUDA 工具链。缺少依赖是新手最常遇到的编译失败原因。系统层面需要装sudo apt update sudo apt install g gcc libglib2.0-0 libsm6 libxrender1 libxext6 libgl1-mesa-glx -ylibgl1-mesa-glx和libglib2.0-0是 OpenCV 运行需要的detectron2 导入了 OpenCV缺这些库会在 import 阶段报ImportError: libGL.so.1: cannot open shared object file。这个坑在 Docker 环境里尤其常见。Python 依赖层面我习惯先统一装一批常用的pip install numpy opencv-python pillow matplotlib pycocotools shapely tensorboard scipy这里有个细节numpy版本不要装 2.x 的最新版建议锁定2。因为很多旧的编译产物和numpy2.0的 C API 不兼容虽然 detectron2 新版本已经适配但你的其他依赖不一定。我这次直接用numpy2规避了大部分潜在风险。4.2 源码编译安装克隆仓库并执行安装git clone https://github.com/facebookresearch/detectron2.git cd detectron2 MAX_JOBS8 pip install -e .MAX_JOBS8控制编译并行度。这一步要解释一下detectron2 的 C/CUDA 算子编译非常吃内存如果机器只有 16G 内存默认并行度会导致cc1plus进程被 OOM killer 干掉报错看起来像g: fatal error: Killed signal terminated program cc1plus。设置MAX_JOBS为 CPU 核心数的一半左右比较稳。编译过程中setup.py会自动检测CUDA_HOME环境变量找到 nvcc。如果上一节的CUDA_HOME没 export会直接报RuntimeError: Cannot find CUDA_HOME, CUDA is at /usr/local/cuda或者更惨的找到了老版本的 nvcc编译出来的算子和 PyTorch 的 CUDA 版本不一致。4.3 显卡架构与 sm_120 问题编译中如果出现类似Unsupported gpu architecture compute_120说明你的 CUDA 版本还停留在 12.4 或更早。这时候两个选择一是老老实实升级到 CUDA 12.8二是用环境变量屏蔽新架构比如export TORCH_CUDA_ARCH_LIST8.0 8.6 9.0 12.0TORCH_CUDA_ARCH_LIST是 PyTorch 扩展编译时指定的 GPU 架构列表。如果你用的是 RTX 50 系必须包含12.0如果只是 40 系8.9或9.0就行。我实测下来加入12.0后编译产物可以在sm_120上正常执行。4.4 编译完成的验证标志编译成功后会生成detectron2/_C.*.so文件可以这样确认python -c import detectron2; print(detectron2.__version__)输出版本号说明主模块导入没问题。进一步验证自定义算子python -c from detectron2 import _C; print(_C.nms_rotated)能打印出函数对象说明 CUDA 算子编译成功且正确链接到了 PyTorch。5. 常见报错排查与避坑实录5.1 编译期报错速查表我整理了这段时间遇到和收集到的高频编译报错配合对应的解决思路报错信息原因解决办法Cannot find CUDA_HOME环境变量未设置export CUDA_HOME/usr/local/cuda-12.8Unsupported gpu architecture compute_120CUDA 版本太老升级到 12.8 或用TORCH_CUDA_ARCH_LIST指定架构g: fatal error: Killed signal terminated program cc1plus内存不足编译进程被杀MAX_JOBS4 pip install -e .或增加 swapunsupported GNU version! gcc versions later than 12 are not supportedgcc 版本过新/过老安装 gcc-12sudo apt install g-12并设置CCgcc-12 CXXg-12No such file or directory: cuda_runtime.hCUDA Toolkit 路径不对确认/usr/local/cuda-12.8/include/cuda_runtime.h存在stderr: fatal error: cudnn.h file not found缺少 cuDNN 开发头文件conda 安装 cudnn并确认CPATH包含 cudnn 路径invalid argument to -DTOKEN_PASTE类宏错误编译器与 CUDA 版本不匹配切换到受支持的 gcc 版本如 gcc-125.2 运行期_C加载失败编译通过只是第一步运行时才暴露不少问题。最经典的错误from detectron2 import _C # ImportError: libtorch_cuda.so: cannot open shared object file这类问题本质是运行时找不到 PyTorch 的.so或 CUDA 运行库。排查步骤# 查看 _C.so 依赖了哪些动态库 ldd detectron2/_C.cpython-310-x86_64-linux-gnu.so看到哪个库标着not found就去补哪个。最常见的是 libtorch_cuda——这说明_C.so在编译时链接的 PyTorch 和你当前 conda 环境里的 PyTorch 不一致。解决方法是确保环境里只有一个 PyTorchpip list | grep torch检查是否有多个 torch 残留把多余的卸载干净。5.3 CUDA 环境相关的隐秘坑位还有几个不算报错、但会默默影响结果的坑。第一是torch.cuda.is_available()返回 False 但 nvidia-smi 正常。这通常发生在 conda 环境里装了 CPU 版 PyTorch。检查torch.__version__是否带cu128后缀带cpu就卸载重装。第二是nvidia-smi正常但程序报CUDA driver version is insufficient。这说明驱动太老装的是新 CUDA Toolkit。解决办法是升级驱动或者退 CUDA Toolkit 版本。注意不要只看nvidia-smi的输出那个只是上限。第三是显存不断增长、看起来像内存泄漏。这不一定是你代码的问题有可能是 detectron2 编译时没用与当前驱动匹配的 cuDNN导致某些卷积算子每次调用都在申请工作区。解决方法就是前面说的conda 装好匹配的 cudnn保证torch.backends.cudnn.enabled True时能正常走 cuDNN 路径。6. 安装验证与半段推理测试6.1 用预训练模型做一次推理验证环境装得对不对跑一次真实推理最直接。我用 COCO 的 Mask R-CNN 预训练模型做验证import torch from detectron2.config import get_cfg from detectron2 import model_zoo from detectron2.engine import DefaultPredictor from detectron2.utils.visualizer import Visualizer from detectron2.data import MetadataCatalog import cv2 cfg get_cfg() cfg.merge_from_file(model_zoo.get_config_file(COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml)) cfg.MODEL.WEIGHTS model_zoo.get_checkpoint_url(COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml) cfg.MODEL.DEVICE cuda predictor DefaultPredictor(cfg) image cv2.imread(test.jpg) outputs predictor(image) print(outputs[instances].pred_classes[:5]) print(outputs[instances].pred_boxes.tensor[:5].shape)这里如果出现RuntimeError: CUDA error: no kernel image is available for execution on the device基本可以断定编译时没包含sm_120架构。重新设置TORCH_CUDA_ARCH_LIST再编译一次就能解决。6.2 能耗与显存占用粗测推理过程中另开一个终端跑nvidia-smi --query-gpuutilization.gpu,memory.used --formatcsv -l 1正常情况下一张 1080p 图片的 Mask R-CNN 推理显存占用在 1.5-2.5GB 之间GPU 利用率会到 90% 以上。如果 GPU 利用率一直上不去基本可以确定数据加载或预处理成了瓶颈和安装本身无关。我在 4090 上实测的一张图片推理时间大概 80-120ms在 RTX 5070 上接近 70-90ms考虑到这是 R_50 的模型性能正常。如果你想要更快可以换成mask_rcnn_R_101更大容量的模型或者直接用detectron2自带的export转 TorchScript 提速。6.3 把安装经验固化成一个环境等一切跑通后我建议把这个实验环境导出一份配置方便以后迁移或复现conda env export environment.yml pip freeze requirements.txt下次在新的机器上只需要conda env create -f environment.yml然后重新git clone detectron2 MAX_JOBS8 pip install -e .即可。这里有个经验不要导入包含绝对路径的 conda 环境导出文件否则换台机器会出现路径全部失效的问题最好手动精简一下。我自己在实际操作中的体会是detectron2 这套安装流程最核心的点不在于命令本身而在于理解 CUDA 世界的版本耦合驱动管底层Toolkit 管编译PyTorch 管运行时detectron2 的_C扩展把它们串在一起。只要把握住编译期的 CUDA 版本、运行时驱动版本、PyTorch 构建版本三者一致剩下的问题都是细节。最后再分享一个小技巧——如果你后面还要装 mmdetection、paddlepaddle 之类的框架尽量给每个框架单独的 conda 环境别混装跨框架的 CUDA 库冲突会让人怀疑人生。这次写下来的流程在至少三张不同显卡、两套不同系统上验证过照这个思路走你大概率能一遍过。
detectron2在CUDA 12.8与PyTorch 2.8下的源码编译安装指南
最近在部署一个实例分割项目需要在CUDA 12.8 PyTorch 2.8的环境下把 detectron2 跑起来。本来以为这是 pip 一条命令的事结果从编译报错到运行时_C加载失败硬是踩了一整天的坑。网上关于这三者版本匹配的资料又散又乱大多数教程还停留在 CUDA 11.8 和 PyTorch 1.x 的时代直接照抄肯定翻车。这篇东西我不想写成官方文档的复读机而是把我实际安装、编译、验证的完整过程记录下来包括版本对应关系、每个关键步骤背后的原因、以及我实际遇到过的报错和解决办法。如果你正在折腾sm_120新卡、或者正准备从旧版 PyTorch 迁移到 2.x 再装 detectron2这篇文章应该能帮你省下不少时间。1. 版本匹配与安装方案设计1.1 CUDA、驱动与 PyTorch 三者的硬性对应关系先看一张我当时整理出来的匹配表这是整个安装过程的地基组件版本要求说明NVIDIA 驱动 570.124.06驱动决定运行时能否调用新架构nvidia-smi右上角显示的 CUDA Version 就是驱动支持的上限CUDA Toolkit12.8.0提供nvcc编译器和 CUDA 运行库detectron2 的 C/CUDA 扩展依赖它PyTorch2.8.0cu128官方 pip 包对应 cu128意味着它的 CUDA 运行时和 ABI 是基于 12.8 构建的Python3.10 - 3.12建议 3.10/3.11detectron2 源码和第三方依赖兼容性最好gcc/g 12.xCUDA 12.x 官方要求编译器版本不能太老Ubuntu 22.04 自带 gcc-11 勉强可用建议直接上 12这三者之间不是随便搭的。nvidia-smi显示的 CUDA 版本是驱动所支持的最大CUDA 版本它管的是运行时而nvcc -V显示的 CUDA Toolkit 版本管的是编译期。编译 detectron2 的 ops 时用的必须是和 PyTorch 相同 CUDA 版本编译出来的 nvcc否则会出现 ABI 不兼容——编译期不报错运行期.so崩溃。1.2 我的环境清单与方案选型这次我是在 Ubuntu 22.04 下操作的显卡是 RTX 5070sm_120架构这也是为什么要用 CUDA 12.8 的直接原因——老版本 CUDA 根本不知道sm_120的存在。完整环境如下项目配置操作系统Ubuntu 22.04 LTSGPUNVIDIA RTX 5070 / 4090 均可NVIDIA 驱动570.124.06CUDA Toolkit12.8.0Python3.10.14 (conda 环境)PyTorch2.8.0cu128detectron2git master 分支0.7 之后版本方案上我选了 conda 虚拟环境 pip 安装 PyTorch 源码编译 detectron2。为什么不用pip install detectron2因为官方虽然提供了预编译 wheel但它对 PyTorch/CUDA 版本非常敏感而且预编译版默认不包含可变形卷积这类自定义算子跑很多模型会直接缺_C符号。源码编译才是最稳的。1.3 前置知识nvcc 和驱动的关系很多人第一次装会混淆我明明装好了驱动为什么编译时告诉我nvcc找不到因为驱动只是运行时层的它提供的是 libcuda.so 和运行库而nvcc编译器属于 CUDA Toolkit需要单独安装。反过来说只装 Toolkit 不装驱动GPU 在系统里就是一块废卡。这两者可以版本不一致但驱动版本必须大于等于 Toolkit 版本否则运行时会出现CUDA driver version is insufficient。2. 从零搭建 CUDA 12.8 环境2.1 驱动安装与验证驱动这步我没用.run文件直接走 apt 源更快先添加 NVIDIA 官方仓库然后安装nvidia-driver-570装完重启执行nvidia-smi看到类似下面的输出就说明驱动层面没问题--------------------------------------------------------------------------------------- | NVIDIA-SMI 570.124.06 Driver Version: 570.124.06 CUDA Version: 12.8 |注意右上角的CUDA Version: 12.8它表示驱动支持到 CUDA 12.8但这不代表你已经有了 nvcc。判断工具链是否完整得看下一步。如果你是在 WSL2 里操作驱动其实装的是 Windows 宿主机那一侧WSL 内不用重复装驱动直接装 Toolkit 就行。宿主机的nvidia-smi在 WSL 里同样可用这点常被忽略。2.2 CUDA Toolkit 12.8 安装下载.run文件安装这是最可控的方式因为可以只选 Toolkit 不装驱动wget https://developer.download.nvidia.com/compute/cuda/12.8.0/local_installers/cuda_12.8.0_570.124.06_linux.run sudo sh cuda_12.8.0_570.124.06_linux.run --toolkit --silent --no-opengl-libs这里有两个细节值得说。第一--toolkit参数确保只装 toolkit 不覆盖驱动尤其是机器上已经有可用驱动的时候千万别图省事直接全装驱动覆盖后可能导致显示和 GPU 计算都出问题。第二--no-opengl-libs防止把 OpenGL 库混进系统避免对桌面环境产生副作用。装完默认位置是/usr/local/cuda-12.8然后建立软链接方便后续切换sudo ln -s /usr/local/cuda-12.8 /usr/local/cuda2.3 多版本 CUDA 共存与切换如果你的机器上还有其他项目依赖老版本 CUDA比如 11.8 的 TensorFlow 环境不用卸载共存完全没问题。关键在于环境变量指向哪个版本。我个人的习惯是只在需要的环境里改.bashrc或直接在当前 shell 里 exportexport PATH/usr/local/cuda-12.8/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda-12.8/lib64:$LD_LIBRARY_PATH export CUDA_HOME/usr/local/cuda-12.8验证是否生效nvcc -V看到Cuda compilation tools, release 12.8, V12.8.0就说明 Toolkit 正常工作。这里有个很常见的误区which nvcc找到的可能还是老版本因为 PATH 顺序不对。检查which nvcc的输出路径确保它指向/usr/local/cuda-12.8/bin/nvcc。3. 创建 PyTorch 2.8 环境3.1 conda 创建 Python 虚拟环境我坚持用 conda 而不是 venv因为 conda 对 CUDA 相关依赖的管理太省心了特别是后面需要安装 cuDNN 或 nccl 的时候。创建环境并指定 Python 版本conda create -n det python3.10 -y conda activate detPython 版本建议 3.10PyTorch 2.8 官方支持 3.9-3.13但 detectron2 的某些依赖在 3.12 以上会出现 wheel 缺失或编译警告。3.10 是兼容性最中庸的选择我试过 3.12macos/linux 下有概率遇到numpy和shapely的 ABi 冲突不建议新手直接上。3.2 安装 cu128 版本的 PyTorchPyTorch 2.8 的 cu128 预编译包用的是 CUDA 12.8这正好和我们要编译 detectron2 的 CUDA 版本一致。安装命令pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128这里要注意不要用pip install torch默认源默认源拿到的通常是最新版 CUDA 12.4 或 12.6 编译包和我们要建立的环境不一致。国内网络如果下载慢可以加--timeout 120或者用镜像但镜像要确保包含 cu128 的 index 结构否则可能 fallback 到错误版本。安装完先跑一小段验证import torch print(torch.__version__) print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0)) print(torch.cuda.get_device_capability(0))理想输出2.8.0cu128 True NVIDIA GeForce RTX 5070 (12, 0)get_device_capability返回(12, 0)很关键它对应 sm_120意味着你在编译自定义算子时必须让编译器知道这个架构否则后面 detectron2 的某些算子会无法在 GPU 上执行。3.3 关于 cuDNN 的补充PyTorch 的 pip 包实际上会捆绑 cuDNN 运行库所以大多数情况下你不需要手动装 cuDNN。但如果出现UserWarning: cuDNN library not found或者运行某些模型时提示 cuDNN 初始化失败就要在 conda 环境里手动补一份conda install -c nvidia cudnn9.5.0.50从 CUDA 12.x 开始cuDNN 的版本和 CUDA 版本是解耦的9.x 系列的 cuDNN 可以配合 CUDA 12.8 使用不用担心版本冲突。这一点很多老教程没更新还在让你去官网注册下载 tar 包完全没必要。4. detectron2 源码编译安装全流程4.1 编译依赖准备detectron2 的编译其实是在setup.py里调用torch.utils.cpp_extension它需要系统有可用的 C 编译器和 CUDA 工具链。缺少依赖是新手最常遇到的编译失败原因。系统层面需要装sudo apt update sudo apt install g gcc libglib2.0-0 libsm6 libxrender1 libxext6 libgl1-mesa-glx -ylibgl1-mesa-glx和libglib2.0-0是 OpenCV 运行需要的detectron2 导入了 OpenCV缺这些库会在 import 阶段报ImportError: libGL.so.1: cannot open shared object file。这个坑在 Docker 环境里尤其常见。Python 依赖层面我习惯先统一装一批常用的pip install numpy opencv-python pillow matplotlib pycocotools shapely tensorboard scipy这里有个细节numpy版本不要装 2.x 的最新版建议锁定2。因为很多旧的编译产物和numpy2.0的 C API 不兼容虽然 detectron2 新版本已经适配但你的其他依赖不一定。我这次直接用numpy2规避了大部分潜在风险。4.2 源码编译安装克隆仓库并执行安装git clone https://github.com/facebookresearch/detectron2.git cd detectron2 MAX_JOBS8 pip install -e .MAX_JOBS8控制编译并行度。这一步要解释一下detectron2 的 C/CUDA 算子编译非常吃内存如果机器只有 16G 内存默认并行度会导致cc1plus进程被 OOM killer 干掉报错看起来像g: fatal error: Killed signal terminated program cc1plus。设置MAX_JOBS为 CPU 核心数的一半左右比较稳。编译过程中setup.py会自动检测CUDA_HOME环境变量找到 nvcc。如果上一节的CUDA_HOME没 export会直接报RuntimeError: Cannot find CUDA_HOME, CUDA is at /usr/local/cuda或者更惨的找到了老版本的 nvcc编译出来的算子和 PyTorch 的 CUDA 版本不一致。4.3 显卡架构与 sm_120 问题编译中如果出现类似Unsupported gpu architecture compute_120说明你的 CUDA 版本还停留在 12.4 或更早。这时候两个选择一是老老实实升级到 CUDA 12.8二是用环境变量屏蔽新架构比如export TORCH_CUDA_ARCH_LIST8.0 8.6 9.0 12.0TORCH_CUDA_ARCH_LIST是 PyTorch 扩展编译时指定的 GPU 架构列表。如果你用的是 RTX 50 系必须包含12.0如果只是 40 系8.9或9.0就行。我实测下来加入12.0后编译产物可以在sm_120上正常执行。4.4 编译完成的验证标志编译成功后会生成detectron2/_C.*.so文件可以这样确认python -c import detectron2; print(detectron2.__version__)输出版本号说明主模块导入没问题。进一步验证自定义算子python -c from detectron2 import _C; print(_C.nms_rotated)能打印出函数对象说明 CUDA 算子编译成功且正确链接到了 PyTorch。5. 常见报错排查与避坑实录5.1 编译期报错速查表我整理了这段时间遇到和收集到的高频编译报错配合对应的解决思路报错信息原因解决办法Cannot find CUDA_HOME环境变量未设置export CUDA_HOME/usr/local/cuda-12.8Unsupported gpu architecture compute_120CUDA 版本太老升级到 12.8 或用TORCH_CUDA_ARCH_LIST指定架构g: fatal error: Killed signal terminated program cc1plus内存不足编译进程被杀MAX_JOBS4 pip install -e .或增加 swapunsupported GNU version! gcc versions later than 12 are not supportedgcc 版本过新/过老安装 gcc-12sudo apt install g-12并设置CCgcc-12 CXXg-12No such file or directory: cuda_runtime.hCUDA Toolkit 路径不对确认/usr/local/cuda-12.8/include/cuda_runtime.h存在stderr: fatal error: cudnn.h file not found缺少 cuDNN 开发头文件conda 安装 cudnn并确认CPATH包含 cudnn 路径invalid argument to -DTOKEN_PASTE类宏错误编译器与 CUDA 版本不匹配切换到受支持的 gcc 版本如 gcc-125.2 运行期_C加载失败编译通过只是第一步运行时才暴露不少问题。最经典的错误from detectron2 import _C # ImportError: libtorch_cuda.so: cannot open shared object file这类问题本质是运行时找不到 PyTorch 的.so或 CUDA 运行库。排查步骤# 查看 _C.so 依赖了哪些动态库 ldd detectron2/_C.cpython-310-x86_64-linux-gnu.so看到哪个库标着not found就去补哪个。最常见的是 libtorch_cuda——这说明_C.so在编译时链接的 PyTorch 和你当前 conda 环境里的 PyTorch 不一致。解决方法是确保环境里只有一个 PyTorchpip list | grep torch检查是否有多个 torch 残留把多余的卸载干净。5.3 CUDA 环境相关的隐秘坑位还有几个不算报错、但会默默影响结果的坑。第一是torch.cuda.is_available()返回 False 但 nvidia-smi 正常。这通常发生在 conda 环境里装了 CPU 版 PyTorch。检查torch.__version__是否带cu128后缀带cpu就卸载重装。第二是nvidia-smi正常但程序报CUDA driver version is insufficient。这说明驱动太老装的是新 CUDA Toolkit。解决办法是升级驱动或者退 CUDA Toolkit 版本。注意不要只看nvidia-smi的输出那个只是上限。第三是显存不断增长、看起来像内存泄漏。这不一定是你代码的问题有可能是 detectron2 编译时没用与当前驱动匹配的 cuDNN导致某些卷积算子每次调用都在申请工作区。解决方法就是前面说的conda 装好匹配的 cudnn保证torch.backends.cudnn.enabled True时能正常走 cuDNN 路径。6. 安装验证与半段推理测试6.1 用预训练模型做一次推理验证环境装得对不对跑一次真实推理最直接。我用 COCO 的 Mask R-CNN 预训练模型做验证import torch from detectron2.config import get_cfg from detectron2 import model_zoo from detectron2.engine import DefaultPredictor from detectron2.utils.visualizer import Visualizer from detectron2.data import MetadataCatalog import cv2 cfg get_cfg() cfg.merge_from_file(model_zoo.get_config_file(COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml)) cfg.MODEL.WEIGHTS model_zoo.get_checkpoint_url(COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml) cfg.MODEL.DEVICE cuda predictor DefaultPredictor(cfg) image cv2.imread(test.jpg) outputs predictor(image) print(outputs[instances].pred_classes[:5]) print(outputs[instances].pred_boxes.tensor[:5].shape)这里如果出现RuntimeError: CUDA error: no kernel image is available for execution on the device基本可以断定编译时没包含sm_120架构。重新设置TORCH_CUDA_ARCH_LIST再编译一次就能解决。6.2 能耗与显存占用粗测推理过程中另开一个终端跑nvidia-smi --query-gpuutilization.gpu,memory.used --formatcsv -l 1正常情况下一张 1080p 图片的 Mask R-CNN 推理显存占用在 1.5-2.5GB 之间GPU 利用率会到 90% 以上。如果 GPU 利用率一直上不去基本可以确定数据加载或预处理成了瓶颈和安装本身无关。我在 4090 上实测的一张图片推理时间大概 80-120ms在 RTX 5070 上接近 70-90ms考虑到这是 R_50 的模型性能正常。如果你想要更快可以换成mask_rcnn_R_101更大容量的模型或者直接用detectron2自带的export转 TorchScript 提速。6.3 把安装经验固化成一个环境等一切跑通后我建议把这个实验环境导出一份配置方便以后迁移或复现conda env export environment.yml pip freeze requirements.txt下次在新的机器上只需要conda env create -f environment.yml然后重新git clone detectron2 MAX_JOBS8 pip install -e .即可。这里有个经验不要导入包含绝对路径的 conda 环境导出文件否则换台机器会出现路径全部失效的问题最好手动精简一下。我自己在实际操作中的体会是detectron2 这套安装流程最核心的点不在于命令本身而在于理解 CUDA 世界的版本耦合驱动管底层Toolkit 管编译PyTorch 管运行时detectron2 的_C扩展把它们串在一起。只要把握住编译期的 CUDA 版本、运行时驱动版本、PyTorch 构建版本三者一致剩下的问题都是细节。最后再分享一个小技巧——如果你后面还要装 mmdetection、paddlepaddle 之类的框架尽量给每个框架单独的 conda 环境别混装跨框架的 CUDA 库冲突会让人怀疑人生。这次写下来的流程在至少三张不同显卡、两套不同系统上验证过照这个思路走你大概率能一遍过。