{"id":"swanlab","name":"experiment-tracking-swanlab","summary":"SwanLabでの実験追跡に関する指針を提供します。オープンソースのラントラッキング、ローカルまたはセルフホストのダッシュボード、軽量なメディアログ(MLワークフロー)が必要なときに使ってください。","body":"# SwanLab: Open-Source Experiment Tracking\n\n## When to Use This Skill\n\nUse SwanLab when you need to:\n- **Track ML experiments** with metrics, configs, tags, and descriptions\n- **Visualize training** with scalar charts and logged media\n- **Compare runs** across seeds, checkpoints, and hyperparameters\n- **Work locally or self-hosted** instead of depending on managed SaaS\n- **Integrate** with PyTorch, Transformers, PyTorch Lightning, or Fastai\n\n**Deployment**: Cloud, local, or self-hosted | **Media**: images, audio, text, GIFs, point clouds, molecules | **Integrations**: PyTorch, Transformers, PyTorch Lightning, Fastai\n\n## Installation\n\n```bash\n# Install SwanLab plus the media dependencies used in this skill\npip install \"swanlab>=0.7.11\" \"pillow>=9.0.0\" \"soundfile>=0.12.0\"\n\n# Add local dashboard support for mode=\"local\" and swanlab watch\npip install \"swanlab[dashboard]>=0.7.11\"\n\n# Optional framework integrations\npip install transformers pytorch-lightning fastai\n\n# Login for cloud or self-hosted usage\nswanlab login\n```\n\n`pillow` and `soundfile` are the media dependencies used by the Image and Audio examples in this skill. `swanlab[dashboard]` adds the local dashboard dependency required by `mode=\"local\"` and `swanlab watch`.\n\n## Quick Start\n\n### Basic Experiment Tracking\n\n```python\nimport swanlab\n\nrun = swanlab.init(\n    project=\"my-project\",\n    experiment_name=\"baseline\",\n    config={\n        \"learning_rate\": 1e-3,\n        \"epochs\": 10,\n        \"batch_size\": 32,\n        \"model\": \"resnet18\",\n    },\n)\n\nfor epoch in range(run.config.epochs):\n    train_loss = train_epoch()\n    val_loss = validate()\n\n    swanlab.log(\n        {\n            \"train/loss\": train_loss,\n            \"val/loss\": val_loss,\n            \"epoch\": epoch,\n        }\n    )\n\nrun.finish()\n```\n\n### With PyTorch\n\n```python\nimport torch\nimport torch.nn as nn\nimport torch.optim as optim\nimport swanlab\n\nrun = swanlab.init(\n    project=\"pytorch-demo\",\n    experiment_name=\"mnist-mlp\",\n    config={\n        \"learning_rate\": 1e-3,\n        \"batch_size\": 64,\n        \"epochs\": 10,\n        \"hidden_size\": 128,\n    },\n)\n\nmodel = nn.Sequential(\n    nn.Flatten(),\n    nn.Linear(28 * 28, run.config.hidden_size),\n    nn.ReLU(),\n    nn.Linear(run.config.hidden_size, 10),\n)\noptimizer = optim.Adam(model.parameters(), lr=run.config.learning_rate)\ncriterion = nn.CrossEntropyLoss()\n\nfor epoch in range(run.config.epochs):\n    model.train()\n    for batch_idx, (data, target) in enumerate(train_loader):\n        optimizer.zero_grad()\n        logits = model(data)\n        loss = criterion(logits, target)\n        loss.backward()\n        optimizer.step()\n\n        if batch_idx % 100 == 0:\n            swanlab.log(\n                {\n                    \"train/loss\": loss.item(),\n                    \"train/epoch\": epoch,\n                    \"train/batch\": batch_idx,\n                }\n            )\n\nrun.finish()\n```\n\n## Core Concepts\n\n### 1. Projects and Experiments\n\n**Project**: Collection of related experiments  \n**Experiment**: Single execution of a training or evaluation workflow\n\n```python\nimport swanlab\n\nrun = swanlab.init(\n    project=\"image-classification\",\n    experiment_name=\"resnet18-seed42\",\n    description=\"Baseline run on ImageNet subset\",\n    tags=[\"baseline\", \"resnet18\"],\n    config={\n        \"model\": \"resnet18\",\n        \"seed\": 42,\n        \"batch_size\": 64,\n        \"learning_rate\": 3e-4,\n    },\n)\n\nprint(run.id)\nprint(run.config.learning_rate)\n```\n\n### 2. Configuration Tracking\n\n```python\nconfig = {\n    \"model\": \"resnet18\",\n    \"seed\": 42,\n    \"batch_size\": 64,\n    \"learning_rate\": 3e-4,\n    \"epochs\": 20,\n}\n\nrun = swanlab.init(project=\"my-project\", config=config)\n\nlearning_rate = run.config.learning_rate\nbatch_size = run.config.batch_size\n```\n\n### 3. Metric Logging\n\n```python\n# Log scalars\nswanlab.log({\"loss\": 0.42, \"accuracy\": 0.91})\n\n# Log multiple metrics\nswanlab.log(\n    {\n        \"train/loss\": train_loss,\n        \"train/accuracy\": train_acc,\n        \"val/loss\": val_loss,\n        \"val/accuracy\": val_acc,\n        \"lr\": current_lr,\n        \"epoch\": epoch,\n    }\n)\n\n# Log with custom step\nswanlab.log({\"loss\": loss}, step=global_step)\n```\n\n### 4. Media and Chart Logging\n\n```python\nimport numpy as np\nimport swanlab\n\n# Image\nimage = np.random.randint(0, 255, (224, 224, 3), dtype=np.uint8)\nswanlab.log({\"examples/image\": swanlab.Image(image, caption=\"Augmented sample\")})\n\n# Audio\nwave = np.sin(np.linspace(0, 8 * np.pi, 16000)).astype(\"float32\")\nswanlab.log({\"examples/audio\": swanlab.Audio(wave, sample_rate=16000)})\n\n# Text\nswanlab.log({\"examples/text\": swanlab.Text(\"Training notes for this run.\")})\n\n# GIF video\nswanlab.log({\"examples/video\": swanlab.Video(\"predictions.gif\", caption=\"Validation rollout\")})\n\n# Point cloud\npoints = np.random.rand(128, 3).astype(\"float32\")\nswanlab.log({\"examples/point_cloud\": swanlab.Object3D(points, caption=\"Point cloud sample\")})\n\n# Molecule\nswanlab.log({\"examples/molecule\": swanlab.Molecule.from_smiles(\"CCO\", caption=\"Ethanol\")})\n```\n\n```python\n# Custom chart with swanlab.echarts\nline = swanlab.echarts.Line()\nline.add_xaxis([\"epoch-1\", \"epoch-2\", \"epoch-3\"])\nline.add_yaxis(\"train/loss\", [0.92, 0.61, 0.44])\nline.set_global_opts(\n    title_opts=swanlab.echarts.options.TitleOpts(title=\"Training Loss\")\n)\n\nswanlab.log({\"charts/loss_curve\": line})\n```\n\nSee [references/visualization.md](references/visualization.md) for more chart and media patterns.\n\n### 5. Local and Self-Hosted Workflows\n\n```python\nimport os\nimport swanlab\n\n# Self-hosted or cloud login\nswanlab.login(\n    api_key=os.environ[\"SWANLAB_API_KEY\"],\n    host=\"http://your-server:5092\",\n)\n\n# Local-only logging\nrun = swanlab.init(\n    project=\"offline-demo\",\n    mode=\"local\",\n    logdir=\"./swanlog\",\n)\n\nswanlab.log({\"loss\": 0.35, \"epoch\": 1})\nrun.finish()\n```\n\n```bash\n# View local logs\nswanlab watch -l ./swanlog\n\n# Sync local logs later\nswanlab sync ./swanlog\n```\n\n## Integration Examples\n\n### HuggingFace Transformers\n\n```python\nfrom transformers import Trainer, TrainingArguments\n\ntraining_args = TrainingArguments(\n    output_dir=\"./results\",\n    per_device_train_batch_size=8,\n    evaluation_strategy=\"epoch\",\n    logging_steps=50,\n    report_to=\"swanlab\",\n    run_name=\"bert-finetune\",\n)\n\ntrainer = Trainer(\n    model=model,\n    args=training_args,\n    train_dataset=train_dataset,\n    eval_dataset=eval_dataset,\n)\n\ntrainer.train()\n```\n\nSee [references/integrations.md](references/integrations.md) for callback-based setups and additional framework patterns.\n\n### PyTorch Lightning\n\n```python\nimport pytorch_lightning as pl\nfrom swanlab.integration.pytorch_lightning import SwanLabLogger\n\nswanlab_logger = SwanLabLogger(\n    project=\"lightning-demo\",\n    experiment_name=\"mnist-classifier\",\n    config={\"batch_size\": 64, \"max_epochs\": 10},\n)\n\ntrainer = pl.Trainer(\n    logger=swanlab_logger,\n    max_epochs=10,\n    accelerator=\"auto\",\n)\n\ntrainer.fit(model, train_loader, val_loader)\n```\n\n### Fastai\n\n```python\nfrom fastai.vision.all import accuracy, resnet34, vision_learner\nfrom swanlab.integration.fastai import SwanLabCallback\n\nlearn = vision_learner(dls, resnet34, metrics=accuracy)\nlearn.fit(\n    5,\n    cbs=[\n        SwanLabCallback(\n            project=\"fastai-demo\",\n            experiment_name=\"pets-classification\",\n            config={\"arch\": \"resnet34\", \"epochs\": 5},\n        )\n    ],\n)\n```\n\nSee [references/integrations.md](references/integrations.md) for fuller framework examples.\n\n## Best Practices\n\n### 1. Use Stable Metric Names\n\n```python\n# Good: grouped metric namespaces\nswanlab.log({\n    \"train/loss\": train_loss,\n    \"train/accuracy\": train_acc,\n    \"val/loss\": val_loss,\n    \"val/accuracy\": val_acc,\n})\n\n# Avoid mixing flat and grouped names for the same metric family\n```\n\n### 2. Initialize Early and Capture Config Once\n\n```python\nrun = swanlab.init(\n    project=\"image-classification\",\n    experiment_name=\"resnet18-baseline\",\n    config={\n        \"model\": \"resnet18\",\n        \"learning_rate\": 3e-4,\n        \"batch_size\": 64,\n        \"seed\": 42,\n    },\n)\n```\n\n### 3. Save Checkpoints Locally\n\n```python\nimport torch\nimport swanlab\n\ncheckpoint_path = \"checkpoints/best.pth\"\ntorch.save(model.state_dict(), checkpoint_path)\n\nswanlab.log(\n    {\n        \"best/val_accuracy\": best_val_accuracy,\n        \"artifacts/checkpoint_path\": swanlab.Text(checkpoint_path),\n    }\n)\n```\n\n### 4. Use Local Mode for Offline-First Workflows\n\n```python\nrun = swanlab.init(project=\"offline-demo\", mode=\"local\", logdir=\"./swanlog\")\n# ... training code ...\nrun.finish()\n\n# Inspect later with: swanlab watch -l ./swanlog\n```\n\n### 5. Keep Advanced Patterns in References\n\n- Use [references/visualization.md](references/visualization.md) for advanced chart and media patterns\n- Use [references/integrations.md](references/integrations.md) for callback-based and framework-specific integration details\n\n## Resources\n\n- [Official docs (Chinese)](https://docs.swanlab.cn)\n- [Official docs (English)](https://docs.swanlab.cn/en)\n- [GitHub repo](https://github.com/SwanHubX/SwanLab)\n- [Self-hosted repo](https://github.com/SwanHubX/self-hosted)\n\n## See Also\n\n- [references/integrations.md](references/integrations.md) - Framework-specific examples\n- [references/visualization.md](references/visualization.md) - Charts and media logging patterns","author":"@Orchestra-Research","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/Orchestra-Research/AI-Research-SKILLs/tree/main/13-mlops/swanlab","license":"MIT","category":"coding","lang":"en","tokens":2436,"stars":0,"calls30d":2,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"references/integrations.md","size":8017,"sha256":"19330c5858713313989dfba3b3d00c87929fc29d74ee9a37b97eb5cdc84b7fd2"},{"path":"references/visualization.md","size":5796,"sha256":"9ab81ed4397eff3b3c3db12c0156bf5effae6d856fc00dad6196eb7482b6f610"}],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":false,"networkEndpoints":["docs.swanlab.cn"]}}