OOTDiffusion 中 Detectron2 安装与构建实战源码编译、预编译轮子与常见坑全解析【免费下载链接】OOTDiffusion[AAAI 2025] Official implementation of OOTDiffusion: Outfitting Fusion based Latent Diffusion for Controllable Virtual Try-on项目地址: https://gitcode.com/GitHub_Trending/oo/OOTDiffusion本指南以 Detectron2 安装文档 为核心结合 OOTDiffusion 仓库中内嵌的 Detectron2 源码位于preprocess/humanparsing/mhp_extension/detectron2/展开讲解。你将掌握从零安装 Detectron2 的三条路线源码编译、本地克隆可编辑安装、Linux 预编译轮子、Docker 化部署方式以及六类最常见编译/运行时故障的定位与修复方法并理解 Detectron2 在 OOTDiffusion 人体解析预处理链路中的角色。一、为什么 OOTDiffusion 需要一个可用的 Detectron2OOTDiffusion 的完整虚拟试穿流程分为人体解析Human Parsing→ 姿态估计OpenPose→ 扩散模型推理多个阶段。其中人体解析环节位于preprocess/humanparsing/它依赖的 MHP 扩展preprocess/humanparsing/mhp_extension/直接内嵌了 Facebook AI ResearchFAIR的 Detectron2 代码库作为底层目标检测与分割框架被引入。从仓库结构看这套 Detectron2 是完整的独立代码库包含configs/检测/分割/关键点/全景分割等大量预训练配置、detectron2/框架核心包、demo/、docs/、docker/、projects/、tests/与tools/等标准模块并在configs/Misc/中额外提供了一份my_Base-RCNN-FPN.yaml定制化基础配置说明该内嵌版本经过项目方的本地化适配。虽然 OOTDiffusion 的最终推理通过 ONNX Runtime 加载checkpoints/humanparsing/parsing_atr.onnx与parsing_lip.onnx完成见 run_parsing.py但若要复现解析模型的训练、微调或自行编译 C 扩展正确安装 Detectron2 仍是必要前提。二、安装前置条件Requirements官方安装文档明确列出了以下环境要求缺一不可依赖项版本/说明操作系统Linux 或 macOS预编译轮子仅支持 LinuxPython≥ 3.6setup.py 中python_requires3.6与之吻合PyTorch≥ 1.4setup.py 顶部有assert torch_ver [1, 4]的硬性校验torchvision必须与 PyTorch 版本严格匹配OpenCV可选demo 与可视化功能需要pycocotools数据集/评估所需安装命令见下文gcc / g≥ 5源码编译必需ninja可选但推荐可显著加速编译pycocotools 的官方推荐安装方式pip install cython pip install -U githttps://github.com/cocodataset/cocoapi.git#subdirectoryPythonAPI版本耦合提示torchvision 与 PyTorch 必须配套安装。最稳妥的方式是到 pytorch.org 按同一 CUDA 版本一次性安装两者避免因版本不一致在运行期出现未定义符号类错误详见第六节的故障清单。三、从源码构建 Detectron2推荐路线源码构建是兼容性最好、也最贴合需要 C 扩展detectron2._C这一使用场景的方式。setup.py的get_extensions()函数setup.py会扫描detectron2/layers/csrc/下的vision.cpp、各*.cpp与*.cu文件将其编译为detectron2._C扩展模块只要torch.cuda.is_available()且CUDA_HOME有效或显式设置FORCE_CUDA1就会启用 CUDA 扩展。方式一从 Git 直接安装python -m pip install githttps://github.com/facebookresearch/detectron2.git # 若无写权限追加 --user 参数 # python -m pip install --user githttps://github.com/facebookresearch/detectron2.git方式二本地克隆后以可编辑模式安装git clone https://github.com/facebookresearch/detectron2.git python -m pip install -e detectron2可编辑模式-e会将包链接到克隆目录便于后续修改框架源码或在项目根目录直接运行python调试与 OOTDiffusion 内嵌代码库的开发调试方式一致。方式三macOS 专用编译参数CCclang CXXclang python -m pip install -e .macOS 下需要显式指定 clang 作为编译器否则默认的 gcc 别名可能导致编译失败。重新构建Rebuild的正确姿势如果 Detectron2 是从本地克隆构建的重新编译前必须清理旧产物rm -rf build/ **/*.so文档特别强调重新安装 PyTorch 后通常需要同步重建 Detectron2因为_C扩展是链接到具体 PyTorch 版本的二进制模块跨版本复用会触发第六节中的符号未定义类错误。四、安装预编译轮子仅限 Linux对不想自行编译的用户官方提供了预编译 wheel本仓库内嵌版本对应 CUDA 10.1 时代仓库 Dockerfile 以nvidia/cuda:10.1-cudnn7-devel为基础镜像并安装torch1.5cu101、torchvision0.6cu101# CUDA 10.1 示例 python -m pip install detectron2 -f https://dl.fbaipublicfiles.com/detectron2/wheels/cu101/index.html将 URL 中的cu101替换为cu100、cu92或cpu即可切换对应 CUDA 版本或纯 CPU 版本python -m pip install detectron2 -f https://dl.fbaipublicfiles.com/detectron2/wheels/cpu/index.html必须注意的两点限制预编译轮子只能搭配特定版本的官方 PyTorch 发行版使用换用其他 PyTorch 版本或非官方构建的 PyTorch 将无法工作请以官方 releases 说明为准。预编译轮子通常落后于 master 分支可能与依赖 detectron2 master 的研究项目如projects/下的 DensePose、PointRend、TensorMask、TridentNet不兼容。五、Docker 化安装一条命令拿到完整环境仓库在docker/目录提供了开箱即用的容器化方案。核心 Dockerfile 的构建链路为基于nvidia/cuda:10.1-cudnn7-devel镜像安装python3-opencv、cmake、ninja-build、protobuf-compiler等系统依赖创建非 root 用户appuser安装tensorboard、cython、torch1.5cu101、torchvision0.6cu101、pycocotools、fvcore克隆 detectron2 仓库后在构建期间强制启用 CUDA 编译ENV FORCE_CUDA1并通过TORCH_CUDA_ARCH_LIST指定覆盖 Kepler 至 Turing 的通用 GPU 架构列表因为 Docker 构建时无法探测宿主机 GPU 架构以pip install --user -e detectron2_repo完成可编辑安装。配套的 docker-compose.yml 提供了便捷编排shm_size: 8gb、memlock: -1等配置专门为训练场景优化了共享内存与锁内存限制并透传 NVIDIA GPU。镜像构建完成后可参考 Dockerfile 注释中的验证命令测试推理wget http://images.cocodataset.org/val2017/000000439715.jpg -O input.jpg python3 demo/demo.py \ --config-file configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml \ --input input.jpg --output outputs/ \ --opts MODEL.WEIGHTS detectron2://COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x/137849600/model_final_f10217.pkl六、常见安装问题排查手册如果预编译轮子出现问题官方建议先卸载并改为源码构建。以下是文档列出的六类高发故障与对应解法。6.1 Undefined torch/aten/caffe2 符号或运行库时立即段错误Segmentation Fault根因detectron2 或 torchvision 未与你当前运行的 PyTorch 版本配套编译。排查步骤若来自预编译 torchvision卸载 torchvision 与 PyTorch按 pytorch.org 重新配套安装若来自预编译 detectron2查阅 release notes 确认该轮子要求的 PyTorch 版本若来自手动源码构建删除build/与**/*.so后重新编译让扩展基于当前环境的 PyTorch 重建仍无法解决时提交 issue 请附带gdb -ex r -ex bt -ex quit --args python -m detectron2.utils.collect_env的输出。6.2 Undefined C symbols如GLIBCXX根因库由较新的 C 编译器编译却运行在较旧的 C 运行时上老版本 anaconda 常见。解法先尝试conda update libgcc后重建 detectron2根治办法是为进程加载正确版本的 C 运行时例如LD_PRELOAD/path/to/libstdc.so。6.3 Not compiled with GPU support 或 Detectron2 CUDA Compiler: not available根因构建时未找到 CUDA。自查命令python -c import torch; from torch.utils.cpp_extension import CUDA_HOME; print(torch.cuda.is_available(), CUDA_HOME)构建时该命令必须输出合法的 CUDA 路径。需要说明的是大部分模型可以在无 GPU 支持的情况下运行推理但无法训练纯 CPU 场景只需在配置中设置MODEL.DEVICEcpu。6.4 invalid device function 或 no kernel image is available for execution两种可能CUDA 版本不一致编译用的 CUDA 与运行用的 CUDA 不同。通过python -m detectron2.utils.collect_env检查输出中的 Detectron2 CUDA Compiler、CUDA_HOME、PyTorch built with - CUDA 三项是否一致不一致时要么更换匹配本地 CUDA 的 PyTorch 构建要么安装与 PyTorch 匹配的 CUDA 版本。GPU 架构算力不匹配detectron2/torchvision 默认按编译时检测到的 GPU 型号生成架构 flags换 GPU 后可能失效。可通过TORCH_CUDA_ARCH_LIST环境变量在编译时覆盖目标架构例如export TORCH_CUDA_ARCH_LIST6.0,7.0 # 同时支持 P100 与 V1006.5 Undefined CUDA symbols / 无法打开 libcudart.so / nvcc 失败根因编译 detectron2 或 torchvision 所用的 NVCC 版本与运行时 CUDA 版本不匹配anaconda 的 CUDA runtime 场景尤其常见。同样用python -m detectron2.utils.collect_env核验三处 CUDA 版本信息然后对齐 PyTorch 与本地 CUDA 的版本。6.6 ImportError: cannot import name _C解法按上文源码构建步骤重新编译安装 detectron2若你正运行在 detectron2 仓库根目录下请先cd到其他目录再导入——否则 Python 可能加载了当前目录下未编译的源码树而非已安装的包。6.7 ONNX 转换时出现 TraceWarning 后段错误根因ONNX 包由过旧的编译器编译。请用与 PyTorch 接近的编译器版本从源码构建 ONNXPyTorch 编译信息可通过torch.__config__.show()查看。七、环境诊断利器collect_env几乎所有故障排查都绕不开环境信息收集。Detectron2 提供了标准化的诊断命令python -m detectron2.utils.collect_env该命令的实现位于 collect_env.py会一次性输出操作系统与 Python 版本、numpy/Pillow 版本、detectron2 版本与安装路径、detectron2._C能否导入、编译器版本与 CUDA 编译器版本、GPU 型号列表、CUDA_HOME、NVCC版本、TORCH_CUDA_ARCH_LIST环境变量等关键信息并借助cuobjdump --list-elf检测_C扩展实际编译的 SM 架构detect_compute_compatibility函数。提交 issue 前务必附上这份输出它能一屏定位绝大多数版本耦合问题。八、安装完成后快速验证与进一步学习安装成功的标志是能正常导入扩展模块import detectron2 from detectron2.utils.collect_env import collect_env_info print(collect_env_info())后续可参考仓库内的 GETTING_STARTED.md 学习 Quick Start推理 demo、自定义数据集与训练流程浏览 MODEL_ZOO.md 查看 COCO 各类任务的基线模型或阅读docs/下的配置、数据加载、评估、扩展等专题教程。回归 OOTDiffusion 场景当你在本仓库环境搭建 Detectron2 时请以仓库内嵌版本preprocess/humanparsing/mhp_extension/detectron2/为准优先采用源码构建 可编辑安装的方式确保_C扩展与当前 PyTorch 严格配套若仅需复现 OOTDiffusion 的完整试穿流程而非训练解析模型可直接走 ONNX Runtime 推理路径run_parsing.py无需编译 Detectron2 即可产出高质量的人体解析 mask作为后续虚拟试穿扩散模型的条件输入。【免费下载链接】OOTDiffusion[AAAI 2025] Official implementation of OOTDiffusion: Outfitting Fusion based Latent Diffusion for Controllable Virtual Try-on项目地址: https://gitcode.com/GitHub_Trending/oo/OOTDiffusion创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OOTDiffusion 中 Detectron2 安装与构建实战：源码编译、预编译轮子与常见坑全解析
OOTDiffusion 中 Detectron2 安装与构建实战源码编译、预编译轮子与常见坑全解析【免费下载链接】OOTDiffusion[AAAI 2025] Official implementation of OOTDiffusion: Outfitting Fusion based Latent Diffusion for Controllable Virtual Try-on项目地址: https://gitcode.com/GitHub_Trending/oo/OOTDiffusion本指南以 Detectron2 安装文档 为核心结合 OOTDiffusion 仓库中内嵌的 Detectron2 源码位于preprocess/humanparsing/mhp_extension/detectron2/展开讲解。你将掌握从零安装 Detectron2 的三条路线源码编译、本地克隆可编辑安装、Linux 预编译轮子、Docker 化部署方式以及六类最常见编译/运行时故障的定位与修复方法并理解 Detectron2 在 OOTDiffusion 人体解析预处理链路中的角色。一、为什么 OOTDiffusion 需要一个可用的 Detectron2OOTDiffusion 的完整虚拟试穿流程分为人体解析Human Parsing→ 姿态估计OpenPose→ 扩散模型推理多个阶段。其中人体解析环节位于preprocess/humanparsing/它依赖的 MHP 扩展preprocess/humanparsing/mhp_extension/直接内嵌了 Facebook AI ResearchFAIR的 Detectron2 代码库作为底层目标检测与分割框架被引入。从仓库结构看这套 Detectron2 是完整的独立代码库包含configs/检测/分割/关键点/全景分割等大量预训练配置、detectron2/框架核心包、demo/、docs/、docker/、projects/、tests/与tools/等标准模块并在configs/Misc/中额外提供了一份my_Base-RCNN-FPN.yaml定制化基础配置说明该内嵌版本经过项目方的本地化适配。虽然 OOTDiffusion 的最终推理通过 ONNX Runtime 加载checkpoints/humanparsing/parsing_atr.onnx与parsing_lip.onnx完成见 run_parsing.py但若要复现解析模型的训练、微调或自行编译 C 扩展正确安装 Detectron2 仍是必要前提。二、安装前置条件Requirements官方安装文档明确列出了以下环境要求缺一不可依赖项版本/说明操作系统Linux 或 macOS预编译轮子仅支持 LinuxPython≥ 3.6setup.py 中python_requires3.6与之吻合PyTorch≥ 1.4setup.py 顶部有assert torch_ver [1, 4]的硬性校验torchvision必须与 PyTorch 版本严格匹配OpenCV可选demo 与可视化功能需要pycocotools数据集/评估所需安装命令见下文gcc / g≥ 5源码编译必需ninja可选但推荐可显著加速编译pycocotools 的官方推荐安装方式pip install cython pip install -U githttps://github.com/cocodataset/cocoapi.git#subdirectoryPythonAPI版本耦合提示torchvision 与 PyTorch 必须配套安装。最稳妥的方式是到 pytorch.org 按同一 CUDA 版本一次性安装两者避免因版本不一致在运行期出现未定义符号类错误详见第六节的故障清单。三、从源码构建 Detectron2推荐路线源码构建是兼容性最好、也最贴合需要 C 扩展detectron2._C这一使用场景的方式。setup.py的get_extensions()函数setup.py会扫描detectron2/layers/csrc/下的vision.cpp、各*.cpp与*.cu文件将其编译为detectron2._C扩展模块只要torch.cuda.is_available()且CUDA_HOME有效或显式设置FORCE_CUDA1就会启用 CUDA 扩展。方式一从 Git 直接安装python -m pip install githttps://github.com/facebookresearch/detectron2.git # 若无写权限追加 --user 参数 # python -m pip install --user githttps://github.com/facebookresearch/detectron2.git方式二本地克隆后以可编辑模式安装git clone https://github.com/facebookresearch/detectron2.git python -m pip install -e detectron2可编辑模式-e会将包链接到克隆目录便于后续修改框架源码或在项目根目录直接运行python调试与 OOTDiffusion 内嵌代码库的开发调试方式一致。方式三macOS 专用编译参数CCclang CXXclang python -m pip install -e .macOS 下需要显式指定 clang 作为编译器否则默认的 gcc 别名可能导致编译失败。重新构建Rebuild的正确姿势如果 Detectron2 是从本地克隆构建的重新编译前必须清理旧产物rm -rf build/ **/*.so文档特别强调重新安装 PyTorch 后通常需要同步重建 Detectron2因为_C扩展是链接到具体 PyTorch 版本的二进制模块跨版本复用会触发第六节中的符号未定义类错误。四、安装预编译轮子仅限 Linux对不想自行编译的用户官方提供了预编译 wheel本仓库内嵌版本对应 CUDA 10.1 时代仓库 Dockerfile 以nvidia/cuda:10.1-cudnn7-devel为基础镜像并安装torch1.5cu101、torchvision0.6cu101# CUDA 10.1 示例 python -m pip install detectron2 -f https://dl.fbaipublicfiles.com/detectron2/wheels/cu101/index.html将 URL 中的cu101替换为cu100、cu92或cpu即可切换对应 CUDA 版本或纯 CPU 版本python -m pip install detectron2 -f https://dl.fbaipublicfiles.com/detectron2/wheels/cpu/index.html必须注意的两点限制预编译轮子只能搭配特定版本的官方 PyTorch 发行版使用换用其他 PyTorch 版本或非官方构建的 PyTorch 将无法工作请以官方 releases 说明为准。预编译轮子通常落后于 master 分支可能与依赖 detectron2 master 的研究项目如projects/下的 DensePose、PointRend、TensorMask、TridentNet不兼容。五、Docker 化安装一条命令拿到完整环境仓库在docker/目录提供了开箱即用的容器化方案。核心 Dockerfile 的构建链路为基于nvidia/cuda:10.1-cudnn7-devel镜像安装python3-opencv、cmake、ninja-build、protobuf-compiler等系统依赖创建非 root 用户appuser安装tensorboard、cython、torch1.5cu101、torchvision0.6cu101、pycocotools、fvcore克隆 detectron2 仓库后在构建期间强制启用 CUDA 编译ENV FORCE_CUDA1并通过TORCH_CUDA_ARCH_LIST指定覆盖 Kepler 至 Turing 的通用 GPU 架构列表因为 Docker 构建时无法探测宿主机 GPU 架构以pip install --user -e detectron2_repo完成可编辑安装。配套的 docker-compose.yml 提供了便捷编排shm_size: 8gb、memlock: -1等配置专门为训练场景优化了共享内存与锁内存限制并透传 NVIDIA GPU。镜像构建完成后可参考 Dockerfile 注释中的验证命令测试推理wget http://images.cocodataset.org/val2017/000000439715.jpg -O input.jpg python3 demo/demo.py \ --config-file configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml \ --input input.jpg --output outputs/ \ --opts MODEL.WEIGHTS detectron2://COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x/137849600/model_final_f10217.pkl六、常见安装问题排查手册如果预编译轮子出现问题官方建议先卸载并改为源码构建。以下是文档列出的六类高发故障与对应解法。6.1 Undefined torch/aten/caffe2 符号或运行库时立即段错误Segmentation Fault根因detectron2 或 torchvision 未与你当前运行的 PyTorch 版本配套编译。排查步骤若来自预编译 torchvision卸载 torchvision 与 PyTorch按 pytorch.org 重新配套安装若来自预编译 detectron2查阅 release notes 确认该轮子要求的 PyTorch 版本若来自手动源码构建删除build/与**/*.so后重新编译让扩展基于当前环境的 PyTorch 重建仍无法解决时提交 issue 请附带gdb -ex r -ex bt -ex quit --args python -m detectron2.utils.collect_env的输出。6.2 Undefined C symbols如GLIBCXX根因库由较新的 C 编译器编译却运行在较旧的 C 运行时上老版本 anaconda 常见。解法先尝试conda update libgcc后重建 detectron2根治办法是为进程加载正确版本的 C 运行时例如LD_PRELOAD/path/to/libstdc.so。6.3 Not compiled with GPU support 或 Detectron2 CUDA Compiler: not available根因构建时未找到 CUDA。自查命令python -c import torch; from torch.utils.cpp_extension import CUDA_HOME; print(torch.cuda.is_available(), CUDA_HOME)构建时该命令必须输出合法的 CUDA 路径。需要说明的是大部分模型可以在无 GPU 支持的情况下运行推理但无法训练纯 CPU 场景只需在配置中设置MODEL.DEVICEcpu。6.4 invalid device function 或 no kernel image is available for execution两种可能CUDA 版本不一致编译用的 CUDA 与运行用的 CUDA 不同。通过python -m detectron2.utils.collect_env检查输出中的 Detectron2 CUDA Compiler、CUDA_HOME、PyTorch built with - CUDA 三项是否一致不一致时要么更换匹配本地 CUDA 的 PyTorch 构建要么安装与 PyTorch 匹配的 CUDA 版本。GPU 架构算力不匹配detectron2/torchvision 默认按编译时检测到的 GPU 型号生成架构 flags换 GPU 后可能失效。可通过TORCH_CUDA_ARCH_LIST环境变量在编译时覆盖目标架构例如export TORCH_CUDA_ARCH_LIST6.0,7.0 # 同时支持 P100 与 V1006.5 Undefined CUDA symbols / 无法打开 libcudart.so / nvcc 失败根因编译 detectron2 或 torchvision 所用的 NVCC 版本与运行时 CUDA 版本不匹配anaconda 的 CUDA runtime 场景尤其常见。同样用python -m detectron2.utils.collect_env核验三处 CUDA 版本信息然后对齐 PyTorch 与本地 CUDA 的版本。6.6 ImportError: cannot import name _C解法按上文源码构建步骤重新编译安装 detectron2若你正运行在 detectron2 仓库根目录下请先cd到其他目录再导入——否则 Python 可能加载了当前目录下未编译的源码树而非已安装的包。6.7 ONNX 转换时出现 TraceWarning 后段错误根因ONNX 包由过旧的编译器编译。请用与 PyTorch 接近的编译器版本从源码构建 ONNXPyTorch 编译信息可通过torch.__config__.show()查看。七、环境诊断利器collect_env几乎所有故障排查都绕不开环境信息收集。Detectron2 提供了标准化的诊断命令python -m detectron2.utils.collect_env该命令的实现位于 collect_env.py会一次性输出操作系统与 Python 版本、numpy/Pillow 版本、detectron2 版本与安装路径、detectron2._C能否导入、编译器版本与 CUDA 编译器版本、GPU 型号列表、CUDA_HOME、NVCC版本、TORCH_CUDA_ARCH_LIST环境变量等关键信息并借助cuobjdump --list-elf检测_C扩展实际编译的 SM 架构detect_compute_compatibility函数。提交 issue 前务必附上这份输出它能一屏定位绝大多数版本耦合问题。八、安装完成后快速验证与进一步学习安装成功的标志是能正常导入扩展模块import detectron2 from detectron2.utils.collect_env import collect_env_info print(collect_env_info())后续可参考仓库内的 GETTING_STARTED.md 学习 Quick Start推理 demo、自定义数据集与训练流程浏览 MODEL_ZOO.md 查看 COCO 各类任务的基线模型或阅读docs/下的配置、数据加载、评估、扩展等专题教程。回归 OOTDiffusion 场景当你在本仓库环境搭建 Detectron2 时请以仓库内嵌版本preprocess/humanparsing/mhp_extension/detectron2/为准优先采用源码构建 可编辑安装的方式确保_C扩展与当前 PyTorch 严格配套若仅需复现 OOTDiffusion 的完整试穿流程而非训练解析模型可直接走 ONNX Runtime 推理路径run_parsing.py无需编译 Detectron2 即可产出高质量的人体解析 mask作为后续虚拟试穿扩散模型的条件输入。【免费下载链接】OOTDiffusion[AAAI 2025] Official implementation of OOTDiffusion: Outfitting Fusion based Latent Diffusion for Controllable Virtual Try-on项目地址: https://gitcode.com/GitHub_Trending/oo/OOTDiffusion创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考