README.md 17.6 KB
Newer Older
1 2
[**中文**](./README_CN.md)

Y
YixinKristy 已提交
3

D
daminglu 已提交
4
<p align="center">
Y
YixinKristy 已提交
5
  <img src="https://raw.githubusercontent.com/PaddlePaddle/VisualDL/develop/frontend/packages/core/public/images/logo-visualdl.svg?sanitize=true" width="70%"/>
D
daminglu 已提交
6 7
</p>

L
LaraStuStu 已提交
8

9

P
Peter Pan 已提交
10
<p align="center">
P
Peter Pan 已提交
11
<a href="https://actions-badge.atrox.dev/PaddlePaddle/VisualDL/goto?ref=develop"><img alt="Build Status" src="https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2FPaddlePaddle%2FVisualDL%2Fbadge%3Fref%3Ddevelop&style=flat-square" alt="Build Status" /></a>
P
Peter Pan 已提交
12 13 14 15 16
<a href="https://pypi.org/project/visualdl/"><img src="https://img.shields.io/pypi/v/visualdl?style=flat-square" alt="PyPI" /></a>
<a href="https://pypi.org/project/visualdl/#files"><img src="https://img.shields.io/pypi/dm/visualdl?style=flat-square" alt="Downloads" /></a>
<a href="https://github.com/PaddlePaddle/VisualDL/blob/develop/LICENSE"><img src="https://img.shields.io/github/license/paddlepaddle/visualdl?style=flat-square" alt="License" /></a>
</p>

17

P
Peter Pan 已提交
18
<p align="center">
19
<a href="javascript:void(0)"><img src="https://img.shields.io/badge/QQ_Group-1045783368-52B6EF?style=social&logo=tencent-qq&logoColor=000&logoWidth=20" alt="QQ Group" /></a>
P
Peter Pan 已提交
20
</p>
Y
YixinKristy 已提交
21

D
daminglu 已提交
22

23 24 25
## Introduction

VisualDL, a visualization analysis tool of PaddlePaddle, provides a variety of charts to show the trends of parameters, and visualizes model structures, data samples, histograms of tensors, pr curves and high-dimensional data distributions. It enables users to understand the training process and the model structure more clearly and intuitively so as to optimize models efficiently.
Q
Qiao Longfei 已提交
26

27 28 29
VisualDL provides various visualization functions, including tracking metrics in real-time, visualizing the model structure, displaying the data sample, presenting the changes of distributions of tensors, showing the pr curves, projecting high-dimensional data to a lower dimensional space and more. Additionally, VisualDL provides VDL.service, which enables developers easily to save, track and share visualization results of experiments. For specific guidelines of each function, please refer to  [**VisualDL User Guide**](./docs/components/UserGuide-en.md). Currently, VisualDL iterates rapidly and new functions will be continuously added.

Browsers supported by VisualDL are:
Y
YixinKristy 已提交
30

P
Peter Pan 已提交
31 32 33 34 35
- Google Chrome ≥ 79
- Firefox ≥ 67
- Microsoft Edge ≥ 79
- Safari ≥ 11.1

36
VisualDL natively supports the use of Python. Developers can retrieve plentiful visualization results by simply adding a few lines of Python code into the model before training.
D
daminglu 已提交
37

38
## Contents
D
daminglu 已提交
39

40 41 42 43 44 45 46
* [Key Highlights](#Key-Highlights)
* [Installation](#Installation)
* [Usage Guideline](#Usage-Guideline)
* [Function Preview](#Function-Preview)
* [Contribution](#Contribution)
* [More Details](#More-Details)
* [Technical Communication](#Technical-Communication)
D
daminglu 已提交
47 48


49

50
## Key Highlights
D
daminglu 已提交
51

52
### Easy to Use
53

54
The high-level design of API makes it easy to use. Only one click can initiate the visualization of model structures.
D
daminglu 已提交
55

56

57
### Various Functions
Q
Qiao Longfei 已提交
58

59
The function contains the visualization of training parameters, data samples, graph structures, histograms of tensors, PR curves and high-dimensional data.
Y
YixinKristy 已提交
60

61
### High Compatibility
Y
YixinKristy 已提交
62

63
VisualDL provides the visualization of the mainstream model structures such as Paddle, ONNX, Caffe, widely supporting visual analysis for diverse users.
Y
YixinKristy 已提交
64

65
### Fully Support
Y
YixinKristy 已提交
66

67
By Integrating into PaddlePaddle and related modules, VisualDL allows developers to use different components unobstructed, and thus have the best experience in the PaddlePaddle ecosystem.
Q
Qiao Longfei 已提交
68

69
## Installation
70 71


72
### Install by PiP
73

74
```shell
Y
YixinKristy 已提交
75
python -m pip install visualdl -i https://mirror.baidu.com/pypi/simple
76
```
77 78

### Install by Code
Y
YixinKristy 已提交
79 80 81 82 83 84 85 86 87

```
git clone https://github.com/PaddlePaddle/VisualDL.git
cd VisualDL

python setup.py bdist_wheel
pip install --upgrade dist/visualdl-*.whl
```

88 89 90 91
Please note that Python 2 is no longer maintained officially since January 1, 2020. VisualDL now only supports Python 3 in order to ensure the usability of codes.


## Usage Guideline
Y
YixinKristy 已提交
92

93
VisualDL stores the data, parameters and other information of the training process in a log file. Users can launch the panel to observe the visualization results.
Y
YixinKristy 已提交
94

95
### 1. Log
Y
YixinKristy 已提交
96

97
The Python SDK is provided at the back end of VisualDL, and a logger can be customized through LogWriter. The interface description is shown as follows:
98

Y
YixinKristy 已提交
99
```python
100
class LogWriter(logdir=None,
Y
YixinKristy 已提交
101 102 103 104 105
                comment='',
                max_queue=10,
                flush_secs=120,
                filename_suffix='',
                write_to_disk=True,
106
                **kwargs)
107 108
```

109
#### Interface Parameters
Y
YixinKristy 已提交
110

111 112 113 114 115 116 117 118 119
| parameters      | type    | meaning                                                      |
| --------------- | ------- | ------------------------------------------------------------ |
| logdir          | string  | The path location of log file. VisualDL will create a log file under this path to record information generated by the training process. If not specified, the path will be  `runs/${CURRENT_TIME}`as default. |
| comment         | string  | Add a suffix to the log folder name, which is invalid if logdir is already specified. |
| max_queue       | int     | The maximum capacity of the data generated before recording in a log file. If the capacity is reached, the data is immediately written into the log file. |
| flush_secs      | int     | The maximum cache time of the data generated before recording in a log file, when this time is reached, the data is immediately written to the log file. |
| filename_suffix | string  | Add a suffix to the default log file name.                   |
| write_to_disk   | boolean | Write into disk or not.                                      |
| display_name    | string  | Set the name of different runs when `logdir` is too long or needed to be hidden. If not set, the default name is `logdir`. |
120 121 122 123 124 125 126 127 128 129
| file_name    | string  | Set the name of the log file. If the file_name already exists, setting the file_name means to continue to add new records in the same log file. Note that the name should include 'vdlrecords'.|

<p align="center">
  <img src="https://user-images.githubusercontent.com/48054808/103187556-b9714280-48ff-11eb-9052-008e02a21199.png" width="100%"/>
</p>

<p align="center">
  <img src="https://user-images.githubusercontent.com/48054808/103187552-b4ac8e80-48ff-11eb-998a-57d5a1bc7ee6.png" width="100%"/>
</p>

Y
YixinKristy 已提交
130

131
#### Example
Y
YixinKristy 已提交
132

133
Create a log file and record scalar values:
D
daminglu 已提交
134 135 136 137

```python
from visualdl import LogWriter

138
# create a log file under `./log/scalar_test/train`
Y
YixinKristy 已提交
139
with LogWriter(logdir="./log/scalar_test/train") as writer:
140
    # use `add_scalar` to record scalar values
Y
YixinKristy 已提交
141 142 143
    writer.add_scalar(tag="acc", step=1, value=0.5678)
    writer.add_scalar(tag="acc", step=2, value=0.6878)
    writer.add_scalar(tag="acc", step=3, value=0.9878)
D
daminglu 已提交
144 145
```

146
### 2. Launch Panel
D
daminglu 已提交
147

148
In the above example, the log has recorded three sets of scalar values. Developers can view the visualization results of the log file through launching the visualDL panel. There are two ways to launch a log file:
Z
Zeyu Chen 已提交
149

150
#### Launch by Command Line
Z
Zeyu Chen 已提交
151

152
Use the command line to launch the VisualDL panel:
D
daminglu 已提交
153

Y
YixinKristy 已提交
154
```python
P
Peter Pan 已提交
155
visualdl --logdir <dir_1, dir_2, ... , dir_n> --model <model_file> --host <host> --port <port> --cache-timeout <cache_timeout> --language <language> --public-path <public_path> --api-only
D
daminglu 已提交
156
```
Y
YixinKristy 已提交
157

158
Parameter details:
Y
YixinKristy 已提交
159

160 161 162 163 164 165 166 167 168 169
| parameters      | meaning                                                      |
| --------------- | ------------------------------------------------------------ |
| --logdir        | Set one or more directories of the log. VisualDL will search the log file recursively under this path to display the all experimental results. |
| --model         | Set path to the model file (not a directory). VisualDL will visualize the model file in Graph page. PaddlePaddle、ONNX、Keras、Core ML、Caffe and Other model formats are supported. Please refer to [Graph - Functional Instructions](./docs/components/UserGuide-en.md#functional-instructions-2). |
| --host          | Specify IP address. The default value is `127.0.0.1`.        |
| --port          | Set the port. The default value is `8040`.                   |
| --cache-timeout | Cache time of the backend. During the cache time, the front end requests the same URL multiple times, and then the returned data is obtained from the cache. The default cache time is 20 seconds. |
| --language      | The language of the VisualDL panel. Language can be specified as 'en' or 'zh', and the default is the language used by the browser. |
| --public-path   | The URL path of the VisualDL panel. The default path is '/app', meaning that the access address is 'http://&lt;host&gt;:&lt;port&gt;/app'. |
| --api-only      | Decide whether or not to provide only API. If this parameter is set, VisualDL will only provides API service without displaying the web page, and the API address is 'http://&lt;host&gt;:&lt;port&gt;/&lt;public_path&gt;/api'. Additionally, If the public_path parameter is not specified, the default address is 'http://&lt;host&gt;:&lt;port&gt;/api'. |
Y
YixinKristy 已提交
170

171
To visualize the log file generated in the previous step, developers can launch the panel through the command:
Y
YixinKristy 已提交
172 173 174

```
visualdl --logdir ./log
D
daminglu 已提交
175 176
```

177
#### Launch in Python Script
Y
YixinKristy 已提交
178

179 180

Developers can start the VisualDL panel in Python script as follows:
D
daminglu 已提交
181

182
```python
Y
YixinKristy 已提交
183
visualdl.server.app.run(logdir,
P
Peter Pan 已提交
184
                        model="path/to/model",
Y
YixinKristy 已提交
185 186 187 188
                        host="127.0.0.1",
                        port=8080,
                        cache_timeout=20,
                        language=None,
189 190
                        public_path=None,
                        api_only=False,
Y
YixinKristy 已提交
191 192 193
                        open_browser=False)
```

194
Please note: since all parameters are indefinite except `logdir`, developers should specify parameter names when using them.
Y
YixinKristy 已提交
195

196
The interface parameters are as follows:
Y
YixinKristy 已提交
197

198 199 200 201 202 203 204 205 206 207 208
| parameters    | type                                               | meaning                                                      |
| ------------- | -------------------------------------------------- | ------------------------------------------------------------ |
| logdir        | string or list[string_1, string_2, ... , string_n] | Set one or more directories of the log. VisualDL will search the log file recursively under this path to display the all experimental results. |
| model         | string                                             | Set path to the model file (not a directory). VisualDL will visualize the model file in Graph page. |
| host          | string                                             | Specify IP address. The default value is `127.0.0.1`.        |
| port          | int                                                | Set the port. The default value is `8040`.                   |
| cache_timeout | int                                                | Cache time of the backend. During the cache time, the front end requests the same URL multiple times, and then the returned data is obtained from the cache. The default cache time is 20 seconds. |
| language      | string                                             | The language of the VisualDL panel. Language can be specified as 'en' or 'zh', and the default is the language used by the browser. |
| public_path   | string                                             | The URL path of the VisualDL panel. The default path is '/app', meaning that the access address is 'http://&lt;host&gt;:&lt;port&gt;/app'. |
| api_only      | boolean                                            | Decide whether or not to provide only API. If this parameter is set, VisualDL will only provides API service without displaying the web page, and the API address is 'http://&lt;host&gt;:&lt;port&gt;/&lt;public_path&gt;/api'. Additionally, If the parameter public_path is not specified, the default address is 'http://&lt;host&gt;:&lt;port&gt;/api'. |
| open_browser  | boolean                                            | Whether or not to open the browser. If this parameter is set as True, the browser will be opened automatically and VisualDL panel will be launched at the same time. If parameter api_only is specified as True,  parameter open_browser can be ignored. |
209

210
To visualize the log file generated in the previous step, developers can launch the panel through the command:
Y
YixinKristy 已提交
211 212 213 214 215

```python
from visualdl.server import app

app.run(logdir="./log")
216
```
D
daminglu 已提交
217

218
After launching the panel by one of the above methods, developers can see the visualization results on the browser shown as blow:
Y
YixinKristy 已提交
219 220

<p align="center">
221
  <img src="https://user-images.githubusercontent.com/48054808/90868674-ba321f00-e3c9-11ea-83c1-f03c6dd19187.png" width="70%"/>
Y
YixinKristy 已提交
222 223
</p>

224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255
### 3. Read data in log files using LogReader

VisualDL also provides `LogReader` interface to read raw data from log files.

```python
class LogReader(file_path='')
```
#### interface parameters
| parameters | type   | meaning                              |
| ---------- | ------ | ------------------------------------ |
| file_path  | string | File path of the log file. Required. |
#### Example
If there is a log file named `vdlrecords.1605533348.log` in the directory of `./log`, we can retrieve the data under the 'loss' tag in the scalar by:
```python
from visualdl import LogReader
reader = LogReader(file_path='./vdlrecords.1605533348.log')
data = reader.get_data('scalar', 'loss')
print(data)
```
The result will be a list shown as below:
```python
...
id: 5
tag: "Metrics/Training(Step): loss"
timestamp: 1605533356039
value: 3.1297709941864014
...
```

For more information of `LogReader`, please refer to [LogReader](./docs/io/LogReader.md).


256
## Function Preview
Y
YixinKristy 已提交
257 258 259

### Scalar

260
**Scalar** makes use of various charts to display how the parameters, such as accuracy, loss and learning rate, change during the training process. In this case, developers can observe not only the single but also the multiple groups of parameters in order to understand the training process and thus speed up the process of model tuning.
Y
YixinKristy 已提交
261

262 263 264
#### Dynamic Display

After the launch of VisualDL Board, the LogReader will continuously record the data to display in the front-end. Hence, the changes of parameters can be visualized in real-time, as shown below:
Y
YixinKristy 已提交
265 266

<p align="center">
267
  <img src="https://visualdl.bj.bcebos.com/images/dynamic_display.gif" width="60%"/>
Y
YixinKristy 已提交
268 269 270 271
</p>



272 273 274
#### Comparison of Multiple Experiments

Developers can compare with multiple experiments by specifying and uploading the path of each experiment at the same time so as to visualize the same parameters in the same chart.
Y
YixinKristy 已提交
275 276

<p align="center">
277
  <img src="https://user-images.githubusercontent.com/48054808/90869567-fdd95880-e3ca-11ea-9855-6c97ad5c8ae7.gif" width="100%"/>
Y
YixinKristy 已提交
278 279 280
</p>


281

Y
YixinKristy 已提交
282
### Image
283 284

**Image** provides real-time visualizations of the image data during the training process, allowing developers to observe the changes of images in different training stages and  to deeply understand the effects of the training process.
Y
YixinKristy 已提交
285 286

<p align="center">
287
<img src="https://user-images.githubusercontent.com/48054808/90869677-22353500-e3cb-11ea-9830-2334bdd8e52e.gif" width="55%"/>
Y
YixinKristy 已提交
288 289
</p>

290

Y
YixinKristy 已提交
291
### Audio
292 293

**Audio** aims to allow developers to listen to the audio data in real-time during the training process, helping developers to monitor the process of speech recognition and text-to-speech.
Y
YixinKristy 已提交
294 295

<p align="center">
296
<img src="https://user-images.githubusercontent.com/48054808/90869771-47c23e80-e3cb-11ea-8b2a-a38b6c33d64b.png" width="85%"/>
Y
YixinKristy 已提交
297 298
</p>

299

Y
YixinKristy 已提交
300 301
### Graph

302 303
**Graph** enables developers to visualize model structures by only one click. Moreover, **Graph** allows Developers to explore model attributes, node information, node input and output. aiding them analyze model structure quickly and understand the direction of data flow easily.

Y
YixinKristy 已提交
304
<p align="center">
305
<img src="https://user-images.githubusercontent.com/48054808/90869866-6aecee00-e3cb-11ea-8211-b8af070239e6.png" width="85%"/>
Y
YixinKristy 已提交
306 307
</p>

308

Y
YixinKristy 已提交
309 310
### Histogram

311
Histogram displays how the trend of tensors (weight, bias, gradient, etc.) changes during the training process in the form of histogram. Developers can adjust the model structures accurately by having an in-depth understanding of the effect of each layer.
Y
YixinKristy 已提交
312

313
- Offset Mode
Y
YixinKristy 已提交
314 315

<p align="center">
316
<img src="https://user-images.githubusercontent.com/48054808/90870121-bd2e0f00-e3cb-11ea-89cf-6622cb607b89.png" width="85%"/>
Y
YixinKristy 已提交
317 318
</p>

Y
YixinKristy 已提交
319

Y
YixinKristy 已提交
320

321
- Overlay Mode
Y
YixinKristy 已提交
322 323

<p align="center">
324
<img src="https://user-images.githubusercontent.com/48054808/90870194-cfa84880-e3cb-11ea-8a66-bebcad267a10.png" width="85%"/>
Y
YixinKristy 已提交
325 326
</p>

327

Y
YixinKristy 已提交
328 329
### High Dimensional

330
**High Dimensional** provides three approaches--T-SNE, PCA and UMAP--to do the dimensionality reduction, allowing developers to have an in-depth analysis of the relationship between high-dimensional data and to optimize algorithms based on the analysis.
Y
YixinKristy 已提交
331 332

<p align="center">
333
<img src="https://user-images.githubusercontent.com/48054808/103188111-1b32ac00-4902-11eb-914e-c2368bdb8373.gif" width="85%"/>
Y
YixinKristy 已提交
334 335
</p>

336

337 338
### VDL.service

339
**VDL.service** enables developers to easily save, track and share visualization results with anyone for free.
340 341

<p align="center">
342
<img src=https://user-images.githubusercontent.com/48054808/93731055-fbeafb00-fbfd-11ea-80f4-bbfd08a0fc35.png width="85%"/>
343 344
</p>

345

346
## Contribution
Y
YixinKristy 已提交
347

348
VisualDL, in which Graph is powered by [Netron](https://github.com/lutzroeder/netron), is an open source project supported by [PaddlePaddle](https://www.paddlepaddle.org/) and [ECharts](https://echarts.apache.org/).
W
wuzewu 已提交
349

350
Developers are warmly welcomed to use, comment and contribute.
W
wuzewu 已提交
351

352
## More Details
W
wuzewu 已提交
353

354
For more details related to the use of VisualDL, please refer to [**VisualDL User Guide**](./docs/components/UserGuide-en.md)
Y
YixinKristy 已提交
355

356
## Technical Communication
Y
YixinKristy 已提交
357

358
Welcome to join the official QQ group 104578336 to communicate with PaddlePaddle team and other developers.
Y
YixinKristy 已提交
359 360 361 362

<p align="center">
<img src="https://user-images.githubusercontent.com/48054808/82522691-c2758680-9b5c-11ea-9aee-fca994aba175.png" width="20%"/>
</p>
363