SwanLab简明教程：从萌新到高手

目录

1. 什么是SwanLab？

1.1 核心特性

2. 安装SwanLab

3. 登录SwanLab账号（云端版）

4. 5分钟快速上手

更多案例

5. SwanLab功能组件

5.1 图表视图

5.2 表格视图

5.3 硬件监控

5.4 环境记录

5.5 组织协同

6. 训练框架集成

6.1 基础框架

6.2 专有/微调框架

6.3 计算机视觉

6.4 强化学习

6.5 其他框架

FAQ

为什么要记录训练？

训练可视化的价值是什么？

---

1. 什么是SwanLab？

• 开始使用：https://swanlab.cn
• Github：https://github.com/swanhubx/swanlab
• 官方文档：欢迎使用SwanLab | SwanLab官方文档
• 案例：kites/yolov8-optimize-v2

SwanLab 是一个开源、现代化设计的深度学习训练跟踪与可视化工具，常被称为"中国版 Weights & Biases + Tensorboard"。目前SwanLab在Github上已收获 1k+ Star，也借此感谢各位小伙伴的支持。

SwanLab同时支持云端和离线使用，并适配了从PyTorch、Transformers、Lightning再到LLaMA Factory、veRL等30多种主流AI训练框架，Python API设计也简洁易上手，能轻松嵌入你的训练代码。

面向人工智能研究者，SwanLab设计了友好的Python API 和漂亮的UI界面，并提供训练可视化、自动日志记录、超参数记录、实验版本管理与对比、多人协同等功能。在SwanLab上，研究者能基于直观的可视化图表发现训练问题，对比多个实验找到研究灵感，并通过在线网页的分享与基于组织的多人协同训练，打破团队沟通的壁垒，提高组织训练效率。

SwanLab支持移动端使用，让你在手机上也能实时看到训练进展。同时，SwanLab也是目前唯一支持昇腾NPU等国产卡硬件监控的训练工具。

1.1 核心特性

以下是SwanLab的一些核心特性：

1. 实验指标与超参数跟踪: 极简的代码嵌入您的机器学习 pipeline，跟踪记录训练关键指标

• 支持云端使用（类似Weights & Biases），随时随地查看训练进展。手机看实验的方法
• 支持超参数记录与表格展示
• 支持的元数据类型：标量指标、图像、音频、文本、...
• 支持的图表类型：折线图、媒体图（图像、音频、文本）、...
• 后台自动记录：日志logging、硬件环境、Git 仓库、Python 环境、Python 库列表、项目运行目录

2. ⚡️ 全面的框架集成: PyTorch、 HuggingFace Transformers、PyTorch Lightning、 LLaMA Factory、MMDetection、Ultralytics、PaddleDetetion、LightGBM、XGBoost、Keras、Tensorboard、Weights&Biases、OpenAI、Swift、XTuner、Stable Baseline3、Hydra 在内的 30+ 框架

3. 硬件监控: 支持实时记录与监控CPU、NPU（昇腾Ascend）、GPU（英伟达Nvidia）、内存的系统级硬件指标

4. 实验管理: 通过专为训练场景设计的集中式仪表板，通过整体视图速览全局，快速管理多个项目与实验

4. 比较结果: 通过在线表格与对比图表比较不同实验的超参数和结果，挖掘迭代灵感

5. 在线协作: 您可以与团队进行协作式训练，支持将实验实时同步在一个项目下，您可以在线查看团队的训练记录，基于结果发表看法与建议

6. ✉️ 分享结果: 复制和发送持久的 URL 来共享每个实验，方便地发送给伙伴，或嵌入到在线笔记中

7. 支持自托管: 支持离线环境使用，自托管的社区版同样可以查看仪表盘与管理实验

2. 安装SwanLab

SwanLab的安装非常简单，只需要使用Python的包管理工具pip，一行命令安装即可：

pip install swanlab

Python版本需要>=3.8

3. 登录SwanLab账号（云端版）

如果你希望：

1. 任何一台远程服务器上跑的实验，都能汇总到一个网页空间下进行管理
2. 无论通勤还是运动，都可以用手机看到最新的训练进展
3. 将训练曲线、超参数一键分享给小伙伴，让他们看到你正在训练的过程
4. 保存你的所有历史实验，告别整理分布在各个文件夹里的日志

那么非常推荐你使用SwanLab云端版（https://swanlab.cn）；如果你希望离线记录，那么可以跳过本节。

使用云端版非常简单，首先在官网上注册1个账号，然后在你的工作区点击左下角的「小闪电」：

然后，复制你的API Key：

最后，打开命令行终端，输入swanlab login，按回车后，粘贴API Key（粘贴的内容在命令行是看不见的，所以请放心你已经粘贴进去了 = w =），再按回车，完成登录。

4. 5分钟快速上手

SwanLab最核心的功能是深度学习训练过程记录与可视化，下面是一个最简代码示例：

import swanlab
import random# 创建一个SwanLab项目
swanlab.init(# 设置项目名project="my-awesome-project",# 设置超参数config={"learning_rate": 0.02,"architecture": "CNN","dataset": "CIFAR-10","epochs": 10}
)# 模拟一次训练
epochs = 10
offset = random.random() / 5
for epoch in range(2, epochs):acc = 1 - 2 ** -epoch - random.random() / epoch - offsetloss = 2 ** -epoch + random.random() / epoch + offset# 记录训练指标swanlab.log({"acc": acc, "loss": loss})# [可选] 完成训练，这在notebook环境中是必要的
swanlab.finish()

这是一个模拟训练过程的脚本，其中用到了SwanLab最核心的两个API swanlab.init()和 swanlab.log()

• swanlab.init：创建SwanLab实验，支持传入项目名project、实验名experiment_name、超参数config、笔记description等一系列参数。
• swanlab.log： 记录指标（Metric），将传入的字典进行记录

上面的代码中，首先创建了1个SwanLab实验，它归属于项目my-awesome-project；然后在10论epoch中，每轮epoch ，SwanLab对acc和loss进行1次记录。

运行脚本后，我们可以在网页上看到可视化图表：

在「卡片」选项卡，可以看到在swanlab.init中被记录的超参数：

更多案例

我们也写了各个门类的训练入门教程，帮助你更好地了解SwanLab的使用方法：

• MNIST手写体识别
• 猫狗分类
• BERT文本分类 | SwanLab官方文档
• 音频分类
• LSTM股票预测
• DQN强化学习-推车倒立摆
• Stable Diffusion文生图微调
• Qwen微调案例
• Qwen2-VL多模态大模型微调实战
• 从零预训练一个自己的大模型

5. SwanLab功能组件

5.1 图表视图

• 折线图

机器学习过程需要跟踪与模型性能相关的不同指标。这对于快速发现问题，并确定模型是否过度拟合等非常重要。通过 SwanLab 折线图看板，可视化关键指标，并对比不同实验的指标差异，让调试模型更轻松：

• 图像

• 音频

• 文本

• 日志记录

启动swanlab.init后，会自动记录命令行的打印信息，并支持网页端搜索和下载。

5.2 表格视图

通过多实验超参数与指标展示进行对比，支持筛选、排序、行拖拽与列拖拽等操作进行辅助分析。

5.3 硬件监控

支持实时监控训练过程中，英伟达GPU、昇腾NPU、内存、CPU的性能变化。

5.4 环境记录

支持自动记录训练使用的操作系统、Python环境、Git仓库、运行命令、运行时长等环境信息。

以及支持记录Python列表，并可以通过搜索快速定位先前实验的Python库版本：

5.5 组织协同

支持创建组织，邀请你的AI搭子在一个空间下协作训练。

测试组织

6. 训练框架集成

• 将SwanLab集成到你的库 | SwanLab官方文档

6.1 基础框架

• PyTorch
• MindSpore
• Keras

6.2 专有/微调框架

• PyTorch Lightning
• HuggingFace Transformers
• LLaMA Factory
• Modelscope Swift
• DiffSynth-Studio
• Sentence Transformers
• OpenMind
• Torchtune
• XTuner
• MMEngine
• FastAI
• LightGBM
• XGBoost

6.3 计算机视觉

• Ultralytics
• MMDetection
• MMSegmentation
• PaddleDetection
• PaddleYOLO

6.4 强化学习

• Stable Baseline3
• veRL
• HuggingFace trl
• EasyR1

6.5 其他框架

• Tensorboard
• Weights&Biases
• MLFlow
• HuggingFace Accelerate
• Hydra
• Omegaconf
• OpenAI
• ZhipuAI

FAQ

为什么要记录训练？

相较于软件开发，模型训练更像一个实验科学。一个品质优秀的模型背后，往往是成千上万次实验。研究者需要不断尝试、记录、对比，积累经验，才能找到最佳的模型结构、超参数与数据配比。在这之中，如果没有好的训练记录工具进行辅助，管理实验本身的复杂度就会让你的科研进展受到很大阻力，所以记录训练非常重要。

训练可视化的价值是什么？

机器学习模型训练往往伴随着大量的超参数、指标、日志等数据，很多关键信息往往存在于实验的中间而非结尾，如果不对连续的指标通过图表进行可视化，往往会错失发现问题的最佳时机，甚至错过关键信息。同时不进行可视化，也难以对比多个实验之间的差异。 可视化也为AI研究者提供了良好的交流基础，研究者们可以基于图表进行沟通、分析与优化，而非以往看着枯燥的终端打印。这打破了团队沟通的壁垒，提高了整体的研发效率。