swanlab-skill

SwanLab Skill

SwanLab 是一个 AI 训练实验跟踪平台。本 Skill 涵盖两种使用场景：

• 编写跟踪代码 — 使用 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 会报错，而不会回退到其他模式。

---

脚本

有两个辅助脚本可用于可视化实验数据：

scripts/plot_metrics.py — 单个实验折线图

当用户想要可视化单个实验的标量指标时触发（例如“绘制我的损失曲线”“显示训练指标图表”）。

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 — 跨实验比较

当用户想要比较多个实验中的同一指标时触发（例如“比较不同运行的损失”“对这些实验进行基准测试”）。

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
“我的实验” / “列出运行”	列出实验	CLI_REFERENCE.md > run list
“以可视化方式比较运行”	跨实验图表	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
运行字段 / 运行列表或运行信息响应	运行对象架构	SWANLAB_CONCEPTS.md > Run Object Schema
“分析此项目/运行” / “实验报告”	分析流程	ANALYSIS_GUIDE.md

---

环境连接

在编写跟踪代码或运行 CLI 查询之前，尤其是在 online 模式下，请先运行以下两项检查，确认环境已就绪：

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 文件中读取 API key 和主机地址（该文件由 swanlab login 创建）。

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 编码 Agent 最常见的 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