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
-
-混合模式的配置：
-
-hybridConfig:
-
-* trainingServicePlatforms. 必填。 该字段指定用于混合模式的平台，值使用 yaml 列表格式。 NNI 支持在此字段中设置 ``local``, ``remote``, ``aml``, ``pai`` 。
-
-
-.. Note:: 如果将平台设置为 trainingServicePlatforms 模式，则用户还应该为平台设置相应的配置。 例如，如果使用 ``remote`` 作为平台，还应设置 ``machineList`` 和 ``remoteConfig`` 配置。 混合模式下的本地平台暂时不支持Windows。
+    trainingServicePlatforms:
+      - remote
+        machineList:
+          - ip: 10.1.1.1
+            username: bob
+            passwd: bob123
+      - local
+
+要使用混合训练平台，用户应在 `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是在重用模式下实现的，所以默认模式是重用模式，不需要手动启用。