中文

简介

VisualDL是飞桨的可视化分析工具，提供多种图表来展示参数变化趋势，并支持模型结构、数据样本、张量直方图、PR曲线、ROC曲线以及高维数据分布的可视化。它帮助用户更清晰直观地理解训练过程和模型结构，从而高效优化模型。

VisualDL提供了丰富的可视化功能，包括 实时跟踪指标、可视化模型结构、展示数据样本、可视化超参数与模型指标的关系、呈现张量分布的变化、绘制PR曲线、将高维数据投影到低维空间等。此外，VisualDL还提供了VDL.service服务，方便开发者轻松保存、追踪和分享实验的可视化结果。关于各功能的具体使用指南，请参阅 VisualDL 用户指南。如需最新体验，欢迎试用我们的 在线演示。目前，VisualDL正在快速迭代，将持续新增更多功能。

VisualDL支持的浏览器包括：

• Google Chrome ≥ 79
• Firefox ≥ 67
• Microsoft Edge ≥ 79
• Safari ≥ 11.1

VisualDL原生支持Python语言。开发者只需在训练前向模型代码中添加几行Python代码，即可获取丰富的可视化结果。

目录

• 核心亮点
• 安装
• 使用指南
• 功能预览
• 常见问题
• 贡献
• 更多详情
• 技术交流

核心亮点

易于使用

API设计简洁易用，仅需一次点击即可启动模型结构的可视化。

功能多样

涵盖训练参数、数据样本、网络结构、张量直方图、PR曲线及高维数据分布等多种可视化功能。

高兼容性

VisualDL支持主流模型架构的可视化，如Paddle、ONNX、Caffe等，广泛适用于不同用户群体的视觉分析需求。

全面支持

通过与飞桨及相关模块深度集成，VisualDL确保开发者能够无缝使用各类组件，在飞桨生态中获得最佳体验。

安装

使用 pip 安装

python -m pip install visualdl -i https://mirror.baidu.com/pypi/simple

使用源码安装

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

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

请注意，自2020年1月1日起，Python 2 已停止官方维护。为保证代码可用性，VisualDL目前仅支持 Python 3。

使用指南

VisualDL会将训练过程中的数据、参数等信息存储在一个日志文件中。用户可以通过启动面板来查看可视化结果。

1. 日志

VisualDL后端提供了Python SDK，可通过LogWriter自定义日志记录器。接口说明如下：

class LogWriter(logdir=None,
                max_queue=10,
                flush_secs=120,
                filename_suffix='',
                **kwargs)

接口参数

参数	类型	含义
logdir	字符串	日志文件的存储路径。VisualDL会在该路径下创建日志文件，用于记录训练过程中产生的信息。若未指定，则默认路径为 runs/${CURRENT_TIME}。
max_queue	整数	在写入日志文件之前，允许缓存的最大数据条目数量。默认值为10。当达到此限制时，数据会立即写入日志文件。
flush_secs	整数	数据在写入日志文件之前的最长缓存时间。默认值为120秒。当达到此时间时，数据会立即写入日志文件。（当日志消息队列达到最大缓存时间或最大容量时，也会立即写入日志文件）
filename_suffix	字符串	为默认的日志文件名添加后缀。
display_name	字符串	此参数会显示在面板的“选择数据流”位置。若未设置，则默认名称为logdir。（当logdir过长或需要隐藏时适用）。
file_name	字符串	设置日志文件的名称。如果文件名已存在，新设置的文件名将在同一日志文件中继续记录，不会创建新文件。注意，文件名应包含“vdlrecords”。

示例

创建日志文件并记录标量值：

from visualdl import LogWriter

# 在 `./log/scalar_test/train` 下创建日志文件
with LogWriter(logdir="./log/scalar_test/train") as writer:
    # 使用 `add_scalar` 记录标量值
    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)
# 你也可以不使用上下文管理器 `with`，而采用如下方式：
"""
writer = LogWriter(logdir="./log/scalar_test/train")

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)

writer.close()
"""

2. 启动面板

在上述示例中，日志记录了三组标量值。开发者可以通过启动 visualDL 面板来查看日志文件的可视化结果。有两种方式可以启动日志文件：

命令行启动

使用命令行启动 visualDL 面板：

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 --component_tabs <tab_name1, tab_name2, ...>

参数说明：

参数	含义
--logdir	设置一个或多个日志目录。路径或子目录中的所有日志都会独立显示在 visualDL Board 上。
--model	设置模型文件的路径（不是目录）。visualDL 会在 Graph 页面中可视化该模型文件。支持 PaddlePaddle、ONNX、Keras、Core ML、Caffe 等多种模型格式。请参考 Graph - 功能说明。
--host	指定 IP 地址。默认值为 127.0.0.1。若设置为 0.0.0.0 或公网 IP 地址，则其他机器也可以访问 visualDL Board。
--port	设置端口。默认值为 8040。
--cache-timeout	后端缓存时间。在此期间，前端多次请求同一 URL 时，返回的数据将来自缓存。默认缓存时间为 20 秒。
--language	visualDL 面板的语言。可指定为 'en' 或 'zh'，默认为浏览器使用的语言。
--public-path	visualDL 面板的 URL 路径。默认路径为 '/app'，即访问地址为 'http://:/app'。
--api-only	决定是否仅提供 API。若设置此参数，visualDL 将仅提供 API 服务，而不显示网页，API 地址为 'http://://api'。此外，若未指定 public_path 参数，则默认地址为 'http://:/api'。
--component_tabs	决定页面上展示哪些组件，目前支持 15 种组件，即 'scalar'、'image'、'text'、'embeddings'、'audio'、'histogram'、'hyper_parameters'、'static_graph'、'dynamic_graph'、'pr_curve'、'roc_curve'、'profiler'、'x2paddle'、'fastdeploy_server'、'fastdeploy_client'。若设置此参数，则仅展示指定的组件。若未设置，但指定了 --logdir 参数，则仅展示 vdlrecords 日志中包含数据的组件。若既未设置 --component_tabs，也未设置 --logdir，则默认仅展示 'static_graph'、'x2paddle'、'fastdeploy_server'、'fastdeploy_client' 组件

要可视化上一步生成的日志文件，开发者可以通过以下命令启动面板：

visualdl --logdir ./log

在 Python 脚本中启动

开发者可以在 Python 脚本中启动 visualDL 面板，方法如下：

visualdl.server.app.run(logdir,
                        model="path/to/model",
                        host="127.0.0.1",
                        port=8080,
                        cache_timeout=20,
                        language=None,
                        public_path=None,
                        api_only=False,
                        open_browser=False)

请注意：由于除 logdir 外其他参数均为可选，因此在使用时应明确指定参数名称。

接口参数如下：

参数	类型	含义
logdir	字符串或列表[字符串_1, 字符串_2, ... , 字符串_n]	设置一个或多个日志目录。路径或子目录中的所有日志都将独立地显示在 VisualDL Board 上。
model	字符串	设置模型文件的路径（不是目录）。VisualDL 会在 Graph 页面中可视化该模型文件。
host	字符串	指定 IP 地址。默认值为 127.0.0.1。将其指定为 0.0.0.0 或公网 IP 地址，以便其他机器可以访问 VisualDL Board。
port	整数	设置端口。默认值为 8040。
cache_timeout	整数	后端缓存时间。在缓存时间内，前端多次请求同一 URL 时，返回的数据将来自缓存。默认缓存时间为 20 秒。
language	字符串	VisualDL 面板的语言。语言可设置为 'en' 或 'zh'，默认为浏览器使用的语言。
public_path	字符串	VisualDL 面板的 URL 路径。默认路径为 '/app'，即访问地址为 'http://:/app'。
api_only	布尔值	决定是否仅提供 API。如果设置了此参数，VisualDL 将仅提供 API 服务，而不显示网页，API 地址为 'http://://api'。此外，如果未指定 public_path 参数，则默认地址为 'http://:/api'。
open_browser	布尔值	是否打开浏览器。如果将此参数设置为 True，浏览器将自动打开，同时启动 VisualDL 面板。如果指定了 api_only 参数为 True，则可以忽略 open_browser 参数。
component_tabs	字符串或列表[字符串_1, 字符串_2, ... , 字符串_n]	决定页面上展示哪些组件，目前支持 15 个组件，即 'scalar', 'image', 'text', 'embeddings', 'audio', 'histogram', 'hyper_parameters', 'static_graph', 'dynamic_graph', 'pr_curve', 'roc_curve', 'profiler', 'x2paddle', 'fastdeploy_server', 'fastdeploy_client'。如果设置了此参数，则仅展示指定的组件。如果没有设置，但指定了 --logdir 参数，则仅展示 vdlrecords 日志中有数据的组件。如果既没有设置 --component_tabs，也没有设置 --logdir，则默认仅展示 'static_graph', 'x2paddle', 'fastdeploy_server', 'fastdeploy_client' 组件。

要可视化上一步生成的日志文件，开发者可以通过以下命令启动面板：

from visualdl.server import app

app.run(logdir="./log")

通过上述方法之一启动面板后，开发者可以在浏览器中看到如下所示的可视化结果：

3. 使用 LogReader 读取日志文件中的数据

VisualDL 还提供了 LogReader 接口，用于从日志文件中读取任何数据。

class LogReader(file_path='')

接口参数

参数	类型	含义
file_path	字符串	日志文件的路径。必填。

示例

如果在 ./log 目录下有一个名为 vdlrecords.1605533348.log 的日志文件，我们可以通过以下方式获取标量中 'loss' 标签下的数据：

from visualdl import LogReader
reader = LogReader(file_path='./vdlrecords.1605533348.log')
data = reader.get_data('scalar', 'loss')
print(data)

结果将是一个如下所示的列表：

...
id: 5
tag: "Metrics/Training(Step): loss"
timestamp: 1605533356039
value: 3.1297709941864014
...

有关 LogReader 的更多信息，请参阅 LogReader。

功能预览

标量

标量利用各种图表来展示训练过程中参数的变化情况，例如准确率、损失和学习率等。在这种情况下，开发者不仅可以观察单个参数的变化，还可以同时观察多组参数的变化，从而更好地理解训练过程并加快模型调优的速度。

动态显示

启动 VisualDL Board 后，LogReader 会持续记录数据并在前端显示。因此，参数的变化可以实时可视化，如下所示：

多实验对比

开发者可以通过同时指定并上传每个实验的路径，将相同的参数在同一张图中进行可视化，从而实现多实验的对比。

图像

图像在训练过程中提供图像数据的实时可视化，使开发者能够观察不同训练阶段图像的变化，并深入理解训练过程的效果。

音频

音频旨在让开发者在训练过程中实时收听音频数据，帮助开发者监控语音识别和文本转语音的过程。

文本

文本可视化 NLP 模型在任意阶段的文本输出，帮助开发者比较不同阶段的输出变化，从而深入理解训练过程并简单评估模型性能。

图形

图形 功能使开发者只需点击一下即可可视化模型结构。此外，图形 还允许开发者探索模型属性、节点信息以及节点的输入和输出，从而帮助他们快速分析模型结构并轻松理解数据流的方向。另外，图形功能分别支持动态图和静态图的可视化。

• 动态图

• 静态图

直方图

直方图 以直方图的形式展示张量（权重、偏置、梯度等）在训练过程中的变化趋势。开发者可以通过深入理解每一层的影响，从而更准确地调整模型结构。

• 偏移模式

• 叠加模式

PR 曲线

PR 曲线 展示不同阈值下的精确率和召回率值，帮助开发者高效地找到最佳阈值。

ROC 曲线

ROC 曲线 显示分类模型在所有分类阈值下的性能；曲线下面积越大，模型性能越好，这有助于开发者评估模型性能并选择合适的阈值。

高维数据

高维数据 提供三种降维方法——T-SNE、PCA 和 UMAP——使开发者能够深入分析高维数据之间的关系，并基于这些分析优化算法。

超参数

超参数 以丰富的视图可视化超参数与模型指标（如准确率和损失）之间的关系，帮助您高效地识别最佳超参数。

性能分析

性能分析（Profiler）可视化程序运行期间收集的剖析数据，帮助您识别程序瓶颈并优化性能。请参阅 VisualDL Profiler 指南。

性能分析

性能分析（Profiler）可视化程序运行期间收集的剖析数据，帮助您识别程序瓶颈并优化性能。请参阅 VisualDL Profiler 指南。

X2Paddle

X2Paddle 组件提供 ONNX 模型格式可视化及转换为 Paddle 格式的功能。

FastDeployServer

FastDeployServer 组件提供加载和编辑模型仓库、管理与监控 FastDeployServer 服务的功能，并提供客户端用于测试服务。请参阅 使用 VisualDL 进行 FastDeploy 服务部署可视化。

FastDeployClient

FastDeployClient 组件主要用于快速访问 FastDeployServer 服务，帮助用户可视化预测请求和结果。请参阅 使用 VisualDL 作为 FastDeploy 客户端进行请求可视化。

VDL.service

VDL.service 使开发者能够轻松保存、跟踪和免费与任何人分享可视化结果。

常见问题解答

如果您在使用 VisualDL 时遇到一些问题，请参阅 我们的常见问题解答。

贡献

VisualDL 的图形功能由 Netron 提供支持，是一个由 PaddlePaddle 和 ECharts 支持的开源项目。我们热烈欢迎开发者使用、评论和贡献。

更多详情

有关 VisualDL 使用的更多详细信息，请参阅 VisualDL 用户指南、VisualDL Profiler 指南、使用 VisualDL 进行 FastDeploy 服务部署可视化以及使用 VisualDL 作为 FastDeploy 客户端进行请求可视化。

技术交流

欢迎加入官方 QQ 群 1045783368，与 PaddlePaddle 团队及其他开发者交流。

VisualDL 快速上手指南

VisualDL 是百度飞桨（PaddlePaddle）推出的深度学习可视化分析工具。它支持实时追踪训练指标、可视化模型结构、展示数据样本、绘制高维数据分布等功能，帮助开发者直观理解训练过程与模型结构，从而高效优化模型。

环境准备

在开始使用前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS, Windows
• Python 版本：Python 3.x (VisualDL 已不再支持 Python 2)
• 浏览器要求：
  • Google Chrome ≥ 79
  • Firefox ≥ 67
  • Microsoft Edge ≥ 79
  • Safari ≥ 11.1

安装步骤

推荐使用国内镜像源进行安装，以获得更快的下载速度。

方式一：通过 pip 安装（推荐）

python -m pip install visualdl -i https://mirror.baidu.com/pypi/simple

方式二：源码安装

如需使用最新开发版功能，可通过源码安装：

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

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

基本使用

VisualDL 的使用流程主要分为两步：记录日志 和 启动面板。

1. 记录日志

在训练代码中引入 LogWriter，将标量、图像、直方图等数据写入日志文件。以下是最简单的记录标量（Scalar）示例：

from visualdl import LogWriter

# 创建日志目录 ./log/scalar_test/train
with LogWriter(logdir="./log/scalar_test/train") as writer:
    # 记录标量数据：tag 为名称，step 为步数，value 为数值
    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)

提示：如果不使用 with 上下文管理器，请在代码末尾手动调用 writer.close() 以确保数据完整写入。

2. 启动可视化面板

日志生成后，使用命令行启动 VisualDL 服务即可查看可视化结果。

启动命令：

visualdl --logdir ./log

参数说明：

• --logdir: 指定日志文件所在的目录（支持多个目录，用逗号分隔）。
• --host: 指定 IP 地址，默认为 127.0.0.1。若需远程访问，可设置为 0.0.0.0。
• --port: 指定端口号，默认为 8040。

执行命令后，终端会显示访问地址（例如 http://127.0.0.1:8040/app），在浏览器中打开该地址即可看到刚才记录的准确率变化曲线及其他可视化组件。