GetStarted.md 4.74 KB
Newer Older
Scarlett Li's avatar
Scarlett Li committed
1
**Get Started with NNI**
Deshui Yu's avatar
Deshui Yu committed
2
3
===

4
5
## **Installation**
* __Dependencies__
6

7
      python >= 3.5
Scarlett Li's avatar
Scarlett Li committed
8
9
      git
      wget
10

11
    python pip should also be correctly installed. You could use "which pip" or "pip -V" to check in Linux.
Scarlett Li's avatar
Scarlett Li committed
12
    
Scarlett Li's avatar
Scarlett Li committed
13
    * Note: we don't support virtual environment in current releases.
Deshui Yu's avatar
Deshui Yu committed
14

15
* __Install NNI through pip__
Deshui Yu's avatar
Deshui Yu committed
16

QuanluZhang's avatar
QuanluZhang committed
17
      pip3 install -v --user git+https://github.com/Microsoft/nni.git@v0.1
18
19
20
21
      source ~/.bashrc

* __Install NNI through source code__
   
QuanluZhang's avatar
QuanluZhang committed
22
      git clone -b v0.1 https://github.com/Microsoft/nni.git
QuanluZhang's avatar
QuanluZhang committed
23
      cd nni
24
25
      chmod +x install.sh
      source install.sh
Deshui Yu's avatar
Deshui Yu committed
26
27


28
29
30
31
32
33
34
* __Install NNI for all users__
   
      sudo pip3 install -v --user git+https://github.com/Microsoft/nni.git@v0.1

    * Note: NNI will be installed to `/usr/share/nni` for all users and to `~/.local/nni` for current user. Respectively, the examples will be copied to `/usr/share/nni/examples` or `~/.local/nni/examples`.
    * The following tutorial assumes that NNI is installed for current user.

Deshui Yu's avatar
Deshui Yu committed
35
36
37
38
39
40
41
42
## **Quick start: run a customized experiment**
An experiment is to run multiple trial jobs, each trial job tries a configuration which includes a specific neural architecture (or model) and hyper-parameter values. To run an experiment through NNI, you should:

* Provide a runnable trial
* Provide or choose a tuner
* Provide a yaml experiment configure file
* (optional) Provide or choose an assessor

43
**Prepare trial**: Let's use a simple trial example, e.g. mnist, provided by NNI. After you installed NNI, NNI examples have been put in ~/nni/examples, run `ls ~/nni/examples/trials` to see all the trial examples. You can simply execute the following command to run the NNI mnist example: 
Deshui Yu's avatar
Deshui Yu committed
44

45
      python ~/nni/examples/trials/mnist-annotation/mnist.py
Deshui Yu's avatar
Deshui Yu committed
46
47
48

This command will be filled in the yaml configure file below. Please refer to [here]() for how to write your own trial.

QuanluZhang's avatar
QuanluZhang committed
49
**Prepare tuner**: NNI supports several popular automl algorithms, including Random Search, Tree of Parzen Estimators (TPE), Evolution algorithm etc. Users can write their own tuner (refer to [here](CustomizedTuner.md)), but for simplicity, here we choose a tuner provided by NNI as below:
Deshui Yu's avatar
Deshui Yu committed
50

QuanluZhang's avatar
QuanluZhang committed
51
52
53
54
      tuner:
        builtinTunerName: TPE
        classArgs:
          optimize_mode: maximize
Deshui Yu's avatar
Deshui Yu committed
55

QuanluZhang's avatar
QuanluZhang committed
56
*builtinTunerName* is used to specify a tuner in NNI, *classArgs* are the arguments pass to the tuner (the spec of builtin tuners can be found [here]()), *optimization_mode* is to indicate whether you want to maximize or minimize your trial's result.
Deshui Yu's avatar
Deshui Yu committed
57

58
**Prepare configure file**: Since you have already known which trial code you are going to run and which tuner you are going to use, it is time to prepare the yaml configure file. NNI provides a demo configure file for each trial example, `cat ~/nni/examples/trials/mnist-annotation/config.yml` to see it. Its content is basically shown below:
Deshui Yu's avatar
Deshui Yu committed
59
60
61
62

```
authorName: your_name
experimentName: auto_mnist
63

Deshui Yu's avatar
Deshui Yu committed
64
65
# how many trials could be concurrently running
trialConcurrency: 2
66

Deshui Yu's avatar
Deshui Yu committed
67
68
# maximum experiment running duration
maxExecDuration: 3h
69

Deshui Yu's avatar
Deshui Yu committed
70
71
# empty means never stop
maxTrialNum: 100
72

Deshui Yu's avatar
Deshui Yu committed
73
74
# choice: local, remote  
trainingServicePlatform: local
75

Deshui Yu's avatar
Deshui Yu committed
76
77
78
# choice: true, false  
useAnnotation: true
tuner:
79
80
81
  builtinTunerName: TPE
  classArgs:
    optimize_mode: maximize
Deshui Yu's avatar
Deshui Yu committed
82
trial:
83
84
85
  command: python mnist.py
  codeDir: ~/nni/examples/trials/mnist-annotation
  gpuNum: 0
Deshui Yu's avatar
Deshui Yu committed
86
87
``` 

QuanluZhang's avatar
QuanluZhang committed
88
Here *useAnnotation* is true because this trial example uses our python annotation (refer to [here](../tools/annotation/README.md) for details). For trial, we should provide *trialCommand* which is the command to run the trial, provide *trialCodeDir* where the trial code is. The command will be executed in this directory. We should also provide how many GPUs a trial requires.
Deshui Yu's avatar
Deshui Yu committed
89
90
91

With all these steps done, we can run the experiment with the following command:

92
      nnictl create --config ~/nni/examples/trials/mnist-annotation/config.yml
Deshui Yu's avatar
Deshui Yu committed
93
94
95
96
97
98
99
100

You can refer to [here](NNICTLDOC.md) for more usage guide of *nnictl* command line tool.

## View experiment results
The experiment has been running now, NNI provides WebUI for you to view experiment progress, to control your experiment, and some other appealing features. The WebUI is opened by default by `nnictl create`.

## Further reading
* [How to write a trial running on NNI (Mnist as an example)?](WriteYourTrial.md)
gongwuji's avatar
gongwuji committed
101
* [Tutorial of NNI python annotation.](../tools/nni_annotation/README.md)
Deshui Yu's avatar
Deshui Yu committed
102
103
104
* [Tuners supported by NNI.](../src/sdk/pynni/nni/README.md)
* [How to enable early stop (i.e. assessor) in an experiment?](EnableAssessor.md)
* [How to run an experiment on multiple machines?](RemoteMachineMode.md)
105
* [How to write a customized tuner?](CustomizedTuner.md)
Deshui Yu's avatar
Deshui Yu committed
106
* [How to write a customized assessor?](../examples/assessors/README.md)
107
* [How to resume an experiment?](NNICTLDOC.md)
Deshui Yu's avatar
Deshui Yu committed
108
* [Tutorial of the command tool *nnictl*.](NNICTLDOC.md)