SwanLab

https://github.com/swanhubx/swanlab
Admin
SwanLab is an AI training analysis platform providing experiment tracking, visualization, and...
Tokens:5,798
Snippets:72
Trust Score:9.3
License:Apache-2.0
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install SwanLab via pip

Source: https://github.com/swanhubx/swanlab/blob/main/README_EN.md

Standard installation command for the SwanLab package.

```bash
pip install swanlab
```

--------------------------------

### Install SwanLab from source

Source: https://github.com/swanhubx/swanlab/blob/main/README_EN.md

Alternative installation methods to access the latest features directly from the repository.

```bash
# Method 1
git clone https://github.com/SwanHubX/SwanLab.git
pip install -e .

# Method 2
pip install git+https://github.com/SwanHubX/SwanLab.git
```

--------------------------------

### Install SwanLab dashboard extension

Source: https://github.com/swanhubx/swanlab/blob/main/README_EN.md

Installs the optional dashboard extension for enhanced visualization capabilities.

```bash
pip install 'swanlab[dashboard]'
```

--------------------------------

### 生成 Protobuf 代码

Source: https://github.com/swanhubx/swanlab/blob/main/docs/skills/pr-review-core/SKILL.md

在具备完整工具链的环境下，通过 make 命令重新生成 proto 相关代码。

```bash
make proto
```

--------------------------------

### 执行本地验证

Source: https://github.com/swanhubx/swanlab/blob/main/docs/skills/pr-review-core/SKILL.md

在 core 目录下运行测试、代码检查和构建，确保代码质量符合 CI 要求。

```bash
cd core && go test -race $(go list ./... | grep -v /proto/)
cd core && golangci-lint run
cd core && go build ./...
```

--------------------------------

### Integrate SwanLab into Python code

Source: https://github.com/swanhubx/swanlab/blob/main/README_EN.md

Initializes an experiment and logs metrics during the training loop.

```python
import swanlab

# Initialize a new SwanLab experiment
swanlab.init(
    project="my-first-ml",
    config={'learning-rate': 0.003},
)

# Log metrics
for i in range(10):
    swanlab.log({"loss": i, "acc": i})
```

--------------------------------

### 审核正文模板

Source: https://github.com/swanhubx/swanlab/blob/main/docs/skills/pr-review-core/SKILL.md

提交审核时使用的 Markdown 模板，用于记录审核结论、范围及验证状态。

```markdown
## 审核结论: 通过 / 要求修改 / 评论

## 本次 PR 解决的问题

<一句话概述>

## 审核范围

- [x] 平台与进程生命周期: <详情>
- [x] 控制台与诊断日志: <详情>
- [x] Protobuf 与生成代码: <详情>
- [x] Go 模块、工具链与构建: <详情>
- [x] Go core 横切质量与代码规范: <详情>
- [x] 安全、性能与跨平台兼容: <详情>
- [x] 测试与验证: <详情>

## 未挂行发现

<没有则写：无>

## 验证

- [ ] go test -race
- [ ] golangci-lint run
- [ ] go build ./...
- [ ] PR Actions 已通过，或已记录未运行/失败状态
```

--------------------------------

### Login to SwanLab

Source: https://github.com/swanhubx/swanlab/blob/main/README_EN.md

Command to initiate the authentication process using an API key.

```bash
swanlab login
```

--------------------------------

### 查看 PR 信息与差异

Source: https://github.com/swanhubx/swanlab/blob/main/docs/skills/pr-review-core/SKILL.md

用于在审核阶段一获取 PR 的元数据、文件变更列表及差异内容。

```bash
gh pr view <PR>
gh pr view <PR> --json files,additions,deletions,baseRefName,headRefName
gh pr diff <PR>
gh pr checks <PR>
```

--------------------------------

### 创建隔离工作区

Source: https://github.com/swanhubx/swanlab/blob/main/docs/skills/pr-review-core/SKILL.md

将 PR 的 head 分支拉取到本地隔离的 worktree 中，避免污染当前工作区。

```bash
git fetch origin pull/<PR>/head:pr-<PR>
git worktree add ../swanlab-pr-<PR> pr-<PR>
```

--------------------------------

### Add SwanLab Badge to README

Source: https://github.com/swanhubx/swanlab/blob/main/README_EN.md

Markdown code to display SwanLab project badges in a repository README file.

```markdown
[![](https://raw.githubusercontent.com/SwanHubX/assets/main/badge2.svg)](your experiment url)
[![](https://raw.githubusercontent.com/SwanHubX/assets/main/badge1.svg)](your experiment url)
```

--------------------------------

### 清理临时工作区

Source: https://github.com/swanhubx/swanlab/blob/main/docs/skills/pr-review-core/SKILL.md

在发布审核结论后，移除临时创建的 worktree 并删除本地分支。

```bash
git worktree remove ../swanlab-pr-<PR>
git branch -D pr-<PR>
```

--------------------------------

### Directory Structure

Source: https://github.com/swanhubx/swanlab/blob/main/protos/README.md

The directory structure of the protos directory, outlining the organization of Protobuf definitions.

```protobuf
protos/
└── swanlab/
    ├── record/
    │   └── v1/
    │       └── record.proto            # Top-level envelope Record
    │
    ├── run/
    │   └── v1/
    │       └── run.proto               # Run lifecycle (StartRecord, FinishRecord, RunState, ResumeMode)
    │
    ├── metric/
    │   ├── column/
    │   │   └── v1/
    │   │       └── column.proto        # Column definition (ColumnRecord), describing metric display and categorization configuration
    │   └── data/
    │       └── v1/
    │           └── data.proto          # Metric data (ScalarRecord, MediaRecord)
    │
    ├── config/
    │   └── v1/
    │       └── config.proto            # Experiment configuration reference (ConfigRecord, UpdateType)
    │
    ├── env/
    │   └── v1/
    │       └── env.proto               # Software environment and host metadata reference (MetadataRecord, RequirementsRecord, CondaRecord)
    │
    ├── terminal/
    │   └── v1/
    │       └── log.proto               # Terminal proxy captured stdout/stderr output (LogRecord, LogLevel)
    │
    ├── save/
    │   └── v1/
    │       └── save.proto              # File save record (SaveRecord, SavePolicy)
    │
    ├── settings/
    │   ├── core/
    │   │   └── v1/
    │   │       └── core.proto          # Core synchronization service configuration (CoreSettings)
    │   └── probe/
    │       └── v1/
    │           └── probe.proto         # Probe hardware acquisition service configuration (ProbeSettings)
    │
    └── grpc/
        ├── core/
        │   ├── v1/
        │   │   ├── core.proto          # CoreService gRPC service (receives experiment records)
        │   │   └── sync.proto          # CoreSyncService gRPC service (starts log synchronization)
        │   └── ...
        └── probe/
            └── v1/
                └── probe.proto         # ProbeService gRPC service (starts hardware acquisition)
```

--------------------------------

### Message Flow

Source: https://github.com/swanhubx/swanlab/blob/main/protos/README.md

Illustrates the sequence of messages generated during a SwanLab run, from initialization to completion.

```protobuf
swanlab.init(...)
  → Record { start:        StartRecord        }   # Run basic information, written once
  → Record { metadata:     MetadataRecord     }   # Host and environment snapshot reference, written once
  → Record { requirements: RequirementsRecord }   # Python dependency reference, written once
  → Record { conda:        CondaRecord        }   # Conda environment reference, written once
  → Record { config:       ConfigRecord       }   # Experiment config (INIT), written once

# When a key first appears in the training loop, send column definition first
  → Record { column: ColumnRecord { key="loss", type=SCALAR, ... } }
  → Record { column: ColumnRecord { key="img",  type=IMAGE, ... } }
# Each metric generates a separate Record, swanlab.log({"loss": 0.5, "img": Image(...)}, step=10) generates two:
  → Record { scalar: ScalarRecord { key="loss", step=10, ... } }
  → Record { media:  MediaRecord  { key="img",  step=10, ... } }

# Terminal proxy (per line)
  → Record { log: LogRecord { line="...", level=INFO } }

# Config update during run
  → Record { config: ConfigRecord { update_type=PATCH, ... } }

# File save
  → Record { save: SaveRecord { name="...", policy=NOW } }

swanlab.finish()
  → Record { finish: FinishRecord { state=FINISHED } }
```

--------------------------------

### Cite SwanLab in Research Papers

Source: https://github.com/swanhubx/swanlab/blob/main/README_EN.md

BibTeX entry for citing SwanLab in academic publications.

```bibtex
@software{Zeyilin_SwanLab_2023,
  author = {Zeyi Lin, Shaohong Chen, Kang Li, Qiushan Jiang, Zirui Cai,  Kaifang Ji and {The SwanLab team}},
  doi = {10.5281/zenodo.11100550},
  license = {Apache-2.0},
  title = {{SwanLab}},
  url = {https://github.com/swanhubx/swanlab},
  year = {2023}
}
```
Tokens:
Raw