1. 从WandB到SwanLab：为什么我们需要一个平替方案

最近在搞具身智能项目，训练一个机械臂抓取模型，本来一切顺利，直到我想看一眼训练曲线。我的老伙计WandB（Weights & Biases）突然就罢工了，终端里疯狂报错，什么ConnectionError、Connection refused，折腾了半天也没连上。上网一搜，发现不少国内开发者都遇到了类似问题，网络连接不稳定成了常态。这感觉就像你正热火朝天地炒菜，突然煤气灶打不着火了，非常影响节奏。

对于具身智能这类实验周期长、参数复杂的任务来说，训练可视化不是“锦上添花”，而是“雪中送炭”。我们需要实时看到损失（loss）是否在下降，成功率（success rate）有没有提升，关节角度（joint angles）的误差变化趋势如何。这些动态的图表能帮我们快速判断模型是否在朝着正确的方向学习，是继续训练、调整参数，还是赶紧停下来检查代码bug。没有可靠的可视化工具，训练就变成了“黑箱操作”，全凭感觉，效率极低。

正是在这种背景下，我开始寻找WandB的替代品。我的核心诉求很明确：第一，连接必须稳定可靠，不能动不动就断线；第二，使用要足够简单，最好能和WandB的API类似，减少迁移成本；第三，数据要安全可控，毕竟是实验数据。兜兜转转，我发现了SwanLab——一个由国内团队开发的机器学习实验跟踪工具。试用了几周后，我发现它完全能满足我的需求，甚至在某些细节上更贴心。这篇文章，我就把自己从WandB迁移到SwanLab的完整过程、踩过的坑以及实战心得分享给你，让你也能快速上手，把精力重新聚焦回模型本身。

2. 环境准备与SwanLab初体验

2.1 安装与配置：一条命令搞定

迁移的第一步，就是把SwanLab装到你的环境里。这个过程简单到超乎想象。打开你的终端（无论是本地还是远程服务器），直接输入：

pip install swanlab

如果你的网络环境不错，通常几十秒就能装好。但我知道，有时候从PyPI官方源下载会比较慢，特别是在一些校内或公司的网络里。别担心，SwanLab支持使用国内镜像源进行加速，这是我非常欣赏的一点，对国内开发者非常友好。你可以用清华源或者中科大源来安装：

pip install swanlab -i https://pypi.tuna.tsinghua.edu.cn/simple

我实测下来，用国内镜像速度能快好几倍，瞬间就装好了。安装完成后，你可以通过 pip show swanlab 来确认版本信息。目前我使用的是较新的稳定版，API已经非常完善。

2.2 账号注册与登录：无缝衔接云端

SwanLab和WandB一样，提供了一个云端看板来集中管理你的所有实验。你需要先到 SwanLab官网 注册一个账号。注册过程就是常规的邮箱验证，完全免费，对于个人和小团队来说，提供的资源额度完全够用。

注册成功后，就需要在本地环境中登录，将你的实验和云端账户关联起来。SwanLab提供了两种登录方式，都非常直观。

第一种是命令行登录，也是最推荐的方式。在终端输入：

swanlab login

然后命令行会提示你打开浏览器，前往个人设置页面获取API Key。你将这个Key复制后，粘贴回终端（粘贴时不会显示，这是出于安全考虑），按下回车，就登录成功了。终端会显示“Login successful”的提示。这个登录状态是持久化的，以后在这台机器上运行实验都不需要再次登录。

第二种是脚本内登录，适用于一些无法交互的环境（比如某些自动化脚本或容器内）。你可以在Python代码中直接登录：

import swanlab
swanlab.login(api_key="你的API_Key")

把api_key替换成你从官网复制的真实Key即可。我个人更习惯用命令行登录一次搞定，这样代码里就不用硬编码敏感信息了。

3. 核心迁移：将WandB代码改为SwanLab

这是最关键的一步，但好消息是，SwanLab的API设计有意向WandB靠拢，所以迁移工作量很小，很多时候只是简单的“改名替换”。下面我们以一个典型的具身智能训练循环为例，看看如何一步步改造。

3.1 初始化实验：定义你的项目与超参数

在WandB中，我们通常用 wandb.init() 来启动一个实验。在SwanLab中，对应的函数是 swanlab.init()。它们的核心参数非常相似。

假设我们原来的WandB初始化代码是这样的：

import wandb

wandb.init(
    project="embodied-grasping",
    config={
        "learning_rate": 0.0003,
        "batch_size": 64,
        "gamma": 0.99,
        "tau": 0.005,
        "hidden_dim": 256,
    }
)

迁移到SwanLab，几乎可以直接照搬：

import swanlab

run = swanlab.init(
    project="embodied-grasping",  # 项目名称，在云端看板中归类
    config={
        "learning_rate": 0.0003,
        "batch_size": 64,
        "gamma": 0.99,          # DDPG等算法的折扣因子
        "tau": 0.005,           # 目标网络软更新参数
        "hidden_dim": 256,      # 策略网络隐藏层维度
    }
)

这里有几个细节需要注意：

1. swanlab.init() 会返回一个 run 对象，这个对象很重要，后面记录指标和访问配置都会用到。
2. config 字典里存放的是你这次实验的所有超参数。SwanLab会把这些参数清晰地展示在云端看板的侧边栏，方便你后续对比不同参数下的实验效果。对于具身智能任务，我通常会记录算法类型、网络结构、奖励函数系数、环境参数等。
3. project 参数用于在云端对实验进行分类。我建议你为不同的研究主题创建不同的项目，比如“robotic-arm-reaching”、“mobile-navigation”，这样管理起来一目了然。

3.2 记录训练指标：让学习过程一目了然

在训练循环中，我们需要持续记录损失、奖励、成功率等指标。WandB用的是 wandb.log()。SwanLab的对应函数是 swanlab.log()，用法几乎一模一样。

原来的WandB记录代码：

for episode in range(total_episodes):
    # ... 训练逻辑 ...
    episode_reward = ...
    policy_loss = ...
    value_loss = ...
    success = ...

    wandb.log({
        "episode_reward": episode_reward,
        "policy_loss": policy_loss,
        "value_loss": value_loss,
        "success_rate": success,
        "episode": episode,
    })

迁移后的SwanLab代码：

for episode in range(total_episodes):
    # ... 训练逻辑（例如PPO、SAC的一个episode）...
    episode_reward = agent.train_one_episode()
    policy_loss = agent.policy_net.loss
    value_loss = agent.value_net.loss
    success = env.is_task_successful()

    # 记录核心指标
    swanlab.log({
        "reward/episode_reward": episode_reward,
        "loss/policy": policy_loss,
        "loss/value": value_loss,
        "metric/success_rate": success,
        "global_step": episode,
    })

这里有一个SwanLab非常实用的特性： 你可以通过斜杠 / 在指标名称中创建分组。比如我把所有损失相关的指标放在 loss/ 组下，所有奖励相关的放在 reward/ 组下。这样在SwanLab的云端看板上，图表会自动按照分组进行整理，界面非常清爽，比所有指标混在一起好看多了。这对于有几十个需要跟踪的指标的复杂具身智能任务来说，简直是福音。

3.3 记录媒体与自定义图表：不只是数字

具身智能的评估往往不能只看数字。我们需要看智能体（机器人）的实际表现。WandB可以记录视频、图像，SwanLab同样支持，而且方式更简洁。

记录环境渲染帧： 假设你的仿真环境（如PyBullet、MuJoCo、Isaac Gym）可以返回RGB图像。

import numpy as np

# 每隔N个episode记录一次智能体行为
if episode % 100 == 0:
    # 从环境获取当前帧，假设是[H, W, C]的numpy数组
    frame = env.render(mode='rgb_array')
    # SwanLab.log可以直接记录numpy数组为图像
    swanlab.log({"visual/rollout_frame": swanlab.Image(frame, caption=f"Episode {episode}")})

记录自定义图表（比如关节角度曲线）： 有时候你想直接记录一个完整的图表，比如机械臂七个关节在一条轨迹中的角度变化。

import matplotlib.pyplot as plt

if episode % 500 == 0:
    joint_angles_history = ... # 从缓冲区获取最近一条轨迹的关节角度历史，形状为[T, 7]
    timesteps = np.arange(joint_angles_history.shape[0])

    fig, ax = plt.subplots(figsize=(10, 6))
    for i in range(7):
        ax.plot(timesteps, joint_angles_history[:, i], label=f'Joint {i+1}')
    ax.set_xlabel('Time Step')
    ax.set_ylabel('Joint Angle (rad)')
    ax.set_title('Joint Angles During Latest Trajectory')
    ax.legend()
    ax.grid(True)

    # 将matplotlib图表记录到SwanLab
    swanlab.log({"chart/joint_angles": swanlab.Figure(fig)})
    plt.close(fig) # 记得关闭图形，避免内存泄漏

SwanLab的 swanlab.Image 和 swanlab.Figure 接口让记录多媒体数据变得非常简单。这些视频和图片会直接出现在你的实验记录中，你可以非常直观地看到智能体随着训练进度，其行为是如何从笨拙变得熟练的。

4. SwanLab云端看板深度使用指南

代码跑起来之后，真正的乐趣在于打开SwanLab的云端看板。你可以在终端输出的日志里找到一个链接，直接点击就能在浏览器中打开本次实验的专属页面。它的界面设计非常现代，逻辑清晰。

4.1 指标图表解读与自定义

看板的默认主页是“指标”面板，这里会把你用 swanlab.log 记录的所有指标自动绘制成随时间（或全局步数）变化的曲线。你可以：

• 悬停查看详情：鼠标放在曲线上任意一点，可以看到该步数下精确的数值。
• 缩放与平移：用鼠标框选可以放大特定区间，拖动图表可以平移，这对于查看训练后期细微的变化非常有用。
• 切换Y轴尺度：对于变化范围巨大的指标（比如奖励可能从负几千到正几百），可以一键切换为对数坐标，让曲线更易读。
• 图表叠加对比：你可以将同一个实验内的不同指标（比如“policy_loss”和“value_loss”）拖到同一个图表中进行对比，看看它们的下降趋势是否同步。

创建自定义仪表盘：这是SwanLab一个强大的功能。你可以在看板中新建一个“面板”，然后自由地从所有已记录的指标、配置参数、甚至系统资源（如GPU内存使用率，如果你记录了的话）中拖拽组件进来。比如，我可以创建一个名为“训练概览”的面板，左边放上“episode_reward”和“success_rate”的曲线图，右边放上最近一次记录的机械臂操作视频，下方再放上关键超参数的当前值。这样，一个屏幕就能掌握训练全貌，非常适合在组会或项目汇报时展示。

4.2 实验对比与管理

当你运行了多次实验（比如调整了学习率或网络层数），实验管理功能就派上用场了。在项目概览页面，所有实验会以列表形式呈现。

• 并行对比：你可以勾选多个实验，然后点击“对比”，SwanLab会将这些实验的所有指标曲线并排显示在同一个坐标系中。不同实验的曲线会用不同颜色区分，并配有图例。一眼就能看出哪个学习率设置收敛更快，哪个奖励函数设计最终性能更高。
• 表格视图与筛选：所有实验的 config 超参数会以表格列的形式展示。你可以点击表头进行排序，或者使用筛选功能，快速找出所有“learning_rate=0.0003”且“batch_size=64”的实验。这对于进行大规模超参数搜索后的结果分析至关重要。
• 标签与备注：你可以给重要的实验打上标签（如“best-so-far”、“bug-exploration”），或者添加详细的文本备注，记录这次实验的特殊发现或问题。良好的实验管理习惯能极大提升研究效率。

4.3 团队协作与分享

SwanLab天然支持团队协作。你可以在项目设置中邀请队友，给他们设置“查看者”或“协作者”权限。

• 共享链接：任何一个实验或项目都可以生成一个分享链接，你可以直接把这个链接发给同事或导师。他们无需登录（或登录后）即可查看你所有的图表、视频和配置，方便快速讨论和反馈。
• 评论功能：在实验页面，你可以针对某个具体的图表或数据点添加评论，进行聚焦的讨论。这比在聊天软件里翻截图和发文件要高效得多。

5. 进阶技巧与避坑指南

用了这么久，我也积累了一些让SwanLab用起来更顺手的高级技巧，以及一些新手容易踩的坑。

5.1 如何高效记录系统资源

训练具身智能模型，尤其是3D仿真，对算力消耗很大。监控系统资源可以帮助你发现瓶颈。SwanLab可以很方便地记录这些信息，但需要安装一个额外的包 psutil：

pip install psutil

然后在你的训练脚本开头，启动一个后台线程来定期记录：

import swanlab
import psutil
import threading
import time

def log_system_stats(interval=10): # 每10秒记录一次
    while True:
        cpu_percent = psutil.cpu_percent(interval=None)
        memory_info = psutil.virtual_memory()
        gpu_memory = ... # 这里需要根据你的CUDA环境获取，例如使用`pynvml`
        swanlab.log({
            "system/cpu_percent": cpu_percent,
            "system/memory_percent": memory_info.percent,
            "system/gpu_memory_used": gpu_memory.used if gpu_memory else None,
        })
        time.sleep(interval)

# 在swanlab.init之后，启动监控线程
monitor_thread = threading.Thread(target=log_system_stats, daemon=True)
monitor_thread.start()

这样，你就能在看板上看到资源使用曲线，如果发现GPU内存使用率在训练中途突然飙升，可能意味着有内存泄漏；如果CPU一直100%，可能说明数据预处理部分成了瓶颈。

5.2 处理分布式与异步训练

如果你的具身智能训练是在多GPU或者多个环境实例上并行进行的，SwanLab也能很好地支持。核心思想是为每个进程创建独立的实验，但通过相同的 run.name 或 group 参数将它们关联起来。

import swanlab
import os

# 假设你有4个并行环境
process_id = os.getpid() # 或用MPI的rank，或自己分配的id
run = swanlab.init(
    project="parallel-embodied",
    group="sac_parallel_trial_1", # 同一个实验组
    name=f"worker_{process_id}",   # 每个进程独立的名字
    config=shared_config,
)

在云端看板上，同一个 group 下的所有实验会被折叠在一起，你可以展开查看每个worker的独立指标，也可以查看整个组的平均指标图表。

5.3 常见问题与解决方案

1. 日志没有上传到云端？ 首先检查网络连接，然后确认 swanlab login 是否成功。最直接的方法是运行官方提供的一个最简单的示例脚本，看能否成功。如果示例可以，那问题可能出在你的代码逻辑里（比如训练循环崩溃导致没执行到 log 语句）。
2. 图表显示“无数据”？ 请确保 swanlab.log 是在训练循环内被调用的，并且传入的字典键是字符串类型。检查一下是否有因为条件判断（如 if episode % log_interval == 0）导致前期很长时间没有记录数据。
3. 本地调试不想上传？ 有时候我们只是想本地跑一下看看逻辑对不对。SwanLab提供了离线模式。在 swanlab.init 时设置 mode="offline"，所有数据会保存在本地一个目录中，之后可以用 swanlab sync 命令手动上传。
4. 想记录的数据类型不支持？ SwanLab支持标量、图像、图表、音频、文本等常见类型。如果你有自定义的3D点云等特殊数据，可以将其转换为图像序列（多视角渲染）或使用 swanlab.Text 记录其摘要信息。也可以关注官方文档，社区一直在增加新的数据类型支持。

从WandB切换到SwanLab，对我来说不仅仅是为了解决网络连接问题。在这个过程中，我重新审视了自己的实验管理流程。SwanLab稳定的连接、符合直觉的界面以及对中文社区的快速响应，让我感觉工具真正在为我服务，而不是我要去适应工具。现在，我的训练脚本里那些 swanlab.log 的调用，就像给训练过程装上了清晰的仪表盘，让我能更自信、更高效地探索具身智能的广阔世界。如果你也在为类似的问题烦恼，不妨花上半小时，按照上面的步骤试试SwanLab，它可能会给你带来不小的惊喜。