企业官网建设流程全解析

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

本文是基于当前仓库 SwanLab Skill 及其参考文档 integrations.md 编写的实战指南，聚焦于如何把 SwanLab 这一开源实验追踪工具接入 PyTorch、HuggingFace Transformers、PyTorch Lightning 与 Fastai 四种主流训练框架。读完本文，你将掌握swanlab.init/swanlab.log的核心用法、report_to="swanlab"一键集成与SwanLabCallback回调两种 Transformers 接入路线、SwanLabLogger日志器接入方式，以及一套可直接复制到项目中的最佳实践，实现本地或自托管环境下的指标、配置与媒体资源追踪。

前置准备：安装与运行环境

SwanLab 的依赖要求与安装方式记录在 SKILL.md 中，其中明确了最低版本要求：swanlab>=0.7.11、pillow>=9.0.0、soundfile>=0.12.0（分别用于图片与音频媒体日志）。

# 安装 SwanLab 及本 Skill 使用的媒体依赖 pip install "swanlab>=0.7.11" "pillow>=9.0.0" "soundfile>=0.12.0" # 为 mode="local" 与 swanlab watch 增加本地仪表盘支持 pip install "swanlab[dashboard]>=0.7.11" # 可选：本文涉及的框架集成 pip install transformers pytorch-lightning fastai # 云托管或自托管场景登录 swanlab login

说明：

• pillow与soundfile是 Image / Audio 示例所需的媒体依赖；
• swanlab[dashboard]提供本地仪表盘所需依赖，是mode="local"与swanlab watch生效的前提；
• 如果你使用自托管服务或云端实例，也可以改用编程式登录：swanlab.login(api_key=..., host="http://your-server:5092")（参见 SKILL.md 中的本地与自托管工作流示例）。

PyTorch：基础训练循环接入

在原生 PyTorch 训练循环中，SwanLab 的接入方式非常直接：训练开始前用swanlab.init创建 run 并一次性登记项目名、实验名与超参数配置；训练过程中用swanlab.log按批次记录指标；训练结束后调用run.finish()收尾。以下完整示例摘自 integrations.md：

import torch import torch.nn as nn import torch.optim as optim import swanlab run = swanlab.init( project="pytorch-training", experiment_name="mnist-mlp", config={ "learning_rate": 1e-3, "batch_size": 64, "epochs": 10, "hidden_size": 128, }, ) model = nn.Sequential( nn.Flatten(), nn.Linear(28 * 28, run.config.hidden_size), nn.ReLU(), nn.Linear(run.config.hidden_size, 10), ) optimizer = optim.Adam(model.parameters(), lr=run.config.learning_rate) criterion = nn.CrossEntropyLoss() for epoch in range(run.config.epochs): model.train() for batch_idx, (data, target) in enumerate(train_loader): optimizer.zero_grad() logits = model(data) loss = criterion(logits, target) loss.backward() optimizer.step() if batch_idx % 100 == 0: swanlab.log( { "train/loss": loss.item(), "train/epoch": epoch, "train/batch": batch_idx, } ) run.finish()

几个值得注意的细节：

• run.config是swanlab.init(config=...)传入配置的访问入口，可直接通过属性方式读取（如run.config.hidden_size），让模型结构与优化器超参都"以配置为单一事实来源"；
• 指标名采用train/loss、train/epoch这类分组命名，便于在仪表盘上按命名空间聚合与对比；
• run.finish()在你自己管理 run 生命周期时必须显式调用，而框架集成（如 Trainer / Trainer.fit）接管生命周期时则由集成层负责收尾。

PyTorch：轻量回调封装器 SwanLabTracker

如果你希望把日志逻辑收敛到一个可复用的工具类中，integrations.md 提供了一个极简封装SwanLabTracker，统一了指标、图片、文本三类日志入口：

import swanlab class SwanLabTracker: def __init__(self, project, experiment_name=None, config=None): self.run = swanlab.init( project=project, experiment_name=experiment_name, config=config, ) def log_metrics(self, metrics, step=None): swanlab.log(metrics, step=step) def log_images(self, name, images, captions=None): if captions is None: payload = [swanlab.Image(image) for image in images] else: payload = [ swanlab.Image(image, caption=caption) for image, caption in zip(images, captions) ] swanlab.log({name: payload}) def log_note(self, name, text): swanlab.log({name: swanlab.Text(text)}) def finish(self): self.run.finish()

特别需要说明的是，文档作者在此处刻意省略了直方图（histogram）与文件类辅助方法——因为这些在当前 SwanLab 公开 API 中并不存在。这是一个重要的 API 边界提示：在编写集成代码时应以 SwanLab 官方公开 API（如swanlab.Image、swanlab.Text、swanlab.Audio、swanlab.Video、swanlab.Object3D、swanlab.Molecule.from_smiles等）为准，不要臆造不存在的接口。完整的媒体与图表日志方式可参考同目录下的 visualization.md。

Transformers：两条接入路线

针对 HuggingFace Transformers，integrations.md 给出了两条路径：官方一键集成（推荐）与基于回调的自控路径（兜底）。

路线一：transformers>=4.50.0官方一键集成

在较新版本的 Transformers 中，直接在TrainingArguments里设置report_to="swanlab"即可完成接入，这是 SwanLab 官方文档的主推路径：

from transformers import ( AutoModelForSequenceClassification, AutoTokenizer, Trainer, TrainingArguments, ) tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased") model = AutoModelForSequenceClassification.from_pretrained( "bert-base-uncased", num_labels=2, ) training_args = TrainingArguments( output_dir="./results", num_train_epochs=3, per_device_train_batch_size=16, per_device_eval_batch_size=16, evaluation_strategy="epoch", logging_steps=100, report_to="swanlab", run_name="bert-imdb", ) trainer = Trainer( model=model, args=training_args, train_dataset=train_dataset, eval_dataset=eval_dataset, ) trainer.train()

当你需要自定义项目路由、又不想脱离官方集成路径时，可以通过环境变量完成：

export SWANLAB_PROJ_NAME="my-text-classification" export SWANLAB_WORKSPACE="my-workspace"

设置SWANLAB_PROJ_NAME与SWANLAB_WORKSPACE后，report_to="swanlab"会自动将 run 路由到对应项目与工作区，无需修改代码。

路线二：transformers<4.50.0或需要自定义控制时的SwanLabCallback

对于旧版本 Transformers，或者当你希望获得 SwanLab 专属控制力（而不依赖report_to="swanlab"）时，使用swanlab.integration.transformers.SwanLabCallback作为回调注入 Trainer 即可。注意此时report_to应设为"none"，避免与回调重复创建日志器：

from transformers import ( AutoModelForSequenceClassification, AutoTokenizer, Trainer, TrainingArguments, ) from swanlab.integration.transformers import SwanLabCallback tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased") model = AutoModelForSequenceClassification.from_pretrained( "bert-base-uncased", num_labels=2, ) training_args = TrainingArguments( output_dir="./results", evaluation_strategy="epoch", logging_steps=100, report_to="none", ) trainer = Trainer( model=model, args=training_args, train_dataset=train_dataset, eval_dataset=eval_dataset, callbacks=[ SwanLabCallback( project="text-classification", experiment_name="bert-imdb", config={ "model": "bert-base-uncased", "batch_size": 16, "epochs": 3, }, ) ], ) trainer.train()

SwanLabCallback接受的 run 元数据（project、experiment_name、config）与swanlab.init(...)完全一致，训练与评估指标会由回调自动写入。

PyTorch Lightning：SwanLabLogger日志器接入

PyTorch Lightning 生态中，SwanLab 通过swanlab.integration.pytorch_lightning.SwanLabLogger作为 Lightning 的Logger接入。它可以直接替你创建 run，因此推荐把项目元数据直接传给 logger。完整示例见 integrations.md：

import pytorch_lightning as pl import torch import torch.nn as nn from swanlab.integration.pytorch_lightning import SwanLabLogger class LitClassifier(pl.LightningModule): def __init__(self, learning_rate=1e-3): super().__init__() self.save_hyperparameters() self.model = nn.Sequential( nn.Flatten(), nn.Linear(28 * 28, 128), nn.ReLU(), nn.Linear(128, 10), ) self.criterion = nn.CrossEntropyLoss() def forward(self, x): return self.model(x) def training_step(self, batch, batch_idx): x, y = batch logits = self(x) loss = self.criterion(logits, y) self.log("train/loss", loss, prog_bar=True) return loss def validation_step(self, batch, batch_idx): x, y = batch logits = self(x) loss = self.criterion(logits, y) acc = (torch.argmax(logits, dim=1) == y).float().mean() self.log("val/loss", loss, prog_bar=True) self.log("val/accuracy", acc, prog_bar=True) def configure_optimizers(self): return torch.optim.Adam(self.parameters(), lr=self.hparams.learning_rate) swanlab_logger = SwanLabLogger( project="lightning-demo", experiment_name="mnist-classifier", config={"learning_rate": 1e-3, "max_epochs": 10}, ) trainer = pl.Trainer( logger=swanlab_logger, max_epochs=10, accelerator="auto", ) trainer.fit(LitClassifier(), train_loader, val_loader)

要点：

• 在LightningModule内部通过self.log("train/loss", loss, prog_bar=True)记录指标，Lightning 会自动把prog_bar上的关键指标同步给 logger；
• run 的生命周期由Trainer.fit托管，无需手动run.finish()；
• accelerator="auto"配合 SwanLab 使用时，指标聚合行为由 Lightning 的 log 机制保证。

Fastai：视觉与文本分类

Fastai 的接入通过swanlab.integration.fastai.SwanLabCallback完成，它接受与swanlab.init(...)相同的 run 元数据，并作为cbs=[...]传入learn.fit或learn.fit_one_cycle。

视觉分类（PETS 数据集）

示例见 integrations.md：

from fastai.vision.all import URLs, ImageDataLoaders, Resize, accuracy, get_image_files, resnet34, untar_data, vision_learner from swanlab.integration.fastai import SwanLabCallback path = untar_data(URLs.PETS) dls = ImageDataLoaders.from_name_func( path, get_image_files(path / "images"), valid_pct=0.2, label_func=lambda x: x[0].isupper(), item_tfms=Resize(224), bs=64, ) learn = vision_learner(dls, resnet34, metrics=accuracy) learn.fit( 5, cbs=[ SwanLabCallback( project="fastai-demo", experiment_name="pets-classification", config={"arch": "resnet34", "epochs": 5, "batch_size": 64}, ) ], )

文本分类（IMDB 情感分析）

示例见 integrations.md：

from fastai.text.all import AWD_LSTM, TextDataLoaders, accuracy, text_classifier_learner, untar_data, URLs from swanlab.integration.fastai import SwanLabCallback path = untar_data(URLs.IMDB) dls = TextDataLoaders.from_folder(path, valid="test", bs=64) learn = text_classifier_learner( dls, AWD_LSTM, drop_mult=0.5, metrics=accuracy, ) learn.fit_one_cycle( 3, cbs=[ SwanLabCallback( project="fastai-text", experiment_name="imdb-sentiment", config={"arch": "AWD_LSTM", "epochs": 3, "batch_size": 64}, ) ], )

两种任务的共同模式：把SwanLabCallback放进 fastai 的cbs列表，回调会自动把训练过程中的 loss、metrics 与学习率等指标写入对应项目，无需在训练循环内手工swanlab.log。

最佳实践清单

integrations.md 归纳了五条经过实践检验的接入规范，贯穿上述所有框架：

1. 尽早初始化：在训练脚本的最开始调用swanlab.init，确保配置与环境元数据只被捕获一次，避免后续修改污染记录；
2. 使用稳定的指标名：跨 run 保持train/loss、val/accuracy这类统一命名，同一指标族不要时而平铺、时而分组，否则仪表盘对比会失真；
3. checkpoint 本地保存、日志记录路径或分数：用框架自带机制把 checkpoint 存到本地，再将 checkpoint 路径（可通过swanlab.Text记录）或最佳分数单独写入日志，而不是把大文件塞进实验数据；
4. 生命周期职责分明：自己管理 run 时显式调用run.finish()；当框架集成（Trainer、Lightning、fastai 回调）接管生命周期时，交给集成层自动收尾，避免重复调用；
5. 离线优先工作流：需要完全离线运行时使用mode="local"配合swanlab watch -l ./swanlog本地查看，之后再用swanlab sync ./swanlog将本地日志同步到云端或自托管服务。

其中第 5 条的本地工作流在 SKILL.md 中有完整示例：

# Local-only logging run = swanlab.init( project="offline-demo", mode="local", logdir="./swanlog", ) swanlab.log({"loss": 0.35, "epoch": 1}) run.finish()

# 查看本地日志 swanlab watch -l ./swanlog # 稍后同步本地日志 swanlab sync ./swanlog

进阶阅读

• 本文核心源码与全部示例：integrations.md
• Skill 总览、安装步骤、核心概念与本地/自托管工作流：SKILL.md
• 图表对象（swanlab.echarts折线图、柱状图、热力图）与媒体日志（图片、音频、GIF、文本、点云、分子）的完整模式：visualization.md

上述文档共同构成 SwanLab 的"安装 → 追踪 → 集成 → 可视化 → 对比"完整链路：集成层负责把 run 生命周期与各框架训练循环衔接起来，可视化层负责把日志内容渲染为可对比的图表与媒体面板。接入时请始终以公开 API 为准，避免使用文档未确认的接口，从而保证代码在不同 SwanLab 版本间的可迁移性。

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