Merge pull request #233 from microsoft/master

merge master

docs/zh_CN/NAS/Overview.md

@@ -6,23 +6,20 @@
 
 以此为动力，NNI 的目标是提供统一的体系结构，以加速NAS上的创新，并将最新的算法更快地应用于现实世界中的问题上。
 
-通过[统一的接口](./NasInterface.md)，有两种方式进行架构搜索。 [一种](#supported-one-shot-nas-algorithms)称为 one-shot NAS，基于搜索空间构建了一个超级网络，并使用 one-shot 训练来生成性能良好的子模型。 [第二种](./NasInterface.md#经典分布式搜索)是传统的搜索方法，搜索空间中每个子模型作为独立的 Trial 运行，将性能结果发给 Tuner，由 Tuner 来生成新的子模型。
-
-* [支持的 One-shot NAS 算法](#supported-one-shot-nas-algorithms)
-* [使用 NNI Experiment 的经典分布式 NAS](./NasInterface.md#经典分布式搜索)
-* [NNI NAS 编程接口](./NasInterface.md)
+通过统一的接口，有两种方法来使用神经网络架构搜索。 [一种](#supported-one-shot-nas-algorithms)称为 one-shot NAS，基于搜索空间构建了一个超级网络，并使用 one-shot 训练来生成性能良好的子模型。 [第二种](#支持的分布式-nas-算法)是传统的搜索方法，搜索空间中每个子模型作为独立的 Trial 运行，将性能结果发给 Tuner，由 Tuner 来生成新的子模型。
 
 ## 支持的 One-shot NAS 算法
 
 NNI 现在支持以下 NAS 算法，并且正在添加更多算法。 用户可以重现算法或在自己的数据集上使用它。 鼓励用户使用 [NNI API](#use-nni-api) 实现其它算法，以使更多人受益。
 
 | 名称                              | 算法简介                                                                                                                                                                            |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [ENAS](ENAS.md)                 | [Efficient Neural Architecture Search via Parameter Sharing](https://arxiv.org/abs/1802.03268). 在 ENAS 中，Contoller 学习在大的计算图中搜索最有子图的方式来发现神经网络。 它通过在子模型间共享参数来实现加速和出色的性能指标。        |
 | [DARTS](DARTS.md)               | [DARTS: Differentiable Architecture Search](https://arxiv.org/abs/1806.09055) 引入了一种在两级网络优化中使用的可微分算法。                                                                            |
 | [P-DARTS](PDARTS.md)            | [Progressive Differentiable Architecture Search: Bridging the Depth Gap between Search and Evaluation](https://arxiv.org/abs/1904.12760) 基于DARTS。 它引入了一种有效的算法，可在搜索过程中逐渐增加搜索的深度。 |
 | [SPOS](SPOS.md)                 | 论文 [Single Path One-Shot Neural Architecture Search with Uniform Sampling](https://arxiv.org/abs/1904.00420) 构造了一个采用统一的路径采样方法来训练简化的超网络，并使用进化算法来提高搜索神经网络结构的效率。                   |
 | [CDARTS](CDARTS.md)             | [Cyclic Differentiable Architecture Search](https://arxiv.org/abs/****) 在搜索和评估的网络见构建了循环反馈的机制。 通过引入的循环的可微分架构搜索框架将两个网络集成为一个架构。                                                    |
+| [ProxylessNAS](Proxylessnas.md) | [ProxylessNAS: Direct Neural Architecture Search on Target Task and Hardware](https://arxiv.org/abs/1812.00332).                                                                |
 
 One-shot 算法**不需要 nnictl，可单独运行**。 只实现了 PyTorch 版本。 将来的版本会支持 Tensorflow 2.x。
 
@@ -33,22 +30,26 @@ One-shot 算法**不需要 nnictl，可单独运行**。 只实现了 PyTorch
 * PyTorch 1.2+
 * git
 
-## 使用 NNI API
+## 支持的分布式 NAS 算法
 
-注意，我们正在尝试通过统一的编程接口来支持各种 NAS 算法，当前处于试验阶段。 这意味着当前编程接口将来会有变化。
+| 名称              | 算法简介                                                                                                                                                          |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [SPOS](SPOS.md) | 论文 [Single Path One-Shot Neural Architecture Search with Uniform Sampling](https://arxiv.org/abs/1904.00420) 构造了一个采用统一的路径采样方法来训练简化的超网络，并使用进化算法来提高搜索神经网络结构的效率。 |
 
-### 编程接口
+```eval_rst
+.. 注意：SPOS 是一种两阶段算法，第一阶段是 one-shot，第二阶段是分布式的，利用第一阶段的结果作为检查点。
+```
+
+## 使用 NNI API
 
 在两种场景下需要用于设计和搜索模型的编程接口。
 
 1. 在设计神经网络时，可能在层、子模型或连接上有多种选择，并且无法确定是其中一种或某些的组合的结果最好。 因此，需要简单的方法来表达候选的层或子模型。
 2. 在神经网络上应用 NAS 时，需要统一的方式来表达架构的搜索空间，这样不必为不同的搜索算法来更改代码。
 
-NNI 提出的 API 在[这里](https://github.com/microsoft/nni/tree/master/src/sdk/pynni/nni/nas/pytorch)。 [这里](https://github.com/microsoft/nni/tree/master/examples/nas/naive)包含了基于此 API 的 NAS 实现示例。
+[这里](./NasGuide.md)是在 NNI 上开始使用 NAS 的用户指南。
+
+## 参考和反馈
 
-## **参考和反馈**
 * 在 GitHub 中[提交此功能的 Bug](https://github.com/microsoft/nni/issues/new?template=bug-report.md)；
-* 在 GitHub 中[提交新功能或改进请求](https://github.com/microsoft/nni/issues/new?template=enhancement.md)；
-* 了解 NNI 中[特征工程的更多信息](https://github.com/microsoft/nni/blob/master/docs/zh_CN/FeatureEngineering/Overview.md)；
+* 在 GitHub 中[提交新功能或改进请求](https://github.com/microsoft/nni/issues/new?template=enhancement.md)。
\ No newline at end of file
-* 了解 NNI 中[模型自动压缩的更多信息](https://github.com/microsoft/nni/blob/master/docs/zh_CN/Compressor/Overview.md)；
-* 了解如何[使用 NNI 进行超参数调优](https://github.com/microsoft/nni/blob/master/docs/zh_CN/Tuner/BuiltinTuner.md)；

docs/zh_CN/NAS/Proxylessnas.md

+# NNI 上的 ProxylessNAS
+
+## 介绍
+
+论文 [ProxylessNAS: Direct Neural Architecture Search on Target Task and Hardware](https://arxiv.org/pdf/1812.00332.pdf) 去掉了代理，直接从大规模目标任务和目标硬件平台上学习架构。 它解决了可微分 NAS 大量内存消耗的问题，从而将计算成本较低到普通训练的水平，同时仍然能使用大规模的候选集。 参考论文了解详情。
+
+## 用法
+
+要使用 ProxylessNAS 训练、搜索方法，用户要在模型中使用 [NNI NAS interface](NasGuide.md) 来指定搜索空间，例如，`LayerChoice`，`InputChoice`。 定义并实例化模型，然后实例化 ProxylessNasTrainer，并将模型传入，剩下的工作由 Trainer 来完成。
+```python
+trainer = ProxylessNasTrainer(model,
+                              model_optim=optimizer,
+                              train_loader=data_provider.train,
+                              valid_loader=data_provider.valid,
+                              device=device,
+                              warmup=True,
+                              ckpt_path=args.checkpoint_path,
+                              arch_path=args.arch_path)
+trainer.train()
+trainer.export(args.arch_path)
+```
+[此处](https://github.com/microsoft/nni/tree/master/examples/nas/proxylessnas)是完整示例。
+
+**ProxylessNasTrainer 的输入参数**
+
+* **model** (*PyTorch 模型, 必需*) - 需要调优、搜索的模型。 它具有可变项以指定搜索空间。
+* **model_optim** (*PyTorch 优化器, 必需*) - 训练模型所需要的优化器。
+* **device** (*device, 必需*) - 用于训练、搜索的 device。 Trainer 会使用数据并行化。
+* **train_loader** (*PyTorch DataLoader, 必需*) - 训练数据集的 DataLoader。
+* **valid_loader** (*PyTorch DataLoader, 必需*) - 验证数据集的 DataLoader。
+* **label_smoothing** (*float, 可选, 默认为 0.1*) - 标签平滑度。
+* **n_epochs** (*int, 可选, 默认为 120*) - 训练、搜索的 Epoch 数量。
+* **init_lr** (*float, 可选, 默认为 0.025*) - 训练的初始学习率。
+* **binary_mode** (*'two', 'full', 或 'full_v2', 可选, 默认为 'full_v2'*) - Mutabor 中二进制权重的 forward, backword 模式。 'full' 表示前向传播所有候选操作，'two' 表示仅前向传播两个采样操作，'full_v2' 表示在反向传播时重新计算非激活的操作。
+* **arch_init_type** (*'normal' 或 'uniform', 可选, 默认为 'normal'*) - 初始化架构参数的方法。
+* **arch_init_ratio** (*float, 可选, 默认为 1e-3*) - 初始化架构参数的比例。
+* **arch_optim_lr** (*float, 可选, 默认为 1e-3*) - 架构参数优化器的学习率。
+* **arch_weight_decay** (*float, 可选, 默认为 0*) - 架构参数优化器的权重衰减。
+* **grad_update_arch_param_every** (*int, 可选, 默认为 5*) - 多少个迷你批处理后更新权重。
+* **grad_update_steps** (*int, 可选, 默认为 1*) - 在每次权重更新时，训练架构权重的次数。
+* **warmup** (*bool, 可选, 默认为 True*) - 是否需要热身。
+* **warmup_epochs** (*int, 可选, 默认为 25*) - 热身的 Epoch 数量。
+* **arch_valid_frequency** (*int, 可选, 默认为 = 1*) - 输出验证集结果的频率。
+* **load_ckpt** (*bool, 可选, 默认为 False*) - 是否加载检查点。
+* **ckpt_path** (*str, 可选, 默认为 None*) - 检查点路径。如果 load_ckpt 为 True，ckpt_path 不能为 None。
+* **arch_path** (*str, 可选, 默认为 None*) - 选择架构的路径。
+
+
+## 实现
+
+NNI 上的实现基于[官方实现](https://github.com/mit-han-lab/ProxylessNAS)。 官方实现支持两种搜索方法：梯度下降和强化学习，还支持不同的硬件，包括 'mobile', 'cpu', 'gpu8', 'flops'。 在当前的 NNI 实现中，支持梯度下降训练方法，不支持不同的硬件。 完整支持正在进行中。
+
+下面将介绍实现的细节。 像 NNI 上其它 one-shot NAS 算法一样，ProxylessNAS 由两部分组成：*搜索空间* 和 *训练方法*。 为了用户能灵活的定义自己的搜索空间，并使用内置的 ProxylessNAS 训练方法，将使用 [NNI NAS 接口](NasGuide.md)定制的搜索空间放在了[示例代码](https://github.com/microsoft/nni/tree/master/examples/nas/proxylessnas)中，并将搜索方法放在了 [SDK](https://github.com/microsoft/nni/tree/master/src/sdk/pynni/nni/nas/pytorch/proxylessnas) 中。
+
+![](../../img/proxylessnas.png)
+
+ProxylessNAS 搜索方法由 ProxylessNasMutator 和 ProxylessNasTrainer 组成。 ProxylessNasMutator 为每个可变量初始化了 MixedOp (即, LayerChoice)，并会在 MixedOp 中管理架构权重。 **对于数据并行化**，架构权重会在用户模型中。 具体地说，在 ProxylessNAS 视线中，为可变变量 (即, LayerChoice) 添加了 MixedOp 作为成员变量。 Mutator 也公开了两个成员函数：`arch_requires_grad` 和 `arch_disable_grad`，用于 Trainer 来控制架构权重的训练。
+
+ProxylessNasMutator 还实现了可变量的前向逻辑 (即, LayerChoice)。
+
+## 重现结果
+
+进行中...

docs/zh_CN/NAS/QuickStart.md

+# NAS 快速入门
+
+NNI 提供的 NAS 功能有两个关键组件：用于表示搜索空间的 API 和 NAS 的训练方法。 前者为用户提供了表示性能好的模块的方法（即，通过搜索空间指定的候选模型）。 后者能让用户可以轻松的在自己的模型上使用最新的 NAS 训练方法。
+
+这里，通过简单的示例，来一步步演示如何使用 NNI NAS API 调优自己的模型架构。 示例的完整代码可在[这里](https://github.com/microsoft/nni/tree/master/examples/nas/naive)找到。
+
+## 使用 NAS API 编写模型
+
+可通过两个 NAS API `LayerChoice` 和 `InputChoice` 来定义神经网络模型，而不需要编写具体的模型。 例如，如果认为在第一卷积层有两种操作可能会有效，可通过 `LayerChoice` 来为代码中的 `self.conv1` 赋值。 同样，第二个卷积层 `self.conv2` 也可以从中选择一个。 此处，指定了 4 个候选的神经网络。 `self.skipconnect` 使用 `InputChoice` 来指定两个选项，即是否添加跳跃的连接。
+
+```python
+import torch.nn as nn
+from nni.nas.pytorch.mutables import LayerChoice, InputChoice
+
+class Net(nn.Module):
+    def __init__(self):
+        super(Net, self).__init__()
+        self.conv1 = LayerChoice([nn.Conv2d(3, 6, 3, padding=1), nn.Conv2d(3, 6, 5, padding=2)])
+        self.pool = nn.MaxPool2d(2, 2)
+        self.conv2 = LayerChoice([nn.Conv2d(6, 16, 3, padding=1), nn.Conv2d(6, 16, 5, padding=2)])
+        self.conv3 = nn.Conv2d(16, 16, 1)
+
+        self.skipconnect = InputChoice(n_candidates=1)
+        self.bn = nn.BatchNorm2d(16)
+
+        self.gap = nn.AdaptiveAvgPool2d(4)
+        self.fc1 = nn.Linear(16 * 4 * 4, 120)
+        self.fc2 = nn.Linear(120, 84)
+        self.fc3 = nn.Linear(84, 10)
+```
+
+有关 `LayerChoice` 和 `InputChoice` 的详细描述可参考[指南](NasGuide.md)。
+
+## 选择 NAS Trainer
+
+实例化模型后，需要通过 NAS Trainer 来训练模型。 不同的 Trainer 会使用不同的方法来从指定的神经网络模块中搜索出最好的。 NNI 提供了流行的 NAS 训练方法，如 DARTS，ENAS。 以下以 `DartsTrainer` 为例。 在 Trainer 实例化后，调用`trainer.train()` 开始搜索。
+
+```python
+trainer = DartsTrainer(net,
+                       loss=criterion,
+                       metrics=accuracy,
+                       optimizer=optimizer,
+                       num_epochs=2,
+                       dataset_train=dataset_train,
+                       dataset_valid=dataset_valid,
+                       batch_size=64,
+                       log_frequency=10)
+trainer.train()
+```
+
+## 导出最佳模型
+
+搜索（即`trainer.train()`）完成后，需要拿到最好的模型，只需要调用 `trainer.export("final_arch.json")` 来将找到的神经网络架构导出到文件。
+
+## NAS 可视化
+
+正在开发 NAS 的可视化，并将很快发布。
+
+## 重新训练导出的最佳模型
+
+重新训练找到（导出）的网络架构非常容易。 第一步，实例化上面定义的模型。 第二步，在模型上调用 `apply_fixed_architecture`。 然后，模型会变为找到（导出）的模型，可通过正常的训练方法来训练此模型。
+
+```python
+model = Net()
+apply_fixed_architecture(model, "final_arch.json")
+```

docs/zh_CN/Release.md

@@ -229,7 +229,7 @@
 
 ### 主要功能
 
-* [支持在 Windows 上使用 NNI](Tutorial/NniOnWindows.md) 
+* [支持在 Windows 上使用 NNI](Tutorial/InstallationWin.md) 
   * NNI 可在 Windows 上使用本机模式
 * [支持新的 Advisor: BOHB](Tuner/BohbAdvisor.md) 
   * 支持新的 BOHB Advisor，这是一个健壮而有效的超参调优算法，囊括了贝叶斯优化和 Hyperband 的优点

docs/zh_CN/TrainingService/PaiMode.md

@@ -4,7 +4,31 @@ NNI 支持在 [OpenPAI](https://github.com/Microsoft/pai) （简称 pai）上运
 
 ## 设置环境
 
-参考[指南](../Tutorial/QuickStart.md)安装 NNI。
+步骤 1. 参考[指南](../Tutorial/QuickStart.md)安装 NNI。
+
+步骤 2. 获取 OpenPAI 的令牌。  
+点击 OpenPAI 界面右上方的 `My profile` 按钮。 ![](../../img/pai_token_button.jpg) 找到 token management，复制当前账号的令牌。 ![](../../img/pai_token_profile.jpg)
+
+步骤 3. 将 NFS 存储挂载到本机。  
+点击 OpenPAI 网站的 `Submit job` 按钮。 ![](../../img/pai_job_submission_page.jpg)  
+在作业提交页面找到数据管理区域。 ![](../../img/pai_data_management_page.jpg)  
+`DEFAULT_STORAGE` 字段是在作业运行起来后，OpenPAI 容器中挂载的路径。 `Preview container paths` 是 API 提供的 NFS 主机和路径，需要将对应的位置挂载到本机，然后 NNI 才能使用 NFS 存储。  
+例如，使用下列命令：
+
+    sudo mount nfs://gcr-openpai-infra02:/pai/data /local/mnt
+    
+
+然后容器中的 `/data` 路径会被挂载到本机的 `/local/mnt` 文件夹  
+然后在 NNI 的配置文件中如下配置：
+
+    nniManagerNFSMountPath: /local/mnt
+    containerNFSMountPath: /data
+    
+
+步骤 4. 获取 OpenPAI 存储插件名称。 联系 OpenPAI 管理员，获得 NFS 存储插件的名称。 默认存储的名称是 `teamwise_storage`，NNI 配置文件中的配置如下：
+
+    paiStoragePlugin: teamwise_storage
+    
 
 ## 运行 Experiment
 
@@ -39,6 +63,7 @@ trial:
   virtualCluster: default
   nniManagerNFSMountPath: /home/user/mnt
   containerNFSMountPath: /mnt/data/user
+  paiStoragePlugin: team_wise
 # 配置要访问的 OpenPAI 集群
 paiConfig:
   userName: your_pai_nni_user
@@ -51,12 +76,12 @@ paiConfig:
 与[本机模式](LocalMode.md)，以及[远程计算机模式](RemoteMachineMode.md)相比，pai 模式的 Trial 需要额外的配置：
 
 * cpuNum 
-    * 必填。 Trial 程序的 CPU 需求，必须为正数。
+    * 可选。 Trial 程序的 CPU 需求，必须为正数。 如果没在 Trial 配置中设置，则需要在 `paiConfigPath` 指定的配置文件中设置。
 * memoryMB 
-    * 必填。 Trial 程序的内存需求，必须为正数。
+    * 可选。 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)。 可以直接使用此映像，或参考它来生成自己的映像。
+    * 可选。 在 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 
@@ -64,7 +89,9 @@ paiConfig:
 * containerNFSMountPath 
     * 必填。 在 OpenPAI 的容器中设置挂载路径。
 * paiStoragePlugin 
-    * 必填。 设置 PAI 中使用的存储插件的名称。
+    * 可选。 设置 PAI 中使用的存储插件的名称。 如果没在 Trial 配置中设置，则需要在 `paiConfigPath` 指定的配置文件中设置。
+* paiConfigPath 
+    * 可选。 设置 OpenPAI 作业配置文件路径，文件为 YAML 格式。
 
 完成并保存 NNI Experiment 配置文件后（例如可保存为：exp_pai.yml），运行以下命令：
 

docs/zh_CN/TrainingService/PaiYarnMode.md

@@ -6,7 +6,7 @@
 参考[指南](../Tutorial/QuickStart.md)安装 NNI。
 
 ## 运行 Experiment
-以 `examples/trials/mnist-annotation` 为例。 NNI 的 YAML 配置文件如下：
+以 `examples/trials/mnist-tfv1` 为例。 NNI 的 YAML 配置文件如下：
 
 ```yaml
 authorName: your_name
@@ -22,14 +22,14 @@ trainingServicePlatform: paiYarn
 # 搜索空间文件
 searchSpacePath: search_space.json
 # 可选项: true, false
-useAnnotation: true
+useAnnotation: false
 tuner:
   builtinTunerName: TPE
   classArgs:
     optimize_mode: maximize
 trial:
   command: python3 mnist.py
-  codeDir: ~/nni/examples/trials/mnist-annotation
+  codeDir: ~/nni/examples/trials/mnist-tfv1
   gpuNum: 0
   cpuNum: 1
   memoryMB: 8196
@@ -83,14 +83,14 @@ paiYarnConfig:
         portNumber: 1
     ```
 
-NNI 支持 OpenPAIYarn 中的两种认证授权方法，即密码和 paiYarn Token，[参考](https://github.com/microsoft/paiYarn/blob/b6bd2ab1c8890f91b7ac5859743274d2aa923c22/docs/rest-server/API.md#2-authentication)。 授权配置在 `paiYarnConfig` 字段中。 密码认证的 `paiYarnConfig` 配置如下：
+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
 ```
-Token 认证的 `paiYarnConfig` 配置如下：
+令牌认证的 `paiYarnConfig` 配置如下：
 ```
 paiYarnConfig:
   userName: your_paiYarn_nni_user

docs/zh_CN/Tutorial/ExperimentConfig.md

@@ -661,9 +661,9 @@ OpenPAI 帐户的密码。
 
 #### token
 
-如果使用 token 身份验证，则需要。 字符串。
+如果使用令牌（token）身份验证，则需要。 字符串。
 
-可以从 OpenPAI 门户检索的个人访问 token。
+可以从 OpenPAI 门户检索的个人访问令牌。
 
 #### host
 

docs/zh_CN/Tutorial/FAQ.md

@@ -54,7 +54,7 @@ nnictl 在执行时，使用 tmp 目录作为临时目录来复制 codeDir 下
 
 ### NNI 在 Windows 上的问题
 
-参考 [Windows 上使用 NNI](NniOnWindows.md)。
+参考 [Windows 上的 NNI](InstallationWin.md#FAQ)
 
 ### 更多常见问题解答
 

docs/zh_CN/Tutorial/HowToUseDocker.md

@@ -38,7 +38,7 @@
 
 如果你直接使用NNI的官方镜像`msranni/nni`来启动实验，你可以直接使用`nnictl`命令。 NNI的官方镜像有最基础的python环境和深度学习框架。
 
-如果你使用你自己的docker镜像，你首先需要安装NNI环境。[参考](Installation.md)
+如果使用自己的 Docker 镜像，需要首先[安装 NNI](InstallationLinux.md)。
 
 如果你想要使用NNI的官方例子，你可以通过以下git命令来克隆NNI：
 

docs/zh_CN/Tutorial/InstallationLinux.md

+# 在 Linux 和 Mac 下安装
+
+## 安装
+
+在 Linux 和 macOS 上安装，遵循以下相同的说明。
+
+### 通过 pip 命令安装 NNI
+
+先决条件：`python 64-bit >= 3.5`
+
+    bash
+      python3 -m pip install --upgrade nni
+
+### 通过源代码安装 NNI
+
+如果对某个或最新版本的代码感兴趣，可通过源代码安装 NNI。
+
+先决条件：`python 64-bit >=3.5`, `git`, `wget`
+
+    bash
+      git clone -b v1.3 https://github.com/Microsoft/nni.git
+      cd nni
+      ./install.sh
+
+### 在 Docker 映像中使用 NNI
+
+也可将 NNI 安装到 docker 映像中。 参考[这里](../deployment/docker/README.md)来生成 NNI 的 Docker 映像。 也可通过此命令从 Docker Hub 中直接拉取 NNI 的映像 `docker pull msranni/nni:latest`。
+
+## 验证安装
+
+以下示例基于 TensorFlow 1.x 。确保运行环境中使用的的是 ** TensorFlow 1.x**。
+
+* 通过克隆源代码下载示例。
+    
+    ```bash
+    git clone -b v1.3 https://github.com/Microsoft/nni.git
+    ```
+
+* 运行 MNIST 示例。
+    
+    ```bash
+    nnictl create --config nni/examples/trials/mnist-tfv1/config.yml
+    ```
+
+* 在命令行中等待输出 `INFO: Successfully started experiment!`。 此消息表明 Experiment 已成功启动。 通过命令行输出的 `Web UI url` 来访问 Experiment 的界面。
+
+```text
+INFO: Starting restful server...
+INFO: Successfully started Restful server!
+INFO: Setting local config...
+INFO: Successfully set local config!
+INFO: Starting experiment...
+INFO: Successfully started experiment!
+-----------------------------------------------------------------------
+The experiment id is egchD4qy
+The Web UI urls are: http://223.255.255.1:8080   http://127.0.0.1:8080
+-----------------------------------------------------------------------
+
+You can use these commands to get more information about the experiment
+-----------------------------------------------------------------------
+         commands                       description
+
+1. nnictl experiment show        show the information of experiments
+2. nnictl trial ls               list all of trial jobs
+3. nnictl top                    monitor the status of running experiments
+4. nnictl log stderr             show stderr log content
+5. nnictl log stdout             show stdout log content
+6. nnictl stop                   stop an experiment
+7. nnictl trial kill             kill a trial job by id
+8. nnictl --help                 get help information about nnictl
+-----------------------------------------------------------------------
+```
+
+* 在浏览器中打开 `Web UI url`，可看到下图的 Experiment 详细信息，以及所有的 Trial 任务。 查看[这里](../Tutorial/WebUI.md)的更多页面。
+
+![概述](../../img/webui_overview_page.png)
+
+![详细说明](../../img/webui_trialdetail_page.png)
+
+## 系统需求
+
+由于程序变更，NNI 的最低配置会有所更改。
+
+### Linux
+
+|          | 推荐配置                                      | 最低配置                                  |
+| -------- | ----------------------------------------- | ------------------------------------- |
+| **操作系统** | Ubuntu 16.04 或以上版本                        |                                       |
+| **CPU**  | Intel® Core™ i5 或 AMD Phenom™ II X3 或更高配置 | Intel® Core™ i3 或 AMD Phenom™ X3 8650 |
+| **GPU**  | NVIDIA® GeForce® GTX 660 或更高配置            | NVIDIA® GeForce® GTX 460              |
+| **内存**   | 6 GB                                      | 4 GB                                  |
+| **存储**   | 30 GB 可用的磁盘空间                             |                                       |
+| **网络**   | 宽带连接                                      |                                       |
+| **分辨率**  | 1024 x 768 以上                             |                                       |
+
+### macOS
+
+|          | 推荐配置                     | 最低配置                                               |
+| -------- | ------------------------ | -------------------------------------------------- |
+| **操作系统** | macOS 10.14.1 或更高版本      |                                                    |
+| **CPU**  | Intel® Core™ i7-4770 或更高 | Intel® Core™ i5-760 或更高                            |
+| **GPU**  | AMD Radeon™ R9 M395X 或更高 | NVIDIA® GeForce® GT 750M 或 AMD Radeon™ R9 M290 或更高 |
+| **内存**   | 8 GB                     | 4 GB                                               |
+| **存储**   | 70GB 可用空间 SSD 硬盘         | 70GB 可用空间及 7200 RPM 硬盘                             |
+| **网络**   | 宽带连接                     |                                                    |
+| **分辨率**  | 1024 x 768 以上            |                                                    |
+
+## 更多
+
+* [概述](../Overview.md)
+* [使用命令行工具 nnictl](Nnictl.md)
+* [使用 NNIBoard](WebUI.md)
+* [定制搜索空间](SearchSpaceSpec.md)
+* [配置 Experiment](ExperimentConfig.md)
+* [如何在本机运行 Experiment (支持多 GPU 卡)？](../TrainingService/LocalMode.md)
+* [如何在多机上运行 Experiment？](../TrainingService/RemoteMachineMode.md)
+* [如何在 OpenPAI 上运行 Experiment？](../TrainingService/PaiMode.md)
+* [如何通过 Kubeflow 在 Kubernetes 上运行 Experiment？](../TrainingService/KubeflowMode.md)
+* [如何通过 FrameworkController 在 Kubernetes 上运行 Experiment？](../TrainingService/FrameworkControllerMode.md)
\ No newline at end of file

docs/zh_CN/Tutorial/InstallationWin.md

+# 在 Windows 上安装
+
+## 安装
+
+强烈建议使用 Anaconda 或 Miniconda 来管理多个 Python 环境。
+
+### 通过 pip 命令安装 NNI
+
+  先决条件：`python 64-bit >= 3.5`
+
+  ```bash
+  python -m pip install --upgrade nni
+  ```
+
+### 通过源代码安装 NNI
+
+  如果对某个或最新版本的代码感兴趣，可通过源代码安装 NNI。
+
+  先决条件：`python 64-bit >=3.5`, `git`, `PowerShell`
+
+  ```bash
+  git clone -b v1.3 https://github.com/Microsoft/nni.git
+  cd nni
+  powershell -ExecutionPolicy Bypass -file install.ps1
+  ```
+
+## 验证安装
+
+以下示例基于 TensorFlow 1.x 。确保运行环境中使用的的是 **TensorFlow 1.x**。
+
+* 通过克隆源代码下载示例。
+
+  ```bash
+  git clone -b v1.3 https://github.com/Microsoft/nni.git
+  ```
+
+* 运行 MNIST 示例。
+
+  ```bash
+  nnictl create --config nni\examples\trials\mnist-tfv1\config_windows.yml
+  ```
+
+  注意：在其它示例中，如果 Python3 是通过 `python` 命令启动，需要将每个示例 YAML 文件的 Trial 命令中的 `python3` 改为 `python`。
+
+* 在命令行中等待输出 `INFO: Successfully started experiment!`。 此消息表明 Experiment 已成功启动。 通过命令行输出的 `Web UI url` 来访问 Experiment 的界面。
+
+```text
+INFO: Starting restful server...
+INFO: Successfully started Restful server!
+INFO: Setting local config...
+INFO: Successfully set local config!
+INFO: Starting experiment...
+INFO: Successfully started experiment!
+-----------------------------------------------------------------------
+The experiment id is egchD4qy
+The Web UI urls are: http://223.255.255.1:8080   http://127.0.0.1:8080
+-----------------------------------------------------------------------
+
+You can use these commands to get more information about the experiment
+-----------------------------------------------------------------------
+         commands                       description
+1. nnictl experiment show        show the information of experiments
+2. nnictl trial ls               list all of trial jobs
+3. nnictl top                    monitor the status of running experiments
+4. nnictl log stderr             show stderr log content
+5. nnictl log stdout             show stdout log content
+6. nnictl stop                   stop an experiment
+7. nnictl trial kill             kill a trial job by id
+8. nnictl --help                 get help information about nnictl
+-----------------------------------------------------------------------
+```
+
+* 在浏览器中打开 `Web UI url`，可看到下图的 Experiment 详细信息，以及所有的 Trial 任务。 查看[这里](../Tutorial/WebUI.md)的更多页面。
+
+![概述](../../img/webui_overview_page.png)
+
+![详细说明](../../img/webui_trialdetail_page.png)
+
+## 系统需求
+
+以下是 NNI 在 Windows 上的最低配置，推荐使用 Windows 10 1809 版。 由于程序变更，NNI 的最低配置会有所更改。
+
+|          | 推荐配置                                      | 最低配置                                  |
+| -------- | ----------------------------------------- | ------------------------------------- |
+| **操作系统** | Windows 10 1809 或更高版本                     |                                       |
+| **CPU**  | Intel® Core™ i5 或 AMD Phenom™ II X3 或更高配置 | Intel® Core™ i3 或 AMD Phenom™ X3 8650 |
+| **GPU**  | NVIDIA® GeForce® GTX 660 或更高配置            | NVIDIA® GeForce® GTX 460              |
+| **内存**   | 6 GB                                      | 4 GB                                  |
+| **存储**   | 30 GB 可用的磁盘空间                             |                                       |
+| **网络**   | 宽带连接                                      |                                       |
+| **分辨率**  | 1024 x 768 以上                             |                                       |
+
+## 常见问答
+
+### 安装 NNI 时出现 simplejson 错误
+
+确保安装了 C++ 14.0 编译器。
+> building 'simplejson._speedups' extension error: [WinError 3] The system cannot find the path specified
+
+### 在命令行或 PowerShell 中，Trial 因为缺少 DLL 而失败
+
+此错误因为缺少 LIBIFCOREMD.DLL 和 LIBMMD.DLL 文件，且 SciPy 安装失败。 使用 Anaconda 或 Miniconda 和 Python（64位）可解决。
+> ImportError: DLL load failed
+
+### Web 界面上的 Trial 错误
+
+检查 Trial 日志文件来了解详情。
+
+如果存在 stderr 文件，也需要查看其内容。 可能的错误情况包括：
+
+* 忘记将 Experiment 配置的 Trial 命令中的 `python3` 改为 `python`。
+* 忘记安装 Experiment 的依赖，如 TensorFlow，Keras 等。
+
+### 无法在 Windows 上使用 BOHB
+确保安装了 C ++ 14.0 编译器然后尝试运行 `nnictl package install --name=BOHB` 来安装依赖项。
+
+### Windows 上不支持的 Tuner
+当前不支持 SMAC，原因可参考[此问题](https://github.com/automl/SMAC3/issues/483)。
+
+### 将 Windows 服务器用作远程服务器
+目前不支持。
+
+注意：
+
+* 如果遇到 `Segmentation fault` 这样的错误，参考[常见问答](FAQ.md)。
+
+
+## 更多
+
+* [概述](../Overview.md)
+* [使用命令行工具 nnictl](Nnictl.md)
+* [使用 NNIBoard](WebUI.md)
+* [定制搜索空间](SearchSpaceSpec.md)
+* [配置 Experiment](ExperimentConfig.md)
+* [如何在本机运行 Experiment (支持多 GPU 卡)？](../TrainingService/LocalMode.md)
+* [如何在多机上运行 Experiment？](../TrainingService/RemoteMachineMode.md)
+* [如何在 OpenPAI 上运行 Experiment？](../TrainingService/PaiMode.md)
+* [如何通过 Kubeflow 在 Kubernetes 上运行 Experiment？](../TrainingService/KubeflowMode.md)
+* [如何通过 FrameworkController 在 Kubernetes 上运行 Experiment？](../TrainingService/FrameworkControllerMode.md)
\ No newline at end of file

docs/zh_CN/Tutorial/Nnictl.md

@@ -45,11 +45,11 @@ nnictl 支持的命令：
 * 选项
   
   | 参数及缩写            | 是否必需  | 默认值 | 说明                     |
-  | ------------ | ----- | --- | ---------------------- |
+  | ---------------- | ----- | --- | ---------------------- |
   | --config, -c     | True  |     | Experiment 的 YAML 配置文件 |
   | --port, -p       | False |     | RESTful 服务的端口          |
   | --debug, -d      | False |     | 设置为调试模式                |
-  | --watch, -w  | False |     | 启动为监视模式                |
+  | --foreground, -f | False |     | 设为前台运行模式，将日志输出到终端      |
 
 * 示例
   
@@ -94,11 +94,11 @@ nnictl 支持的命令：
 * 选项
   
   | 参数及缩写            | 是否必需  | 默认值 | 说明                               |
-  | ----------- | ----- | --- | -------------------------------- |
+  | ---------------- | ----- | --- | -------------------------------- |
   | id               | True  |     | 要恢复的 Experiment 标识               |
   | --port, -p       | False |     | 要恢复的 Experiment 使用的 RESTful 服务端口 |
   | --debug, -d      | False |     | 设置为调试模式                          |
-  | --watch, -w | False |     | 启动为监视模式                          |
+  | --foreground, -f | False |     | 设为前台运行模式，将日志输出到终端                |
 
 * 示例
   

docs/zh_CN/Tutorial/QuickStart.md

@@ -20,7 +20,7 @@
 
 * 在 Linux 和 macOS 上，如果要将 NNI 安装到当前用户的 home 目录中，可使用 `--user`，则不需要特殊权限。
 * 如果遇到如`Segmentation fault` 这样的任何错误请参考[常见问题](FAQ.md)。
-* 参考[安装 NNI](Installation.md)，来了解`系统需求`。
+* 有关 NNI 的`系统要求`，参考[在 Linux 和 macOS 上安装](InstallationLinux.md) 或 [Windows](InstallationWin.md)。
 
 ## MNIST 上的 "Hello World"
 

docs/zh_CN/builtin_assessor.rst

 内置 Assessor
 =================
 
+为了节省计算资源，在 NNI 中可通过创建 **Assessor**，来配置提前终止策略。
+
+Assessor 从 Trial 中接收中间结果，并通过指定的算法决定此 Trial 是否应该终止。 一旦 Trial 满足了提前终止策略（这表示 Assessor 认为最终结果不会太好），Assessor 会终止此 Trial，并将其状态标志为 `"EARLY_STOPPED"`。
+
+这是 MNIST 在使用了 'Curvefitting' Assessor 的 'maximize' 模式后的实验结果，可以看到 Assessor 成功的将大量最终结果不好的 Trial **提前结束** 。 使用 Assessor，能在相同的计算资源下，得到更好的结果。
+
+*实现代码：config_assessor.yml <https://github.com/Microsoft/nni/blob/master/examples/trials/mnist-tfv1/config_assessor.yml>*
+
+..  image:: ../img/Assessor.png
+
 ..  toctree::
     :maxdepth: 1
 

docs/zh_CN/builtin_tuner.rst

 内置 Tuner
-==================
+==============
+
+NNI 能用简单快速的方法来配置超参调优算法，称之为 **Tuner**。
+
+Tuner 从 Trial 接收指标结果，来评估一组超参或网络结构的性能。 然后 Tuner 会将下一组超参或网络结构的配置发送给新的 Trial。
+
 
 ..  toctree::
     :maxdepth: 1

docs/zh_CN/feature_engineering.rst

+###################
 特征工程
-===================
+###################
 
-很高兴的宣布 NNI 的特征工程包 Alpha 版本发布了。
+很高兴在 NNI 上引入了特征工程工具包，
 其仍处于试验阶段，会根据使用反馈来演化。
 诚挚邀请您使用、反馈，或更多贡献。
 

docs/zh_CN/hpo_advanced.rst

+高级功能
+=================
+
+..  toctree::
+    启用多阶段 <AdvancedFeature/MultiPhase>
+    编写新的 Tuner <Tuner/CustomizeTuner>
+    编写新的 Assessor <Assessor/CustomizeAssessor>
+    编写新的 Advisor <Tuner/CustomizeAdvisor>
+    编写新的训练平台 <TrainingService/HowToImplementTrainingService>

docs/zh_CN/hyperparameter_tune.rst

+#############################
+自动（超参数）调优
+#############################
+
+自动调优是 NNI 提供的关键功能之一，主要应用场景是
+超参调优。 Trial 代码是需要被调优的，这里提供了一些常见的
+自动调优算法（称为 Tuner ）和一些提前终止算法（称为 Assessor）。
+NNI 支持在各种培训平台上运行 Trial，例如，在本地计算机上运行，
+在多台服务器上分布式运行，或在 OpenPAI，Kubernetes 等平台上。
+
+NNI 的其它重要功能，例如模型压缩，特征工程，也可以进一步
+通过自动调优来提高，这会在介绍具体功能时提及。
+
+NNI 具有高扩展性，高级用户可以定制自己的 Tuner、 Assessor，以及训练平台
+根据自己的需求。
+
+..  toctree::
+    :maxdepth: 2
+
+    实现 Trial<./TrialExample/Trials>
+    Tuners <builtin_tuner>
+    Assessors <builtin_assessor>
+    训练平台 <training_services>
+    示例 <examples>
+    Web 界面 <Tutorial/WebUI>
+    如何调试 <Tutorial/HowToDebug>
+    高级 <hpo_advanced>
\ No newline at end of file

docs/zh_CN/index.rst

@@ -2,9 +2,6 @@
 Neural Network Intelligence
 ###########################
 
-********
-内容
-********
 
 ..  toctree::
     :caption: 目录
@@ -12,11 +9,14 @@ Neural Network Intelligence
     :titlesonly:
 
     概述<Overview>
+    安装 <installation>
     入门<Tutorial/QuickStart>
-    教程<tutorials>
-    示例<examples>
+    自动（超参数）调优 <hyperparameter_tune>
+    神经网络架构搜索<nas>
+    模型压缩<model_compression>
+    特征工程<feature_engineering>
     参考<reference>
-    FAQ<Tutorial/FAQ>
-    贡献<contribution>
-    更改日志<Release>
-    社区分享<CommunitySharings/community_sharings>
+    社区分享 <CommunitySharings/community_sharings>
+    常见问题 <Tutorial/FAQ>
+    如何贡献 <contribution>
+    更改日志 <Release>
\ No newline at end of file

docs/zh_CN/installation.rst

+############
+安装
+############
+
+当前支持在 Linux，macOS 和 Windows 下安装。 还可使用 Docker。
+
+..  toctree::
+    :maxdepth: 2
+
+    Linux 和 macOS <Tutorial/InstallationLinux>
+    Windows <Tutorial/InstallationWin>
+    使用 Docker <Tutorial/HowToUseDocker>
\ No newline at end of file