Skip to content

GitLab

Unverified Commit 39432390 authored by kvartet's avatar kvartet Committed by GitHub
Browse files

Update Chinese documentation (#3886)

parent 93dbaf3e
Expand all Show whitespace changes
Inline Side-by-side
Showing with 511 additions and 898 deletions
docs/zh_CN/NAS/SPOS.rst
View file @ 39432390
......@@ -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 deleted 100644 → 0
View file @ 93dbaf3e
.. 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 deleted 100644 → 0
View file @ 93dbaf3e
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 deleted 100644 → 0
View file @ 93dbaf3e
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 0 → 100644
View file @ 39432390
自定义 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 deleted 100644 → 0
View file @ 93dbaf3e
编写搜索空间
====================
通常，搜索空间是要在其中找到最好结构的候选项。 无论是经典 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
View file @ 39432390
自定义 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
View file @ 39432390
自定义 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 0 → 100644
View file @ 39432390
#####################
构建模型空间
#####################
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 0 → 100644
View file @ 39432390
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
View file @ 39432390
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 deleted 100644 → 0
View file @ 93dbaf3e
使用 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 deleted 100644 → 0
View file @ 93dbaf3e
#################
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/Release.rst
View file @ 39432390
This diff is collapsed.
docs/zh_CN/ResearchPublications.rst
View file @ 39432390
......@@ -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
View file @ 39432390
......@@ -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
View file @ 39432390
在 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
View file @ 39432390
......@@ -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>`__)。
如何运行示例
------------------
......
docs/zh_CN/TrainingService/HowToImplementTrainingService.rst
View file @ 39432390
......@@ -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
View file @ 39432390
......@@ -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` 训练平台。
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment