Skip to content

GitLab

Unverified Commit 297a1e2e authored by Yuge Zhang's avatar Yuge Zhang Committed by GitHub
Browse files

Refine readme, index and quickstart (#4659)

parent 01e9a28f
Show whitespace changes
Inline Side-by-side
Showing with 142 additions and 310 deletions
docs/source/Tutorial/QuickStart_zh.rst deleted 100644 → 0
View file @ 01e9a28f
.. 3b483d31655ac74e05b4c43b70452e08
快速入门
==========
安装
----
目前NNI支持了 Linux、macOS 和 Windows系统。 其中，Ubuntu 16.04 及更高版本、macOS 10.14.1 和 Windows 10.1809 均经过测试并支持。 在 ``python >= 3.6`` 环境中，只需运行 ``pip install`` 即可完成安装。
Linux 和 macOS
^^^^^^^^^^^^^^
.. 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>` 。
MNIST 上的 "Hello World"
------------------------
NNI 是一个能进行自动机器学习实验的工具包。 它可以自动进行获取超参、运行 Trial，测试结果，调优超参的循环。 在这里，将演示如何使用 NNI 帮助找到 MNIST 模型的最佳超参数。
这是还 **没有 NNI** 的示例代码，用 CNN 在 MNIST 数据集上训练：
.. code-block:: python
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)
上面的代码一次只能尝试一组参数，如果想要调优学习率，需要手工改动超参，并一次次尝试。
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: 返回最好的实验结果
.. note::
如果需要使用 NNI 来自动训练模型，找到最佳超参，有两种实现方式：
1. 编写配置文件，然后使用命令行启动 experiment；
2. 直接从 Python 文件中配置并启动 experiment。
在本节中，我们将重点介绍第一种实现方式。如果希望使用第二种实现方式，请参考 `教程 <HowToLaunchFromPython.rst>`__\ 。
第一步：修改 ``Trial`` 代码
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
修改 ``Trial`` 代码来从 NNI 获取超参，并向 NNI 报告训练结果。
.. code-block:: diff
+ 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)
*示例：* :githublink:`mnist.py <examples/trials/mnist-pytorch/mnist.py>`
第二步：定义搜索空间
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
编写 YAML 格式的 **搜索空间** 文件，包括所有需要搜索的超参的 **名称** 和 **分布** （离散和连续值均可）。
.. code-block:: yaml
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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
除了在第二步中定义的搜索空间，还需要定义 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>`__.
.. _nniignore:
.. Note:: 如果要使用远程服务器或集群作为训练平台，为了避免产生过大的网络压力，NNI 限制了文件的最大数量为 2000，大小为 300 MB。 如果代码目录中包含了过多的文件，可添加 ``.nniignore`` 文件来排除部分，与 ``.gitignore`` 文件用法类似。 参考 `git documentation <https://git-scm.com/docs/gitignore#_pattern_format>`__ ，了解更多如何编写此文件的详细信息。
*示例：* :githublink:`config.yml <examples/trials/mnist-pytorch/config.yml>` 和 :githublink:`.nniignore <examples/trials/mnist-pytorch/.nniignore>`
上面的代码都已准备好，并保存在 :githublink:`examples/trials/mnist-pytorch/ <examples/trials/mnist-pytorch>`。
第四步：运行 experiment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Linux 和 macOS
**************
从命令行使用 **config.yml** 文件启动 MNIST experiment 。
.. code-block:: bash
nnictl create --config nni/examples/trials/mnist-pytorch/config_detailed.yml
Windows
*******
在 **config_detailed.yml** 文件的 ``trialCommand`` 项中将 ``python3`` 修改为 ``python``，然后从命令行使用 **config_detailed.yml** 文件启动 MNIST experiment 。
.. code-block:: bash
nnictl create --config nni\examples\trials\mnist-pytorch\config_detailed.yml
.. Note:: ``nnictl`` 是一个命令行工具，用来控制 NNI experiment，如启动、停止、继续 experiment，启动、停止 NNIBoard 等等。 点击 :doc:`这里 <../reference/nnictl>` 查看 ``nnictl`` 的更多用法。
在命令行中等待输出 ``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
-----------------------------------------------------------------------
如果根据上述步骤准备好了相应 ``Trial`` ， **搜索空间** 和 **配置** ，并成功创建的 NNI 任务。NNI 会自动开始通过配置的搜索空间来运行不同的超参集合，搜索最好的超参。 通过 Web 界面可看到 NNI 的进度。
第五步：查看 experiment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
启动 experiment 后，可以在命令行界面找到如下的 **Web 界面地址** ：
.. code-block:: text
The Web UI urls are: [Your IP]:8080
在浏览器中打开 **Web 界面地址** （即： ``[IP 地址]:8080`` ），就可以看到 experiment 的详细信息，以及所有的 Trial 任务。 如果无法打开终端中的 Web 界面链接，可以参考 `常见问题 <FAQ.rst>`__。
查看概要页面
******************
Experiment 相关信息会显示在界面上，包括配置和搜索空间等。 NNI 还支持通过 **Experiment summary** 按钮下载这些信息和参数。
.. image:: ../../img/webui-img/full-oview.png
:target: ../../img/webui-img/full-oview.png
:alt: overview
查看 Trial 详情页面
**********************************
可以在此页面中看到最佳的 ``Trial`` 指标和超参数图。 您可以点击 ``Add/Remove columns`` 按钮向表格中添加更多列。
.. image:: ../../img/webui-img/full-detail.png
:target: ../../img/webui-img/full-detail.png
:alt: detail
查看 experiment 管理页面
**********************************
``All experiments`` 页面可以查看计算机上的所有实验。
.. image:: ../../img/webui-img/managerExperimentList/expList.png
:target: ../../img/webui-img/managerExperimentList/expList.png
:alt: Experiments list
更多信息可参考 `此文档 <./WebUI.rst>`__。
相关主题
-------------
* `进行Debug <HowToDebug.rst>`__
* `如何实现 Trial 代码 <../TrialExample/Trials.rst>`__
* `尝试不同的 Tuner <../Tuner/BuiltinTuner.rst>`__
* `尝试不同的 Assessor <../Assessor/BuiltinAssessor.rst>`__
* `在不同训练平台上运行 experiment <../training_services.rst>`__
* `如何使用 Annotation <AnnotationSpec.rst>`__
* `如何使用命令行工具 nnictl <Nnictl.rst>`__
* `在 Web 界面中启动 TensorBoard <Tensorboard.rst>`__
docs/source/conf.py
View file @ 297a1e2e
......@@ -73,8 +73,12 @@ autosummary_ignore_module_all = False
autosummary_generate = True
# Add mock modules
autodoc_mock_imports = ['apex', 'nni_node', 'tensorrt', 'pycuda', 'nn_meter', 'azureml']
autodoc_mock_imports = [
'apex', 'nni_node', 'tensorrt', 'pycuda', 'nn_meter', 'azureml',
'ConfigSpace', 'ConfigSpaceNNI', 'smac', 'statsmodels', 'pybnn',
]
# Some of our modules cannot generate summary
autosummary_mock_imports = [
'nni.retiarii.codegen.tensorflow',
'nni.nas.benchmarks.nasbench101.db_gen',
......@@ -114,6 +118,25 @@ sphinx_gallery_conf = {
'default_thumb_file': os.path.join(os.path.dirname(__file__), '../img/thumbnails/nni_icon_blue.png'),
}
# Some tutorials might need to appear more than once in toc.
# In this list, we make source/target tutorial pairs.
# Each "source" tutorial rst will be copied to "target" tutorials.
# The anchors will be replaced to avoid dupilcate labels.
# Target should start with ``cp_`` to be properly ignored in git.
tutorials_copy_list = [
# The global quickstart
('tutorials/hpo_quickstart_pytorch/main.rst', 'tutorials/hpo_quickstart_pytorch/cp_global_quickstart_hpo.rst'),
('tutorials/hello_nas.rst', 'tutorials/cp_global_quickstart_nas.rst'),
('tutorials/pruning_quick_start_mnist.rst', 'tutorials/cp_global_quickstart_compression.rst'),
# Others in full-scale materials
('tutorials/hello_nas.rst', 'tutorials/cp_hello_nas_quickstart.rst'),
('tutorials/pruning_quick_start_mnist.rst', 'tutorials/cp_pruning_quick_start_mnist.rst'),
('tutorials/pruning_speed_up.rst', 'tutorials/cp_pruning_speed_up.rst'),
('tutorials/quantization_quick_start_mnist.rst', 'tutorials/cp_quantization_quick_start_mnist.rst'),
('tutorials/quantization_speed_up.rst', 'tutorials/cp_quantization_speed_up.rst'),
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['../templates']
......
docs/source/experiment/remote.rst
View file @ 297a1e2e
......@@ -2,3 +2,11 @@ Remote Training Service
=======================
TBD
Temporarily placed here:
.. _nniignore:
.. Note:: If you are planning to use remote machines or clusters as your training service, to avoid too much pressure on network, NNI limits the number of files to 2000 and total size to 300MB. If your codeDir contains too many files, you can choose which files and subfolders should be excluded by adding a ``.nniignore`` file that works like a ``.gitignore`` file. For more details on how to write this file, see the `git documentation <https://git-scm.com/docs/gitignore#_pattern_format>`__.
*Example:* :githublink:`config_detailed.yml <examples/trials/mnist-pytorch/config_detailed.yml>` and :githublink:`.nniignore <examples/trials/mnist-pytorch/.nniignore>`
docs/source/index.rst
View file @ 297a1e2e
......@@ -6,9 +6,9 @@ Neural Network Intelligence
:caption: Get Started
:hidden:
Installation <installation>
QuickStart <Tutorial/QuickStart>
Tutorials <tutorials>
installation
quickstart
Learning NNI <tutorials>
.. toctree::
:maxdepth: 2
......@@ -65,7 +65,7 @@ To install the current release:
See the :doc:`installation guide </installation>` if you need additional help on installation.
Then, please read :doc:`Quick start <Tutorial/QuickStart>` and :doc:`Tutorials <tutorials>` to start your journey with NNI!
Then, please read :doc:`quickstart` and :doc:`tutorials` to start your journey with NNI!
.. Please keep this part sync with readme
......@@ -95,7 +95,7 @@ Then, please read :doc:`Quick start <Tutorial/QuickStart>` and :doc:`Tutorials <
<div class="codesnippet-card-container">
.. codesnippetcard::
:icon: ../img/thumbnails/hpo-icon-small.png
:icon: ../img/thumbnails/hpo-small.svg
:title: Hyper-parameter Tuning
:link: tutorials/hpo_quickstart_pytorch/main
......@@ -118,7 +118,7 @@ Then, please read :doc:`Quick start <Tutorial/QuickStart>` and :doc:`Tutorials <
nni.report_final_result(accuracy)
.. codesnippetcard::
:icon: ../img/thumbnails/pruning-icon-small.png
:icon: ../img/thumbnails/pruning-small.svg
:title: Model Pruning
:link: tutorials/pruning_quick_start_mnist
......@@ -140,7 +140,7 @@ Then, please read :doc:`Quick start <Tutorial/QuickStart>` and :doc:`Tutorials <
speedup_model()
.. codesnippetcard::
:icon: ../img/thumbnails/quantization-icon-small.png
:icon: ../img/thumbnails/quantization-small.svg
:title: Quantization
:link: tutorials/quantization_speed_up
......@@ -167,7 +167,7 @@ Then, please read :doc:`Quick start <Tutorial/QuickStart>` and :doc:`Tutorials <
engine.compress()
.. codesnippetcard::
:icon: ../img/thumbnails/multi-trial-nas-icon-small.png
:icon: ../img/thumbnails/multi-trial-nas-small.svg
:title: Neural Architecture Search
:link: tutorials/hello_nas
......@@ -189,7 +189,7 @@ Then, please read :doc:`Quick start <Tutorial/QuickStart>` and :doc:`Tutorials <
evaluator, strategy).run()
.. codesnippetcard::
:icon: ../img/thumbnails/one-shot-nas-icon-small.png
:icon: ../img/thumbnails/one-shot-nas-small.svg
:title: One-shot NAS
:link: nas/index
......@@ -206,7 +206,7 @@ Then, please read :doc:`Quick start <Tutorial/QuickStart>` and :doc:`Tutorials <
arch = trainer.export()
.. codesnippetcard::
:icon: ../img/thumbnails/feature-engineering-icon-small.png
:icon: ../img/thumbnails/feature-engineering-small.svg
:title: Feature Engineering
:link: FeatureEngineering/Overview
......@@ -233,7 +233,7 @@ Then, please read :doc:`Quick start <Tutorial/QuickStart>` and :doc:`Tutorials <
<h3>NNI eases the effort to scale and manage AutoML experiments.</h3>
.. codesnippetcard::
:icon: ../img/thumbnails/feature-engineering-icon-small.png
:icon: ../img/thumbnails/training-service-small.svg
:title: Training Service
:link: experiment/training_service
:seemore: See more here.
......@@ -244,7 +244,7 @@ Then, please read :doc:`Quick start <Tutorial/QuickStart>` and :doc:`Tutorials <
Currently, NNI supports **more than 9** kinds of training services.
.. codesnippetcard::
:icon: ../img/thumbnails/feature-engineering-icon-small.png
:icon: ../img/thumbnails/web-portal-small.svg
:title: Web Portal
:link: experiment/web_portal
:seemore: See more here.
......@@ -255,7 +255,7 @@ Then, please read :doc:`Quick start <Tutorial/QuickStart>` and :doc:`Tutorials <
:width: 100%
.. codesnippetcard::
:icon: ../img/thumbnails/feature-engineering-icon-small.png
:icon: ../img/thumbnails/experiment-management-small.svg
:title: Experiment Management
:link: experiment/exp_management
:seemore: See more here.
......@@ -286,3 +286,22 @@ NNI is maintained on the `NNI GitHub repository <https://github.com/microsoft/nn
.. image:: https://user-images.githubusercontent.com/39592018/80665738-e0574a80-8acc-11ea-91bc-0836dc4cbf89.png
-
.. image:: https://github.com/scarlett2018/nniutil/raw/master/wechat.png
.. raw:: html
<h2>Citing NNI</h2>
If you use NNI in a scientific publication, please consider citing NNI in your references.
Microsoft. Neural Network Intelligence (version |release|). https://github.com/microsoft/nni
Bibtex entry (please replace the version with the particular version you are using): ::
@software{nni2021,
author = {{Microsoft}},
month = {1},
title = {{Neural Network Intelligence}},
url = {https://github.com/microsoft/nni},
version = {2.0},
year = {2021}
}
docs/source/index_zh.rst
View file @ 297a1e2e
.. 667579cc0df56e2a258a2222f0f6cd36
.. 4d670c5b2f7eebe5b65f593d7d350b85
###########################
Neural Network Intelligence
......@@ -10,7 +10,7 @@ Neural Network Intelligence
:titlesonly:
:hidden:
入门<Tutorial/QuickStart>
入门 <quickstart>
安装 <installation>
教程<tutorials>
自动（超参数）调优 <hpo/index>
......
docs/source/nas/index.rst
View file @ 297a1e2e
......@@ -14,6 +14,8 @@ Retiarii for Neural Architecture Search
.. attention:: NNI's latest NAS supports are all based on Retiarii Framework, users who are still on `early version using NNI NAS v1.0 <https://nni.readthedocs.io/en/v2.2/nas.html>`__ shall migrate your work to Retiarii as soon as possible.
.. note:: PyTorch is the **only supported framework on Retiarii**. Inquiries of NAS support on Tensorflow is in `this discussion <https://github.com/microsoft/nni/discussions/4605>`__. If you intend to run NAS with DL frameworks other than PyTorch and Tensorflow, please `open new issues <https://github.com/microsoft/nni/issues>`__ to let us know.
.. Using rubric to prevent the section heading to be include into toc
.. rubric:: Motivation
......@@ -24,7 +26,7 @@ However, it is pretty hard to use existing NAS work to help develop common DNN m
In summary, we highlight the following features for Retiarii:
* Simple APIs are provided for defining model search space within PyTorch/TensorFlow model.
* Simple APIs are provided for defining model search space within a deep learning model.
* SOTA NAS algorithms are built-in to be used for exploring model search space.
* System-level optimizations are implemented for speeding up the exploration.
......
docs/source/quickstart.rst 0 → 100644
View file @ 297a1e2e
Quickstart
==========
.. TOC
.. toctree::
:maxdepth: 2
:hidden:
tutorials/hpo_quickstart_pytorch/cp_global_quickstart_hpo
tutorials/cp_global_quickstart_nas
tutorials/cp_global_quickstart_compression
.. ----------------------
.. cardlinkitem::
:header: HPO Quickstart with PyTorch
:description: Use HPO to tune a PyTorch FashionMNIST model
:link: tutorials/hpo_quickstart_pytorch/cp_global_quickstart_hpo.html
:image: ../img/thumbnails/overview-33.png
.. cardlinkitem::
:header: NAS Quickstart
:description: Beginners' NAS tutorial on how to search for neural architectures for MNIST dataset.
:link: tutorials/cp_global_quickstart_nas.html
:image: ../img/thumbnails/overview-30.png
:background: cyan
.. cardlinkitem::
:header: Get Started with Model Pruning on MNIST
:description: Familiarize yourself with pruning to compress your model.
:link: tutorials/cp_global_quickstart_compression.html
:image: ../img/thumbnails/overview-29.png
:background: teal
docs/static/css/material_custom.css
View file @ 297a1e2e
......@@ -39,6 +39,37 @@ dt.sig-object {
word-wrap: break-word;
}
.class > dt.sig-object {
border-left: none; /* remove left border */
border-top: 0.18rem solid #ec407a; /* this should be matched with theme color. */
}
.function > dt.sig-object {
border-left: none; /* remove left border */
border-top: 0.18rem solid #ec407a; /* this should be matched with theme color. */
}
.exception > dt.sig-object {
border-left: none; /* remove left border */
border-top: 0.18rem solid #ec407a; /* this should be matched with theme color. */
}
/* Padding on parameter list is not needed */
dl.field-list > dt {
padding-left: 0 !important;
}
dl.field-list > dd {
margin-left: 1.5em;
}
/* show headerlink when hover/focus */
.headerlink:focus, .headerlink:hover {
-webkit-transform: translate(0);
transform: translate(0);
opacity: 1;
}
/* logo is too large */
a.md-logo img {
padding: 3px;
......@@ -134,10 +165,10 @@ nav.md-tabs .md-tabs__item:not(:last-child) .md-tabs__link:after {
position: relative;
}
.codesnippet-card-title-container h3 {
padding-left: 2.5rem;
line-height: 1.8rem;
height: 1.8rem;
.codesnippet-card-title-container h4 {
padding-left: 2.3rem;
line-height: 1.6rem;
height: 1.6rem;
margin-top: 0;
}
......@@ -163,8 +194,8 @@ nav.md-tabs .md-tabs__item:not(:last-child) .md-tabs__link:after {
}
.codesnippet-card-icon {
width: 1.8rem;
height: 1.8rem;
width: 1.6rem;
height: 1.6rem;
padding: 0;
}
......@@ -183,6 +214,6 @@ nav.md-tabs .md-tabs__item:not(:last-child) .md-tabs__link:after {
/* We did this by using scroll-margin-top instead */
dt:target {
margin-top: 0.15rem !important;
padding-top: 0 !important;
padding-top: 0.5rem !important;
scroll-margin-top: 3.5rem;
}
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