Merge branch 'master' into nn-meter

docs/zh_CN/TrainingService/HowToImplementTrainingService.rst

@@ -15,8 +15,7 @@ TrainingService 是与平台管理、任务调度相关的模块。 TrainingServ
    :alt: 
 
 
-NNI 的架构如图所示。 NNIManager 是系统的核心管理模块，负责调用 TrainingService 来管理 Trial，并负责不同模块之间的通信。 Dispatcher 是消息处理中心。 TrainingService 是管理任务的模块，它和 NNIManager 通信，并且根据平台的特点有不同的实现。 NNI 目前支持的平台有 `本地平台 <LocalMode.rst>`__\ 
- ，`远程平台 <RemoteMachineMode.rst>`__\ ， `PAI <PaiMode.rst>`__\ ， `kubeflow <KubeflowMode.rst>`__ 和 `FrameworkController <FrameworkControllerMode.rst>`__。
+NNI 的架构如图所示。 NNIManager 是系统的核心管理模块，负责调用 TrainingService 来管理 Trial，并负责不同模块之间的通信。 Dispatcher 是消息处理中心。 TrainingService 是管理任务的模块，它和 NNIManager 通信，并且根据平台的特点有不同的实现。 ，`远程平台 <RemoteMachineMode.rst>`__\ ， `PAI <PaiMode.rst>`__\ ， `kubeflow <KubeflowMode.rst>`__ 和 `FrameworkController <FrameworkControllerMode.rst>`__。
 
 本文中，会介绍 TrainingService 的简要设计。 如果要添加新的 TrainingService，只需要继承 TrainingServcie 类并实现相应的方法，不需要理解NNIManager、Dispatcher 等其它模块的细节。
 

docs/zh_CN/TrainingService/HybridMode.rst

@@ -15,40 +15,25 @@
 
 .. code-block:: yaml
 
-    authorName: default
     experimentName: example_mnist
+    searchSpacePath: search_space.json
+    command: python3 mnist.py
+    codeDir: .
     trialConcurrency: 2
+    gpuNum: 1
     maxExecDuration: 1h
     maxTrialNum: 10
-    trainingServicePlatform: hybrid
-    searchSpacePath: search_space.json
-    # 可选项：true, false
-    useAnnotation: false
     tuner:
       builtinTunerName: TPE
       classArgs:
-        # 可选项: maximize, minimize
         optimize_mode: maximize
-    trial:
-      command: python3 mnist.py
-      codeDir: .
-      gpuNum: 1
-    hybridConfig:
     trainingServicePlatforms:
-        - local
       - remote
-    remoteConfig:
-      reuse: true
         machineList:
           - ip: 10.1.1.1
             username: bob
             passwd: bob123
+      - local
 
-混合模式的配置：
-
-hybridConfig:
-
-* trainingServicePlatforms. 必填。 该字段指定用于混合模式的平台，值使用 yaml 列表格式。 NNI 支持在此字段中设置 ``local``, ``remote``, ``aml``, ``pai`` 。
-
-
-.. Note:: 如果将平台设置为 trainingServicePlatforms 模式，则用户还应该为平台设置相应的配置。 例如，如果使用 ``remote`` 作为平台，还应设置 ``machineList`` 和 ``remoteConfig`` 配置。 混合模式下的本地平台暂时不支持Windows。
+要使用混合训练平台，用户应在 `trainingService` 字段中将训练平台设置为列表。  
+目前，混合训练平台只支持 `local`, `remote`, `pai` 和 `aml` 训练平台。

docs/zh_CN/TrainingService/KubeflowMode.rst

 在 Kubeflow 上运行 Experiment
 =============================
 
-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 作业来运行。
+NNI 支持在 `Kubeflow <https://github.com/kubeflow/kubeflow>`__ 上运行，称为 kubeflow 模式。 NNI 支持基于 Azure Kubernetes Service 的 Kubeflow，参考 `指南 <https://azure.microsoft.com/zh-cn/services/kubernetes-service/>`__ 来设置 Azure Kubernetes Service。 如果不熟悉 Kubernetes，可先浏览 `这里 <https://kubernetes.io/docs/tutorials/kubernetes-basics/>`__ 。 在 kubeflow 模式下，每个 Trial 程序会在 Kubernetes 集群中作为一个 Kubeflow 作业来运行。
 
 私有部署的 Kubernetes 的准备工作
 -----------------------------------------------
@@ -24,8 +24,8 @@ Azure 部署的 Kubernetes 的准备工作
 -----------------------------------------
 
 
-#. NNI 支持基于 Azure Kubernetes Service 的 Kubeflow，参考 `指南 <https://azure.microsoft.com/zh-cn/services/kubernetes-service/>`__ 来设置 Azure Kubernetes Service。
 #. 安装 `Azure CLI <https://docs.microsoft.com/zh-cn/cli/azure/install-azure-cli?view=azure-cli-latest>`__ 和 ``kubectl``。  使用 ``az login`` 命令来设置 Azure 账户，并将 kubectl 客户端连接到 AKS，参考此 `指南 <https://docs.microsoft.com/zh-cn/azure/aks/kubernetes-walkthrough#connect-to-the-cluster>`__。
+#. NNI 需要访问密钥来连接 Azure 存储服务，NNI 使用 `Azure Key Vault <https://azure.microsoft.com/zh-cn/services/key-vault/>`__ 服务来保护私钥。 设置 Azure Key Vault 服务，并添加密钥到 Key Vault 中来存取 Azure 存储账户。 参考 `指南 <https://docs.microsoft.com/zh-cn/azure/key-vault/quick-create-cli>`__ 来存储访问密钥。  使用 ``az login`` 命令来设置 Azure 账户，并将 kubectl 客户端连接到 AKS，参考此 `指南 <https://docs.microsoft.com/zh-cn/azure/aks/kubernetes-walkthrough#connect-to-the-cluster>`__。
 #. 在 Azure Kubernetes Service 上部署 Kubeflow，参考此 `指南 <https://www.kubeflow.org/docs/started/getting-started/>`__。
 #. 参考此 `指南 <https://docs.microsoft.com/zh-cn/azure/storage/common/storage-quickstart-create-account?tabs=portal>`__ 来创建 Azure 文件存储账户。 NNI 需要 Azure Storage Service 来存取代码和输出文件。
 #. NNI 需要访问密钥来连接 Azure 存储服务，NNI 使用 `Azure Key Vault <https://azure.microsoft.com/zh-cn/services/key-vault/>`__ 服务来保护私钥。 设置 Azure Key Vault 服务，并添加密钥到 Key Vault 中来存取 Azure 存储账户。 参考 `指南 <https://docs.microsoft.com/zh-cn/azure/key-vault/quick-create-cli>`__ 来存储访问密钥。
@@ -40,7 +40,7 @@ Azure 部署的 Kubernetes 的准备工作
 
 Kubeflow 训练平台会实例化一个 Kubernetes 客户端来与 Kubernetes 集群的 API 服务器交互。
 
-对于每个 Trial，会上传本机 codeDir 路径（在 nni_config.yml 中配置）中的所有文件，包括 parameter.cfg 这样的生成的文件到存储卷中。 当前支持两种存储卷：`nfs <https://en.wikipedia.org/wiki/Network_File_System>`__ 和 `azure file storage <https://azure.microsoft.com/zh-cn/services/storage/files/>`__，需要在 NNI 的 YAML 文件中进行配置。 当文件准备好后，Kubeflow 训练平台会调用 Kubernetes 的 API 来创建 Kubeflow 作业 (\ `tf-operator <https://github.com/kubeflow/tf-operator>`__ 作业或 `pytorch-operator <https://github.com/kubeflow/pytorch-operator>`__ 作业) ，并将存储卷挂载到作业的 pod 中。 Kubeflow 作业的输出文件，例如 stdout, stderr, trial.log 以及模型文件，也会被复制回存储卷。 NNI 会在网页中显示每个 Trial 的存储卷的 URL，以便浏览日志和输出文件。
+对于每个 Trial，会上传本机 codeDir 路径（在 nni_config.yml 中配置）中的所有文件，包括 parameter.cfg 这样的生成的文件到存储卷中。 如果使用了 Azure 存储，需要在 YAML 文件中如下设置 ``kubeflowConfig``： 当文件准备好后，Kubeflow 训练平台会调用 Kubernetes 的 API 来创建 Kubeflow 作业 (\ `tf-operator <https://github.com/kubeflow/tf-operator>`__ 作业或 `pytorch-operator <https://github.com/kubeflow/pytorch-operator>`__ 作业) ，并将存储卷挂载到作业的 pod 中。 Kubeflow 作业的输出文件，例如 stdout, stderr, trial.log 以及模型文件，也会被复制回存储卷。 NNI 会在网页中显示每个 Trial 的存储卷的 URL，以便浏览日志和输出文件。
 
 支持的操作符（operator）
 ------------------------------------

docs/zh_CN/TrainingService/Overview.rst

@@ -68,3 +68,13 @@ NNI 训练平台让用户专注于 AutoML 任务，不需要关心 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 管理器的计算机能被工作节点访问到。
+
+
+重用模式下的训练平台
+---------------------------------
+
+启用重用模式后，一个集群，例如远程机器或 AML 上的计算实例，将启动一个长期运行的环境，以便 NNI 将 Trial 迭代地提交到这些环境，从而节省创建新任务的时间。 例如，在重用模式下使用 OpenPAI 训练平台可以避免重复拉取 docker 镜像、创建容器和下载数据的开销。
+
+在重用模式下，用户需要确保每个 Trial 可以在同一任务中独立运行（例如，避免加载先前 Trial 的检查点）。
+
+.. note:: 目前，只有 `Local <./LocalMode.rst>`__, `Remote <./RemoteMachineMode.rst>`__, `OpenPAI <./PaiMode.rst>`__ 和 `AML <./AMLMode.rst>`__ 训练平台支持重用模式。 对于 Remote 和 OpenPAI 训练平台，您可以根据 `这里 <../reference/experiment_config.rst>`__ 手动启用重用模式。 AML是在重用模式下实现的，所以默认模式是重用模式，不需要手动启用。

docs/zh_CN/TrainingService/RemoteMachineMode.rst

@@ -141,10 +141,10 @@ Windows
 
    nnictl create --config examples/trials/mnist-annotation/config_remote.yml
 
-配置 python 环境
+配置 Python 环境
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-默认情况下，命令和脚本将在远程计算机的默认环境中执行。 如果远程机器上有多个 python 虚拟环境，并且想在特定环境中运行实验，请使用 **preCommand** 来指定远程计算机上的 python 环境。 
+默认情况下，命令和脚本将在远程计算机的默认环境中执行。 如果远程机器上有多个 python 虚拟环境，并且想在特定环境中运行实验，请使用 **pythonPath** 来指定远程计算机上的 Python 环境。 
 
 以 ``examples/trials/mnist-tfv2`` 为例。 示例文件 ``examples/trials/mnist-tfv2/config_remote.yml`` 的内容如下：
 
@@ -179,7 +179,7 @@ Windows
        # Below is an example of specifying python environment.
        pythonPath: ${replace_to_python_environment_path_in_your_remote_machine}
 
-远程计算机支持以重用模式运行实验。 在这种模式下，NNI 将重用远程机器任务来运行尽可能多的 Trial. 这样可以节省创建新作业的时间。 用户需要确保同一作业中的每个 Trial 相互独立，例如，要避免从之前的 Trial 中读取检查点。  
+远程计算机支持以重用模式运行实验。 在这种模式下，NNI 将重用远程机器任务来运行尽可能多的 Trial。这样可以节省创建新作业的时间。用户需要确保同一作业中的每个 Trial 相互独立，例如，要避免从之前的 Trial 中读取检查点。  
 按照以下设置启用重用模式：
 
 .. code-block:: yaml

docs/zh_CN/TrialExample/KDExample.rst

@@ -4,7 +4,7 @@ NNI 上的知识蒸馏
 知识蒸馏 (Knowledge Distillation)
 ---------------------------------------
 
-在 `Distilling the Knowledge in a Neural Network <https://arxiv.org/abs/1503.02531>`__\ 中提出了知识蒸馏（KD）的概念,  压缩后的模型被训练去模仿预训练的、较大的模型。  这种训练设置也称为"师生（teacher-student）"方式，其中大模型是教师，小模型是学生。 KD 通常用于微调剪枝后的模型。
+在 `Distilling the Knowledge in a Neural Network <https://arxiv.org/abs/1503.02531>`__\ 中提出了知识蒸馏（KD）的概念,  压缩后的模型被训练去模仿预训练的、较大的模型。这种训练设置也称为"师生（teacher-student）"方式，其中大模型是教师，小模型是学生。KD 通常用于微调剪枝后的模型。
 
 
 .. image:: ../../img/distill.png

docs/zh_CN/TrialExample/MnistExamples.rst

@@ -71,14 +71,14 @@ MNIST 示例
 
 此样例演示了 NNI 如何支持嵌套的搜索空间。 搜索空间文件示了如何定义嵌套的搜索空间。
 
-代码示例： :githublink:`mnist-nested-search-space/ <examples/trials/mnist-nested-search-space/>`
+代码示例： :githublink:`mnist-distributed/ <examples/trials/mnist-distributed/>`
 
 :raw-html:`<a name="mnist-kubeflow-tf"></a>`
 **用 Kubeflow 运行分布式的 MNIST (tensorflow)**
 
 此样例展示了如何通过 NNI 来在 Kubeflow 上运行分布式训练。 只需要简单的提供分布式训练代码，并在配置文件中指定 kubeflow 模式。 例如，运行 ps 和 worker 的命令行，以及各自需要的资源。 此样例使用了 Tensorflow 来实现，因而，需要使用 Kubeflow 的 tf-operator。
 
-代码示例： :githublink:`mnist-distributed/ <examples/trials/mnist-distributed/>`
+代码示例： :githublink:`mnist-distributed-pytorch/ <examples/trials/mnist-distributed-pytorch/>`
 
 :raw-html:`<a name="mnist-kubeflow-pytorch"></a>`
 **用 Kubeflow 运行分布式的 MNIST (PyTorch)**

docs/zh_CN/TrialExample/RocksdbExamples.rst

@@ -8,11 +8,11 @@
 
 RocksDB 的性能表现非常依赖于调优操作。 但由于其底层技术较复杂，可配置参数非常多，很难获得较好的配置。 NNI 可帮助解决此问题。 NNI 支持多种调优算法来为 RocksDB 搜索最好的配置，并支持本机、远程服务器和云服务等多种环境。 
 
-本示例展示了如何使用 NNI，通过评测工具 ``db_bench`` 来找到 ``fillrandom`` 基准的最佳配置，此工具是 RocksDB 官方提供的评测工具。 在运行示例前，需要检查 NNI 已安装， `db_bench <https://github.com/facebook/rocksdb/wiki/Benchmarking-tools>`__ 已经加入到了 ``PATH`` 中。 参考 `这里 <../Tutorial/QuickStart.rst>`__ ，了解如何安装并准备 NNI 环境，参考 `这里 <https://github.com/facebook/rocksdb/blob/master/INSTALL.md>`__ 来编译 RocksDB 以及 ``db_bench``。
+本示例展示了如何使用 NNI，通过评测工具 ``db_bench`` 来找到 ``fillrandom`` 基准的最佳配置，此工具是 RocksDB 官方提供的评测工具。 在运行示例前，需要检查 NNI 已安装， `db_bench <https://github.com/facebook/rocksdb/wiki/Benchmarking-tools>`__ 已经加入到了 ``PATH`` 中。 此简单脚本 :githublink:`db_bench_installation.sh <examples/trials/systems_auto_tuning/rocksdb-fillrandom/db_bench_installation.sh>` 可帮助编译并在 Ubuntu 上安装 ``db_bench`` 及其依赖包。 可遵循相同的过程在其它系统中安装 RocksDB。
 
-此简单脚本 :githublink:`db_bench_installation.sh <examples/trials/systems_auto_tuning/rocksdb-fillrandom/db_bench_installation.sh>` 可帮助编译并在 Ubuntu 上安装 ``db_bench`` 及其依赖包。 可遵循相同的过程在其它系统中安装 RocksDB。
+:githublink:`代码文件 <examples/trials/systems_auto_tuning/rocksdb-fillrandom>` 可遵循相同的过程在其它系统中安装 RocksDB。
 
-:githublink:`代码文件 <examples/trials/systems_auto_tuning/rocksdb-fillrandom>`
+:githublink:`代码文件 <examples/trials/systems_auto_tuning/rocksdb-fillrandom/main.py>`
 
 Experiment 设置
 ----------------
@@ -54,7 +54,7 @@ Experiment 设置
 * 使用 ``nni.get_next_parameter()`` 来获取下一个系统配置。
 * 使用 ``nni.report_final_result(metric)`` 来返回测试结果。
 
-:githublink:`代码文件 <examples/trials/systems_auto_tuning/rocksdb-fillrandom/main.py>`
+:githublink:`代码文件 <examples/trials/systems_auto_tuning/rocksdb-fillrandom/config_tpe.yml>`
 
 配置文件
 ^^^^^^^^^^^

docs/zh_CN/TrialExample/Trials.rst

@@ -159,10 +159,10 @@ NNI 支持独立模式，使 Trial 代码无需启动 NNI 实验即可运行。
 
 .. code-block:: python
 
-   ＃注意：请为 Trial 代码中的超参分配默认值
+   # 注意：请为 Trial 代码中的超参分配默认值
    nni.get_next_parameter # 返回 {}
-   nni.report_final_result ＃已在 stdout 上打印日志，但不报告
-   nni.report_intermediate_result # ＃已在 stdout 上打印日志，但不报告
+   nni.report_final_result # 已在 stdout 上打印日志，但不报告
+   nni.report_intermediate_result # 已在 stdout 上打印日志，但不报告
    nni.get_experiment_id # 返回 "STANDALONE"
    nni.get_trial_id # 返回 "STANDALONE"
    nni.get_sequence_id # 返回 0
@@ -208,6 +208,7 @@ Trial 存放在什么地方？
 -------------------
 
 
+* `将日志写入 TensorBoard 的 Trial 输出目录 <../Tutorial/Tensorboard.rst>`__
 * `MNIST 示例 <MnistExamples.rst>`__
 * `为 CIFAR 10 分类找到最佳的 optimizer <Cifar10Examples.rst>`__
 * `如何在 NNI 调优 SciKit-learn 的参数 <SklearnExamples.rst>`__

docs/zh_CN/Tuner/HyperoptTuner.rst

@@ -33,7 +33,7 @@ TPE 的并行优化
 * **constant_liar_type** (*min、max 或 mean, 可选, 默认值为 min*) - 使用的 constant liar 类型，会在 X 点根据 y 的取值来确定。对应三个值：min{Y}, max{Y}, 和 mean{Y}。
 
 Random Search（随机搜索）
----------------------------------------
+--------------------------------------
 
 论文 `Random Search for Hyper-Parameter Optimization <http://www.jmlr.org/papers/volume13/bergstra12a/bergstra12a.pdf>`__ 中介绍了随机搜索惊人的简单和效果。 建议在不知道超参数的先验分布时，使用随机搜索作为基准。
 

docs/zh_CN/Tuner/NetworkmorphismTuner.rst

@@ -61,7 +61,7 @@ Network Morphism Tuner
 
    # 1. 使用 NNI API
    # 从 WebUI 获得最佳模型 ID
-   # or `nni-experiments/experiment_id/log/model_path/best_model.txt'
+   # 或者 ``nni-experiments/experiment_id/log/model_path/best_model.txt``
 
    # 从模型文件中读取 json 字符串，并用 NNI API 加载
    with open("best-model.json") as json_file: