experiment-tracking-swanlab

SwanLab：开源实验跟踪

何时使用此技能

在以下情况下使用 SwanLab：

• 跟踪机器学习实验，记录指标、配置、标签和描述
• 可视化训练过程，查看标量图表和已记录的媒体
• 比较运行记录，涵盖不同随机种子、检查点和超参数
• 在本地或可自托管环境中工作，而非依赖托管式 SaaS
• 集成 PyTorch、Transformers、PyTorch Lightning 或 Fastai

部署方式：云端、本地或可自托管 | 媒体：图像、音频、文本、GIF、点云、分子 | 集成：PyTorch、Transformers、PyTorch Lightning、Fastai

安装

# Install SwanLab plus the media dependencies used in this skill
pip install "swanlab>=0.7.11" "pillow>=9.0.0" "soundfile>=0.12.0"

# Add local dashboard support for mode="local" and swanlab watch
pip install "swanlab[dashboard]>=0.7.11"

# Optional framework integrations
pip install transformers pytorch-lightning fastai

# Login for cloud or self-hosted usage
swanlab login

pillow 和 soundfile 是此技能中图像和音频示例使用的媒体依赖项。swanlab[dashboard] 会添加本地仪表板依赖项，这是使用 mode="local" 和 swanlab watch 所必需的。

快速入门

基本实验跟踪

import swanlab

run = swanlab.init(
    project="my-project",
    experiment_name="baseline",
    config={
        "learning_rate": 1e-3,
        "epochs": 10,
        "batch_size": 32,
        "model": "resnet18",
    },
)

for epoch in range(run.config.epochs):
    train_loss = train_epoch()
    val_loss = validate()

    swanlab.log(
        {
            "train/loss": train_loss,
            "val/loss": val_loss,
            "epoch": epoch,
        }
    )

run.finish()

使用 PyTorch

import torch
import torch.nn as nn
import torch.optim as optim
import swanlab

run = swanlab.init(
    project="pytorch-demo",
    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()

核心概念

1. 项目和实验

项目：相关实验的集合
实验：训练或评估工作流的一次执行

import swanlab

run = swanlab.init(
    project="image-classification",
    experiment_name="resnet18-seed42",
    description="Baseline run on ImageNet subset",
    tags=["baseline", "resnet18"],
    config={
        "model": "resnet18",
        "seed": 42,
        "batch_size": 64,
        "learning_rate": 3e-4,
    },
)

print(run.id)
print(run.config.learning_rate)

2. 配置跟踪

config = {
    "model": "resnet18",
    "seed": 42,
    "batch_size": 64,
    "learning_rate": 3e-4,
    "epochs": 20,
}

run = swanlab.init(project="my-project", config=config)

learning_rate = run.config.learning_rate
batch_size = run.config.batch_size

3. 指标记录

# Log scalars
swanlab.log({"loss": 0.42, "accuracy": 0.91})

# Log multiple metrics
swanlab.log(
    {
        "train/loss": train_loss,
        "train/accuracy": train_acc,
        "val/loss": val_loss,
        "val/accuracy": val_acc,
        "lr": current_lr,
        "epoch": epoch,
    }
)

# Log with custom step
swanlab.log({"loss": loss}, step=global_step)

4. 媒体和图表记录

import numpy as np
import swanlab

# Image
image = np.random.randint(0, 255, (224, 224, 3), dtype=np.uint8)
swanlab.log({"examples/image": swanlab.Image(image, caption="Augmented sample")})

# Audio
wave = np.sin(np.linspace(0, 8 * np.pi, 16000)).astype("float32")
swanlab.log({"examples/audio": swanlab.Audio(wave, sample_rate=16000)})

# Text
swanlab.log({"examples/text": swanlab.Text("Training notes for this run.")})

# GIF video
swanlab.log({"examples/video": swanlab.Video("predictions.gif", caption="Validation rollout")})

# Point cloud
points = np.random.rand(128, 3).astype("float32")
swanlab.log({"examples/point_cloud": swanlab.Object3D(points, caption="Point cloud sample")})

# Molecule
swanlab.log({"examples/molecule": swanlab.Molecule.from_smiles("CCO", caption="Ethanol")})

# Custom chart with swanlab.echarts
line = swanlab.echarts.Line()
line.add_xaxis(["epoch-1", "epoch-2", "epoch-3"])
line.add_yaxis("train/loss", [0.92, 0.61, 0.44])
line.set_global_opts(
    title_opts=swanlab.echarts.options.TitleOpts(title="Training Loss")
)

swanlab.log({"charts/loss_curve": line})

更多图表和媒体用法请参阅 references/visualization.md。

5. 本地和可自托管工作流

import os
import swanlab

# Self-hosted or cloud login
swanlab.login(
    api_key=os.environ["SWANLAB_API_KEY"],
    host="http://your-server:5092",
)

# Local-only logging
run = swanlab.init(
    project="offline-demo",
    mode="local",
    logdir="./swanlog",
)

swanlab.log({"loss": 0.35, "epoch": 1})
run.finish()

# View local logs
swanlab watch -l ./swanlog

# Sync local logs later
swanlab sync ./swanlog

集成示例

HuggingFace Transformers

from transformers import Trainer, TrainingArguments

training_args = TrainingArguments(
    output_dir="./results",
    per_device_train_batch_size=8,
    evaluation_strategy="epoch",
    logging_steps=50,
    report_to="swanlab",
    run_name="bert-finetune",
)

trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=train_dataset,
    eval_dataset=eval_dataset,
)

trainer.train()

有关基于回调的设置和其他框架用法，请参阅 references/integrations.md。

PyTorch Lightning

import pytorch_lightning as pl
from swanlab.integration.pytorch_lightning import SwanLabLogger

swanlab_logger = SwanLabLogger(
    project="lightning-demo",
    experiment_name="mnist-classifier",
    config={"batch_size": 64, "max_epochs": 10},
)

trainer = pl.Trainer(
    logger=swanlab_logger,
    max_epochs=10,
    accelerator="auto",
)

trainer.fit(model, train_loader, val_loader)

Fastai

from fastai.vision.all import accuracy, resnet34, vision_learner
from swanlab.integration.fastai import SwanLabCallback

learn = vision_learner(dls, resnet34, metrics=accuracy)
learn.fit(
    5,
    cbs=[
        SwanLabCallback(
            project="fastai-demo",
            experiment_name="pets-classification",
            config={"arch": "resnet34", "epochs": 5},
        )
    ],
)

更多框架示例请参阅 references/integrations.md。

最佳实践

1. 使用稳定的指标名称

# Good: grouped metric namespaces
swanlab.log({
    "train/loss": train_loss,
    "train/accuracy": train_acc,
    "val/loss": val_loss,
    "val/accuracy": val_acc,
})

# Avoid mixing flat and grouped names for the same metric family

2. 尽早初始化，并一次性捕获配置

run = swanlab.init(
    project="image-classification",
    experiment_name="resnet18-baseline",
    config={
        "model": "resnet18",
        "learning_rate": 3e-4,
        "batch_size": 64,
        "seed": 42,
    },
)

3. 在本地保存检查点

import torch
import swanlab

checkpoint_path = "checkpoints/best.pth"
torch.save(model.state_dict(), checkpoint_path)

swanlab.log(
    {
        "best/val_accuracy": best_val_accuracy,
        "artifacts/checkpoint_path": swanlab.Text(checkpoint_path),
    }
)

4. 离线优先的工作流使用本地模式

run = swanlab.init(project="offline-demo", mode="local", logdir="./swanlog")
# ... training code ...
run.finish()

# Inspect later with: swanlab watch -l ./swanlog

5. 将高级用法放在参考文档中

• 高级图表和媒体用法请参阅 references/visualization.md
• 基于回调和特定框架的集成详情请参阅 references/integrations.md

资源

• 官方文档（中文）
• 官方文档（英文）
• GitHub 仓库
• 可自托管版本仓库

另请参阅

• references/integrations.md - 特定框架的示例
• references/visualization.md - 图表和媒体记录用法

Agent 操作流程

1. 检查环境。 确认硬件、框架和服务版本、模型格式及预期负载。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。凡是会改变结果的值，不要猜测，应先询问。
3. 先运行小规模版本。 扩大规模前，先提供或记录单个请求，或端到端运行一次。
4. 按照上述说明和参考资料执行完整任务。
5. 验证结果。 对照参考值测量延迟、吞吐量和输出正确性；检查资源使用情况和成本。
6. 汇报。 说明运行了什么（版本、命令、参数）、检查了什么，以及仍有哪些不确定之处。

如果发生以下情况	请采取以下措施
服务无法启动或发生 OOM	检查模型大小与内存是否匹配，以及量化和并行设置。
这些说明中的函数、标志或端点在已安装的版本中不存在	查看该版本自带的文档（help()、--help、官方文档），进行调整并告知用户。切勿臆造 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明所采用的假设。

诚信规则

• 切勿伪造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请明确说明。
• 不要公开暴露服务或凭证；配置前确认云服务成本。
• 此处与版本相关的细节可能已过时：请根据已安装版本的官方文档进行确认。
• 对于涉及费用、占用共享 GPU 或云配额、处理个人或患者数据，或无法撤销的操作，请先征求同意。