Update Chinese documents (#3243)

docs/zh_CN/TrainingService/LocalMode.rst

+**教程：使用 NNI API 在本地创建和运行 Experiment**
+====================================================================
+
+本教程会使用 [~/examples/trials/mnist-tfv1] 示例来解释如何在本地使用 NNI API 来创建并运行 Experiment。
+
+..
+
+   在开始前
+
+
+要有一个使用卷积层对 MNIST 分类的代码，如 ``mnist_before.py``。
+
+..
+
+   第一步：更新模型代码
+
+
+对代码进行以下改动来启用 NNI API：
+
+* 声明 NNI API 在 Trial 代码中通过 ``import nni`` 来导入 NNI API。
+* 获取预定义参数
+
+使用一下代码段：
+
+.. code-block:: python
+
+   RECEIVED_PARAMS = nni.get_next_parameter()
+
+获得 tuner 分配的超参数值。 ``RECEIVED_PARAMS`` 是一个对象，如：
+
+.. code-block:: json
+
+   {"conv_size": 2, "hidden_size": 124, "learning_rate": 0.0307, "dropout_rate": 0.2029}
+
+* 导出 NNI results API：``nni.report_intermediate_result(accuracy)`` 发送 ``accuracy`` 给 assessor。
+  使用 API: ``nni.report_final_result(accuracy)`` 返回 ``accuracy`` 的值给 Tuner。
+
+将改动保存到 ``mnist.py`` 文件中。
+
+**注意**：
+
+.. code-block:: bash
+
+   accuracy - 如果使用内置的 Tuner/Assessor，那么 `accuracy` 必须是数值（如 float, int）。在定制 Tuner/Assessor 时 `accuracy` 可以是任何类型的 Python 对象。  
+   Assessor（评估器）- 会根据 Trial 的历史值（即其中间结果），来决定这次 Trial 是否应该提前终止。
+   Tuner（调参器） - 会根据探索的历史（所有 Trial 的最终结果）来生成下一组参数、架构。
+
+..
+
+   第二步：定义搜索空间
+
+
+在 ``Step 1.2 获取预定义的参数`` 中使用的超参定义在 ``search_space.json`` 文件中：
+
+.. code-block:: bash
+
+   {
+       "dropout_rate":{"_type":"uniform","_value":[0.1,0.5]},
+       "conv_size":{"_type":"choice","_value":[2,3,5,7]},
+       "hidden_size":{"_type":"choice","_value":[124, 512, 1024]},
+       "learning_rate":{"_type":"uniform","_value":[0.0001, 0.1]}
+   }
+
+参考 `define search space <../Tutorial/SearchSpaceSpec.rst>`__ 进一步了解搜索空间。
+
+..
+
+   第三步：定义 Experiment
+
+   ..
+
+      3.1 启用 NNI API 模式
+
+
+要启用 NNI 的 API 模式，需要将 useAnnotation 设置为 *false*，并提供搜索空间文件的路径（即第一步中定义的文件）：
+
+.. code-block:: bash
+
+   useAnnotation: false
+   searchSpacePath: /path/to/your/search_space.json
+
+在 NNI 中运行 Experiment，只需要：
+
+
+* 可运行的 Trial 的代码
+* 实现或选择 Tuner
+* 准备 YAML 的 Experiment 配置文件
+* （可选）实现或选择 Assessor
+
+**准备 trial**\ :
+
+..
+
+   在克隆代码后，可以在 ~/nni/examples 中找到一些示例，运行 ``ls examples/trials`` 查看所有 Trial 示例。
+
+
+以一个简单的 trial 来举例。 NNI 提供了 mnist 样例。 安装 NNI 之后，NNI 的样例已经在目录 ~/nni/examples下，运行 ``ls ~/nni/examples/trials`` 可以看到所有的 examples。 执行下面的命令可轻松运行 NNI 的 mnist 样例：
+
+.. code-block:: bash
+
+     python ~/nni/examples/trials/mnist-annotation/mnist.py
+
+
+上面的命令会写在 YAML 文件中。 参考 `这里 <../TrialExample/Trials.rst>`__ 来写出自己的 Experiment 代码。
+
+**准备 Tuner**： NNI 支持多种流行的自动机器学习算法，包括：Random Search（随机搜索），Tree of Parzen Estimators (TPE)，Evolution（进化算法）等等。 也可以实现自己的 Tuner（参考 `这里 <../Tuner/CustomizeTuner.rst>`__）。下面使用了 NNI 内置的 Tuner：
+
+.. code-block:: bash
+
+     tuner:
+       builtinTunerName: TPE
+       classArgs:
+         optimize_mode: maximize
+
+
+*builtinTunerName* 用来指定 NNI 中的 Tuner，*classArgs* 是传入到 Tuner 的参数（内置 Tuner 在 `这里 <../Tuner/BuiltinTuner.rst>`__\ ），*optimization_mode* 表明需要最大化还是最小化 Trial 的结果。
+
+**准备配置文件**\：实现 Trial 的代码，并选择或实现自定义的 Tuner 后，就要准备 YAML 配置文件了。 NNI 为每个 Trial 示例都提供了演示的配置文件，用命令 ``cat ~/nni/examples/trials/mnist-annotation/config.yml`` 来查看其内容。 大致内容如下：
+
+.. code-block:: yaml
+
+   authorName: your_name
+   experimentName: auto_mnist
+
+   # 同时运行的 trial 数量
+   trialConcurrency: 1
+
+   # 实验最大运行时长
+   maxExecDuration: 3h
+
+   # 此项设置为 empty 意为无限大
+   maxTrialNum: 100
+
+   # choice: local, remote
+   trainingServicePlatform: local
+
+   # search space file
+   searchSpacePath: search_space.json
+
+   # choice: true, false
+   useAnnotation: true
+   tuner:
+     builtinTunerName: TPE
+     classArgs:
+       optimize_mode: maximize
+   trial:
+     command: python mnist.py
+     codeDir: ~/nni/examples/trials/mnist-annotation
+     gpuNum: 0
+
+因为这个 Trial 代码使用了 NNI Annotation 的方法（参考 `这里 <../Tutorial/AnnotationSpec.rst>`__ ），所以 *useAnnotation* 为 true。 *command* 是运行 Trial 代码所需要的命令，*codeDir* 是 Trial 代码的相对位置。 命令会在此目录中执行。 同时，也需要提供每个 Trial 进程所需的 GPU 数量。
+
+完成上述步骤后，可通过下列命令来启动 Experiment：
+
+.. code-block:: bash
+
+     nnictl create --config ~/nni/examples/trials/mnist-annotation/config.yml
+
+
+参考 `这里 <../Tutorial/Nnictl.rst>`__ 来了解 *nnictl* 命令行工具的更多用法。
+
+查看 Experiment 结果
+-----------------------
+
+Experiment 应该一直在运行。 除了 *nnictl* 以外，还可以通过 NNI 的网页来查看 Experiment 进程，进行控制和其它一些有意思的功能。
+
+使用多个本地 GPU 加快搜索速度
+--------------------------------------------
+
+以下步骤假定在本地安装了4个 NVIDIA GPU，并且 `具有 GPU 支持的 tensorflow <https://www.tensorflow.org/install/gpu>`__。 演示启用了 4 个并发的 Trial 任务，每个 Trial 任务使用了 1 块 GPU。
+
+**准备配置文件**：NNI 提供了演示用的配置文件，使用 ``cat examples/trials/mnist-annotation/config_gpu.yml`` 来查看。 trailConcurrency 和 gpuNum 与基本配置文件不同：
+
+.. code-block:: bash
+
+   ...
+
+   # how many trials could be concurrently running
+   trialConcurrency: 4
+
+   ...
+
+   trial:
+     command: python mnist.py
+     codeDir: ~/nni/examples/trials/mnist-annotation
+     gpuNum: 1
+
+用下列命令运行 Experiment：
+
+.. code-block:: bash
+
+     nnictl create --config ~/nni/examples/trials/mnist-annotation/config_gpu.yml
+
+
+可以用 *nnictl* 命令行工具或网页界面来跟踪训练过程。 *nvidia_smi* 命令行工具能在训练过程中查看 GPU 使用情况。

docs/zh_CN/TrainingService/Overview.md

-# 训练平台
-
-## 什么是训练平台？
-
-NNI 训练平台让用户专注于 AutoML 任务，不需要关心 Trial 实际运行的计算基础架构平台。 当从一个集群迁移到另一个集群时 (如，从本机迁移到 Kubeflow)，用户只需要调整几项配置，能很容易的扩展计算资源。
-
-NNI 提供的训练平台包括：[本机](./LocalMode.md), [远程计算机](./RemoteMachineMode.md), 以及集群类的 [OpenPAI](./PaiMode.md), [Kubeflow](./KubeflowMode.md), [FrameworkController](./FrameworkControllerMode.md), [DLTS](./DLTSMode.md) 和 [AML](./AMLMode.md).。 这些都是*内置的训练平台*。
-
-如果需要在计算资源上使用 NNI，可以根据相关接口，轻松构建对其它训练平台的支持。 参考 "[如何实现训练平台](./HowToImplementTrainingService)" 了解详情。
-
-## 如何使用训练平台？
-
-在 Experiment 的 YAML 配置文件中选择并配置好训练平台。 参考相应训练平台的文档来了解如何配置。 同时，[Experiment 文档](../Tutorial/ExperimentConfig)提供了更多详细信息。
-
-然后，需要准备代码目录，将路径填入配置文件的 `codeDir` 字段。 注意，非本机模式下，代码目录会在 Experiment 运行前上传到远程或集群中。 因此，NNI 将文件数量限制到 2000，总大小限制为 300 MB。 如果代码目录中文件太多，可添加 `.nniignore` 文件来排除一部分文件，其用法与 `.gitignore` 类似。 关于如何编写该文件，详见 [此示例](https://github.com/Microsoft/nni/tree/master/examples/trials/mnist-tfv1/.nniignore) 以及 [git 文档](https://git-scm.com/docs/gitignore#_pattern_format).
-
-如果用户需要在 Experiment 使用大文件（如，大规模的数据集），并且不想使用本机模式，可以：1) 在 Trial command 字段中添加命令，每次 Trial 运行前下载数据；或 2) 使用工作节点可访问的共享存储。 通常情况下，训练平台都会有共享存储。 参考每个训练平台的文档，了解详情。
-
-## 内置训练平台
-
-| 训练平台                                                    | 简介                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [__本机__](./LocalMode.md)                                | NNI 支持在本机运行实验，称为 local 模式。 local 模式表示 NNI 会在运行 NNI Manager 进程计算机上运行 Trial 任务，支持 GPU 调度功能。                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| [__远程计算机__](./RemoteMachineMode.md)                     | NNI 支持通过 SSH 通道在多台计算机上运行 Experiment，称为 remote 模式。 NNI 需要这些计算机的访问权限，并假定已配置好了深度学习训练环境。 NNI 将在远程计算机上中提交 Trial 任务，并根据 GPU 资源调度 Trial 任务。                                                                                                                                                                                                                                                                                                                                                                                                   |
-| [__OpenPAI__](./PaiMode.md)                             | NNI 支持在 [OpenPAI](https://github.com/Microsoft/pai) 上运行 Experiment，即 pai 模式。 在使用 NNI 的 pai 模式前, 需要有 [OpenPAI](https://github.com/Microsoft/pai) 群集的账户。 如果没有 OpenPAI，参考[这里](https://github.com/Microsoft/pai#how-to-deploy)来进行部署。 在 pai 模式中，会在 Docker 创建的容器中运行 Trial 程序。                                                                                                                                                                                                                                                                |
-| [__Kubeflow__](./KubeflowMode.md)                       | NNI 支持在 [Kubeflow](https://github.com/kubeflow/kubeflow)上运行，称为 kubeflow 模式。 在开始使用 NNI 的 Kubeflow 模式前，需要有一个 Kubernetes 集群，可以是私有部署的，或者是 [Azure Kubernetes Service(AKS)](https://azure.microsoft.com/zh-cn/services/kubernetes-service/)，并需要一台配置好 [kubeconfig](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) 的 Ubuntu 计算机连接到此 Kubernetes 集群。 如果不熟悉 Kubernetes，可先浏览[这里](https://kubernetes.io/docs/tutorials/kubernetes-basics/)。 在 kubeflow 模式下，每个 Trial 程序会在 Kubernetes 集群中作为一个 Kubeflow 作业来运行。 |
-| [__FrameworkController__](./FrameworkControllerMode.md) | NNI 支持使用 [FrameworkController](https://github.com/Microsoft/frameworkcontroller)，来运行 Experiment，称之为 frameworkcontroller 模式。 FrameworkController 构建于 Kubernetes 上，用于编排各种应用。这样，可以不用为某个深度学习框架安装 Kubeflow 的 tf-operator 或 pytorch-operator 等。 而直接用 FrameworkController 作为 NNI Experiment 的训练平台。                                                                                                                                                                                                                                            |
-| [__DLTS__](./DLTSMode.md)                               | NNI 支持在 [DLTS](https://github.com/microsoft/DLWorkspace.git) 上运行 Experiment，这是一个由微软开源的工具包。                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| [__AML__](./AMLMode.md)                                 | NNI 支持在 [AML](https://azure.microsoft.com/zh-cn/services/machine-learning/) 上运行 Experiment，称为 aml 模式。                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-
-## 训练平台做了什么？
-
-<p align="center">
-<img src="https://user-images.githubusercontent.com/23273522/51816536-ed055580-2301-11e9-8ad8-605a79ee1b9a.png" alt="drawing" width="700"/>
-</p>
-
-根据[概述](../Overview)中展示的架构，训练平台会做三件事：1) 启动 Trial; 2) 收集指标，并与 NNI 核心（NNI 管理器）通信；3) 监控 Trial 任务状态。 为了展示训练平台的详细工作原理，下面介绍了训练平台从最开始到第一个 Trial 运行成功的过程。
-
-步骤 1. **验证配置，并准备训练平台。** 训练平台会首先检查用户配置是否正确（例如，身份验证是否有错）。 然后，训练平台会为 Experiment 做准备，创建训练平台可访问的代码目录（`codeDir`）。
-
-```eval_rst
-.. Note:: 不同的训练平台会有不同的方法来处理 ``codeDir``。 例如，本机训练平台会直接在 ``codeDir`` 中运行 Trial。 远程训练平台会将 ``codeDir`` 打包成 zip 文件，并上传到每台机器中。 基于 Kubernetes 的训练平台会将 ``codeDir`` 复制到共享存储上，此存储可以由训练平台提供，或者用户在配置文件中指定。
-```
-
-步骤 2. **提交第一个 Trial。** 要初始化 Trial，通常（在不重用环境的情况下），NNI 会复制一些文件（包括参数配置，启动脚本等）到训练平台中。 然后，NNI 会通过子进程、SSH、RESTful API 等方式启动 Trial。
-
-```eval_rst
-.. Warning:: Trial 当前目录的内容与 ``codeDir`` 会完全一样，但可能是完全不同的路径（甚至不同的计算机）。本机模式是唯一一个所有 Trial 都使用同一个 ``codeDir`` 的训练平台。 其它训练平台，会将步骤 1 中准备好的 ``codeDir``，从共享目录复制到每个 Trial 自己独立的工作目录下。 强烈建议不要依赖于本机模式下的共享行为，这会让 Experiment 很难扩展到其它训练平台上。
-```
-
-步骤 3. **收集指标。**  NNI 会监控 Trial 的状态，更新状态（如，从 `WAITING` 到 `RUNNING`，`RUNNING` 到 `SUCCEEDED`，并收集指标。 当前，大部分训练平台都实现为 "主动" 模式，即，训练平台会调用 NNI 管理器上的 RESTful API 来更新指标。 注意，这也需要运行 NNI 管理器的计算机能被工作节点访问到。

docs/zh_CN/TrainingService/Overview.rst

+训练平台
+================
+
+什么是训练平台？
+-------------------------
+
+NNI 训练平台让用户专注于 AutoML 任务，不需要关心 Trial 实际运行的计算基础架构平台。 当从一个集群迁移到另一个集群时 (如，从本机迁移到 Kubeflow)，用户只需要调整几项配置，能很容易的扩展计算资源。
+
+用户可以使用 NNI 提供的训练平台来跑 trial, 训练平台有：`local machine <./LocalMode.rst>`__\ ， `remote machines <./RemoteMachineMode.rst>`__\ 以及集群类的 `PAI <./PaiMode.rst>`__\ ，`Kubeflow <./KubeflowMode.rst>`__\ ，`AdaptDL <./AdaptDLMode.rst>`__\ ， `FrameworkController <./FrameworkControllerMode.rst>`__\ ， `DLTS <./DLTSMode.rst>`__ 和 `AML <./AMLMode.rst>`__。 这些都是\ *内置的训练平台*。
+
+如果需要在计算资源上使用 NNI，可以根据相关接口，轻松构建对其它训练平台的支持。 详情请参考 `NNI 中如何实现训练平台 <./HowToImplementTrainingService.rst>`__  。
+
+如何使用训练平台？
+----------------------------
+
+在 Experiment 的 YAML 配置文件中选择并配置好训练平台。 参考相应训练平台的文档来了解如何配置。 同时， `Experiment 文档 <../Tutorial/ExperimentConfig.rst>`__ 提供了更多详细信息。
+
+然后，需要准备代码目录，将路径填入配置文件的 ``codeDir`` 字段。 注意，非本机模式下，代码目录会在 Experiment 运行前上传到远程或集群中。 因此，NNI 将文件数量限制到 2000，总大小限制为 300 MB。 如果 codeDir 中包含了过多的文件，可添加 ``.nniignore`` 文件来排除部分，与 ``.gitignore`` 文件用法类似。 写好这个文件请参考 :githublink:`示例 <examples/trials/mnist-tfv1/.nniignore>` 和 `git 文档 <https://git-scm.com/docs/gitignore#_pattern_format>`__。
+
+如果用户需要在 Experiment 使用大文件（如，大规模的数据集），并且不想使用本机模式，可以：1) 在 Trial command 字段中添加命令，每次 Trial 运行前下载数据；或 2) 使用工作节点可访问的共享存储。 通常情况下，训练平台都会有共享存储。 参考每个训练平台的文档，了解详情。
+
+内置训练平台
+--------------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: auto
+
+   * - 训练平台
+     - 简介
+   * - `Local <./LocalMode.rst>`__
+     - NNI 支持在本机运行实验，称为 local 模式。 local 模式表示 NNI 会在运行 NNI Manager 进程计算机上运行 Trial 任务，支持 GPU 调度功能。
+   * - `Remote <./RemoteMachineMode.rst>`__
+     - NNI 支持通过 SSH 通道在多台计算机上运行 Experiment，称为 remote 模式。 NNI 需要这些计算机的访问权限，并假定已配置好了深度学习训练环境。 NNI 将在远程计算机上中提交 Trial 任务，并根据 GPU 资源调度 Trial 任务。
+   * - `PAI <./PaiMode.rst>`__
+     - NNI 支持在 `OpenPAI <https://github.com/Microsoft/pai>`__ (aka PAI) 上运行 Experiment，即 pai 模式。 在使用 NNI 的 pai 模式前, 需要有 `OpenPAI <https://github.com/Microsoft/pai>`__ 群集的账户。 如果没有 OpenPAI 账户，参考 `这里 <https://github.com/Microsoft/pai#how-to-deploy>`__ 来进行部署。 在 pai 模式中，会在 Docker 创建的容器中运行 Trial 程序。
+   * - `Kubeflow <./KubeflowMode.rst>`__
+     - NNI 支持在 `Kubeflow <https://github.com/kubeflow/kubeflow>`__ 上运行，称为 kubeflow 模式。 在开始使用 NNI 的 Kubeflow 模式前，需要有一个 Kubernetes 集群，可以是私有部署的，或者是 `Azure Kubernetes Service(AKS) <https://azure.microsoft.com/zh-cn/services/kubernetes-service/>`__，并需要一台配置好  `kubeconfig <https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/>`__ 的 Ubuntu 计算机连接到此 Kubernetes 集群。 如果不熟悉 Kubernetes，可先浏览 `这里 <https://kubernetes.io/docs/tutorials/kubernetes-basics/>`__ 。 在 kubeflow 模式下，每个 Trial 程序会在 Kubernetes 集群中作为一个 Kubeflow 作业来运行。
+   * - `AdaptDL <./AdaptDLMode.rst>`__
+     - NNI 支持在 `AdaptDL <https://github.com/petuum/adaptdl>`__ 上运行，称为 AdaptDL 模式。 在开始使用 NNI kubeflow 模式之前，应该具有 Kubernetes 集群。
+   * - `FrameworkController <./FrameworkControllerMode.rst>`__
+     - NNI 支持使用 `FrameworkController <https://github.com/Microsoft/frameworkcontroller>`__，来运行 Experiment，称之为 frameworkcontroller 模式。 FrameworkController 构建于 Kubernetes 上，用于编排各种应用。这样，可以不用为某个深度学习框架安装 Kubeflow 的 tf-operator 或 pytorch-operator 等。 而直接用 FrameworkController 作为 NNI Experiment 的训练平台。
+   * - `DLTS <./DLTSMode.rst>`__
+     - NNI 支持在 `DLTS <https://github.com/microsoft/DLWorkspace.git>`__ 上运行 Experiment，这是一个由微软开源的工具包。
+   * - `AML <./AMLMode.rst>`__
+     - NNI 支持在 `AML <https://azure.microsoft.com/zh-cn/services/machine-learning/>`__ 上运行 Experiment，称为 aml 模式。
+
+
+训练平台做了什么？
+------------------------------
+
+
+.. raw:: html
+
+   <p align="center">
+   <img src="https://user-images.githubusercontent.com/23273522/51816536-ed055580-2301-11e9-8ad8-605a79ee1b9a.png" alt="drawing" width="700"/>
+   </p>
+
+
+根据 `概述 <../Overview>`__ 中展示的架构，训练平台会做三件事：1) 启动 Trial; 2) 收集指标，并与 NNI 核心（NNI 管理器）通信；3) 监控 Trial 任务状态。 为了展示训练平台的详细工作原理，下面介绍了训练平台从最开始到第一个 Trial 运行成功的过程。
+
+步骤 1. **验证配置，并准备训练平台。** 训练平台会首先检查用户配置是否正确（例如，身份验证是否有错）。 然后，训练平台会为 Experiment 做准备，创建训练平台可访问的代码目录（ ``codeDir`` ）。
+
+.. Note:: 不同的训练平台会有不同的方法来处理 ``codeDir``。 例如，本机训练平台会直接在 ``codeDir`` 中运行 Trial。 远程训练平台会将 ``codeDir`` 打包成 zip 文件，并上传到每台机器中。 基于 Kubernetes 的训练平台会将 ``codeDir`` 复制到共享存储上，此存储可以由训练平台提供，或者用户在配置文件中指定。
+
+步骤 2. **提交第一个 Trial。** 要初始化 Trial，通常（在不重用环境的情况下），NNI 会复制一些文件（包括参数配置，启动脚本等）到训练平台中。 然后，NNI 会通过子进程、SSH、RESTful API 等方式启动 Trial。
+
+.. Warning:: Trial 当前目录的内容与 ``codeDir`` 会完全一样，但可能是完全不同的路径（甚至不同的计算机）。本机模式是唯一一个所有 Trial 都使用同一个 ``codeDir`` 的训练平台。 其它训练平台，会将步骤 1 中准备好的 ``codeDir``，从共享目录复制到每个 Trial 自己独立的工作目录下。 强烈建议不要依赖于本机模式下的共享行为，这会让 Experiment 很难扩展到其它训练平台上。
+
+步骤 3. **收集 metrics。**  NNI 监视记录 trial 状态，更新 trial 的状态（例如，从 ``WAITING`` to ``RUNNING``，从 ``RUNNING`` 到 ``SUCCEEDED``），并收集 metrics 。 当前，大部分训练平台都实现为 "主动" 模式，即，训练平台会调用 NNI 管理器上的 RESTful API 来更新指标。 注意，这也需要运行 NNI 管理器的计算机能被工作节点访问到。

docs/zh_CN/TrainingService/PaiMode.md

-# **在 OpenPAI 上运行 Experiment**
-
-NNI 支持在 [OpenPAI](https://github.com/Microsoft/pai) 上运行 Experiment，即 pai 模式。 在使用 NNI 的 pai 模式前, 需要有 [OpenPAI](https://github.com/Microsoft/pai) 群集的账户。 如果没有 OpenPAI 账户，参考[这里](https://github.com/Microsoft/pai#how-to-deploy)来进行部署。 在 pai 模式中，会在 Docker 创建的容器中运行 Trial 程序。
-
-## 设置环境
-
-步骤 1. 参考[指南](../Tutorial/QuickStart.md)安装 NNI。
-
-步骤 2. 获得令牌（token）。
-
-打开 OpenPAI 的 Web 界面，并点击右上方的 `My profile` 按钮。 ![](../../img/pai_profile.jpg)
-
-点击页面中的 `copy` 按钮来复制 jwt 令牌。 ![](../../img/pai_token.jpg)
-
-步骤 3. 将 NFS 存储挂在到本地计算机。
-
-点击 Web 界面中的 `Submit job` 按钮。 ![](../../img/pai_job_submission_page.jpg)
-
-找到作业提交页面中的数据管理部分。 ![](../../img/pai_data_management_page.jpg)
-
-`Preview container paths` 是 API 提供的 NFS 主机和路径，需要将对应的位置挂载到本机，然后 NNI 才能使用 NFS 存储。  
-例如，使用下列命令：
-
-```bash
-sudo mount -t nfs4 gcr-openpai-infra02:/pai/data /local/mnt
-```
-
-然后容器中的 `/data` 路径会被挂载到本机的 `/local/mnt` 文件夹  
-然后在 NNI 的配置文件中如下配置：
-
-```yaml
-nniManagerNFSMountPath: /local/mnt
-```
-
-步骤 4. 获得 OpenPAI 存储的配置名称和 nniManagerMountPath
-
-`Team share storage` 字段是在 OpenPAI 中指定存储配置的值。 可以在 `Team share storage` 中找到 `paiStorageConfigName` 和 `containerNFSMountPath` 字段，如：
-
-```yaml
-paiStorageConfigName: confignfs-data
-containerNFSMountPath: /mnt/confignfs-data
-```
-
-## 运行 Experiment
-
-以 `examples/trials/mnist-annotation` 为例。 NNI 的 YAML 配置文件如下：
-
-```yaml
-authorName: your_name
-experimentName: auto_mnist
-# 并发运行的 Trial 数量
-trialConcurrency: 2
-# Experiment 的最长持续运行时间
-maxExecDuration: 3h
-# 空表示一直运行
-maxTrialNum: 100
-# 可选项: local, remote, pai
-trainingServicePlatform: pai
-# 搜索空间文件
-searchSpacePath: search_space.json
-# 可选项: true, false
-useAnnotation: true
-tuner:
-  builtinTunerName: TPE
-  classArgs:
-    optimize_mode: maximize
-trial:
-  command: python3 mnist.py
-  codeDir: ~/nni/examples/trials/mnist-annotation
-  gpuNum: 0
-  cpuNum: 1
-  memoryMB: 8196
-  image: msranni/nni:latest
-  virtualCluster: default
-  nniManagerNFSMountPath: /local/mnt
-  containerNFSMountPath: /mnt/confignfs-data
-  paiStorageConfigName: confignfs-data
-# 配置要访问的 OpenPAI 集群
-paiConfig:
-  userName: your_pai_nni_user
-  token: your_pai_token
-  host: 10.1.1.1
-  # 可选，测试版功能。
-  reuse: true
-```
-
-注意：如果用 pai 模式运行，需要在 YAML 文件中设置 `trainingServicePlatform: pai`。 配置文件中的 host 字段是 OpenPAI 作业提交页面的地址，例如：`10.10.5.1`，NNI 中默认协议是 `http`，如果 OpenPAI 集群启用了 https，则需要使用 `https://10.10.5.1` 的格式。
-
-### Trial 配置
-
-与[本机模式](LocalMode.md)，以及[远程计算机模式](RemoteMachineMode.md)相比，pai 模式的 `trial` 需要额外的配置：
-
-* cpuNum
-    
-    可选。 Trial 程序的 CPU 需求，必须为正数。 如果没在 Trial 配置中设置，则需要在 `paiConfigPath` 指定的配置文件中设置。
-
-* memoryMB
-    
-    可选。 Trial 程序的内存需求，必须为正数。 如果没在 Trial 配置中设置，则需要在 `paiConfigPath` 指定的配置文件中设置。
-
-* image
-    
-    可选。 在 pai 模式中，Trial 程序由 OpenPAI 在 [Docker 容器](https://www.docker.com/)中安排运行。 此字段用来指定 Trial 程序的容器使用的 Docker 映像。
-    
-    [Docker Hub](https://hub.docker.com/) 上有预制的 NNI Docker 映像 [nnimsra/nni](https://hub.docker.com/r/msranni/nni/)。 它包含了用来启动 NNI Experiment 所依赖的所有 Python 包，Node 模块和 JavaScript。 生成此 Docker 映像的文件在[这里](https://github.com/Microsoft/nni/tree/master/deployment/docker/Dockerfile)。 可以直接使用此映像，或参考它来生成自己的映像。 如果没在 Trial 配置中设置，则需要在 `paiConfigPath` 指定的配置文件中设置。
-
-* virtualCluster
-    
-    可选。 设置 OpenPAI 的 virtualCluster，即虚拟集群。 如果未设置此参数，将使用默认（default）虚拟集群。
-
-* nniManagerNFSMountPath
-    
-    必填。 在 nniManager 计算机上设置挂载的路径。
-
-* containerNFSMountPath
-    
-    必填。 在 OpenPAI 的容器中设置挂载路径。
-
-* paiStorageConfigName:
-    
-    可选。 设置 OpenPAI 中使用的存储名称。 如果没在 Trial 配置中设置，则需要在 `paiConfigPath` 指定的配置文件中设置。
-
-* command
-    
-    可选。 设置 OpenPAI 容器中使用的命令。
-
-* paiConfigPath 可选。 设置 OpenPAI 作业配置文件路径，文件为 YAML 格式。
-    
-    如果在 NNI 配置文件中设置了 `paiConfigPath`，则不需在 `trial` 配置中设置 `command`, `paiStorageConfigName`, `virtualCluster`, `image`, `memoryMB`, `cpuNum`, `gpuNum`。 这些字段将使用 `paiConfigPath` 指定的配置文件中的值。
-    
-    注意：
-    
-    1. OpenPAI 配置文件中的作业名称会由 NNI 指定，格式为：nni_exp_${this.experimentId}*trial*${trialJobId}。
-    
-    2. 如果在 OpenPAI 配置文件中有多个 taskRoles，NNI 会将这些 taksRoles 作为一个 Trial 任务，用户需要确保只有一个 taskRole 会将指标上传到 NNI 中，否则可能会产生错误。
-
-### OpenPAI 配置
-
-`paiConfig` 包括了 OpenPAI 的专门配置，
-
-* userName
-    
-    必填。 OpenPAI 平台的用户名。
-
-* token
-    
-    必填。 OpenPAI 平台的身份验证密钥。
-
-* host
-    
-    必填。 OpenPAI 平台的主机。 OpenPAI 作业提交页面的地址，例如：`10.10.5.1`，NNI 中默认协议是 `http`，如果 OpenPAI 集群启用了 https，则需要使用 `https://10.10.5.1` 的格式。
-
-* reuse (测试版功能)
-    
-    可选，默认为 false。 如果为 true，NNI 会重用 OpenPAI 作业，在其中运行尽可能多的 Trial。 这样可以节省创建新作业的时间。 用户需要确保同一作业中的每个 Trial 相互独立，例如，要避免从之前的 Trial 中读取检查点。
-
-完成并保存 NNI Experiment 配置文件后（例如可保存为：exp_pai.yml），运行以下命令：
-
-```bash
-nnictl create --config exp_pai.yml
-```
-
-来在 pai 模式下启动 Experiment。 NNI 会为每个 Trial 创建 OpenPAI 作业，作业名称的格式为 `nni_exp_{experiment_id}_trial_{trial_id}`。 可以在 OpenPAI 集群的网站中看到 NNI 创建的作业，例如： ![](../../img/nni_pai_joblist.jpg)
-
-注意：pai 模式下，NNIManager 会启动 RESTful 服务，监听端口为 NNI 网页服务器的端口加1。 例如，如果网页端口为`8080`，那么 RESTful 服务器会监听在 `8081`端口，来接收运行在 Kubernetes 中的 Trial 作业的指标。 因此，需要在防火墙中启用端口 `8081` 的 TCP 协议，以允许传入流量。
-
-当一个 Trial 作业完成后，可以在 NNI 网页的概述页面（如：http://localhost:8080/oview）中查看 Trial 的信息。
-
-在 Trial 列表页面中展开 Trial 信息，点击如下的 logPath： ![](../../img/nni_webui_joblist.jpg)
-
-接着将会打开 HDFS 的 WEB 界面，并浏览到 Trial 的输出文件： ![](../../img/nni_trial_hdfs_output.jpg)
-
-在输出目录中可以看到三个文件：stderr, stdout, 以及 trial.log
-
-## 数据管理
-
-使用 NNI 启动 Experiment 前，应在 nniManager 计算机中设置相应的挂载数据的路径。 OpenPAI 有自己的存储（NFS、AzureBlob ...），在 OpenPAI 中使用的存储将在启动作业时挂载到容器中。 应通过 `paiStorageConfigName` 字段选择 OpenPAI 中的存储类型。 然后，应将存储挂载到 nniManager 计算机上，并在配置文件中设置 `nniManagerNFSMountPath`，NNI会生成 bash 文件并将 `codeDir` 中的数据拷贝到 `nniManagerNFSMountPath` 文件夹中，然后启动 Trial 任务。 `nniManagerNFSMountPath` 中的数据会同步到 OpenPAI 存储中，并挂载到 OpenPAI 的容器中。 容器中的数据路径在 `containerNFSMountPath` 设置，NNI 将进入该文件夹，运行脚本启动 Trial 任务。
-
-## 版本校验
-
-从 0.6 开始，NNI 支持版本校验。确保 NNIManager 与 trialKeeper 的版本一致，避免兼容性错误。 检查策略：
-
-1. 0.6 以前的 NNIManager 可与任何版本的 trialKeeper 一起运行，trialKeeper 支持向后兼容。
-2. 从 NNIManager 0.6 开始，与 triakKeeper 的版本必须一致。 例如，如果 NNIManager 是 0.6 版，则 trialKeeper 也必须是 0.6 版。
-3. 注意，只有版本的前两位数字才会被检查。例如，NNIManager 0.6.1 可以和 trialKeeper 的 0.6 或 0.6.2 一起使用，但不能与 trialKeeper 的 0.5.1 或 0.7 版本一起使用。
-
-如果 Experiment 无法运行，而且不能确认是否是因为版本不匹配造成的，可以在 Web 界面检查是否有相关的错误消息。 ![](../../img/version_check.png)
\ No newline at end of file

docs/zh_CN/TrainingService/PaiMode.rst

+.. role:: raw-html(raw)
+   :format: html
+
+
+**在 OpenPAI 上运行 Experiment**
+====================================
+
+NNI 支持在 `OpenPAI <https://github.com/Microsoft/pai>`__  上运行 Experiment，即 pai 模式。 在使用 NNI 的 pai 模式前, 需要有 `OpenPAI <https://github.com/Microsoft/pai>`__ 群集的账户。 如果没有 OpenPAI 账户，参考 `这里 <https://github.com/Microsoft/pai#how-to-deploy>`__ 来进行部署。 在 pai 模式中，会在 Docker 创建的容器中运行 Trial 程序。
+
+.. toctree::
+
+设置环境
+-----------------
+
+**步骤 1. 参考** `指南 <../Tutorial/QuickStart.rst>`__ **安装 NNI。**   
+
+**步骤 2. 获得令牌（token）。**
+
+打开 OpenPAI 的 Web 界面，并点击右上方的 ``My profile`` 按钮。
+
+.. image:: ../../img/pai_profile.jpg
+   :scale: 80%
+
+点击页面中的 ``copy`` 按钮来复制 jwt 令牌。
+
+.. image:: ../../img/pai_token.jpg
+   :scale: 67%
+
+**步骤 3. 将 NFS 存储挂在到本地计算机。**  
+
+点击 Web 界面中的 ``Submit job`` 按钮。
+
+.. image:: ../../img/pai_job_submission_page.jpg
+   :scale: 50%
+
+找到作业提交页面中的数据管理部分。
+
+
+.. image:: ../../img/pai_data_management_page.jpg
+   :scale: 33%  
+
+``Preview container paths`` 是 API 提供的 NFS 主机和路径，需要将对应的位置挂载到本机，然后 NNI 才能使用 NFS 存储。
+例如，使用下面的命令。
+
+.. code-block:: bash
+
+   sudo mount -t nfs4 gcr-openpai-infra02:/pai/data /local/mnt
+
+然后将容器中的 ``/ data`` 文件夹安装到本地计算机的 ``/ local / mnt`` 文件夹中。\ :raw-html:`<br>`
+可以在NNI的配置文件中使用以下配置：
+
+.. code-block:: yaml
+
+   nniManagerNFSMountPath: /local/mnt
+
+**步骤 4. 获得 OpenPAI 存储的配置名称和 nniManagerMountPath**
+
+``Team share storage`` 字段是在 OpenPAI 中指定存储配置的值。 可以在 ``Team share storage`` 中找到 ``paiStorageConfigName`` 和 ``containerNFSMountPath`` 字段，如：
+
+.. code-block:: yaml
+
+   paiStorageConfigName: confignfs-data
+   containerNFSMountPath: /mnt/confignfs-data
+
+运行实验
+-----------------
+
+以 ``examples/trials/mnist-annotation`` 为例。 NNI 的 YAML 配置文件如下：
+
+.. code-block:: yaml
+
+   authorName: your_name
+   experimentName: auto_mnist
+   # how many trials could be concurrently running
+   trialConcurrency: 2
+   # maximum experiment running duration
+   maxExecDuration: 3h
+   # empty means never stop
+   maxTrialNum: 100
+   # choice: local, remote, pai
+   trainingServicePlatform: pai
+   # search space file
+   searchSpacePath: search_space.json
+   # choice: true, false
+   useAnnotation: true
+   tuner:
+     builtinTunerName: TPE
+     classArgs:
+       optimize_mode: maximize
+   trial:
+     command: python3 mnist.py
+     codeDir: ~/nni/examples/trials/mnist-annotation
+     gpuNum: 0
+     cpuNum: 1
+     memoryMB: 8196
+     image: msranni/nni:latest
+     virtualCluster: default
+     nniManagerNFSMountPath: /local/mnt
+     containerNFSMountPath: /mnt/confignfs-data
+     paiStorageConfigName: confignfs-data
+   # Configuration to access OpenPAI Cluster
+   paiConfig:
+     userName: your_pai_nni_user
+     token: your_pai_token
+     host: 10.1.1.1
+     # optional, experimental feature.
+     reuse: true
+
+注意：如果用 pai 模式运行，需要在 YAML 文件中设置 ``trainingServicePlatform: pai`` 。 配置文件中的 host 字段是 OpenPAI 作业提交页面的地址，例如：``10.10.5.1``，NNI 中默认协议是 ``http``，如果 OpenPAI 集群启用了 https，则需要使用 ``https://10.10.5.1`` 的格式。
+
+Trial 配置
+^^^^^^^^^^^^^^^^^^^^
+
+与 `LocalMode <LocalMode.md>`__ 和 `RemoteMachineMode <RemoteMachineMode.rst>`__\ 相比， pai 模式下的 ``trial`` 配置有下面所列的其他 keys：
+
+
+* 
+  cpuNum
+
+  可选。 Trial 程序的 CPU 需求，必须为正数。 如果没在 Trial 配置中设置，则需要在 ``paiConfigPath`` 指定的配置文件中设置。
+
+* 
+  memoryMB
+
+  可选。 Trial 程序的内存需求，必须为正数。 如果没在 Trial 配置中设置，则需要在 ``paiConfigPath`` 指定的配置文件中设置。
+
+* 
+  image
+
+  可选。 在 pai 模式下，OpenPAI 将安排试用程序在 `Docker 容器 <https://www.docker.com/>`__ 中运行。 此键用来指定 Trial 程序的容器使用的 Docker 映像。
+
+  我们已经 build 了一个 docker image :githublink:`nnimsra/nni <deployment/docker/Dockerfile>`。 可以直接使用此映像，或参考它来生成自己的映像。 如果没在 Trial 配置中设置，则需要在 ``paiConfigPath`` 指定的配置文件中设置。
+
+* 
+  virtualCluster
+
+  可选。 设置 OpenPAI 的 virtualCluster，即虚拟集群。 如果未设置此参数，将使用默认的虚拟集群。
+
+* 
+  nniManagerNFSMountPath
+
+  必填。 在 nniManager 计算机上设置挂载的路径。
+
+* 
+  containerNFSMountPath
+
+  必填。 在 OpenPAI 的容器中设置挂载路径。
+
+* 
+  paiStorageConfigName:
+
+  可选。 设置 OpenPAI 中使用的存储名称。 如果没在 Trial 配置中设置，则需要在 ``paiConfigPath`` 指定的配置文件中设置。
+
+* 
+  command
+
+  可选。 设置 OpenPAI 容器中使用的命令。
+
+* 
+  paiConfigPath
+  可选。 设置 OpenPAI 作业配置文件路径，文件为 YAML 格式。
+
+  如果用户在配置文件中设置了 ``paiConfigPath``，那么就无需声明以下字段： ``command`` ， ``paiStorageConfigName``\ ， ``virtualCluster``\ ， ``image``\ ， ``memoryMB``\ ， ``cpuNum``\   和 ``gpuNum`` 。 这些字段将使用 ``paiConfigPath`` 指定的配置文件中的值。
+
+  注意：
+
+
+  #. 
+     OpenPAI 配置文件中的作业名称会由 NNI 指定，格式为：nni\ *exp*\ ${this.experimentId}*trial*\ ${trialJobId}。
+
+  #. 
+     如果在 OpenPAI 配置文件中有多个 taskRoles，NNI 会将这些 taksRoles 作为一个 Trial 任务，用户需要确保只有一个 taskRole 会将指标上传到 NNI 中，否则可能会产生错误。
+
+OpenPAI 配置
+^^^^^^^^^^^^^^^^^^^^^^
+
+``paiConfig`` 包括了 OpenPAI 的专门配置，
+
+
+* 
+  userName
+
+  必填。 OpenPAI 平台的用户名。
+
+* 
+  token
+
+  必填。 OpenPAI 平台的身份验证密钥。
+
+* 
+  host
+
+  必填。 OpenPAI 平台的主机。 OpenPAI 作业提交页面的地址，例如：``10.10.5.1``，NNI 中默认协议是 ``http``，如果 OpenPAI 集群启用了 https，则需要使用 ``https://10.10.5.1`` 的格式。
+
+* 
+  reuse (测试版功能)
+
+  可选，默认为 false。 如果为 true，NNI 会重用 OpenPAI 作业，在其中运行尽可能多的 Trial。 这样可以节省创建新作业的时间。 用户需要确保同一作业中的每个 Trial 相互独立，例如，要避免从之前的 Trial 中读取检查点。
+
+完成并保存 NNI Experiment 配置文件后（例如可保存为：exp_pai.yml），运行以下命令：
+
+.. code-block:: bash
+
+   nnictl create --config exp_pai.yml
+
+来在 pai 模式下启动 Experiment。 NNI 会为每个 Trial 创建 OpenPAI 作业，作业名称的格式为 ``nni_exp_{experiment_id}_trial_{trial_id}``。
+可以在 OpenPAI 集群的网站中看到 NNI 创建的作业，例如：
+
+.. image:: ../../img/nni_pai_joblist.jpg
+   :target: ../../img/nni_pai_joblist.jpg
+   :alt: 
+
+
+注意：pai 模式下，NNIManager 会启动 RESTful 服务，监听端口为 NNI 网页服务器的端口加 1。 例如，如果网页端口为 ``8080``，那么 RESTful 服务器会监听在 ``8081`` 端口，来接收运行在 Kubernetes 中的 Trial 作业的指标。 因此，需要在防火墙中启用端口 ``8081`` 的 TCP 协议，以允许传入流量。
+
+当一个 Trial 作业完成后，可以在 NNI 网页的概述页面（如：http://localhost:8080/oview）中查看 Trial 的信息。
+
+在 Trial 列表页面中展开 Trial 信息，点击如下的 logPath：
+
+
+.. image:: ../../img/nni_webui_joblist.jpg
+   :scale: 30%
+
+接着将会打开 HDFS 的 WEB 界面，并浏览到 Trial 的输出文件：
+
+
+.. image:: ../../img/nni_trial_hdfs_output.jpg
+   :scale: 80%
+
+在输出目录中可以看到三个文件：stderr，stdout 以及 trial.log。
+
+数据管理
+---------------
+
+使用 NNI 启动 Experiment 前，应在 nniManager 计算机中设置相应的挂载数据的路径。 OpenPAI 有自己的存储（NFS、AzureBlob ...），在 OpenPAI 中使用的存储将在启动作业时挂载到容器中。 应通过 ``paiStorageConfigName`` 字段选择 OpenPAI 中的存储类型。 然后，应将存储挂载到 nniManager 计算机上，并在配置文件中设置 ``nniManagerNFSMountPath``，NNI会生成 bash 文件并将 ``codeDir`` 中的数据拷贝到 ``nniManagerNFSMountPath`` 文件夹中，然后启动 Trial 任务。 ``nniManagerNFSMountPath`` 中的数据会同步到 OpenPAI 存储中，并挂载到 OpenPAI 的容器中。 容器中的数据路径在 ``containerNFSMountPath`` 设置，NNI 将进入该文件夹，运行脚本启动 Trial 任务。 
+
+版本校验
+-------------
+
+从 0.6 开始，NNI 支持版本校验。 确保 NNIManager 与 trialKeeper 的版本一致，避免兼容性错误。
+检查策略：
+
+
+#. 0.6 以前的 NNIManager 可与任何版本的 trialKeeper 一起运行，trialKeeper 支持向后兼容。
+#. 从 NNIManager 0.6 开始，与 triakKeeper 的版本必须一致。 例如，如果 NNIManager 是 0.6 版，则 trialKeeper 也必须是 0.6 版。
+#. 注意，只有版本的前两位数字才会被检查。例如，NNIManager 0.6.1 可以和 trialKeeper 的 0.6 或 0.6.2 一起使用，但不能与 trialKeeper 的 0.5.1 或 0.7 版本一起使用。
+
+如果 Experiment 无法运行，而且不能确认是否是因为版本不匹配造成的，可以在 Web 界面检查是否有相关的错误消息。
+
+
+.. image:: ../../img/version_check.png
+   :scale: 80%

docs/zh_CN/TrainingService/PaiYarnMode.md

-**在 OpenPAIYarn 上运行 Experiment**
-===
-原始的 `pai` 模式改为了 `paiYarn` 模式，这是基于 Yarn 的分布式训练平台。
-
-## 设置环境
-参考[指南](../Tutorial/QuickStart.md)安装 NNI。
-
-## 运行 Experiment
-以 `examples/trials/mnist-tfv1` 为例。 NNI 的 YAML 配置文件如下：
-
-```yaml
-authorName: your_name
-experimentName: auto_mnist
-# 并发运行的 Trial 数量
-trialConcurrency: 2
-# Experiment 的最长持续运行时间
-maxExecDuration: 3h
-# 空表示一直运行
-maxTrialNum: 100
-# 可选项: local, remote, pai, paiYarn
-trainingServicePlatform: paiYarn
-# 搜索空间文件
-searchSpacePath: search_space.json
-# 可选项: true, false
-useAnnotation: false
-tuner:
-  builtinTunerName: TPE
-  classArgs:
-    optimize_mode: maximize
-trial:
-  command: python3 mnist.py
-  codeDir: ~/nni/examples/trials/mnist-tfv1
-  gpuNum: 0
-  cpuNum: 1
-  memoryMB: 8196
-  image: msranni/nni:latest
-# 配置访问的 OpenpaiYarn 集群
-paiYarnConfig:
-  userName: your_paiYarn_nni_user
-  passWord: your_paiYarn_password
-  host: 10.1.1.1
-```
-
-注意：如果用 paiYarn 模式运行，需要在 YAML 文件中设置 `trainingServicePlatform: paiYarn`。
-
-与[本机模式](LocalMode.md)，以及[远程计算机模式](RemoteMachineMode.md)相比，paiYarn 模式的 Trial 有额外的配置：
-* cpuNum
-    * 必填。 Trial 程序的 CPU 需求，必须为正数。
-* memoryMB
-    * 必填。 Trial 程序的内存需求，必须为正数。
-* image
-    * 必填。 在 paiYarn 模式中，Trial 程序由 OpenpaiYarn 在 [Docker 容器](https://www.docker.com/)中安排运行。 此键用来指定 Trial 程序的容器使用的 Docker 映像。
-    * [Docker Hub](https://hub.docker.com/) 上有预制的 NNI Docker 映像 [nnimsra/nni](https://hub.docker.com/r/msranni/nni/)。 它包含了用来启动 NNI Experiment 所依赖的所有 Python 包，Node 模块和 JavaScript。 生成此 Docker 映像的文件在[这里](https://github.com/Microsoft/nni/tree/master/deployment/docker/Dockerfile)。 可以直接使用此映像，或参考它来生成自己的映像。
-* virtualCluster
-    * 可选。 设置 OpenPAIYarn 的 virtualCluster，即虚拟集群。 如果未设置此参数，将使用默认（default）虚拟集群。
-* shmMB
-    * 可选。 设置 OpenPAIYarn 的 shmMB，即 Docker 中的共享内存。
-* authFile
-    * 可选。在使用 paiYarn 模式时，为私有 Docker 仓库设置认证文件，[见参考文档](https://github.com/microsoft/paiYarn/blob/2ea69b45faa018662bc164ed7733f6fdbb4c42b3/docs/faq.md#q-how-to-use-private-docker-registry-job-image-when-submitting-an-openpaiYarn-job)。提供 authFile 的本地路径即可， NNI 会上传此文件。
-* portList
-    * 可选。 设置 OpenPAIYarn 的 portList。指定了容器中使用的端口列表，[参考文档](https://github.com/microsoft/paiYarn/blob/b2324866d0280a2d22958717ea6025740f71b9f0/docs/job_tutorial.md#specification)。<br /> 示例如下： NNI 中的配置架构如下所示：
-    ```
-    portList:
-      - label: test
-        beginAt: 8080
-        portNumber: 2
-    ```
-    假设需要在 MNIST 示例中使用端口来运行 TensorBoard。 第一步是编写 `mnist.py` 的包装脚本 `launch_paiYarn.sh`。
-
-    ```bash
-    export TENSORBOARD_PORT=paiYarn_PORT_LIST_${paiYarn_CURRENT_TASK_ROLE_NAME}_0_tensorboard
-    tensorboard --logdir . --port ${!TENSORBOARD_PORT} &
-    python3 mnist.py
-    ```
-    portList 的配置部分如下：
-
-    ```yaml
-  trial:
-    command: bash launch_paiYarn.sh
-    portList:
-      - label: tensorboard
-        beginAt: 0
-        portNumber: 1
-    ```
-
-NNI 支持 OpenPAIYarn 中的两种认证授权方法，即密码和 paiYarn 令牌（token)，[参考](https://github.com/microsoft/paiYarn/blob/b6bd2ab1c8890f91b7ac5859743274d2aa923c22/docs/rest-server/API.md#2-authentication)。 授权配置在 `paiYarnConfig` 字段中。 密码认证的 `paiYarnConfig` 配置如下：
-```
-paiYarnConfig:
-  userName: your_paiYarn_nni_user
-  passWord: your_paiYarn_password
-  host: 10.1.1.1
-```
-令牌认证的 `paiYarnConfig` 配置如下：
-```
-paiYarnConfig:
-  userName: your_paiYarn_nni_user
-  token: your_paiYarn_token
-  host: 10.1.1.1
-```
-
-完成并保存 NNI Experiment 配置文件后（例如可保存为：exp_paiYarn.yml），运行以下命令：
-```
-nnictl create --config exp_paiYarn.yml
-```
-来在 paiYarn 模式下启动 Experiment。 NNI 会为每个 Trial 创建 OpenPAIYarn 作业，作业名称的格式为 `nni_exp_{experiment_id}_trial_{trial_id}`。 可以在 OpenPAIYarn 集群的网站中看到 NNI 创建的作业，例如： ![](../../img/nni_pai_joblist.jpg)
-
-注意：paiYarn 模式下，NNIManager 会启动 RESTful 服务，监听端口为 NNI 网页服务器的端口加1。 例如，如果网页端口为`8080`，那么 RESTful 服务器会监听在 `8081`端口，来接收运行在 Kubernetes 中的 Trial 作业的指标。 因此，需要在防火墙中启用端口 `8081` 的 TCP 协议，以允许传入流量。
-
-当一个 Trial 作业完成后，可以在 NNI 网页的概述页面（如：http://localhost:8080/oview）中查看 Trial 的信息。
-
-在 Trial 列表页面中展开 Trial 信息，点击如下的 logPath： ![](../../img/nni_webui_joblist.jpg)
-
-接着将会打开 HDFS 的 WEB 界面，并浏览到 Trial 的输出文件： ![](../../img/nni_trial_hdfs_output.jpg)
-
-在输出目录中可以看到三个文件：stderr, stdout, 以及 trial.log
-
-## 数据管理
-如果训练数据集不大，可放在 codeDir 中，NNI会将其上传到 HDFS，或者构建 Docker 映像来包含数据。 如果数据集非常大，则不可放在 codeDir 中，可参考此[指南](https://github.com/microsoft/paiYarn/blob/master/docs/user/storage.md)来将数据目录挂载到容器中。
-
-如果要将 Trial 的其它输出保存到 HDFS 上，如模型文件等，需要在 Trial 代码中使用 `NNI_OUTPUT_DIR` 来保存输出文件。NNI 的 SDK 会将文件从 Trial 容器的 `NNI_OUTPUT_DIR` 复制到 HDFS 上，目标路径为：`hdfs://host:port/{username}/nni/{experiments}/{experimentId}/trials/{trialId}/nnioutput`。
-
-## 版本校验
-从 0.6 开始，NNI 支持版本校验。确保 NNIManager 与 trialKeeper 的版本一致，避免兼容性错误。 检查策略：
-1. 0.6 以前的 NNIManager 可与任何版本的 trialKeeper 一起运行，trialKeeper 支持向后兼容。
-2. 从 NNIManager 0.6 开始，与 triakKeeper 的版本必须一致。 例如，如果 NNIManager 是 0.6 版，则 trialKeeper 也必须是 0.6 版。
-3. 注意，只有版本的前两位数字才会被检查。例如，NNIManager 0.6.1 可以和 trialKeeper 的 0.6 或 0.6.2 一起使用，但不能与 trialKeeper 的 0.5.1 或 0.7 版本一起使用。
-
-如果 Experiment 无法运行，而且不能确认是否是因为版本不匹配造成的，可以在 Web 界面检查是否有相关的错误消息。 ![](../../img/version_check.png)

docs/zh_CN/TrainingService/PaiYarnMode.rst

+.. role:: raw-html(raw)
+   :format: html
+
+
+**在 OpenPAIYarn 上运行 Experiment**
+========================================
+
+原始的 ``pai`` 模式改为了 ``paiYarn`` 模式，这是基于 Yarn 的分布式训练平台。
+
+设置环境
+-----------------
+
+参考 `指南 <../Tutorial/QuickStart.rst>`__ 安装 NNI。
+
+运行实验
+-----------------
+
+以 ``examples/trials/mnist-tfv1`` 为例。 NNI 的 YAML 配置文件如下：
+
+.. code-block:: yaml
+
+   authorName: your_name
+   experimentName: auto_mnist
+   # how many trials could be concurrently running
+   trialConcurrency: 2
+   # maximum experiment running duration
+   maxExecDuration: 3h
+   # empty means never stop
+   maxTrialNum: 100
+   # choice: local, remote, pai, paiYarn
+   trainingServicePlatform: paiYarn
+   # search space file
+   searchSpacePath: search_space.json
+   # choice: true, false
+   useAnnotation: false
+   tuner:
+     builtinTunerName: TPE
+     classArgs:
+       optimize_mode: maximize
+   trial:
+     command: python3 mnist.py
+     codeDir: ~/nni/examples/trials/mnist-tfv1
+     gpuNum: 0
+     cpuNum: 1
+     memoryMB: 8196
+     image: msranni/nni:latest
+   # Configuration to access OpenpaiYarn Cluster
+   paiYarnConfig:
+     userName: your_paiYarn_nni_user
+     passWord: your_paiYarn_password
+     host: 10.1.1.1
+
+注意：如果用 paiYarn 模式运行，需要在 YAML 文件中设置 ``trainingServicePlatform: paiYarn`` 。
+
+与 `LocalMode <LocalMode.md>`__ 和 `RemoteMachineMode <RemoteMachineMode.rst>`__\ 相比， paiYarn 模式下的 trial 配置有其他 keys：
+
+
+* cpuNum
+
+  * 必填。 Trial 程序的 CPU 需求，必须为正数。
+
+* memoryMB
+
+  * 必填。 Trial 程序的内存需求，必须为正数。
+
+* image
+
+  * 必填。 在 paiYarn 模式下，OpenpaiYarn 将安排试用程序在 `Docker 容器 <https://www.docker.com/>`__ 中运行。 此键用来指定 Trial 程序的容器使用的 Docker 映像。
+  * 我们已经 build 了一个 docker image :githublink:`nnimsra/nni <deployment/docker/Dockerfile>`。 可以直接使用此映像，或参考它来生成自己的映像。
+
+* virtualCluster
+
+  * 可选。 设置 OpenPAIYarn 的 virtualCluster，即虚拟集群。 如果未设置此参数，将使用默认的虚拟集群。
+
+* shmMB
+
+  * 可选。 设置 OpenPAIYarn 的 shmMB，即 Docker 中的共享内存。
+
+* authFile
+
+  * 可选。在使用 paiYarn 模式时，为私有 Docker 仓库设置认证文件，`见参考文档 <https://github.com/microsoft/paiYarn/blob/2ea69b45faa018662bc164ed7733f6fdbb4c42b3/docs/faq.rst#q-how-to-use-private-docker-registry-job-image-when-submitting-an-openpaiYarn-job>`__\。提供 authFile 的本地路径即可， NNI 会上传此文件。
+
+* 
+  portList  
+
+
+  * 
+    可选。 设置 OpenPAIYarn 的 portList。指定了容器中使用的端口列表，`参考文档 <https://github.com/microsoft/paiYarn/blob/b2324866d0280a2d22958717ea6025740f71b9f0/docs/job_tutorial.rst#specification>`__。\ :raw-html:`<br>`
+    NNI 中的配置架构如下所示：
+
+    .. code-block:: bash
+
+       portList:
+       - label: test
+         beginAt: 8080
+         portNumber: 2
+
+    假设需要在 MNIST 示例中使用端口来运行 TensorBoard。 第一步是编写 ``mnist.py`` 的包装脚本 ``launch_paiYarn.sh``。
+
+    .. code-block:: bash
+
+       export TENSORBOARD_PORT=paiYarn_PORT_LIST_${paiYarn_CURRENT_TASK_ROLE_NAME}_0_tensorboard
+       tensorboard --logdir . --port ${!TENSORBOARD_PORT} &
+       python3 mnist.py
+
+    portList 的配置部分如下：
+
+    .. code-block:: yaml
+
+       trial:
+       command: bash launch_paiYarn.sh
+       portList:
+       - label: tensorboard
+         beginAt: 0
+         portNumber: 1
+
+NNI 支持 OpenPAIYarn 中的两种认证授权方法，即密码和 paiYarn 令牌（token)，`参考 <https://github.com/microsoft/paiYarn/blob/b6bd2ab1c8890f91b7ac5859743274d2aa923c22/docs/rest-server/API.rst#2-authentication>`__。 授权在 ``paiYarnConfig`` 字段中配置。\ :raw-html:`<br>`
+密码认证的 ``paiYarnConfig`` 配置如下：
+
+.. code-block:: bash
+
+   paiYarnConfig:
+     userName: your_paiYarn_nni_user
+     passWord: your_paiYarn_password
+     host: 10.1.1.1
+
+paiYarn 令牌认证的 ``paiYarnConfi`` 配置如下：
+
+.. code-block:: bash
+
+   paiYarnConfig:
+     userName: your_paiYarn_nni_user
+     token: your_paiYarn_token
+     host: 10.1.1.1
+
+完成并保存 NNI Experiment 配置文件后（例如可保存为：exp_paiYarn.yml），运行以下命令：
+
+.. code-block:: bash
+
+   nnictl create --config exp_paiYarn.yml
+
+来在 paiYarn 模式下启动 Experiment。 NNI 会为每个 Trial 创建 OpenpaiYarn 作业，作业名称的格式为 ``nni_exp_{experiment_id}_trial_{trial_id}``。
+可以在 OpenPAIYarn 集群的网站中看到 NNI 创建的作业，例如：
+
+.. image:: ../../img/nni_pai_joblist.jpg
+   :target: ../../img/nni_pai_joblist.jpg
+   :alt: 
+
+
+注意：paiYarn 模式下，NNIManager 会启动 RESTful 服务，监听端口为 NNI 网页服务器的端口加 1。 例如，如果网页端口为 ``8080``，那么 RESTful 服务器会监听在 ``8081`` 端口，来接收运行在 Kubernetes 中的 Trial 作业的指标。 因此，需要在防火墙中启用端口 ``8081`` 的 TCP 协议，以允许传入流量。
+
+当一个 Trial 作业完成后，可以在 NNI 网页的概述页面（如：http://localhost:8080/oview）中查看 Trial 的信息。
+
+在 Trial 列表页面中展开 Trial 信息，点击如下的 logPath：
+
+
+.. image:: ../../img/nni_webui_joblist.jpg
+   :target: ../../img/nni_webui_joblist.jpg
+   :alt: 
+
+
+接着将会打开 HDFS 的 WEB 界面，并浏览到 Trial 的输出文件：
+
+
+.. image:: ../../img/nni_trial_hdfs_output.jpg
+   :target: ../../img/nni_trial_hdfs_output.jpg
+   :alt: 
+
+
+在输出目录中可以看到三个文件：stderr，stdout 以及 trial.log。
+
+数据管理
+---------------
+
+如果训练数据集不大，可放在 codeDir中，NNI会将其上传到 HDFS，或者构建 Docker 映像来包含数据。 如果数据集非常大，则不可放在 codeDir 中，可参考此 `指南 <https://github.com/microsoft/paiYarn/blob/master/docs/user/storage.rst>`__ 来将数据目录挂载到容器中。
+
+如果要将 Trial 的其它输出保存到 HDFS 上，如模型文件等，需要在 Trial 代码中使用 ``NNI_OUTPUT_DIR`` 来保存输出文件。NNI 的 SDK 会将文件从 Trial 容器的 ``NNI_OUTPUT_DIR`` 复制到 HDFS 上，目标路径为：``hdfs://host:port/{username}/nni/{experiments}/{experimentId}/trials/{trialId}/nnioutput``。
+
+版本校验
+-------------
+
+从 0.6 开始，NNI 支持版本校验。 确保 NNIManager 与 trialKeeper 的版本一致，避免兼容性错误。
+检查策略：
+
+
+#. 0.6 以前的 NNIManager 可与任何版本的 trialKeeper 一起运行，trialKeeper 支持向后兼容。
+#. 从 NNIManager 0.6 开始，与 triakKeeper 的版本必须一致。 例如，如果 NNIManager 是 0.6 版，则 trialKeeper 也必须是 0.6 版。
+#. 注意，只有版本的前两位数字才会被检查。例如，NNIManager 0.6.1 可以和 trialKeeper 的 0.6 或 0.6.2 一起使用，但不能与 trialKeeper 的 0.5.1 或 0.7 版本一起使用。
+
+如果 Experiment 无法运行，而且不能确认是否是因为版本不匹配造成的，可以在 Web 界面检查是否有相关的错误消息。
+
+.. image:: ../../img/version_check.png
+   :target: ../../img/version_check.png
+   :alt: 
+

docs/zh_CN/TrainingService/RemoteMachineMode.md

-# 在远程计算机上运行 Experiment
-
-NNI 可以通过 SSH 在多个远程计算机上运行同一个 Experiment，称为 `remote` 模式。 这就像一个轻量级的训练平台。 在此模式下，可以从计算机启动 NNI，并将 Trial 并行调度到远程计算机。
-
-远程计算机操作系统支持 `Linux`, `Windows 10`, 和 `Windows Server 2019`。
-
-## 必需组件
-
-* 确保远程计算机的默认环境符合 Trial 代码的需求。 如果默认环境不符合要求，可以将设置脚本添加到 NNI 配置的 `command` 字段。
-
-* 确保远程计算机能被运行 `nnictl` 命令的计算机通过 SSH 访问。 同时支持 SSH 的密码和密钥验证方法。 有关高级用法，参考[配置](../Tutorial/ExperimentConfig.md)的 machineList 部分。
-
-* 确保每台计算机上的 NNI 版本一致。
-
-* 如果要同时使用远程 Linux 和 Windows，请确保 Trial 的命令与远程操作系统兼容。 例如，Python 3.x 的执行文件在 Linux 下是 `python3`，在 Windows 下是 `python`。
-
-### Linux
-
-* 根据[安装说明](../Tutorial/InstallationLinux.md)，在远程计算机上安装 NNI。
-
-### Windows
-
-* 根据[安装说明](../Tutorial/InstallationWin.md)，在远程计算机上安装 NNI。
-
-* 安装并启动 `OpenSSH Server`。
-    
-    1. 打开 Windows 中的`设置`应用。
-    
-    2. 点击`应用程序`，然后点击`可选功能`。
-    
-    3. 点击`添加功能`，搜索并选择 `OpenSSH Server`，然后点击`安装`。
-    
-    4. 安装后，运行下列命令来启动服务并设为自动启动。
-    
-    ```bat
-    sc config sshd start=auto
-    net start sshd
-    ```
-
-* 确保远程账户为管理员权限，以便可以停止运行中的 Trial。
-
-* 确保除了默认消息外，没有别的欢迎消息，否则会导致 NodeJS 中的 ssh2 出错。 例如，如果在 Azure 中使用了 Data Science VM，需要删除 `C:\dsvm\tools\setup\welcome.bat` 中的 echo 命令。
-    
-    打开新命令窗口，如果输入如下，则表示正常。
-    
-    ```text
-    Microsoft Windows [Version 10.0.17763.1192]
-    (c) 2018 Microsoft Corporation. All rights reserved.
-    
-    (py37_default) C:\Users\AzureUser>
-    ```
-
-## 运行 Experiment
-
-例如，有三台机器，可使用用户名和密码登录。
-
-| IP       | 用户名 | 密码     |
-| -------- | --- | ------ |
-| 10.1.1.1 | bob | bob123 |
-| 10.1.1.2 | bob | bob123 |
-| 10.1.1.3 | bob | bob123 |
-
-在这三台计算机或另一台能访问这些计算机的环境中安装并运行 NNI。
-
-以 `examples/trials/mnist-annotation` 为例。 示例文件 `examples/trials/mnist-annotation/config_remote.yml` 的内容如下：
-
-```yaml
-authorName: default
-experimentName: example_mnist
-trialConcurrency: 1
-maxExecDuration: 1h
-maxTrialNum: 10
-#choice: local, remote, pai
-trainingServicePlatform: remote
-# 搜索空间文件
-searchSpacePath: search_space.json
-# 可选项: true, false
-useAnnotation: true
-tuner:
-  # 可选项: TPE, Random, Anneal, Evolution, BatchTuner
-  #SMAC (SMAC 需要先通过 nnictl 来安装)
-  builtinTunerName: TPE
-  classArgs:
-    # 可选项:: maximize, minimize
-    optimize_mode: maximize
-trial:
-  command: python3 mnist.py
-  codeDir: .
-  gpuNum: 0
-#local 模式下 machineList 可为空
-machineList:
-  - ip: 10.1.1.1
-    username: bob
-    passwd: bob123
-    #使用默认端口 22 时，该配置可跳过
-    #port: 22
-  - ip: 10.1.1.2
-    username: bob
-    passwd: bob123
-  - ip: 10.1.1.3
-    username: bob
-    passwd: bob123
-```
-
-`codeDir` 中的文件会自动上传到远程计算机中。 可在 Windows、Linux 或 macOS 上运行以下命令，在远程 Linux 计算机上启动 Trial：
-
-```bash
-nnictl create --config examples/trials/mnist-annotation/config_remote.yml
-```
\ No newline at end of file

docs/zh_CN/TrainingService/RemoteMachineMode.rst

+在远程计算机上运行 Experiment
+====================================
+
+NNI 可以通过 SSH 在多个远程计算机上运行同一个 Experiment，称为 ``remote`` 模式。 这就像一个轻量级的训练平台。 在此模式下，可以从计算机启动 NNI，并将 Trial 并行调度到远程计算机。
+
+远程计算机的操作系统支持 ``Linux``\ ， ``Windows 10`` 和 ``Windows Server 2019``。
+
+必需组件
+------------
+
+
+* 
+  确保远程计算机的默认环境符合 Trial 代码的需求。 如果默认环境不符合要求，可以将设置脚本添加到 NNI 配置的 ``command`` 字段。
+
+* 
+  确保远程计算机能被运行 ``nnictl`` 命令的计算机通过 SSH 访问。 同时支持 SSH 的密码和密钥验证方法。 高级用法请参考 `实验配置参考 <../Tutorial/ExperimentConfig.rst>`__ 。
+
+* 
+  确保每台计算机上的 NNI 版本一致。
+
+* 
+  如果要同时使用远程 Linux 和 Windows，请确保 Trial 的命令与远程操作系统兼容。 例如，Python 3.x 的执行文件在 Linux 下是 ``python3``，在 Windows 下是 ``python``。
+
+Linux
+^^^^^
+
+
+* 按照 `安装教程 <../Tutorial/InstallationLinux.rst>`__  在远程计算机上安装 NNI 。
+
+Windows
+^^^^^^^
+
+
+* 
+  按照 `安装教程 <../Tutorial/InstallationLinux.rst>`__  在远程计算机上安装 NNI 。
+
+* 
+  安装并启动 ``OpenSSH Server``。
+
+
+  #. 
+     在 Windows 上打开 ``设置`` 应用。
+
+  #. 
+     点击 ``应用``，然后点击 ``可选功能``。
+
+  #. 
+     点击 ``添加功能``，找到并选择 ``OpenSSH 服务器``，然后点击 ``安装``。
+
+  #. 
+     安装后，运行下列命令来启动服务并设为自动启动。
+
+  .. code-block:: bat
+
+     sc config sshd start=auto
+     net start sshd
+
+* 
+  确保远程账户为管理员权限，以便可以停止运行中的 Trial。
+
+* 
+  确保除了默认消息外，没有别的欢迎消息，否则会导致 NodeJS 中的 ssh2 出错。 例如，如果在 Azure 中使用了 Data Science VM，需要删除 ``C:\dsvm\tools\setup\welcome.bat`` 中的 echo 命令。
+
+  打开新命令窗口，如果输入如下，则表示正常。
+
+  .. code-block:: text
+
+     Microsoft Windows [Version 10.0.17763.1192]
+     (c) 2018 Microsoft Corporation. All rights reserved.
+
+     (py37_default) C:\Users\AzureUser>
+
+运行实验
+-----------------
+
+例如， 有三台机器，可使用用户名和密码登录。
+
+.. list-table::
+   :header-rows: 1
+   :widths: auto
+
+   * - IP
+     - Username
+     - Password
+   * - 10.1.1.1
+     - bob
+     - bob123
+   * - 10.1.1.2
+     - bob
+     - bob123
+   * - 10.1.1.3
+     - bob
+     - bob123
+
+
+在这三台计算机或另一台能访问这些计算机的环境中安装并运行 NNI。
+
+以 ``examples/trials/mnist-annotation`` 为例。 示例文件 ``examples/trials/mnist-annotation/config_remote.yml`` 的内容如下：
+
+.. code-block:: yaml
+
+   authorName: default
+   experimentName: example_mnist
+   trialConcurrency: 1
+   maxExecDuration: 1h
+   maxTrialNum: 10
+   #choice: local, remote, pai
+   trainingServicePlatform: remote
+   # search space file
+   searchSpacePath: search_space.json
+   #choice: true, false
+   useAnnotation: true
+   tuner:
+     #choice: TPE, Random, Anneal, Evolution, BatchTuner
+     #SMAC (SMAC should be installed through nnictl)
+     builtinTunerName: TPE
+     classArgs:
+       #choice: maximize, minimize
+       optimize_mode: maximize
+   trial:
+     command: python3 mnist.py
+     codeDir: .
+     gpuNum: 0
+   # machineList can be empty if the platform is local
+   machineList:
+     - ip: 10.1.1.1
+       username: bob
+       passwd: bob123
+       # port can be skip if using default ssh port 22
+       # port: 22
+     - ip: 10.1.1.2
+       username: bob
+       passwd: bob123
+     - ip: 10.1.1.3
+       username: bob
+       passwd: bob123
+
+``codeDir`` 中的文件会自动上传到远程计算机中。 可在 Windows、Linux 或 macOS 上运行以下命令，在远程 Linux 计算机上启动 Trial：
+
+.. code-block:: bash
+
+   nnictl create --config examples/trials/mnist-annotation/config_remote.yml
+
+配置 python 环境
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+默认情况下，命令和脚本将在远程计算机的默认环境中执行。 如果远程机器上有多个 python 虚拟环境，并且想在特定环境中运行实验，请使用 **preCommand** 来指定远程计算机上的 python 环境。 
+
+以 ``examples/trials/mnist-tfv2`` 为例。 示例文件 ``examples/trials/mnist-tfv2/config_remote.yml`` 的内容如下：
+
+.. code-block:: yaml
+
+   authorName: default
+   experimentName: example_mnist
+   trialConcurrency: 1
+   maxExecDuration: 1h
+   maxTrialNum: 10
+   #choice: local, remote, pai
+   trainingServicePlatform: remote
+   searchSpacePath: search_space.json
+   #choice: true, false
+   useAnnotation: false
+   tuner:
+     #choice: TPE, Random, Anneal, Evolution, BatchTuner, MetisTuner
+     #SMAC (SMAC should be installed through nnictl)
+     builtinTunerName: TPE
+     classArgs:
+       #choice: maximize, minimize
+       optimize_mode: maximize
+   trial:
+     command: python3 mnist.py
+     codeDir: .
+     gpuNum: 0
+   #machineList can be empty if the platform is local
+   machineList:
+     - ip: ${replace_to_your_remote_machine_ip}
+       username: ${replace_to_your_remote_machine_username}
+       sshKeyPath: ${replace_to_your_remote_machine_sshKeyPath}
+       # Pre-command will be executed before the remote machine executes other commands.
+       # Below is an example of specifying python environment.
+       # If you want to execute multiple commands, please use "&&" to connect them.
+       # preCommand: source ${replace_to_absolute_path_recommended_here}/bin/activate
+       # preCommand: source ${replace_to_conda_path}/bin/activate ${replace_to_conda_env_name}
+       preCommand: export PATH=${replace_to_python_environment_path_in_your_remote_machine}:$PATH
+
+在远程机器执行其他命令之前，将执行 **预命令**。 因此，可以像这样配置 python 环境路径：
+
+.. code-block:: yaml
+
+   # Linux remote machine
+   preCommand: export PATH=${replace_to_python_environment_path_in_your_remote_machine}:$PATH
+   # Windows remote machine
+   preCommand: set path=${replace_to_python_environment_path_in_your_remote_machine};%path%
+
+或者，如果想激活 ``virtualen`` 环境：
+
+.. code-block:: yaml
+
+   # Linux remote machine
+   preCommand: source ${replace_to_absolute_path_recommended_here}/bin/activate
+   # Windows remote machine
+   preCommand: ${replace_to_absolute_path_recommended_here}\\scripts\\activate
+
+或者，如果想激活 ``conda`` 环境：
+
+.. code-block:: yaml
+
+   # Linux remote machine
+   preCommand: source ${replace_to_conda_path}/bin/activate ${replace_to_conda_env_name}
+   # Windows remote machine
+   preCommand: call activate ${replace_to_conda_env_name}
+
+如果要执行多个命令，可以使用 ``&&`` 连接以下命令：
+
+.. code-block:: yaml
+
+   preCommand: command1 && command2 && command3
+
+**注意**：因为 ``preCommand`` 每次都会在其他命令之前执行，所以强烈建议不要设置 **preCommand** 来对系统进行更改，即 ``mkdir`` or ``touch``.

docs/zh_CN/TrialExample/Cifar10Examples.md

-# CIFAR-10 示例
-
-## 概述
-
-[CIFAR-10](https://www.cs.toronto.edu/~kriz/cifar.html) 分类是机器学习中常用的基准问题。 CIFAR-10 数据集是图像的集合。 它也是机器学习领域最常用的数据集之一，包含 60000 万张 32x32 的图像，共有 10 个分类。 因此以 CIFAR-10 分类为例来介绍 NNI 的用法。
-
-### **目标**
-
-总所周知，模型 optimizer (优化器）的选择直接影响了最终指标的性能。 本教程的目标是**调优出性能更好的优化器**，从而为图像识别训练出一个相对较小的卷积网络（CNN）。
-
-本例中，选择了以下常见的深度学习优化器：
-
-> "SGD", "Adadelta", "Adagrad", "Adam", "Adamax"
-
-### **实验**
-
-#### 准备
-
-此示例需要安装 PyTorch。 PyTorch 安装包需要选择所基于的 Python 和 CUDA 版本。
-
-这是环境 python==3.5 且 cuda == 8.0 的示例，然后用下列命令来安装 [ PyTorch](https://pytorch.org/)：
-
-```bash
-python3 -m pip install http://download.pytorch.org/whl/cu80/torch-0.4.1-cp35-cp35m-linux_x86_64.whl
-python3 -m pip install torchvision
-```
-
-#### NNI 与 CIFAR-10
-
-**搜索空间**
-
-正如本文目标，要为 CIFAR-10 找到最好的`优化器`。 使用不同的优化器时，还要相应的调整`学习率`和`网络架构`。 因此，选择这三个参数作为超参，并创建如下的搜索空间。
-
-```json
-{
-    "lr":{"_type":"choice", "_value":[0.1, 0.01, 0.001, 0.0001]},
-    "optimizer":{"_type":"choice", "_value":["SGD", "Adadelta", "Adagrad", "Adam", "Adamax"]},
-    "model":{"_type":"choice", "_value":["vgg", "resnet18", "googlenet", "densenet121", "mobilenet", "dpn92", "senet18"]}
-}
-```
-
-*实现代码：[search_space.json](https://github.com/Microsoft/nni/blob/master/examples/trials/cifar10_pytorch/search_space.json)*
-
-**Trial（尝试）**
-
-这是超参集合的训练代码，关注以下几点：
-
-* 使用 `nni.get_next_parameter()` 来获取下一组训练的超参组合。
-* 使用 `nni.report_intermediate_result(acc)` 在每个 epoch 结束时返回中间结果。
-* 使用 `nni.report_final_result(acc)` 在每个 Trial 结束时返回最终结果。
-
-*实现代码：[main.py](https://github.com/Microsoft/nni/blob/master/examples/trials/cifar10_pytorch/main.py)*
-
-还可直接修改现有的代码来支持 Nni，参考：[如何实现 Trial](Trials.md)。
-
-**配置**
-
-这是在本机运行 Experiment 的示例（多GPU）：
-
-代码：[examples/trials/cifar10_pytorch/config.yml](https://github.com/Microsoft/nni/blob/master/examples/trials/cifar10_pytorch/config.yml)
-
-这是在 OpenPAI 上运行 Experiment 的示例：
-
-代码：[examples/trials/cifar10_pytorch/config_pai.yml](https://github.com/Microsoft/nni/blob/master/examples/trials/cifar10_pytorch/config_pai.yml)
-
-*完整示例：[examples/trials/cifar10_pytorch/](https://github.com/Microsoft/nni/tree/master/examples/trials/cifar10_pytorch)*
-
-#### 运行 Experiment
-
-以上即为 Experiment 的代码介绍，**从命令行运行 config.yml 文件来开始 Experiment**。
-
-```bash
-nnictl create --config nni/examples/trials/cifar10_pytorch/config.yml
-```
\ No newline at end of file

docs/zh_CN/TrialExample/Cifar10Examples.rst

+CIFAR-10 示例
+=================
+
+概述
+--------
+
+`CIFAR-10 <https://www.cs.toronto.edu/~kriz/cifar.html>`__ 分类是机器学习中常用的基准问题。 CIFAR-10 数据集是图像的集合。 它也是机器学习领域最常用的数据集之一，包含 60000 万张 32x32 的图像，共有 10 个分类。 因此以 CIFAR-10 分类为例来介绍 NNI 的用法。
+
+**目标**
+^^^^^^^^^^^^^
+
+总所周知，模型 optimizer (优化器）的选择直接影响了最终指标的性能。 本教程的目标是 **调优出性能更好的优化器**，从而为图像识别训练出一个相对较小的卷积网络（CNN）。
+
+本例中，选择了以下常见的深度学习优化器：
+
+..
+
+   "SGD", "Adadelta", "Adagrad", "Adam", "Adamax"
+
+
+实验
+^^^^^^^^^^^^^^^^^^^^
+
+准备
+^^^^^^^^^^^^
+
+此示例需要安装 PyTorch。 PyTorch 安装包需要选择所基于的 Python 和 CUDA 版本。
+
+这是环境 python==3.5 且 cuda == 8.0 的样例，然后用下列命令来安装 `PyTorch <https://pytorch.org/>`__\ :
+
+.. code-block:: bash
+
+   python3 -m pip install http://download.pytorch.org/whl/cu80/torch-0.4.1-cp35-cp35m-linux_x86_64.whl
+   python3 -m pip install torchvision
+
+NNI 与 CIFAR-10
+^^^^^^^^^^^^^^^^^
+
+**搜索空间**
+
+正如本文目标，要为 CIFAR-10 找到最好的 ``优化器``。 使用不同的优化器时，还要相应的调整 ``学习率`` 和 ``网络架构``。 因此，选择这三个参数作为超参，并创建如下的搜索空间。
+
+.. code-block:: json
+
+   {
+       "lr":{"_type":"choice", "_value":[0.1, 0.01, 0.001, 0.0001]},
+       "optimizer":{"_type":"choice", "_value":["SGD", "Adadelta", "Adagrad", "Adam", "Adamax"]},
+       "model":{"_type":"choice", "_value":["vgg", "resnet18", "googlenet", "densenet121", "mobilenet", "dpn92", "senet18"]}
+   }
+
+示例： :githublink:`search_space.json <examples/trials/cifar10_pytorch/search_space.json>`
+
+**Trial**
+
+这是超参集合的训练代码，关注以下几点：
+
+
+* 使用 ``nni.get_next_parameter()`` 来获取下一组训练的超参组合。
+* 使用 ``nni.report_intermediate_result(acc)`` 在每个 epoch 结束时返回中间结果。
+* 使用 ``nni.report_final_result(acc)`` 在每个 Trial 结束时返回最终结果。
+
+示例： :githublink:`main.py <examples/trials/cifar10_pytorch/main.py>`
+
+还可直接修改现有的代码来支持 Nni，参考：`如何实现 Trial <Trials.rst>`__。
+
+**配置**
+
+这是在本机运行 Experiment 的示例（多GPU）：
+
+代码 :githublink:`examples/trials/cifar10_pytorch/config.yml <examples/trials/cifar10_pytorch/config.yml>`
+
+这是在 OpenPAI 上运行 Experiment 的示例：
+
+代码 :githublink:`examples/trials/cifar10_pytorch/config_pai.yml <examples/trials/cifar10_pytorch/config_pai.yml>`
+
+完整示例 :githublink:`examples/trials/cifar10_pytorch/ <examples/trials/cifar10_pytorch>`
+
+运行 Experiment
+^^^^^^^^^^^^^^^^^^^^^
+
+以上即为 Experiment 的代码介绍，**从命令行运行 config.yml 文件来开始 Experiment**。
+
+.. code-block:: bash
+
+   nnictl create --config nni/examples/trials/cifar10_pytorch/config.yml

docs/zh_CN/TrialExample/EfficientNet.md

-# EfficientNet
-
-[EfficientNet: Rethinking Model Scaling for Convolutional Neural Networks](https://arxiv.org/abs/1905.11946)
-
-如论文中 3.3 所述，使用遍历搜索来找到 EfficientNet-B1 的 alpha, beta 和 gamma 的最好组合。 搜索空间，Tuner，配置示例如下。
-
-## 说明
-
-[示例代码](https://github.com/microsoft/nni/tree/master/examples/trials/efficientnet)
-
-1. 将示例代码目录设为当前工作目录。
-2. 运行 `git clone https://github.com/ultmaster/EfficientNet-PyTorch` 来克隆修改过的 [EfficientNet-PyTorch](https://github.com/lukemelas/EfficientNet-PyTorch)。 修改尽可能接近原始的 [TensorFlow 版本](https://github.com/tensorflow/tpu/tree/master/models/official/efficientnet) （包括 EMA，标记平滑度等等。）；另外添加了代码从 Tuner 获取参数并回调中间和最终结果。 将其 clone 至 `EfficientNet-PyTorch`；`main.py`，`train_imagenet.sh` 等文件会在配置文件中指定的路径。
-3. 运行 `nnictl create --config config_local.yml` (OpenPAI 可使用 `config_pai.yml`) 来找到最好的 EfficientNet-B1。 根据环境来调整训练平台（OpenPAI、本机、远程），batch size。
-
-在 ImageNet 上的训练，可阅读 `EfficientNet-PyTorch/train_imagenet.sh`。 下载 ImageNet，并参考 [PyTorch 格式](https://pytorch.org/docs/stable/torchvision/datasets.html#imagenet) 来解压，然后将 `/mnt/data/imagenet` 替换为 ImageNet 的路径。 此文件也是如何将 ImageNet 挂载到 OpenPAI 容器的示例。
-
-## 结果
-
-下图展示了 acc@1 和 alpha、beta、gamma 之间的关系。
-
-![](../../img/efficientnet_search_result.png)

docs/zh_CN/TrialExample/EfficientNet.rst

+EfficientNet
+============
+
+`EfficientNet: Rethinking Model Scaling for Convolutional Neural Networks <https://arxiv.org/abs/1905.11946>`__
+
+如论文中 3.3 所述，使用遍历搜索来找到 EfficientNet-B1 的 alpha, beta 和 gamma 的最好组合。 搜索空间，Tuner，配置示例如下。
+
+说明
+------------
+
+:githublink:`示例代码 <examples/trials/efficientnet>`
+
+
+#. 将示例代码目录设为当前工作目录。
+#. 运行 ``git clone https://github.com/ultmaster/EfficientNet-PyTorch`` 来克隆 `ultmaster 修改过的版本 <https://github.com/ultmaster/EfficientNet-PyTorch>`__ 。 修改尽可能接近原始的 `Tensorflow 版本 <https://github.com/tensorflow/tpu/tree/master/models/official/efficientnet>`__ （包括 EMA，标记平滑度等等。）；另外添加了代码从 Tuner 获取参数并回调中间和最终结果。 将其 clone 至 ``EfficientNet-PyTorch``；``main.py``，``train_imagenet.sh`` 等文件会在配置文件中指定的路径。
+#. 运行 ``nnictl create --config config_local.yml``（OpenPAI 可使用 ``config_pai.yml``）来找到最好的 EfficientNet-B1。 根据环境来调整训练平台（OpenPAI、本机、远程），batch size。
+
+在 ImageNet 上的训练，可阅读 ``EfficientNet-PyTorch/train_imagenet.sh``。 下载 ImageNet，并参考 `PyTorch 格式 <https://pytorch.org/docs/stable/torchvision/datasets.html#imagenet>`__ 来解压，然后将 ``/mnt/data/imagenet`` 替换为 ImageNet 的路径。 此文件也是如何将 ImageNet 挂载到 OpenPAI 容器的示例。
+
+结果
+-------
+
+下图展示了 acc@1 和 alpha、beta、gamma 之间的关系。
+
+
+.. image:: ../../img/efficientnet_search_result.png
+   :target: ../../img/efficientnet_search_result.png
+   :alt: 
+

docs/zh_CN/TrialExample/GbdtExample.md

-# GBDT
-
-梯度提升是机器学习中回归和分类问题的一种方法。它由一组弱分类模型所组成，决策树是其中的典型。 像其它提升方法一样，它也分步来构建模型，并使用可微分的损失函数来优化。
-
-梯度决策树（gradient boosting decision tree，GBDT）有很多流行的实现，如：[LightGBM](https://github.com/Microsoft/LightGBM), [xgboost](https://github.com/dmlc/xgboost), 和 [catboost](https://github.com/catboost/catboost)，等等。 GBDT 是解决经典机器学习问题的重要工具。 GBDT 也是一种鲁棒的算法，可以使用在很多领域。 GBDT 的超参越好，就能获得越好的性能。
-
-NNI 是用来调优超参的平台，可以在 NNI 中尝试各种内置的搜索算法，并行运行多个 Trial。
-
-## 1. GBDT 的搜索空间
-
-GBDT 有很多超参，但哪些才会影响性能或计算速度呢？ 基于实践经验，建议如下（以 lightgbm 为例）：
-
-> * 获得更好的精度
-
-* `learning_rate`. `学习率`的范围应该是 [0.001, 0.9]。
-
-* `num_leaves`. `num_leaves` 与 `max_depth` 有关，不必两个值同时调整。
-
-* `bagging_freq`. `bagging_freq` 可以是 [1, 2, 4, 8, 10]。
-
-* `num_iterations`. 如果达到期望的拟合精度，可以调整得大一些。
-
-> * 加速
-
-* `bagging_fraction`. `bagging_fraction` 的范围应该是 [0.7, 1.0]。
-
-* `feature_fraction`. `feature_fraction` 的范围应该是 [0.6, 1.0]。
-
-* `max_bin`.
-
-> * 避免过拟合
-
-* `min_data_in_leaf`. 取决于数据集。
-
-* `min_sum_hessian_in_leaf`. 取决于数据集。
-
-* `lambda_l1` 和 `lambda_l2`.
-
-* `min_gain_to_split`.
-
-* `num_leaves`.
-
-更多信息可参考： [lightgbm](https://lightgbm.readthedocs.io/en/latest/Parameters-Tuning.html) 和 [autoxgoboost](https://github.com/ja-thomas/autoxgboost/blob/master/poster_2018.pdf)
-
-## 2. 任务描述
-
-"auto-gbdt" 基于 LightGBM 和 NNI。 数据集有[训练数据](https://github.com/Microsoft/nni/blob/master/examples/trials/auto-gbdt/data/regression.train)和[测试数据](https://github.com/Microsoft/nni/blob/master/examples/trials/auto-gbdt/data/regression.train)。 根据数据中的特征和标签，训练一个 GBDT 回归模型，用来做预测。
-
-## 3. 如何运行 NNI
-
-### 3.1 安装所有要求的包
-
-    pip install lightgbm
-    pip install pandas
-    
-
-### 3.2 准备 Trial 代码
-
-基础代码如下：
-
-```python
-...
-
-def get_default_parameters():
-    ...
-    return params
-
-
-def load_data(train_path='./data/regression.train', test_path='./data/regression.test'):
-    '''
-    读取或创建数据集
-    '''
-    ...
-
-    return lgb_train, lgb_eval, X_test, y_test
-
-def run(lgb_train, lgb_eval, params, X_test, y_test):
-    # 训练
-    gbm = lgb.train(params,
-                    lgb_train,
-                    num_boost_round=20,
-                    valid_sets=lgb_eval,
-                    early_stopping_rounds=5)
-    # 预测
-    y_pred = gbm.predict(X_test, num_iteration=gbm.best_iteration)
-
-    # 评估
-    rmse = mean_squared_error(y_test, y_pred) ** 0.5
-    print('The rmse of prediction is:', rmse)
-
-if __name__ == '__main__':
-    lgb_train, lgb_eval, X_test, y_test = load_data()
-
-    PARAMS = get_default_parameters()
-    # train
-    run(lgb_train, lgb_eval, PARAMS, X_test, y_test)
-```
-
-### 3.3 准备搜索空间
-
-如果要调优 `num_leaves`, `learning_rate`, `bagging_fraction` 和 `bagging_freq`, 可创建一个 [search_space.json](https://github.com/Microsoft/nni/blob/master/examples/trials/auto-gbdt/search_space.json) 文件：
-
-```json
-{
-    "num_leaves":{"_type":"choice","_value":[31, 28, 24, 20]},
-    "learning_rate":{"_type":"choice","_value":[0.01, 0.05, 0.1, 0.2]},
-    "bagging_fraction":{"_type":"uniform","_value":[0.7, 1.0]},
-    "bagging_freq":{"_type":"choice","_value":[1, 2, 4, 8, 10]}
-}
-```
-
-参考[这里](../Tutorial/SearchSpaceSpec.md)，了解更多变量类型。
-
-### 3.4 在代码中使用 NNI SDK
-
-```diff
-+import nni
-...
-
-def get_default_parameters():
-    ...
-    return params
-
-
-def load_data(train_path='./data/regression.train', test_path='./data/regression.test'):
-    '''
-    读取或创建数据集
-    '''
-    ...
-
-    return lgb_train, lgb_eval, X_test, y_test
-
-def run(lgb_train, lgb_eval, params, X_test, y_test):
-    # 训练
-    gbm = lgb.train(params,
-                    lgb_train,
-                    num_boost_round=20,
-                    valid_sets=lgb_eval,
-                    early_stopping_rounds=5)
-    # 预测
-    y_pred = gbm.predict(X_test, num_iteration=gbm.best_iteration)
-
-    # 评估
-    rmse = mean_squared_error(y_test, y_pred) ** 0.5
-    print('The rmse of prediction is:', rmse)
-
-+   nni.report_final_result(rmse)
-
-if __name__ == '__main__':
-    lgb_train, lgb_eval, X_test, y_test = load_data()
-
-+   RECEIVED_PARAMS = nni.get_next_parameter()
-    PARAMS = get_default_parameters()
-+   PARAMS.update(RECEIVED_PARAMS)
-
-    # 训练
-    run(lgb_train, lgb_eval, PARAMS, X_test, y_test)
-```
-
-### 3.5 实现配置文件并运行
-
-在配置文件中，可以设置如下内容：
-
-* Experiment 设置：`trialConcurrency`, `maxExecDuration`, `maxTrialNum`, `trial gpuNum`, 等等。
-* 平台设置：`trainingServicePlatform`，等等。
-* 路径设置：`searchSpacePath`, `trial codeDir`，等等。
-* 算法设置：选择 `Tuner` 算法，`优化方向`，等等。
-
-config.yml 示例：
-
-```yaml
-authorName: default
-experimentName: example_auto-gbdt
-trialConcurrency: 1
-maxExecDuration: 10h
-maxTrialNum: 10
-#可选项: local, remote, pai
-trainingServicePlatform: local
-searchSpacePath: search_space.json
-#可选项: true, false
-useAnnotation: false
-tuner:
-  #可选项: TPE, Random, Anneal, Evolution, BatchTuner
-  #SMAC (SMAC 需要先通过 nnictl 来安装)
-  builtinTunerName: TPE
-  classArgs:
-    #可选项: maximize, minimize
-    optimize_mode: minimize
-trial:
-  command: python3 main.py
-  codeDir: .
-  gpuNum: 0
-```
-
-使用下面的命令启动 Experiment：
-
-```bash
-nnictl create --config ./config.yml
-```
\ No newline at end of file

docs/zh_CN/TrialExample/GbdtExample.rst

+GBDT
+===========
+
+梯度提升是机器学习中回归和分类问题的一种方法。它由一组弱分类模型所组成，决策树是其中的典型。 像其它提升方法一样，它也分步来构建模型，并使用可微分的损失函数来优化。
+
+梯度决策树（gradient boosting decision tree，GBDT）有很多流行的实现，如：`lightgbm <https://github.com/Microsoft/LightGBM>`__\ ， `xgboost <https://github.com/dmlc/xgboost>`__\ ， and `catboost <https://github.com/catboost/catboost>`__，等等。 GBDT 是解决经典机器学习问题的重要工具。 GBDT 也是一种鲁棒的算法，可以使用在很多领域。 GBDT 的超参越好，就能获得越好的性能。
+
+NNI 是用来调优超参的平台，可以在 NNI 中尝试各种内置的搜索算法，并行运行多个 Trial。
+
+1. GBDT 的搜索空间
+-----------------------
+
+GBDT 有很多超参，但哪些才会影响性能或计算速度呢？ 基于实践经验，建议如下（以 lightgbm 为例）：
+
+..
+
+   * 获得更好的精度
+   * ``learning_rate``. ``学习率`` 的范围应该是 [0.001, 0.9]。
+
+
+
+* 
+  ``num_leaves``. ``num_leaves`` 与 ``max_depth`` 有关，不必两个值同时调整。
+
+* 
+  ``bagging_freq``. ``bagging_freq`` 可以是 [1, 2, 4, 8, 10]。
+
+* 
+  ``num_iterations``. 如果达到期望的拟合精度，可以调整得大一些。
+
+..
+
+   * 加速
+   * ``bagging_fraction``. ``bagging_fraction`` 的范围应该是 [0.7, 1.0]。
+
+
+
+* 
+  ``feature_fraction``. ``feature_fraction`` 的范围应该是 [0.6, 1.0]。
+
+* 
+  ``max_bin``.
+
+..
+
+   * 避免过拟合
+   * ``min_data_in_leaf``. 取决于数据集。
+
+
+
+* 
+  ``min_sum_hessian_in_leaf``. 取决于数据集。
+
+* 
+  ``lambda_l1`` 和 ``lambda_l2``.
+
+* 
+  ``min_gain_to_split``.
+
+* 
+  ``num_leaves``.
+
+参考链接：
+`lightgbm <https://lightgbm.readthedocs.io/en/latest/Parameters-Tuning.html>`__ 和 `autoxgoboost <https://github.com/ja-thomas/autoxgboost/blob/master/poster_2018.pdf>`__
+
+2. 任务描述
+-------------------
+
+"auto-gbdt" 基于 LightGBM 和 NNI。 数据集有 :githublink:`训练数据 <examples/trials/auto-gbdt/data/regression.train>` and :githublink:`测试数据 <examples/trials/auto-gbdt/data/regression.train>`。
+根据数据中的特征和标签，训练一个 GBDT 回归模型，用来做预测。
+
+3. 如何在 NNI 中运行
+--------------------
+
+3.1 安装所有要求的包
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+   pip install lightgbm
+   pip install pandas
+
+3.2 准备 Trial 代码
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+基础代码如下：
+
+.. code-block:: python
+
+   ...
+
+   def get_default_parameters():
+       ...
+       return params
+
+
+   def load_data(train_path='./data/regression.train', test_path='./data/regression.test'):
+       '''
+       准备数据集
+       '''
+       ...
+
+       return lgb_train, lgb_eval, X_test, y_test
+
+   def run(lgb_train, lgb_eval, params, X_test, y_test):
+       # 训练
+       gbm = lgb.train(params,
+                       lgb_train,
+                       num_boost_round=20,
+                       valid_sets=lgb_eval,
+                       early_stopping_rounds=5)
+       # 预测
+       y_pred = gbm.predict(X_test, num_iteration=gbm.best_iteration)
+
+       # 评估
+       rmse = mean_squared_error(y_test, y_pred) ** 0.5
+       print('The rmse of prediction is:', rmse)
+
+   if __name__ == '__main__':
+       lgb_train, lgb_eval, X_test, y_test = load_data()
+
+       PARAMS = get_default_parameters()
+       # 训练
+       run(lgb_train, lgb_eval, PARAMS, X_test, y_test)
+
+3.3 准备搜索空间
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+如果要调优 ``num_leaves``\ , ``learning_rate``\ , ``bagging_fraction`` 和 ``bagging_freq``，可创建一个 :githublink:`search_space.json <examples/trials/auto-gbdt/search_space.json>` 文件：
+
+.. code-block:: json
+
+   {
+       "num_leaves":{"_type":"choice","_value":[31, 28, 24, 20]},
+       "learning_rate":{"_type":"choice","_value":[0.01, 0.05, 0.1, 0.2]},
+       "bagging_fraction":{"_type":"uniform","_value":[0.7, 1.0]},
+       "bagging_freq":{"_type":"choice","_value":[1, 2, 4, 8, 10]}
+   }
+
+参考 `这里 <../Tutorial/SearchSpaceSpec.rst>`__，了解更多变量类型。
+
+3.4 在代码中使用 NNI SDK
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: diff
+
+   +import nni
+   ...
+
+   def get_default_parameters():
+       ...
+       return params
+
+
+   def load_data(train_path='./data/regression.train', test_path='./data/regression.test'):
+       '''
+       准备数据集
+       '''
+       ...
+
+       return lgb_train, lgb_eval, X_test, y_test
+
+   def run(lgb_train, lgb_eval, params, X_test, y_test):
+       # 训练
+       gbm = lgb.train(params,
+                       lgb_train,
+                       num_boost_round=20,
+                       valid_sets=lgb_eval,
+                       early_stopping_rounds=5)
+       # 预测
+       y_pred = gbm.predict(X_test, num_iteration=gbm.best_iteration)
+
+       # 评估
+       rmse = mean_squared_error(y_test, y_pred) ** 0.5
+       print('The rmse of prediction is:', rmse)
+   +   nni.report_final_result(rmse)
+
+   if __name__ == '__main__':
+       lgb_train, lgb_eval, X_test, y_test = load_data()
+   +   RECEIVED_PARAMS = nni.get_next_parameter()
+       PARAMS = get_default_parameters()
+   +   PARAMS.update(RECEIVED_PARAMS)
+
+       # 训练
+       run(lgb_train, lgb_eval, PARAMS, X_test, y_test)
+
+3.5 实现配置文件并运行
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+在配置文件中，可以设置如下内容：
+
+
+* Experiment 设置： ``trialConcurrency``\ , ``maxExecDuration``\ , ``maxTrialNum``\ , ``trial gpuNum``\ 等。
+* 平台设置： ``trainingServicePlatform``\ 等。
+* 路径设置： ``searchSpacePath``\ , ``trial codeDir``\ 等。
+* 算法设置：选择 ``Tuner`` 算法，``优化方向``，等等。
+
+config.yml 示例：
+
+.. code-block:: yaml
+
+   authorName: default
+   experimentName: example_auto-gbdt
+   trialConcurrency: 1
+   maxExecDuration: 10h
+   maxTrialNum: 10
+   # 选择平台： local, remote, pai
+   trainingServicePlatform: local
+   searchSpacePath: search_space.json
+   # 选择：true, false
+   useAnnotation: false
+   tuner:
+     # 选择：TPE, Random, Anneal, Evolution, BatchTuner
+     # SMAC (SMAC 应该通过 nnictl 安装)
+     builtinTunerName: TPE
+     classArgs:
+       # 选择：maximize, minimize
+       optimize_mode: minimize
+   trial:
+     command: python3 main.py
+     codeDir: .
+     gpuNum: 0
+
+使用下面的命令启动 Experiment：
+
+.. code-block:: bash
+
+   nnictl create --config ./config.yml

docs/zh_CN/TrialExample/KDExample.md

-NNI Compressor 上使用知识蒸馏
-===
-
-## 知识蒸馏 (Knowledge Distillation)
-
-知识蒸馏，在 [Distilling the Knowledge in a Neural Networ](https://arxiv.org/abs/1503.02531) 中，压缩模型被训练成模拟预训练的大模型。  这种训练设置也称为"师生（teacher-student）"方式，其中大模型是教师，小模型是学生。
-
-![](../../img/distill.png)
-
-### 用法
-
-PyTorch 代码
-
-```python
-from knowledge_distill.knowledge_distill import KnowledgeDistill
-kd = KnowledgeDistill(kd_teacher_model, kd_T=5)
-alpha = 1
-beta = 0.8
-for batch_idx, (data, target) in enumerate(train_loader):
-    data, target = data.to(device), target.to(device)
-    optimizer.zero_grad()
-    output = model(data)
-    loss = F.cross_entropy(output, target)
-    # 只需要添加以下行来使用知识蒸馏微调模型
-    loss = alpha * loss + beta * kd.loss(data=data, student_out=output)
-    loss.backward()
-```
-
-#### 知识蒸馏的用户配置
-* **kd_teacher_model:** 预训练过的教师模型
-* **kd_T:** 用于平滑教师模型输出的温度。
-
-完整代码[在这里](https://github.com/microsoft/nni/tree/v1.3/examples/model_compress/knowledge_distill/)。

docs/zh_CN/TrialExample/KDExample.rst

+NNI 上的知识蒸馏
+=============================
+
+知识蒸馏 (Knowledge Distillation)
+---------------------------------------
+
+知识蒸馏，在 `Distilling the Knowledge in a Neural Network <https://arxiv.org/abs/1503.02531>`__ 中，压缩模型被训练成模拟预训练的大模型。  这种训练设置也称为"师生（teacher-student）"方式，其中大模型是教师，小模型是学生。
+
+
+.. image:: ../../img/distill.png
+   :target: ../../img/distill.png
+   :alt: 
+
+
+用法
+^^^^^
+
+PyTorch 代码
+
+.. code-block:: python
+
+   from knowledge_distill.knowledge_distill import KnowledgeDistill
+   kd = KnowledgeDistill(kd_teacher_model, kd_T=5)
+   alpha = 1
+   beta = 0.8
+   for batch_idx, (data, target) in enumerate(train_loader):
+       data, target = data.to(device), target.to(device)
+       optimizer.zero_grad()
+       output = model(data)
+       loss = F.cross_entropy(output, target)
+       # 只需要添加以下行来使用知识蒸馏微调模型
+       loss = alpha * loss + beta * kd.loss(data=data, student_out=output)
+       loss.backward()
+
+知识蒸馏的用户配置
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+* **kd_teacher_model**：预训练过的教师模型 
+* **kd_T**：用于平滑教师模型输出的温度。
+
+完整代码在 `这里 <https://github.com/microsoft/nni/tree/v1.3/examples/model_compress/knowledge_distill/>`__。

docs/zh_CN/TrialExample/MnistExamples.md → docs/zh_CN/TrialExample/MnistExamples.rst

-# MNIST 示例
+.. role:: raw-html(raw)
+   :format: html
 
-在深度学习中，用 CNN 来分类 MNIST 数据，就像介绍编程语言中的 `hello world` 示例。 因此，NNI 将 MNIST 作为示例来介绍功能。 示例如下：
 
-- [MNIST 中使用 NNI API (TensorFlow v1.x)](#mnist-tfv1)
-- [MNIST 中使用 NNI API (TensorFlow v2.x)](#mnist-tfv2)
-- [MNIST 中使用 NNI 标记（annotation）](#mnist-annotation)
-- [在 Keras 中使用 MNIST](#mnist-keras)
-- [MNIST -- 用批处理 Tuner 来调优](#mnist-batch)
-- [MNIST -- 用 hyperband 调优](#mnist-hyperband)
-- [MNIST -- 用嵌套搜索空间调优](#mnist-nested)
-- [用 Kubeflow 运行分布式的 MNIST (tensorflow)](#mnist-kubeflow-tf)
-- [用 Kubeflow 运行分布式的 MNIST (PyTorch)](#mnist-kubeflow-pytorch)
+MNIST 示例
+==============
 
-<a name="mnist-tfv1"></a>
+在深度学习中，用 CNN 来分类 MNIST 数据，就像介绍编程语言中的 ``hello world`` 示例。 因此，NNI 将 MNIST 作为示例来介绍功能。 示例如下：
+
+
+* `MNIST 中使用 NNI API (TensorFlow v1.x) <#mnist-tfv1>`__
+* `MNIST 中使用 NNI API (TensorFlow v2.x) <#mnist-tfv2>`__
+* `MNIST 中使用 NNI 标记（annotation） <#mnist-annotation>`__
+* `在 keras 中使用 MNIST <#mnist-keras>`__
+* `MNIST -- 用批处理 tuner 来调优 <#mnist-batch>`__
+* `MNIST -- 用 hyperband 来调优 <#mnist-hyperband>`__
+* `MNIST -- 用嵌套搜索空间来调优 <#mnist-nested>`__
+* `用 Kubeflow 运行分布式的 MNIST（TensorFlow） <#mnist-kubeflow-tf>`__
+* `用 Kubeflow 运行分布式的 MNIST（PyTorch） <#mnist-kubeflow-pytorch>`__
+
+:raw-html:`<a name="mnist-tfv1"></a>`
 **MNIST 中使用 NNI API (TensorFlow v1.x)**
 
 这是个简单的卷积网络，有两个卷积层，两个池化层和一个全连接层。 调优的超参包括 dropout 比率，卷积层大小，隐藏层（全连接层）大小等等。 它能用 NNI 中大部分内置的 Tuner 来调优，如 TPE，SMAC，Random。 示例的 YAML 文件也启用了评估器来提前终止一些中间结果不好的尝试。
 
-`代码目录: examples/trials/mnist-tfv1/`
+``代码目录：examples/trials/mnist-tfv1/``
 
-<a name="mnist-tfv2"></a>
+:raw-html:`<a name="mnist-tfv2"></a>`
 **MNIST 中使用 NNI API (TensorFlow v2.x)**
 
 与上述示例的网络相同，但使用了 TensorFlow v2.x Keras API。
 
-`代码目录: examples/trials/mnist-tfv2/`
+``代码目录：examples/trials/mnist-tfv2/``
 
-<a name="mnist-annotation"></a>
+:raw-html:`<a name="mnist-annotation"></a>`
 **MNIST 中使用 NNI 标记（annotation）**
 
-此示例与上例类似，上例使用的是 NNI API 来指定搜索空间并返回结果，而此例使用的是 NNI 标记。
+此样例与上例类似，上例使用的是 NNI API 来指定搜索空间并返回结果，而此例使用的是 NNI 标记。
 
-`代码目录: examples/trials/mnist-annotation/`
+``代码目录：examples/trials/mnist-annotation/``
 
-<a name="mnist-keras"></a>
+:raw-html:`<a name="mnist-keras"></a>`
 **在 Keras 中使用 MNIST**
 
-此示例由 Keras 实现。 这也是 MNIST 数据集的网络，包括两个卷积层，一个池化层和两个全连接层。
+此样例由 Keras 实现。 这也是 MNIST 数据集的网络，包括两个卷积层，一个池化层和两个全连接层。
 
-`代码目录: examples/trials/mnist-keras/`
+``代码目录：examples/trials/mnist-keras/``
 
-<a name="mnist-batch"></a>
+:raw-html:`<a name="mnist-batch"></a>`
 **MNIST -- 用批处理 Tuner 来调优**
 
-此示例演示了如何使用批处理 Tuner。 只需要在搜索空间文件中列出所有要尝试的配置， NNI 会逐个尝试。
+此样例演示了如何使用批处理 Tuner。 只需要在搜索空间文件中列出所有要尝试的配置， NNI 会逐个尝试。
 
-`代码目录: examples/trials/mnist-batch-tune-keras/`
+``代码目录：examples/trials/mnist-batch-tune-keras/``
 
-<a name="mnist-hyperband"></a>
+:raw-html:`<a name="mnist-hyperband"></a>`
 **MNIST -- 用 hyperband 调优**
 
-此示例演示了如何使用 hyperband 来调优模型。 在尝试收到的配置中，有个主键叫做 `STEPS`，尝试要用它来控制运行多长时间（例如，控制迭代的次数）。
+此样例演示了如何使用 hyperband 来调优模型。 在尝试收到的配置中，有个主键叫做 ``STEPS``，尝试要用它来控制运行多长时间（例如，控制迭代的次数）。
 
-`代码目录: examples/trials/mnist-hyperband/`
+``代码目录：examples/trials/mnist-hyperband/``
 
-<a name="mnist-nested"></a>
+:raw-html:`<a name="mnist-nested"></a>`
 **MNIST -- 用嵌套搜索空间调优**
 
-此示例演示了 NNI 如何支持嵌套的搜索空间。 搜索空间文件示了如何定义嵌套的搜索空间。
+此样例演示了 NNI 如何支持嵌套的搜索空间。 搜索空间文件示了如何定义嵌套的搜索空间。
 
-`代码目录: examples/trials/mnist-nested-search-space/`
+``代码目录：examples/trials/mnist-nested-search-space/``
 
-<a name="mnist-kubeflow-tf"></a>
+:raw-html:`<a name="mnist-kubeflow-tf"></a>`
 **用 Kubeflow 运行分布式的 MNIST (tensorflow)**
 
-此示例展示了如何通过 NNI 来在 Kubeflow 上运行分布式训练。 只需要简单的提供分布式训练代码，并在配置文件中指定 kubeflow 模式。 例如，运行 ps 和 worker 的命令行，以及各自需要的资源。 此示例使用了 Tensorflow 来实现，因而，需要使用 Kubeflow 的 tf-operator。
+此样例展示了如何通过 NNI 来在 Kubeflow 上运行分布式训练。 只需要简单的提供分布式训练代码，并在配置文件中指定 kubeflow 模式。 例如，运行 ps 和 worker 的命令行，以及各自需要的资源。 此样例使用了 Tensorflow 来实现，因而，需要使用 Kubeflow 的 tf-operator。
 
-`代码目录: examples/trials/mnist-distributed/`
+``代码目录：examples/trials/mnist-distributed/``
 
-<a name="mnist-kubeflow-pytorch"></a>
+:raw-html:`<a name="mnist-kubeflow-pytorch"></a>`
 **用 Kubeflow 运行分布式的 MNIST (PyTorch)**
 
-与前面的示例类似，不同之处是此示例是 Pytorch 实现的，因而需要使用 Kubeflow 的 pytorch-operator。
+与前面的样例类似，不同之处是此样例是 Pytorch 实现的，因而需要使用 Kubeflow 的 pytorch-operator。
 
-`代码目录: examples/trials/mnist-distributed-pytorch/`
\ No newline at end of file
+``代码目录：examples/trials/mnist-distributed-pytorch/``

docs/zh_CN/TrialExample/OpEvoExamples.md → docs/zh_CN/TrialExample/OpEvoExamples.rst

-# NNI 上调优张量算子
+.. role:: raw-html(raw)
+   :format: html
 
-## 概述
+
+NNI 上调优张量算子
+==============================
+
+概述
+--------
 
 深度神经网络（DNN）的大量应用，催生了对从云服务器到嵌入式设备等不同硬件平台上的训练和推理的需求。 此外，还有深度神经网络上的计算图优化问题，如张量算子融合会引入新的张量算子。 然而，人工通过特定硬件库来优化张量算子，不能很好的支持新硬件平台和新算子，存在一定的局限性。因此，在大规模部署和深度学习技术的实际场景中，不同平台上的自动化的张量算子优化变得非常重要。
 
 张量算子优化的本质，是一个组合优化问题。 目标函数是张量算子在某个硬件平台上的性能，通过调整超参（如，如何切片矩阵，展开循环）实现该平台上的最佳性能。 与许多典型的此类问题（如旅行推销员问题）不同，张量算子优化的目标函数是黑盒，采样成本较高。 必须用特定的配置编译设备代码，并在真实的硬件上运行，以获得相应的性能指标。 因此，理想的张量算子优化方法应该在尽可能少的样本下找到最佳的配置。
 
-代价昂贵的目标函数使得用传统的组合优化方法，如模拟退火和进化算法求解张量算子优化问题几乎不可能。 尽管这些算法本质上支持组合搜索空间，但它们并未考虑采样效率，因此通常需要成千上万甚至更多的样本，这在生产环境中调整张量算子时是不可接受的。 另一方面，事实证明，基于序列模型的优化（SMBO）方法可有效地优化具有连续搜索空间的黑盒函数。 然而，在使用组合搜索空间进行优化时，SMBO 方法的采样效率不及连续搜索方法，这是因为缺少关于目标函数的先验假设，例如连续搜索空间的连续性和可微性。 例如，如果可以假设具有连续搜索空间的目标函数是无限可微的，则可以使用具有径向基函数（RBF）核的高斯过程对目标函数进行建模。 这样，一个样本不仅提供了一个点上的单一值，而且还提供了目标函数在其邻域上的局部性质，甚至是全局性质，从而获得了较高的采样效率。 相比之下，用于组合优化的SMBO方法由于缺乏适当的先验假设和可以利用它们的替代模型而导致采样效率低下。
-
-最近提出的 OpEvo 就是为了解决这个具有挑战性的问题。 它通过引入基于 q-随机游走分布的拓扑感知突变操作来利用搜索空间上的拓扑结构，有效地探索了张量算子的搜索空间。 在本例中，可以使用OpEvo调优从两个流行的神经网络（BERT和AlexNet）中选择的三种代表性张量算子。 还提供了三个比较基线：AutoTVM，G-BFS和N-A2C。 参考论文 [OpEvo: An Evolutionary Method for Tensor Operator Optimization](https://arxiv.org/abs/2006.05664) 来了解算法。
-
-## 配置环境
-
-此示例准备了 Dockerfile 作为 Experiment 的环境。 开始前，确保 Docker 守护进程已启动，GPU 加速驱动已正确安装。 进入示例目录 `examples/trials/systems/opevo` 并运行下列命令，从 Dockerfile 构建并实例化 Docker 映像。
-```bash
-# 如果使用 Nvidia GPU
-make cuda-env
-# 如果使用 AMD GPU
-make rocm-env
-```
-
-## 运行 Experiment
-
-这里从 BERT 和 AlexNet 中选择了三种有代表性的张量算子：**矩阵乘法**、**批处理的矩阵乘法**，以及**二维卷积**，并使用 NNI 进行调优。 所有张量算子的 `Trial` 代码都是 `/root/compiler_auto_tune_stable.py`，每个调优算法的`搜索空间`和`配置`文件都在按张量算子分类的 `/root/experiments/` 目录中。 这里的 `/root` 表示容器中的 root 目录。
-
-在 `/root` 中运行以下命令来调优矩阵乘法：
-```bash
-# (N, K) x (K, M) 表示形状为 (N, K) 的矩阵乘以形状为 (K, M) 的矩阵
-
-# (512, 1024) x (1024, 1024)
-# 用 OpenEvo 调优
-nnictl create --config experiments/mm/N512K1024M1024/config_opevo.yml
-# 用 G-BFS 调优
-nnictl create --config experiments/mm/N512K1024M1024/config_gbfs.yml
-# 用 N-A2C 调优
-nnictl create --config experiments/mm/N512K1024M1024/config_na2c.yml
-# 用 AutoTVM 调优
-OP=matmul STEP=512 N=512 M=1024 K=1024 P=NN ./run.s
-
-# (512, 1024) x (1024, 4096)
-# 用 OpenEvo 调优
-nnictl create --config experiments/mm/N512K1024M4096/config_opevo.yml
-# 用 G-BFS 调优
-nnictl create --config experiments/mm/N512K1024M4096/config_gbfs.yml
-# 用 N-A2C调优
-nnictl create --config experiments/mm/N512K1024M4096/config_na2c.yml
-# 用 AutoTVM 调优
-OP=matmul STEP=512 N=512 M=1024 K=4096 P=NN ./run.sh
-
-# (512, 4096) x (4096, 1024)
-# 用 OpenEvo 调优
-nnictl create --config experiments/mm/N512K4096M1024/config_opevo.yml
-# 用 G-BFS 调优
-nnictl create --config experiments/mm/N512K4096M1024/config_gbfs.yml
-# 用 N-A2C调优
-nnictl create --config experiments/mm/N512K4096M1024/config_na2c.yml
-# 用 AutoTVM 调优
-OP=matmul STEP=512 N=512 M=4096 K=1024 P=NN ./run.sh
-```
-
-在 `/root` 中运行以下命令来调优批处理矩阵乘法：
-```bash
-# 批处理大小为 960，形状为 (128, 128) 的矩阵，乘以批处理大小为 960，形状为 (128, 64) 的矩阵
-# 用 OpEvo 调优
-nnictl create --config experiments/bmm/B960N128K128M64PNN/config_opevo.yml
-# 用 AutoTVM 调优
-OP=batch_matmul STEP=512 B=960 N=128 K=128 M=64 P=NN ./run.sh
-
-# 批处理大小为 960，形状为 (128, 128) 的矩阵，先转置，然后乘以批处理大小为 960，形状为 (128, 64) 的矩阵
-# 用 OpEvo 调优
-nnictl create --config experiments/bmm/B960N128K128M64PTN/config_opevo.yml
-# 用 AutoTVM 调优
-OP=batch_matmul STEP=512 B=960 N=128 K=128 M=64 P=TN ./run.sh
-
-# 批处理大小为 960，形状为 (128, 128) 的矩阵，先转置，然后右乘批处理大小为 960，形状为 (128, 64) 的矩阵
-# 用 OpEvo 调优
-nnictl create --config experiments/bmm/B960N128K64M128PNT/config_opevo.yml
-# 用 AutoTVM 调优
-OP=batch_matmul STEP=512 B=960 N=128 K=64 M=128 P=NT ./run.sh
-```
-
-在 `/root` 中运行以下命令来调优二维卷积：
-```bash
-# 形状为（512，3，227，227）的图像张量与形状为（64，3，11，11）的内核张量以步幅 4 和填充 0 卷积
-# 用 OpEvo 调优
-nnictl create --config experiments/conv/N512C3HW227F64K11ST4PD0/config_opevo.yml
-# 用 AutoTVM 调优
-OP=convfwd_direct STEP=512 N=512 C=3 H=227 W=227 F=64 K=11 ST=4 PD=0 ./run.sh
-
-# 形状为（512，64，27，27）的图像张量和形状为（192，64，5，5）的内核张量以步幅 1 和填充 2 卷积
-# 用 OpEvo 调优
-nnictl create --config experiments/conv/N512C64HW27F192K5ST1PD2/config_opevo.yml
-# 用 AutoTVM 调优
-OP=convfwd_direct STEP=512 N=512 C=64 H=27 W=27 F=192 K=5 ST=1 PD=2 ./run.sh
-```
-
-请注意，G-BFS 和 N-A2C 这两种方法是专为优化行和列为2的幂的矩阵相乘的平铺（tiling）策略而设计的，所以他们不能够兼容其他类型的搜索空间，因此不能够用来优化批量矩阵乘和2维卷积这两种张量算子。 这里，AutoTVM是由作者在 TVM 项目中实现的，因此调优结果打印在屏幕上，而不是报告给 NNI 管理器。 容器的端口 8080 绑定到主机的同一端口，因此可以通过 `host_ip_addr:8080` 访问NNI Web 界面，并监视调优过程，如下面的屏幕截图所示。
-
-<img src="../../../examples/trials/systems/opevo/screenshot.png" />
-
-## 引用 OpEvo
+代价昂贵的目标函数使得用传统的组合优化方法，如模拟退火和进化算法求解张量算子优化问题几乎不可能。 尽管这些算法本质上支持组合搜索空间，但它们并未考虑采样效率，
+因此通常需要成千上万甚至更多的样本，这在生产环境中调整张量算子时是不可接受的。 另一方面，事实证明，基于序列模型的优化（SMBO）方法可有效地优化具有连续搜索空间的黑盒函数。 然而，在使用组合搜索空间进行优化时，SMBO 方法的采样效率不及连续搜索方法，这是因为缺少关于目标函数的先验假设，例如连续搜索空间的连续性和可微性。 例如，如果可以假设具有连续搜索空间的目标函数是无限可微的，则可以使用具有径向基函数（RBF）核的高斯过程对目标函数进行建模。 这样，一个样本不仅提供了一个点上的单一值，而且还提供了目标函数在其邻域上的局部性质，甚至是全局性质，
+从而获得了较高的采样效率。 相比之下，用于组合优化的SMBO方法由于缺乏适当的先验假设和可以利用它们的替代模型而导致采样效率低下。
+
+最近提出的 OpEvo 就是为了解决这个具有挑战性的问题。 它通过引入基于 q-随机游走分布的拓扑感知突变操作来利用搜索空间上的拓扑结构，有效地探索了张量算子的搜索空间。 在本例中，可以使用OpEvo调优从两个流行的神经网络（BERT和AlexNet）中选择的三种代表性张量算子。 还提供了三个比较基线：AutoTVM，G-BFS和N-A2C。 请参考 `OpEvo: An Evolutionary Method for Tensor Operator Optimization <https://arxiv.org/abs/2006.05664>`__ 获取算法的更多细节。
+
+配置环境
+-----------------
+
+此示例准备了 Dockerfile 作为 Experiment 的环境。 开始前，确保 Docker 守护进程已启动，GPU 加速驱动已正确安装。 进入示例目录 ``examples/trials/systems/opevo`` 并运行下列命令，从 Dockerfile 构建并实例化 Docker 映像。
+
+.. code-block:: bash
+
+   # 如果使用 NVIDIA GPU
+   make cuda-env
+   # 如果使用 AMD GPU
+   make rocm-env
+
+运行 Experiment
+----------------
+
+这里从 BERT 和 AlexNet 中选择了三种有代表性的张量算子：**矩阵乘法**、**批处理的矩阵乘法**，以及 **二维卷积**，并使用 NNI 进行调优。 所有张量算子的 ``Trial`` 代码都是 ``/root/compiler_auto_tune_stable.py``，每个调优算法的 ``搜索空间`` 和 ``配置`` 文件都在按张量算子分类的 ``/root/experiments/`` 目录中。 这里的 ``/root`` 表示容器中的 root 目录。
+
+在 ``/root`` 中运行以下命令来调优矩阵乘法：
+
+.. code-block:: bash
+
+   # (N, K) x (K, M) 表示形状为 (N, K) 的矩阵乘以形状为 (K, M) 的矩阵
+
+   # (512, 1024) x (1024, 1024)
+   # 用 OpEvo 调优
+   nnictl create --config experiments/mm/N512K1024M1024/config_opevo.yml
+   # 用 G-BFS 调优
+   nnictl create --config experiments/mm/N512K1024M1024/config_gbfs.yml
+   # 用 N-A2C 调优
+   nnictl create --config experiments/mm/N512K1024M1024/config_na2c.yml
+   # 用 AutoTVM 调优
+   OP=matmul STEP=512 N=512 M=1024 K=1024 P=NN ./run.s
+
+   # (512, 1024) x (1024, 4096)
+   # 用 OpEvo 调优
+   nnictl create --config experiments/mm/N512K1024M4096/config_opevo.yml
+   # 用 G-BFS 调优
+   nnictl create --config experiments/mm/N512K1024M4096/config_gbfs.yml
+   # 用 N-A2C 调优
+   nnictl create --config experiments/mm/N512K1024M4096/config_na2c.yml
+   # 用 AutoTVM 调优
+   OP=matmul STEP=512 N=512 M=1024 K=4096 P=NN ./run.sh
+
+   # (512, 4096) x (4096, 1024)
+   # 用 OpEvo 调优
+   nnictl create --config experiments/mm/N512K4096M1024/config_opevo.yml
+   # 用 G-BFS 调优
+   nnictl create --config experiments/mm/N512K4096M1024/config_gbfs.yml
+   # 用 N-A2C 调优
+   nnictl create --config experiments/mm/N512K4096M1024/config_na2c.yml
+   # 用 AutoTVM 调优
+   OP=matmul STEP=512 N=512 M=4096 K=1024 P=NN ./run.sh
+
+在 ``/root`` 中运行以下命令来调优矩阵乘法：
+
+.. code-block:: bash
+
+   # 批处理大小为 960，形状为 (128, 128) 的矩阵，乘以批处理大小为 960，形状为 (128, 64) 的矩阵
+   # 用 OpEvo 调优
+   nnictl create --config experiments/bmm/B960N128K128M64PNN/config_opevo.yml
+   # 用 AutoTVM 调优
+   OP=batch_matmul STEP=512 B=960 N=128 K=128 M=64 P=NN ./run.sh
+
+   # 批处理大小为 960，形状为 (128, 128) 的矩阵，先转置，然后乘以批处理大小为 960，形状为 (128, 64)
+   # 用 OpEvo 调优
+   nnictl create --config experiments/bmm/B960N128K128M64PTN/config_opevo.yml
+   # 用 AutoTVM 调优
+   OP=batch_matmul STEP=512 B=960 N=128 K=128 M=64 P=TN ./run.sh
+
+   # 批处理大小为 960，形状为 (128, 128) 的矩阵，先转置，然后右乘批处理大小为 960，形状为 (128, 64)
+   # 用 OpEvo 调优
+   nnictl create --config experiments/bmm/B960N128K64M128PNT/config_opevo.yml
+   # 用 AutoTVM 调优
+   OP=batch_matmul STEP=512 B=960 N=128 K=64 M=128 P=NT ./run.sh
+
+在 ``/root`` 中运行以下命令来调优二维卷积：
+
+.. code-block:: bash
+
+   # 形状为（512，3，227，227）的图像张量与形状为（64，3，11，11）的内核张量以步幅 4 和填充 0 卷积
+   # 用 OpEvo 调优
+   nnictl create --config experiments/conv/N512C3HW227F64K11ST4PD0/config_opevo.yml
+   # 用 AutoTVM 调优
+   OP=convfwd_direct STEP=512 N=512 C=3 H=227 W=227 F=64 K=11 ST=4 PD=0 ./run.sh
+
+   # 形状为（512，64，27，27）的图像张量和形状为（192，64，5，5）的内核张量以步幅 1 和填充 2 卷积
+   # 用 OpEvo 调优
+   nnictl create --config experiments/conv/N512C64HW27F192K5ST1PD2/config_opevo.yml
+   # 用 AutoTVM 调优
+   OP=convfwd_direct STEP=512 N=512 C=64 H=27 W=27 F=192 K=5 ST=1 PD=2 ./run.sh
+
+请注意，G-BFS 和 N-A2C 这两种方法是专为优化行和列为2的幂的矩阵相乘的平铺（tiling）策略而设计的，所以他们不能够兼容其他类型的搜索空间，因此不能够用来优化批量矩阵乘和2维卷积这两种张量算子。 这里，AutoTVM是由作者在 TVM 项目中实现的，因此调优结果打印在屏幕上，而不是报告给 NNI 管理器。 容器的端口 8080 绑定到主机的同一端口，因此可以通过 ``host_ip_addr:8080`` 访问 NNI Web 界面，并监视调优过程，如下面的屏幕截图所示。
+
+:raw-html:`<img src="https://github.com/microsoft/nni/blob/v2.0/docs/img/opevo.png?raw=true" />`
+
+引用 OpEvo
+------------
 
 如果认为 OpEvo 有帮助，请考虑如下引用论文：
-```
-@misc{gao2020opevo,
-    title={OpEvo: An Evolutionary Method for Tensor Operator Optimization},
-    author={Xiaotian Gao and Cui Wei and Lintao Zhang and Mao Yang},
-    year={2020},
-    eprint={2006.05664},
-    archivePrefix={arXiv},
-    primaryClass={cs.LG}
-}
-```
+
+.. code-block:: bash
+
+   @misc{gao2020opevo,
+       title={OpEvo: An Evolutionary Method for Tensor Operator Optimization},
+       author={Xiaotian Gao and Cui Wei and Lintao Zhang and Mao Yang},
+       year={2020},
+       eprint={2006.05664},
+       archivePrefix={arXiv},
+       primaryClass={cs.LG}
+   }

docs/zh_CN/TrialExample/RocksdbExamples.md

-# 在 NNI 上调优 RocksDB
-
-## 概述
-
-[RocksDB](https://github.com/facebook/rocksdb) 是流行的高性能、嵌入式的生产级别的键值数据库，它在 Facebook，Yahoo!，和 LinkedIn 等各种规模的网站上使用。 这是 Facebook 的 [LevelDB](https://github.com/google/leveldb) 分支，为多 CPU，快速存储（如 SSD）的输入输出进行了优化。
-
-RocksDB 的性能表现非常依赖于调优操作。 但由于其底层技术较复杂，可配置参数非常多，很难获得较好的配置。 NNI 可帮助解决此问题。 NNI 支持多种调优算法来为 RocksDB 搜索最好的配置，并支持本机、远程服务器和云服务等多种环境。
-
-本示例展示了如何使用 NNI，通过评测工具 `db_bench` 来找到 `fillrandom` 基准的最佳配置，此工具是 RocksDB 官方提供的评测工具。 在运行示例前，需要检查 NNI 已安装，
-
-db_bench</code> 已经加入到了 `PATH` 中。 参考[这里](../Tutorial/QuickStart.md)，了解如何安装并准备 NNI 环境，参考[这里](https://github.com/facebook/rocksdb/blob/master/INSTALL.md)来编译 RocksDB 以及 `db_bench`。</p> 
-
-此简单脚本 [`db_bench_installation.sh`](https://github.com/microsoft/nni/tree/master/examples/trials/systems/rocksdb-fillrandom/db_bench_installation.sh) 可帮助编译并在 Ubuntu 上安装 `db_bench` 及其依赖包。 可遵循相同的过程在其它系统中安装 RocksDB。
-
-*代码路径：[`example/trials/systems/rocksdb-fillrandom`](https://github.com/microsoft/nni/tree/master/examples/trials/systems/rocksdb-fillrandom)*
-
-
-
-## Experiment 设置
-
-在 NNI 上配置调优的 Experiment 主要有三个步骤。 使用 `json` 文件定义搜索空间，编写评测代码，将配置传入 NNI 管理器来启动 Experiment。
-
-
-
-### 搜索空间
-
-为简单起见，此示例仅调优三个参数，`write_buffer_size`, `min_write_buffer_num` 以及 `level0_file_num_compaction_trigger`，场景为测试随机写入 16M 数据的每秒写操作数（OPS），其 Key 为 20 字节，值为 100 字节。 `write_buffer_size` 设置单个内存表的大小。 一旦内存表超过此大小，会被标记为不可变，并创建新内存表。 `min_write_buffer_num` 是要合并写入存储的最小内存表数量。 一旦 Level 0 的文件数量达到了 `level0_file_num_compaction_trigger`，就会触发 Level 0 到 Level 1 的压缩。
-
-此示例中，下列 `search_space.json` 文件指定了搜索空间。 搜索空间的详细说明参考[这里](../Tutorial/SearchSpaceSpec.md)。
-
-
-
-```json
-{
-    "write_buffer_size": {
-        "_type": "quniform",
-        "_value": [2097152, 16777216, 1048576]
-    },
-    "min_write_buffer_number_to_merge": {
-        "_type": "quniform",
-        "_value": [2, 16, 1]
-    },
-    "level0_file_num_compaction_trigger": {
-        "_type": "quniform",
-        "_value": [2, 16, 1]
-    }
-}
-```
-
-
-*代码路径：[`example/trials/systems/rocksdb-fillrandom/search_space.json`](https://github.com/microsoft/nni/tree/master/examples/trials/systems/rocksdb-fillrandom/search_space.json)*
-
-
-
-### 评测代码
-
-评测代码从 NNI 管理器接收配置，并返回相应的基准测试结果。 下列 NNI API 用于相应的操作。 此示例中，每秒写操作数（OPS）作为了性能指标。 参考[这里](Trials.md)，了解详情。
-
-* 使用 `nni.get_next_parameter()` 来获取下一个系统配置。
-* 使用 `nni.report_final_result(metric)` 来返回测试结果。
-
-*代码路径：[`example/trials/systems/rocksdb-fillrandom/main.py`](https://github.com/microsoft/nni/tree/master/examples/trials/systems/rocksdb-fillrandom/main.py)*
-
-
-
-### 配置文件
-
-用于启动 NNI Experiment 的配置文件。 NNI 的配置文件是 `YAML` 格式，通常包括了 Experiment 设置 (`trialConcurrency`, `maxExecDuration`, `maxTrialNum`, `trial gpuNum`, 等)，平台设置 (`trainingServicePlatform`, 等), 路径设置 (`searchSpacePath`, `trial codeDir`, 等) 以及 Tuner 设置 (`tuner`, `tuner optimize_mode`, 等)。 参考[这里](../Tutorial/QuickStart.md)了解详情。
-
-这是使用 SMAC 算法调优 RocksDB 的示例：
-
-*代码路径：[`example/trials/systems/rocksdb-fillrandom/config_smac.yml`](https://github.com/microsoft/nni/tree/master/examples/trials/systems/rocksdb-fillrandom/config_smac.yml)*
-
-这是使用 TPE 算法调优 RocksDB 的示例：
-
-*代码路径：[`example/trials/systems/rocksdb-fillrandom/config_tpe.yml`](https://github.com/microsoft/nni/tree/master/examples/trials/systems/rocksdb-fillrandom/config_tpe.yml)*
-
-其它 Tuner 算法可以通过相同的方式来使用。 参考[这里](../Tuner/BuiltinTuner.md)了解详情。
-
-最后，进入示例目录，并通过下列命令启动 Experiment：
-
-
-
-```bash
-# 使用 SMAC Tuner 调优 RocksDB
-nnictl create --config ./config_smac.yml
-# 使用 TPE Tuner 调优 RocksDB
-nnictl create --config ./config_tpe.yml
-```
-
-
-
-
-## Experiment 结果
-
-在同一台计算机上运行这两个示例的详细信息：
-
-* 16 * Intel(R) Xeon(R) CPU E5-2650 v2 @ 2.60GHz
-* 465 GB 磁盘，安装 ext4 操作系统
-* 128 GB 内存
-* 内核版本: 4.15.0-58-generic
-* NNI 版本: v1.0-37-g1bd24577
-* RocksDB 版本: 6.4
-* RocksDB DEBUG_LEVEL: 0
-
-详细的实验结果如下图所示。 水平轴是 Trial 的顺序。 垂直轴是指标，此例中为写入的 OPS。 蓝点表示使用的是 SMAC Tuner，橙色表示使用的是 TPE Tuner。 
-
-![image](https://github.com/microsoft/nni/tree/master/examples/trials/systems/rocksdb-fillrandom/plot.png)
-
-下表列出了两个 Tuner 获得的最佳 Trial 以及相应的参数和指标。 不出所料，两个 Tuner 都为 `fillrandom` 测试找到了一样的最佳配置。
-
-| Tuner | 最佳 Trial | 最佳 OPS | write_buffer_size | min_write_buffer_number_to_merge | level0_file_num_compaction_trigger |
-|:-----:|:--------:|:------:|:-------------------:|:------------------------------------:|:--------------------------------------:|
-| SMAC  |   255    | 779289 |       2097152       |                 7.0                  |                  7.0                   |
-|  TPE  |   169    | 761456 |       2097152       |                 7.0                  |                  7.0                   |