QuickStart_zh.rst 11.4 KB
Newer Older
1
.. 90b7c298df11d68ba419a1feaf453cfc
2

kvartet's avatar
kvartet committed
3
4
5
6
快速入门
==========

安装
7
----
kvartet's avatar
kvartet committed
8

9
目前NNI支持了 LinuxmacOS  Windows系统。 其中,Ubuntu 16.04 及更高版本、macOS 10.14.1  Windows 10.1809 均经过测试并支持。  ``python >= 3.6`` 环境中,只需运行 ``pip install`` 即可完成安装。
kvartet's avatar
kvartet committed
10
11

Linux  macOS
12
^^^^^^^^^^^^^^
kvartet's avatar
kvartet committed
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

.. code-block:: bash

   python3 -m pip install --upgrade nni

Windows
^^^^^^^

.. code-block:: bash

   python -m pip install --upgrade nni

.. Note::  Linux  macOS 上,如果要将 NNI 安装到当前用户的 home 目录中,可使用 ``--user`` ;这不需要特殊权限。

.. Note:: 如果出现 ``Segmentation fault`` 这样的错误,参考 :doc:`常见问题 <FAQ>` 

29
.. Note:: NNI 的系统需求,参考 :doc:`Linux & Mac <InstallationLinux>` 或者 :doc:`Windows <InstallationWin>` 的安装教程。如果想要使用 docker, 参考 :doc:`如何使用 Docker <HowToUseDocker>` 
kvartet's avatar
kvartet committed
30
31
32


MNIST 上的 "Hello World"
33
------------------------
kvartet's avatar
kvartet committed
34
35
36
37
38
39
40

NNI 是一个能进行自动机器学习实验的工具包。 它可以自动进行获取超参、运行 Trial,测试结果,调优超参的循环。 在这里,将演示如何使用 NNI 帮助找到 MNIST 模型的最佳超参数。

这是还 **没有 NNI** 的示例代码,用 CNN  MNIST 数据集上训练:

.. code-block:: python

kvartet's avatar
kvartet committed
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
    def main(args):
        # 下载数据
        train_loader = torch.utils.data.DataLoader(datasets.MNIST(...), batch_size=args['batch_size'], shuffle=True)
        test_loader = torch.tuils.data.DataLoader(datasets.MNIST(...), batch_size=1000, shuffle=True)
        # 构建模型
        model = Net(hidden_size=args['hidden_size'])
        optimizer = optim.SGD(model.parameters(), lr=args['lr'], momentum=args['momentum'])
        # 训练
        for epoch in range(10):
            train(args, model, device, train_loader, optimizer, epoch)
            test_acc = test(args, model, device, test_loader)
            print(test_acc)
        print('final accuracy:', test_acc)
         
    if __name__ == '__main__':
        params = {
            'batch_size': 32,
            'hidden_size': 128,
            'lr': 0.001,
            'momentum': 0.5
        }
        main(params)
kvartet's avatar
kvartet committed
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

上面的代码一次只能尝试一组参数,如果想要调优学习率,需要手工改动超参,并一次次尝试。

NNI 用来帮助超参调优。它的流程如下:

.. code-block:: text

   输入: 搜索空间, Trial 代码, 配置文件
   输出: 一组最优的参数配置

   1: For t = 0, 1, 2, ..., maxTrialNum,
   2:      hyperparameter = 从搜索空间选择一组参数
   3:      final result = run_trial_and_evaluate(hyperparameter)
   4:      返回最终结果给 NNI
   5:      If 时间达到上限,
   6:          停止实验
   7: 返回最好的实验结果

81
.. note::
kvartet's avatar
kvartet committed
82

83
   如果需要使用 NNI 来自动训练模型,找到最佳超参,有两种实现方式:
kvartet's avatar
kvartet committed
84

85
86
   1. 编写配置文件,然后使用命令行启动 experiment
   2. 直接从 Python 文件中配置并启动 experiment
kvartet's avatar
kvartet committed
87

88
   在本节中,我们将重点介绍第一种实现方式。如果希望使用第二种实现方式,请参考 `教程 <HowToLaunchFromPython.rst>`__\ 
kvartet's avatar
kvartet committed
89
90


91
第一步:修改 ``Trial`` 代码
92
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
kvartet's avatar
kvartet committed
93

94
修改 ``Trial`` 代码来从 NNI 获取超参,并向 NNI 报告训练结果。
kvartet's avatar
kvartet committed
95
96
97

.. code-block:: diff

kvartet's avatar
kvartet committed
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
    + import nni

      def main(args):
          # 下载数据
          train_loader = torch.utils.data.DataLoader(datasets.MNIST(...), batch_size=args['batch_size'], shuffle=True)
          test_loader = torch.tuils.data.DataLoader(datasets.MNIST(...), batch_size=1000, shuffle=True)
          # 构造模型
          model = Net(hidden_size=args['hidden_size'])
          optimizer = optim.SGD(model.parameters(), lr=args['lr'], momentum=args['momentum'])
          # 训练
          for epoch in range(10):
              train(args, model, device, train_loader, optimizer, epoch)
              test_acc = test(args, model, device, test_loader)
    -         print(test_acc)
    +         nni.report_intermeidate_result(test_acc)
    -     print('final accuracy:', test_acc)
    +     nni.report_final_result(test_acc)
           
      if __name__ == '__main__':
    -     params = {'batch_size': 32, 'hidden_size': 128, 'lr': 0.001, 'momentum': 0.5}
    +     params = nni.get_next_parameter()
          main(params)

121
122
123
124
*示例:* :githublink:`mnist.py <examples/trials/mnist-pytorch/mnist.py>`


第二步:定义搜索空间
125
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
kvartet's avatar
kvartet committed
126

127
编写 YAML 格式的 **搜索空间** 文件,包括所有需要搜索的超参的 **名称**  **分布** (离散和连续值均可)。
kvartet's avatar
kvartet committed
128
129
130

.. code-block:: yaml

131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
   searchSpace:
      batch_size:
         _type: choice
         _value: [16, 32, 64, 128]
      hidden_size:
         _type: choice
         _value: [128, 256, 512, 1024]
      lr:
         _type: choice
         _value: [0.0001, 0.001, 0.01, 0.1]
      momentum:
         _type: uniform
         _value: [0, 1]

*示例:* :githublink:`config_detailed.yml <examples/trials/mnist-pytorch/config_detailed.yml>`

也可以使用 JSON 文件来编写搜索空间,并在配置中确认文件路径。关于如何编写搜索空间,可以参考 `教程 <SearchSpaceSpec.rst>`__.


第三步:配置 experiment
151
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
kvartet's avatar
kvartet committed
152

153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
除了在第二步中定义的搜索空间,还需要定义 YAML 格式的 **配置** 文件,声明 experiment 的关键信息,例如 Trail 文件,调优算法,最大 Trial 运行次数和最大持续时间等。

.. code-block:: yaml

   experimentName: MNIST               # 用于区分 experiment 的名字,可选项
   trialCommand: python3 mnist.py      # 注意:如果使用 Windows,请将 "python3" 修改为 "python" 
   trialConcurrency: 2                 # 同时运行 2  trial
   maxTrialNumber: 10                  # 最多生成 10  trial
   maxExperimentDuration: 1h           # 1 小时后停止生成 trial
   tuner:                              # 配置调优算法
      name: TPE
      classArgs:                       # 算法特定参数
         optimize_mode: maximize
   trainingService:                    # 配置训练平台
      platform: local

Experiment 的配置文件可以参考 `文档 <../reference/experiment_config.rst>`__.
kvartet's avatar
kvartet committed
170
171
172

.. _nniignore:

173
.. Note:: 如果要使用远程服务器或集群作为 :doc:`训练平台 <../TrainingService/Overview>`,为了避免产生过大的网络压力,NNI 限制了文件的最大数量为 2000,大小为 300 MB 如果代码目录中包含了过多的文件,可添加 ``.nniignore`` 文件来排除部分,与 ``.gitignore`` 文件用法类似。 参考 `git documentation <https://git-scm.com/docs/gitignore#_pattern_format>`__ ,了解更多如何编写此文件的详细信息。
kvartet's avatar
kvartet committed
174

175
*示例:* :githublink:`config.yml <examples/trials/mnist-pytorch/config.yml>`  :githublink:`.nniignore <examples/trials/mnist-pytorch/.nniignore>`
kvartet's avatar
kvartet committed
176

kvartet's avatar
kvartet committed
177
上面的代码都已准备好,并保存在 :githublink:`examples/trials/mnist-pytorch/ <examples/trials/mnist-pytorch>`
kvartet's avatar
kvartet committed
178

179
180

第四步:运行 experiment
181
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
182

kvartet's avatar
kvartet committed
183
Linux  macOS
184
**************
kvartet's avatar
kvartet committed
185

186
从命令行使用 **config.yml** 文件启动 MNIST experiment 
kvartet's avatar
kvartet committed
187
188
189

.. code-block:: bash

190
   nnictl create --config nni/examples/trials/mnist-pytorch/config_detailed.yml
kvartet's avatar
kvartet committed
191
192

Windows
193
*******
kvartet's avatar
kvartet committed
194

195
 **config_detailed.yml** 文件的 ``trialCommand`` 项中将 ``python3`` 修改为 ``python``,然后从命令行使用 **config_detailed.yml** 文件启动 MNIST experiment 
kvartet's avatar
kvartet committed
196
197
198

.. code-block:: bash

199
   nnictl create --config nni\examples\trials\mnist-pytorch\config_detailed.yml
kvartet's avatar
kvartet committed
200

201
.. Note:: ``nnictl`` 是一个命令行工具,用来控制 NNI experiment,如启动、停止、继续 experiment,启动、停止 NNIBoard 等等。 点击 :doc:`这里 <../reference/nnictl>` 查看 ``nnictl`` 的更多用法。
kvartet's avatar
kvartet committed
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230

在命令行中等待输出 ``INFO: Successfully started experiment!`` 。 此消息表明实验已成功启动。 期望的输出如下:

.. code-block:: text

   INFO: Starting restful server...
   INFO: Successfully started Restful server!
   INFO: Setting local config...
   INFO: Successfully set local config!
   INFO: Starting experiment...
   INFO: Successfully started experiment!
   -----------------------------------------------------------------------
   The experiment id is egchD4qy
   The Web UI urls are: [Your IP]:8080
   -----------------------------------------------------------------------

   You can use these commands to get more information about the experiment
   -----------------------------------------------------------------------
            commands                       description
   1. nnictl experiment show        show the information of experiments
   2. nnictl trial ls               list all of trial jobs
   3. nnictl top                    monitor the status of running experiments
   4. nnictl log stderr             show stderr log content
   5. nnictl log stdout             show stdout log content
   6. nnictl stop                   stop an experiment
   7. nnictl trial kill             kill a trial job by id
   8. nnictl --help                 get help information about nnictl
   -----------------------------------------------------------------------

231
如果根据上述步骤准备好了相应 ``Trial``  **搜索空间**  **配置** ,并成功创建的 NNI 任务。NNI 会自动开始通过配置的搜索空间来运行不同的超参集合,搜索最好的超参。 通过 Web 界面可看到 NNI 的进度。
kvartet's avatar
kvartet committed
232

233
第五步:查看 experiment
234
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
kvartet's avatar
kvartet committed
235

236
启动 experiment 后,可以在命令行界面找到如下的 **Web 界面地址** 
kvartet's avatar
kvartet committed
237
238
239
240
241

.. code-block:: text

   The Web UI urls are: [Your IP]:8080

242
在浏览器中打开 **Web 界面地址** (即: ``[IP 地址]:8080`` ),就可以看到 experiment 的详细信息,以及所有的 Trial 任务。 如果无法打开终端中的 Web 界面链接,可以参考 `常见问题 <FAQ.rst>`__
kvartet's avatar
kvartet committed
243
244


245
246
查看概要页面
******************
kvartet's avatar
kvartet committed
247

248
Experiment 相关信息会显示在界面上,包括配置和搜索空间等。 NNI 还支持通过 **Experiment summary** 按钮下载这些信息和参数。
kvartet's avatar
kvartet committed
249

kvartet's avatar
kvartet committed
250
251
252
.. image:: ../../img/webui-img/full-oview.png
   :target: ../../img/webui-img/full-oview.png
   :alt: overview
kvartet's avatar
kvartet committed
253
254
255


查看 Trial 详情页面
256
**********************************
kvartet's avatar
kvartet committed
257

258
可以在此页面中看到最佳的 ``Trial`` 指标和超参数图。 您可以点击 ``Add/Remove columns`` 按钮向表格中添加更多列。
kvartet's avatar
kvartet committed
259

kvartet's avatar
kvartet committed
260
261
262
.. image:: ../../img/webui-img/full-detail.png
   :target: ../../img/webui-img/full-detail.png
   :alt: detail
kvartet's avatar
kvartet committed
263
264


265
查看 experiment 管理页面
266
**********************************
kvartet's avatar
kvartet committed
267

kvartet's avatar
kvartet committed
268
``All experiments`` 页面可以查看计算机上的所有实验。 
kvartet's avatar
kvartet committed
269

kvartet's avatar
kvartet committed
270
271
272
.. image:: ../../img/webui-img/managerExperimentList/expList.png
   :target: ../../img/webui-img/managerExperimentList/expList.png
   :alt: Experiments list
kvartet's avatar
kvartet committed
273

kvartet's avatar
kvartet committed
274
更多信息可参考 `此文档 <./WebUI.rst>`__
kvartet's avatar
kvartet committed
275

276

kvartet's avatar
kvartet committed
277
278
279
相关主题
-------------

280
281
* `进行Debug <HowToDebug.rst>`__
* `如何实现 Trial 代码 <../TrialExample/Trials.rst>`__
kvartet's avatar
kvartet committed
282
283
* `尝试不同的 Tuner <../Tuner/BuiltinTuner.rst>`__
* `尝试不同的 Assessor <../Assessor/BuiltinAssessor.rst>`__
284
285
* `在不同训练平台上运行 experiment <../training_services.rst>`__
* `如何使用 Annotation <AnnotationSpec.rst>`__
kvartet's avatar
kvartet committed
286
* `如何使用命令行工具 nnictl <Nnictl.rst>`__
287
* ` Web 界面中启动 TensorBoard <Tensorboard.rst>`__