weights-and-biases

Weights & Biases：ML 実験追跡と MLOps

このスキルを使用する場面

次のような場合に Weights & Biases (W&B) を使用します。

• ML 実験を追跡する（メトリクスの自動記録）
• トレーニングを可視化する（リアルタイムのダッシュボード）
• 実行結果を比較する（ハイパーパラメーターや設定ごと）
• ハイパーパラメーターを最適化する（自動スイープ）
• モデルレジストリを管理する（バージョン管理とリネージ）
• ML プロジェクトで共同作業する（チームのワークスペース）
• アーティファクトを追跡する（データセット、モデル、コードとリネージ）

インストール

# Install W&B
pip install wandb

# Login (creates API key)
wandb login

# Or set API key programmatically
export WANDB_API_KEY=your_api_key_here

クイックスタート

基本的な実験追跡

import wandb

# Initialize a run
run = wandb.init(
    project="my-project",
    config={
        "learning_rate": 0.001,
        "epochs": 10,
        "batch_size": 32,
        "architecture": "ResNet50"
    }
)

# Training loop
for epoch in range(run.config.epochs):
    # Your training code
    train_loss = train_epoch()
    val_loss = validate()

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

# Finish the run
wandb.finish()

PyTorch を使用する場合

import torch
import wandb

# Initialize
wandb.init(project="pytorch-demo", config={
    "lr": 0.001,
    "epochs": 10
})

# Access config
config = wandb.config

# Training loop
for epoch in range(config.epochs):
    for batch_idx, (data, target) in enumerate(train_loader):
        # Forward pass
        output = model(data)
        loss = criterion(output, target)

        # Backward pass
        optimizer.zero_grad()
        loss.backward()
        optimizer.step()

        # Log every 100 batches
        if batch_idx % 100 == 0:
            wandb.log({
                "loss": loss.item(),
                "epoch": epoch,
                "batch": batch_idx
            })

# Save model
torch.save(model.state_dict(), "model.pth")
wandb.save("model.pth")  # Upload to W&B

wandb.finish()

中核となる概念

1. プロジェクトと実行

プロジェクト：関連する実験の集まり
実行：トレーニングスクリプトを1回実行したもの

# Create/use project
run = wandb.init(
    project="image-classification",
    name="resnet50-experiment-1",  # Optional run name
    tags=["baseline", "resnet"],    # Organize with tags
    notes="First baseline run"      # Add notes
)

# Each run has unique ID
print(f"Run ID: {run.id}")
print(f"Run URL: {run.url}")

2. 設定の追跡

ハイパーパラメーターを自動的に追跡します。

config = {
    # Model architecture
    "model": "ResNet50",
    "pretrained": True,

    # Training params
    "learning_rate": 0.001,
    "batch_size": 32,
    "epochs": 50,
    "optimizer": "Adam",

    # Data params
    "dataset": "ImageNet",
    "augmentation": "standard"
}

wandb.init(project="my-project", config=config)

# Access config during training
lr = wandb.config.learning_rate
batch_size = wandb.config.batch_size

3. メトリクスの記録

# Log scalars
wandb.log({"loss": 0.5, "accuracy": 0.92})

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

# Log with custom x-axis
wandb.log({"loss": loss}, step=global_step)

# Log media (images, audio, video)
wandb.log({"examples": [wandb.Image(img) for img in images]})

# Log histograms
wandb.log({"gradients": wandb.Histogram(gradients)})

# Log tables
table = wandb.Table(columns=["id", "prediction", "ground_truth"])
wandb.log({"predictions": table})

4. モデルのチェックポイント保存

import torch
import wandb

# Save model checkpoint
checkpoint = {
    'epoch': epoch,
    'model_state_dict': model.state_dict(),
    'optimizer_state_dict': optimizer.state_dict(),
    'loss': loss,
}

torch.save(checkpoint, 'checkpoint.pth')

# Upload to W&B
wandb.save('checkpoint.pth')

# Or use Artifacts (recommended)
artifact = wandb.Artifact('model', type='model')
artifact.add_file('checkpoint.pth')
wandb.log_artifact(artifact)

ハイパーパラメータースイープ

詳細、コード例、パラメーター表については、references/hyperparameter-sweeps.md を参照してください。この手順が該当する場合に読みます。

アーティファクト

データセット、モデル、その他のファイルをリネージとともに追跡します。

アーティファクトを記録する

# Create artifact
artifact = wandb.Artifact(
    name='training-dataset',
    type='dataset',
    description='ImageNet training split',
    metadata={'size': '1.2M images', 'split': 'train'}
)

# Add files
artifact.add_file('data/train.csv')
artifact.add_dir('data/images/')

# Log artifact
wandb.log_artifact(artifact)

アーティファクトを使用する

# Download and use artifact
run = wandb.init(project="my-project")

# Download artifact
artifact = run.use_artifact('training-dataset:latest')
artifact_dir = artifact.download()

# Use the data
data = load_data(f"{artifact_dir}/train.csv")

モデルレジストリ

# Log model as artifact
model_artifact = wandb.Artifact(
    name='resnet50-model',
    type='model',
    metadata={'architecture': 'ResNet50', 'accuracy': 0.95}
)

model_artifact.add_file('model.pth')
wandb.log_artifact(model_artifact, aliases=['best', 'production'])

# Link to model registry
run.link_artifact(model_artifact, 'model-registry/production-models')

統合例

詳細、コード例、パラメーター表については、references/integration-examples.md を参照してください。この手順が該当する場合に読みます。

可視化と分析

カスタムチャート

# Log custom visualizations
import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot(x, y)
wandb.log({"custom_plot": wandb.Image(fig)})

# Log confusion matrix
wandb.log({"conf_mat": wandb.plot.confusion_matrix(
    probs=None,
    y_true=ground_truth,
    preds=predictions,
    class_names=class_names
)})

レポート

W&B UI で共有可能なレポートを作成します。

• 実行結果、チャート、テキストを組み合わせる
• Markdown をサポート
• 埋め込み可能な可視化
• チームでの共同作業

ベストプラクティス

1. タグとグループで整理する

wandb.init(
    project="my-project",
    tags=["baseline", "resnet50", "imagenet"],
    group="resnet-experiments",  # Group related runs
    job_type="train"             # Type of job
)

2. 関連する情報をすべて記録する

# Log system metrics
wandb.log({
    "gpu/util": gpu_utilization,
    "gpu/memory": gpu_memory_used,
    "cpu/util": cpu_utilization
})

# Log code version
wandb.log({"git_commit": git_commit_hash})

# Log data splits
wandb.log({
    "data/train_size": len(train_dataset),
    "data/val_size": len(val_dataset)
})

3. 内容がわかる名前を付ける

# ✅ Good: Descriptive run names
wandb.init(
    project="nlp-classification",
    name="bert-base-lr0.001-bs32-epoch10"
)

# ❌ Bad: Generic names
wandb.init(project="nlp", name="run1")

4. 重要なアーティファクトを保存する

# Save final model
artifact = wandb.Artifact('final-model', type='model')
artifact.add_file('model.pth')
wandb.log_artifact(artifact)

# Save predictions for analysis
predictions_table = wandb.Table(
    columns=["id", "input", "prediction", "ground_truth"],
    data=predictions_data
)
wandb.log({"predictions": predictions_table})

5. 接続が不安定な場合はオフラインモードを使用する

import os

# Enable offline mode
os.environ["WANDB_MODE"] = "offline"

wandb.init(project="my-project")
# ... your code ...

# Sync later
# wandb sync <run_directory>

チームでの共同作業

実行結果を共有する

# Runs are automatically shareable via URL
run = wandb.init(project="team-project")
print(f"Share this URL: {run.url}")

チームプロジェクト

• wandb.ai でチームアカウントを作成する
• チームメンバーを追加する
• プロジェクトの公開範囲（非公開／公開）を設定する
• チームレベルのアーティファクトとモデルレジストリを使用する

料金

• 無料：公開プロジェクトは無制限、ストレージは 100GB
• アカデミック：学生・研究者は無料
• チーム：$50/シート/月、非公開プロジェクト、ストレージ無制限
• エンタープライズ：個別料金、オンプレミスのオプション

リソース

• ドキュメント：https://docs.wandb.ai
• GitHub：https://github.com/wandb/wandb
• 例：https://github.com/wandb/examples
• コミュニティ：https://wandb.ai/community
• Discord：https://wandb.me/discord

関連項目

• references/sweeps.md - ハイパーパラメーター最適化の包括的なガイド
• references/artifacts.md - データとモデルのバージョン管理パターン
• references/integrations.md - フレームワーク別の例

エージェントの運用手順

1. 環境を確認します。 ハードウェア、フレームワークとサーバーのバージョン、モデル形式、想定負荷を確認します。
2. 入力を特定します。 データまたはユーザーから、形式、識別子、パラメーターを確認します。結果を左右する値は推測せず、質問してください。
3. まず小規模に実行します。 スケールアップする前に、単一のリクエストを処理または記録するか、エンドツーエンドで実行します。
4. 上記の手順と参考情報を使って、タスク全体を実行します。
5. 結果を検証します。 レイテンシ、スループット、出力の正確性を参照値と照らし合わせて測定し、リソース使用量とコストを確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確定事項を明示します。

次の状況が発生した場合	対応
サーバーが起動しない、または OOM が発生する	モデルサイズとメモリ、量子化、並列処理の設定を確認します。
これらの手順にある関数、フラグ、エンドポイントが、インストール済みバージョンにない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認し、適宜対応してユーザーに伝えます。API をでっち上げてはいけません。
必須の入力、識別子、パラメーターが曖昧	ユーザーに質問するか、実行前に前提を明示します。

誠実性に関するルール

• 結果、パラメーター、識別子、引用、統計情報を決して捏造しないでください。実行または検証できない場合は、その旨を明確に伝えてください。
• サービスや認証情報を公開しないでください。プロビジョニングする前に、クラウドのコストを確認してください。
• ここに記載されているバージョン固有の詳細は古くなっている可能性があります。インストール済みバージョンの公式ドキュメントで確認してください。
• 費用が発生する操作、共有 GPU やクラウドクォータを消費する操作、個人データや患者データに触れる操作、取り消せない操作を行う前に、ユーザーに確認してください。