SwanLab简明教程：从入门到高手

1. 什么是SwanLab？

开始使用： swanlab.cn
Github： github.com/swanhubx/sw...
官方文档： 欢迎使用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账号（云端版）

如果你希望：

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

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

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

然后，复制你的API Key：

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

4. 5分钟快速上手

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

python 复制代码

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 - offset
  loss = 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中被记录的超参数：

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 基础框架

6.2 专有/微调框架

6.3 计算机视觉

6.4 强化学习

6.5 其他框架

FAQ

为什么要记录训练？

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

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

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