企业官网建设流程全解析

• AI 技能
• 人工智能
• 大模型
• 深度学习

导读

本文是 AI-Research-SKILLs 仓库中 TensorBoard 技能 的框架集成专题，系统讲解如何将 TensorBoard 与 PyTorch、TensorFlow/Keras、PyTorch Lightning、HuggingFace Transformers、Fast.ai、JAX、scikit-learn 等主流 ML 框架无缝打通，在同一套可视化工作台下统一追踪标量指标、权重直方图、模型图、图片批次与超参数。阅读完本文，你将掌握各框架的推荐接入方式（SummaryWriter、tf.summary、TensorBoardLogger、report_to='tensorboard'、TensorBoardCallback等）、分布式训练下的日志收敛策略，以及一套跨框架可复用的命名规范与日志封装模式，并可在 references/integrations.md 中直接取用全部代码示例。

一、集成前的准备：安装与启动 TensorBoard

在任何框架接入之前，先完成 TensorBoard 自身的安装与启动。仓库中的 SKILL.md 给出了标准安装方式：

# 安装 TensorBoard 本体 pip install tensorboard # PyTorch 集成（SummaryWriter 依赖 torch 与 tensorboard） pip install torch torchvision tensorboard # TensorFlow 集成（TensorBoard 随 TensorFlow 一起分发） pip install tensorflow

启动可视化的方式是在任意日志根目录上运行：

tensorboard --logdir=runs # 浏览器访问 http://localhost:6006

核心约定是：所有框架最终都会向磁盘写入同一套 event 文件格式（PyTorch 通过SummaryWriter写runs/下的 event 文件，TensorFlow 通过tf.summary.create_file_writer写logs/下的 event 文件），TensorBoard 只负责聚合这些文件。这意味着即使多个实验来自不同框架，只要--logdir指向同一根目录，就能在同一个面板里横向对比——这是多框架团队共享实验看板的基础。

二、PyTorch 集成

2.1 基础集成：SummaryWriter 与训练循环

PyTorch 官方通过torch.utils.tensorboard.SummaryWriter与 TensorBoard 对接。最基础的用法是围绕训练循环插入日志点：

import torch import torch.nn as nn from torch.utils.tensorboard import SummaryWriter # 创建 writer writer = SummaryWriter('runs/pytorch_experiment') # 模型与优化器 model = ResNet50() optimizer = torch.optim.Adam(model.parameters(), lr=0.001) criterion = nn.CrossEntropyLoss() # 记录模型计算图 dummy_input = torch.randn(1, 3, 224, 224) writer.add_graph(model, dummy_input) # 训练循环 for epoch in range(100): model.train() train_loss = 0.0 for batch_idx, (data, target) in enumerate(train_loader): optimizer.zero_grad() output = model(data) loss = criterion(output, target) loss.backward() optimizer.step() train_loss += loss.item() # 按批次记录指标（每 100 个 batch 记录一次，避免日志爆炸） if batch_idx % 100 == 0: global_step = epoch * len(train_loader) + batch_idx writer.add_scalar('Loss/train_batch', loss.item(), global_step) # 按 epoch 记录指标 train_loss /= len(train_loader) writer.add_scalar('Loss/train_epoch', train_loss, epoch) # 记录权重直方图（用于诊断梯度消失/爆炸） for name, param in model.named_parameters(): writer.add_histogram(name, param, epoch) writer.close()

几个关键点：

• add_scalar(tag, value, global_step)的第三个参数是横轴刻度，建议用单调递增的全局步数而非批次内序号，保证曲线可对齐；
• add_graph(model, dummy_input)需要传入与真实输入同形状的dummy_input，TensorBoard 的 Graphs 页签会展示网络拓扑与张量形状；
• 关于标量、直方图、图、嵌入等更细的可视化能力（含激活直方图钩子、注意力图、嵌入投影器等），可继续阅读同仓库的 references/visualization.md。

2.2 torchvision 集成：记录图片批次

训练视觉模型时，把输入图片批次写入 TensorBoard，能直接肉眼检查数据增强是否合理、样本是否对齐：

from torchvision.utils import make_grid # 记录图片批次 for batch_idx, (images, labels) in enumerate(train_loader): if batch_idx == 0: # 只取第一个批次 img_grid = make_grid(images[:64], nrow=8) writer.add_image('Training_batch', img_grid, epoch) break

make_grid(images[:64], nrow=8)会把 64 张图拼成 8×8 网格，add_image将其写入 Images 页签，可拖动时间轴逐 epoch 回放。

2.3 分布式训练：仅由 rank 0 记录

使用DistributedDataParallel做多卡训练时，若每个进程都写 event 文件，会得到重复且相互覆盖的日志。标准做法是只在 rank 0 上创建 writer 并写日志：

import torch.distributed as dist from torch.nn.parallel import DistributedDataParallel as DDP # 初始化进程组 dist.init_process_group(backend='nccl') rank = dist.get_rank() # 仅 rank 0 创建 writer if rank == 0: writer = SummaryWriter('runs/distributed_experiment') model = DDP(model, device_ids=[rank]) for epoch in range(100): train_loss = train_epoch() # 仅 rank 0 写日志 if rank == 0: writer.add_scalar('Loss/train', train_loss, epoch)

注意train_epoch()内部的 loss 通常也要先dist.all_reduce或使用DistributedSampler保证各 rank 数据一致，避免 rank 0 记录的只是自己那份分片指标。

三、TensorFlow / Keras 集成

3.1 Keras 回调：一行启用完整日志

TensorFlow 生态中最省事的接入方式是tf.keras.callbacks.TensorBoard回调，通过参数即可打开直方图、图、图片、嵌入和性能剖析：

import tensorflow as tf # TensorBoard 回调 tensorboard_callback = tf.keras.callbacks.TensorBoard( log_dir='logs/keras_experiment', histogram_freq=1, # 每个 epoch 记录一次权重直方图 write_graph=True, # 可视化模型计算图 write_images=True, # 将层权重可视化为图片 update_freq='epoch', # 指标更新频率：'epoch' / 'batch' / 正整数(每 N 步) profile_batch='10,20', # 剖析第 10~20 个 batch embeddings_freq=1 # 每个 epoch 记录一次嵌入向量 ) # 编译模型 model.compile( optimizer='adam', loss='sparse_categorical_crossentropy', metrics=['accuracy'] ) # 训练时挂载回调 history = model.fit( x_train, y_train, epochs=10, validation_data=(x_val, y_val), callbacks=[tensorboard_callback] )

参数速查：

3.2 自定义训练循环：tf.summary 文件写入器

不使用model.fit时，通过tf.summary.create_file_writer创建文件写入器，并用with writer.as_default()划定作用域写各类数据：

import tensorflow as tf # 训练/验证各自独立的 writer（便于 TensorBoard 内分组对比） train_summary_writer = tf.summary.create_file_writer('logs/train') val_summary_writer = tf.summary.create_file_writer('logs/val') # 训练循环 for epoch in range(100): # 训练 for step, (x_batch, y_batch) in enumerate(train_dataset): with tf.GradientTape() as tape: predictions = model(x_batch, training=True) loss = loss_fn(y_batch, predictions) gradients = tape.gradient(loss, model.trainable_variables) optimizer.apply_gradients(zip(gradients, model.trainable_variables)) # 记录训练指标 with train_summary_writer.as_default(): tf.summary.scalar('loss', loss, step=epoch * len(train_dataset) + step) # 验证 for x_batch, y_batch in val_dataset: predictions = model(x_batch, training=False) val_loss = loss_fn(y_batch, predictions) val_acc = accuracy_fn(y_batch, predictions) # 记录验证指标 with val_summary_writer.as_default(): tf.summary.scalar('loss', val_loss, step=epoch) tf.summary.scalar('accuracy', val_acc, step=epoch) # 记录权重直方图 with train_summary_writer.as_default(): for layer in model.layers: for weight in layer.weights: tf.summary.histogram(weight.name, weight, step=epoch)

与 PyTorch 的SummaryWriter不同，tf.summary是一组函数式 API：tf.summary.scalar、tf.summary.histogram、tf.summary.image、tf.summary.text等，都必须运行在as_default()上下文内才会落到对应的 writer。

3.3 tf.data 集成：记录数据管线样本

调试数据管线时，可直接把tf.data.Dataset的样本写入 TensorBoard：

# 记录数据集样本 for images, labels in train_dataset.take(1): with file_writer.as_default(): tf.summary.image('Training samples', images, step=0, max_outputs=25)

max_outputs=25限制最多写入 25 张图，避免一次写入整个批次造成日志过大。

四、PyTorch Lightning 集成

4.1 内置 Logger：TensorBoardLogger

PyTorch Lightning 原生内置TensorBoardLogger，配合LightningModule.log()即可实现零样板日志：

import pytorch_lightning as pl from pytorch_lightning.loggers import TensorBoardLogger # 创建 logger logger = TensorBoardLogger('logs', name='lightning_experiment') # Lightning 模块 class LitModel(pl.LightningModule): def __init__(self): super().__init__() self.model = ResNet50() def training_step(self, batch, batch_idx): x, y = batch y_hat = self.model(x) loss = F.cross_entropy(y_hat, y) # 记录指标（on_step=True 同时记录 batch 级，on_epoch=True 聚合到 epoch 级） self.log('train_loss', loss, on_step=True, on_epoch=True) return loss def validation_step(self, batch, batch_idx): x, y = batch y_hat = self.model(x) loss = F.cross_entropy(y_hat, y) acc = (y_hat.argmax(dim=1) == y).float().mean() # 验证指标默认按 epoch 聚合 self.log('val_loss', loss, on_epoch=True) self.log('val_acc', acc, on_epoch=True) return loss def configure_optimizers(self): return torch.optim.Adam(self.parameters(), lr=0.001) # Trainer trainer = pl.Trainer( max_epochs=100, logger=logger, log_every_n_steps=50 # 每 50 步写一次 batch 级日志 ) # 训练 model = LitModel() trainer.fit(model, train_loader, val_loader)

Lightning 自动管理 writer 生命周期，log_every_n_steps控制 batch 级日志频率；同一 run 下验证指标自动与训练指标同图对比。

4.2 自定义日志：通过 logger.experiment 直达 SummaryWriter

Lightning 的self.logger.experiment暴露了底层的SummaryWriter，可记录标量之外的类型（图片、直方图、PR 曲线等）：

class LitModel(pl.LightningModule): def training_step(self, batch, batch_idx): x, y = batch y_hat = self.model(x) loss = F.cross_entropy(y_hat, y) # 记录标量 self.log('train_loss', loss) # 记录图片（每 100 个 batch 一次） if batch_idx % 100 == 0: from torchvision.utils import make_grid img_grid = make_grid(x[:8]) self.logger.experiment.add_image('train_images', img_grid, self.global_step) # 记录直方图 self.logger.experiment.add_histogram('predictions', y_hat, self.global_step) return loss

这里self.global_step是 Lightning 维护的全局步数，用它作为横轴可与其他标量曲线对齐。

五、HuggingFace Transformers 集成

5.1 TrainingArguments 一键开启

transformers.Trainer只需在TrainingArguments中声明report_to='tensorboard'，即可自动把训练/评估指标写入logging_dir：

from transformers import Trainer, TrainingArguments training_args = TrainingArguments( output_dir='./results', num_train_epochs=3, per_device_train_batch_size=16, per_device_eval_batch_size=64, logging_dir='./logs', # TensorBoard 日志目录 logging_steps=100, # 每 100 步记录一次 evaluation_strategy='epoch', # 每个 epoch 评估一次 save_strategy='epoch', load_best_model_at_end=True, report_to='tensorboard' # 启用 TensorBoard 上报 ) trainer = Trainer( model=model, args=training_args, train_dataset=train_dataset, eval_dataset=eval_dataset, tokenizer=tokenizer ) # 训练（自动写 TensorBoard 日志） trainer.train()

除 loss 与学习率外，Trainer 会自动记录每步耗时、吞吐量、内存占用等运行时指标，无需额外代码。

5.2 自定义评估指标：compute_metrics

通过compute_metrics注入自定义评估函数，其结果会被自动汇总到 TensorBoard：

from transformers import Trainer, TrainingArguments import numpy as np def compute_metrics(eval_pred): """自定义评估指标。""" predictions, labels = eval_pred predictions = np.argmax(predictions, axis=1) accuracy = (predictions == labels).mean() f1 = f1_score(labels, predictions, average='weighted') return { 'accuracy': accuracy, 'f1': f1 } trainer = Trainer( model=model, args=training_args, train_dataset=train_dataset, eval_dataset=eval_dataset, compute_metrics=compute_metrics # 自定义指标随评估自动写入 TensorBoard )

5.3 手动日志：自定义 TrainerCallback

需要按自定义节奏写日志时，可继承TrainerCallback并持有自己的SummaryWriter，在on_log钩子中把logs字典逐项写入：

from transformers import TrainerCallback from torch.utils.tensorboard import SummaryWriter class TensorBoardCallback(TrainerCallback): """自定义 TensorBoard 日志回调。""" def __init__(self, log_dir='logs'): self.writer = SummaryWriter(log_dir) def on_log(self, args, state, control, logs=None, **kwargs): """日志事件触发时调用。""" if logs: for key, value in logs.items(): self.writer.add_scalar(key, value, state.global_step) def on_train_end(self, args, state, control, **kwargs): """训练结束时关闭 writer。""" self.writer.close() # 使用回调 trainer = Trainer( model=model, args=training_args, train_dataset=train_dataset, callbacks=[TensorBoardCallback()] )

回调方式适合在 Trainer 默认日志之外补充自定义 tag（如梯度范数、EMA 指标等）。

六、Fast.ai 集成

6.1 Learner 内建回调

Fast.ai 提供官方TensorBoardCallback，直接挂在fit_one_cycle的cbs参数上：

from fastai.vision.all import * from fastai.callback.tensorboard import TensorBoardCallback # 创建数据加载器 dls = ImageDataLoaders.from_folder(path, train='train', valid='valid') # 创建 learner learn = cnn_learner(dls, resnet50, metrics=accuracy) # 带 TensorBoard 日志训练 learn.fit_one_cycle( 10, cbs=TensorBoardCallback('logs/fastai', trace_model=True) ) # 查看日志 # tensorboard --logdir=logs/fastai

trace_model=True时 Fast.ai 会自动记录模型图（与 PyTorch 的add_graph等价）。Fast.ai 的数据加载器与可视化机制详见 03-fine-tuning/axolotl 之外的官方文档，本仓库则侧重于把它接入 TensorBoard 的姿势。

6.2 自定义回调：继承 Callback

若需按 Fast.ai 的after_batch/after_epoch钩子节奏写日志，可自定义Callback：

from fastai.callback.core import Callback from torch.utils.tensorboard import SummaryWriter class CustomTensorBoardCallback(Callback): """自定义 TensorBoard 回调。""" def __init__(self, log_dir='logs'): self.writer = SummaryWriter(log_dir) def after_batch(self): """每个 batch 之后触发。""" if self.train_iter % 100 == 0: self.writer.add_scalar('Loss/train', self.loss, self.train_iter) def after_epoch(self): """每个 epoch 之后触发。""" self.writer.add_scalar('Loss/train_epoch', self.recorder.train_loss, self.epoch) self.writer.add_scalar('Loss/val_epoch', self.recorder.valid_loss, self.epoch) # 记录所有指标 for i, metric in enumerate(self.recorder.metrics): metric_name = self.recorder.metric_names[i+1] self.writer.add_scalar(f'Metrics/{metric_name}', metric, self.epoch) # 使用回调 learn.fit_one_cycle(10, cbs=[CustomTensorBoardCallback()])

self.recorder是 Fast.ai 训练循环中的指标记录器，recorder.metrics按 epoch 存放各验证指标，metric_names与之对齐。

七、JAX 集成

7.1 基础集成：借道 SummaryWriter

JAX 生态没有原生 TensorBoard 绑定，社区通用做法是把 JAX 数组转成 Python 标量后复用torch.utils.tensorboard.SummaryWriter（前提是环境中已安装 torch；纯 JAX 环境也可改用tensorboard的SummaryWriter高级 API，用法一致）：

import jax import jax.numpy as jnp from torch.utils.tensorboard import SummaryWriter writer = SummaryWriter('logs/jax_experiment') # 训练循环 for epoch in range(100): for batch in train_batches: # JAX 训练步（纯函数式） state, loss = train_step(state, batch) # 写入 TensorBoard（把 JAX 数组转成 Python 标量） writer.add_scalar('Loss/train', float(loss), epoch) # 验证 val_loss = evaluate(state, val_batches) writer.add_scalar('Loss/val', float(val_loss), epoch) writer.close()

JAX 是函数式框架，train_step通常返回新的参数状态与 loss；float(loss)触发一次设备同步并取出标量，注意不要在热点路径上高频调用。

7.2 Flax 集成：记录参数分布

Flax 的TrainState统一管理参数与优化器状态，可直接遍历state.params记录各层参数直方图：

from flax.training import train_state import optax from torch.utils.tensorboard import SummaryWriter writer = SummaryWriter('logs/flax_experiment') # 创建训练状态 state = train_state.TrainState.create( apply_fn=model.apply, params=params, tx=optax.adam(0.001) ) # 训练循环 for epoch in range(100): for batch in train_loader: state, loss = train_step(state, batch) # 记录指标 writer.add_scalar('Loss/train', loss.item(), epoch) # 记录参数分布 for name, param in state.params.items(): writer.add_histogram(f'Params/{name}', jnp.array(param), epoch) writer.close()

八、scikit-learn 集成

8.1 手动日志：超参数扫描与交叉验证

传统机器学习同样可以借助 TensorBoard 做实验管理，比如在超参数网格上记录交叉验证分数：

from sklearn.ensemble import RandomForestClassifier from sklearn.model_selection import cross_val_score from torch.utils.tensorboard import SummaryWriter writer = SummaryWriter('logs/sklearn_experiment') # 超参数搜索 for n_estimators in [10, 50, 100, 200]: for max_depth in [3, 5, 10, None]: # 训练模型 model = RandomForestClassifier( n_estimators=n_estimators, max_depth=max_depth, random_state=42 ) # 5 折交叉验证 scores = cross_val_score(model, X_train, y_train, cv=5) # 记录结果 run_name = f'n{n_estimators}_d{max_depth}' writer.add_scalar(f'{run_name}/cv_mean', scores.mean(), 0) writer.add_scalar(f'{run_name}/cv_std', scores.std(), 0) # 记录超参数（HParams 页签） writer.add_hparams( {'n_estimators': n_estimators, 'max_depth': max_depth or -1}, {'cv_accuracy': scores.mean()} ) writer.close()

add_hparams同时写入超参组合与目标指标，TensorBoard 的 HParams 页签会生成平行坐标图与表格，便于快速定位最优组合。

8.2 GridSearchCV 日志：批量记录 cv_results_

配合GridSearchCV的cv_results_字典，可以一键把整个网格搜索结果批量写入：

from sklearn.model_selection import GridSearchCV from torch.utils.tensorboard import SummaryWriter writer = SummaryWriter('logs/gridsearch') # 网格搜索 param_grid = { 'n_estimators': [10, 50, 100], 'max_depth': [3, 5, 10] } grid_search = GridSearchCV( RandomForestClassifier(), param_grid, cv=5, return_train_score=True ) grid_search.fit(X_train, y_train) # 记录全部结果 for i, params in enumerate(grid_search.cv_results_['params']): mean_train_score = grid_search.cv_results_['mean_train_score'][i] mean_test_score = grid_search.cv_results_['mean_test_score'][i] param_str = '_'.join([f'{k}{v}' for k, v in params.items()]) writer.add_scalar(f'{param_str}/train', mean_train_score, 0) writer.add_scalar(f'{param_str}/test', mean_test_score, 0) # 记录最优参数 writer.add_text('Best_params', str(grid_search.best_params_), 0) writer.add_scalar('Best_score', grid_search.best_score_, 0) writer.close()

add_text把最优参数组合以文本形式写进 Text 页签，配合标量曲线即可复现“哪个组合最优、差距多大”。

九、跨框架最佳实践

9.1 统一的层级化命名约定

TensorBoard 以/作为 tag 的分隔符构造分组树。跨框架统一用域/子域/指标结构，可以让不同框架、不同 run 的同类指标在左侧树中对齐：

# ✅ 推荐：跨框架一致的层级命名 writer.add_scalar('Loss/train', train_loss, step) writer.add_scalar('Loss/val', val_loss, step) writer.add_scalar('Metrics/accuracy', accuracy, step) # PyTorch、TensorFlow、Lightning 下写法一致

9.2 用框架原生的日志入口

优先使用各框架提供的官方入口，而不是都手动调SummaryWriter，以享受框架自带的生命周期与自动聚合：

# PyTorch：使用 SummaryWriter from torch.utils.tensorboard import SummaryWriter # TensorFlow：使用 tf.summary import tensorflow as tf tf.summary.scalar('loss', loss, step=step) # Lightning：使用 self.log() self.log('train_loss', loss) # Transformers：使用 report_to='tensorboard' training_args = TrainingArguments(report_to='tensorboard')

9.3 集中封装日志逻辑

在多框架并存的团队里，把日志抽象成统一的MetricLogger门面，可以避免业务代码与具体框架 API 耦合：

class MetricLogger: """通用指标记录器。""" def __init__(self, log_dir='logs'): self.writer = SummaryWriter(log_dir) def log_scalar(self, name, value, step): self.writer.add_scalar(name, value, step) def log_image(self, name, image, step): self.writer.add_image(name, image, step) def log_histogram(self, name, values, step): self.writer.add_histogram(name, values, step) def close(self): self.writer.close() # 跨框架复用 logger = MetricLogger('logs/universal') logger.log_scalar('Loss/train', train_loss, epoch)

9.4 框架自动检测

需要一份代码在不同环境（torch / tf）下都能跑时，可用“尝试导入”的方式自动选择底层 writer：

def get_tensorboard_writer(framework='auto', log_dir='logs'): """为任意框架获取 TensorBoard writer。""" if framework == 'auto': # 自动探测框架 try: import torch framework = 'pytorch' except ImportError: try: import tensorflow as tf framework = 'tensorflow' except ImportError: raise ValueError("No supported framework found") if framework == 'pytorch': from torch.utils.tensorboard import SummaryWriter return SummaryWriter(log_dir) elif framework == 'tensorflow': import tensorflow as tf return tf.summary.create_file_writer(log_dir) # 使用 writer = get_tensorboard_writer(log_dir='logs/auto')

9.5 与实验对比相关的实践

多 run 对比、实验目录组织、日志频率控制与 writer 生命周期管理的完整建议，可参考 SKILL.md 的 Comparing Experiments 与 Best Practices 章节：

• 用带时间戳的描述性目录名（runs/resnet50_lr0.001_bs32_20260101_120000），并用tensorboard --logdir=runs聚合全部 run 对比；
• 用runs/baseline/run_1这样的层级目录组织实验族；
• 批量指标每 100 步记一次、epoch 指标必记，避免 event 文件膨胀；
• 训练结束务必writer.close()，或用with SummaryWriter(...) as writer:自动关闭。

十、在仓库中的延伸阅读

TensorBoard 在 AI-Research-SKILLs 中并非孤立技能，它与其他训练与后训练工具深度联动：

• DeepSpeed：DeepSpeed 的 Monitor 模块通过 PyTorch 向 TensorBoard 输出日志，要求环境中安装tensorboard包，并在配置的tensorboard字典中指定输出目录（见 deepspeed/references/other.md 中 Monitor 与comms_logger一节），可自动记录训练指标、通信耗时等信息；
• Axolotl：微调框架 Axolotl 提供use_tensorboard配置项，置为true即可将微调过程指标上报 TensorBoard（见 axolotl/references/other.md）；
• PyTorch Lightning：仓库的 pytorch-lightning 技能中TensorBoardLogger是默认日志器，其 callbacks.md 对日志与检查点回调有更细的说明；
• 可视化与性能剖析：本文只聚焦“如何接入各框架”。若你需要系统掌握标量、图片、直方图、图、嵌入、PR 曲线等可视化手段，请阅读 references/visualization.md；若需要借助 TensorBoard Profile 页签剖析 GPU 利用率、内存分配与算子瓶颈，请阅读 references/profiling.md（内含 PyTorch Profiler、TensorFlow Profiler 与torch.profiler.tensorboard_trace_handler的完整示例）。

综合来看，无论你使用的是 PyTorch 系的SummaryWriter、TensorFlow 系的tf.summary/Keras 回调、Lightning 的self.log、Transformers 的report_to，还是 Fast.ai 的TensorBoardCallback、乃至 JAX/sklearn 的桥接写法，最终都汇聚到同一套 event 文件格式与tensorboard --logdir启动命令上。掌握本文的接入模式与命名规范，即可让团队内所有实验在同一个看板下横向对比、统一复盘。

• AI 技能
• 人工智能
• 大模型
• 深度学习