企业官网建设流程全解析

• 人工智能
• 计算机视觉
• 深度学习

MMCV 是 OpenMMLab 计算机视觉算法库的公共基础组件，提供通用训练/推理接口、图像与视频处理工具，以及大量开箱即用的 CPU/CUDA 算子。本文以仓库中的官方安装文档 docs/en/get_started/installation.md 为主体，结合仓库源码，系统讲解两个发行版本（mmcv 完整版与 mmcv-lite 精简版）的区别、使用 mim 与 pip 两种安装方式的完整步骤、预编译包与源码包的判别、与 PyTorch/CUDA 的版本匹配规则，以及基于 Docker 的镜像构建方法。读完本文，你将能够在任意环境中正确安装并验证 MMCV，并学会在缺少预编译包时自行判断下一步该怎么做。

一、先弄清两个版本：mmcv 与 mmcv-lite

MMCV 在 PyPI 上以两个独立的包名发布，功能边界清晰：

• mmcv：完整版。包含全部特性以及丰富的 CPU/CUDA 算子，开箱即用。代价是完整版可能需要在本地编译较长时间（若无可用的预编译 wheel）。
• mmcv-lite：精简版。不包含 CPU/CUDA 算子，但保留其余所有特性和功能，形态上接近 MMCV 1.0 之前的版本。当你确定不需要任何算子时，它可以作为轻量选项。

安装文档对此给出了明确警告：不要在同一个环境中同时安装两个版本，否则可能遇到ModuleNotFound之类的错误；安装其中一个之前必须卸载另一个。文档同时强调："如果 CUDA 可用，强烈推荐安装 mmcv"。这是因为包括 NMS、ROI Align、可变形卷积等在内的大量高性能算子只存在于完整版中，而它们是 OpenMMLab 系列算法（如 MMDetection、MMSegmentation、MMDetection3D）高效运行的基础。

从源码角度可以更精确地理解这两个名字的由来：setup.py 中有一行关键逻辑：

name='mmcv' if os.getenv('MMCV_WITH_OPS', '1') == '1' else 'mmcv-lite',

也就是说，包名直接由环境变量MMCV_WITH_OPS决定：为1（默认值）时构建并发布为mmcv，为0时跳过算子扩展编译并发布为mmcv-lite。同时 mmcv/version.py 记录了当前仓库的版本号__version__ = '2.2.0'，安装时可通过它核对版本。

二、安装 mmcv：前提检查与推荐路径

1. 安装前确认 PyTorch 已就绪

MMCV 依赖 PyTorch 的 C++ 扩展体系和张量类型，安装 mmcv 之前必须确保 PyTorch 已按官方流程安装成功。官方文档给出的验证命令是：

python -c 'import torch;print(torch.__version__)'

如果命令输出了版本号（例如1.8.1、2.1.0），说明 PyTorch 可用；若报错ModuleNotFoundError: No module named 'torch'，则应先回头完成 PyTorch 的安装。

2. 使用 mim 安装（官方推荐）

mim 是 OpenMMLab 系列项目的包管理工具，最大的价值是：它会自动探测当前环境中的 PyTorch 与 CUDA 版本，并从 OpenMMLab 的预编译包索引中选择匹配的 mmcv wheel 进行安装，用户无需手工拼接繁琐的-f参数。

pip install -U openmim mim install mmcv

安装指定版本（例如 2.0.0）：

mim install mmcv==2.0.0

mim 的底层逻辑是：访问形如https://download.openmmlab.com/mmcv/dist/{cu版本}/{torch版本}/index.html的索引页，获取该环境下可用的包列表。安装日志中两种典型的包来源可以帮你判断发生了什么：

• 使用预编译包：下载的是以.whl结尾的文件，例如mmcv-2.0.0-cp38-cp38-manylinux1_x86_64.whl，说明当前 PyTorch/CUDA/Python 组合有现成的二进制包，安装会很快。
• 使用源码包：下载的是以.tar.gz结尾的源码包（如mmcv-2.0.0.tar.gz），说明没有匹配的预编译包，pip/mim 退回到源码构建。

如果你的环境中出现了第二种日志，意味着当前 PyTorch、CUDA 或 mmcv 版本没有对应的预编译产物，此时应该转向源码编译，具体步骤见 docs/en/get_started/build.md。

3. 两个实用的安装技巧

• 无 GUI 环境使用 headless OpenCV：在最小化容器或无图形界面的服务器上，可以先安装opencv-python-headless再安装 MMCV，这样依赖解析阶段会自动跳过对opencv-python的安装。这一行为与 setup.py 中的逻辑对应：安装脚本会先尝试import cv2，若失败则从opencv-python-headless>=3与opencv-python>=3中选择当前环境已满足的那一个。
• 指定 PyPI 镜像源：当依赖库下载过慢时，可显式指定镜像源：

mim install mmcv -i https://pypi.tuna.tsinghua.edu.cn/simple

4. 安装完成后的验证

运行仓库自带的安装检查脚本 .dev_scripts/check_installation.py：

python .dev_scripts/check_installation.py

该脚本会执行两类真实运算来验证算子扩展是否编译/安装成功（源码见 .dev_scripts/check_installation.py）：

• 构造两组带角度信息的旋转框张量，调用mmcv.ops.box_iou_rotated在 CPU 上执行，成功则输出CPU ops were compiled successfully.；
• 若torch.cuda.is_available()为真，将同样的张量搬到 GPU 再执行一次，成功则输出CUDA ops were compiled successfully.，否则提示跳过 CUDA 检查；
• 最后通过mmcv.utils.collect_env汇总打印完整的环境信息（PyTorch、CUDA、GCC、Python 等），便于排查问题。

如果此脚本报错，可先查阅 docs/en/faq.md 中的常见问题解决方案。

三、使用 pip 手工安装：版本匹配规则详解

当你不使用 mim 时，需要自行确定与当前环境匹配的 mmcv 预编译包。官方文档给出的第一步是查看 CUDA 与 PyTorch 版本：

python -c 'import torch;print(torch.__version__);print(torch.version.cuda)'

例如输出1.8.1与10.2，则对应的安装命令为：

pip install mmcv==2.0.0 -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html

这条命令的通用模板是：

pip install mmcv=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html

其中两个占位符的换算规则（与官方文档内置的下拉选择器脚本逻辑一致）：

• cu_version：把 CUDA 版本号去掉小数点并加上cu前缀，例如10.2 → cu102、11.3 → cu113；若是 CPU 环境或 Apple MPS 环境，则统一为cpu。
• torch_version：取 PyTorch 版本号去掉最后一位（即舍去 patch 版本），例如1.8.1 → torch1.8.0、1.9.0 → torch1.9.0。

版本匹配的三条重要提示

1. 找不到对应版本怎么办：如果在官方提供的预编译包索引中没有与你的 PyTorch、CUDA 或 mmcv 版本匹配的产物，说明该组合没有预编译包，此时应改为源码编译，见 docs/en/get_started/build.md。
2. PyTorch 1.x 的 patch 版本兼容性：mmcv 只对1.x.0提供编译产物，因为 PyTorch 的1.x.0与1.x.1之间通常保持二进制兼容。因此如果你的 PyTorch 是1.8.1，可以放心选用按1.8.0编译的 mmcv，通常可以正常工作。
3. 可用的版本组合：仓库的 docs/en/_static/version.json 保存了官方版本矩阵的原始数据，覆盖 Linux、Windows、macOS 三大平台，CUDA 包括 12.1、11.8、10.2 及更低版本，并包含cpu（无 GPU）与mps（Apple Silicon）两种特殊环境；当前版本矩阵中 mmcv 的最新发布版本即 2.2.0，与 mmcv/version.py 一致。你可以对照该文件核对自己环境是否在预编译支持范围内。

同样地，pip 方式下若想加速依赖下载，也可以组合使用镜像源与预编译索引：

pip install mmcv -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9.0/index.html -i https://pypi.tuna.tsinghua.edu.cn/simple

mmcv 的运行时依赖一览

以 pip 或 mim 安装 mmcv 时，会一并解析 setup.py 读取的install_requires，其来源为 requirements/runtime.txt：addict、mmengine>=0.3.0、numpy、packaging、Pillow、pyyaml，以及 Windows 平台专用的regex与yapf；此外如前所述，还会按环境在opencv-python-headless>=3与opencv-python>=3二选一。了解这些依赖有助于在离线或受限网络环境下提前准备。仓库还提供了all、tests、build、optional四组扩展依赖（见 setup.py），其中optional包含ninja与psutil（见 requirements/optional.txt），它们在源码编译阶段用于加速构建，这也是源码编译文档要求先安装该文件的原因。

四、使用 Docker 安装 mmcv

1. 基于 release Dockerfile 构建

官方推荐两种构建方式：一是先把仓库克隆到本地再构建：

git clone https://github.com/open-mmlab/mmcv.git && cd mmcv docker build -t mmcv -f docker/release/Dockerfile .

二是直接基于远程仓库的docker/release目录构建，无需本地克隆：

docker build -t mmcv https://github.com/open-mmlab/mmcv.git#main:docker/release

2. 通过 build-arg 定制版本

查看仓库中的 docker/release/Dockerfile 可知，该镜像支持四个构建参数，均有默认值：

默认构建会安装最新发布版 mmcv；要安装指定版本，例如 2.0.0：

docker image build -t mmcv -f docker/release/Dockerfile --build-arg MMCV=2.0.0 .

如需同时定制 PyTorch 与 CUDA，例如使用 PyTorch 1.11 + CUDA 11.3 + cuDNN 8 构建 2.0.0 版本：

docker build -t mmcv -f docker/release/Dockerfile \ --build-arg PYTORCH=1.11.0 \ --build-arg CUDA=11.3 \ --build-arg CUDNN=8 \ --build-arg MMCV=2.0.0 .

Dockerfile 的构建逻辑值得注意（docker/release/Dockerfile）：它以pytorch/pytorch:${PYTORCH}-cuda${CUDA}-cudnn${CUDNN}-devel为基础镜像；先通过 apt 安装 OpenCV 所需的系统库libgl1与libglib2.0-0；随后使用pip install -U openmim && mim install mmcv==${MMCV}完成安装（MMCV为空时安装mmcv>=2.0.0rc1）；最后执行python -c 'import mmcv;print(mmcv.__version__)'在镜像内自动验证安装结果。这也印证了 mim 在 OpenMMLab 安装链路中的核心地位。

3. 开发者模式镜像（供参考）

仓库还提供了一份面向开发者的 docker/dev/Dockerfile，其差异在于：从源码克隆仓库并git checkout 2.x，以pip install -e .[all] -v的可编辑模式安装，并通过FORCE_CUDA=1、TORCH_CUDA_ARCH_LIST等环境变量控制 CUDA 编译行为。一般使用场景无需此镜像，但它展示了源码构建在 Docker 环境中的典型组合方式。

五、安装 mmcv-lite：一行命令

如果你只需要 MMCV 的基础工具（如图像/视频处理、CNN 组件、通用训练接口），不需要任何 CPU/CUDA 算子，可以安装精简版：

pip install mmcv-lite

同样地，若你的程序会用到与 PyTorch 相关的模块，请先确保 PyTorch 已成功安装。需要注意，mmcv-lite 与 mmcv 是两个独立包，不要在同一个环境中混装。

六、总结：如何选择安装路径

结合官方文档与仓库源码，可归纳出如下决策流程：

1. 确认 PyTorch 已安装（python -c 'import torch;print(torch.__version__)'）；
2. 若 CUDA 可用且需要高性能算子，选择mmcv（完整版）；否则可选mmcv-lite；
3. 优先使用mim install mmcv，由工具自动匹配预编译包；需要固定版本时用mim install mmcv==x.y.z；
4. 若日志显示下载的是.tar.gz源码包（即无匹配预编译包），转至 docs/en/get_started/build.md 按平台源码编译；
5. 安装完成后运行 .dev_scripts/check_installation.py 验证 CPU/CUDA 算子是否可用，出错时查阅 docs/en/faq.md；
6. 在容器化部署场景下，使用 docker/release/Dockerfile 并通过PYTORCH、CUDA、CUDNN、MMCV四个 build-arg 锁定镜像版本。

• 人工智能
• 计算机视觉
• 深度学习