Skip to content

Commit 910a97f

Browse files
Zeyi-LinZeyi-Lin
committed
docs: sync wandb
1 parent a033579 commit 910a97f

File tree

5 files changed

+163
-25
lines changed

5 files changed

+163
-25
lines changed

‎assets/ig-wandb-4.png‎

385 KB
Loading

‎en/guide_cloud/general/changelog.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Github: https://github.com/SwanHubX/SwanLab
88
## v0.4.3 - 2025.1.17
99

1010
**🚀 New Features**
11-
- Added `swanlab.sync_wandb()`: Supports synchronizing metrics to SwanLab when using Weights&Biases for experiment tracking.
11+
- Added `swanlab.sync_wandb()`: Supports synchronizing metrics to SwanLab when using Weights&Biases for experiment tracking. [Docs](/en/guide_cloud/integration/integration-wandb.md)
1212
- Added framework integration: Configuration items will now record the framework being used.
1313

1414
**Optimizations**

‎en/guide_cloud/integration/integration-wandb.md‎

Lines changed: 87 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,114 @@
11
# Weights & Biases
22

3-
[Weights & Biases](https://github.com/wandb/wandb) (Wandb) is an experiment tracking, model optimization, and collaboration platform for machine learning and deep learning projects. W&B provides powerful tools to log and visualize experiment results, helping data scientists and researchers better manage and share their work.
3+
[Weights & Biases](https://github.com/wandb/wandb) (Wandb) is a platform for experiment tracking, model optimization, and collaboration in machine learning and deep learning projects. W&B provides powerful tools for recording and visualizing experimental results, helping data scientists and researchers better manage and share their work.
44

55
![wandb](/assets/ig-wandb.png)
66

7-
You can use `swanlab convert` to convert existing projects on Wandb into SwanLab projects.
7+
**You can synchronize projects from Wandb to SwanLab in two ways:**
8+
9+
1. **Synchronized Tracking**: If your current project uses wandb for experiment tracking, you can use the `swanlab.sync_wandb()` command to synchronize metrics to SwanLab while running the training script.
10+
2. **Convert Existing Projects**: If you want to copy a project from wandb to SwanLab, you can use `swanlab convert` to convert an existing project on Wandb to a SwanLab project.
811

912
::: info
10-
In the current version, only scalar charts are supported for conversion.
13+
The current version only supports converting scalar charts.
1114
:::
1215

13-
## Find Your Project, Entity, and Run ID
16+
[[toc]]
17+
18+
## 1. Synchronized Tracking
19+
20+
### 1.1 Add the `sync_wandb` Command
21+
22+
Add the `swanlab.sync_wandb()` command anywhere before `wandb.init()` in your code to synchronize wandb metrics to SwanLab during training.
23+
24+
```python
25+
import swanlab
26+
27+
swanlab.sync_wandb()
28+
29+
...
30+
31+
wandb.init()
32+
```
33+
34+
In the above code, `wandb.init()` will simultaneously initialize swanlab, with the project name, experiment name, and configuration matching the `project`, `name`, and `config` in `wandb.init()`. Therefore, you do not need to manually initialize swanlab.
35+
36+
### 1.2 Alternative Approach
37+
38+
Another approach is to manually initialize swanlab first, then run the wandb code.
39+
40+
```python
41+
import swanlab
42+
43+
swanlab.init(...)
44+
swanlab.sync_wandb()
45+
46+
...
47+
48+
wandb.init()
49+
```
50+
51+
In this approach, the project name, experiment name, and configuration will match the `project`, `experiment_name`, and `config` in `swanlab.init()`. The `project` and `name` in the subsequent `wandb.init()` will be ignored, and the `config` will be updated in `swanlab.config`.
52+
53+
### 1.3 Test Code
1454

15-
The `project`, `entity`, and `runid` are required for the conversion (runid is optional).
16-
Location of `project` and `entity`:
55+
```python
56+
import wandb
57+
import random
58+
import swanlab
59+
60+
swanlab.sync_wandb()
61+
# swanlab.init(project="sync_wandb")
62+
63+
wandb.init(
64+
project="test",
65+
config={"a": 1, "b": 2},
66+
name="test",
67+
)
68+
69+
epochs = 10
70+
offset = random.random() / 5
71+
for epoch in range(2, epochs):
72+
acc = 1 - 2 ** -epoch - random.random() / epoch - offset
73+
loss = 2 ** -epoch + random.random() / epoch + offset
74+
75+
wandb.log({"acc": acc, "loss": loss})
76+
```
77+
78+
![alt text](/assets/ig-wandb-4.png)
79+
80+
## 2. Convert Existing Projects
81+
82+
### 2.1 Locate Your Project, Entity, and Run ID on wandb.ai
83+
84+
The project, entity, and run ID are required for conversion (run ID is optional).
85+
The location of the project and entity:
1786
![alt text](/assets/ig-wandb-2.png)
1887

19-
Location of `runid`:
88+
The location of the run ID:
2089

2190
![alt text](/assets/ig-wandb-3.png)
2291

23-
## Method 1: Command Line Conversion
92+
### 2.2 Method 1: Command Line Conversion
2493

25-
First, ensure that you are logged into Wandb in the current environment and have access to the target project.
94+
First, ensure that you are logged into wandb in the current environment and have access to the target project.
2695

27-
Conversion command line:
96+
Conversion command:
2897

2998
```bash
3099
swanlab convert -t wandb --wb-project [WANDB_PROJECT_NAME] --wb-entity [WANDB_ENTITY]
31100
```
32101

33-
Supported parameters are as follows:
102+
Supported parameters:
34103

35-
- `-t`: Conversion type, options include `wandb` and `tensorboard`.
36-
- `--wb-project`: The name of the Wandb project to be converted.
37-
- `--wb-entity`: The space name where the Wandb project is located.
38-
- `--wb-runid`: The ID of the Wandb Run (an experiment under the project).
104+
- `-t`: Conversion type, options are wandb and tensorboard.
105+
- `--wb-project`: The name of the wandb project to be converted.
106+
- `--wb-entity`: The space name where the wandb project is located.
107+
- `--wb-runid`: The ID of the wandb Run (a specific experiment under the project).
39108

40-
If `--wb-runid` is not filled in, all Runs under the specified project will be converted; if filled in, only the specified Run will be converted.
109+
If `--wb-runid` is not provided, all Runs under the specified project will be converted; if provided, only the specified Run will be converted.
41110

42-
## Method 2: Conversion Within Code
111+
### 2.3 Method 2: Conversion Within Code
43112

44113
```python
45114
from swanlab.converter import WandbConverter
@@ -48,5 +117,4 @@ wb_converter = WandbConverter()
48117
# wb_runid is optional
49118
wb_converter.run(wb_project="WANDB_PROJECT_NAME", wb_entity="WANDB_USERNAME")
50119
```
51-
52-
This method achieves the same effect as the command line conversion.
120+
The effect is the same as command line conversion.

‎zh/guide_cloud/general/changelog.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Github: https://github.com/SwanHubX/SwanLab
88
## v0.4.3 - 2025.1.17
99

1010
**🚀新增功能**
11-
- 新增`swanlab.sync_wandb()`：支持使用Weights&Biases跟踪实验时，同步指标到SwanLab
11+
- 新增`swanlab.sync_wandb()`：支持使用Weights&Biases跟踪实验时，同步指标到SwanLab，[文档](/guide_cloud/integration/integration-wandb.md)
1212
- 新增在使用框架集成时，配置项将记录所使用的框架
1313

1414
**优化**

‎zh/guide_cloud/integration/integration-wandb.md‎

Lines changed: 74 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,83 @@
44

55
![wandb](/assets/ig-wandb.png)
66

7-
你可以使用swanlab convert将Wandb上已存在的项目转换成SwanLab项目。
7+
**你可以用两种方式将Wandb上的项目同步到SwanLab：**
8+
9+
1. **同步跟踪**：如果你现在的项目使用了wandb进行实验跟踪，你可以使用`swanlab.sync_wandb()`命令，在运行训练脚本时同步记录指标到SwanLab。
10+
2. **转换已存在的项目**：如果你想要将wandb上的项目复制到SwanLab，你可以使用`swanlab convert`，将Wandb上已存在的项目转换成SwanLab项目。
811

912
::: info
1013
在当前版本暂仅支持转换标量图表。
1114
:::
1215

13-
## 找到你的projecy、entity和runid
16+
[[toc]]
17+
18+
19+
## 1. 同步跟踪
20+
21+
### 1.1 添加sync_wandb命令
22+
23+
在你的代码执行`wandb.init()`之前的任何位置，添加一行`swanlab.sync()`命令，即可在训练时同步wandb的指标到SwanLab。
24+
25+
```python
26+
import swanlab
27+
28+
swanlab.sync_wandb()
29+
30+
...
31+
32+
wandb.init()
33+
```
34+
35+
在上述这种代码写法中，`wandb.init()`的同时会初始化swanlab，项目名、实验名和配置和`wandb.init()`中的`project`、`name`、`config`一致，因此你不需要再手动初始化swanlab。
36+
37+
### 1.2 另一种写法
38+
39+
另一种用法是先手动初始化swanlab，再运行wandb的代码。
40+
41+
```python
42+
import swanlab
43+
44+
swanlab.init(...)
45+
swanlab.sync_wandb()
46+
47+
...
48+
49+
wandb.init()
50+
```
51+
52+
在这种写法中，项目名、实验名、配置和`swanlab.init()`中的`project`、`experiment_name`、`config`一致，而后续`wandb.init()`中的`project`、`name`会被忽略，`config`会更新进`swanlab.config`中。
53+
54+
### 1.3 测试代码
55+
56+
```python
57+
import wandb
58+
import random
59+
import swanlab
60+
61+
swanlab.sync_wandb()
62+
# swanlab.init(project="sync_wandb")
63+
64+
wandb.init(
65+
project="test",
66+
config={"a": 1, "b": 2},
67+
name="test",
68+
)
69+
70+
epochs = 10
71+
offset = random.random() / 5
72+
for epoch in range(2, epochs):
73+
acc = 1 - 2 ** -epoch - random.random() / epoch - offset
74+
loss = 2 ** -epoch + random.random() / epoch + offset
75+
76+
wandb.log({"acc": acc, "loss": loss})
77+
```
78+
79+
![alt text](/assets/ig-wandb-4.png)
80+
81+
## 2. 转换已存在的项目
82+
83+
### 2.1 找到你在wandb.ai上的projecy、entity和runid
1484

1585
projecy、entity和runid是转换所需要的（runid是可选的）。
1686
project和entity的位置：
@@ -20,7 +90,7 @@ runid的位置：
2090

2191
![alt text](/assets/ig-wandb-3.png)
2292

23-
## 方式一：命令行转换
93+
### 2.2 方式一：命令行转换
2494

2595
首先，需要确保当前环境下，你已登录了wandb，并有权限访问目标项目。
2696

@@ -39,7 +109,7 @@ swanlab convert -t wandb --wb-project [WANDB_PROJECT_NAME] --wb-entity [WANDB_EN
39109

40110
如果不填写`--wb-runid`，则会将指定项目下的全部Run进行转换；如果填写，则只转换指定的Run。
41111

42-
## 方式二：代码内转换
112+
### 2.3 方式二：代码内转换
43113

44114
```python
45115
from swanlab.converter import WandbConverter

0 commit comments

Comments
 (0)