TensorBoard - pytorch实战 - 笔记

拉拉拉拉拉拉拉马

已于 2025-05-14 21:25:41 修改

阅读量570

点赞数 20

文章标签： pytorch 笔记人工智能深度学习

于 2025-05-13 22:10:16 首次发布

本文链接：https://blog.csdn.net/2301_79168784/article/details/147933460

版权

TensorBoard - pytorch实战

TensorBoard 作为一款强大的可视化工具，能够帮助开发者深入理解机器学习模型的训练过程、调试模型并优化性能。虽然最初为 TensorFlow 设计，但 PyTorch 也能通torch.utils.tensorboard 模块完美集成 TensorBoard，实现训练指标、图像、模型图、参数分布等多种数据的可视化。本指南将详细介绍如何在 PyTorch 项目中使用 TensorBoard，重点讲解 SummaryWriter 的核心用法和命令行工具的实际操作，并结合具体示例，助你轻松驾驭这一可视化利器。

I. TensorBoard 与 PyTorch

TensorBoard 提供了一套 Web 应用，用于检查和理解模型的运行和图结构，支持标量、图像、音频、直方图和计算图等多种可视化方式。在 PyTorch 中torch.utils.tensorboard.SummaryWriter 类是与 TensorBoard 交互的核心，它能够将 PyTorch 模型和指标数据记录到特定目录，供 TensorBoard 读取和展示。

A. 安装 TensorBoard

在 PyTorch 项目中使用 TensorBoard 前，首先需要确保已安装 TensorBoard。安装过程非常简单，可以通过 pip 或 conda 完成：

Pip 安装:
```
pip install tensorboard
```

Conda 安装:

conda install -c conda-forge tensorboard

值得注意的是，即使不安装 tensorboard，也可以在 PyTorch 项目中使用 TensorBoard 。建议使用较新版本的 PyTorch（如 1.10 或更高版本）以获得更好的兼容性。

B. TensorBoard 核心组件概览

TensorBoard 提供了多个仪表板（Dashboards）来展示不同类型的数据，帮助用户从多个维度理解模型和训练过程。

Scalars (标量): 用于可视化标量指标随时间（通常是训练步数或轮次）的变化，如损失函数值 (loss)、准确率 (accuracy)、学习率 (learning rate) 等。这是监控模型训练最基本也是最常用的功能。
Images (图像): 用于展示图像数据，可以是模型的输入样本、卷积层的特征图输出，或是生成模型产生的图片。这对于理解计算机视觉任务中的模型行为至关重要。
Graphs (计算图): 可视化模型的计算图结构，清晰展示网络层、操作以及它们之间的连接关系和数据流向。这有助于检查模型构建是否正确，理解数据在网络中的传递过程。
Histograms (直方图): 展示张量数据（如模型权重、偏置、梯度或激活值）的分布情况及其随时间的变化。通过观察参数分布，可以帮助诊断梯度消失/爆炸、神经元死亡等问题。
Distributions (分布图): 与直方图类似，也用于展示张量数据的分布，但通常以更平滑的曲线形式呈现，同样可以追踪参数在训练过程中的变化。
HParams (超参数): TensorBoard 的 HParams 仪表板允许用户记录不同超参数组合下的实验结果，并进行可视化比较，从而辅助超参数调优。
Profiler (性能分析器): 用于分析模型训练过程中的计算性能，识别性能瓶颈，例如哪些操作耗时较长，GPU/CPU 利用率如何等。

这些组件共同构成了 TensorBoard 强大的可视化能力，使得开发者能够更直观地监控、理解和优化他们的 PyTorch 模型。

II. PyTorch 中的 `SummaryWriter`：

torch.utils.tensorboard.SummaryWriter 是 PyTorch 中用于将数据写入 TensorBoard 事件文件的核心类。它提供了一系列 API，可以将训练过程中的各种信息（如标量、图像、模型结构等）异步写入磁盘上的日志文件，而不会显著拖慢训练速度。

A. 初始化 `SummaryWriter`：组织你的实验日志

正确初始化 SummaryWriter 是有效使用 TensorBoard 的第一步。关键在于合理设置日志目录 (log_dir) 和可选的注释 (comment)，这对于后续在 TensorBoard 中区分和比较不同的实验运行至关重要。

数据点：
- SummaryWriter(log_dir=None, comment='',...): log_dir 参数指定日志文件的存储路径。如果为 None（默认情况），日志将保存在 ./runs/TIMESTAMPED_FOLDER/ 目录下，其中 TIMESTAMPED_FOLDER 是一个基于当前时间的文件夹名。
- comment 参数可以为默认的 log_dir 添加后缀，方便区分不同的实验运行。例如，SummaryWriter(comment="_LR_0.01_BATCH_32") 会创建一个类似 runs/May10_10-30-00_hostname_LR_0.01_BATCH_32/ 的目录。
解释：

虽然 TensorBoard 默认的时间戳文件夹对于单个、孤立的测试来说尚可，但在进行迭代开发，例如调整学习率、批量大小等超参数时，这些时间戳几乎不提供任何语义信息。如果不对日志目录进行规划，TensorBoard 界面很快就会充斥着难以辨认的时间戳文件夹，使得查找和对比特定实验变得异常困难。

通过显式设置 log_dir (例如 SummaryWriter('logs/experiment_A'), SummaryWriter('logs/experiment_B')) 或使用包含信息的 comment (例如 SummaryWriter(comment='_lr0.001_bs32'))，开发者可以创建一个人类可读的日志结构。这种结构化的日志使得在 TensorBoard 用户界面中快速选择和比较相关运行成为可能，直接提高了机器学习开发的流程效率，避免了手动将时间戳与实验配置进行交叉引用的麻烦。

代码示例 (初始化 SummaryWriter):

from torch.utils.tensorboard import SummaryWriter

# 选项 1: 默认日志目录 (./runs/TIMESTAMPED_FOLDER/)
writer_default = SummaryWriter()

# 选项 2: 自定义日志目录
writer_custom_logdir = SummaryWriter("logs/my_first_experiment")

# 选项 3: 默认日志目录，但带有注释以便识别
# 会创建类似这样的目录: runs/May10_10-30-00_hostname_LR_0.01_BATCH_32/
writer_with_comment = SummaryWriter(comment="_LR_0.01_BATCH_32")

专业提示：使用层级化标签提升可读性 (例如, 'Loss/train')
- 数据点： 在标签 (tag) 中使用正斜杠 /（例如 "Loss/train", "Loss/test", "Accuracy/train", "Accuracy/test") 可以在 TensorBoard 用户界面中将图表按层级分组。
- 解释： 这种简单的命名约定能够极大地改善 TensorBoard 中标量图和其他图表的组织性，使得比较相关指标更为便捷。层级化标签不仅仅是一个美化功能，它更是一个强大的组织工具，能够反映实验的逻辑结构（例如，训练阶段 vs. 验证阶段，不同损失组件等），使得 TensorBoard 仪表盘能够直观地体现实验设计。若不使用层级标签，所有标量都会显示在 TensorBoard 的顶层，导致一个冗长且未分化的列表（例如，"train_loss", "val_loss", "train_acc", "val_acc"）。而使用如 "Loss/train" 和 "Loss/test" 2 这样的标签，则会在 TensorBoard 中创建一个可折叠的 "Loss" 部分，其中包含训练和测试的图表。这种分组方式使得比较相关指标变得更加容易（例如，可以快速查看训练损失是否在下降而验证损失是否在上升，从而判断是否过拟合）。这直接增强了 TensorBoard 所承诺的“可理解性”和“调试”能力。
- 代码示例 (层级化标签):
```
# 在你的训练循环中:
# writer.add_scalar('Loss/train', training_loss, epoch)
# writer.add_scalar('Loss/validation', validation_loss, epoch)
# writer.add_scalar('Accuracy/train', training_accuracy, epoch)
# writer.add_scalar('Accuracy/validation', validation_accuracy, epoch)
```

B. `SummaryWriter` 核心日志记录方法详解及示例

SummaryWriter 提供了多种方法来记录不同类型的数据。以下表格总结了最核心的几种方法：

表 1: 核心 SummaryWriter 日志记录方法

SummaryWriter 方法	记录的数据类型	简要描述及使用场景
`add_scalar`	单个数值	追踪损失、准确率、学习率等指标随时间的变化。
`add_scalars`	多个数值	将相关的标量（如训练/验证损失）分组到同一个图表中。
`add_image`	单个图像张量	可视化输入数据、特征图或生成的图像。
`add_images`	一批图像张量	可视化多个图像，通常以网格形式展示。
`add_graph`	模型架构	查看 `nn.Module` 的计算图。
`add_histogram`	值的分布	监控权重、偏置、梯度或激活值的分布。

接下来，我们将结合 PyTorch 代码示例详细介绍这些核心方法的使用。

1. 追踪指标: `add_scalar` & `add_scalars`

add_scalar 和 add_scalars 是监控模型训练进度的基石，用于记录单个或多个标量值，如损失、准确率、学习率等。

数据点：
- add_scalar(tag, scalar_value, global_step): 记录单个标量值。tag 是数据标识符，scalar_value 是要保存的值，global_step 是记录的全局步数值（例如，epoch 或 iteration），它对于在 x 轴上绘图至关重要。
- add_scalars(main_tag, tag_scalar_dict, global_step): 在 main_tag 下将多个标量记录到同一个图表中。tag_scalar_dict 是一个字典，键是子标签，值是对应的标量值。
解释：

在训练循环中，可以使用这些方法记录关键指标。global_step 参数至关重要，它决定了 TensorBoard 图表中的 x 轴。使用一致且有意义的 global_step（如总迭代次数或轮次数）可以确保 TensorBoard 能够正确地绘制趋势图，并对齐以不同频率记录的不同指标。不一致的 global_step 会导致误导性的可视化结果。

例如，如果在每次迭代时记录损失，global_step 应该是迭代编号；如果在每个 epoch 结束时记录，则应该是 epoch 编号。如果不同的指标使用了不一致的 global_step 方案（例如，一个按迭代记录，另一个按 epoch 记录，但使用了相同的标签或一起绘制），TensorBoard 图表将会错位且难以解读。一种常见的细粒度迭代级日志记录方法是使用 epoch * len(dataloader) + batch_idx 作为 global_step，这提供了一个在所有 epoch 中单调递增的步数，确保所有迭代级别的图表都是可比较的。

代码示例 (训练循环中使用 add_scalar 和 add_scalars):

import torch
import torch.nn as nn
import torch.optim as optim
from torch.utils.tensorboard import SummaryWriter
import numpy as np # 用于 [3, 10] 示例

# 虚拟模型、数据集和数据加载器
model = nn.Linear(10, 1)
criterion = nn.MSELoss()
optimizer = optim.SGD(model.parameters(), lr=0.01)
dummy_data = [(torch.randn(10), torch.randn(1)) for _ in range(100)]
train_loader = torch.utils.data.DataLoader(dummy_data, batch_size=10)

# 初始化 SummaryWriter
writer = SummaryWriter(comment="_simple_scalar_example")

num_epochs = 20
for epoch in range(num_epochs):
    epoch_loss = 0.0
    num_batches = 0
    for i, (inputs, labels) in enumerate(train_loader):
        optimizer.zero_grad()
        outputs = model(inputs)
        loss = criterion(outputs, labels)
        loss.backward()
        optimizer.step()

        epoch_loss += loss.item()
        num_batches += 1

        # 使用 add_scalar 记录每次迭代 (batch) 的损失
        # global_step 可以是 epoch * len(train_loader) + i
        current_iter = epoch * len(train_loader) + i
        writer.add_scalar('Loss/iteration', loss.item(), current_iter) # [1, 2, 17]

    avg_epoch_loss = epoch_loss / num_batches
    # 使用 add_scalar 记录平均 epoch 损失
    writer.add_scalar('Loss/epoch_avg', avg_epoch_loss, epoch) # [1, 2, 17]

    # add_scalars 示例: 记录虚拟的训练和验证损失
    # 在实际场景中，你会计算真实的验证损失
    writer.add_scalars('Loss/epoch_comparison', {
        'train': avg_epoch_loss,
        'validation': np.random.random() # 虚拟验证损失
    }, epoch) # [2, 10, 15]

    print(f"Epoch [{epoch+1}/{num_epochs}], Loss: {avg_epoch_loss:.4f}")

writer.close()

2. 可视化图像: `add_image` & `add_images`

在计算机视觉任务中，可视化图像数据（如输入样本、模型生成的图像或注意力图）对于理解模型行为非常有帮助。

数据点：
- add_image(tag, img_tensor, global_step, dataformats='CHW'): 记录单个图像。img_tensor 通常是 (C, H, W) 或 (1, C, H, W) 形状。
- add_images(tag, img_tensor, global_step, dataformats='NCHW'): 记录一批图像。img_tensor 通常是 (N, C, H, W) 形状。
- torchvision.utils.make_grid 常用于从一批图像创建网格，以便通过 add_image 进行记录。
- 如果图像张量不是默认的 CHW/NCHW 格式，dataformats 参数非常重要。
解释：

图像归一化和 dataformats 是常见的痛点。未经适当归一化（例如，归一化到 ` ` 范围）记录的图像可能在 TensorBoard 中显示不正确。同样，张量维度与 dataformats 参数不匹配将导致错误或误解。

add_image 期望接收张量，通常是归一化后的张量（3 提到了 transforms.Normalize，18 也使用了它）。如果像素值超出了预期范围（例如，0-255，或者根据 make_grid 或 add_image 显示时的期望范围是 -1 到 1），可视化结果可能会被裁剪或看起来像噪声。

dataformats 参数（例如，'CHW', 'HWC', 'NCHW'）告诉 TensorBoard 如何解释图像张量的维度。PyTorch 通常使用 NCHW 格式。如果传递了一个 HWC 格式的图像而没有指定 dataformats='HWC'，TensorBoard 可能会将通道数误解为批次大小，反之亦然。

代码示例 (记录一批图像):

import torch
import torchvision
from torch.utils.tensorboard import SummaryWriter
from torchvision import datasets, transforms

# 初始化 SummaryWriter
writer = SummaryWriter(comment="_image_example")

# 加载一个样本数据集 [1, 18]
transform = transforms.Compose()
train_set = datasets.FashionMNIST(
    root='./data', train=True, download=True, transform=transform
)
train_loader = torch.utils.data.DataLoader(train_set, batch_size=16, shuffle=True)

# 获取一批图像和标签
images, labels = next(iter(train_loader))

# 使用 torchvision.utils.make_grid 创建图像网格
img_grid = torchvision.utils.make_grid(images) # [1, 2, 18]

# 使用 add_image 记录图像网格
# (如果 images 已经是 NCHW 批次格式，也可以直接使用 add_images)
writer.add_image('FashionMNIST_Input_Samples', img_grid, 0) # [1, 18]

# 从批次中记录单个图像的示例 (使用 add_images)
# writer.add_images('Individual_FashionMNIST_Samples', images, 0) # [2]

# HWC 格式示例 (如果你的图像是该格式)
# img_hwc = images.permute(0, 2, 3, 1) # 将 NCHW 转换为 NHWC
# writer.add_images('FashionMNIST_HWC_Samples', img_hwc, 1, dataformats='NHWC') # [2, 10]

writer.close()

3. 理解你的模型架构: `add_graph`

add_graph 方法可以将 PyTorch 模型的计算图写入 TensorBoard，帮助开发者可视化网络结构、层与层之间的连接以及数据的流向。

数据点： add_graph(model, input_to_model) 记录模型图。它需要模型本身（一个 nn.Module 对象）和一个符合模型期望输入尺寸的样本输入张量。
解释：

add_graph 通过一个样本输入来追踪模型。如果模型具有依赖于输入值（不仅仅是形状）的动态控制流，那么追踪到的图可能只代表一个执行路径。对于复杂的模型，特别是那些具有字典输出或非张量输出的模型，add_graph 可能需要模型包装器或对输出进行仔细处理。

add_graph 通过使用提供的 input_to_model 对模型进行即时编译 (JIT) 追踪来工作。这个追踪过程捕获了针对该特定输入形状和类型执行的操作。如果模型的架构根据输入值而改变（例如，基于张量内容的 if 条件），计算图将只显示为样本输入所采取的路径。

代码示例 (记录模型图):

import torch
import torch.nn as nn
import torchvision.models as models
from torch.utils.tensorboard import SummaryWriter

# 初始化 SummaryWriter
writer = SummaryWriter(comment="_graph_example")

# 定义一个简单的 CNN 模型 [1]
class SimpleCNN(nn.Module):
    def __init__(self):
        super(SimpleCNN, self).__init__()
        self.conv1 = nn.Conv2d(1, 6, 5) # 假设输入为 1 通道 (例如灰度图)
        self.pool = nn.MaxPool2d(2, 2)
        self.conv2 = nn.Conv2d(6, 16, 5)
        # 根据卷积和池化后的输入图像大小调整 4*4
        self.fc1 = nn.Linear(16 * 4 * 4, 120)
        self.fc2 = nn.Linear(120, 84)
        self.out = nn.Linear(84, 10)

    def forward(self, x):
        x = self.pool(torch.relu(self.conv1(x)))
        x = self.pool(torch.relu(self.conv2(x)))
        x = x.view(-1, 16 * 4 * 4) # 展平
        x = torch.relu(self.fc1(x))
        x = torch.relu(self.fc2(x))
        x = self.out(x)
        return x

model = SimpleCNN()

# 创建一个虚拟输入张量 (batch_size, channels, height, width)
# 对于 FashionMNIST (28x28 灰度图) 如 [1] 中所用
# 经过 conv1 (kernel 5, stride 1, no padding): 28-5+1 = 24. 经过 pool (kernel 2, stride 2): 12
# 经过 conv2 (kernel 5, stride 1, no padding): 12-5+1 = 8. 经过 pool (kernel 2, stride 2): 4
# 因此，对于 28x28 输入，16 * 4 * 4 是正确的。
dummy_input = torch.randn(1, 1, 28, 28) # [1, 3] 使用一批图像

# 记录模型图
writer.add_graph(model, dummy_input) # [1, 2, 3, 18]

# torchvision 模型示例
# resnet_model = models.resnet18()
# dummy_resnet_input = torch.randn(1, 3, 224, 224) # ResNet 典型输入
# writer.add_graph(resnet_model, dummy_resnet_input) # [2, 3]

writer.close()

4. 监控参数分布: `add_histogram`

add_histogram 方法用于记录张量中数值的分布情况，这对于监控模型权重、偏置、梯度或激活值的变化非常有用，有助于检测梯度消失/爆炸、神经元死亡等潜在问题。

数据点： add_histogram(tag, values, global_step) 记录张量值的直方图。values 是包含要构建直方图的值的张量。
解释：

可以通过迭代 model.named_parameters() 来记录所有可学习参数的直方图。然而，在每一步都为所有参数记录直方图可能会非常耗时，并且会生成庞大的日志文件。更实际的做法是降低记录频率（例如，每个 epoch 或每 N 次迭代记录一次），或者只针对模型中特定的、感兴趣的层进行记录。

add_histogram 需要处理张量中的所有值来计算分箱计数。现代深度学习模型可能拥有数百万甚至数十亿的参数。在每次训练迭代（批处理）中遍历所有参数及其梯度，并将这些可能很大的分布写入磁盘，会显著减慢训练速度并导致非常大的事件文件。示例是每个 epoch 记录一次直方图。建议 weight_histograms 也可以按 epoch 调用。因此，一个实用的建议是对记录直方图的内容和频率进行选择，以平衡获取详细洞察的需求与性能开销。

代码示例 (记录权重和偏置的直方图):

import torch
import torch.nn as nn
from torch.utils.tensorboard import SummaryWriter

# 复用 add_graph 示例中的 SimpleCNN
class SimpleCNN(nn.Module):
    def __init__(self):
        super(SimpleCNN, self).__init__()
        self.conv1 = nn.Conv2d(1, 6, 5)
        self.pool = nn.MaxPool2d(2, 2)
        self.conv2 = nn.Conv2d(6, 16, 5)
        self.fc1 = nn.Linear(16 * 4 * 4, 120)
        self.fc2 = nn.Linear(120, 84)
        self.out = nn.Linear(84, 10)
    def forward(self, x): # 虚拟前向传播
        x = self.pool(torch.relu(self.conv1(x)))
        x = self.pool(torch.relu(self.conv2(x)))
        x = x.view(-1, 16 * 4 * 4)
        x = torch.relu(self.fc1(x))
        x = torch.relu(self.fc2(x))
        x = self.out(x)
        return x

model = SimpleCNN()
writer = SummaryWriter(comment="_histogram_example")

# 用于演示的虚拟训练循环
optimizer = torch.optim.SGD(model.parameters(), lr=0.01)
criterion = nn.CrossEntropyLoss() # 假设是分类任务
dummy_input = torch.randn(4, 1, 28, 28) # 批大小为 4
dummy_labels = torch.randint(0, 10, (4,))

for epoch in range(5): # 每个 epoch 记录一次直方图
    # 虚拟训练步骤
    optimizer.zero_grad()
    outputs = model(dummy_input)
    loss = criterion(outputs, dummy_labels)
    loss.backward()
    optimizer.step()

    # 记录权重和偏置的直方图
    for name, param in model.named_parameters():
        if param.requires_grad:
            writer.add_histogram(f'Weights/{name}', param.data, epoch) # [1, 23]
            if param.grad is not None: # 梯度可能在第一次反向传播前或非训练状态下不存在
                 writer.add_histogram(f'Gradients/{name}', param.grad.data, epoch) # [1] (修改后用于梯度)

    print(f"Epoch {epoch+1} completed, histograms logged.")

writer.close()

C. 确保数据完整性: `writer.flush()` 和 `writer.close()`

为了确保所有记录的数据都被正确保存到磁盘，SummaryWriter 提供了 flush() 和 close() 方法。

数据点：
- writer.flush(): 强制将所有待处理的事件写入磁盘。SummaryWriter 的构造函数有一个 flush_secs 参数（默认为 120 秒），用于控制自动刷新的频率。
- writer.close(): 刷新待处理的事件并关闭写入器。应在完成日志记录后调用。
解释：

这些方法对于确保数据被成功保存至关重要，尤其是在训练被意外中断或需要实时查看 TensorBoard 日志的情况下。不调用 writer.close() 或 writer.flush() 是导致 TensorBoard 中出现“无数据”的一个常见原因，因为数据可能仍保留在缓冲区中而未写入磁盘，特别是在脚本过早终止时。

SummaryWriter 为了提高效率，会先将事件缓冲在内存中，然后再写入磁盘。如果脚本在缓冲区被刷新（无论是通过 flush_secs 自动刷新还是通过 flush()/close() 手动刷新）之前结束或崩溃，最新的数据将不会出现在事件文件中。忘记调用 flush() 或 close() 可能导致“无数据”或“没有活动的仪表盘”错误。因此，在训练结束时显式调用 writer.close()，以及在长时间运行时定期调用 writer.flush()，对于数据完整性和可靠的可视化至关重要。

D. 其他日志记录功能简介

除了上述核心方法外，SummaryWriter 还支持记录其他类型的数据，以满足更丰富的可视化需求。

数据点：
- add_text(tag, text_string, global_step): 记录文本信息，可用于保存实验笔记、配置参数等。
- add_embedding(features, metadata, label_img, global_step, tag): 可视化高维数据（如词嵌入、图像特征）在低维空间的投影，通常在 TensorBoard 的 Projector 标签页显示。
- add_figure(tag, figure, global_step): 记录 Matplotlib 图表。
- add_video(tag, vid_tensor, global_step, fps): 记录视频数据。
- add_audio(tag, snd_tensor, global_step, sample_rate): 记录音频数据。
- add_pr_curve(tag, labels, predictions, global_step): 记录精确率-召回率曲线 (Precision-Recall Curve)，用于评估分类模型性能。
- add_mesh(tag, vertices, colors, faces, global_step): 记录 3D 点云或网格数据。
解释：

这些方法为特定类型的可视化需求提供了支持。例如，add_text 可以用来记录超参数配置或训练过程中的重要注释。add_embedding 对于理解高维特征的结构特别有用。

代码示例 (简要 add_text 和 add_embedding):

# writer.add_text('Experiment_Notes', 'This run uses Adam optimizer with LR=0.001.', 0) # [22]

# 对于 add_embedding [18]
# 假设 'features_tensor' 是 (N_samples, N_features)
# 'metadata_list' 是一个包含 N_sample 个标签的列表
# 'label_images_tensor' 是 (N_samples, C, H, W)
# writer.add_embedding(features_tensor, metadata=metadata_list, label_img=label_images_tensor, global_step=epoch)

III. TensorBoard 命令行：你的可视化控制中心

当 SummaryWriter 将数据写入日志文件后，需要通过 TensorBoard 的命令行工具来启动其 Web 服务，从而在浏览器中查看可视化结果。

A. 启动 TensorBoard：基础操作

启动 TensorBoard 的核心命令非常简单。

数据点： 主要命令是 tensorboard --logdir <path_to_your_runs_folder> 。执行后，TensorBoard 通常会在 http://localhost:6006 上提供服务。
解释： 你需要从终端启动 TensorBoard，并将其指向 SummaryWriter 保存事件文件的目录。TensorBoard 会递归扫描 logdir 以查找事件文件。这意味着你可以将其指向一个包含多个实验子目录的父目录，TensorBoard 将自动检测这些不同的“运行”并允许进行比较。 --logdir 参数指定了日志的根目录。TensorBoard 的设计是“递归地遍历以 logdir 为根的目录树，查找包含 tfevents 数据的子目录”，并“将其作为新的运行加载” 。这种递归扫描是比较多个实验（例如，不同的超参数集、模型架构）的关键，只需将它们组织到通用 logdir 根目录下的子文件夹中即可 34。这与需要单独指定每个运行相比，使得多运行分析更为简单。

B. PyTorch 用户常用的 CLI 参数

TensorBoard 提供了多个命令行参数来定制其行为。

表 2: TensorBoard 核心 CLI 参数

CLI 参数	目的	PyTorch 用户示例用法
`--logdir PATH`	指定包含事件日志的目录（可以是一个或多个）	`tensorboard --logdir runs/my_pytorch_experiment`
`--port PORT`	设置 TensorBoard 运行的端口（默认为 6006）	`tensorboard --logdir runs --port 6007`
`--host HOST_IP`	设置 TensorBoard 绑定的主机 IP（默认为 localhost）	`tensorboard --logdir runs --host 0.0.0.0`
`--bind_all`	绑定到所有网络接口（等同于 --host 0.0.0.0）	`tensorboard --logdir runs --bind_all`
`--reload_interval SEC`	数据重新加载的频率（单位：秒，默认为 5 或 60）	`tensorboard --logdir runs --reload_interval 30`
`--help`	显示所有可用的 CLI 选项	`tensorboard --help`

1. `--logdir`: 指定日志位置 (单个, 多个, 命名)

数据点：
- 单个目录: tensorboard --logdir runs/experiment_A 。
- 包含多个运行的父目录: tensorboard --logdir runs_parent_folder/ 。
- 多个逗号分隔的目录（旧版，或用于特定比较）：tensorboard --logdir_spec run1:/path/to/logs/1,run2:/path/to/logs/2 。注意：--logdir_spec 在较新的文档中通常不被推荐，但 --logdir name1:/path1,name2:/path2 可能仍被支持或历史上曾被支持 34。对于多个不同的运行，最稳健的方法通常是使用不同的 SummaryWriter 实例写入到共享父目录下的不同子目录中，然后将该父目录传递给 --logdir。
解释： 虽然 --logdir_spec 或在 --logdir 中使用命名路径为比较分散的日志位置提供了明确的控制，但对于 PyTorch 用户而言，最常见且通常最简单的方法是将实验组织到共享根目录下的子目录中，并使用指向该根目录的单个 --logdir。这利用了 TensorBoard 的递归扫描功能。 TensorBoard 对 logdir 的递归扫描是其多运行比较的核心功能。为每个实验变体（例如，不同的超参数）创建单独的 SummaryWriter 实例，并将日志记录到不同的子文件夹（例如，runs/lr0.01/，runs/lr0.001/）是 PyTorch 中一种自然的工作流程。然后，通过指向 tensorboard --logdir runs/ 即可自动加载所有这些变体。虽然 --logdir_spec 或 name1:/path1,... 为分散在文件系统中的日志提供了更细致的控制，但它们输入起来可能更麻烦，并且有时被标记为旧版或不推荐使用。对于典型的 PyTorch 项目结构，子目录方法通常更为直接。

2. `--port`: 避免冲突和自定义端口选择

数据点： 默认端口是 6006 。如果 6006 端口已被占用或需要运行多个 TensorBoard 实例，可以使用 --port <NUMBER> (例如, --port 6007) 来指定不同的端口。
解释： 端口冲突是一个常见的小麻烦。了解 --port 对于在本地运行多个服务或多个 TensorBoard 实例的用户至关重要。默认的 6006 端口广为人知。如果另一个应用程序（或其他 TensorBoard 实例）已在使用端口 6006，新的 TensorBoard 实例将无法启动或尝试使用下一个可用端口。如果运行过多的 TensorBoard 进程，默认扫描范围内的所有端口都可能不可用，此时必须使用 --port 参数。因此，--port 是一个实用的故障排除和配置工具。

3. `--host` & `--bind_all`: 网络和远程访问

数据点：
- 默认主机是 localhost (127.0.0.1)，这意味着 TensorBoard 只能从本地机器访问。
- --host 0.0.0.0 或 --bind_all 使 TensorBoard 可以从网络上的其他机器访问。这通常需要配置防火墙。
解释： 这些选项允许从其他设备访问 TensorBoard，这对于在远程服务器上运行 TensorBoard 至关重要。但需要注意安全问题，例如，对于安全的远程访问，应与 SSH 隧道结合使用。--bind_all 或 --host 0.0.0.0 对于在远程服务器（例如云虚拟机、实验室服务器）上运行 TensorBoard 并从本地机器的浏览器查看是必需的。但它几乎总是应该与安全措施（如 SSH 端口转发或 VPN）结合使用，因为它会将 TensorBoard 实例暴露给网络。 TensorBoard 默认为 localhost 以确保安全，防止意外的网络暴露。要访问在远程机器上运行的 TensorBoard，它必须侦听一个外部可访问的 IP 地址。--bind_all（或 --host 0.0.0.0）可以实现这一点。然而，这使得 TensorBoard 实例可能对网络上任何能够访问服务器 IP 和端口的人可见。SSH 端口转发是访问远程 TensorBoard 的推荐安全方法。在这种设置中，远程机器上的 TensorBoard通常仍然可以在 localhost 上运行，SSH 安全地隧道化连接。如果在远程服务器上使用 --bind_all，SSH 隧道仍然通过不将端口直接暴露给公共互联网（如果服务器本身有防火墙）来增加一层安全性。关键在于，网络可访问性选项必须谨慎使用，并采取适当的安全措施。

4. `--reload_interval`: 控制数据刷新频率

数据点： 设置 TensorBoard 从 logdir 重新加载数据的频率（单位：秒）。默认值通常是 5 秒（对于 R 语言接口是 5 秒 33，14 也提到 5 秒）或 60 秒。设置为 0 则只在启动时加载一次。
解释： 调整 reload_interval 可以在近乎实时更新和系统负载之间取得平衡，特别是当 logdir 位于较慢或远程的文件系统上时。TensorBoard 会定期重新扫描 logdir 以获取新数据。频繁的重新加载（较小的 reload_interval）可以提供更新的可视化，但会增加存储日志的系统的 I/O 负载。如果日志位于网络共享或慢速磁盘上，过于频繁的重新加载可能效率低下。将 reload_interval 设置为 0 对于分析静态的、已完成的实验日志（预计不会有新数据）非常有用。用户可以根据他们对响应速度与资源使用的需求来调整此参数。

5. `--help`: 内置命令参考

数据点： tensorboard --help 显示所有可用的 CLI 参数及其描述。
解释： 鼓励用户将其作为探索更高级选项的第一步。

C. 在 Jupyter Notebook 和远程设置中使用 TensorBoard (SSH 隧道)

TensorBoard 不仅限于本地命令行启动，也可以方便地集成到 Jupyter Notebook 中，或通过 SSH 隧道进行安全的远程访问。

数据点：
- Jupyter Notebook: 使用魔法命令 %load_ext tensorboard 加载 TensorBoard 扩展，然后使用 %tensorboard --logdir <log_folder> 启动 TensorBoard 。
- 远程访问 (SSH 隧道):
  1. 在本地机器上执行命令 ssh -L local_port:localhost:remote_port user@remote_server 来建立 SSH 隧道。例如 ssh -L 16006:localhost:6006 user@remote_server 。
  2. 在远程服务器上运行 tensorboard --logdir <path> --port remote_port。
  3. 在本地浏览器的地址栏输入 http://localhost:local_port 即可访问远程 TensorBoard 。
解释： SSH 隧道是访问在远程服务器上运行的 TensorBoard（以及 Jupyter Notebook）的标准安全方法，避免了将这些服务直接暴露到互联网上。在远程服务器（实验室服务器、云服务器）上运行机器学习实验是很常见的。如果未正确配置防火墙，直接使用 --bind_all 暴露 TensorBoard 或 Jupyter 等服务可能存在安全风险。SSH 提供了一个安全的加密通道。端口转发（-L 选项）允许将本地机器上的一个端口映射到远程机器上的一个端口，该端口只能通过 SSH 隧道访问。这意味着远程服务器上的 TensorBoard 通常可以绑定到 localhost（其默认且更安全的设置），而本地机器通过 localhost:local_port 访问它，SSH 负责安全传输。这是远程开发和监控中广泛采用的最佳实践。

D. 其他有用的 CLI 参数简介

除了上述核心参数外，TensorBoard 还提供了一些其他有用的标志位。

数据点：
- --purge_orphaned_data=TRUE (在某些上下文如 R 语言接口中默认为 TRUE 33) 或 FALSE: 是否清除由于 TensorBoard 重启可能产生的孤立数据。禁用此选项有助于调试数据丢失问题。
- --max_reload_threads (或 processes): 用于重新加载运行的最大线程数。
- --window_title: 为 TensorBoard 窗口设置自定义标题
解释： 简要提及这些更高级或实用性的标志位，供用户进一步探索。

IV. 实战演练：一个完整的 PyTorch 与 TensorBoard 集成示例

理论结合实践是掌握新工具的最佳途径。下面提供一个完整的 PyTorch 训练脚本，演示如何集成 TensorBoard 来记录关键信息，并指导如何启动 TensorBoard 查看结果。

A. 简明的端到端 PyTorch 训练脚本

import torch
import torch.nn as nn
import torch.optim as optim
import torchvision
import torchvision.transforms as transforms
from torch.utils.tensorboard import SummaryWriter
from torch.utils.data import DataLoader

# 1. 定义模型 [1]
class SimpleCNN(nn.Module):
    def __init__(self):
        super(SimpleCNN, self).__init__()
        self.conv1 = nn.Conv2d(1, 6, 5) # FashionMNIST 是灰度图，所以输入通道为 1
        self.pool = nn.MaxPool2d(2, 2)
        self.conv2 = nn.Conv2d(6, 16, 5)
        # 对于 28x28 输入:
        # 第一次卷积 (5x5): (28-5)/1 + 1 = 24 -> 池化 (2x2, stride 2): 12
        # 第二次卷积 (5x5): (12-5)/1 + 1 = 8  -> 池化 (2x2, stride 2): 4
        # 所以展平后是 16 * 4 * 4
        self.fc1 = nn.Linear(16 * 4 * 4, 120)
        self.fc2 = nn.Linear(120, 84)
        self.out = nn.Linear(84, 10) # FashionMNIST 有 10 个类别

    def forward(self, x):
        x = self.pool(torch.relu(self.conv1(x)))
        x = self.pool(torch.relu(self.conv2(x)))
        x = x.view(-1, 16 * 4 * 4)
        x = torch.relu(self.fc1(x))
        x = torch.relu(self.fc2(x))
        x = self.out(x)
        return x

# 2. 准备数据 [1]
transform = transforms.Compose()

train_set = datasets.FashionMNIST(
    root='./data', train=True, download=True, transform=transform
)
train_loader = DataLoader(train_set, batch_size=64, shuffle=True)

# 3. 初始化 SummaryWriter
# 使用 comment 来更好地区分实验
writer = SummaryWriter(log_dir="runs/fashion_mnist_experiment", comment="_cnn_final_example")

# 4. 实例化模型、损失函数和优化器
model = SimpleCNN()
criterion = nn.CrossEntropyLoss()
optimizer = optim.Adam(model.parameters(), lr=0.001)

# 5. 记录模型图 (只需要一次)
# 获取一批数据用于 add_graph
dataiter = iter(train_loader)
images_for_graph, _ = next(dataiter)
writer.add_graph(model, images_for_graph) # [1, 3]
writer.flush() # 确保图被写入

# 6. 训练循环
num_epochs = 5
running_loss_interval = 100 # 每 100 个 batch 记录一次迭代损失

for epoch in range(num_epochs):
    epoch_total_loss = 0.0
    epoch_total_correct = 0
    num_samples_epoch = 0

    for i, (inputs, labels) in enumerate(train_loader):
        optimizer.zero_grad()
        outputs = model(outputs)
        loss = criterion(outputs, labels)
        loss.backward()
        optimizer.step()

        epoch_total_loss += loss.item() * inputs.size(0)
        _, predicted = torch.max(outputs.data, 1)
        epoch_total_correct += (predicted == labels).sum().item()
        num_samples_epoch += labels.size(0)

        # 记录迭代损失 (每 running_loss_interval 次)
        if (i + 1) % running_loss_interval == 0:
            current_iter = epoch * len(train_loader) + i
            avg_iter_loss = loss.item() # 当前 batch 的损失
            writer.add_scalar('Loss/iteration', avg_iter_loss, current_iter) # [1]

    # 计算并记录 Epoch 级别的损失和准确率
    avg_epoch_loss = epoch_total_loss / num_samples_epoch
    epoch_accuracy = epoch_total_correct / num_samples_epoch
    writer.add_scalar('Loss/train_epoch', avg_epoch_loss, epoch)
    writer.add_scalar('Accuracy/train_epoch', epoch_accuracy, epoch)

    # 记录模型参数的直方图 (每个 epoch 结束时)
    for name, param in model.named_parameters():
        if param.requires_grad:
            writer.add_histogram(f'Weights/{name}', param.data, epoch) # [1]
            if param.grad is not None:
                writer.add_histogram(f'Gradients/{name}', param.grad.data, epoch)

    # 记录一批输入图像 (每个 epoch 记录第一批)
    if epoch == 0: # 或者根据需要定期记录
        img_grid = torchvision.utils.make_grid(inputs) # 使用当前 epoch 的最后一批输入
        writer.add_image('Training_Input_Samples_Epoch_' + str(epoch), img_grid, epoch) # [1]

    print(f"Epoch [{epoch+1}/{num_epochs}], Loss: {avg_epoch_loss:.4f}, Accuracy: {epoch_accuracy:.4f}")

# 7. 关闭 SummaryWriter
writer.close()
print("Training finished. TensorBoard logs saved to runs/fashion_mnist_experiment...")

B. 启动 TensorBoard 查看结果的步骤指南

一个包含完整代码的、可运行的示例是帮助用户快速掌握实际应用并验证其理解的最有效方法。它弥合了孤立的 API 解释与实际使用之间的差距。

将上述脚本保存为 pytorch_tensorboard_example.py。
从终端运行脚本: python pytorch_tensorboard_example.py。
训练完成后，启动 TensorBoard，确保 --logdir 指向脚本中 SummaryWriter 指定的路径（或其父目录）：
```
tensorboard --logdir runs/fashion_mnist_experiment
```
（如果 SummaryWriter 中使用了 comment，实际路径可能包含该 comment，例如 runs/fashion_mnist_experiment_cnn_final_example，或者如果 log_dir 直接指定为 runs/fashion_mnist_experiment，则直接使用该路径。）
打开你的网络浏览器，访问 TensorBoard 终端输出中显示的地址，通常是 http://localhost:6006。
在 TensorBoard 界面中，你现在可以浏览 SCALARS（标量）、IMAGES（图像）、GRAPHS（计算图）和 HISTOGRAMS（直方图）等选项卡，查看记录的训练信息。

通过这个端到端的示例，你可以直观地看到 SummaryWriter 的各种方法如何在实际训练流程中协同工作，以及如何通过 TensorBoard 命令行启动服务并查看结果。

V. PyTorch 与 TensorBoard 集成常见问题排查

在使用 TensorBoard 与 PyTorch 集成时，可能会遇到一些常见问题。了解这些问题的根源和解决方法，可以帮助你更顺畅地进行可视化。许多“TensorBoard 不工作”的问题源于 PyTorch 写入日志的方式/位置（SummaryWriter 的 log_dir、flush/close 调用）与 TensorBoard 读取日志的方式/位置（tensorboard --logdir 路径、时间）之间的不匹配。

A. "TensorBoard not found" / 安装问题
- 数据点： 确保 TensorBoard 已通过 pip install tensorboard 正确安装，并且在当前环境中可以访问（可通过 tensorboard --version 检查）。如果命令失败，检查系统的 PATH 环境变量设置。
- 解释： 这是最基础的问题，通常是由于未安装 TensorBoard 或环境配置不当导致。
B. 日志目录问题
- 数据点： 如果在 SummaryWriter 中指定了 log_dir，请确保该目录存在且具有写入权限；如果使用默认的 runs/ 目录，请确保程序有权限创建它。TensorBoard 启动时的 --logdir 参数必须指向正确的日志存储位置。
- 解释： 路径错误或权限问题是导致 TensorBoard 无法找到日志文件的常见原因。
C. TensorBoard 中 "No data" / "No dashboards are active"
- 数据点：
  - 确保在代码中调用了 writer.flush() 或 writer.close()，以强制将缓冲数据写入磁盘。
  - 核实数据是否以正确的间隔被记录（例如，如果只在 epoch 结束时记录，确保在训练过程完成后运行 TensorBoard。
  - TensorBoard 可能需要一些时间来加载新数据；检查 --reload_interval 设置或尝试刷新浏览器。
- 解释： 这是非常常见的问题。SummaryWriter 为了效率会缓冲数据，如果脚本在数据完全写入前终止，或者 TensorBoard 未能及时加载，就会出现此提示。
D. 端口已被占用 (Port Already in Use)
- 数据点： 如果默认端口 6006 已被其他程序占用，TensorBoard 可能启动失败或尝试使用其他端口。可以使用 --port <new_port> 指定一个新端口。
- 解释： 当系统中运行多个网络服务或多个 TensorBoard 实例时，容易发生端口冲突。
E. 计算图未显示或不正确
- 数据点： 确保传递给 add_graph 方法的样本输入张量具有正确的形状和类型，与模型期望的输入一致。如果模型输出复杂（例如字典类型），可能需要使用包装器 (wrapper) 来处理。
- 解释： add_graph 依赖于对模型的一次追踪运行，输入不匹配或输出格式不支持都可能导致问题。