Merge branch 'master' into nn-meter

docs/zh_CN/NAS/Proxylessnas.rst

@@ -9,7 +9,7 @@ NNI 上的 ProxylessNAS
 用法
 -----
 
-要使用 ProxylessNAS 训练/搜索方法，用户需要使用 `NNI NAS 接口 <NasGuide.rst>`__ 在其模型中指定搜索空间，例如， ``LayerChoice``\ , ``InputChoice``。 定义并实例化模型，然后实例化 ProxylessNasTrainer，并将模型传入，剩下的工作由 Trainer 来完成。
+要使用 ProxylessNAS 训练/搜索方法，用户需要使用 `NNI NAS 接口 <MutationPrimitives.rst>`__ 在其模型中指定搜索空间，例如， ``LayerChoice``\ , ``InputChoice``。 定义并实例化模型，然后实例化 ProxylessNasTrainer，并将模型传入，剩下的工作由 Trainer 来完成。
 
 .. code-block:: python
 
@@ -56,7 +56,7 @@ NNI 上的 ProxylessNAS
 
 在NNI上的实现基于 `官方实现 <https://github.com/mit-han-lab/ProxylessNAS>`__ 。 官方实现支持两种搜索方法：梯度下降和强化学习，还支持不同的硬件，包括 'mobile', 'cpu', 'gpu8', 'flops'。 在当前的 NNI 实现中，支持梯度下降训练方法，不支持不同的硬件。 完整支持正在进行中。
 
-下面将介绍实现的细节。 像 NNI 上其它 one-shot NAS 算法一样，ProxylessNAS 由两部分组成：*搜索空间* 和 *训练方法*。 为了让用户灵活地定义自己的搜索空间并使用内置的 ProxylessNAS 训练方法，我们将指定的搜索空间放在 :githublink:`示例代码 <examples/nas/proxylessnas>` 使用 :githublink:`NNI NAS 接口 <nni/algorithms/nas/pytorch/proxylessnas>`。
+下面将介绍实现的细节。 像 NNI 上其它 one-shot NAS 算法一样，ProxylessNAS 由两部分组成：*搜索空间* 和 *训练方法*。 为了让用户灵活地定义自己的搜索空间并使用内置的 ProxylessNAS 训练方法，我们将指定的搜索空间放在 :githublink:`示例代码 <examples/nas/oneshot/proxylessnas>` 使用 :githublink:`NNI NAS 接口 <nni/algorithms/nas/pytorch/proxylessnas>`。
 
 .. image:: ../../img/proxylessnas.png
    :target: ../../img/proxylessnas.png

docs/zh_CN/NAS/QuickStart.rst

+快速入门 Retiarii
+==============================
+
+
+.. contents::
+
+在快速入门教程中，我们以 multi-trial NAS 为例来展示如何构建和探索模型空间。 神经网络架构搜索任务主要有三个关键组件，即：
+
+* 模型搜索空间（Model search space），定义了要探索的模型集合。
+* 一个适当的策略（strategy），作为探索这个搜索空间的方法。
+* 一个模型评估器（model evaluator），报告一个给定模型的性能。
+
+One-shot NAS 教程在 `这里 <./OneshotTrainer.rst>`__。
+
+.. note:: 目前，PyTorch 是 Retiarii 唯一支持的框架，我们只用 **PyTorch 1.6 和 1.7** 进行了测试。 本文档基于 PyTorch 的背景，但它也应该适用于其他框架，这在我们未来的计划中。
+
+定义模型空间
+-----------------------
+
+模型空间是由用户定义的，用来表达用户想要探索、认为包含性能良好模型的一组模型。 模型空间是由用户定义的，用来表达用户想要探索、认为包含性能良好模型的一组模型。 在这个框架中，模型空间由两部分组成：基本模型和基本模型上可能的突变。
+
+定义基本模型
+^^^^^^^^^^^^^^^^^
+
+定义基本模型与定义 PyTorch（或 TensorFlow）模型几乎相同， 只有两个小区别。 对于 PyTorch 模块（例如 ``nn.Conv2d``, ``nn.ReLU``），将代码 ``import torch.nn as nn`` 替换为 ``import nni.retiarii.nn.pytorch as nn`` 。
+
+下面是定义基本模型的一个简单的示例，它与定义 PyTorch 模型几乎相同。
+
+.. code-block:: python
+
+  import torch.nn.functional as F
+  import nni.retiarii.nn.pytorch as nn
+  from nni.retiarii import model_wrapper
+
+  class BasicBlock(nn.Module):
+    def __init__(self, const):
+      self.const = const
+    def forward(self, x):
+      return x + self.const
+
+  class ConvPool(nn.Module):
+    def __init__(self):
+      super().__init__()
+      self.conv = nn.Conv2d(32, 1, 5)  # possibly mutate this conv
+      self.pool = nn.MaxPool2d(kernel_size=2)
+    def forward(self, x):
+      return self.pool(self.conv(x))
+
+  @model_wrapper      # 这个装饰器应该放在最外面的 PyTorch 模块上
+  class Model(nn.Module):
+    def __init__(self):
+      super().__init__()
+      self.convpool = ConvPool()
+      self.mymodule = BasicBlock(2.)
+    def forward(self, x):
+      return F.relu(self.convpool(self.mymodule(x)))
+
+定义模型突变
+^^^^^^^^^^^^^^^^^^^^^^
+
+基本模型只是一个具体模型，而不是模型空间。 我们为用户提供 API 和原语，用于把基本模型变形成包含多个模型的模型空间。
+
+用户可以按以下方式实例化多个 Mutator，这些 Mutator 将依次依次应用于基本模型来对新模型进行采样。 API 可以像 PyTorch 模块一样使用。 这种方法也被称为内联突变。
+
+* ``nn.LayerChoice``， 它允许用户放置多个候选操作（例如，PyTorch 模块），在每个探索的模型中选择其中一个。
+
+  .. code-block:: python
+
+    # import nni.retiarii.nn.pytorch as nn
+    # 在 `__init__` 中声明
+    self.layer = nn.LayerChoice([
+      ops.PoolBN('max', channels, 3, stride, 1),
+      ops.SepConv(channels, channels, 3, stride, 1),
+      nn.Identity()
+    ]))
+    # 在 `forward` 函数中调用
+    out = self.layer(x)
+
+* ``nn.InputChoice``， 它主要用于选择（或尝试）不同的连接。 它会从设置的几个张量中，选择 ``n_chosen`` 个张量。
+
+  .. code-block:: python
+
+    # import nni.retiarii.nn.pytorch as nn
+    # 在 `__init__` 中声明
+    self.input_switch = nn.InputChoice(n_chosen=1)
+    # 在 `forward` 函数中调用，三者选一
+    out = self.input_switch([tensor1, tensor2, tensor3])
+
+* ``nn.ValueChoice``， 它用于从一些候选值中选择一个值。 它只能作为基本单元的输入参数，即 ``nni.retiarii.nn.pytorch`` 中的模块和用 ``@basic_unit`` 装饰的用户定义的模块。
+
+  .. code-block:: python
+
+    # import nni.retiarii.nn.pytorch as nn
+    # 在 `__init__` 中声明
+    self.conv = nn.Conv2d(XX, XX, kernel_size=nn.ValueChoice([1, 3, 5])
+    self.op = MyOp(nn.ValueChoice([0, 1], nn.ValueChoice([-1, 1]))
+
+所有的API都有一个可选的参数，叫做 ``label``，具有相同标签的突变将共享相同的选择。 一个典型示例：
+
+  .. code-block:: python
+
+    self.net = nn.Sequential(
+        nn.Linear(10, nn.ValueChoice([32, 64, 128], label='hidden_dim'),
+        nn.Linear(nn.ValueChoice([32, 64, 128], label='hidden_dim'), 3)
+    )
+
+使用说明和 API 文档在 `这里 <./ApiReference>`__。 详细的 API 描述和使用说明在 `这里 <./ApiReference.rst>`__。 使用这些 API 的示例在 :githublink:`Darts base model <test/retiarii_test/darts/darts_model.py>`。 我们正在积极丰富内联突变 API，使其更容易表达一个新的搜索空间。 参考 `这里 <./construct_space.rst>`__ 获取更多关于表达复杂模型空间的教程。
+
+探索定义的模型空间
+-------------------------------
+
+基本上有两种探索方法：(1)通过独立评估每个采样模型进行搜索；(2)基于 One-Shot 的权重共享式搜索。 我们在本教程中演示了下面的第一种方法。 第二种方法可以参考 `这里 <./OneshotTrainer.rst>`__。
+
+用户可以选择合适的探索策略来探索模型空间，并选择或自定义模型评估器来评估每个采样模型的性能。
+
+选择搜索策略
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Retiarii 支持许多 `探索策略（exploration strategies） <./ExplorationStrategies.rst>`__。
+
+简单地选择（即实例化）一个探索策略：
+
+.. code-block:: python
+
+  import nni.retiarii.strategy as strategy
+
+  search_strategy = strategy.Random(dedup=True)  # dedup=False 如果不希望有重复数据删除
+
+选择或编写模型评估器
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+在 NAS 过程中，探索策略反复生成新模型。 模型评估器用于训练和验证每个生成的模型。 生成的模型所获得的性能被收集起来，并送至探索策略以生成更好的模型。
+
+在 PyTorch 的上下文中，Retiarii 提供了两个内置模型评估器，为简单用例而设计：分类和回归。 这两个评估器是建立在强大的库 PyTorch-Lightning 之上。
+
+这里的一个例子创建了一个简单的评估器，它在 MNIST 数据集上运行，训练 10 个 Epoch，并报告其验证准确性。
+
+.. code-block:: python
+
+  import nni.retiarii.evaluator.pytorch.lightning as pl
+  from nni.retiarii import serialize
+  from torchvision import transforms
+
+  transform = serialize(transforms.Compose, [serialize(transforms.ToTensor()), serialize(transforms.Normalize, (0.1307,), (0.3081,))])
+  train_dataset = serialize(MNIST, root='data/mnist', train=True, download=True, transform=transform)
+  test_dataset = serialize(MNIST, root='data/mnist', train=False, download=True, transform=transform)
+  evaluator = pl.Classification(train_dataloader=pl.DataLoader(train_dataset, batch_size=100),
+                                val_dataloaders=pl.DataLoader(test_dataset, batch_size=100),
+                                max_epochs=10)
+
+由于模型评估器是在另一个进程中运行的（可能是在一些远程机器中），定义的评估器以及它的所有参数都需要被正确序列化。 例如，用户应该使用已经被包装为在 ``nni.retiarii.evaluator.pytorch.lightning`` 中的可序列化类的 dataloader。 对于 dataloader 中使用的参数，需要进行递归序列化，直到参数为 int、str、float 等简单类型。
+
+模型评价器的详细描述和使用方法可以在 `这里 <./ApiReference.rst>`__ 找到。
+
+如果内置的模型评估器不符合您的要求，或者您已经编写了训练代码只是想使用它，您可以参考 `编写新模型评估器的指南 <./WriteTrainer.rst>`__ 。
+
+.. note:: 如果您想在本地运行模型评估器以进行调试，您可以通过 ``evaluator._execute(Net)`` 直接运行评估器（注意它必须是 ``Net``，而不是 ``Net()``）。 但是，此 API 目前是内部的，可能会发生变化。
+
+.. warning:: 目前不支持模型评估器参数的突变（也就是超参数调整），但将未来会支持。
+
+.. warning:: 要在 Retiarii中 使用 PyTorch-lightning，目前你需要安装 PyTorch-lightning v1.1.x（不支持 v1.2）。
+
+发起 Experiment
+--------------------
+
+上述内容准备就绪之后，就可以发起 Experiment 以进行模型搜索了。 样例如下：
+
+.. code-block:: python
+
+  exp = RetiariiExperiment(base_model, trainer, None, simple_strategy)
+  exp_config = RetiariiExeConfig('local')
+  exp_config.experiment_name = 'mnasnet_search'
+  exp_config.trial_concurrency = 2
+  exp_config.max_trial_number = 10
+  exp_config.training_service.use_active_gpu = False
+  exp.run(exp_config, 8081)
+
+一个简单 MNIST 示例的完整代码在 :githublink:`这里 <test/retiarii_test/mnist/test.py>`。 除了本地训练平台，用户还可以在 `不同的训练平台 <../training_services.rst>`__ 上运行 Retiarii 的实验。
+
+可视化 Experiment
+------------------------
+
+用户可以像可视化普通的超参数调优 Experiment 一样可视化他们的 Experiment。 例如，在浏览器里打开 ``localhost::8081``，8081 是在 ``exp.run`` 里设置的端口。 参考 `这里 <../Tutorial/WebUI.rst>`__ 了解更多细节。
+
+导出最佳模型
+-----------------
+
+探索完成后，用户可以使用 ``export_top_models`` 导出最佳模型。
+
+.. code-block:: python
+
+  for model_code in exp.export_top_models(formatter='dict'):
+    print(model_code)

docs/zh_CN/NAS/SPOS.rst

@@ -99,12 +99,6 @@
 PyTorch
 ^^^^^^^
 
-..  autoclass:: nni.algorithms.nas.pytorch.spos.SPOSEvolution
-    :members:
-
-..  autoclass:: nni.algorithms.nas.pytorch.spos.SPOSSupernetTrainer
-    :members:
-
 ..  autoclass:: nni.algorithms.nas.pytorch.spos.SPOSSupernetTrainingMutator
     :members:
 

docs/zh_CN/NAS/SearchSpaceZoo.rst

-.. role:: raw-html(raw)
-   :format: html
-
-
-搜索空间集合
-================
-
-DartsCell
----------
-
-DartsCell 是从 :githublink:`CNN 模型<examples/nas/darts>` 中提取的。 一个 DartsCell 是一个包含 N 个节点的序列的有向无环图 ，其中每个节点代表一个潜在特征的表示（例如， 卷积网络中的特征图）。 从节点 1 到节点 2 的有向边表示一些将节点 1 转换为节点 2 的操作。这些操作获取节点 1 的值并将转换的结果储存在节点 2 上。 节点之间的 `Candidate <＃predefined-operations-darts>`__ 是预定义的且不可更改。 一条边表示从预定义的操作中选择的一项，并将该操作将应用于边的起始节点。 一个 cell 包括两个输入节点，一个输出节点和其他 ``n_node`` 个节点。 输入节点定义为前两个 cell 的输出。 cell 的输出是通过应用归约运算到所有中间节点（例如， 级联）。 为了使搜索空间连续，在所有可能的操作上通过 softmax 对特定操作选择进行松弛。 通过调整每个节点上 softmax 的权重，选择概率最高的操作作为最终结构的一部分。 可以通过堆叠多个 cell 组成一个 CNN 模型，从而构建一个搜索空间。 值得注意的是，在 DARTS 论文中，模型中的所有 cell 都具有相同的结构。
-
-ENAS Micro 的搜索空间如下图所示。 请注意，在 NNI 的实现中将最后一个中间节点与输出节点进行了合并。
-
-
-.. image:: ../../img/NAS_Darts_cell.svg
-   :target: ../../img/NAS_Darts_cell.svg
-   :alt: 
-
-
-预定义的操作在 `参考 <#predefined-operations-darts>`__ 中列出。
-
-..  autoclass:: nni.nas.pytorch.search_space_zoo.DartsCell
-    :members:
-
-示例代码
-^^^^^^^^^^^^
-
-:githublink:`示例代码 <examples/nas/search_space_zoo/darts_example.py>`
-
-.. code-block:: bash
-
-   git clone https://github.com/Microsoft/nni.git
-   cd nni/examples/nas/search_space_zoo
-   # 搜索最优结构
-   python3 darts_example.py
-
-:raw-html:`<a name="predefined-operations-darts"></a>`
-
-候选运算符
-^^^^^^^^^^^^^^^^^^^
-
-所有 Darts 支持的操作如下。
-
-
-* 
-  最大池化 / 平均池化
-
-
-  * 最大池化：调用 ``torch.nn.MaxPool2d``。 这个操作对所有输入的通道进行最大池化。 参数 ``kernel_size = 3`` 和 ``padding = 1`` 是固定的。 在池化操作后通过 BatchNorm2d 得到最终结果。
-  * 
-    平均池化：调用 ``torch.nn.AvgPool2d``。 这个操作对所有输入的通道进行平均池化。 参数 ``kernel_size = 3`` 和 ``padding = 1`` 是固定的。 在池化操作后通过 BatchNorm2d 得到最终结果。
-
-    参数为 ``kernel_size=3`` 和 ``padding=1`` 的最大池化操作和平均池化操作后均有 BatchNorm2d 操作。
-
-..  autoclass:: nni.nas.pytorch.search_space_zoo.darts_ops.PoolBN
-
-* 
-  跳过连接
-
-    两个节点之间没有任何操作。 调用 ``torch.nn.Identity`` 将其获取的内容转发到输出。
-
-* 
-  零操作
-
-    两个节点之间没有连接。
-
-* 
-  DilConv3x3 / DilConv5x5
-
-    :raw-html:`<a name="DilConv"></a>`\ DilConv3x3: (Dilated) depthwise separable Conv. 3x3 深度可分离卷积是由 ``C_in`` 组的 3x3 深度卷积和 1x1 的卷积串联组成。 这个操作减少了参数的数量。 输入首先通过 RelLU，然后通过 DilConv，最后是 batchNorm2d。 **请注意这个操作不是扩散卷积，但是按照 NAS 论文中的约定命名为 DilConv。** 3x3 深度可分离卷积的参数是 ``kernel_size=3``,  ``padding=1`` 。5x5 深度可分离卷积的参数是 ``kernel_size=5``, ``padding=4``。
-
-  ..  autoclass:: nni.nas.pytorch.search_space_zoo.darts_ops.DilConv
-
-* 
-  SepConv3x3 / SepConv5x5
-
-    由两个顺序固定为 ``kernel_size = 3``，``padding = 1`` 或 ``kernel_size = 5``，``padding = 2`` 的 DilConv 组成。
-
-  ..  autoclass:: nni.nas.pytorch.search_space_zoo.darts_ops.SepConv
-
-ENASMicroLayer
---------------
-
-这层是由 :githublink:`这里 <examples/nas/enas>` 的模型提取出来的。 一个模型包含共享结构的多个块。 一个块由一些常规层和约简层组成，``ENASMicroLayer`` 是这两型层的统一实现。 这两类层之间的唯一区别是约简层的所有操作 ``stride=2``。
-
-ENAS Micro 的一个 cell 是含有 N 个节点的有向无环图。其中节点表示张量，边表示 N 个节点间的信息流。 一个 cell 包含两个输入节点和一个输出节点。 接下来节点选择前两个之前的节点作为输入，并从 `预定义的的操作集 <#predefined-operations-enas>`__ 中选择两个操作，分别应用到输入上，然后将它们相加为该节点的输出。 例如，节点 4 选择节点 1 和节点 3 作为输入，然后分别对输入应用 
- ``MaxPool`` 和 ``AvgPool``，然后将它们相加作为节点 4 的输出。 未用作任何其他节点输入的节点将被视为该层的输出。 如果有多个输出节点，则模型将计算这些节点的平均值作为当前层的输出。
-
-ENAS Micro 的搜索空间如下图所示。
-
-
-.. image:: ../../img/NAS_ENAS_micro.svg
-   :target: ../../img/NAS_ENAS_micro.svg
-   :alt: 
- 
-
-预定义的操作在 `参考 <#predefined-operations-enas>`__ 中列出。
-
-..  autoclass:: nni.nas.pytorch.search_space_zoo.ENASMicroLayer
-    :members:
-
-归约层由两个卷积操作和之后的 BatchNorm 组成，每个卷积操作都将输出 ``C_out//2`` 个通道并将它们在通道方向上串联作为输出。 卷积的参数是 ``kernel_size=1``，``stride=2``，并且它们对输入进行交替采样以降低分辨率而不会丢失信息。 该层封装在 ``ENASMicroLayer`` 中。
-
-示例代码
-^^^^^^^^^^^^
-
-:githublink:`示例代码 <examples/nas/search_space_zoo/enas_micro_example.py>`
-
-.. code-block:: bash
-
-   git clone https://github.com/Microsoft/nni.git
-   cd nni/examples/nas/search_space_zoo
-   # 搜索最优结构
-   python3 enas_micro_example.py
-
-:raw-html:`<a name="predefined-operations-enas"></a>`
-
-候选运算符
-^^^^^^^^^^^^^^^^^^^
-
-所有 ENAS Micro 支持的操作如下。
-
-
-* 
-  最大池化 / 平均池化
-
-
-  * 最大池化：调用 ``torch.nn.MaxPool2d``。 这个操作对所有输入的通道进行最大池化，之后进行 BatchNorm2d。 参数固定为  ``kernel_size=3``\ , ``stride=1`` 和 ``padding=1``。
-  * 平均池化：调用 ``torch.nn.AvgPool2d``。 这个操作对所有输入的通道进行最大池化，之后进行 BatchNorm2d。 参数固定为  ``kernel_size=3``\ , ``stride=1`` 和 ``padding=1``。
-
-..  autoclass:: nni.nas.pytorch.search_space_zoo.enas_ops.Pool
-
-* 
-  SepConv
-
-
-  * SepConvBN3x3：首先进行ReLU，之后进行 `DilConv <#DilConv>`__ ，最后是BatchNorm2d。 卷积参数固定为  ``kernel_size=3``\ , ``stride=1`` 和 ``padding=1``。
-  * 
-    SepConvBN5x5：进行与之前相同的操作，但是它具有不同的内核大小和填充，分别设置为 5 和 2。
-
-..  autoclass:: nni.nas.pytorch.search_space_zoo.enas_ops.SepConvBN
-
-* 
-  跳过连接
-
-    调用 ``torch.nn.Identity`` 直接连接到一个 cell。
-
-ENASMacroLayer
---------------
-
-在宏搜索中，控制器为每个层做出两个决定：i）对上一层的结果执行的 `操作 <#macro-operations>`__ ，ii）通过跳过连接，连接到之前的那个层。 ENAS 使用控制器来设计整个模型结构而不是模型的某一部分。 操作的输出将与跳过连接的所选层的张量连接在一起。 NNI 为宏搜索提供 `预定义运算符 <＃macro-operations>`__，这些宏在 `候选运算符 <＃macro-operations>`__ 中列出。
-
-ENAS Macro 的搜索空间如下图所示。
-
-
-.. image:: ../../img/NAS_ENAS_macro.svg
-   :target: ../../img/NAS_ENAS_macro.svg
-   :alt: 
-
-
-..  autoclass:: nni.nas.pytorch.search_space_zoo.ENASMacroLayer
-    :members:
-
-为了描述整个搜索空间，NNI 提供了一个模型，该模型是通过堆叠 ENASMacroLayer 构成的。
-
-..  autoclass:: nni.nas.pytorch.search_space_zoo.ENASMacroGeneralModel
-    :members:
-
-示例代码
-^^^^^^^^^^^^
-
-:githublink:`示例代码 <examples/nas/search_space_zoo/enas_macro_example.py>`
-
-.. code-block:: bash
-
-   git clone https://github.com/Microsoft/nni.git
-   cd nni/examples/nas/search_space_zoo
-   # search the best cell structure
-   python3 enas_macro_example.py
-
-:raw-html:`<a name="macro-operations"></a>`
-
-候选运算符
-^^^^^^^^^^^^^^^^^^^
-
-所有 ENAS Macro 支持的操作如下。
-
-
-* 
-  ConvBranch
-
-    首先将所有输入传递到 StdConv，该操作由 1x1Conv，BatchNorm2d 和 ReLU 组成。 然后进行下列的操作之一。 最终结果通过后处理，包括BatchNorm2d和ReLU。
-
-
-  * Separable Conv3x3：如果 ``separable=True``，则 cell 将使用 `SepConv <#DilConv>`__ 而不是常规的卷积操作。 SepConv 固定为  ``kernel_size=3``\ , ``stride=1`` 和 ``padding=1``。
-  * Separable Conv5x5: SepConv 固定为 ``kernel_size=5``\ , ``stride=1`` 和 ``padding=2``。
-  * Normal Conv3x3: 如果 ``separable=False``\ , cell 将使用常规的转化操作 ``kernel_size=3``\ , ``stride=1`` 和 ``padding=1``。
-  * 
-    Normal Conv5x5：Conv 固定为 ``kernel_size=5``\ , ``stride=1`` 和 ``padding=2``。
-
-..  autoclass:: nni.nas.pytorch.search_space_zoo.enas_ops.ConvBranch
-
-* 
-  PoolBranch
-
-    首先将所有输入传递到 StdConv，该操作由 1x1Conv，BatchNorm2d 和 ReLU 组成。 然后对中间结果进行池化操作和 BatchNorm。
-
-
-  * 平均池化：调用 ``torch.nn.AvgPool2d``。 这个操作对所有输入的通道进行平均池化。 参数固定为  ``kernel_size=3``\ , ``stride=1`` 和 ``padding=1``。
-  * 
-    最大池化：调用 ``torch.nn.MaxPool2d``。 这个操作对所有输入的通道进行最大池化。 参数固定为  ``kernel_size=3``\ , ``stride=1`` 和 ``padding=1``。
-
-..  autoclass:: nni.nas.pytorch.search_space_zoo.enas_ops.PoolBranch
-
-NAS-Bench-201
--------------
-
-NAS Bench 201 定义了与算法无关的统一搜索空间。 预定义的骨架由共享相同体系结构的 cell 堆栈组成。 每个 cell 包含四个节点，并且通过连接它们之间的边来形成 DAG，其中该节点表示特征图的总和，并且边表示将张量从源节点转换为目标节点的操作。 预定义的候选运算符可以在 `候选运算符 <#nas-bench-201-reference>`__ 中找到。
-
-NAS Bench 201 的搜索空间如下所示。
-
-
-.. image:: ../../img/NAS_Bench_201.svg
-   :target: ../../img/NAS_Bench_201.svg
-   :alt: 
-
-
-..  autoclass:: nni.nas.pytorch.nasbench201.NASBench201Cell
-    :members:
-
-示例代码
-^^^^^^^^^^^^
-
-:githublink:`示例代码 <examples/nas/search_space_zoo/nas_bench_201.py>`
-
-.. code-block:: bash
-
-   # for structure searching
-   git clone https://github.com/Microsoft/nni.git
-   cd nni/examples/nas/search_space_zoo
-   python3 nas_bench_201.py
-
-:raw-html:`<a name="nas-bench-201-reference"></a>`
-
-候选运算符
-^^^^^^^^^^^^^^^^^^^
-
-所有 NAS Bench 201 支持的操作如下。
-
-
-* 
-  AvgPool
-
-  如果输入通道数不等于输出通道数，则输入会首先通过 ``kernel_size = 1``，``stride = 1``，``padding = 0`` 和 ``dilation = 0`` 的 ``ReLUConvBN`` 层 。
-  调用 ``torch.nn.AvgPool2d``。 这个操作对所有输入的通道进行最大池化，之后进行BatchNorm2d。 参数固定为  ``kernel_size=3`` 和 ``padding=1``。
-
-..  autoclass:: nni.nas.pytorch.nasbench201.nasbench201_ops.Pooling
-    :members:
-
-* 
-  Conv
-
-
-  * Conv1x1: 由一些列 ReLU，``nn.Cinv2d`` 和 BatchNorm 组成。 Conv 操作的参数固定为 ``kernal_size = 1``，``padding = 0`` 和 ``dilation = 1``。
-  * Conv3x3: 由一些列 ReLU，``nn.Cinv2d`` 和 BatchNorm 组成。 Conv 操作的参数固定为 ``kernal_size = 3``，``padding = 1`` 和 ``dilation = 1``。
-
-..  autoclass:: nni.nas.pytorch.nasbench201.nasbench201_ops.ReLUConvBN
-    :members:
-
-* 
-  跳过连接
-
-  调用 ``torch.nn.Identity`` 直接连接到一个 cell。
-
-* 
-  归零
-
-  没有生成 tensors 表示从源节点到目标节点之间没有连接。
-
-..  autoclass:: nni.nas.pytorch.nasbench201.nasbench201_ops.Zero
-    :members:

docs/zh_CN/NAS/TextNAS.rst

-TextNAS
-=======
-
-介绍
-------------
-
-这是 `TextNAS: A Neural Architecture Search Space tailored for Text Representation <https://arxiv.org/pdf/1912.10729.pdf>`__ 提出的 TextNAS 算法的实现。 TextNAS 是用于文本表示的神经网络架构搜索算法，具体来说，TextNAS 基于由适配各种自然语言任务的操作符所组成的新的搜索空间，TextNAS 还支持单个网络中的多路径集成，来平衡网络的宽度和深度。 
-
-TextNAS 的搜索空间包含： 
-
-.. code-block:: bash
-
-   * 滤波器尺寸为 1, 3, 5, 7 的一维卷积操作 
-   * 循环操作符（双向 GRU） 
-   * 自注意操作符
-   * 池化操作符（最大值、平均值）
-
-
-遵循 ENAS 算法，TextNAS 也用了参数共享来加速搜索速度，并采用了强化学习的 Controller 来进行架构采样和生成。 参考 TextNAS 论文了解更多细节。
-
-准备
------------
-
-准备词向量和 SST 数据集，并按如下结构放到 data 目录中：
-
-.. code-block:: bash
-
-   textnas
-   ├── data
-   │   ├── sst
-   │   │   └── trees
-   │   │       ├── dev.txt
-   │   │       ├── test.txt
-   │   │       └── train.txt
-   │   └── glove.840B.300d.txt
-   ├── dataloader.py
-   ├── model.py
-   ├── ops.py
-   ├── README.md
-   ├── search.py
-   └── utils.py
-
-以下链接有助于查找和下载相应的数据集：
-
-
-* `GloVe: Global Vectors for Word Representation <https://nlp.stanford.edu/projects/glove/>`__
-
-  * `glove.840B.300d.txt <http://nlp.stanford.edu/data/glove.840B.300d.zip>`__
-
-* `Recursive Deep Models for Semantic Compositionality Over a Sentiment Treebank <https://nlp.stanford.edu/sentiment/>`__
-
-  * `trainDevTestTrees_PTB.zip <https://nlp.stanford.edu/sentiment/trainDevTestTrees_PTB.zip>`__
-
-示例
---------
-
-搜索空间
-^^^^^^^^^^^^
-
-:githublink:`示例代码 <examples/nas/textnas>`
-
-.. code-block:: bash
-
-   ＃如果未克隆 NNI 代码。 如果代码已被克隆，请忽略此行并直接进入代码目录。
-   git clone https://github.com/Microsoft/nni.git
-
-   # 搜索最优结构
-   cd examples/nas/textnas
-
-   # 查看更多的搜索选择
-   python3 search.py -h
-
-在每个搜索 Epoch 后，会直接测试 10 个采样的结构。 10 个 Epoch 后的性能预计为 40% - 42%。
-
-默认情况下，20 个采样结构会被导出到 ``checkpoints`` 目录中，以便进行下一步处理。
-
-重新训练
-^^^^^^^^^^^^
-
-.. code-block:: bash
-
-   ＃如果未克隆 NNI 代码。 如果代码已被克隆，请忽略此行并直接进入代码目录。
-   git clone https://github.com/Microsoft/nni.git
-
-   # 搜索最优结构
-   cd examples/nas/textnas
-
-   # default to retrain on sst-2
-   sh run_retrain.sh
-
-参考
----------
-
-TextNAS 直接使用了 EnasTrainer，参考 `ENAS <./ENAS.rst>`__ 了解 Trainer 的 API。

docs/zh_CN/NAS/Visualization.rst

-NAS 可视化（测试版）
-================================
-
-内置 Trainer 支持
--------------------------
-
-当前，仅 ENAS 和 DARTS 支持可视化。 `ENAS <./ENAS.rst>`__ 和 `DARTS <./DARTS.rst>`__ 的示例演示了如何在代码中启用可视化，其需要在 ``trainer.train()`` 前添加代码。
-
-.. code-block:: python
-
-   trainer.enable_visualization()
-
-此代码会在当前目录中创建新目录 ``logs/<current_time_stamp>``，并创建两个新文件 ``graph.json`` 和 ``log``。
-
-不必等到程序运行完后，再启动 NAS 界面，但需要确保这两个文件产生后，再启动。 启动 NAS 界面：
-
-.. code-block:: bash
-
-   nnictl webui nas --logdir logs/<current_time_stamp> --port <port>
-
-可视化定制的 Trainer
-------------------------------
-
-如果要定制 Trainer，参考 `文档 <./Advanced.rst#extend-the-ability-of-one-shot-trainers>`__。
-
-需要对已有 Trainer 代码做两处改动来支持可视化：
-
-
-#. 在训练前导出图：
-
-.. code-block:: python
-
-   vis_graph = self.mutator.graph(inputs)
-   # `inputs` is a dummy input to your model. For example, torch.randn((1, 3, 32, 32)).cuda()
-   # If your model has multiple inputs, it should be a tuple.
-   with open("/path/to/your/logdir/graph.json", "w") as f:
-       json.dump(vis_graph, f)
-
-
-#. 记录选择的 Choice。 可以每个 Epoch，批处理或任何频率下做次记录。
-
-.. code-block:: python
-
-   def __init__(self):
-       # ...
-       self.status_writer = open("/path/to/your/logdir/log", "w")  # create a writer
-
-   def train(self):
-       # ...
-       print(json.dumps(self.mutator.status()), file=self.status_writer, flush=True)  # dump a record of status
-
-如果继承 ``Trainer``，实现定制的 Trainer。 NNI 提供了 ``enable_visualization()`` 和 ``_write_graph_status()`` 来简化可视化。 只需要在开始前调用 ``trainer.enable_visualization()``，并在每次要记录日志前调用 ``trainer._write_graph_status()``。 注意，这两个 API 还处于试用阶段，未来可能会有所更改。
-
-最后，启动 NAS 界面：
-
-.. code-block:: bash
-
-   nnictl webui nas --logdir /path/to/your/logdir
-
-NAS 界面预览
---------------
-
-
-.. image:: ../../img/nasui-1.png
-   :target: ../../img/nasui-1.png
-   :alt: 
-
-
-
-.. image:: ../../img/nasui-2.png
-   :target: ../../img/nasui-2.png
-   :alt: 
-
-
-局限性
------------
-
-
-* NAS 可视化仅适用于 PyTorch >= 1.4。 PyTorch 1.3.1 上无法使用。
-* 其依赖于 PyTorch 对 tensorboard 导出图的支持，即依赖于 ``torch.jit``。 如果模型不支持 ``jit``，也无法使用。
-
-* 在加载中等大小，但有许多 Choice 的模型时（如 DARTS 的搜索空间），会遇到性能问题。
-
-反馈
---------
-
-NAS UI 目前是测试版。 欢迎提交反馈。 `这里 <https://github.com/microsoft/nni/pull/2085>`__ 列出了 NAS UI 接下来的工作。 欢迎直接评论，如果有其它建议，也可以 `提交新问题 <https://github.com/microsoft/nni/issues/new?template=enhancement.rst>`__。

docs/zh_CN/NAS/WriteOneshot.rst

+自定义 One-shot Trainer
+=========================================
+
+One-shot Trainer 应继承 ``nni.retiarii.oneshot.BaseOneShotTrainer``，并需要实现``fit()`` 函数（用于进行拟合和搜索过程）和 ``export()`` 方法（用于返回搜索到的最佳架构）。
+
+编写一个 One-Shot Trainer 与单个结构的 evaluator 有很大不同。 首先，init 方法参数没有限制，可以接收任何 Python 参数。 其次，输入到 One-Shot Trainer 中的模型可能带有 Retiarii 特定的模块（例如 LayerChoice 和 InputChoice）的模型。 这种模型不能直接向前传播，Trainer 需要决定如何处理这些模块。
+
+一个典型的示例是 DartsTrainer，其中可学习参数用于在 LayerChoice 中组合多个 Choice。 Retiarii为模块替换提供了易于使用的函数，即 ``replace_layer_choice``, ``replace_input_choice``。 示例如下。 
+
+.. code-block:: python
+
+    from nni.retiarii.oneshot import BaseOneShotTrainer
+    from nni.retiarii.oneshot.pytorch import replace_layer_choice, replace_input_choice
+
+
+    class DartsLayerChoice(nn.Module):
+        def __init__(self, layer_choice):
+            super(DartsLayerChoice, self).__init__()
+            self.name = layer_choice.key
+            self.op_choices = nn.ModuleDict(layer_choice.named_children())
+            self.alpha = nn.Parameter(torch.randn(len(self.op_choices)) * 1e-3)
+
+        def forward(self, *args, **kwargs):
+            op_results = torch.stack([op(*args, **kwargs) for op in self.op_choices.values()])
+            alpha_shape = [-1] + [1] * (len(op_results.size()) - 1)
+            return torch.sum(op_results * F.softmax(self.alpha, -1).view(*alpha_shape), 0)
+
+
+    class DartsTrainer(BaseOneShotTrainer):
+
+        def __init__(self, model, loss, metrics, optimizer):
+            self.model = model
+            self.loss = loss
+            self.metrics = metrics
+            self.num_epochs = 10
+
+            self.nas_modules = []
+            replace_layer_choice(self.model, DartsLayerChoice, self.nas_modules)
+
+            ... # 初始化 dataloaders 和 optimizers
+
+        def fit(self):
+            for i in range(self.num_epochs):
+                for (trn_X, trn_y), (val_X, val_y) in zip(self.train_loader, self.valid_loader):
+                    self.train_architecture(val_X, val_y)
+                    self.train_model_weight(trn_X, trn_y)
+
+        @torch.no_grad()
+        def export(self):
+            result = dict()
+            for name, module in self.nas_modules:
+                if name not in result:
+                    result[name] = select_best_of_module(module)
+            return result
+
+Retsarii 源代码提供了 DartsTrainer 的完整代码。 请参考 :githublink:`DartsTrainer <nni/retiarii/oneshot/pytorch/darts.py>`。

docs/zh_CN/NAS/WriteSearchSpace.rst

-编写搜索空间
-====================
-
-通常，搜索空间是要在其中找到最好结构的候选项。 无论是经典 NAS 还是 One-Shot NAS，不同的搜索算法都需要搜索空间。 NNI 提供了统一的 API 来表达神经网络架构的搜索空间。
-
-搜索空间可基于基础模型来构造。 这也是在已有模型上使用 NAS 的常用方法。 `MNIST on PyTorch <https://github.com/pytorch/examples/blob/master/mnist/main.py>`__ 是一个例子。 注意，NNI 为 PyTorch 和 TensorFlow 提供了同样的搜索空间 API。
-
-.. code-block:: python
-
-   from nni.nas.pytorch import mutables
-
-   class Net(nn.Module):
-       def __init__(self):
-           super(Net, self).__init__()
-           self.conv1 = mutables.LayerChoice([
-               nn.Conv2d(1, 32, 3, 1),
-               nn.Conv2d(1, 32, 5, 3)
-           ])  # try 3x3 kernel and 5x5 kernel
-           self.conv2 = nn.Conv2d(32, 64, 3, 1)
-           self.dropout1 = nn.Dropout2d(0.25)
-           self.dropout2 = nn.Dropout2d(0.5)
-           self.fc1 = nn.Linear(9216, 128)
-           self.fc2 = nn.Linear(128, 10)
-
-       def forward(self, x):
-           x = self.conv1(x)
-           x = F.relu(x)
-           # ... same as original ...
-           return output
-
-以上示例在 conv1 上添加了 conv5x5 的选项。 修改非常简单，只需要声明 ``LayerChoice`` 并将原始的 conv3x3 和新的 conv5x5 作为参数即可。 就这么简单！ 不需要修改 forward 函数。 可将 conv1 想象为没有 NAS 的模型。
-
-如何表示可能的连接？ 通过 ``InputChoice`` 来实现。 要在 MNIST 示例上使用跳过连接，需要增加另一层 conv3。 下面的示例中，从 conv2 的可能连接加入到了 conv3 的输出中。
-
-.. code-block:: python
-
-   from nni.nas.pytorch import mutables
-
-   class Net(nn.Module):
-       def __init__(self):
-           # ... same ...
-           self.conv2 = nn.Conv2d(32, 64, 3, 1)
-           self.conv3 = nn.Conv2d(64, 64, 1, 1)
-           # declaring that there is exactly one candidate to choose from
-           # search strategy will choose one or None
-           self.skipcon = mutables.InputChoice(n_candidates=1)
-           # ... same ...
-
-       def forward(self, x):
-           x = self.conv1(x)
-           x = F.relu(x)
-           x = self.conv2(x)
-           x0 = self.skipcon([x])  # choose one or none from [x]
-           x = self.conv3(x)
-           if x0 is not None:  # skipconnection is open
-               x += x0
-           x = F.max_pool2d(x, 2)
-           # ... same ...
-           return output
-
-Input Choice 可被视为可调用的模块，它接收张量数组，输出其中部分的连接、求和、平均（默认为求和），或没有选择时输出 ``None``。 就像 layer choices, input choices，应该用 ``__init__`` 来初始化，用 ``forward`` 来回调。 这会让搜索算法找到这些 Choice，并进行所需的准备。
-
-``LayerChoice`` and ``InputChoice`` 都是 **mutables**。 Mutable 表示 "可变化的"。 与传统深度学习层、模型都是固定的不同，使用 Mutable 的模块，是一组可能选择的模型。
-
-用户可以为每一个 mutable 声明一个 key。 默认情况下，NNI 会分配全局唯一的，但如果需要共享 Choice（例如，两个 ``LayerChoice`` 有同样的候选操作，希望共享同样的 Choice。即，如果一个选择了第 i 个操作，第二个也要选择第 i 个操作），那么就应该给它们相同的 key。 key 标记了此 Choice，并会在存储的检查点中使用。 如果要增加导出架构的可读性，可为每个 Mutable 的 key 指派名称。 mutables 的高级用法请参照文档 `Mutables <./NasReference.rst>`__。
-
-定义了搜索空间后，下一步是从中找到最好的模型。 至于如何从定义的搜索空间进行搜索请参阅 `经典 NAS 算法 <./ClassicNas.rst>`__ 和 `one-shot NAS 算法 <./NasGuide.rst>`__ 。

docs/zh_CN/NAS/retiarii/WriteStrategy.rst → docs/zh_CN/NAS/WriteStrategy.rst

-自定义 Strategy
-========================
+自定义探索 Strategy
+======================================
 
-要编写新策略，应该继承基本策略类 ``BaseStrategy``，然后实现成员函数 ``run``。 此成员函数将 ``base_model`` 和 ``applied_mutators`` 作为输入参数， 并将用户在 ``applied_mutators`` 中指定的 Mutator 应用到 ``base_model`` 中生成新模型。 当应用一个 Mutator 时，应该与一个 sampler 绑定（例如，``RandomSampler``）。 每个 sampler 都实现了从候选值中选择值的 ``choice`` 函数。 在 Mutator 中调用 ``choice`` 函数是用 sampler 执行的。
+如果用户想研究一个新的探索策略，他们可以按照 NNI 提供的接口轻松定制一个新的策略。 要编写新策略，应该继承基本策略类 ``BaseStrategy``，然后实现成员函数 ``run``。 此成员函数将 ``base_model`` 和 ``applied_mutators`` 作为输入参数， 并将用户在 ``applied_mutators`` 中指定的 Mutator 应用到 ``base_model`` 中生成新模型。 当应用一个 Mutator 时，应该与一个 sampler 绑定（例如，``RandomSampler``）。 每个 sampler 都实现了从候选值中选择值的 ``choice`` 函数。 在 Mutator 中调用 ``choice`` 函数是用 sampler 执行的。
 
 下面是一个非常简单的随机策略，它使选择完全随机。
 

docs/zh_CN/NAS/retiarii/WriteTrainer.rst → docs/zh_CN/NAS/WriteTrainer.rst

-自定义 Trainer
-=======================
+自定义模型 Evaluator
+===============================
 
-Trainer 对评估新模型的性能是必要的。 在 NAS 场景中，Trainer 进一步分为两类：
+模型评估器（Evaluator）对于评估新探索的模型的性能是必要的。 一个模型评估器通常包括训练、验证和测试一个单一的模型。 我们为用户提供了两种方法来编写新的模型评估器，下面将分别演示。
 
-1. **Single-arch trainers**：用于训练和评估单个模型的 Trainer。
-2. **One-shot trainers**：端到端同时处理训练和搜索的 Trainer。
+使用 FunctionalEvaluator
+------------------------
 
-Single-arch trainers
---------------------
+定制一个新的评估器的最简单的方法是使用功能性的 API，当训练代码已经可用时，这就非常容易。 用户只需要编写一个 fit 函数来包装所有内容。 此函数接收一个位置参数（``model_cls``）和可能的关键字参数。 关键字参数（除 ``model_cls`` 外）作为 FunctionEvaluator 的初始化参数被输入。 通过这种方式，用户可以控制一切，但向框架公开的信息较少，因此进行优化的机会也较少。 示例如下。
+
+.. code-block:: python
+
+    from nni.retiarii.evaluator import FunctionalEvaluator
+    from nni.retiarii.experiment.pytorch import RetiariiExperiment
+
+    def fit(model_cls, dataloader):
+        model = model_cls()
+        train(model, dataloader)
+        acc = test(model, dataloader)
+        nni.report_final_result(acc)
+
+    evaluator = FunctionalEvaluator(fit, dataloader=DataLoader(foo, bar))
+    experiment = RetiariiExperiment(base_model, evaluator, mutators, strategy)
+
+.. note:: 由于我们目前的实施限制，``fit`` 函数应该放在另一个 python 文件中，而不是放在主文件中。 这个限制将在未来的版本中得到修复。
 
 使用 PyTorch-Lightning
-^^^^^^^^^^^^^^^^^^^^^^
+----------------------
 
-NNI 建议以 PyTorch-Lightning 风格编写训练代码，即编写一个 LightningModule，定义训练所需的所有元素（例如 loss function、optimizer），并定义一个 Trainer，使用 dataloader 来执行训练（可选）。 在此之前，请阅读 `PyTorch-lightning 文档 <https://pytorch-lightning.readthedocs.io/>` 了解 PyTorch-lightning 的基本概念和组件。
+NNI 建议以 PyTorch-Lightning 风格编写训练代码，即编写一个 LightningModule，定义训练所需的所有元素（例如 loss function、optimizer），并定义一个 Trainer，使用 dataloader 来执行训练（可选）。 在此之前，请阅读 `PyTorch-lightning 文档 <https://pytorch-lightning.readthedocs.io/>` 了解 PyTorch-lightning 的基本概念和组件。 在此之前，请阅读 `PyTorch-lightning 文档 <https://pytorch-lightning.readthedocs.io/>`__ 了解 PyTorch-lightning 的基本概念和组件。
 
-在实践中，在 NNI 中编写一个新的训练模块应继承 ``nni.retiarii.trainer.pytorch.lightning.LightningModule``，它将在 ``__init__`` 之后调用 ``set_model`` 函数，以将候选模型（由策略生成的）保存为 ``self.model``。 编写其余过程（如 ``training_step``）应与其他 lightning 模块相同。 Trainer 还应该通过两个 API 调用与策略进行通讯（对于中间指标而言为 ``nni.report_intermediate_result``，对于最终指标而言为 ``nni.report_final_result``），分别被添加在 ``on_validation_epoch_end`` 和 ``teardown`` 中。 
+在实践中，在 NNI 中编写一个新的训练模块应继承 ``nni.retiarii.trainer.pytorch.lightning.LightningModule``，它将在 ``__init__`` 之后调用 ``set_model`` 函数，以将候选模型（由策略生成的）保存为 ``self.model``。 编写其余过程（如 ``training_step``）应与其他 lightning 模块相同。 Evaluators 还应该通过两个 API 调用与策略进行通讯（对于中间指标而言为 ``nni.report_intermediate_result``，对于最终指标而言为 ``nni.report_final_result``），分别被添加在 ``on_validation_epoch_end`` 和 ``teardown`` 中。 
 
 示例如下。
 
-.. code-block::python
+.. code-block:: python
 
-    from nni.retiarii.trainer.pytorch.lightning import LightningModule  # please import this one
+    from nni.retiarii.evaluator.pytorch.lightning import LightningModule  # please import this one
 
-    @blackbox_module
+    @basic_unit
     class AutoEncoder(LightningModule):
         def __init__(self):
             super().__init__()
@@ -41,7 +56,7 @@ NNI 建议以 PyTorch-Lightning 风格编写训练代码，即编写一个 Light
             # 它独立于 forward 函数
             x, y = batch
             x = x.view(x.size(0), -1)
-            z = self.model(x)  # model is the one that is searched for
+            z = self.model(x)  # 模型是一个被搜索的模型
             x_hat = self.decoder(z)
             loss = F.mse_loss(x_hat, x)
             # 默认日志记录到 TensorBoard
@@ -69,9 +84,9 @@ NNI 建议以 PyTorch-Lightning 风格编写训练代码，即编写一个 Light
 
 然后，用户需要将所有东西（包括 LightningModule、trainer 和 dataloaders）包装成一个 ``Lightning`` 对象，并将这个对象传递给 Retiarii Experiment。
 
-.. code-block::python
+.. code-block:: python
 
-    import nni.retiarii.trainer.pytorch.lightning as pl
+    import nni.retiarii.evaluator.pytorch.lightning as pl
     from nni.retiarii.experiment.pytorch import RetiariiExperiment
 
     lightning = pl.Lightning(AutoEncoder(),
@@ -79,79 +94,3 @@ NNI 建议以 PyTorch-Lightning 风格编写训练代码，即编写一个 Light
                              train_dataloader=pl.DataLoader(train_dataset, batch_size=100),
                              val_dataloaders=pl.DataLoader(test_dataset, batch_size=100))
     experiment = RetiariiExperiment(base_model, lightning, mutators, strategy)
-
-使用 FunctionalTrainer
-^^^^^^^^^^^^^^^^^^^^^^
-
-还有另一种使用功能性 API 自定义新 Trainer 的方法，该方法提供了更大的灵活性。 用户只需要编写一个 fit 函数来包装所有内容。 此函数接收一个位置参数（model）和可能的关键字参数。 通过这种方式，用户可以控制一切，但向框架公开的信息较少，因此可能进行优化的机会也较少。 示例如下。
-
-.. code-block::python
-
-    from nni.retiarii.trainer import FunctionalTrainer
-    from nni.retiarii.experiment.pytorch import RetiariiExperiment
-
-    def fit(model, dataloader):
-        train(model, dataloader)
-        acc = test(model, dataloader)
-        nni.report_final_result(acc)
-
-    trainer = FunctionalTrainer(fit, dataloader=DataLoader(foo, bar))
-    experiment = RetiariiExperiment(base_model, trainer, mutators, strategy)
-
-
-One-shot trainers
------------------
-
-One-shot Trainer 应继承 ``nni.retiarii.trainer.BaseOneShotTrainer``，并需要实现``fit()`` 函数（用于进行拟合和搜索过程）和 ``export()`` 方法（用于返回搜索到的最佳架构）。
-
-编写一个 One-Shot Trainer 与经典 Trainer 有很大不同。 首先，init 方法参数没有限制，可以接收任何 Python 参数。 其次，输入到 One-Shot Trainer 中的模型可能带有 Retiarii 特定的模块（例如 LayerChoice 和 InputChoice）的模型。 这种模型不能直接向前传播，Trainer 需要决定如何处理这些模块。
-
-一个典型的示例是 DartsTrainer，其中可学习参数用于在 LayerChoice 中组合多个 Choice。 Retiarii为模块替换提供了易于使用的函数，即 ``replace_layer_choice``, ``replace_input_choice``。 示例如下。 
-
-.. code-block::python
-
-    from nni.retiarii.trainer.pytorch import BaseOneShotTrainer
-    from nni.retiarii.trainer.pytorch.utils import replace_layer_choice, replace_input_choice
-
-
-    class DartsLayerChoice(nn.Module):
-        def __init__(self, layer_choice):
-            super(DartsLayerChoice, self).__init__()
-            self.name = layer_choice.key
-            self.op_choices = nn.ModuleDict(layer_choice.named_children())
-            self.alpha = nn.Parameter(torch.randn(len(self.op_choices)) * 1e-3)
-
-        def forward(self, *args, **kwargs):
-            op_results = torch.stack([op(*args, **kwargs) for op in self.op_choices.values()])
-            alpha_shape = [-1] + [1] * (len(op_results.size()) - 1)
-            return torch.sum(op_results * F.softmax(self.alpha, -1).view(*alpha_shape), 0)
-
-
-    class DartsTrainer(BaseOneShotTrainer):
-
-        def __init__(self, model, loss, metrics, optimizer):
-            self.model = model
-            self.loss = loss
-            self.metrics = metrics
-            self.num_epochs = 10
-
-            self.nas_modules = []
-            replace_layer_choice(self.model, DartsLayerChoice, self.nas_modules)
-
-            ... # 初始化 dataloaders 和 optimizers
-
-        def fit(self):
-            for i in range(self.num_epochs):
-                for (trn_X, trn_y), (val_X, val_y) in zip(self.train_loader, self.valid_loader):
-                    self.train_architecture(val_X, val_y)
-                    self.train_model_weight(trn_X, trn_y)
-
-        @torch.no_grad()
-        def export(self):
-            result = dict()
-            for name, module in self.nas_modules:
-                if name not in result:
-                    result[name] = select_best_of_module(module)
-            return result
-
-Retsarii 源代码提供了 DartsTrainer 的完整代码。 请查看 :githublink:`nni/retiarii/trainer/pytorch/darts.py`.

docs/zh_CN/NAS/construct_space.rst

+#####################
+构建模型空间
+#####################
+
+NNI为用户提供了强大的API，以方便表达模型空间（或搜索空间）。 首先，用户可以使用 mutation 原语（如 ValueChoice、LayerChoice）在他们的模型中内联一个空间。 其次，NNI为用户提供了简单的接口，可以定制新的 mutators 来表达更复杂的模型空间。 在大多数情况下，mutation 原语足以表达用户的模型空间。
+
+..  toctree::
+    :maxdepth: 1
+
+    mutation 原语 <MutationPrimitives>
+    定制 mutator <Mutators>
\ No newline at end of file

docs/zh_CN/NAS/multi_trial_nas.rst

+Multi-trial NAS
+===============
+
+在 multi-trial NAS 中，用户需要模型评估器来评估每个采样模型的性能，并且需要一个探索策略来从定义的模型空间中采样模型。 在这里，用户可以使用 NNI 提供的模型评估器或编写自己的模型评估器。 他们可以简单地选择一种探索策略。 高级用户还可以自定义新的探索策略。 关于如何运行 multi-trial NAS 实验的简单例子，请参考 `快速入门 <./QuickStart.rst>`__。
+
+..  toctree::
+    :maxdepth: 1
+
+    模型评估器 <ModelEvaluators>
+    自定义模型评估器 <WriteTrainer>
+    探索策略 <ExplorationStrategies>
+    自定义探索策略 <WriteStrategy>
+    执行引擎 <ExecutionEngines>
\ No newline at end of file

docs/zh_CN/NAS/one_shot_nas.rst

-One-Shot NAS 算法
-=======================
+One-shot NAS
+============
 
-One-Shot NAS 算法利用了搜索空间中模型间的权重共享来训练超网络，并使用超网络来指导选择出更好的模型。 与从头训练每个模型（我们称之为 "经典 NAS"）算法相比，此类算法大大减少了使用的计算资源。 NNI 支持下列流行的 One-Shot NAS 算法。
+One-Shot NAS 算法利用了搜索空间中模型间的权重共享来训练超网络，并使用超网络来指导选择出更好的模型。 与从头训练每个模型（我们称之为 "Multi-trial NAS"）算法相比，此类算法大大减少了使用的计算资源。 NNI 支持下列流行的 One-Shot NAS 算法。
 
 
 ..  toctree::
     :maxdepth: 1
 
-    快速入门 <NasGuide>
+    运行 One-shot NAS <OneshotTrainer>
     ENAS <ENAS>
     DARTS <DARTS>
-    P-DARTS <PDARTS>
     SPOS <SPOS>
-    CDARTS <CDARTS>
     ProxylessNAS <Proxylessnas>
-    TextNAS <TextNAS>
-    Cream <Cream>
+    FBNet <FBNet>
+    自定义 one-shot NAS <WriteOneshot>
\ No newline at end of file

docs/zh_CN/NAS/retiarii/Tutorial.rst

-使用 Retiarii 进行神经网络架构搜索（实验性）
-==============================================================================================================
-
-`Retiarii <https://www.usenix.org/system/files/osdi20-zhang_quanlu.pdf>`__ 是一个支持神经体系架构搜索和超参数调优的新框架。 它允许用户以高度的灵活性表达各种搜索空间，重用许多前沿搜索算法，并利用系统级优化来加速搜索过程。 该框架提供了以下全新的用户体验。
-
-* 搜索空间可以直接在用户模型代码中表示。 调优空间可以通过定义模型来表示。
-* 在 Experiment 中，神经架构候选项和超参数候选项得到了更友好的支持。
-* Experiment 可以直接从 Python 代码启动。
-
-NNI 正在把 `之前 NAS 框架 <../Overview.rst>`__ *迁移至 Retiarii 框架。 因此，此功能仍然是实验性的。 NNI 建议用户尝试新的框架，并提供有价值的反馈来改进它。 旧框架目前仍受支持。*
-
-.. contents::
-
-有两个步骤来开始神经架构搜索任务的 Experiment。 首先，定义要探索的模型空间。 其次，选择一种搜索方法来探索您定义的模型空间。
-
-定义模型空间
------------------------
-
-模型空间是由用户定义的，用来表达用户想要探索、认为包含性能良好模型的一组模型。 在这个框架中，模型空间由两部分组成：基本模型和基本模型上可能的突变。
-
-定义基本模型
-^^^^^^^^^^^^^^^^^
-
-定义基本模型与定义 PyTorch（或 TensorFlow）模型几乎相同， 只有两个小区别。
-
-* 对于 PyTorch 模块（例如 ``nn.Conv2d``, ``nn.ReLU``），将代码 ``import torch.nn as nn`` 替换为 ``import nni.retiarii.nn.pytorch as nn`` 。
-* 一些\ **用户定义**\ 的模块应该用 ``@blackbox_module`` 修饰。 例如，``LayerChoice`` 中使用的用户定义模块应该被修饰。 用户可参考 `这里 <#blackbox-module>`__ 获取 ``@blackbox_module`` 的详细使用说明。
-
-下面是定义基本模型的一个简单的示例，它与定义 PyTorch 模型几乎相同。
-
-.. code-block:: python
-
-  import torch.nn.functional as F
-  import nni.retiarii.nn.pytorch as nn
-
-  class MyModule(nn.Module):
-    def __init__(self):
-      super().__init__()
-      self.conv = nn.Conv2d(32, 1, 5)
-      self.pool = nn.MaxPool2d(kernel_size=2)
-    def forward(self, x):
-      return self.pool(self.conv(x))
-
-  class Model(nn.Module):
-    def __init__(self):
-      super().__init__()
-      self.mymodule = MyModule()
-    def forward(self, x):
-      return F.relu(self.mymodule(x))
-
-可参考 :githublink:`Darts 基本模型 <test/retiarii_test/darts/darts_model.py>` 和 :githublink:`Mnasnet 基本模型 <test/retiarii_test/mnasnet/base_mnasnet.py>` 获取更复杂的示例。
-
-定义模型突变
-^^^^^^^^^^^^^^^^^^^^^^
-
-基本模型只是一个具体模型，而不是模型空间。 我们为用户提供 API 和原语，用于把基本模型变形成包含多个模型的模型空间。
-
-**以内联方式表示突变**
-
-为了易于使用和向后兼容，我们提供了一些 API，供用户在定义基本模型后轻松表达可能的突变。 API 可以像 PyTorch 模块一样使用。
-
-* ``nn.LayerChoice``， 它允许用户放置多个候选操作（例如，PyTorch 模块），在每个探索的模型中选择其中一个。 *注意，如果候选模块是用户定义的模块，则应将其修饰为* `blackbox module <#blackbox-module>`__。 在下面的例子中，``ops.PoolBN`` 和 ``ops.SepConv`` 应该被修饰。
-
-  .. code-block:: python
-
-    # import nni.retiarii.nn.pytorch as nn
-    # 在 `__init__` 中声明
-    self.layer = nn.LayerChoice([
-      ops.PoolBN('max', channels, 3, stride, 1),
-      ops.SepConv(channels, channels, 3, stride, 1),
-      nn.Identity()
-    ]))
-    # 在 `forward` 函数中调用
-    out = self.layer(x)
-
-* ``nn.InputChoice``， 它主要用于选择（或尝试）不同的连接。 它会从设置的几个张量中，选择 ``n_chosen`` 个张量。
-
-  .. code-block:: python
-
-    # import nni.retiarii.nn.pytorch as nn
-    # 在 `__init__` 中声明
-    self.input_switch = nn.InputChoice(n_chosen=1)
-    # 在 `forward` 函数中调用，三者选一
-    out = self.input_switch([tensor1, tensor2, tensor3])
-
-* ``nn.ValueChoice``， 它用于从一些候选值中选择一个值。 它能用作 ``nn.modules`` 中的模块和 ``@blackbox_module`` 修饰的用户自定义模块中的输入参数。
-
-  .. code-block:: python
-
-    # import nni.retiarii.nn.pytorch as nn
-    # 在 `__init__` 中使用
-    self.conv = nn.Conv2d(XX, XX, kernel_size=nn.ValueChoice([1, 3, 5])
-    self.op = MyOp(nn.ValueChoice([0, 1], nn.ValueChoice([-1, 1]))
-
-详细的 API 描述和使用说明在 `这里 <./ApiReference.rst>`__。 使用这些 API 的示例在 :githublink:`Darts base model <test/retiarii_test/darts/darts_model.py>`。
-
-**用 Mutator 表示突变**
-
-尽管内联突变易于使用，但其表达能力有限，无法表达某些模型空间。 为了提高表达能力和灵活性，我们提供了编写 *Mutator* 的原语，方便用户更灵活地修改基本模型。 Mutator 位于基础模型之上，因此具有编辑模型的全部能力。
-
-用户可以按以下方式实例化多个 Mutator，这些 Mutator 将依次依次应用于基本模型来对新模型进行采样。
-
-.. code-block:: python
-
-  applied_mutators = []
-  applied_mutators.append(BlockMutator('mutable_0'))
-  applied_mutators.append(BlockMutator('mutable_1'))
-
-``BlockMutator`` 由用户定义，表示如何对基本模型进行突变。 用户定义的 Mutator 应该继承 ``Mutator`` 类，并在成员函数 ``mutate`` 中实现突变逻辑。
-
-.. code-block:: python
-
-  from nni.retiarii import Mutator
-  class BlockMutator(Mutator):
-    def __init__(self, target: str, candidates: List):
-        super(BlockMutator, self).__init__()
-        self.target = target
-        self.candidate_op_list = candidates
-
-    def mutate(self, model):
-      nodes = model.get_nodes_by_label(self.target)
-      for node in nodes:
-        chosen_op = self.choice(self.candidate_op_list)
-        node.update_operation(chosen_op.type, chosen_op.params)
-
-``mutate`` 的输入是基本模型的 graph IR（请参考 `这里 <./ApiReference.rst>`__ 获取 IR 的格式和 API），用户可以使用其成员函数（例如， ``get_nodes_by_label``，``update_operation``）对图进行变异。 变异操作可以与 API ``self.choice`` 相结合，以表示一组可能的突变。 在上面的示例中，节点的操作可以更改为 ``candidate_op_list`` 中的任何操作。
-
-使用占位符使突变更容易：``nn.Placeholder``。 如果要更改模型的子图或节点，可以在此模型中定义一个占位符来表示子图或节点。 然后，使用 Mutator 对这个占位符进行变异，使其成为真正的模块。
-
-.. code-block:: python
-
-  ph = nn.Placeholder(label='mutable_0',
-    related_info={
-      'kernel_size_options': [1, 3, 5],
-      'n_layer_options': [1, 2, 3, 4],
-      'exp_ratio': exp_ratio,
-      'stride': stride
-    }
-  )
-
-Mutator 使用 ``label`` 来标识此占位符，``related_info`` 是 Mutator 所需的信息。 由于 ``related_info`` 是一个 dict，所以它可以包含用户想要输入的任何信息，并将其传递给用户定义的 Mutator。 完整的示例代码在 :githublink:`Mnasnet base model <test/retiarii_test/mnasnet/base_mnasnet.py>`。
-
-探索定义的模型空间
-------------------------------------------
-
-在模型空间被定义之后，是时候探索这个模型空间了。 用户可以选择合适的搜索和训练方法来探索模型空间。
-
-创建 Trainer 和探索 Strategy
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-**经典搜索方法：**
-在这种方法中，Trainer 负责对每个探索的模型进行训练，而 Strategy 则负责对模型进行抽样。 探索模型空间既需要 Trainer，也需要 Strategy。 我们推荐使用 PyTorch-Lightning 编写完整的训练过程。
-
-**Oneshot（权重共享）探索方法：**
-在这种方法中，用户只需要一个 Oneshot Trainer，来负责探索和训练。
-
-在下表中，我们列出了可用的 Trainer 和 Strategy。
-
-.. list-table::
-  :header-rows: 1
-  :widths: auto
-
-  * - Trainer
-    - Strategy
-    - Oneshot Trainer
-  * - 分类
-    - TPEStrategy
-    - DartsTrainer
-  * - 回归
-    - Random
-    - EnasTrainer
-  * - 
-    - GridSearch
-    - ProxylessTrainer
-  * - 
-    - RegularizedEvolution
-    - SinglePathTrainer (RandomTrainer)
-
-使用说明和 API 文档在 `这里 <./ApiReference>`__。
-
-下面是一个使用 Trainer 和 Strategy 的简单示例。
-
-.. code-block:: python
-
-  import nni.retiarii.trainer.pytorch.lightning as pl
-  from nni.retiarii import blackbox
-  from torchvision import transforms
-
-  transform = transforms.Compose([transforms.ToTensor(), transforms.Normalize((0.1307,), (0.3081,))])
-  train_dataset = blackbox(MNIST, root='data/mnist', train=True, download=True, transform=transform)
-  test_dataset = blackbox(MNIST, root='data/mnist', train=False, download=True, transform=transform)
-  lightning = pl.Classification(train_dataloader=pl.DataLoader(train_dataset, batch_size=100),
-                                val_dataloaders=pl.DataLoader(test_dataset, batch_size=100),
-                                max_epochs=10)
-
-.. Note:: 为了使 NNI 能够捕获数据集和 dataloader 并让其分别运行，请使用 ``blackbox`` 包装数据集，并使用 ``pl.DataLoader`` 而不是 ``torch.utils.data.DataLoader``。 参考 ``blackbox_module`` 部分获取更多细节信息。
-
-用户可查看 `API 说明 <./ApiReference.rst>`__ 获取 Trainer 的详细用法。 参考 "`此文档 <./WriteTrainer.rst>`__" 编写一个新的 Trainer，参考 `此文档 <./WriteStrategy.rst>`__ 编写一个新的 Strategy。
-
-发起 Experiment
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-上述内容准备就绪之后，就可以发起 Experiment 以进行模型搜索了。 NNI 设计了统一的接口来发起 Experiment， 示例如下：
-
-.. code-block:: python
-
-  exp = RetiariiExperiment(base_model, trainer, applied_mutators, simple_strategy)
-  exp_config = RetiariiExeConfig('local')
-  exp_config.experiment_name = 'mnasnet_search'
-  exp_config.trial_concurrency = 2
-  exp_config.max_trial_number = 10
-  exp_config.training_service.use_active_gpu = False
-  exp.run(exp_config, 8081)
-
-此代码发起了一个 NNI Experiment， 注意，如果使用内联突变，``applied_mutators`` 应为 ``None``。
-
-一个简单 MNIST 示例的完整代码在 :githublink:`这里 <test/retiarii_test/mnist/test.py>`。
-
-可视化 Experiment
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-用户可以像可视化普通的超参数调优 Experiment 一样可视化他们的 Experiment。 例如，在浏览器里打开 ``localhost::8081``，8081 是在 ``exp.run`` 里设置的端口。 参考 `这里 <../../Tutorial/WebUI.rst>`__ 了解更多细节。 如果用户使用的是 Oneshot Trainer，可以参考 `这里 <../Visualization.rst>`__ 去可视化他们的 Experiment。
-
-导出 Experiment 中发现的最佳模型
----------------------------------------------------------------------
-
-如果您使用的是\ *经典搜索方法*，那么您可以从 WebUI 中找到最好的模型。
-
-如果您使用的是 *Oneshot（权重共享）搜索方法*，则可以使用 ``exp.export_top_models`` 导出 Experiment 中发现的几个最佳模型。
-
-高级功能和常见问题
---------------------------------
-
-.. _blackbox-module:
-
-**Blackbox Module**
-
-为了理解修饰器 ``blackbox_module``，首先需要解释一下我们的框架是如何工作的：它将用户定义的模型转换为图表示形式（称为 graph IR），每个实例化的模块都将转换为一个子图， 然后将用户定义的突变应用于图上以生成新的图， 并将每个新图转换回 PyTorch 代码执行。 ``@blackbox_module`` 这里的意思是模块不会被转换成子图，而是被转换成单个图节点。 也就是说，该模块将不再展开。 在以下情况下，用户应该/可以修饰自定义的模块类：
-
-* 当模块类由于某些实现问题无法成功转换为子图时。 例如，目前 Retiarii 的框架不支持 adhoc 循环，如果一个模块的 forward 中有 adhoc 循环，那么这个类应该被修饰成 blackbox 模块。 下面的 ``MyModule`` 应该被修饰：
-
-  .. code-block:: python
-
-    @blackbox_module
-    class MyModule(nn.Module):
-      def __init__(self):
-        ...
-      def forward(self, x):
-        for i in range(10): # <- adhoc loop
-          ...
-
-* ``LayerChoice`` 中的候选操作应修饰为 blackbox 模块。 例如，在 ``self.op = nn.LayerChoice([Op1(...), Op2(...), Op3(...)])``中，如果 ``Op1``, ``Op2``, ``Op3`` 是用户自定义的模块，则应该被修饰。
-* 当用户希望在模块的输入参数中使用 ``ValueChoice`` 时，应该将该模块修饰为 blackbox 模块。 例如，在 ``self.conv = MyConv(kernel_size=nn.ValueChoice([1, 3, 5]))`` 中，``MyConv`` 应该被修饰。
-* 如果没有针对某个模块的突变，那么这个模块\ *可以*\ 修饰成一个 blackbox 模块。
\ No newline at end of file

docs/zh_CN/NAS/retiarii/retiarii_index.rst

-#################
-Retiarii 概览
-#################
-
-`Retiarii <https://www.usenix.org/system/files/osdi20-zhang_quanlu.pdf>`__ 是一个支持神经体系架构搜索和超参数调优的新框架。 它允许用户以高度的灵活性表达各种搜索空间，重用许多前沿搜索算法，并利用系统级优化来加速搜索过程。 该框架提供了以下全新的用户体验。
-
-..  toctree::
-    :maxdepth: 2
-
-    快速入门 <Tutorial>
-    自定义 Trainer <WriteTrainer>
-    自定义 Strategy <WriteStrategy>
-    Retiarii APIs <ApiReference>
\ No newline at end of file

docs/zh_CN/ResearchPublications.rst

@@ -97,9 +97,12 @@
 
    @article{gao2020opevo, 
         title={OpEvo: An Evolutionary Method for Tensor Operator Optimization}, 
+        volume={35},
+        url={https://ojs.aaai.org/index.php/AAAI/article/view/17462}, 
+        number={14}, 
+        journal={Proceedings of the AAAI Conference on Artificial Intelligence},
         author={Gao, Xiaotian and Wei, Cui and Zhang, Lintao and Yang, Mao},
-     journal={arXiv preprint arXiv:2006.05664},
-     year={2020}
+        year={2021}, month={May}, pages={12320-12327}
    }
 
 评估和理解

docs/zh_CN/TrainingService/AMLMode.rst

@@ -125,3 +125,8 @@ amlConfig 需要的信息可以从步骤 5 下载的 ``config.json`` 找到。
    nnictl create --config config_aml.yml
 
 将 ``${NNI_VERSION}`` 替换为发布的版本或分支名称，例如：``v2.0``。
+
+通过使用工作室监控你在云端的代码
+--------------------------------------------------
+
+要监控你的任务的代码，你需要访问你在第5步创建的工作室。 一旦任务完成，进入 Outputs + logs 栏。 在那里你可以看到一个 70_driver_log.txt 文件，这个文件包含了运行的标准输出，当你在云端调试远程运行时，这个文件很有用。 从 `这里 <https://docs.microsoft.com/zh-cn/azure/machine-learning/tutorial-1st-experiment-hello-world>`__ 了解更多关于 AML 的信息。

docs/zh_CN/TrainingService/AdaptDLMode.rst

 在 AdaptDL 上运行 Experiment
 ============================
 
-NNI 支持在 `AdaptDL <https://github.com/petuum/adaptdl>`__ 上运行，称为 AdaptDL 模式。 在开始使用 NNI 的 AdaptDL 模式前，需要有一个 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 集群。 在 AdaptDL 模式下，每个 Trial 程序会在 AdaptDL 集群中作为一个 Kubeflow 作业来运行。
+NNI 支持在 `AdaptDL <https://github.com/petuum/adaptdl>`__ 上运行，称为 AdaptDL 模式。 采用 **Kubernetes 1.14** 或更高版本。 根据下面的指南设置 Kubernetes 环境： `on Azure <https://azure.microsoft.com/zh-cn/services/kubernetes-service/>`__\ ， `on-premise <https://kubernetes.io/docs/setup/>`__ ， `cephfs <https://kubernetes.io/docs/concepts/storage/storage-classes/#ceph-rbd>`__\ 和 `microk8s with storage add-on enabled <https://microk8s.io/docs/addons>`__。 在 AdaptDL 模式下，每个 Trial 程序会在 AdaptDL 集群中作为一个 Kubeflow 作业来运行。
 
 AdaptDL 旨在使动态资源环境（例如共享集群和云）中的分布式深度学习变得轻松高效。
 
@@ -133,7 +133,7 @@ NFS 存储
 简而言之，并没有限制 trial 如何读取或写入 NFS 存储，因此可以根据需要灵活使用它。
 
 通过日志流监控
----------------------------------------------
+----------------------------------------------
 
 遵循特定 trial 的日志流：
 
@@ -151,7 +151,7 @@ NFS 存储
 根据以下方法。
 
 通过 TensorBoard 进行监控
-----------------------------------------------
+---------------------------------------------
 
 在 NNI 的背景下，一个实验有多条 trial。
 为了在模型调整过程的各个 trial 之间轻松进行比较，

docs/zh_CN/TrainingService/FrameworkControllerMode.rst

@@ -28,6 +28,16 @@ Azure 部署的 Kubernetes 的准备工作
 #. 参考此 `指南 <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>`__ 来存储访问密钥。
 
+
+部署 PVC 存储模式的准备工作
+-----------------------------------------
+为了使用 PVC（persistent volume claims）而不是 NFS 或 Azure 存储，相关存储必须
+在你的 Trial 以后要运行的命名空间中手动创建。 这一限制是由于
+PVC 很难被回收，因此会迅速扰乱一个集群的
+存储管理， PVC 可以通过 kubectl 被创建。 请参考
+`Kubernetes 官方文档 <https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims>`__ 获取更多信息。
+
+
 安装 FrameworkController
 -------------------------
 
@@ -116,6 +126,37 @@ frameworkcontroller 模式中的 Trial 配置使用以下主键：
   * image: 用来创建 pod，并运行程序的 Docker 映像。
   * frameworkAttemptCompletionPolicy: 运行框架的策略，参考 `用户手册 <https://github.com/Microsoft/frameworkcontroller/blob/master/doc/user-manual.md#frameworkattemptcompletionpolicy>`__ 了解更多信息。 这些策略可以用来控制 pod，例如，如果 worker 任务停止了，但 ps 还在运行，要通过完成策略来停止 ps。
 
+NNI还提供了一个定制 FrameworkController 模板的可能性，类似于
+前面提到的 TensorFlow 示例。 一个有效的配置大致如下：
+
+.. code-block:: yaml
+
+    experimentName: example_mnist_pytorch
+    trialConcurrency: 1
+    maxExecDuration: 1h
+    maxTrialNum: 2
+    logLevel: trace
+    trainingServicePlatform: frameworkcontroller
+    searchSpacePath: search_space.json
+    tuner:
+      builtinTunerName: TPE
+      classArgs:
+        optimize_mode: maximize
+    assessor:
+      builtinAssessorName: Medianstop
+      classArgs:
+        optimize_mode: maximize
+    trial:
+      codeDir: .
+    frameworkcontrollerConfig:
+      configPath: fc_template.yml
+      storage: pvc
+      namespace: twin-pipelines
+      pvc:
+        path: /mnt/data
+
+请注意，在这个例子中，已经使用了 PVC 存储，其必须事先在指定的命名空间中手动创建。 点击 mnist-pytorch 示例 (:githublink: `<examples/trials/mnist-pytorch>`__) 获取更加详细的配置 (:githublink: `<examples/trials/mnist-pytorch/config_frameworkcontroller_custom.yml>`__) 和 FrameworkController 模板 (:githublink: `<examples/trials/fc_template.yml>`__)。
+
 如何运行示例
 ------------------