[Docs] Update install tutorial. (#1223)
* [Docs] Update install tutorial. * Update collapsed sections. * Update requirements * Update install tutorial.pull/1248/head
Ma Zerun
GitHub
parent
f9be21ab74
commit
a4ec2799d6
docs
en
_static/js
zh_CN
_static/js
requirements
|
|
@ -1,4 +1,4 @@
|
|||
var collapsedSections = ['Model zoo'];
|
||||
var collapsedSections = ['Useful Tools', 'Advanced Guids', 'Model zoo', 'Notes'];
|
||||
|
||||
$(document).ready(function () {
|
||||
$('.model-summary').DataTable({
|
||||
|
|
|
|||
|
|
@ -37,19 +37,8 @@ conda install pytorch torchvision cpuonly -c pytorch
|
|||
|
||||
# Installation
|
||||
|
||||
We recommend that users follow our best practices to install MMClassification. However, the whole process is highly customizable. See [Customize Installation](#customize-installation) section for more information.
|
||||
|
||||
## Best Practices
|
||||
|
||||
**Step 1.** Install [MMEngine](https://github.com/open-mmlab/mmengine) and [MMCV](https://github.com/open-mmlab/mmcv) using [MIM](https://github.com/open-mmlab/mim).
|
||||
|
||||
```shell
|
||||
pip install -U openmim
|
||||
mim install mmengine "mmcv>=2.0.0rc1"
|
||||
```
|
||||
|
||||
**Step 2.** Install MMClassification.
|
||||
|
||||
According to your needs, we support two install modes:
|
||||
|
||||
- [Install from source (Recommended)](#install-from-source): You want to develop your own image classification task or new features based on MMClassification framework. For example, adding new dataset or new models. And you can use all tools we provided.
|
||||
|
|
@ -60,27 +49,25 @@ According to your needs, we support two install modes:
|
|||
In this case, install mmcls from source:
|
||||
|
||||
```shell
|
||||
git clone https://github.com/open-mmlab/mmclassification.git
|
||||
git clone -b 1.x https://github.com/open-mmlab/mmclassification.git
|
||||
cd mmclassification
|
||||
git checkout 1.x
|
||||
pip install -v -e .
|
||||
# "-v" means verbose, or more output
|
||||
# "-e" means installing a project in editable mode,
|
||||
# thus any local modifications made to the code will take effect without reinstallation.
|
||||
pip install -U openmim && mim install -e .
|
||||
```
|
||||
|
||||
Optionally, if you want to contribute to MMClassification or experience experimental functions, please checkout to the `dev-1.x` branch:
|
||||
|
||||
```shell
|
||||
git checkout dev-1.x
|
||||
```{note}
|
||||
`"-e"` means installing a project in editable mode, thus any local modifications made to the code will take effect without reinstallation.
|
||||
```
|
||||
|
||||
### Install as a Python package
|
||||
|
||||
Just install with pip.
|
||||
Just install with mim.
|
||||
|
||||
```shell
|
||||
pip install "mmcls>=1.0.0rc0"
|
||||
pip install -U openmim && mim install "mmcls>=1.0.0rc0"
|
||||
```
|
||||
|
||||
```{note}
|
||||
`mim` is a light-weight command-line tool to setup appropriate environment for OpenMMLab repositories according to PyTorch and CUDA version. It also has some useful functions for deep-learning experiments.
|
||||
```
|
||||
|
||||
## Verify the installation
|
||||
|
|
@ -139,65 +126,17 @@ and its version should match the CUDA version of PyTorch. i.e., the specified
|
|||
version of cudatoolkit in `conda install` command.
|
||||
```
|
||||
|
||||
### Install MMCV without MIM
|
||||
|
||||
MMCV contains C++ and CUDA extensions, thus depending on PyTorch in a complex
|
||||
way. MIM solves such dependencies automatically and makes the installation
|
||||
easier. However, it is not a must.
|
||||
|
||||
To install MMCV with pip instead of MIM, please follow {external+mmcv:doc}`MMCV installation guides <get_started/installation>`.
|
||||
This requires manually specifying a find-url based on PyTorch version and its CUDA version.
|
||||
|
||||
For example, the following command install mmcv built for PyTorch 1.10.x and CUDA 11.3.
|
||||
|
||||
```shell
|
||||
pip install "mmcv>=2.0.0rc1" -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10/index.html
|
||||
```
|
||||
|
||||
### Install on CPU-only platforms
|
||||
|
||||
MMClassification can be built for CPU only environment. In CPU mode you can train, test or inference a model.
|
||||
|
||||
Some functionalities are gone in this mode, usually GPU-compiled ops. But don't
|
||||
worry, almost all models in MMClassification don't depends on these ops.
|
||||
|
||||
### Install on Google Colab
|
||||
|
||||
[Google Colab](https://research.google.com/) usually has PyTorch installed,
|
||||
thus we only need to install MMCV and MMClassification with the following
|
||||
commands.
|
||||
|
||||
**Step 1.** Install [MMEngine](https://github.com/open-mmlab/mmengine) and [MMCV](https://github.com/open-mmlab/mmcv) using [MIM](https://github.com/open-mmlab/mim).
|
||||
|
||||
```shell
|
||||
!pip3 install openmim
|
||||
!mim install mmengine "mmcv>=2.0.0rc1"
|
||||
```
|
||||
|
||||
**Step 2.** Install MMClassification from the source.
|
||||
|
||||
```shell
|
||||
!git clone https://github.com/open-mmlab/mmclassification.git
|
||||
%cd mmclassification
|
||||
!git checkout 1.x
|
||||
!pip install -e .
|
||||
```
|
||||
|
||||
**Step 3.** Verification.
|
||||
|
||||
```python
|
||||
import mmcls
|
||||
print(mmcls.__version__)
|
||||
# Example output: 1.0.0rc0 or newer
|
||||
```
|
||||
|
||||
```{note}
|
||||
Within Jupyter, the exclamation mark `!` is used to call external executables and `%cd` is a [magic command](https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-cd) to change the current working directory of Python.
|
||||
```
|
||||
See [the Colab tutorial](https://colab.research.google.com/github/mzr1996/mmclassification-tutorial/blob/master/1.x/MMClassification_tools.ipynb).
|
||||
|
||||
### Using MMClassification with Docker
|
||||
|
||||
We provide a [Dockerfile](https://github.com/open-mmlab/mmclassification/blob/master/docker/Dockerfile)
|
||||
We provide a [Dockerfile](https://github.com/open-mmlab/mmclassification/blob/1.x/docker/Dockerfile)
|
||||
to build an image. Ensure that your [docker version](https://docs.docker.com/engine/install/) >=19.03.
|
||||
|
||||
```shell
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
var collapsedSections = ['Model zoo'];
|
||||
var collapsedSections = ['实用工具', '进阶教程', '模型库', '其他说明'];
|
||||
|
||||
$(document).ready(function () {
|
||||
$('.model-summary').DataTable({
|
||||
|
|
|
|||
|
|
@ -43,15 +43,6 @@ conda install pytorch torchvision cpuonly -c pytorch
|
|||
|
||||
## 最佳实践
|
||||
|
||||
**第 1 步** 使用 [MIM](https://github.com/open-mmlab/mim) 安装 [MMEngine](https://github.com/open-mmlab/mmengine) 和 [MMCV](https://github.com/open-mmlab/mmcv)
|
||||
|
||||
```shell
|
||||
pip install -U openmim
|
||||
mim install mmengine "mmcv>=2.0rc0"
|
||||
```
|
||||
|
||||
**第 2 步** 安装 MMClassification
|
||||
|
||||
根据具体需求，我们支持两种安装模式：
|
||||
|
||||
- [从源码安装（推荐）](#从源码安装)：希望基于 MMClassification 框架开发自己的图像分类任务，需要添加新的功能，比如新的模型或是数据集，或者使用我们提供的各种工具。
|
||||
|
|
@ -62,26 +53,25 @@ mim install mmengine "mmcv>=2.0rc0"
|
|||
这种情况下，从源码按如下方式安装 mmcls：
|
||||
|
||||
```shell
|
||||
git clone https://github.com/open-mmlab/mmclassification.git
|
||||
git clone -b 1.x https://github.com/open-mmlab/mmclassification.git
|
||||
cd mmclassification
|
||||
git checkout 1.x
|
||||
pip install -v -e .
|
||||
# "-v" 表示输出更多安装相关的信息
|
||||
# "-e" 表示以可编辑形式安装，这样可以在不重新安装的情况下，让本地修改直接生效
|
||||
pip install -U openmim && mim install -e .
|
||||
```
|
||||
|
||||
另外，如果你希望向 MMClassification 贡献代码，或者使用试验中的功能，请签出到 `dev-1.x` 分支。
|
||||
|
||||
```shell
|
||||
git checkout dev-1.x
|
||||
```{note}
|
||||
`"-e"` 表示以可编辑形式安装，这样可以在不重新安装的情况下，让本地修改直接生效
|
||||
```
|
||||
|
||||
### 作为 Python 包安装
|
||||
|
||||
直接使用 pip 安装即可。
|
||||
直接使用 mim 安装即可。
|
||||
|
||||
```shell
|
||||
pip install "mmcls>=1.0rc0"
|
||||
pip install -U openmim && mim install "mmcls>=1.0rc0"
|
||||
```
|
||||
|
||||
```{note}
|
||||
`mim` 是一个轻量级的命令行工具，可以根据 PyTorch 和 CUDA 版本为 OpenMMLab 算法库配置合适的环境。同时它也提供了一些对于深度学习实验很有帮助的功能。
|
||||
```
|
||||
|
||||
## 验证安装
|
||||
|
|
@ -137,58 +127,13 @@ inference_model(model, 'demo/demo.JPEG')
|
|||
的配置相匹配（如用 `conda install` 安装 PyTorch 时指定的 cudatoolkit 版本）。
|
||||
```
|
||||
|
||||
### 不使用 MIM 安装 MMCV
|
||||
|
||||
MMCV 包含 C++ 和 CUDA 扩展，因此其对 PyTorch 的依赖比较复杂。MIM 会自动解析这些
|
||||
依赖，选择合适的 MMCV 预编译包，使安装更简单，但它并不是必需的。
|
||||
|
||||
要使用 pip 而不是 MIM 来安装 MMCV，请遵照 [MMCV 安装指南](https://mmcv.readthedocs.io/zh_CN/latest/get_started/installation.html)。
|
||||
它需要你用指定 url 的形式手动指定对应的 PyTorch 和 CUDA 版本。
|
||||
|
||||
举个例子，如下命令将会安装基于 PyTorch 1.10.x 和 CUDA 11.3 编译的 mmcv。
|
||||
|
||||
```shell
|
||||
pip install "mmcv>=2.0rc0" -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10/index.html
|
||||
```
|
||||
|
||||
### 在 CPU 环境中安装
|
||||
|
||||
MMClassification 可以仅在 CPU 环境中安装，在 CPU 模式下，你可以完成训练、测试和模型推理等所有操作。
|
||||
|
||||
在 CPU 模式下，MMCV 的部分功能将不可用，通常是一些 GPU 编译的算子。不过不用担心，
|
||||
MMClassification 中几乎所有的模型都不会依赖这些算子。
|
||||
|
||||
### 在 Google Colab 中安装
|
||||
|
||||
[Google Colab](https://research.google.com/) 通常已经包含了 PyTorch 环境，因此我们只需要安装 MMCV 和 MMClassification 即可，命令如下：
|
||||
|
||||
**第 1 步** 使用 [MIM](https://github.com/open-mmlab/mim) 安装 [MMEngine](https://github.com/open-mmlab/mmengine) 和 [MMCV](https://github.com/open-mmlab/mmcv)
|
||||
|
||||
```shell
|
||||
!pip3 install openmim
|
||||
!mim install mmengine "mmcv>=2.0rc0"
|
||||
```
|
||||
|
||||
**第 2 步** 从源码安装 MMClassification
|
||||
|
||||
```shell
|
||||
!git clone https://github.com/open-mmlab/mmclassification.git
|
||||
%cd mmclassification
|
||||
!git checkout 1.x
|
||||
!pip install -e .
|
||||
```
|
||||
|
||||
**第 3 步** 验证
|
||||
|
||||
```python
|
||||
import mmcls
|
||||
print(mmcls.__version__)
|
||||
# 预期输出： 1.0.0rc0 或更新的版本号
|
||||
```
|
||||
|
||||
```{note}
|
||||
在 Jupyter 中，感叹号 `!` 用于执行外部命令，而 `%cd` 是一个[魔术命令](https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-cd)，用于切换 Python 的工作路径。
|
||||
```
|
||||
参考 [Colab 教程](https://colab.research.google.com/github/mzr1996/mmclassification-tutorial/blob/master/1.x/MMClassification_tools.ipynb) 安装即可。
|
||||
|
||||
### 通过 Docker 使用 MMClassification
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
docutils==0.17.1
|
||||
modelindex
|
||||
myst-parser
|
||||
git+https://github.com/open-mmlab/pytorch_sphinx_theme.git#egg=pytorch_sphinx_theme
|
||||
git+https://github.com/mzr1996/pytorch_sphinx_theme.git#egg=pytorch_sphinx_theme
|
||||
sphinx==4.5.0
|
||||
sphinx-copybutton
|
||||
sphinx-notfound-page
|
||||
|
|
|
|||
Loading…
Reference in New Issue