From 4eb366b07ce50c86aad85ba72817ec729122dbdd Mon Sep 17 00:00:00 2001 From: tianlei Date: Sat, 17 Dec 2022 17:29:21 +0800 Subject: [PATCH] CodeCamp #1565 [Doc] update the Chinese version of get_started.md (#2417) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * DOC Update docs/zh_cn/get_started.md Co-authored-by: 谢昕辰 --- docs/zh_cn/get_started.md | 342 +++++++++++++++++--------------------- 1 file changed, 148 insertions(+), 194 deletions(-) diff --git a/docs/zh_cn/get_started.md b/docs/zh_cn/get_started.md index 66325d592..fff70a256 100644 --- a/docs/zh_cn/get_started.md +++ b/docs/zh_cn/get_started.md @@ -1,248 +1,202 @@ -# 开始（待更新） +# 开始：安装和运行 MMSeg -## 依赖 +## 预备知识 -- Linux or macOS (Windows下支持需要 mmcv-full，但运行时可能会有一些问题。) -- Python 3.6+ -- PyTorch 1.3+ -- CUDA 9.2+ (如果您基于源文件编译 PyTorch, CUDA 9.0也可以使用) -- GCC 5+ -- [MMCV](https://mmcv.readthedocs.io/en/latest/#installation) +本教程中，我们将会演示如何使用 PyTorch 准备环境。 -可编译的 MMSegmentation 和 MMCV 版本如下所示，请对照对应版本安装以避免安装问题。 +MMSegmentation 可以在 Linux, Windows 和 macOS 系统上运行，并且需要安装 Python 3.6+, CUDA 9.2+ 和 PyTorch 1.5+ -| MMSegmentation 版本 | MMCV 版本 | MMClassification 版本 | -| :-----------------: | :-------------------------: | :---------------------: | -| master | mmcv-full>=1.4.4, \<=1.6.0 | mmcls>=0.20.1, \<=1.0.0 | -| 0.24.1 | mmcv-full>=1.4.4, \<=1.6.0 | mmcls>=0.20.1, \<=1.0.0 | -| 0.23.0 | mmcv-full>=1.4.4, \<=1.6.0 | mmcls>=0.20.1, \<=1.0.0 | -| 0.22.0 | mmcv-full>=1.4.4, \<=1.6.0 | mmcls>=0.20.1, \<=1.0.0 | -| 0.21.1 | mmcv-full>=1.4.4, \<=1.6.0 | Not required | -| 0.20.2 | mmcv-full>=1.3.13, \<=1.6.0 | Not required | -| 0.19.0 | mmcv-full>=1.3.13, \<1.3.17 | Not required | -| 0.18.0 | mmcv-full>=1.3.13, \<1.3.17 | Not required | -| 0.17.0 | mmcv-full>=1.3.7, \<1.3.17 | Not required | -| 0.16.0 | mmcv-full>=1.3.7, \<1.3.17 | Not required | -| 0.15.0 | mmcv-full>=1.3.7, \<1.3.17 | Not required | -| 0.14.1 | mmcv-full>=1.3.7, \<1.3.17 | Not required | -| 0.14.0 | mmcv-full>=1.3.1, \<1.3.2 | Not required | -| 0.13.0 | mmcv-full>=1.3.1, \<1.3.2 | Not required | -| 0.12.0 | mmcv-full>=1.1.4, \<1.3.2 | Not required | -| 0.11.0 | mmcv-full>=1.1.4, \<1.3.0 | Not required | -| 0.10.0 | mmcv-full>=1.1.4, \<1.3.0 | Not required | -| 0.9.0 | mmcv-full>=1.1.4, \<1.3.0 | Not required | -| 0.8.0 | mmcv-full>=1.1.4, \<1.2.0 | Not required | -| 0.7.0 | mmcv-full>=1.1.2, \<1.2.0 | Not required | -| 0.6.0 | mmcv-full>=1.1.2, \<1.2.0 | Not required | +**注意:** +如果您已经安装了 PyTorch, 可以跳过该部分，直接到[下一小节](##安装)。否则，您可以按照以下步骤操作。 -注意: 如果您已经安装好 mmcv， 您首先需要运行 `pip uninstall mmcv`。 -如果 mmcv 和 mmcv-full 同时被安装，会报错 `ModuleNotFoundError`。 +**步骤 0.** 从[官方网站](https://docs.conda.io/en/latest/miniconda.html)下载并安装 Miniconda + +**步骤 1.** 创建一个 conda 环境，并激活 + +```shell +conda create --name openmmlab python=3.8 -y +conda activate openmmlab +``` + +**Step 2.** 参考 [official instructions](https://pytorch.org/get-started/locally/) 安装 PyTorch + +在 GPU 平台上： + +```shell +conda install pytorch torchvision -c pytorch +``` + +在 CPU 平台上 + +```shell +conda install pytorch torchvision cpuonly -c pytorch +``` ## 安装 -a. 创建一个 conda 虚拟环境并激活它 +我们建议用户遵循我们的最佳实践来安装 MMSegmentation 。但是整个过程是高度自定义的。更多信息请参见[自定义安装](#自定义安装)部分。 + +### 最佳实践 + +**步骤 0.** 使用 [MIM](https://github.com/open-mmlab/mim) 安装 [MMCV](https://github.com/open-mmlab/mmcv) ```shell -conda create -n open-mmlab python=3.10 -y -conda activate open-mmlab - +pip install -U openmim +mim install mmengine +mim install "mmcv>=2.0.0rc1" ``` -b. 按照[官方教程](https://pytorch.org/) 安装 PyTorch 和 totchvision， -这里我们使用 PyTorch1.11.0 和 CUDA11.3， -您也可以切换至其他版本 +**步骤 1.** 安装 MMSegmentation + +情况 a: 如果您想立刻开发和运行 mmsegmentation，您可通过源码安装： ```shell -conda install pytorch=1.11.0 torchvision cudatoolkit=11.3 -c pytorch -``` - -c. 按照 [官方教程](https://mmcv.readthedocs.io/en/latest/#installation) -安装 [MMCV](https://mmcv.readthedocs.io/en/latest/) ， -`mmcv` 或 `mmcv-full` 和 MMSegmentation 均兼容，但对于 CCNet 和 PSANet，`mmcv-full` 里的 CUDA 运算是必须的 - -**在 Linux 下安装 mmcv：** - -为了安装 MMCV, 我们推荐使用下面的这种预编译好的 MMCV. - -```shell -pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html -``` - -请替换 url 里面的 `{cu_version}` 和 `{torch_version}` 为您想要使用的版本. mmcv-full 仅在 -PyTorch 1.x.0 上面编译, 因为在 1.x.0 和 1.x.1 之间通常是兼容的. 如果您的 PyTorch 版本是 1.x.1, -您可以安装用 PyTorch 1.x.0 编译的 mmcv-full 而它通常是可以正常使用的. -例如, 用 `CUDA 11.1` and `PyTorch 1.11.0` 安装使用 `mmcv-full`, 使用如下命令: - -```shell -pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.11/index.html -``` - -请查看 [这里](https://github.com/open-mmlab/mmcv#installation) 来找到适配不同 PyTorch 和 CUDA 版本的 MMCV. - -您也可以采用下面的命令来从源码编译 MMCV (可选) - -```shell -git clone https://github.com/open-mmlab/mmcv.git -cd mmcv -MMCV_WITH_OPS=1 pip install -e . # package mmcv-full, which contains cuda ops, will be installed after this step -# OR pip install -e . # package mmcv, which contains no cuda ops, will be installed after this step -cd .. -``` - -**重点:** 如果您已经安装了 MMCV, 您需要先运行 `pip uninstall mmcv`. 因为如果 `mmcv` 和 `mmcv-full` 被同时安装, 将会报错 `ModuleNotFoundError`. - -**在 Windows 下安装 mmcv (有风险)：** - -对于 Windows， MMCV 的安装需要本地 C++ 编译工具， 例如 cl.exe。 请添加编译工具至 %PATH%。 - -如果您已经在电脑上安装好Windows SDK 和 Visual Studio，cl.exe 的一个典型路径看起来如下： - -```shell -C:\Program Files (x86)\Microsoft Visual Studio\2019\Professional\VC\Tools\MSVC\14.26.28801\bin\Hostx86\x64 -``` - -或者您需要从网上下载 cl 编译工具并安装至路径。 - -随后，从 github 克隆 mmcv 并通过 pip 安装： - -```shell -git clone https://github.com/open-mmlab/mmcv.git -cd mmcv -pip install -e . -``` - -或直接: - -```shell -pip install mmcv -``` - -当前，mmcv-full 并不完全在 windows 上支持。 - -d. 安装 MMSegmentation - -```shell -pip install mmsegmentation # 安装最新版本 -``` - -或者 - -```shell -pip install git+https://github.com/open-mmlab/mmsegmentation.git # 安装 master 分支 -``` - -此外，如果您想安装 `dev` 模式的 MMSegmentation, 运行如下命令： - -```shell -git clone https://github.com/open-mmlab/mmsegmentation.git +git clone -b dev-1.x https://github.com/open-mmlab/mmsegmentation.git cd mmsegmentation -pip install -e . # 或者 "python setup.py develop" +pip install -v -e . +# '-v' 表示详细模式，更多的输出 +# '-e' 表示以可编辑模式安装工程， +# 因此对代码所做的任何修改都生效，无需重新安装 ``` -注意: - -1. 当在 windows 下训练和测试模型时，请确保路径下所有的'\\' 被替换成 '/'， - 在 python 代码里可以使用`.replace('\\', '/')`处理路径的字符串 -2. `version+git_hash` 也将被保存进 meta 训练模型里，即0.5.0+c415a2e -3. 当 MMsegmentation 以 `dev` 模式被安装时，本地对代码的修改将不需要重新安装即可产生作用 -4. 如果您想使用 `opencv-python-headless` 替换 `opencv-python`，您可以在安装 MMCV 前安装它 -5. 一些依赖项是可选的。简单的运行 `pip install -e .` 将仅安装最必要的一些依赖。为了使用可选的依赖项如`cityscapessripts`， - 要么手动使用 `pip install -r requirements/optional.txt` 安装，要么专门从pip下安装(即 `pip install -e .[optional]`， - 其中选项可设置为 `all`, `tests`, `build`, 和 `optional`) - -### 完整的安装脚本 - -#### Linux - -这里便是一个完整安装 MMSegmentation 的脚本，使用 conda 并链接了数据集的路径（以您的数据集路径为 $DATA_ROOT 来安装）。 +情况 b: 如果您把 mmsegmentation 作为依赖库或者第三方库，可以通过 pip 安装： ```shell -conda create -n open-mmlab python=3.10 -y -conda activate open-mmlab - -conda install pytorch=1.11.0 torchvision cudatoolkit=11.3 -c pytorch -pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.11.0/index.html -git clone https://github.com/open-mmlab/mmsegmentation.git -cd mmsegmentation -pip install -e . # 或者 "python setup.py develop" - -mkdir data -ln -s $DATA_ROOT data +pip install "mmsegmentation>=1.0.0rc0" ``` -#### Windows (有风险) +### 验证是否安装成功 -这里便是一个完整安装 MMSegmentation 的脚本，使用 conda 并链接了数据集的路径（以您的数据集路径为 %DATA_ROOT% 来安装）。 -注意：它必须是一个绝对路径。 +为了验证 MMSegmentation 是否正确安装，我们提供了一些示例代码来运行一个推理 demo 。 + +**步骤 1.** 下载配置文件和模型文件 ```shell -conda create -n open-mmlab python=3.10 -y -conda activate open-mmlab - -conda install pytorch=1.11.0 torchvision cudatoolkit=11.3 -c pytorch -set PATH=full\path\to\your\cpp\compiler;%PATH% -pip install mmcv - -git clone https://github.com/open-mmlab/mmsegmentation.git -cd mmsegmentation -pip install -e . # 或者 "python setup.py develop" - -mklink /D data %DATA_ROOT% +mim download mmsegmentation --config pspnet_r50-d8_4xb2-40k_cityscapes-512x1024 --dest . ``` -#### 使用多版本 MMSegmentation 进行开发 +该下载过程可能需要花费几分钟，这取决于您的网络环境。当下载结束，您将看到以下两个文件在您当前工作目录：`pspnet_r50-d8_4xb2-40k_cityscapes-512x1024.py` 和 `pspnet_r50-d8_512x1024_40k_cityscapes_20200605_003338-2966598c.pth` -训练和测试脚本已经修改了 `PYTHONPATH` 来确保使用当前路径的MMSegmentation。 +**步骤 2.** 验证推理 demo -为了使用当前环境默认安装的 MMSegmentation 而不是正在工作的 MMSegmentation，您可以在那些脚本里移除下面的内容： +选项 (a). 如果您通过源码安装了 mmsegmentation，运行以下命令即可： ```shell -PYTHONPATH="$(dirname $0)/..":$PYTHONPATH +python demo/image_demo.py demo/demo.png configs/pspnet/pspnet_r50-d8_4xb2-40k_cityscapes-512x1024.py pspnet_r50-d8_512x1024_40k_cityscapes_20200605_003338-2966598c.pth --device cuda:0 --out-file result.jpg ``` -## 验证 +您将在当前文件夹中看到一个新图像 `result.jpg`，其中所有目标都覆盖了分割 mask -为了验证 MMSegmentation 和它所需要的环境是否正确安装，我们可以使用样例 python 代码来初始化一个 segmentor 并推理一张 demo 图像。 +选项 (b). 如果您通过 pip 安装 mmsegmentation, 打开您的 python +解释器，复制粘贴以下代码： ```python -from mmseg.apis import inference_model, init_model +from mmseg.apis import inference_model, init_model, show_result_pyplot +from mmseg.utils import register_all_modules import mmcv -config_file = 'configs/pspnet/pspnet_r50-d8_512x1024_40k_cityscapes.py' -checkpoint_file = 'checkpoints/pspnet_r50-d8_512x1024_40k_cityscapes_20200605_003338-2966598c.pth' +register_all_modules() +config_file = 'pspnet_r50-d8_4xb2-40k_cityscapes-512x1024.py' +checkpoint_file = 'pspnet_r50-d8_512x1024_40k_cityscapes_20200605_003338-2966598c.pth' -# 从一个 config 配置文件和 checkpoint 文件里创建分割模型 +# 根据配置文件和模型文件建立模型 model = init_model(config_file, checkpoint_file, device='cuda:0') -# 测试一张样例图片并得到结果 -img = 'test.jpg' # 或者 img = mmcv.imread(img), 这将只加载图像一次． +# 在单张图像上测试并可视化 +img = 'demo/demo.png' # or img = mmcv.imread(img), 这样仅需下载一次 result = inference_model(model, img) -# 在新的窗口里可视化结果 -model.show_result(img, result, show=True) -# 或者保存图片文件的可视化结果 -# 您可以改变 segmentation map 的不透明度(opacity)，在(0, 1]之间。 -model.show_result(img, result, out_file='result.jpg', opacity=0.5) - -# 测试一个视频并得到分割结果 +# 在新的窗口可视化结果 +show_result_pyplot(model, img, result, show=True) +# 或者将可视化结果保存到图像文件夹中 +# 您可以修改分割 map 的透明度 (0, 1]. +show_result_pyplot(model, img, result, show=True, out_file='result.jpg', opacity=0.5) +# 在一段视频上测试并可视化分割结果 video = mmcv.VideoReader('video.mp4') for frame in video: - result = inference_model(model, frame) - model.show_result(frame, result, wait_time=1) + result = inference_segmentor(model, frame) + show_result_pyplot(model, result, wait_time=1) ``` -当您完成 MMSegmentation 的安装时，上述代码应该可以成功运行。 +您可以修改上面的代码来测试单个图像或视频，这两个选项都可以验证安装是否成功。 -我们还提供一个 demo 脚本去可视化单张图片。 +### 自定义安装 + +#### CUDA 版本 + +当安装 PyTorch 的时候，您需要指定 CUDA 的版本， 如果您不确定选择哪个版本，请遵循我们的建议： + +- 对于基于 Ampere 的 NVIDIA GPUs, 例如 GeForce 30 系列和 NVIDIA A100, 必须要求是 CUDA 11. +- 对于更老的 NVIDIA GPUs, CUDA 11 is backward compatible, but CUDA 10.2 提供了更好的兼容性，以及更加的轻量化 + +请确保 GPU 驱动满足最小的版本需求。详情请参考这个[表格](https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html#cuda-major-component-versions__table-cuda-toolkit-driver-versions) + +**注意:** +如果您按照我们的最佳实践，安装 CUDA 运行库就足够了，因为不需要 CUDA 代码在本地编译。 但是如果您希望从源码编译 MMCV 或者需要开发其他的 CUDA 算子，您需要从 NVIDIA 的[官网](https://developer.nvidia.com/cuda-downloads)安装完整的 CUDA 工具，同时它的版本需要与 PyTorch 的 CUDA 版本匹配。即 `conda install` 命令中指定的 cudatoolkit 版本。 + +#### 不使用 MIM 安装 MMCV + +MMCV 包含 C++ 和 CUDA 扩展，因此与 PyTorch 的依赖方式比较复杂。MIM 自动解决了这种依赖关系，使安装更容易。然而，MIM 也并不是必须的。 + +为了使用 pip 而不是 MIM 安装 MMCV, 请参考 [MMCV 安装指南](https://mmcv.readthedocs.io/en/latest/get_started/installation.html). 这需要手动指定一个基于 PyTorch 版本及其 CUDA 版本的 find-url. + +例如，以下命令可为 PyTorch 1.10.x and CUDA 11.3 安装 mmcv==2.0.0rc1 ```shell -python demo/image_demo.py ${IMAGE_FILE} ${CONFIG_FILE} ${CHECKPOINT_FILE} [--device ${DEVICE_NAME}] [--palette-thr ${PALETTE}] +pip install mmcv==2.0.0rc1 -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10/index.html ``` -样例： +#### 在仅有 CPU 的平台安装 + +MMSegmentation 可以在仅有 CPU 的版本上运行。在 CPU 模式，您可以训练（需要 MMCV-Lite 版本 >= 2.0.0rc0），测试和推理模型。 + +#### 在 Google Colab 上安装 + +[Google Colab](https://research.google.com/) 通常已经安装了 PyTorch，因此我们仅需要通过以下命令安装 MMCV 和 MMSegmentation。 + +**步骤 1.** 使用 [MIM](https://github.com/open-mmlab/mim) 安装 [MMCV](https://github.com/open-mmlab/mmcv) ```shell -python demo/image_demo.py demo/demo.jpg configs/pspnet/pspnet_r50-d8_512x1024_40k_cityscapes.py \ - checkpoints/pspnet_r50-d8_512x1024_40k_cityscapes_20200605_003338-2966598c.pth --device cuda:0 --palette cityscapes +!pip3 install openmim +!mim install mmengine +!mim install "mmcv>=2.0.0rc1" ``` -推理的 demo 文档可在此查询：[demo/inference_demo.ipynb](../demo/inference_demo.ipynb) 。 +**Step 2.** 通过源码安装 MMSegmentation + +```shell +!git clone https://github.com/open-mmlab/mmsegmentation.git +%cd mmsegmentation +!git checkout dev-1.x +!pip install -e . +``` + +**Step 3.** 验证 + +```python +import mmseg +print(mmseg.__version__) +# 示例输出: 1.0.0rc0 +``` + +**注意:** +在 Jupyter 中, 感叹号 `!` 用于调用外部可执行命令，`%cd` 是一个 [magic command](https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-cd) 可以改变当前 python 的工作目录。 + +### 通过 Docker 使用 MMSegmentation + +我们提供了一个 [Dockerfile](https://github.com/open-mmlab/mmsegmentation/blob/master/docker/Dockerfile) 来建立映像。确保您的 [docker 版本](https://docs.docker.com/engine/install/) >=19.03. + +```shell +# 通过 PyTorch 1.11, CUDA 11.3 建立映像 +# 如果您使用其他版本，修改 Dockerfile 即可 +docker build -t mmsegmentation docker/ +``` + +运行： + +```shell +docker run --gpus all --shm-size=8g -it -v {DATA_DIR}:/mmsegmentation/data mmsegmentation +``` + +## 问题解答 + +如果您在安装过程中遇到了其他问题，请第一时间查阅 [FAQ](faq.md) 文件。如果没有找到答案，您也可以在 GitHub 上提出 [issue](https://github.com/open-mmlab/mmsegmentation/issues/new/choose)