README.md 19.6 KB
Newer Older
1 2


Y
YixinKristy 已提交
3 4 5 6 7 8 9 10
# VisualDL 使用指南

### 概述

VisualDL 是一个面向深度学习任务设计的可视化工具。VisualDL 利用了丰富的图表来展示数据,用户可以更直观、清晰地查看数据的特征与变化趋势,有助于分析数据、及时发现错误,进而改进神经网络模型的设计。

目前,VisualDL 支持 scalar, image, high dimensional 三个组件,项目正处于高速迭代中,敬请期待新组件的加入。

Y
YixinKristy 已提交
11 12 13 14 15
|                           组件名称                           |  展示图表  | 作用                                                         |
| :----------------------------------------------------------: | :--------: | :----------------------------------------------------------- |
|      [ Scalar](#Scalar--折线图组件)      |   折线图   | 动态展示损失函数值、准确率等标量数据                         |
|      [Image](#Image--图片可视化组件)      | 图片可视化 | 显示图片,可显示输入图片和处理后的结果,便于查看中间过程的变化 |
|               [Graph](#Graph--网络结构组件)                |  网络结构  | 展示网络结构、节点属性及数据流向,辅助学习、优化网络结构     |
Y
YixinKristy 已提交
16
|            [Histogram](#Histogram--训练参数分布)             |   直方图   | 展示训练过程中权重、梯度等张量的分布                         |
Y
YixinKristy 已提交
17
| [High Dimensional](#High-Dimensional--数据降维组件) |  数据降维  | 将高维数据映射到 2D/3D 空间来可视化嵌入,便于观察不同数据的相关性 |
Y
YixinKristy 已提交
18 19


20

Y
YixinKristy 已提交
21
## Scalar--折线图组件
22 23 24

### 介绍

Y
YixinKristy 已提交
25
Scalar 组件的输入数据类型为标量,该组件的作用是将训练参数以折线图形式呈现。将损失函数值、准确率等标量数据作为参数传入 scalar 组件,即可画出折线图,便于观察变化趋势。
26 27 28 29 30 31 32 33 34

### 记录接口

Scalar 组件的记录接口如下:

```python
add_scalar(tag, value, step, walltime=None)
```
接口参数说明如下:
35 36 37 38 39 40
|   参数   |  格式  |                    含义                     |
| -------- | ------ | ------------------------------------------- |
| tag      | string | 记录指标的标志,如`train/loss`,不能含有`%` |
| value    | float  | 要记录的数据值                              |
| step     | int    | 记录的步数                                  |
| walltime | int    | 记录数据的时间戳,默认为当前时间戳          |
41

Y
YixinKristy 已提交
42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67
*注意tag的使用规则为:

1. 第一个`/`前的为父tag,并作为一栏图片的tag
2. 第一个`/`后的为子tag,子tag的对应图片将显示在父tag下
3. 可以使用多次`/`,但一栏图片的tag依旧为第一个`/`前的tag

具体使用参见以下三个例子:

- 创建train为父tag,acc和loss为子tag:`train/acc``train/loss`,即创建了tag为train的图片栏,包含acc和loss两张图片:

<p align="center">
  <img src="https://user-images.githubusercontent.com/48054808/84653342-d6d05780-af3f-11ea-8979-8da039ae7201.JPG" width="100%"/>
</p>

- 创建train为父tag,test/acc和test/loss为子tag:`train/test/acc``train/test/loss`,即创建了tag为train的图片栏,包含test/acc和test/loss两张图片:

<p align="center">
  <img src="https://user-images.githubusercontent.com/48054808/84644066-3bd08100-af31-11ea-8eb5-c4a4cab351ed.png" width="100%"/>
</p>

- 创建两个父tag:`acc``loss`,即创建了tag分别为acc和loss的两个图片栏::

<p align="center">
  <img src="https://user-images.githubusercontent.com/48054808/84644323-99fd6400-af31-11ea-9855-eca7f7b01810.png" width="100%"/>
</p>

Y
YixinKristy 已提交
68
### Demo
Y
YixinKristy 已提交
69 70 71

- 基础使用

72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93
下面展示了使用 Scalar 组件记录数据的示例,代码见[Scalar组件](../../demo/components/scalar_test.py)
```python
from visualdl import LogWriter

if __name__ == '__main__':
    value = [i/1000.0 for i in range(1000)]
    # 初始化一个记录器
    with LogWriter(logdir="./log/scalar_test/train") as writer:
        for step in range(1000):
            # 向记录器添加一个tag为`acc`的数据
            writer.add_scalar(tag="acc", step=step, value=value[step])
            # 向记录器添加一个tag为`loss`的数据
            writer.add_scalar(tag="loss", step=step, value=1/(value[step] + 1))
```
运行上述程序后,在命令行执行
```shell
visualdl --logdir ./log --port 8080
```

接着在浏览器打开`http://127.0.0.1:8080`,即可查看以下折线图。

<p align="center">
Y
YixinKristy 已提交
94
  <img src="https://user-images.githubusercontent.com/48054808/82397559-478c6d00-9a83-11ea-80db-a0844dcaca35.png" width="100%"/>
Y
YixinKristy 已提交
95 96
</p>

Y
YixinKristy 已提交
97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138
- 多组实验对比

下面展示了使用Scalar组件实现多组实验对比

多组实验对比的实现分为两步:

1. 创建子日志文件储存每组实验的参数数据
2. 将数据写入scalar组件时,**使用相同的tag**,即可实现对比**不同实验****同一类型参数**

```python
from visualdl import LogWriter

if __name__ == '__main__':
    value = [i/1000.0 for i in range(1000)]
    # 步骤一:创建父文件夹:log与子文件夹:scalar_test
    with LogWriter(logdir="./log/scalar_test") as writer:
        for step in range(1000):
            # 步骤二:向记录器添加一个tag为`train/acc`的数据
            writer.add_scalar(tag="train/acc", step=step, value=value[step])
            # 步骤二:向记录器添加一个tag为`train/loss`的数据
            writer.add_scalar(tag="train/loss", step=step, value=1/(value[step] + 1))
    # 步骤一:创建第二个子文件夹scalar_test2       
    value = [i/500.0 for i in range(1000)]
    with LogWriter(logdir="./log/scalar_test2") as writer:
        for step in range(1000):
            # 步骤二:在同样名为`train/acc`下添加scalar_test2的accuracy的数据
            writer.add_scalar(tag="train/acc", step=step, value=value[step])
            # 步骤二:在同样名为`train/loss`下添加scalar_test2的loss的数据
            writer.add_scalar(tag="train/loss", step=step, value=1/(value[step] + 1))
```

运行上述程序后,在命令行执行

```shell
visualdl --logdir ./log --port 8080
```

接着在浏览器打开`http://127.0.0.1:8080`,即可查看以下折线图,观察scalar_test和scalar_test2的accuracy和loss的对比。

<p align="center">
  <img src="https://user-images.githubusercontent.com/48054808/84644158-5efb3080-af31-11ea-8e64-bbe4078425f4.png" width="100%"/>
</p>
Y
YixinKristy 已提交
139

Y
YixinKristy 已提交
140
*多组实验对比的应用案例可参考AI Studio项目:[VisualDL 2.0--眼疾识别训练可视化](https://aistudio.baidu.com/aistudio/projectdetail/502834)
Y
YixinKristy 已提交
141 142 143 144 145 146

### 功能操作说明

* 支持数据卡片「最大化」、「还原」、「坐标系转化」(y轴对数坐标)、「下载」折线图

<p align="center">
147
  <img src="https://visualdl.bj.bcebos.com/images/scalar-icon.png" width="55%"/>
Y
YixinKristy 已提交
148 149 150 151 152 153 154
</p>



* 数据点Hover展示详细信息

<p align="center">
155
  <img src="https://visualdl.bj.bcebos.com/images/scalar-tooltip.png" width="60%"/>
Y
YixinKristy 已提交
156 157 158 159 160 161 162
</p>



* 可搜索卡片标签,展示目标图像

<p align="center">
163
  <img src="https://visualdl.bj.bcebos.com/images/scalar-searchlabel.png" width="90%"/>
Y
YixinKristy 已提交
164 165 166 167 168 169 170
</p>



* 可搜索打点数据标签,展示特定数据

<p align="center">
171
  <img src="https://visualdl.bj.bcebos.com/images/scalar-searchstream.png" width="40%"/>
Y
YixinKristy 已提交
172 173 174 175 176 177 178 179 180 181
</p>


* X轴有三种衡量尺度

1. Step:迭代次数
2. Walltime:训练绝对时间
3. Relative:训练时长

<p align="center">
182
  <img src="https://visualdl.bj.bcebos.com/images/x-axis.png" width="40%"/>
Y
YixinKristy 已提交
183 184 185 186
</p>
* 可调整曲线平滑度,以便更好的展现参数整体的变化趋势

<p align="center">
187
  <img src="https://visualdl.bj.bcebos.com/images/scalar-smooth.png" width="37%"/>
188 189 190
</p>


Y
YixinKristy 已提交
191
## Image--图片可视化组件
192 193 194

### 介绍

Y
YixinKristy 已提交
195
Image 组件用于显示图片数据随训练的变化。在模型训练过程中,将图片数据传入 Image 组件,就可在 VisualDL 的前端网页查看相应图片。
196 197 198 199 200 201 202 203 204

### 记录接口

Image 组件的记录接口如下:

```python
add_image(tag, img, step, walltime=None)
```
接口参数说明如下:
205 206 207 208 209 210
|   参数   |     格式      |                    含义                     |
| -------- | ------------- | ------------------------------------------- |
| tag      | string        | 记录指标的标志,如`train/loss`,不能含有`%` |
| img      | numpy.ndarray | 以ndarray格式表示的图片                     |
| step     | int           | 记录的步数                                  |
| walltime | int           | 记录数据的时间戳,默认为当前时间戳          |
211

Y
YixinKristy 已提交
212 213
### Demo
下面展示了使用 Image 组件记录数据的示例,代码文件请见[Image组件](../../demo/components/image_test.py)
214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235
```python
import numpy as np
from PIL import Image
from visualdl import LogWriter


def random_crop(img):
    """获取图片的随机 100x100 分片
    """
    img = Image.open(img)
    w, h = img.size
    random_w = np.random.randint(0, w - 100)
    random_h = np.random.randint(0, h - 100)
    r = img.crop((random_w, random_h, random_w + 100, random_h + 100))
    return np.asarray(r)


if __name__ == '__main__':
    # 初始化一个记录器
    with LogWriter(logdir="./log/image_test/train") as writer:
        for step in range(6):
            # 添加一个图片数据
Y
YixinKristy 已提交
236
            writer.add_image(tag="eye",
Y
YixinKristy 已提交
237
                             img=random_crop("../../docs/images/eye.jpg"),
238 239 240 241 242 243 244
                             step=step)
```
运行上述程序后,在命令行执行
```shell
visualdl --logdir ./log --port 8080
```

Y
YixinKristy 已提交
245 246 247
在浏览器输入`http://127.0.0.1:8080`,即可查看图片数据。

<p align="center">
Y
YixinKristy 已提交
248
  <img src="https://user-images.githubusercontent.com/48054808/82397685-86babe00-9a83-11ea-870e-502f313bdc7c.png" width="90%"/>
Y
YixinKristy 已提交
249 250 251 252 253
</p>


### 功能操作说明

Y
YixinKristy 已提交
254
- 可搜索图片标签显示对应图片数据
Y
YixinKristy 已提交
255 256

<p align="center">
257
  <img src="https://visualdl.bj.bcebos.com/images/image-search.png" width="90%"/>
Y
YixinKristy 已提交
258 259 260
</p>


Y
YixinKristy 已提交
261
- 支持滑动Step/迭代次数查看不同迭代次数下的图片数据
262 263

<p align="center">
264
  <img src="https://visualdl.bj.bcebos.com/images/image-eye.gif" width="60%"/>
265 266
</p>

Y
YixinKristy 已提交
267 268 269 270 271 272 273 274 275
## Graph--网络结构组件

### 介绍

Graph组件一键可视化模型的网络结构。用于查看模型属性、节点信息、节点输入输出等,并进行节点搜索,协助开发者们快速分析模型结构与了解数据流向。

### Demo
共有两种启动方式:

Y
YixinKristy 已提交
276 277 278 279 280 281 282 283 284 285 286
- 前端启动Graph:

  - 如只需使用Graph,无需添加任何参数,在命令行执行`visualdl`后即可启动。
  - 如果同时需使用其他功能,在命令行指定日志文件路径(以`./log`为例),即可启动:

  ```shell
  visualdl --logdir ./log --port 8080
  ```


- 后端启动Graph:
Y
YixinKristy 已提交
287

Y
YixinKristy 已提交
288
  - 在命令行加入参数`--model`并指定**模型文件**路径(非文件夹路径),即可启动:
Y
YixinKristy 已提交
289

Y
YixinKristy 已提交
290 291 292
  ```shell
  visualdl --model ./log/model --port 8080
  ```
Y
YixinKristy 已提交
293 294

   
Y
YixinKristy 已提交
295
启动后即可查看网络结构可视化:
Y
YixinKristy 已提交
296 297 298 299 300 301 302 303

<p align="center">
  <img src="https://user-images.githubusercontent.com/48054808/84490149-51e20580-acd5-11ea-9663-1f156892c0e0.png" width="80%"/>
</p>

### 功能操作说明

- 一键上传模型
Y
YixinKristy 已提交
304 305
  - 支持模型格式:PaddlePaddle、ONNX、Keras、Core ML、Caffe、Caffe2、Darknet、MXNet、ncnn、TensorFlow Lite
  - 实验性支持模型格式:TorchScript、PyTorch、Torch、 ArmNN、BigDL、Chainer、CNTK、Deeplearning4j、MediaPipe、ML.NET、MNN、OpenVINO、Scikit-learn、Tengine、TensorFlow.js、TensorFlow
Y
YixinKristy 已提交
306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355

<p align="center">
  <img src="https://user-images.githubusercontent.com/48054808/84487396-44c31780-acd1-11ea-831a-1632e636613d.png" width="80%"/>
</p>

- 支持上下左右任意拖拽模型、放大和缩小模型

<p align="center">
  <img src="https://user-images.githubusercontent.com/48054808/84487568-8784ef80-acd1-11ea-9da1-befedd69b872.GIF" width="80%"/>
</p>

- 搜索定位到对应节点

<p align="center">
  <img src="https://user-images.githubusercontent.com/48054808/84487694-b9965180-acd1-11ea-8214-34f3febc1828.png" width="30%"/>
</p>

- 点击查看模型属性

<p align="center">
  <img src="https://user-images.githubusercontent.com/48054808/84487751-cadf5e00-acd1-11ea-9ce2-4fdfeeea9c5a.png" width="30%"/>
</p>

<p align="center">
  <img src="https://user-images.githubusercontent.com/48054808/84487759-d03ca880-acd1-11ea-9294-520ef7f9e0b1.png" width="30%"/>
</p>

- 支持选择模型展示的信息

<p align="center">
  <img src="https://user-images.githubusercontent.com/48054808/84487829-ee0a0d80-acd1-11ea-8563-6682a15483d9.png" width="23%"/>
</p>

- 支持以PNG、SVG格式导出文件

<p align="center">
  <img src="https://user-images.githubusercontent.com/48054808/84487884-ff531a00-acd1-11ea-8b12-5221db78683e.png" width="30%"/>
</p>

- 点击节点即可展示对应属性信息

<p align="center">
  <img src="https://user-images.githubusercontent.com/48054808/84487941-13971700-acd2-11ea-937d-42fb524b9ee1.png" width="30%"/>
</p>

- 支持一键更换模型

<p align="center">
  <img src="https://user-images.githubusercontent.com/48054808/84487998-27db1400-acd2-11ea-83d7-5d75832ef41d.png" width="25%"/>
</p>
356

Y
YixinKristy 已提交
357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451
## Histogram--训练参数分布

### 介绍

Histogram组件以直方图形式实时展示训练过程中张量参数,如weight、bias、gradient的分布变化。深入了解训练效果,探查模型问题所在,提高调参效率。

### 记录接口

Histogram 组件的记录接口如下:

```python
add_histogram(tag, values, step, walltime=None, buckets=10)
```
接口参数说明如下:
|   参数   |          格式          |                    含义                     |
| -------- | --------------------- | ------------------------------------------- |
| tag      | string                | 记录指标的标志,如`train/loss`,不能含有`%` |
| values   | numpy.ndarray or list | 以ndarray或list格式表示的数据                     |
| step     | int                   | 记录的步数                                  |
| walltime | int                   | 记录数据的时间戳,默认为当前时间戳          |
| buckets  | int                   | 生成直方图的分段数,默认为10          |
### Demo

下面展示了使用 Histogram组件记录数据的示例,代码见[Histogram组件](https://github.com/PaddlePaddle/VisualDL/blob/develop/demo/components/histogram_test.py)

```python
from visualdl import LogWriter
import numpy as np


if __name__ == '__main__':
    values = np.arange(0, 1000)
    with LogWriter(logdir="./log/histogram_test/train") as writer:
        for index in range(1, 101):
            interval_start = 1 + 2 * index / 100.0
            interval_end = 6 - 2 * index / 100.0
            data = np.random.uniform(interval_start, interval_end, size=(10000))
            writer.add_histogram(tag='default tag',
                                 values=data,
                                 step=index,
                                 buckets=10)
```

运行上述程序后,在命令行执行

```shell
visualdl --logdir ./log --port 8080
```

在浏览器输入`http://127.0.0.1:8080`,即可查看训练参数直方图。

### 功能操作说明

- 支持数据卡片「最大化」、「下载」直方图
  <p align="center">
    <img src="https://user-images.githubusercontent.com/48054808/86535351-42d82700-bf12-11ea-89f0-171280e7c526.png" width="60%"/>
  </p>

- 可选择Offset或Overlay模式

  <p align="center">
    <img src="https://user-images.githubusercontent.com/48054808/86535413-c134c900-bf12-11ea-9ad6-f0ad8eafa76f.png" width="30%"/>
  </p>

  - Offset模式

  <p align="center">
    <img src="https://user-images.githubusercontent.com/48054808/86536435-2b9d3780-bf1a-11ea-9981-92f837d22ae5.png" width="60%"/>
  </p>

  - Overlay模式

  <p align="center">
    <img src="https://user-images.githubusercontent.com/48054808/86536458-5ab3a900-bf1a-11ea-985e-05f06c1b762b.png" width="60%"/>
  </p>

- 数据点Hover展示参数值、训练步数、频次
  - 在第240次训练步数时,权重为-0.0031,且出现的频次是2734次

  <p align="center">
    <img src="https://user-images.githubusercontent.com/48054808/86536482-80d94900-bf1a-11ea-9e12-5bea9f382b34.png" width="60%"/>
  </p>

- 可搜索卡片标签,展示目标直方图

  <p align="center">
    <img src="https://user-images.githubusercontent.com/48054808/86536503-baaa4f80-bf1a-11ea-80ab-cd988617d018.png" width="40%"/>
  </p>

- 可搜索打点数据标签,展示特定数据流

  <p align="center">
    <img src="https://user-images.githubusercontent.com/48054808/86536639-b894c080-bf1b-11ea-9ee5-cf815dd4bbd7.png" width="40%"/>
  </p>

Y
YixinKristy 已提交
452
## High Dimensional--数据降维组件
453 454 455

### 介绍

Y
YixinKristy 已提交
456
High Dimensional 组件将高维数据进行降维展示,用于深入分析高维数据间的关系。目前支持以下两种降维算法:
457 458 459 460 461 462 463 464 465 466 467 468

 - PCA : Principle Component Analysis 主成分分析
 - t-SNE : t-distributed stochastic neighbor embedding t-分布式随机领域嵌入

### 记录接口

High Dimensional 组件的记录接口如下:

```python
add_embeddings(tag, labels, hot_vectors, walltime=None)
```
接口参数说明如下:
469 470 471 472 473 474
|    参数     |        格式         |                         含义                         |
| ----------- | ------------------- | ---------------------------------------------------- |
| tag         | string              | 记录指标的标志,如`default`,不能含有`%`             |
| labels      | numpy.array 或 list | 一维数组表示的标签,每个元素是一个string类型的字符串 |
| hot_vectors | numpy.array or list | 与labels一一对应,每个元素可以看作是某个标签的特征   |
| walltime    | int                 | 记录数据的时间戳,默认为当前时间戳                   |
475

Y
YixinKristy 已提交
476
### Demo
477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505
下面展示了使用 High Dimensional 组件记录数据的示例,代码见[High Dimensional组件](../../demo/components/high_dimensional_test.py)
```python
from visualdl import LogWriter


if __name__ == '__main__':
    hot_vectors = [
        [1.3561076367500755, 1.3116267195134017, 1.6785401875616097],
        [1.1039614644440658, 1.8891609992484688, 1.32030488587171],
        [1.9924524852447711, 1.9358920727142739, 1.2124401279391606],
        [1.4129542689796446, 1.7372166387197474, 1.7317806077076527],
        [1.3913371800587777, 1.4684674577930312, 1.5214136352476377]]

    labels = ["label_1", "label_2", "label_3", "label_4", "label_5"]
    # 初始化一个记录器
    with LogWriter(logdir="./log/high_dimensional_test/train") as writer:
        # 将一组labels和对应的hot_vectors传入记录器进行记录
        writer.add_embeddings(tag='default',
                              labels=labels,
                              hot_vectors=hot_vectors)
```
运行上述程序后,在命令行执行
```shell
visualdl --logdir ./log --port 8080
```

接着在浏览器打开`http://127.0.0.1:8080`,即可查看降维后的可视化数据。

<p align="center">
506
  <img src="https://visualdl.bj.bcebos.com/images/dynamic_high_dimensional.gif" width="80%"/>
507
</p>
Y
YixinKristy 已提交
508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533

### 功能操作说明

* 支持展示特定打点数据

  <p align="center">
    <img src="https://user-images.githubusercontent.com/48054808/83006541-f6f9ae80-a044-11ea-82d9-03f1c99a310a.png" width="30%"/>
  </p>

* 可搜索展示特定数据标签或展示所有数据标签

  <p align="center">
    <img src="https://user-images.githubusercontent.com/48054808/83006580-0842bb00-a045-11ea-9f7b-776f80ae8b90.png" width="30%"/>
  </p>

* 支持「二维」或「三维」展示高维数据分布

  <p align="center">
    <img src="https://user-images.githubusercontent.com/48054808/83006687-2f998800-a045-11ea-888e-2b59e16a92b9.png" width="27%"/>
  </p>

* 可选择「PCA」或「T-SNE」作为降维方式

  <p align="center">
    <img src="https://user-images.githubusercontent.com/48054808/83006747-3fb16780-a045-11ea-83e0-a314b7765108.png" width="27%"/>
  </p>