swanlab-skill

SwanLab スキル

SwanLab は AI トレーニング実験の追跡プラットフォームです。このスキルでは、次の 2 つの使用パターンを扱います。

• 追跡コードの記述 — Python SDK（swanlab.init、swanlab.log、swanlab.finish、メディアヘルパー）を使用します
• 実験データの読み取り — swanlab api CLI を使用して、メトリクス、ログ、サマリー、メディアなどをクエリします

---

リファレンスの参照先

ユーザーの要望	参照するドキュメント
追跡コード（init/log/finish/media）を記述する	references/SDK_QUICKSTART.md
CLI でデータをクエリする（metrics/summary/logs/filter など）	references/CLI_REFERENCE.md
データモデル、用語、フィルター構文を理解する	references/SWANLAB_CONCEPTS.md
実行やプロジェクトを分析し、実験を比較して、実験レポートを作成する	references/ANALYSIS_GUIDE.md
メトリクスをプロットしたり、実験を視覚的に比較したりする	以下の スクリプト を参照してください

バージョンに関する注意（SDK ≥ 0.9.0）：swanlab api run series を使用して、実験のメトリクスキーを確認してください。run column / run columns は 0.9.0 以降非推奨で、マルチビュー実験には適用されません。インストール済み SDK が < 0.9.0 の場合に限り、代替手段として使用してください。詳しくは CLI_REFERENCE.md > Version Applicability を参照してください。

---

実行モード

swanlab.init(mode=...) はデータの保存先を制御します。

モード	ローカルストレージ	クラウドへのアップロード	用途
online	はい（protobuf）	はい（Transport → HTTP）	通常のクラウド利用です。ログインが必要です。
local	はい（protobuf）	いいえ	インターネットから隔離された環境での利用。アカウントは不要です。
offline	はい（protobuf）	いいえ（後で swanlab sync により同期可能）	ローカルに保存し、後でクラウドにアップロードします。
disabled	いいえ	いいえ	すべてのログ記録を完全に無効にします。

ログイン済みの場合、デフォルトは online です。それ以外の場合は、ログイン、登録、または offline を選択する対話型プロンプトが表示されます。API キーがない非対話型環境では、フォールバックせずに init がエラーを発生させます。

---

スクリプト

実験データを可視化するためのヘルパースクリプトが 2 つあります。

scripts/plot_metrics.py — 単一実験の折れ線グラフ

ユーザーが1 つの実験のスカラー指標を可視化したい場合に使用します（例：「loss 曲線をプロットして」「トレーニング指標のグラフを表示して」）。

python scripts/plot_metrics.py username/project_name/run_id --keys loss,acc
python scripts/plot_metrics.py user/proj/run1 -k loss -o loss_chart.png -s 500
python scripts/plot_metrics.py --data metrics.json -k loss,acc -o chart.png   # from saved JSON

scripts/runs_benchmark.py — 実験間の比較

ユーザーが複数の実験にわたって同じ指標を比較したい場合に使用します（例：「実行間で loss を比較して」「これらの実験をベンチマークして」）。

python scripts/runs_benchmark.py user/proj/run1 user/proj/run2 user/proj/run3 -k loss
python scripts/runs_benchmark.py user/proj/run1 user/proj/run2 -k loss --direction lower
python scripts/runs_benchmark.py user/proj/run1 user/proj/run2 -k loss,acc --normalize
python scripts/runs_benchmark.py --data benchmark_data.json -k loss              # from saved JSON

どちらのスクリプトも swanlab login（または --api-key / --host フラグ）が必要です。

---

パスの規則

CLI コマンドでは、username/project_name（プロジェクト）または username/project_name/run_id（実験）を使用します。詳しくは SWANLAB_CONCEPTS.md > Path Convention を参照してください。

---

すばやく内容を見分ける

ユーザーの発言...	意味している可能性が高いもの	参照先
「トレーニングを追跡したい」／「メトリクスを記録したい」	トラッキングコードの作成	SDK_QUICKSTART.md
「画像／音声／テキストを記録したい」	メディアデータの記録	SDK_QUICKSTART.md
「自分の損失曲線」／「実験メトリクス」	スカラー値データのクエリ	CLI_REFERENCE.md > run metrics
「実験を絞り込みたい」	条件によるクエリ	CLI_REFERENCE.md > run filter
「自分の実験」／「run を一覧表示したい」	実験の一覧表示	CLI_REFERENCE.md > run list
「run を視覚的に比較したい」	複数の実験をまたぐチャート	scripts/runs_benchmark.py
「メトリクスのチャートを描画したい」	単一実験のチャート	scripts/plot_metrics.py
「実験の設定」	ハイパーパラメーター	CLI_REFERENCE.md > run info
「コンソール出力」	キャプチャされたログ	CLI_REFERENCE.md > run logs
「どのメトリクスが追跡されているか」	メトリクスキー	CLI_REFERENCE.md > run series
「接続を確認したい」／「swanlab に接続できるか」	環境の確認	swanlab ping
「ログイン状態を確認したい」／「ログインできているか」	認証情報の検証	swanlab verify
「プロジェクトが見つからない」／クエリが 404 を返す	ホストの誤り（可能性が高い）	CLI_REFERENCE.md > Troubleshooting
run のフィールド／run list または run info の応答	Run オブジェクトのスキーマ	SWANLAB_CONCEPTS.md > Run Object Schema
「このプロジェクト／run を分析したい」／「実験レポート」	分析パイプライン	ANALYSIS_GUIDE.md

---

環境の接続性

トラッキングコードを作成したり CLI クエリを実行したりする前に、特に online モードでは、次の 2 つのチェックを実行して環境の準備ができていることを確認してください。

1. swanlab ping — ネットワーク到達性をテストする

接続の問題を診断する最も手早い方法です。ユーザーからアップロードの失敗、ログインの問題、予期しないモードへのフォールバックについて報告があった場合は、まず実行してください。

swanlab ping
# Reports: API host, web host, latency, and login status.
# If ping fails, check SWANLAB_API_HOST / network proxy / firewall settings.

2. swanlab verify — ログイン認証情報を検証する

サーバーに接続できることを確認したら、swanlab verify を使って、保存されている認証情報が有効で、期限切れになっていないことを確認してください。このコマンドは、ローカルの .netrc ファイル（swanlab login によって作成）から API キーとホストを読み取ります。

swanlab verify
# Validates stored API key against the server.
# Reports: which host (default https://swanlab.cn) and the logged-in username.
# Fails if: not logged in, API key is invalid, or key has expired.

swanlab verify --local
# Check local login status (.swanlab in current directory) instead of the global one.

推奨される事前確認手順：

1. swanlab ping → サーバーに接続できることを確認します
2. swanlab verify → 認証情報が有効であることを確認し、ログイン先のホストを確認します
3. 対象のプロジェクトがそのホスト上にあることを確認します。 SwanLab には互いに独立した複数のインスタンス（公開版の swanlab.cn とセルフホスト可能なデプロイメント）があり、認証情報はインスタンスごとに異なります。詳しくは SWANLAB_CONCEPTS.md > Instances, Hosts & Credentials を参照してください。プロジェクトが別のインスタンスにある場合は、すべてのコマンドに --host／--api-key を指定するか、SWANLAB_API_HOST／SWANLAB_API_KEY をエクスポートしてください。project info／run list が 404 Not_Found を返す場合は、プロジェクトが存在しないのではなく、ホストが間違っています。詳しくは CLI_REFERENCE.md > Troubleshooting を参照してください。
4. swanlab api クエリまたは SDK コードに進みます

---

動作上の制約

全項目については、CLI_REFERENCE.md > Behavioral Constraints を参照してください。主なルールは次のとおりです。

• ユーザーから明示的に求められた場合にのみ --all を使用してください（例：「すべて取得して」「全部取得して」「完全な一覧」）。ページネーション対応の一覧コマンドでは、常にデフォルトのページネーション（--page_num / --page_size）を使用してください。
• run metrics または run medias を実行する前に、必ず具体的なメトリクスキーを確認してください。 キー名がわからない場合は、まず run series PATH を実行して確認してください（SDK < 0.9.0 では、代替手段として run columns PATH を使用してください）。
• 大量のメトリクスデータは必ず --save でファイルに保存してから、scripts/plot_metrics.py --data file.json で可視化するか、集計統計には run summary を使用してください。

---

さらに詳しく

このスキルでは、AI コーディングエージェントでよく使われる SwanLab ワークフローを扱います。ここで扱っていない内容（SDK の全機能、CLI の高度なフラグ、セルフホスト環境へのデプロイ、連携など）については、SwanLab の公式ドキュメントを参照してください。

• クラウドガイド（SwanLab の概要、概念、使い方）：https://docs.swanlab.cn/guide_cloud/general/what-is-swanlab.md
• Python SDK と OpenAPI リファレンス：https://docs.swanlab.cn/api/api-index.md