企业官网建设流程全解析

Lightning Fabric 实验追踪与可视化实战：用fabric.log/fabric.log_dict记录指标并接入多 Logger

【免费下载链接】pytorch-lightningPretrain, finetune ANY AI model of ANY size on 1 or 10,000+ GPUs with zero code changes.项目地址: https://gitcode.com/gh_mirrors/py/pytorch-lightning

本篇技术指南以 Lightning Fabric 的日志记录（logging）机制为核心，讲解如何在自定义训练循环中通过Fabric.log与Fabric.log_dict记录标量指标、选择并配置TensorBoardLogger、CSVLogger、LitLogger、WandbLogger 等多种 Logger，以及在 TensorBoard 等面板中实时查看结果、控制日志频率和同时使用多个 Logger。读完本文，你将掌握一套可直接复制进 Fabric 训练循环的完整指标追踪方案，并理解其底层实现（rank-zero 日志、Tensor 自动转标量、自动版本号等）是如何工作的。

为什么需要追踪指标

在模型开发过程中，我们通常需要记录一些关心的数值（例如validation_loss），以此可视化模型的学习过程。Lightning 官方文档有一个非常形象的比喻：模型开发就像开一辆没有车窗的车，图表和日志就是让我们知道车该往哪儿开的"车窗"。

使用 Lightning Fabric，你可以可视化几乎任何想记录的内容：数字、文本、图片，乃至音频。其中，指标（metric）可视化是理解模型在整个开发过程中表现如何的最基础、也最强大的方式。

追踪指标：两步接入 Fabric

在 Lightning Fabric 中，指标记录只涉及两个步骤：选一个 Logger，然后在代码里调用log/log_dict。

Step 1：选择并配置 Logger

from lightning.fabric import Fabric from lightning.fabric.loggers import TensorBoardLogger # Pick a logger and add it to Fabric logger = TensorBoardLogger(root_dir="logs") fabric = Fabric(loggers=logger)

可供选择的 Logger 包括：

• TensorBoardLogger—— 官方推荐的本地 Logger，将日志以 TensorBoard 格式写入本地文件系统（实现位于 src/lightning/fabric/loggers/tensorboard.py）；
• CSVLogger—— 以 CSV 格式写入本地文件系统（实现位于 src/lightning/fabric/loggers/csv_logs.py）；
• LitLogger —— 对接 Lightning.ai 平台的实验追踪与产物管理（详见 docs/source-fabric/guide/loggers/litlogger.rst）；
• WandbLogger —— 对接 Weights & Biases 平台，支持图片、音频、视频等富媒体与 Artifact（详见 docs/source-fabric/guide/loggers/wandb.rst）。

所有内置 Logger 都从 src/lightning/fabric/loggers/logger.py 中的抽象基类Logger派生，统一实现log_metrics、log_hyperparams、log_graph、save、finalize等接口，因此切换 Logger 时无需改动训练循环里的记录代码。

Step 2：在代码中调用Fabric.log

value = ... # Python scalar or tensor scalar fabric.log("some_value", value)

如果需要一次性记录多个指标，使用Fabric.log_dict：

values = {"loss": loss, "acc": acc, "other": other} fabric.log_dict(values)

从源码看，Fabric.log本质上只是log_dict的单指标特例（见 src/lightning/fabric/fabric.py）：

def log(self, name: str, value: Any, step: Optional[int] = None) -> None: self.log_dict(metrics={name: value}, step=step) def log_dict(self, metrics: Mapping[str, Any], step: Optional[int] = None) -> None: metrics = convert_tensors_to_scalars(metrics) for logger in self._loggers: logger.log_metrics(metrics=metrics, step=step)

这里有三个值得注意的底层细节：

1. Tensor 自动脱离计算图并转成标量：传入的torch.Tensor会先经过convert_tensors_to_scalars（位于 src/lightning/fabric/utilities/apply_func.py）递归处理，自动调用.item()转成 Python 标量；如果 Tensor 含有多于一个元素，会抛出ValueError，提示无法转成标量。因此你不必担心记录的是"带梯度的 Tensor"。
2. 一次调用写所有 Logger：log_dict会遍历fabric上注册的全部 Logger，逐个调用其log_metrics，这正是"同时使用多个 Logger"能够零成本实现的原因。
3. step参数可选：大多数 Logger 实现会在每次调用时自动递增 step；你也可以显式传入自己的步数（例如以 epoch 或 global step 为基准）。

在 Dashboard 中查看日志

如何查看指标取决于你选择的 Logger，绝大多数 Logger 都提供可实时浏览所记录内容的 Dashboard。

以文档示例中的TensorBoardLogger为例，启动方式如下：

tensorboard --logdir=./logs

如果你的运行环境是 notebook（如 Google Colab、Kaggle 或 Jupyter），则使用以下魔法命令：

%reload_ext tensorboard %tensorboard --logdir=./logs

关于日志落盘位置，TensorBoardLogger的日志会写入os.path.join(root_dir, name, version)目录（name默认是lightning_logs），因此root_dir="logs"时，日志实际位于logs/lightning_logs/version_0/等路径下。若传入了sub_dir参数，还会继续在该目录下追加子目录（见 src/lightning/fabric/loggers/tensorboard.py）。CSVLogger则会在对应目录下生成metrics.csv文件，列名会按字典序排序并自动维护表头（见 tests/tests_fabric/loggers/test_csv.py）。

控制日志记录频率

如果在每一个迭代都记录指标，会显著拖慢训练速度。通过在循环中加入频率控制，可以大幅降低日志带来的额外开销：

for iteration in range(num_iterations): if iteration % log_every_n_steps == 0: value = ... fabric.log("some_value", value)

除了在应用层控制频率外，CSVLogger还提供了flush_logs_every_n_steps参数（默认 100），控制每隔多少步把内存中的指标刷写到磁盘（见 src/lightning/fabric/loggers/csv_logs.py 与 tests/tests_fabric/loggers/test_csv.py 的test_flush_n_steps用例）。TensorBoardLogger则可通过构造函数透传max_queue（flush 前待写日志的队列大小）和flush_secs（多少秒后强制 flush）等SummaryWriter关键字参数来控制刷盘时机。

同时使用多个 Logger

你可以在不改动训练循环中任何日志代码的前提下，同时挂载任意多个 Logger：

from lightning.fabric import Fabric from lightning.fabric.loggers import CSVLogger, TensorBoardLogger tb_logger = TensorBoardLogger(root_dir="logs/tensorboard") csv_logger = CSVLogger(root_dir="logs/csv") # Add multiple loggers in a list fabric = Fabric(loggers=[tb_logger, csv_logger]) # Calling .log() or .log_dict() always logs to all loggers simultaneously fabric.log("some_value", value)

常见组合是"TensorBoard 负责实时可视化 + CSV 负责轻量归档"，两者写盘互不干扰。由于Fabric.log_dict内部会遍历self._loggers逐个写入（见上文 src/lightning/fabric/fabric.py），因此无论挂几个 Logger，调用方式始终是同一个fabric.log。

深入源码：Logger 的关键行为与实现细节

只从 rank 0 记录，避免多进程重复写盘

在多卡（如 DDP）场景下，所有进程都会执行训练循环。若每个进程都写日志，会产出重复或损坏的日志文件。Fabric 通过@rank_zero_only与@rank_zero_experiment装饰器解决这一问题：只有全局 rank 0 的进程会真正写入指标，其余 rank 拿到的是一个_DummyExperiment（所有方法都是空操作，见 src/lightning/fabric/loggers/logger.py）。这体现在TensorBoardLogger.log_metrics、CSVLogger.log_metrics等实现均标注了@rank_zero_only（见 src/lightning/fabric/loggers/tensorboard.py、src/lightning/fabric/loggers/csv_logs.py）。

自动版本号与目录结构

两个内置 Logger 都实现了自动版本管理：不传version时，会扫描root_dir/name下已有的version_*目录，取最大版本号加一（见TensorBoardLogger._get_next_version与CSVLogger._get_next_version）。这也意味着不指定版本号时，多次运行会自动创建新的version_N目录，互不覆盖；而手动指定整数版本且目录中已存在该版本的指标文件时，会被覆盖并给出警告。相关行为在测试中有完整覆盖：

• tests/tests_fabric/loggers/test_csv.py：test_automatic_versioning、test_manual_versioning、test_named_version等；
• tests/tests_fabric/loggers/test_tensorboard.py：test_tensorboard_automatic_versioning、test_tensorboard_manual_versioning、test_tensorboard_named_version。

前缀与超参数记录

TensorBoardLogger和CSVLogger都支持prefix参数，会在所有指标 key 前统一添加前缀（连接符为-），用于区分同名指标（见 src/lightning/fabric/utilities/logger.py 的_add_prefix）。此外：

• TensorBoardLogger.log_hyperparams支持记录超参数，嵌套字典会被拍平为a/b形式的键（见 src/lightning/fabric/utilities/logger.py 的_flatten_dict），callable、Namespace、多维数组等非标量类型会被自动字符串化；default_hp_metric参数控制未显式传入指标时是否写入占位指标hp_metric。注意：TensorBoard 中"带超参数"与"不带超参数"的日志互不兼容，切换记录方式时需要清掉旧日志。
• CSVLogger目前不支持log_hyperparams，调用会直接抛出NotImplementedError（见 src/lightning/fabric/loggers/csv_logs.py 与 tests/tests_fabric/loggers/test_csv.py）。

延伸：接入云端平台 Logger

如果希望把指标同步到云端面板，Fabric 生态还提供两类 Logger：

• LitLogger（pip install litlogger）：自动检测 Lightning.ai 凭据，除了fabric.log/fabric.log_dict外，还支持log_hyperparams、log_model自动上传 checkpoint、log_file记录任意文件、save_logs捕获终端输出，并通过logger.url获取实验页面地址；
• WandbLogger（pip install wandb，先执行wandb login <your-api-key>）：从wandb.integration.lightning.fabric导入，配置project后即可复用同一套fabric.log调用，额外支持图片、文本、表格、Artifact 等富媒体记录。

两者的详细用法分别参见 docs/source-fabric/guide/loggers/litlogger.rst 与 docs/source-fabric/guide/loggers/wandb.rst。无论选用哪种，训练循环中的记录代码始终保持fabric.log/fabric.log_dict不变，这正是 Fabric 日志抽象的核心价值：记录逻辑与后端解耦，一行代码切换可视化平台。

【免费下载链接】pytorch-lightningPretrain, finetune ANY AI model of ANY size on 1 or 10,000+ GPUs with zero code changes.项目地址: https://gitcode.com/gh_mirrors/py/pytorch-lightning