Skip to content

GitLab

"...git@developer.sourcefind.cn:wuxk1/megatron-lm.git" did not exist on "ff15473d5895bd7071db76a930ab737d3315048f"
Unverified Commit 035d58bc authored by SparkSnail's avatar SparkSnail Committed by GitHub
Browse files

Merge pull request #121 from Microsoft/master 

merge master
parents b633c265 8e732f2c
Show whitespace changes
Inline Side-by-side
Showing with 2842 additions and 0 deletions
zh_CN/docs/Builtin_Tuner.md 0 → 100644
View file @ 035d58bc
# 内置 Tuner
NNI 提供了先进的调优算法，使用上也很简单。 下面是内置 Tuner 的简单介绍：
| Tuner | 算法简介 |
| ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **TPE** [(用法)](#TPE) | Tree-structured Parzen Estimator (TPE) 是一种 sequential model-based optimization（SMBO，即基于序列模型优化）的方法。 SMBO 方法根据历史指标数据来按顺序构造模型，来估算超参的性能，随后基于此模型来选择新的超参。 |
| **Random Search** [(用法)](#Random) | 在超参优化时，随机搜索算法展示了其惊人的简单和效果。 建议当不清楚超参的先验分布时，采用随机搜索作为基准。 |
| **Anneal** [(用法)](#Anneal) | 这种简单的退火算法从先前的采样开始，会越来越靠近发现的最佳点取样。 此算法是随机搜索的简单变体，利用了反应曲面的平滑性。 退火率不是自适应的。 |
| **Naive Evolution** [(用法)](#Evolution) | 朴素进化算法来自于大规模图像分类进化。 它会基于搜索空间随机生成一个种群。 在每一代中，会选择较好的结果，并对其下一代进行一些变异（例如，改动一个超参，增加或减少一层）。 进化算法需要很多次 Trial 才能有效，但它也非常简单，也很容易扩展新功能。 |
| **SMAC** [(用法)](#SMAC) | SMAC 基于 Sequential Model-Based Optimization (SMBO，即序列的基于模型优化方法)。 它会利用使用过的结果好的模型（高斯随机过程模型），并将随机森林引入到 SMBO 中，来处理分类参数。 SMAC 算法包装了 Github 的 SMAC3。 注意：SMAC 需要通过 `nnictl package` 命令来安装。 |
| **Batch tuner** [(用法)](#Batch) | Batch Tuner 能让用户简单的提供几组配置（如，超参选项的组合）。 当所有配置都执行完后，Experiment 即结束。 Batch Tuner 仅支持 choice 类型。 |
| **Grid Search** [(用法)](#GridSearch) | 网格搜索会穷举定义在搜索空间文件中的所有超参组合。 网格搜索可以使用的类型有 choice, quniform, qloguniform。 quniform 和 qloguniform 中的数值 q 具有特别的含义（不同于搜索空间文档中的说明）。 它表示了在最高值与最低值之间采样的值的数量。 |
| [Hyperband](https://github.com/Microsoft/nni/tree/master/src/sdk/pynni/nni/hyperband_advisor) [(用法)](#Hyperband) | Hyperband 试图用有限的资源来探索尽可能多的组合，并发现最好的结果。 它的基本思路是生成大量的配置，并运行少量的步骤来找到有可能好的配置，然后继续训练找到其中更好的配置。 |
| [Network Morphism](../src/sdk/pynni/nni/networkmorphism_tuner/README.md) [(用法)](#NetworkMorphism) | Network Morphism 提供了深度学习模型的自动架构搜索功能。 每个子网络都继承于父网络的知识和形态，并变换网络的不同形态，包括深度，宽度，跨层连接（skip-connection）。 然后使用历史的架构和指标，来估计子网络的值。 最后会选择最有希望的模型进行训练。 |
| **Metis Tuner** [(用法)](#MetisTuner) | 大多数调参工具仅仅预测最优配置，而 Metis 的优势在于有两个输出：(a) 最优配置的当前预测结果， 以及 (b) 下一次 Trial 的建议。 它不进行随机取样。 大多数工具假设训练集没有噪声数据，但 Metis 会知道是否需要对某个超参重新采样。 |
<br />
## 用法
要使用 NNI 内置的 Tuner，需要在 `config.yml` 文件中添加 **builtinTunerName** 和 **classArgs**。 这一节会介绍推荐的场景、参数等详细用法以及样例。
注意：参考样例中的格式来创建新的 `config.yml` 文件。 一些内置的 Tuner 还需要通过 `nnictl package` 命令先安装，如 SMAC。
<a name="TPE"></a>
![](https://placehold.it/15/1589F0/000000?text=+) `TPE`
> 名称：**TPE**
**建议场景**
TPE 是一种黑盒优化方法，可以使用在各种场景中，通常情况下都能得到较好的结果。 特别是在计算资源有限，只能运行少量 Trial 的情况。 大量的实验表明，TPE 的性能远远优于随机搜索。
**参数**
* **optimize_mode** (*maximize 或 minimize，可选，默认值为 maximize*) - 如果为 'maximize'，Tuner 会给出有可能产生较大值的参数组合。 如果为 'minimize'，Tuner 会给出有可能产生较小值的参数组合。
**使用样例：**
```yaml
# config.yml
tuner:
builtinTunerName: TPE
classArgs:
optimize_mode: maximize
```
<br />
<a name="Random"></a>
![](https://placehold.it/15/1589F0/000000?text=+) `Random Search`
> 名称：**Random**
**建议场景**
在每个 Trial 运行时间不长（例如，能够非常快的完成，或者很快的被 Assessor 终止），并有充足计算资源的情况下。 或者需要均匀的探索搜索空间。 随机搜索可作为搜索算法的基准线。
**参数**
* **optimize_mode** (*maximize 或 minimize，可选，默认值为 maximize*) - 如果为 'maximize'，Tuner 会给出有可能产生较大值的参数组合。 如果为 'minimize'，Tuner 会给出有可能产生较小值的参数组合。
**使用样例：**
```yaml
# config.yml
tuner:
builtinTunerName: Random
classArgs:
optimize_mode: maximize
```
<br />
<a name="Anneal"></a>
![](https://placehold.it/15/1589F0/000000?text=+) `Anneal`
> 名称：**Anneal**
**建议场景**
当每个 Trial 的时间不长，并且有足够的计算资源时使用（与随机搜索基本相同）。 或者搜索空间的变量能从一些先验分布中采样。
**参数**
* **optimize_mode** (*maximize 或 minimize，可选，默认值为 maximize*) - 如果为 'maximize'，Tuner 会给出有可能产生较大值的参数组合。 如果为 'minimize'，Tuner 会给出有可能产生较小值的参数组合。
**使用样例：**
```yaml
# config.yml
tuner:
builtinTunerName: Anneal
classArgs:
optimize_mode: maximize
```
<br />
<a name="Evolution"></a>
![](https://placehold.it/15/1589F0/000000?text=+) `Naive Evolution`
> 名称：**Evolution**
**建议场景**
此算法对计算资源的需求相对较高。 需要非常大的初始种群，以免落入局部最优中。 如果 Trial 时间很短，或者利用了 Assessor，就非常适合此算法。 如果 Trial 代码支持权重迁移，即每次 Trial 会从上一轮继承已经收敛的权重，建议使用此算法。 这会大大提高训练速度。
**参数**
* **optimize_mode** (*maximize 或 minimize，可选，默认值为 maximize*) - 如果为 'maximize'，Tuner 会给出有可能产生较大值的参数组合。 如果为 'minimize'，Tuner 会给出有可能产生较小值的参数组合。
**使用样例：**
```yaml
# config.yml
tuner:
builtinTunerName: Evolution
classArgs:
optimize_mode: maximize
```
<br />
<a name="SMAC"></a>
![](https://placehold.it/15/1589F0/000000?text=+) `SMAC`
> 名称：**SMAC**
**安装**
SMAC 在第一次使用前，必须用下面的命令先安装。
```bash
nnictl package install --name=SMAC
```
**建议场景**
与 TPE 类似，SMAC 也是一个可以被用在各种场景中的黑盒 Tuner。在计算资源有限时，也可以使用。 此算法为离散超参而优化，因此，如果大部分超参是离散值时，建议使用此算法。
**参数**
* **optimize_mode** (*maximize 或 minimize，可选，默认值为 maximize*) - 如果为 'maximize'，Tuner 会给出有可能产生较大值的参数组合。 如果为 'minimize'，Tuner 会给出有可能产生较小值的参数组合。
**使用样例：**
```yaml
# config.yml
tuner:
builtinTunerName: SMAC
classArgs:
optimize_mode: maximize
```
<br />
<a name="Batch"></a>
![](https://placehold.it/15/1589F0/000000?text=+) `Batch Tuner`
> 名称：BatchTuner
**建议场景**
如果 Experiment 配置已确定，可通过 Batch Tuner 将它们罗列到搜索空间中运行即可。
**使用样例：**
```yaml
# config.yml
tuner:
builtinTunerName: BatchTuner
```
<br />
注意 Batch Tuner 支持的搜索空间文件如下例：
```json
{
"combine_params":
{
"_type" : "choice",
"_value" : [{"optimizer": "Adam", "learning_rate": 0.00001},
{"optimizer": "Adam", "learning_rate": 0.0001},
{"optimizer": "Adam", "learning_rate": 0.001},
{"optimizer": "SGD", "learning_rate": 0.01},
{"optimizer": "SGD", "learning_rate": 0.005},
{"optimizer": "SGD", "learning_rate": 0.0002}]
}
}
```
搜索空间文件使用了键 `combine_params`。 参数类型必须是 `choice` ，并且 `values` 要包含所有需要 Experiment 的参数组合。
<a name="GridSearch"></a>
![](https://placehold.it/15/1589F0/000000?text=+) `Grid Search`
> 名称：**Grid Search**
**建议场景**
注意，搜索空间仅支持 `choice`, `quniform`, `qloguniform`。 `quniform` 和 `qloguniform` 中的 **数字 `q` 有不同的含义（与[搜索空间](./SearchSpaceSpec.md)说明不同）。 在这里意味着会在 `low` 和 `high` 之间均匀取值的数量。</p>
当搜索空间比较小，能够遍历整个搜索空间。
**使用样例：**
```yaml
# config.yml
tuner:
builtinTunerName: GridSearch
```
<br />
<a name="Hyperband"></a>
![](https://placehold.it/15/1589F0/000000?text=+) `Hyperband`
> 名称：**Hyperband**
**建议场景**
当搜索空间很大，但计算资源有限时建议使用。 中间结果能够很好的反映最终结果的情况下，此算法会非常有效。
**参数**
* **optimize_mode** (*maximize 或 minimize，可选，默认值为 maximize*) - 如果为 'maximize'，Tuner 会给出有可能产生较大值的参数组合。 如果为 'minimize'，Tuner 会给出有可能产生较小值的参数组合。
* **R** (*int, 可选, 默认为 60*) - 能分配给 Trial 的最大 STEPS (可以是 mini-batches 或 epochs 的数值)。 Trial 需要用 STEPS 来控制运行时间。
* **eta** (*int, 可选, 默认为 3*) - `(eta-1)/eta` 是丢弃 Trial 的比例。
**使用样例：**
```yaml
# config.yml
advisor:
builtinAdvisorName: Hyperband
classArgs:
optimize_mode: maximize
R: 60
eta: 3
```
<br />
<a name="NetworkMorphism"></a>
![](https://placehold.it/15/1589F0/000000?text=+) `Network Morphism`
> 名称：**NetworkMorphism**
**安装**
必须先安装 [pyTorch](https://pytorch.org/get-started/locally)。
**建议场景**
需要将深度学习方法应用到自己的任务（自己的数据集）上，但不清楚该如何选择或设计网络。 可修改[样例](https://github.com/Microsoft/nni/tree/master/examples/trials/network_morphism/cifar10/cifar10_keras.py)来适配自己的数据集和数据增强方法。 也可以修改批处理大小，学习率或优化器。 它可以为不同的任务找到好的网络架构。 当前，此 Tuner 仅支持视觉领域。
**参数**
* **optimize_mode** (*maximize 或 minimize，可选，默认值为 maximize*) - 如果为 'maximize'，Tuner 会给出有可能产生较大值的参数组合。 如果为 'minimize'，Tuner 会给出有可能产生较小值的参数组合。
* **task** (*('cv'), 可选, 默认为 'cv'*) - 实验的领域，当前仅支持视觉（cv）。
* **input_width** (*int, 可选, 默认为 = 32*) - 输入图像的宽度
* **input_channel** (*int, 可选, 默认为 3*) - 输入图像的通道数
* **n_output_node** (*int, 可选, 默认为 10*) - 输出分类的数量
**使用样例：**
```yaml
# config.yml
tuner:
builtinTunerName: NetworkMorphism
classArgs:
optimize_mode: maximize
task: cv
input_width: 32
input_channel: 3
n_output_node: 10
```
<br />
<a name="MetisTuner"></a>
![](https://placehold.it/15/1589F0/000000?text=+) `Metis Tuner`
> 名称：**MetisTuner**
注意，搜索空间仅支持 `choice`, `quniform`, `uniform` 和 `randint`。
**安装**
Metis Tuner 需要先安装 [sklearn](https://scikit-learn.org/)。 可通过 `pip3 install sklearn` 命令来安装。
**建议场景**
与 TPE 和 SMAC 类似，Metis 是黑盒 Tuner。 如果系统需要很长时间才能完成一次 Trial，Metis 就比随机搜索等其它方法要更合适。 此外，Metis 还为接下来的 Trial 提供了候选。 如何使用 Metis 的[样例](https://github.com/Microsoft/nni/tree/master/examples/trials/auto-gbdt/search_space_metis.json)。 通过调用 NNI 的 SDK，用户只需要发送 `精度` 这样的最终结果给 Tuner。
**参数**
* **optimize_mode** (*maximize 或 minimize，可选，默认值为 maximize*) - 如果为 'maximize'，Tuner 会给出有可能产生较大值的参数组合。 如果为 'minimize'，Tuner 会给出有可能产生较小值的参数组合。
**使用样例：**
```yaml
# config.yml
tuner:
builtinTunerName: MetisTuner
classArgs:
optimize_mode: maximize
```
\ No newline at end of file
zh_CN/docs/CONTRIBUTING.md 0 → 100644
View file @ 035d58bc
# 改进 Neural Network Intelligence (NNI)
欢迎！！ 我们非常欢迎贡献者，特别是代码贡献者。
首先，如果有什么不确定的事情，可随时提交问题或拉取请求。 不会有人因此而抱怨。:) 最有可能的是，会有礼貌的请求你修改一些内容。 我们会感激任何形式的贡献，不想用一堆规则来阻止这些贡献。
不管怎样，如果想要更有效的贡献代码，可以阅读以下内容。 本文档包括了所有在贡献中需要注意的要点，会加快合并代码、解决问题的速度。
查看[快速入门](./QuickStart.md)来初步了解。
下面是一些简单的贡献指南。
## 提交问题
在提出问题时，请说明以下事项：
- 按照问题模板的内容来填写安装的细节，以便评审者检查。
- 出现问题的场景 (尽量详细，以便重现问题)。
- 错误和日志消息。
- 其它可能有用的细节信息。
## 提交新功能建议
- 在适配使用场景时，总会需要一些新的功能。 可以加入新功能的讨论，也可以直接提交新功能的拉取请求。
- 在自己的 github 账户下 fork 存储库。 在 fork 后， 对于 add, commit, push, 或 squash (如需要) 等改动都需要详细的提交消息。 然后就可以提交拉取请求了。
## 参与源代码和 Bug 修复
拉取请求需要选好正确的标签，表明是 Bug 修复还是功能改进。 所有代码都需要遵循正确的命名约定和代码风格。
参考[如何配置 NNI 的开发环境](./SetupNNIDeveloperEnvironment.md)，来安装开发环境。
与[快速入门](QuickStart.md)类似。 其它内容，参考[NNI 文档](http://nni.readthedocs.io)。
## 处理现有问题
查看[问题列表](https://github.com/Microsoft/nni/issues)，找到需要贡献的问题。 可以找找有 'good-first-issue' 或 'help-wanted' 标签的来开始贡献。
修改问题的注释和指派人来表明此问题已经开始跟进。 如果上述问题在一周内没有拉取请求或更新状态，这个问题会重新开放给所有人。 高优先级的 Bug 和回归问题需在一天内响应。
## 代码风格和命名约定
NNI 遵循 [PEP8](https://www.python.org/dev/peps/pep-0008/) 的 Python 代码命名约定。在提交拉取请求时，请尽量遵循此规范。 可通过`flake8`或`pylint`的提示工具来帮助遵循规范。
\ No newline at end of file
zh_CN/docs/Contribution.rst 0 → 100644
View file @ 035d58bc
###############################
为 NNI 做贡献
###############################
.. toctree::
设置开发环境<SetupNNIDeveloperEnvironment>
贡献指南<CONTRIBUTING>
如何调试<HowToDebug>
\ No newline at end of file
zh_CN/docs/Customize_Advisor.md 0 → 100644
View file @ 035d58bc
# **指南** - 自定义 advisor
*Advisor 用于同时需要 Tuner 和 Assessor 方法的自动机器学习算法。 Advisor 与 Tuner 类似，它接收 Trial 的参数请求、最终结果，并生成 Trial 的参数。 另外，它也能像 Assessor 一样接收中间结果、Trial 的最终状态，并可以发送终止 Trial 的命令。 注意，在使用 Advisor 时，不能同时使用 Tuner 和 Assessor。*
如果要自定义 Advisor，需要：
1. 从 MsgDispatcherBase 类继承并创建新的 Advisor 类
2. 实现所有除了 `handle_request` 外的，以 `handle_` 前缀开始的方法
3. 在 Experiment 的 YAML 文件中配置好自定义的 Advisor
样例如下：
**1) 从 MsgDispatcherBase 类继承并创建新的 Advisor 类**
```python
from nni.msg_dispatcher_base import MsgDispatcherBase
class CustomizedAdvisor(MsgDispatcherBase):
def __init__(self, ...):
...
```
**2) 实现所有除了 `handle_request` 外的，以 `handle_` 前缀开始的方法**
参考 Hyperband 的实现 ([src/sdk/pynni/nni/hyperband_advisor/hyperband_advisor.py](https://github.com/Microsoft/nni/tree/master/src/sdk/pynni/nni/hyperband_advisor/hyperband_advisor.py)) 来学习如何实现这些方法。
**3) 在 Experiment 的 YAML 文件中配置好自定义的 Advisor**
与 Tuner 和 Assessor 类似。 NNI 需要定位到自定义的 Advisor 类，并实例化它，因此需要指定自定义 Advisor 类的文件位置，并将参数值传给 \_\_init__ 构造函数。
```yaml
advisor:
codeDir: /home/abc/myadvisor
classFileName: my_customized_advisor.py
className: CustomizedAdvisor
# 任何传入 __init__ 构造函数的参数
# 都需要声明在 classArgs 字段中，如：
classArgs:
arg1: value1
```
\ No newline at end of file
zh_CN/docs/Customize_Assessor.md 0 → 100644
View file @ 035d58bc
# 自定义 Assessor
NNI 支持自定义 Assessor。
实现自定义的 Assessor，需要如下几步：
1. 继承 Assessor 基类
2. 实现 assess_trial 函数
3. 在 Experiment 的 YAML 文件中配置好自定义的 Assessor
**1. 继承 Assessor 基类**
```python
from nni.assessor import Assessor
class CustomizedAssessor(Assessor):
def __init__(self, ...):
...
```
**2. 实现 assess_trial 函数**
```python
from nni.assessor import Assessor, AssessResult
class CustomizedAssessor(Assessor):
def __init__(self, ...):
...
def assess_trial(self, trial_history):
"""
确定是否要停止该 Trial。 必须重载。
trial_history: 中间结果列表对象。
返回 AssessResult.Good 或 AssessResult.Bad。
"""
# 代码实现于此处。
...
```
**3. 在 Experiment 的 YAML 文件中配置好自定义的 Assessor**
NNI 需要定位到自定义的 Assessor 类，并实例化它，因此需要指定自定义 Assessor 类的文件位置，并将参数值传给 \_\_init__ 构造函数。
```yaml
assessor:
codeDir: /home/abc/myassessor
classFileName: my_customized_assessor.py
className: CustomizedAssessor
# 任何传入 __init__ 构造函数的参数，
# 都需要在 classArgs 字段中指定，如
classArgs:
arg1: value1
```
注意在 **2** 中， `trial_history` 对象与 Trial 通过 `report_intermediate_result` 函数返回给 Assessor 的对象完全一致。
更多样例，可参考：
> - [medianstop-assessor](https://github.com/Microsoft/nni/tree/master/src/sdk/pynni/nni/medianstop_assessor)
> - [curvefitting-assessor](https://github.com/Microsoft/nni/tree/master/src/sdk/pynni/nni/curvefitting_assessor)
\ No newline at end of file
zh_CN/docs/Customize_Tuner.md 0 → 100644
View file @ 035d58bc
# 自定义 Tuner
## 自定义 Tuner
NNI 在内置的 Tuner 中提供了最新的调优算法。 NNI 同时也支持自定义 Tuner。
通过自定义 Tuner，可实现自己的调优算法。主要有三步：
1. 继承 Tuner 基类
2. 实现 receive_trial_result 和 generate_parameter 函数
3. 在 Experiment 的 YAML 文件中配置好自定义的 Tuner
样例如下：
**1. 继承 Tuner 基类**
```python
from nni.tuner import Tuner
class CustomizedTuner(Tuner):
def __init__(self, ...):
...
```
**2. 实现 receive_trial_result 和 generate_parameter 函数**
```python
from nni.tuner import Tuner
class CustomizedTuner(Tuner):
def __init__(self, ...):
...
def receive_trial_result(self, parameter_id, parameters, value):
'''
接收 Trial 的最终结果。
parameter_id: int
parameters: 'generate_parameters()' 所创建的对象
value: Trial 的最终指标结果
'''
# 实现代码
...
def generate_parameters(self, parameter_id):
'''
返回 Trial 的超参组合的序列化对象
parameter_id: int
'''
# 代码实现位置
return your_parameters
...
```
`receive_trial_result` 从输入中会接收 `parameter_id, parameters, value` 参数。 Tuner 会收到 Trial 进程发送的完全一样的 `value` 值。
`generate_parameters` 函数返回的 `your_parameters`，会被 NNI SDK 打包为 json。 然后 SDK 会将 json 对象解包给 Trial 进程。因此，Trial 进程会收到来自 Tuner 的完全相同的 `your_parameters`。
例如： 如下实现了 `generate_parameters`：
```python
def generate_parameters(self, parameter_id):
'''
返回 Trial 的超参组合的序列化对象
parameter_id: int
'''
# 代码实现位置
return {"dropout": 0.3, "learning_rate": 0.4}
```
这表示 Tuner 会一直生成超参组合 `{"dropout": 0.3, "learning_rate": 0.4}`。 而 Trial 进程也会在调用 API `nni.get_next_parameter()` 时得到 `{"dropout": 0.3, "learning_rate": 0.4}`。 Trial 结束后的返回值（通常是某个指标），通过调用 API `nni.report_final_result()` 返回给 Tuner。如： `nni.report_final_result(0.93)`。 而 Tuner 的 `receive_trial_result` 函数会收到如下结果：
```python
parameter_id = 82347
parameters = {"dropout": 0.3, "learning_rate": 0.4}
value = 0.93
```
**注意** 如果需要存取自定义的 Tuner 目录里的文件 (如, `data.txt`)，不能使用 `open('data.txt', 'r')`。 要使用：
```python
_pwd = os.path.dirname(__file__)
_fd = open(os.path.join(_pwd, 'data.txt'), 'r')
```
这是因为自定义的 Tuner 不是在自己的目录里执行的。（即，`pwd` 返回的目录不是 Tuner 的目录）。
**3. 在 Experiment 的 YAML 文件中配置好自定义的 Tuner**
NNI 需要定位到自定义的 Tuner 类，并实例化它，因此需要指定自定义 Tuner 类的文件位置，并将参数值传给 \_\_init__ 构造函数。
```yaml
tuner:
codeDir: /home/abc/mytuner
classFileName: my_customized_tuner.py
className: CustomizedTuner
# 任何传入 __init__ 构造函数的参数
# 都需要声明在 classArgs 字段中，如：
classArgs:
arg1: value1
```
更多样例，可参考：
> - [evolution-tuner](https://github.com/Microsoft/nni/tree/master/src/sdk/pynni/nni/evolution_tuner)
> - [hyperopt-tuner](https://github.com/Microsoft/nni/tree/master/src/sdk/pynni/nni/hyperopt_tuner)
> - [evolution-based-customized-tuner](https://github.com/Microsoft/nni/tree/master/examples/tuners/ga_customer_tuner)
### 实现更高级的自动机器学习算法
上述内容足够写出通用的 Tuner。 但有时可能需要更多的信息，例如，中间结果， Trial 的状态等等，从而能够实现更强大的自动机器学习算法。 因此，有另一个叫做 `advisor` 的类，直接继承于 `MsgDispatcherBase`，它位于 [`src/sdk/pynni/nni/msg_dispatcher_base.py`](https://github.com/Microsoft/nni/tree/master/src/sdk/pynni/nni/msg_dispatcher_base.py)。 参考[这里](Customize_Advisor.md)来了解如何实现自定义的 advisor。
\ No newline at end of file
zh_CN/docs/Examples.rst 0 → 100644
View file @ 035d58bc
######################
样例
######################
.. toctree::
:maxdepth: 2
MNIST<mnist_examples>
Cifar10<cifar10_examples>
Scikit-learn<sklearn_examples>
EvolutionSQuAD<SQuAD_evolution_examples>
GBDT<gbdt_example>
zh_CN/docs/ExperimentConfig.md 0 → 100644
View file @ 035d58bc
# Experiment（实验）配置参考
创建 Experiment 时，需要给 nnictl 命令提供配置文件的路径。 配置文件是 YAML 格式，需要保证其格式正确。 本文介绍了配置文件的内容，并提供了一些示例和模板。
* [模板](#Template) (配置文件的模板)
* [配置说明](#Configuration) (配置文件每个项目的说明)
* [样例](#Examples) (配置文件样例)
<a name="Template"></a>
## 模板
* **简化版（不包含 Annotation（标记）和 Assessor）**
```yaml
authorName:
experimentName:
trialConcurrency:
maxExecDuration:
maxTrialNum:
#可选项: local, remote, pai, kubeflow
trainingServicePlatform:
searchSpacePath:
#可选项: true, false
useAnnotation:
tuner:
#可选项: TPE, Random, Anneal, Evolution
builtinTunerName:
classArgs:
#可选项: maximize, minimize
optimize_mode:
gpuNum:
trial:
command:
codeDir:
gpuNum:
#在本地使用时，machineList 可为空
machineList:
- ip:
port:
username:
passwd:
```
* **使用 Assessor**
```yaml
authorName:
experimentName:
trialConcurrency:
maxExecDuration:
maxTrialNum:
#可选项: local, remote, pai, kubeflow
trainingServicePlatform:
searchSpacePath:
#可选项: true, false
useAnnotation:
tuner:
#可选项: TPE, Random, Anneal, Evolution
builtinTunerName:
classArgs:
#可选项: maximize, minimize
optimize_mode:
gpuNum:
assessor:
#可选项: Medianstop
builtinAssessorName:
classArgs:
#可选项: maximize, minimize
optimize_mode:
gpuNum:
trial:
command:
codeDir:
gpuNum:
#在本地使用时，machineList 可为空
machineList:
- ip:
port:
username:
passwd:
```
* **使用 Annotation**
```yaml
authorName:
experimentName:
trialConcurrency:
maxExecDuration:
maxTrialNum:
#可选项: local, remote, pai, kubeflow
trainingServicePlatform:
#可选项: true, false
useAnnotation:
tuner:
#可选项: TPE, Random, Anneal, Evolution
builtinTunerName:
classArgs:
#可选项: maximize, minimize
optimize_mode:
gpuNum:
assessor:
#可选项: Medianstop
builtinAssessorName:
classArgs:
#可选项: maximize, minimize
optimize_mode:
gpuNum:
trial:
command:
codeDir:
gpuNum:
#在本地使用时，machineList 可为空
machineList:
- ip:
port:
username:
passwd:
```
<a name="Configuration"></a>
## 说明
* **authorName**
* 说明
**authorName** 是创建 Experiment 的作者。 待定: 增加默认值
* **experimentName**
* 说明
**experimentName** 是 Experiment 的名称。
待实现：增加默认值
* **trialConcurrency**
* 说明
**trialConcurrency** 定义了并发尝试任务的最大数量。
注意：如果 trialGpuNum 大于空闲的 GPU 数量，并且并发的 Trial 任务数量还没达到 trialConcurrency，Trial 任务会被放入队列，等待分配 GPU 资源。
* **maxExecDuration**
* 说明
**maxExecDuration** 定义 Experiment 执行的最长时间。时间单位：{**s**, **m**, **h**, **d**}，分别代表：{*seconds*, *minutes*, *hours*, *days*}。
注意：maxExecDuration 设置的是 Experiment 执行的时间，不是 Trial 的。 如果 Experiment 达到了设置的最大时间，Experiment 不会停止，但不会再启动新的 Trial 作业。
* **maxTrialNum**
* 说明
**maxTrialNum** 定义了 Trial 任务的最大数量，成功和失败的都计算在内。
* **trainingServicePlatform**
* 说明
**trainingServicePlatform** 定义运行 Experiment 的平台，包括：{**local**, **remote**, **pai**, **kubeflow**}.
* **local** 在本机的 ubuntu 上运行 Experiment。
* **remote** 将任务提交到远程的 Ubuntu 上，必须用 **machineList** 来指定远程的 SSH 连接信息。
* **pai** 提交任务到微软开源的 [OpenPAI](https://github.com/Microsoft/pai) 上。 更多 OpenPAI 配置，参考 [pai 模式](./PAIMode.md)。
* **kubeflow** 提交任务至 [Kubeflow](https://www.kubeflow.org/docs/about/kubeflow/)。 NNI 支持基于 Kubeflow 的 Kubenetes，以及[Azure Kubernetes](https://azure.microsoft.com/en-us/services/kubernetes-service/)。
* **searchSpacePath**
* 说明
**searchSpacePath** 定义搜索空间文件的路径，此文件必须在运行 nnictl 的本机。
注意: 如果设置了 useAnnotation=True，searchSpacePath 字段必须被删除。
* **useAnnotation**
* 说明
**useAnnotation** 定义使用标记来分析代码并生成搜索空间。
注意: 如果设置了 useAnnotation=True，searchSpacePath 字段必须被删除。
* **nniManagerIp**
* 说明
**nniManagerIp** 设置 NNI 管理器运行的 IP 地址。 此字段为可选项，如果没有设置，则会使用 eth0 的 IP 地址。
注意: 可在 NNI 管理器机器上运行 ifconfig 来检查 eth0 是否存在。 如果不存在，推荐显式设置 nnimanagerIp。
* **logDir**
* 说明
**logDir** 配置存储日志和数据的目录。 默认值是 `<user home directory>/nni/experiment`
* **logLevel**
* 说明
**logLevel** 为 Experiment 设置日志级别，支持的日志级别有：`trace, debug, info, warning, error, fatal`。 默认值是 `info`。
* **Tuner**
* 说明
**tuner** 指定了 Experiment 的 Tuner 算法。有两种方法可设置 Tuner。 一种方法是使用 SDK 提供的 Tuner，需要设置 **builtinTunerName** 和 **classArgs**。 另一种方法，是使用用户自定义的 Tuner，需要设置 **codeDirectory**，**classFileName**，**className** 和 **classArgs**。
* **builtinTunerName** 和 **classArgs**
* **builtinTunerName**
**builtinTunerName** 指定了系统 Tuner 的名字，NNI SDK 提供了多种 Tuner，如：{**TPE**, **Random**, **Anneal**, **Evolution**, **BatchTuner**, **GridSearch**}。
* **classArgs**
**classArgs** 指定了 Tuner 算法的参数。 如果 **builtinTunerName** 是{**TPE**, **Random**, **Anneal**, **Evolution**}，用户需要设置 **optimize_mode**。
* **codeDir**, **classFileName**, **className** 和 **classArgs**
* **codeDir**
**codeDir** 指定 Tuner 代码的目录。
* **classFileName**
**classFileName** 指定 Tuner 文件名。
* **className**
**className** 指定 Tuner 类名。
* **classArgs**
**classArgs** 指定了 Tuner 算法的参数。
* **gpuNum**
**gpuNum** 指定了运行 Tuner 进程的 GPU 数量。 此字段的值必须是正整数。
注意: 只能使用一种方法来指定 Tuner，例如：设置{tunerName, optimizationMode} 或 {tunerCommand, tunerCwd}，不能同时设置。
* **Assessor**
* 说明
**assessor** 指定了 Experiment 的 Assessor 算法。有两种方法可设置 Assessor。 一种方法是使用 SDK 提供的 Assessor，需要设置 **builtinAssessorName** 和 **classArgs**。 另一种方法，是使用用户自定义的 Assessor，需要设置 **codeDirectory**，**classFileName**，**className** 和 **classArgs**。
* **builtinAssessorName** 和 **classArgs**
* **builtinAssessorName**
**builtinAssessorName** 指定了系统 Assessor 的名称， NNI 内置的 Assessor 有 {**Medianstop**，等等}。
* **classArgs**
**classArgs** 指定了 Assessor 算法的参数。
* **codeDir**, **classFileName**, **className** 和 **classArgs**
* **codeDir**
**codeDir** 指定 Assessor 代码的目录。
* **classFileName**
**classFileName** 指定 Assessor 文件名。
* **className**
**className** 指定 Assessor 类名。
* **classArgs**
**classArgs** 指定了 Assessor 算法的参数。
* **gpuNum**
**gpuNum** 指定了运行 Assessor 进程的 GPU 数量。 此字段的值必须是正整数。
注意: 只能使用一种方法来指定评估器，例如：设置 {assessorName, optimizationMode} 或 {assessorCommand, assessorCwd}，不能同时设置。如果不需要使用评估器，可将其置为空。
* **trial (local, remote)**
* **command**
**command** 指定了运行 Trial 进程的命令行。
* **codeDir**
**codeDir** 指定了 Trial 代码文件的目录。
* **gpuNum**
**gpuNum** 指定了运行 Trial 进程的 GPU 数量。 默认值为 0。
* **trial (pai)**
* **command**
**command** 指定了运行 Trial 进程的命令行。
* **codeDir**
**codeDir** 指定了 Trial 代码文件的目录。
* **gpuNum**
**gpuNum** 指定了运行 Trial 进程的 GPU 数量。 默认值为 0。
* **cpuNum**
**cpuNum** 指定了 OpenPAI 容器中使用的 CPU 数量。
* **memoryMB**
**memoryMB** 指定了 OpenPAI 容器中使用的内存数量。
* **image**
**image** 指定了 OpenPAI 中使用的 docker 映像。
* **dataDir**
**dataDir** 是 HDFS 中用到的数据目录变量。
* **outputDir**
**outputDir** 是 HDFS 中用到的输出目录变量。在 OpenPAI 中，stdout 和 stderr 文件会在作业完成后，存放在此目录中。
* **trial (kubeflow)**
* **codeDir**
**codeDir** 指定了代码文件的本机路径。
* **ps (可选)**
**ps** 是 Kubeflow 的 Tensorflow-operator 配置。
* **replicas**
**replicas** 是 **ps** 角色的副本数量。
* **command**
**command** 是在 **ps** 的容器中运行的脚本命令。
* **gpuNum**
**gpuNum** 是在 **ps** 容器中使用的 GPU 数量。
* **cpuNum**
**cpuNum** 是在 **ps** 容器中使用的 CPU 数量。
* **memoryMB**
**memoryMB** 指定了容器中使用的内存数量。
* **image**
**iamge** 设置了 **ps** 使用的 docker 映像。
* **worker**
**worker** 是 Kubeflow 的 Tensorflow-operator 配置。
* **replicas**
**replicas** 是 **worker** 角色的副本数量。
* **command**
**command** 是在 **worker** 的容器中运行的脚本命令。
* **gpuNum**
**gpuNum** 是在 **worker** 容器中使用的 GPU 数量。
* **cpuNum**
**cpuNum** 是在 **worker** 容器中使用的 CPU 数量。
* **memoryMB**
**memoryMB** 指定了容器中使用的内存数量。
* **image**
**image** 设置了 **worker** 使用的 docker 映像。
* **machineList**
如果 **trainingServicePlatform** 为 remote，则需要设置 **machineList**。否则应将其置为空。
* **ip**
**ip** 是远程计算机的 ip 地址。
* **port**
**端口** 是用于连接远程计算机的 ssh 端口。
注意：如果 port 设为空，则为默认值 22。
* **username**
**username** 是远程计算机的用户名。
* **passwd**
**passwd** 指定了账户的密码。
* **sshKeyPath**
如果要使用 ssh 密钥登录远程计算机，则需要设置 **sshKeyPath**。 **sshKeyPath** 为有效的 ssh 密钥文件路径。
注意：如果同时设置了 passwd 和 sshKeyPath，NNI 会使用 passwd。
* **passphrase**
**passphrase** 用于保护 ssh 密钥，如果没有使用，可为空。
* **kubeflowConfig**:
* **operator**
**operator** 指定了 kubeflow 使用的 operator，NNI 当前版本支持 **tf-operator**。
* **存储**
**storage** 指定了 kubeflow 的存储类型，包括 {**nfs**，**azureStorage**}。 此字段可选，默认值为 **nfs**。 如果使用了 azureStorage，此字段必须填写。
* **nfs**
**server** 是 NFS 服务器的地址
**path** 是 NFS 挂载的路径
* **keyVault**
如果用户使用 Azure Kubernetes Service，需要设置 keyVault 来使用 Azure 存储账户的私钥。 参考: https://docs.microsoft.com/en-us/azure/key-vault/key-vault-manage-with-cli2
* **vaultName**
**vaultName** 是 az 命令中 `--vault-name` 的值。
* **name**
**name** 是 az 命令中 `--name` 的值。
* **azureStorage**
如果用户使用了 Azure Kubernetes Service，需要设置 Azure 存储账户来存放代码文件。
* **accountName**
**accountName** 是 Azure 存储账户的名称。
* **azureShare**
**azureShare** 是 Azure 文件存储的共享参数。
* **paiConfig**
* **userName**
**userName** 是 OpenPAI 的用户名。
* **password**
**password** 是 OpenPAI 用户的密码。
* **host**
**host** 是 OpenPAI 的主机地址。
<a name="Examples"></a>
## 样例
* **本机模式**
如果要在本机运行 Trial 任务，并使用标记来生成搜索空间，可参考下列配置：
```yaml
authorName: test
experimentName: test_experiment
trialConcurrency: 3
maxExecDuration: 1h
maxTrialNum: 10
#可选项: local, remote, pai, kubeflow
trainingServicePlatform: local
#可选项: true, false
useAnnotation: true
tuner:
#可选项: TPE, Random, Anneal, Evolution
builtinTunerName: TPE
classArgs:
#可选项: maximize, minimize
optimize_mode: maximize
gpuNum: 0
trial:
command: python3 mnist.py
codeDir: /nni/mnist
gpuNum: 0
```
增加 Assessor 配置
```yaml
authorName: test
experimentName: test_experiment
trialConcurrency: 3
maxExecDuration: 1h
maxTrialNum: 10
#可选项: local, remote, pai, kubeflow
trainingServicePlatform: local
searchSpacePath: /nni/search_space.json
#可选项: true, false
useAnnotation: false
tuner:
#可选项: TPE, Random, Anneal, Evolution
builtinTunerName: TPE
classArgs:
#可选项: maximize, minimize
optimize_mode: maximize
gpuNum: 0
assessor:
#可选项: Medianstop
builtinAssessorName: Medianstop
classArgs:
#可选项: maximize, minimize
optimize_mode: maximize
gpuNum: 0
trial:
command: python3 mnist.py
codeDir: /nni/mnist
gpuNum: 0
```
或者可以指定自定义的 Tuner 和 Assessor：
```yaml
authorName: test
experimentName: test_experiment
trialConcurrency: 3
maxExecDuration: 1h
maxTrialNum: 10
#可选项: local, remote, pai, kubeflow
trainingServicePlatform: local
searchSpacePath: /nni/search_space.json
#可选项: true, false
useAnnotation: false
tuner:
codeDir: /nni/tuner
classFileName: mytuner.py
className: MyTuner
classArgs:
#可选项: maximize, minimize
optimize_mode: maximize
gpuNum: 0
assessor:
codeDir: /nni/assessor
classFileName: myassessor.py
className: MyAssessor
classArgs:
#choice: maximize, minimize
optimize_mode: maximize
gpuNum: 0
trial:
command: python3 mnist.py
codeDir: /nni/mnist
gpuNum: 0
```
* **远程模式**
如果在远程服务器上运行 Trial 任务，需要增加服务器信息：
```yaml
authorName: test
experimentName: test_experiment
trialConcurrency: 3
maxExecDuration: 1h
maxTrialNum: 10
#可选项: local, remote, pai, kubeflow
trainingServicePlatform: remote
searchSpacePath: /nni/search_space.json
#可选项: true, false
useAnnotation: false
tuner:
#可选项: TPE, Random, Anneal, Evolution
builtinTunerName: TPE
classArgs:
#可选项: maximize, minimize
optimize_mode: maximize
gpuNum: 0
trial:
command: python3 mnist.py
codeDir: /nni/mnist
gpuNum: 0
# 如果是本地 Experiment，machineList 可为空。
machineList:
- ip: 10.10.10.10
port: 22
username: test
passwd: test
- ip: 10.10.10.11
port: 22
username: test
passwd: test
- ip: 10.10.10.12
port: 22
username: test
sshKeyPath: /nni/sshkey
passphrase: qwert
```
* **pai 模式**
```yaml
authorName: test
experimentName: nni_test1
trialConcurrency: 1
maxExecDuration:500h
maxTrialNum: 1
#可选项: local, remote, pai, kubeflow
trainingServicePlatform: pai
searchSpacePath: search_space.json
#可选项: true, false
useAnnotation: false
tuner:
#可选项: TPE, Random, Anneal, Evolution, BatchTuner
#SMAC (SMAC 需要使用 nnictl package 单独安装)
builtinTunerName: TPE
classArgs:
#可选项: maximize, minimize
optimize_mode: maximize
trial:
command: python3 main.py
codeDir: .
gpuNum: 4
cpuNum: 2
memoryMB: 10000
# 在 OpenPAI 上用来运行 Nni 作业的 docker 映像
image: msranni/nni:latest
# 在 OpenPAI 的 hdfs 上存储数据的目录，如：'hdfs://host:port/directory'
dataDir: hdfs://10.11.12.13:9000/test
# 在 OpenPAI 的 hdfs 上存储输出的目录，如：'hdfs://host:port/directory'
outputDir: hdfs://10.11.12.13:9000/test
paiConfig:
# OpenPAI 用户名
userName: test
# OpenPAI 密码
passWord: test
# OpenPAI 服务器 Ip
host: 10.10.10.10
```
* **Kubeflow 模式**
使用 NFS 存储。
```yaml
authorName: default
experimentName: example_mni
trialConcurrency: 1
maxExecDuration: 1h
maxTrialNum: 1
#可选项: local, remote, pai, kubeflow
trainingServicePlatform: kubeflow
searchSpacePath: search_space.json
#可选项: true, false
useAnnotation: false
tuner:
#可选项: TPE, Random, Anneal, Evolution
builtinTunerName: TPE
classArgs:
#可选项: maximize, minimize
optimize_mode: maximize
trial:
codeDir: .
worker:
replicas: 1
command: python3 mnist.py
gpuNum: 0
cpuNum: 1
memoryMB: 8192
image: msranni/nni:latest
kubeflowConfig:
operator: tf-operator
nfs:
server: 10.10.10.10
path: /var/nfs/general
```
使用 Azure 存储。
```yaml
authorName: default
experimentName: example_mni
trialConcurrency: 1
maxExecDuration: 1h
maxTrialNum: 1
#可选项: local, remote, pai, kubeflow
trainingServicePlatform: kubeflow
searchSpacePath: search_space.json
#可选项: true, false
useAnnotation: false
#nniManagerIp: 10.10.10.10
tuner:
#可选项: TPE, Random, Anneal, Evolution
builtinTunerName: TPE
classArgs:
#可选项: maximize, minimize
optimize_mode: maximize
assessor:
builtinAssessorName: Medianstop
classArgs:
optimize_mode: maximize
gpuNum: 0
trial:
codeDir: .
worker:
replicas: 1
command: python3 mnist.py
gpuNum: 0
cpuNum: 1
memoryMB: 4096
image: msranni/nni:latest
kubeflowConfig:
operator: tf-operator
keyVault:
vaultName: Contoso-Vault
name: AzureStorageAccountKey
azureStorage:
accountName: storage
azureShare: share01
```
\ No newline at end of file
zh_CN/docs/FAQ.md 0 → 100644
View file @ 035d58bc
# 常见问答
此页为常见问题
### tmp 目录没空间了
nnictl 在执行时，使用 tmp 目录作为临时目录来复制 codeDir 下的文件。 当遇到下列错误时，先试试清空 **tmp** 目录。
> OSError: [Errno 28] No space left on device
### OpenPAI 模式下无法获得 Trial 的数据
在 OpenPAI 的训练模式下，NNI 管理器会在端口 51189 启动一个 RESTful 服务，来接收 OpenPAI 集群中 Trial 任务的指标数据。 如果在 OpenPAI 模式下的网页中不能看到任何指标，需要检查 51189 端口是否在防火墙规则中已打开。
### 安装时出现 Segmentation Fault (core dumped)
> make: *** [install-XXX] Segmentation fault (core dumped)
可依次试试以下方法：
* 更新或重新安装 Python 中的 pip： `python3 -m pip install -U pip`
* 在安装 NNI 时，添加 `--no-cache-dir` 参数：`python3 -m pip install nni --no-cache-dir`
### Job management error: getIPV4Address() failed because os.networkInterfaces().eth0 is undefined.
计算机没有 eth0 设备，需要在配置中设置 [nniManagerIp](ExperimentConfig.md)。
### 运行时间超过了 MaxDuration ，但没有停止
当 Experiment 到达最长运行时间时，nniManager 不会创建新的 Trial ，但除非手动停止 Experiment，运行中的 Trial 会继续运行直到结束。
### 使用 `nnictl stop` 无法停止 Experiment
如果在实验运行时，升级了 nni 或删除了一些配置文件，会因为丢失配置文件而出现这类错误。 可以使用 `ps -ef | grep node` 命令来找到 Experiment 的 pid，并用 `kill -9 {pid}` 命令来停止 Experiment 进程。
### 无法在虚拟机的 NNI 网页中看到 `指标数据`
将虚拟机的网络配置为桥接模式来让虚拟机能被网络访问，并确保虚拟机的防火墙没有禁止相关端口。
### 帮助改进
在创建新问题前，请在 https://github.com/Microsoft/nni/issues 查看是否有人已经报告了相似的问题。
\ No newline at end of file
zh_CN/docs/FrameworkControllerMode.md 0 → 100644
View file @ 035d58bc
# **在 FrameworkController 上运行 Experiment**
NNI 支持使用 [FrameworkController](https://github.com/Microsoft/frameworkcontroller)，来运行 Experiment，称之为 frameworkcontroller 模式。 FrameworkController 构建于 Kubernetes 上，用于编排各种应用。这样，可以不用为某个深度学习框架安装 Kubeflow 的 tf-operator 的 pytorch-operator 等。 而直接用 frameworkcontroller 作为 NNI Experiment 的训练服务。
## 私有部署的 Kubernetes 的准备工作
1. 采用 Kubernetes 1.8 或更高版本。 根据[指南](https://kubernetes.io/docs/setup/)来安装 Kubernetes。
2. 配置 **kubeconfig** 文件，NNI 将使用此配置与 Kubernetes API 服务交互。 默认情况下，NNI 管理器会使用 $(HOME)/.kube/config 作为 kubeconfig 文件的路径。 也可以通过环境变量 **KUBECONFIG** 来指定其它 kubeconfig 文件。 根据[指南](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig)了解更多 kubeconfig 的信息。
3. 如果 NNI Trial 作业需要 GPU 资源，需按照[指南](https://github.com/NVIDIA/k8s-device-plugin)来配置 **Kubernetes 下的 Nvidia 插件**。
4. 准备 **NFS 服务器** 并导出通用的装载 (mount)，推荐将 NFS 服务器路径映射到 `root_squash 选项`，否则可能会在 NNI 复制文件到 NFS 时出现权限问题。 参考[页面](https://linux.die.net/man/5/exports)，来了解关于 root_squash 选项，或 **Azure File Storage**。
5. 在安装 NNI 并运行 nnictl 的计算机上安装 **NFS 客户端**。 运行此命令安装 NFSv4 客户端： ```apt-get install nfs-common```
6. 参考[指南](QuickStart.md)安装 **NNI**。
## Azure 部署的 Kubernetes 的准备工作
1. NNI 支持基于 Azure Kubernetes Service 的 Kubeflow，参考[指南](https://azure.microsoft.com/en-us/services/kubernetes-service/)来设置 Azure Kubernetes Service。
2. 安装 [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest) 和 **kubectl**。 使用 `az login` 命令来设置 Azure 账户吗，并将 kubectl 客户端连接到 AKS，参考此[指南](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough#connect-to-the-cluster)。
3. 参考此[指南](https://docs.microsoft.com/en-us/azure/storage/common/storage-quickstart-create-account?tabs=portal)来创建 Azure 文件存储账户。 NNI 需要 Azure Storage Service 来存取代码和输出文件。
4. NNI 需要访问密钥来连接 Azure 存储服务，NNI 使用 [Azure Key Vault](https://azure.microsoft.com/en-us/services/key-vault/) 服务来保护私钥。 设置 Azure Key Vault 服务，并添加密钥到 Key Vault 中来存取 Azure 存储账户。 参考[指南](https://docs.microsoft.com/en-us/azure/key-vault/quick-create-cli)来存储访问密钥。
## 安装 FrameworkController
参考[指南](https://github.com/Microsoft/frameworkcontroller/tree/master/example/run)来在 Kubernetes 集群中配置 Frameworkcontroller。NNI 通过 statefulset 模式来 支持 Frameworkcontroller。
## 设计
参考[Kubeflow 训练服务](./KubeflowMode.md)，Frameworkcontroller 服务管道非常类似。
## 样例
Frameworkcontroller 配置文件的格式如下：
authorName: default
experimentName: example_mnist
trialConcurrency: 1
maxExecDuration: 10h
maxTrialNum: 100
#可选项: local, remote, pai, kubeflow, frameworkcontroller
trainingServicePlatform: frameworkcontroller
searchSpacePath: ~/nni/examples/trials/mnist/search_space.json
#可选项: true, false
useAnnotation: false
tuner:
#可选项: TPE, Random, Anneal, Evolution
builtinTunerName: TPE
classArgs:
#可选项: maximize, minimize
optimize_mode: maximize
assessor:
builtinAssessorName: Medianstop
classArgs:
optimize_mode: maximize
gpuNum: 0
trial:
codeDir: ~/nni/examples/trials/mnist
taskRoles:
- name: worker
taskNum: 1
command: python3 mnist.py
gpuNum: 1
cpuNum: 1
memoryMB: 8192
image: msranni/nni:latest
frameworkAttemptCompletionPolicy:
minFailedTaskCount: 1
minSucceededTaskCount: 1
frameworkcontrollerConfig:
storage: nfs
nfs:
server: {your_nfs_server}
path: {your_nfs_server_exported_path}
如果使用了 Azure Kubernetes Service，需要在 YAML 文件中如下设置 `frameworkcontrollerConfig`：
frameworkcontrollerConfig:
storage: azureStorage
keyVault:
vaultName: {your_vault_name}
name: {your_secert_name}
azureStorage:
accountName: {your_storage_account_name}
azureShare: {your_azure_share_name}
注意：如果用 FrameworkController 模式运行，需要在 YAML 文件中显式设置 `trainingServicePlatform: frameworkcontroller`。
FrameworkController 模式的 Trial 配置格式，是 FrameworkController 官方配置的简化版。参考 [frameworkcontroller 的 tensorflow 样例](https://github.com/Microsoft/frameworkcontroller/blob/master/example/framework/scenario/tensorflow/cpu/tensorflowdistributedtrainingwithcpu.yaml) 了解详情。
frameworkcontroller 模式中的 Trial 配置使用以下主键：
* taskRoles: 配置文件中可以设置多个任务角色，每个任务角色都是在 Kubernetes 集群中的基本执行单元。
* name: 任务角色的名字，例如，"worker", "ps", "master"。
* taskNum: 任务角色的实例数量。
* command: 在容器中要执行的用户命令。
* gpuNum: 容器要使用的 GPU 数量。
* cpuNum: 容器中要使用的 CPU 数量。
* memoryMB: 容器的内存限制。
* image: 用来创建 pod，并运行程序的 Docker 映像。
* frameworkAttemptCompletionPolicy: 运行框架的策略，参考[用户手册](https://github.com/Microsoft/frameworkcontroller/blob/master/doc/user-manual.md#frameworkattemptcompletionpolicy)了解更多信息。 这些策略可以用来控制 pod，例如，如果 worker 任务停止了，但 ps 没有停止，CompletionPolicy 策略可以停止 ps。
## 如何运行示例
准备好配置文件后，通过运行 nnictl 来启动 Experiment。 在 Frameworkcontroller 上开始 Experiment 的方法与 Kubeflow 类似，可参考[指南](./KubeflowMode.md)了解更多信息。
\ No newline at end of file
zh_CN/docs/HowToDebug.md 0 → 100644
View file @ 035d58bc
# **在 NNI 中调试代码**
*编写中……*
\ No newline at end of file
zh_CN/docs/Installation.md 0 → 100644
View file @ 035d58bc
# 安装 NNI
当前仅支持 Linux 和 Mac。
## **安装**
* **通过 pip 命令安装 NNI**
先决条件：`python >= 3.5`
```bash
python3 -m pip install --upgrade nni
```
* **通过源代码安装 NNI**
先决条件：`python >=3.5, git, wget`
```bash
git clone -b v0.5.1 https://github.com/Microsoft/nni.git
cd nni
./install.sh
```
* **在 docker 映像中安装 NNI**
也可将 NNI 安装到 docker 映像中。 参考[这里](../deployment/docker/README.md)来生成 NNI 的 Docker 映像。 也可通过此命令从 Docker Hub 中直接拉取 NNI 的映像 `docker pull msranni/nni:latest`。
## **系统需求**
以下是 NNI 在 Linux 下的最低配置。 由于程序变更，NNI 的最低配置会有所更改。
| | 最低配置 | 推荐配置 |
| -------- | ------------------------------------- | ----------------------------------------- |
| **操作系统** | Ubuntu 16.04 或以上版本 | Ubuntu 16.04 或以上版本 |
| **CPU** | Intel® Core™ i3 或 AMD Phenom™ X3 8650 | Intel® Core™ i5 或 AMD Phenom™ II X3 或更高配置 |
| **GPU** | NVIDIA® GeForce® GTX 460 | NVIDIA® GeForce® GTX 660 或更高配置 |
| **内存** | 4 GB | 6 GB |
| **存储** | 30 GB 可用的磁盘空间 | |
| **网络** | 宽带连接 | |
| **分辨率** | 1024 x 768 以上 | |
以下是 NNI 在 MacOS 下的最低配置。 由于程序变更，NNI 的最低配置会有所更改。
| | 最低配置 | 推荐配置 |
| -------- | -------------------------------------------------- | ------------------------ |
| **操作系统** | macOS 10.14.1 (最新版本) | macOS 10.14.1 (最新版本) |
| **CPU** | Intel® Core™ i5-760 或更高 | Intel® Core™ i7-4770 或更高 |
| **GPU** | NVIDIA® GeForce® GT 750M 或 AMD Radeon™ R9 M290 或更高 | AMD Radeon™ R9 M395X 或更高 |
| **内存** | 4 GB | 8 GB |
| **存储** | 70GB 可用空间及 7200 RPM 硬盘 | 70GB 可用空间 SSD 硬盘 |
| **网络** | 宽带连接 | |
| **分辨率** | 1024 x 768 以上 | |
## 更多
* [概述](Overview.md)
* [使用命令行工具 nnictl](NNICTLDOC.md)
* [使用 NNIBoard](WebUI.md)
* [定制搜索空间](SearchSpaceSpec.md)
* [配置 Experiment](ExperimentConfig.md)
* [如何在本机运行 Experiment (支持多 GPU 卡)？](tutorial_1_CR_exp_local_api.md)
* [如何在多机上运行 Experiment？](RemoteMachineMode.md)
* [如何在 OpenPAI 上运行 Experiment？](PAIMode.md)
* [如何通过 Kubeflow 在 Kubernetes 上运行 Experiment？](KubeflowMode.md)
* [如何通过 FrameworkController 在 Kubernetes 上运行 Experiment？](FrameworkControllerMode.md)
\ No newline at end of file
zh_CN/docs/KubeflowMode.md 0 → 100644
View file @ 035d58bc
# **在 Kubeflow 上运行 Experiment**
NNI 支持在 [Kubeflow](https://github.com/kubeflow/kubeflow)上运行，称为 kubeflow 模式。 在开始使用 NNI 的 kubeflow 模式前，需要有一个 kubernetes 集群，可以是私有部署的，或者是 [Azure Kubernetes Service(AKS)](https://azure.microsoft.com/en-us/services/kubernetes-service/)，并需要一台配置好 [kubeconfig](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) 的 Ubuntu 计算机连接到此 kubernetes 集群。 如果不熟悉 Kubernetes，可先浏览[这里](https://kubernetes.io/docs/tutorials/kubernetes-basics/)。 在 kubeflow 模式下，每个 Trial 程序会在 Kubernetes 集群中作为一个 kubeflow 作业来运行。
## 私有部署的 Kubernetes 的准备工作
1. 采用 Kubernetes 1.8 或更高版本。 根据[指南](https://kubernetes.io/docs/setup/)来安装 Kubernetes。
2. 在 Kubernetes 集群中下载、安装、部署 **Kubelow**。 根据[指南](https://www.kubeflow.org/docs/started/getting-started/)安装 Kubeflow。
3. 配置 **kubeconfig** 文件，NNI 将使用此配置与 Kubernetes API 服务交互。 默认情况下，NNI 管理器会使用 $(HOME)/.kube/config 作为 kubeconfig 文件的路径。 也可以通过环境变量 **KUBECONFIG** 来指定其它 kubeconfig 文件。 根据[指南](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig)了解更多 kubeconfig 的信息。
4. 如果 NNI Trial 作业需要 GPU 资源，需按照[指南](https://github.com/NVIDIA/k8s-device-plugin)来配置 **Kubernetes 下的 Nvidia 插件**。
5. 准备 **NFS 服务器** 并导出通用的装载 (mount)，推荐将 NFS 服务器路径映射到 `root_squash 选项`，否则可能会在 NNI 复制文件到 NFS 时出现权限问题。 参考[页面](https://linux.die.net/man/5/exports)，来了解关于 root_squash 选项，或 **Azure File Storage**。
6. 在安装 NNI 并运行 nnictl 的计算机上安装 **NFS 客户端**。 运行此命令安装 NFSv4 客户端：
apt-get install nfs-common
7. 参考[指南](QuickStart.md)安装 **NNI**。
## Azure 部署的 Kubernetes 的准备工作
1. NNI 支持基于 Azure Kubernetes Service 的 Kubeflow，参考[指南](https://azure.microsoft.com/en-us/services/kubernetes-service/)来设置 Azure Kubernetes Service。
2. 安装 [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest) 和 **kubectl**。 使用 `az login` 命令来设置 Azure 账户吗，并将 kubectl 客户端连接到 AKS，参考此[指南](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough#connect-to-the-cluster)。
3. 在 Azure Kubernetes Service 上部署 Kubeflow，参考此[指南](https://www.kubeflow.org/docs/started/getting-started/)。
4. 参考此[指南](https://docs.microsoft.com/en-us/azure/storage/common/storage-quickstart-create-account?tabs=portal)来创建 Azure 文件存储账户。 NNI 需要 Azure Storage Service 来存取代码和输出文件。
5. NNI 需要访问密钥来连接 Azure 存储服务，NNI 使用 [Azure Key Vault](https://azure.microsoft.com/en-us/services/key-vault/) 服务来保护私钥。 设置 Azure Key Vault 服务，并添加密钥到 Key Vault 中来存取 Azure 存储账户。 参考[指南](https://docs.microsoft.com/en-us/azure/key-vault/quick-create-cli)来存储访问密钥。
## 设计
![](./img/kubeflow_training_design.png) Kubeflow 训练服务会实例化一个 kubernetes 客户端来与 Kubernetes 集群的 API 服务器交互。
对于每个 Trial，会上传本机 codeDir 路径（在 nni_config.yml 中配置）中的所有文件，包括 parameter.cfg 这样的生成的文件到存储卷中。 当前支持两种存储卷：[nfs](https://en.wikipedia.org/wiki/Network_File_System) 和 [Azure 文件存储](https://azure.microsoft.com/en-us/services/storage/files/)，需要在 NNI 的 YAML 文件中进行配置。 当文件准备好后，Kubeflow 训练服务会调用 Kubernetes 的 API 来创建 Kubeflow 作业 ([tf-operator](https://github.com/kubeflow/tf-operator) 作业或 [pytorch-operator](https://github.com/kubeflow/pytorch-operator) 作业) ，并将存储卷挂载到作业的 pod 中。 Kubeflow 作业的输出文件，例如 stdout, stderr, trial.log 以及模型文件，也会被复制回存储卷。 NNI 会在网页中显示每个 Trial 的存储卷的 URL，以便浏览日志和输出文件。
## 支持的操作符（operator）
NNI 仅支持 kubeflow 的 tf-operator 和 pytorch-operator，其它操作符未经测试。 可以在配置文件中设置操作符类型。 这是 tf-operator 的设置：
kubeflowConfig:
operator: tf-operator
这是 pytorch-operator 的设置：
kubeflowConfig:
operator: pytorch-operator
如果要使用 tf-operator，需要在 Trial 配置中设置 `ps` 和 `worker`。如果要使用 pytorch-operator，需要在 Trial 配置中设置 `master` 和 `worker`。
## 支持的存储类型
NNI 支持使用 NFS 和 Azure 存储来存储代码和输出文件，可在配置文件进行相应的配置。
NFS 存储配置如下：
kubeflowConfig:
storage: nfs
nfs:
# NFS 服务器 IP， 如 10.10.10.10
server: {your_nfs_server_ip}
# NFS 服务器的导出路径，如 /var/nfs/nni
path: {your_nfs_server_export_path}
如果使用了 Azure 存储，需要在 YAML 文件中如下设置 `kubeflowConfig`：
kubeflowConfig:
storage: azureStorage
keyVault:
vaultName: {your_vault_name}
name: {your_secert_name}
azureStorage:
accountName: {your_storage_account_name}
azureShare: {your_azure_share_name}
## 运行 Experiment
以 `examples/trials/mnist` 为例。 这是一个 TensorFlow 作业，使用了 Kubeflow 的 tf-operator。 NNI 的 YAML 配置文件如下：
authorName: default
experimentName: example_mnist
trialConcurrency: 2
maxExecDuration: 1h
maxTrialNum: 20
#可选项: local, remote, pai, kubeflow
trainingServicePlatform: kubeflow
searchSpacePath: search_space.json
#可选项: true, false
useAnnotation: false
tuner:
#可选项: TPE, Random, Anneal, Evolution
builtinTunerName: TPE
classArgs:
#可选项: maximize, minimize
optimize_mode: maximize
assessor:
builtinAssessorName: Medianstop
classArgs:
optimize_mode: maximize
gpuNum: 0
trial:
codeDir: .
worker:
replicas: 2
command: python3 dist_mnist.py
gpuNum: 1
cpuNum: 1
memoryMB: 8196
image: msranni/nni:latest
ps:
replicas: 1
command: python3 dist_mnist.py
gpuNum: 0
cpuNum: 1
memoryMB: 8196
image: msranni/nni:latest
kubeflowConfig:
operator: tf-operator
apiVersion: v1alpha2
storage: nfs
nfs:
# NFS 服务器 IP，如 10.10.10.10
server: {your_nfs_server_ip}
# NFS 服务器的导出路径，如 /var/nfs/nni
path: {your_nfs_server_export_path}
注意：如果用 Kubeflow 模式运行，需要在 YAML 文件中显式设置 `trainingServicePlatform: kubeflow`。
如果要运行 Pytorch 作业，需要如下配置：
authorName: default
experimentName: example_mnist_distributed_pytorch
trialConcurrency: 1
maxExecDuration: 1h
maxTrialNum: 10
#可选项: local, remote, pai, kubeflow
trainingServicePlatform: kubeflow
searchSpacePath: search_space.json
#可选项: true, false
useAnnotation: false
tuner:
#可选项: TPE, Random, Anneal, Evolution
builtinTunerName: TPE
classArgs:
#可选项: maximize, minimize
optimize_mode: minimize
trial:
codeDir: .
master:
replicas: 1
command: python3 dist_mnist.py
gpuNum: 1
cpuNum: 1
memoryMB: 2048
image: msranni/nni:latest
worker:
replicas: 1
command: python3 dist_mnist.py
gpuNum: 0
cpuNum: 1
memoryMB: 2048
image: msranni/nni:latest
kubeflowConfig:
operator: pytorch-operator
apiVersion: v1alpha2
nfs:
# NFS 服务器 IP，如 10.10.10.10
server: {your_nfs_server_ip}
# NFS 服务器导出路径，如 /var/nfs/nni
path: {your_nfs_server_export_path}
Kubeflow 模式的配置有下列主键：
* codeDir
* 代码目录，存放训练代码和配置文件
* worker (必填)。 此部分用于配置 TensorFlow 的 worker 角色
* replicas
* 必填。 需要运行的 TensorFlow woker 角色的数量，必须为正数。
* command
* 必填。 用来运行 Trial 作业的命令，例如： ```python mnist.py```
* memoryMB
* 必填。 Trial 程序的内存需求，必须为正数。
* cpuNum
* gpuNum
* image
* 必填。 在 kubeflow 模式中，Kubernetes 会安排 Trial 程序在 [Pod](https://kubernetes.io/docs/concepts/workloads/pods/pod/) 中执行。 此键用来指定 Trial 程序的 pod 使用的 Docker 映像。
* [Docker Hub](https://hub.docker.com/) 上有预制的 NNI Docker 映像 [msranni/nni](https://hub.docker.com/r/msranni/nni/)。 它包含了用来启动 NNI Experiment 所依赖的所有 Python 包，Node 模块和 JavaScript。 生成此 Docker 映像的文件在[这里](https://github.com/Microsoft/nni/tree/master/deployment/Dockerfile.build.base)。 可以直接使用此映像，或参考它来生成自己的映像。
* apiVersion
* 必填。 Kubeflow 的 API 版本。
* ps (可选)。 此部分用于配置 TensorFlow 的 parameter 服务器角色。
* master (可选)。 此部分用于配置 PyTorch 的 parameter 服务器角色。
完成并保存 NNI Experiment 配置文件后（例如可保存为：exp_kubeflow.yml），运行以下命令：
nnictl create --config exp_kubeflow.yml
来在 Kubeflow 模式下启动 Experiment。 NNI 会为每个 Trial 创建 Kubeflow tfjob 或 pytorchjob，作业名称的格式为 `nni_exp_{experiment_id}_trial_{trial_id}`。 可以在 Kubernetes 面板中看到创建的 Kubeflow tfjob。
注意：Kubeflow 模式下，NNIManager 会启动 RESTful 服务，监听端口为 NNI 网页服务器的端口加1。 例如，如果网页端口为`8080`，那么 RESTful 服务器会监听在 `8081`端口，来接收运行在 Kubernetes 中的 Trial 作业的指标。 因此，需要在防火墙中启用端口 `8081` 的 TCP 协议，以允许传入流量。
当一个 Trial 作业完成后，可以在 NNI 网页的概述页面（如：http://localhost:8080/oview）中查看 Trial 的信息。
如果在使用 Kubeflow 模式时遇到任何问题，请到 [NNI Github](https://github.com/Microsoft/nni) 中创建问题。
\ No newline at end of file
zh_CN/docs/Makefile 0 → 100644
View file @ 035d58bc
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
zh_CN/docs/NNICTLDOC.md 0 → 100644
View file @ 035d58bc
# nnictl
## 介绍
**nnictl** 是一个命令行工具，用来控制 NNI Experiment，如启动、停止、继续 Experiment，启动、停止 NNIBoard 等等。
## 命令
nnictl 支持的命令：
* [nnictl create](#create)
* [nnictl resume](#resume)
* [nnictl stop](#stop)
* [nnictl update](#update)
* [nnictl trial](#trial)
* [nnictl top](#top)
* [nnictl experiment show](#experiment)
* [nnictl config](#config)
* [nnictl log](#log)
* [nnictl webui](#webui)
* [nnictl tensorboard](#tensorboard)
* [nnictl package](#package)
* [nnictl --version](#version)
### 管理 Experiment
<a name="create"></a>
* **nnictl create**
* 说明
此命令使用参数中的配置文件，来创建新的 Experiment。
此命令成功完成后，上下文会被设置为此 Experiment。这意味着如果不显式改变上下文（暂不支持），输入的以下命令，都作用于此 Experiment。
* 用法
```bash
nnictl create [OPTIONS]
```
* 选项
| 参数及缩写 | 是否必需 | 默认值 | 说明 |
| ------------ | ----- | --- | ---------------------- |
| --config, -c | True | | Experiment 的 YAML 配置文件 |
| --port, -p | False | | RESTful 服务的端口 |
<a name="resume"></a>
* **nnictl resume**
* 说明
使用此命令恢复已停止的 Experiment。
* 用法
```bash
nnictl resume [OPTIONS]
```
* 选项
| 参数及缩写 | 是否必需 | 默认值 | 说明 |
| ---------- | ----- | --- | -------------------------------- |
| id | False | | 要恢复的 Experiment 标识 |
| --port, -p | False | | 要恢复的 Experiment 使用的 RESTful 服务端口 |
<a name="stop"></a>
* **nnictl stop**
* 说明
使用此命令来停止正在运行的单个或多个 Experiment。
* 用法
```bash
nnictl stop [id]
```
* 详细说明
1. 如果指定了 id，并且此 id 匹配正在运行的 Experiment，nnictl 会停止相应的 Experiment，否则会输出错误信息。
2. 如果没有指定 id，并且当前有运行的 Experiment，则会停止该 Experiment，否则会输出错误信息。
3. 如果 id 以 * 结尾，nnictl 会停止所有匹配此通配符的 Experiment。
4. 如果 id 不存在，但匹配了某个Experiment 的 id 前缀，nnictl 会停止匹配的Experiment 。
5. 如果 id 不存在，但匹配多个 Experiment id 的前缀，nnictl 会输出这些 id 的信息。
6. 可使用 'nnictl stop all' 来停止所有的 Experiment。
<a name="update"></a>
* **nnictl update**
* **nnictl update searchspace**
* 说明
可以用此命令来更新 Experiment 的搜索空间。
* 用法
```bash
nnictl update searchspace [OPTIONS]
```
* 选项
| 参数及缩写 | 是否必需 | 默认值 | 说明 |
| -------------- | ----- | --- | --------------------- |
| id | False | | 需要设置的 Experiment 的 id |
| --filename, -f | True | | 新的搜索空间文件名 |
* **nnictl update concurrency**
* 说明
可以用此命令来更新 Experiment 的并发设置。
* 用法
```bash
nnictl update concurrency [OPTIONS]
```
* 选项
| 参数及缩写 | 是否必需 | 默认值 | 说明 |
| ----------- | ----- | --- | --------------------- |
| id | False | | 需要设置的 Experiment 的 id |
| --value, -v | True | | 允许同时运行的 Trial 的数量 |
* **nnictl update duration**
* 说明
可以用此命令来更新 Experiment 的运行时间。
* 用法
```bash
nnictl update duration [OPTIONS]
```
* 选项
| 参数及缩写 | 是否必需 | 默认值 | 说明 |
| ----------- | ----- | --- | ----------------------------------------------------------------------- |
| id | False | | 需要设置的 Experiment 的 id |
| --value, -v | True | | Experiment 持续时间如没有单位，则为秒。 后缀可以为 's' 即秒 (默认值), 'm' 即分钟, 'h' 即小时或 'd' 即天。 |
* **nnictl update trialnum**
* 说明
可以用此命令来更新 Experiment 的最大 Trial 数量。
* 用法
```bash
nnictl update trialnum [OPTIONS]
```
* 选项
| 参数及缩写 | 是否必需 | 默认值 | 说明 |
| ----------- | ----- | --- | --------------------- |
| id | False | | 需要设置的 Experiment 的 id |
| --value, -v | True | | 需要设置的 maxtrialnum 的数量 |
<a name="trial"></a>
* **nnictl trial**
* **nnictl trial ls**
* 说明
使用此命令来查看 Trial 的信息。
* 用法
```bash
nnictl trial ls
```
* 选项
| 参数及缩写 | 是否必需 | 默认值 | 说明 |
| ----- | ----- | --- | --------------------- |
| id | False | | 需要设置的 Experiment 的 id |
* **nnictl trial kill**
* 说明
此命令用于终止 Trial。
* 用法
```bash
nnictl trial kill [OPTIONS]
```
* 选项
| 参数及缩写 | 是否必需 | 默认值 | 说明 |
| ------------- | ----- | --- | --------------------- |
| id | False | | 需要设置的 Experiment 的 id |
| --trialid, -t | True | | 需要终止的 Trial 的 id。 |
<a name="top"></a>
* **nnictl top**
* 说明
查看正在运行的 Experiment。
* 用法
```bash
nnictl top
```
* 选项
| 参数及缩写 | 是否必需 | 默认值 | 说明 |
| ---------- | ----- | --- | ------------------------------------ |
| id | False | | 需要设置的 Experiment 的 id |
| --time, -t | False | | 刷新 Experiment 状态的时间间隔，单位为秒，默认值为 3 秒。 |
<a name="experiment"></a>
### 管理 Experiment 信息
* **nnictl experiment show**
* 说明
显示 Experiment 的信息。
* 用法
```bash
nnictl experiment show
```
* 选项
| 参数及缩写 | 是否必需 | 默认值 | 说明 |
| ----- | ----- | --- | --------------------- |
| id | False | | 需要设置的 Experiment 的 id |
* **nnictl experiment status**
* 说明
显示 Experiment 的状态。
* 用法
```bash
nnictl experiment status
```
* 选项
| 参数及缩写 | 是否必需 | 默认值 | 说明 |
| ----- | ----- | --- | --------------------- |
| id | False | | 需要设置的 Experiment 的 id |
* **nnictl experiment list**
* 说明
显示正在运行的 Experiment 的信息
* 用法
```bash
nnictl experiment list
```
<a name="config"></a>
* **nnictl config show**
* 说明
显示当前上下文信息。
* 用法
```bash
nnictl config show
```
<a name="log"></a>
### 管理日志
* **nnictl log stdout**
* 说明
显示 stdout 日志内容。
* 用法
```bash
nnictl log stdout [options]
```
* 选项
| 参数及缩写 | 是否必需 | 默认值 | 说明 |
| ---------- | ----- | --- | --------------------- |
| id | False | | 需要设置的 Experiment 的 id |
| --head, -h | False | | 显示 stdout 开始的若干行 |
| --tail, -t | False | | 显示 stdout 结尾的若干行 |
| --path, -p | False | | 显示 stdout 文件的路径 |
* **nnictl log stderr**
* 说明
显示 stderr 日志内容。
* 用法
```bash
nnictl log stderr [options]
```
* 选项
| 参数及缩写 | 是否必需 | 默认值 | 说明 |
| ---------- | ----- | --- | --------------------- |
| id | False | | 需要设置的 Experiment 的 id |
| --head, -h | False | | 显示 stderr 开始的若干行 |
| --tail, -t | False | | 显示 stderr 结尾的若干行 |
| --path, -p | False | | 显示 stderr 文件的路径 |
* **nnictl log trial**
* 说明
显示 Trial 日志的路径。
* 用法
```bash
nnictl log trial [options]
```
* 选项
| 参数及缩写 | 是否必需 | 默认值 | 说明 |
| ----- | ----- | --- | ---------- |
| id | False | | Trial 的 id |
<a name="webui"></a>
### 管理网页
* **nnictl webui url**
<a name="tensorboard"></a>
### 管理 tensorboard
* **nnictl tensorboard start**
* 说明
启动 tensorboard 进程。
* 用法
```bash
nnictl tensorboard start
```
* 选项
| 参数及缩写 | 是否必需 | 默认值 | 说明 |
| --------- | ----- | ---- | --------------------- |
| id | False | | 需要设置的 Experiment 的 id |
| --trialid | False | | Trial 的 id |
| --port | False | 6006 | tensorboard 进程的端口 |
* 详细说明
1. NNICTL 当前仅支持本机和远程平台的 tensorboard，其它平台暂不支持。
2. 如果要使用 tensorboard，需要将 tensorboard 日志输出到环境变量 [NNI_OUTPUT_DIR] 路径下。
3. 在 local 模式中，nnictl 会直接设置 --logdir=[NNI_OUTPUT_DIR] 并启动 tensorboard 进程。
4. 在 remote 模式中，nnictl 会创建一个 ssh 客户端来将日志数据从远程计算机复制到本机临时目录中，然后在本机开始 tensorboard 进程。 需要注意的是，nnictl 只在使用此命令时复制日志数据，如果要查看最新的 tensorboard 结果，需要再次执行 nnictl tensorboard 命令。
5. 如果只有一个 Trial 任务，不需要设置 trialid。 如果有多个运行的 Trial 作业，需要设置 trialid，或使用 [nnictl tensorboard start --trialid all] 来将 --logdir 映射到所有 Trial 的路径。
* **nnictl tensorboard stop**
* 说明
停止所有 tensorboard 进程。
* 用法
```bash
nnictl tensorboard stop
```
* 选项
| 参数及缩写 | 是否必需 | 默认值 | 说明 |
| ----- | ----- | --- | ----------- |
| id | False | | 需要设置的实验的 id |
<a name="package"></a>
### 管理安装包
* **nnictl package install**
* 说明
安装 NNI 实验所需要的包。
* 用法
```bash
nnictl package install [OPTIONS]
```
* 选项
| 参数及缩写 | 是否必需 | 默认值 | 说明 |
| ------ | ---- | --- | ------- |
| --name | True | | 要安装的包名称 |
* **nnictl package show**
* 说明
列出支持的安装包
* 用法
```bash
nnictl package show
```
<a name="version"></a>
### 检查 NNI 版本
* **nnictl --version**
* 说明
显示当前安装的 NNI 的版本。
* 用法
```bash
nnictl --version
```
\ No newline at end of file
zh_CN/docs/Overview.md 0 → 100644
View file @ 035d58bc
# 概述
NNI (Neural Network Intelligence) 是一个工具包，可有效的帮助用户设计并调优机器学习模型的神经网络架构，复杂系统的参数（如超参）等。 NNI 的特性包括：易于使用，可扩展，灵活，高效。
* **易于使用**：NNI 可通过 pip 安装。 只需要在代码中添加几行，就可以利用 NNI 来调优参数。 可使用命令行工具或 Web 界面来查看实验过程。
* **可扩展**：调优超参或网络结构通常需要大量的计算资源。NNI 在设计时就支持了多种不同的计算资源，如远程服务器组，训练平台（如：OpenPAI，Kubernetes），等等。 通过训练平台，可拥有同时运行数百个 Trial 的能力。
* **灵活**：除了内置的算法，NNI 中还可以轻松集成自定义的超参调优算法，神经网络架构搜索算法，提前终止算法等等。 还可以将 NNI 连接到更多的训练平台上，如云中的虚拟机集群，Kubernetes 服务等等。 此外，NNI 还可以连接到外部环境中的特殊应用和模型上。
* **高效**：NNI 在系统及算法级别上不停的优化。 例如：通过 Trial 早期的反馈来加速调优过程。
下图显示了 NNI 的体系结构。
<p align="center">
<img src="https://user-images.githubusercontent.com/23273522/51816536-ed055580-2301-11e9-8ad8-605a79ee1b9a.png" alt="drawing" width="700"/>
</p>
## 主要概念
* *Experiment（实验）*：实验是一次找到模型的最佳超参组合，或最好的神经网络架构的任务。 它由 Trial 和自动机器学习算法所组成。
* *搜索空间*：是模型调优的范围。 例如，超参的取值范围。
* *Configuration（配置）*：配置是来自搜索空间的一个参数实例，每个超参都会有一个特定的值。
* *Trial*: Trial 是一次尝试，它会使用某组配置（例如，一组超参值，或者特定的神经网络架构）。 Trial 会基于提供的配置来运行。
* *Tuner*: Tuner 是一个自动机器学习算法，会为下一个 Trial 生成新的配置。 新的 Trial 会使用这组配置来运行。
* *Assessor*：Assessor 分析 Trial 的中间结果（例如，测试数据集上定期的精度），来确定 Trial 是否应该被提前终止。
* *训练平台*：是 Trial 的执行环境。 根据 Experiment 的配置，可以是本机，远程服务器组，或其它大规模训练平台（如，OpenPAI，Kubernetes）。
Experiment 的运行过程为：Tuner 接收搜索空间并生成配置。 这些配置将被提交到训练平台，如本机，远程服务器组或训练集群。 执行的性能结果会被返回给 Tuner。 然后，再生成并提交新的配置。
每次 Experiment 执行时，用户只需要定义搜索空间，改动几行代码，就能利用 NNI 内置的 Tuner/Assessor 和训练服务来搜索最好的超参组合以及神经网络结构。 基本上分为三步：
> 第一步：[定义搜索空间](SearchSpaceSpec.md)
>
> 第二步：[改动模型代码](Trials.md)
>
> 第三步：[定义 Experiment 配置](ExperimentConfig.md)
<p align="center">
<img src="https://user-images.githubusercontent.com/23273522/51816627-5d13db80-2302-11e9-8f3e-627e260203d5.jpg" alt="drawing"/>
</p>
更多 Experiment 运行的详情，参考[快速入门](QuickStart.md)。
## 了解更多信息
* [开始使用](QuickStart.md)
* [如何为 NNI 调整代码？](Trials.md)
* [NNI 支持哪些 Tuner？](Builtin_Tuner.md)
* [如何自定义 Tuner？](Customize_Tuner.md)
* [NNI 支持哪些 Assessor？](Builtin_Assessors.md)
* [如何自定义 Assessor？](Customize_Assessor.md)
* [如何在本机上运行 Experiment？](tutorial_1_CR_exp_local_api.md)
* [如何在多机上运行 Experiment？](RemoteMachineMode.md)
* [如何在 OpenPAI 上运行 Experiment？](PAIMode.md)
* [样例](mnist_examples.md)
\ No newline at end of file
zh_CN/docs/PAIMode.md 0 → 100644
View file @ 035d58bc
# **在 OpenPAI 上运行 Experiment**
NNI 支持在 [OpenPAI](https://github.com/Microsoft/pai) （简称 pai）上运行 Experiment，即 pai 模式。 在使用 NNI 的 pai 模式前, 需要有 [OpenPAI](https://github.com/Microsoft/pai) 群集的账户。 如果没有 OpenPAI 账户，参考[这里](https://github.com/Microsoft/pai#how-to-deploy)来进行部署。 在 pai 模式中，会在 Docker 创建的容器中运行 Trial 程序。
## 设置环境
参考[指南](QuickStart.md)安装 NNI。
## 运行 Experiment
以 `examples/trials/mnist-annotation` 为例。 NNI 的 YAML 配置文件如下：
```yaml
authorName: your_name
experimentName: auto_mnist
# 并发运行的 Trial 数量
trialConcurrency: 2
# Experiment 的最长持续运行时间
maxExecDuration: 3h
# 空表示一直运行
maxTrialNum: 100
# 可选项: local, remote, pai
trainingServicePlatform: pai
# 可选项: true, false
useAnnotation: true
tuner:
builtinTunerName: TPE
classArgs:
optimize_mode: maximize
trial:
command: python3 mnist.py
codeDir: ~/nni/examples/trials/mnist-annotation
gpuNum: 0
cpuNum: 1
memoryMB: 8196
image: openpai/pai.example.tensorflow
dataDir: hdfs://10.1.1.1:9000/nni
outputDir: hdfs://10.1.1.1:9000/nni
# 配置访问的 OpenPAI 集群
paiConfig:
userName: your_pai_nni_user
passWord: your_pai_password
host: 10.1.1.1
```
注意：如果用 pai 模式运行，需要在 YAML 文件中设置 `trainingServicePlatform: pai`。
与本机模式，以及[远程计算机模式](RemoteMachineMode.md)相比，pai 模式的 Trial 有额外的配置：
* cpuNum
* 必填。 Trial 程序的 CPU 需求，必须为正数。
* memoryMB
* 必填。 Trial 程序的内存需求，必须为正数。
* image
* 必填。 在 pai 模式中，Trial 程序由 OpenPAI 在 [Docker 容器](https://www.docker.com/)中安排运行。 此键用来指定 Trial 程序的容器使用的 Docker 映像。
* [Docker Hub](https://hub.docker.com/) 上有预制的 NNI Docker 映像 [nnimsra/nni](https://hub.docker.com/r/msranni/nni/)。 它包含了用来启动 NNI Experiment 所依赖的所有 Python 包，Node 模块和 JavaScript。 生成此 Docker 映像的文件在[这里](https://github.com/Microsoft/nni/tree/master/deployment/Dockerfile.build.base)。 可以直接使用此映像，或参考它来生成自己的映像。
* dataDir
* 可选。 指定了 Trial 用于下载数据的 HDFS 数据目录。 格式应为 hdfs://{your HDFS host}:9000/{数据目录}
* outputDir
* 可选。 指定了 Trial 的 HDFS 输出目录。 Trial 在完成（成功或失败）后，Trial 的 stdout， stderr 会被 NNI 自动复制到此目录中。 格式应为 hdfs://{your HDFS host}:9000/{输出目录}
完成并保存 NNI Experiment 配置文件后（例如可保存为：exp_pai.yml），运行以下命令：
nnictl create --config exp_pai.yml
来在 pai 模式下启动 Experiment。 NNI 会为每个 Trial 创建 OpenPAI 作业，作业名称的格式为 `nni_exp_{experiment_id}_trial_{trial_id}`。 可以在 OpenPAI 集群的网站中看到 NNI 创建的作业，例如： ![](./img/nni_pai_joblist.jpg)
注意：pai 模式下，NNIManager 会启动 RESTful 服务，监听端口为 NNI 网页服务器的端口加1。 例如，如果网页端口为`8080`，那么 RESTful 服务器会监听在 `8081`端口，来接收运行在 Kubernetes 中的 Trial 作业的指标。 因此，需要在防火墙中启用端口 `8081` 的 TCP 协议，以允许传入流量。
当一个 Trial 作业完成后，可以在 NNI 网页的概述页面（如：http://localhost:8080/oview）中查看 Trial 的信息。
在 Trial 列表页面中展开 Trial 信息，点击如下的 logPath： ![](./img/nni_webui_joblist.jpg)
接着将会打开 HDFS 的 WEB 界面，并浏览到 Trial 的输出文件： ![](./img/nni_trial_hdfs_output.jpg)
在输出目录中可以看到三个文件：stderr, stdout, 以及 trial.log
如果希望将 Trial 的模型数据等其它输出保存到HDFS中，可在 Trial 代码中使用 `NNI_OUTPUT_DIR` 来自己保存输出文件，NNI SDK会从 Trial 的容器中将 `NNI_OUTPUT_DIR` 中的文件复制到 HDFS 中。
如果在使用 pai 模式时遇到任何问题，请到 [NNI Github](https://github.com/Microsoft/nni) 中创建问题。
\ No newline at end of file
zh_CN/docs/QuickStart.md 0 → 100644
View file @ 035d58bc
# 快速入门
## 安装
当前支持 Linux 和 MacOS。测试并支持的版本包括：Ubuntu 16.04 及更高版本，MacOS 10.14.1。 在 `python >= 3.5` 的环境中，只需要运行 `pip install` 即可完成安装。
```bash
python3 -m pip install --upgrade nni
```
注意：
* 如果需要将 NNI 安装到自己的 home 目录中，可使用 `--user`，这样也不需要任何特殊权限。
* 如果遇到如`Segmentation fault` 这样的任何错误请参考[常见问题](FAQ.md)。
* 参考[安装 NNI](Installation.md)，来了解`系统需求`。
## MNIST 上的 "Hello World"
NNI 是一个能进行自动机器学习实验的工具包。 它可以自动进行获取超参、运行 Trial，测试结果，调优超参的循环。 下面会展示如何使用 NNI 来找到最佳超参组合。
这是还**没有 NNI** 的样例代码，用 CNN 在 MNIST 数据集上训练：
```python
def run_trial(params):
# 输入数据
mnist = input_data.read_data_sets(params['data_dir'], one_hot=True)
# 构建网络
mnist_network = MnistNetwork(channel_1_num=params['channel_1_num'], channel_2_num=params['channel_2_num'], conv_size=params['conv_size'], hidden_size=params['hidden_size'], pool_size=params['pool_size'], learning_rate=params['learning_rate'])
mnist_network.build_network()
test_acc = 0.0
with tf.Session() as sess:
# 训练网络
mnist_network.train(sess, mnist)
# 评估网络
test_acc = mnist_network.evaluate(mnist)
if __name__ == '__main__':
params = {'data_dir': '/tmp/tensorflow/mnist/input_data', 'dropout_rate': 0.5, 'channel_1_num': 32, 'channel_2_num': 64, 'conv_size': 5, 'pool_size': 2, 'hidden_size': 1024, 'learning_rate': 1e-4, 'batch_num': 2000, 'batch_size': 32}
run_trial(params)
```
注意：完整实现请参考 [examples/trials/mnist/mnist_before.py](https://github.com/Microsoft/nni/tree/master/examples/trials/mnist/mnist_before.py)
上面的代码一次只能尝试一组参数，如果想要调优学习率，需要手工改动超参，并一次次尝试。
NNI 就是用来帮助调优工作的。它的工作流程如下：
输入: 搜索空间, Trial 代码, 配置文件
输出: 一组最佳的超参配置
1: For t = 0, 1, 2, ..., maxTrialNum,
2: hyperparameter = 从搜索空间选择一组参数
3: final result = run_trial_and_evaluate(hyperparameter)
4: 返回最终结果给 NNI
5: If 时间达到上限,
6: 停止实验
7: return 最好的实验结果
如果需要使用 NNI 来自动训练模型，找到最佳超参，需要如下三步：
**使用 NNI 时的三个步骤**
**第一步**：定义 JSON 格式的`搜索空间`文件，包括所有需要搜索的超参的`名称`和`分布`（离散和连续值均可）。
```diff
- params = {'data_dir': '/tmp/tensorflow/mnist/input_data', 'dropout_rate': 0.5, 'channel_1_num': 32, 'channel_2_num': 64,
- 'conv_size': 5, 'pool_size': 2, 'hidden_size': 1024, 'learning_rate': 1e-4, 'batch_num': 2000, 'batch_size': 32}
+ {
+ "dropout_rate":{"_type":"uniform","_value":[0.5, 0.9]},
+ "conv_size":{"_type":"choice","_value":[2,3,5,7]},
+ "hidden_size":{"_type":"choice","_value":[124, 512, 1024]},
+ "batch_size": {"_type":"choice", "_value": [1, 4, 8, 16, 32]},
+ "learning_rate":{"_type":"choice","_value":[0.0001, 0.001, 0.01, 0.1]}
+ }
```
*实现代码：[search_space.json](https://github.com/Microsoft/nni/tree/master/examples/trials/mnist/search_space.json)*
**第二步**：修改 `Trial` 代码来从 NNI 获取超参，并返回 NNI 最终结果。
```diff
+ import nni
def run_trial(params):
mnist = input_data.read_data_sets(params['data_dir'], one_hot=True)
mnist_network = MnistNetwork(channel_1_num=params['channel_1_num'], channel_2_num=params['channel_2_num'], conv_size=params['conv_size'], hidden_size=params['hidden_size'], pool_size=params['pool_size'], learning_rate=params['learning_rate'])
mnist_network.build_network()
with tf.Session() as sess:
mnist_network.train(sess, mnist)
test_acc = mnist_network.evaluate(mnist)
+ nni.report_final_result(acc)
if __name__ == '__main__':
- params = {'data_dir': '/tmp/tensorflow/mnist/input_data', 'dropout_rate': 0.5, 'channel_1_num': 32, 'channel_2_num': 64,
- 'conv_size': 5, 'pool_size': 2, 'hidden_size': 1024, 'learning_rate': 1e-4, 'batch_num': 2000, 'batch_size': 32}
+ params = nni.get_next_parameter()
run_trial(params)
```
*实现代码：[mnist.py](https://github.com/Microsoft/nni/tree/master/examples/trials/mnist/mnist.py)*
**第三步**：定义 YAML 格式的`配置`文件，其中声明了搜索空间和 Trial 文件的`路径`，以及`其它信息`，如调优算法，最大尝试次数，最大运行时间等等。
```yaml
authorName: default
experimentName: example_mnist
trialConcurrency: 1
maxExecDuration: 1h
maxTrialNum: 10
trainingServicePlatform: local
# 搜索空间文件
searchSpacePath: search_space.json
useAnnotation: false
tuner:
builtinTunerName: TPE
# 运行的命令，以及 Trial 代码的路径
trial:
command: python3 mnist.py
codeDir: .
gpuNum: 0
```
*实现代码：[config.yml](https://github.com/Microsoft/nni/tree/master/examples/trials/mnist/config.yml)*
上面的代码都已准备好，并保存在 [examples/trials/mnist/](https://github.com/Microsoft/nni/tree/master/examples/trials/mnist)。
上述步骤完成后，**从命令行运行 config.yml 文件来开始 Experiment**。
```bash
nnictl create --config nni/examples/trials/mnist/config.yml
```
注意：**nnictl** 是一个命令行工具，用来控制 NNI Experiment，如启动、停止、继续 Experiment，启动、停止 NNIBoard 等等。 查看[这里](NNICTLDOC.md)，了解 `nnictl` 更多用法。
在命令行中等待输出 `INFO: Successfully started experiment!`。 此消息表明 Experiment 已成功启动。 期望的输出如下：
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 的进度。
## Web 界面
启动 Experiment 后，可以在命令行界面找到如下的 `Web 界面地址`：
The Web UI urls are: [IP 地址]:8080
在浏览器中打开 `Web 界面地址`(即：`[IP 地址]:8080`)，就可以看到 Experiment 的详细信息，以及所有的 Trial 任务。
#### 查看概要页面
点击标签 "Overview"。
Experiment 相关信息会显示在界面上，配置和搜索空间等。 可通过 **Download** 按钮来`下载信息和参数`。 可以在运行中或结束后，随时下载 Experiment 的结果。
![](./img/QuickStart1.png)
前 10 个 Trial 结果也会列在 Overview 页面中，可以在 "Trials Detail" 部分浏览所有的 Trial。
![](./img/QuickStart2.png)
#### 查看 Trial 详情页面
点击 "Default Metric" 来查看所有 Trial 的点图。 悬停鼠标来查看默认指标和搜索空间信息。
![](./img/QuickStart3.png)
点击 "Hyper Parameter" 标签查看图像。
* 可选择百分比查看最好的 Trial。
* 选择两个轴来交换位置。
![](./img/QuickStart4.png)
点击 "Trial Duration" 标签来查看柱状图。
![](./img/QuickStart5.png)
下面是所有 Trial 的状态。 包括：
* Trial 详情：Trial 的 id，持续时间，开始时间，结束时间，状态，精度和搜索空间。
* 如果在 OpenPAI 平台上运行，还可以看到 hdfsLog。
* Kill: 可终止正在运行的任务。
* 支持搜索某个特定的 Trial。
![](./img/QuickStart6.png)
* 中间结果图
![](./img/QuickStart7.png)
## 相关主题
* [尝试不同的 Tuner](Builtin_Tuner.md)
* [尝试不同的 Assessor](Builtin_Assessors.md)
* [使用命令行工具 nnictl](NNICTLDOC.md)
* [如何编写 Trial 代码](Trials.md)
* [如何在本机运行 Experiment (支持多 GPU 卡)？](tutorial_1_CR_exp_local_api.md)
* [如何在多机上运行 Experiment？](RemoteMachineMode.md)
* [如何在 OpenPAI 上运行 Experiment？](PAIMode.md)
* [如何通过 Kubeflow 在 Kubernetes 上运行 Experiment？](KubeflowMode.md)
* [如何通过 FrameworkController 在 Kubernetes 上运行 Experiment？](FrameworkControllerMode.md)
\ No newline at end of file
zh_CN/docs/RELEASE.md 0 → 100644
View file @ 035d58bc
# 更改日志
## 发布 0.5.1 - 1/31/2018
### 改进
* 可配置[日志目录](ExperimentConfig.md)。
* 支持[不同级别的日志](ExperimentConfig.md)，使其更易于调试。
### 文档
* 重新组织文档，新的主页位置：https://nni.readthedocs.io/en/latest/
### Bug 修复和其它更新
* 修复了 Python 虚拟环境中安装的 Bug，并重构了安装逻辑。
* 修复了在最新的 OpenPAI 下存取 HDFS 失败的问题。
* 修复了有时刷新 stdout 会造成 Experiment 崩溃的问题。
## 发布 0.5.0 - 01/14/2019
### 主要功能
#### 支持新的 Tuner 和 Assessor
* 支持[Metis tuner](./Builtin_Tuner.md#MetisTuner) 作为 NNI 的 Tuner。 **在线**超参调优的场景下，Metis 算法已经被证明非常有效。
* 支持 [ENAS customized tuner](https://github.com/countif/enas_nni)。由 GitHub 社区用户所贡献。它是神经网络的搜索算法，能够通过强化学习来学习神经网络架构，比 NAS 的性能更好。
* 支持 [Curve fitting （曲线拟合）Assessor](./Builtin_Tuner.md#Curvefitting)，通过曲线拟合的策略来实现提前终止 Trial。
* 进一步支持 [Weight Sharing（权重共享）](./AdvancedNAS.md)：为 NAS Tuner 通过 NFS 来提供权重共享。
#### 改进训练平台
* [FrameworkController 训练服务](./FrameworkControllerMode.md): 支持使用在 Kubernetes 上使用 FrameworkController。
* FrameworkController 是 Kubernetes 上非常通用的控制器（Controller），能用来运行基于各种机器学习框架的分布式作业，如 TensorFlow，Pytorch， MXNet 等。
* NNI 为作业定义了统一而简单的规范。
* 如何使用 FrameworkController 的 MNIST 样例。
#### 改进用户体验
* 为 OpenPAI, Kubeflow 和 FrameworkController 模式提供更好的日志支持。
* 改进后的日志架构能将尝试的 stdout/stderr 通过 HTTP POST 方式发送给 NNI 管理器。 NNI 管理器将 Trial 的 stdout/stderr 消息存储在本地日志文件中。
* 在 WEB 界面上显示 Trial 日志的链接。
* 支持将最终结果显示为键值对。
## 发布 0.4.1 - 12/14/2018
### 主要功能
#### 支持新的 Tuner
* 支持新 Tuner [network morphism](./Builtin_Tuner.md#NetworkMorphism)
#### 改进训练平台
* 将[Kubeflow 训练服务](KubeflowMode.md)的依赖从 kubectl CLI 迁移到 [Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/) 客户端。
* Kubeflow 训练服务支持 [Pytorch-operator](https://github.com/kubeflow/pytorch-operator)。
* 改进将本地代码文件上传到 OpenPAI HDFS 的性能。
* 修复 OpenPAI 在 WEB 界面的 Bug：当 OpenPAI 认证过期后，Web 界面无法更新 Trial 作业的状态。
#### 改进 NNICTL
* 在 nnictl 和 WEB 界面中显示 NNI 的版本信息。 可使用 **nnictl -v** 来显示安装的 NNI 版本。
#### 改进 WEB 界面
* 在 Experiment 运行中可修改并发数量
* 增加指向 NNI Github 的反馈链接，可直接创建问题
* 可根据指标，定制选择（最大或最小）的前 10 个 Trial。
* 为 dispatcher 和 nnimanager 提供下载日志的功能
* 为指标数值图提供自动缩放的数轴
* 改进 Annotation，支持在搜索空间中显示实际的选项
### 新样例
* [FashionMnist](https://github.com/Microsoft/nni/tree/master/examples/trials/network_morphism)，使用 network morphism Tuner
* 使用 PyTorch 的[分布式 MNIST 样例](https://github.com/Microsoft/nni/tree/master/examples/trials/mnist-distributed-pytorch)
## 发布 0.4 - 12/6/2018
### 主要功能
* [Kubeflow 训练服务](./KubeflowMode.md)
* 支持 tf-operator
* 使用 Kubeflow 的[分布式 Trial 样例](https://github.com/Microsoft/nni/tree/master/examples/trials/mnist-distributed/dist_mnist.py)
* [网格搜索 Tuner](Builtin_Tuner.md#GridSearch)
* [Hyperband Tuner](Builtin_Tuner.md#Hyperband)
* 支持在 MAC 上运行 NNI Experiment
* Web 界面
* 支持 hyperband Tuner
* 移除 tensorboard 按钮
* 显示 Experiment 的错误消息
* 显示搜索空间和 Trial 配置的行号
* 支持通过指定的 Trial id 来搜索
* 显示 Trial 的 hdfsLogPath
* 下载 Experiment 参数
### 其它
* 异步调度
* 更新 Docker 文件，增加 pytorch 库
* 重构 'nnictl stop' 过程，发送 SIGTERM 给 NNI 管理器进程，而不是调用停止 Restful API.
* 修复 OpenPAI 训练服务的 Bug
* 在 NNI 管理器中为 OpenPAI 集群配置文件支持 IP 配置(nniManagerIp)，来修复用户计算机没有 eth0 设备的问题。
* codeDir 中的文件数量上限改为1000，避免用户无意中填写了 root 目录。
* 移除 OpenPAI 作业的 stdout 日志中无用的 ‘metrics is empty’。 在新指标被记录时，仅输出有用的消息，来减少用户检查 OpenPAI Trial 输出时的困惑。
* 在 Trial keeper 的开始增加时间戳。
## 发布 0.3.0 - 11/2/2018
### NNICTL 的新功能和更新
* 支持同时运行多个 Experiment。
在 v0.3 以前，NNI 仅支持一次运行一个 Experiment。 此版本开始，用户可以同时运行多个 Experiment。 每个 Experiment 都需要一个唯一的端口，第一个 Experiment 会像以前版本一样使用默认端口。 需要为其它 Experiment 指定唯一端口：
```bash
nnictl create --port 8081 --config <config file path>
```
* 支持更新最大 Trial 的数量。 使用 `nnictl update --help` 了解详情。 或参考 [NNICTL 说明](NNICTLDOC.md)来查看完整帮助。
### API 的新功能和更新
* <span style="color:red"><strong>不兼容的改动</strong></span>：nn.get_parameters() 改为 nni.get_next_parameter。 所有以前版本的样例将无法在 v0.3 上运行，需要重新克隆 NNI 代码库获取新样例。 如果在自己的代码中使用了 NNI，也需要相应的更新。
* 新 API **nni.get_sequence_id()**。 每个 Trial 任务都会被分配一个唯一的序列数字，可通过 nni.get_sequence_id() API 来获取。
```bash
git clone -b v0.3 https://github.com/Microsoft/nni.git
```
* **nni.report_final_result(result)** API 对结果参数支持更多的数据类型。
可用类型：
* int
* float
* 包含有 'default' 键值的 dict，'default' 的值必须为 int 或 float。 dict 可以包含任何其它键值对。
### 支持新的 Tuner
* **Batch Tuner（批处理调参器）** 会执行所有超参组合，可被用来批量提交 Trial 任务。
### 新样例
* 公开的 NNI Docker 映像：
```bash
docker pull msranni/nni:latest
```
* 新的 Trial 样例： [NNI Sklearn 样例](https://github.com/Microsoft/nni/tree/master/examples/trials/sklearn)
* 新的竞赛样例：[Kaggle Competition TGS Salt](https://github.com/Microsoft/nni/tree/master/examples/trials/kaggle-tgs-salt)
### 其它
* 界面重构，参考[网页文档](WebUI.md)，了解如何使用新界面。
* 持续集成：NNI 已切换到 Azure pipelines。
* [0.3.0 的已知问题](https://github.com/Microsoft/nni/labels/nni030knownissues)。
## 发布 0.2.0 - 9/29/2018
### 主要功能
* 支持 [OpenPAI](https://github.com/Microsoft/pai) (又称 pai) 训练服务 (参考[这里](./PAIMode.md)来了解如何在 OpenPAI 下提交 NNI 任务)
* 支持 pai 模式的训练服务。 NNI Trial 可发送至 OpenPAI 集群上运行
* NNI Trial 输出 (包括日志和模型文件) 会被复制到 OpenPAI 的 HDFS 中。
* 支持 [SMAC](https://www.cs.ubc.ca/~hutter/papers/10-TR-SMAC.pdf) Tuner (参考[这里](Builtin_Tuner.md)，了解如何使用 SMAC Tuner)
* [SMAC](https://www.cs.ubc.ca/~hutter/papers/10-TR-SMAC.pdf) 基于 Sequential Model-Based Optimization (SMBO). 它会利用使用过的结果好的模型（高斯随机过程模型），并将随机森林引入到 SMBO 中，来处理分类参数。 NNI 的 SMAC 通过包装 [SMAC3](https://github.com/automl/SMAC3) 来支持。
* 支持将 NNI 安装在 [conda](https://conda.io/docs/index.html) 和 Python 虚拟环境中。
* 其它
* 更新 ga squad 样例与相关文档
* 用户体验改善及 Bug 修复
### 已知问题
[0.2.0 的已知问题](https://github.com/Microsoft/nni/labels/nni020knownissues)。
## 发布 0.1.0 - 9/10/2018 (首个版本)
首次发布 Neural Network Intelligence (NNI)。
### 主要功能
* 安装和部署
* 支持 pip 和源代码安装
* 支持本机（包括多 GPU 卡）训练和远程多机训练模式
* Tuner ，Assessor 和 Trial
* 支持的自动机器学习算法包括： hyperopt_tpe, hyperopt_annealing, hyperopt_random, 和 evolution_tuner。
* 支持 Assessor（提前终止）算法包括：medianstop。
* 提供 Python API 来自定义 Tuner 和 Assessor
* 提供 Python API 来包装 Trial 代码，以便能在 NNI 中运行
* Experiment
* 提供命令行工具 'nnictl' 来管理 Experiment
* 提供网页界面来查看并管理 Experiment
* 持续集成
* 使用 Ubuntu 的 [travis-ci](https://github.com/travis-ci) 来支持持续集成
* 其它
* 支持简单的 GPU 任务调度
### 已知问题
[0.1.0 的已知问题](https://github.com/Microsoft/nni/labels/nni010knownissues)。
\ No newline at end of file
zh_CN/docs/Reference.rst 0 → 100644
View file @ 035d58bc
参考
==================
.. toctree::
:maxdepth: 3
命令行<NNICTLDOC>
Annotation<AnnotationSpec>
配置<ExperimentConfig>
搜索空间<SearchSpaceSpec>
\ No newline at end of file
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