Weights & Biases (W&B) 集成操作指南

1. 环境准备

1.1 安装依赖

# 安装最新版wandb（推荐≥0.17.5）
pip install wandb --upgrade

# 验证安装
python -c "import wandb; print(f'Wandb version: {wandb.__version__}')"
### 1.2 添加必要导入

 - 在所有训练/验证文件中添加：

```bash
 import wandb  # 必须放在文件顶部

2. 初始化配置

2.1 主函数初始化

def main():
    # 必须最先初始化（整个训练过程只调用一次）
    wandb.init(
        project="lcl-saliency",    # 项目名称
        name="stem-v1",            # 实验标识
        config={
            "max_epochs": 150,
            "batch_size": 32,
            "base_lr": 1e-4,
            "optimizer": "AdamW"
        }
    )
    
    global_step = 0  # 全局步数计数器
    # 后续训练代码...

2.2 配置参数说明

参数	必须	说明	示例值
project	✓	项目名称（区分不同任务）	lcl-saliency
name	✗	实验名称（区分不同配置）	stem-ela-v2
config	✓	超参数配置字典	自定义字典
resume	✗	断点续训模式	"allow"

3. 训练循环配置

3.1 全局步数管理

for epoch in range(max_epochs):
    # 设置学习率
    current_lr = lr_schedule[epoch]
    for param_group in optimizer.param_groups:
        param_group["lr"] = current_lr
    
    # 记录学习率（使用当前全局步数）
    wandb.log({"epoch/lr": current_lr}, step=global_step)
    
    # 训练阶段
    global_step = train_one_epoch(
        model, 
        train_loader,
        global_step,
        wandb=wandb  # 传递wandb实例
    )

3.2 训练步骤实现

def train_one_epoch(model, loader, global_step, wandb=None):
    model.train()
    
    for batch_idx, (images, labels) in enumerate(loader):
        # ...前向传播和损失计算...
        
        # 每10步记录batch指标
        if batch_idx % 10 == 0 and wandb:
            wandb.log({
                "batch/total_loss": loss.item(),
                "batch/loss_L0": loss_L0.item(),
                "batch/distance1": distance1
            }, step=global_step)
            
        global_step += 1  # 关键：必须递增
        
    return global_step

4. 验证阶段记录

4.1 验证指标记录

def validate(model, loader, global_step):
    model.eval()
    
    total_cc, total_kl = 0.0, 0.0
    
    with torch.no_grad():
        for images, labels in loader:
            # ...前向计算...
            total_cc += cc_coeff
            total_kl += kl_div
            
    # 记录验证指标
    wandb.log({
        "val/cc": total_cc / len(loader),
        "val/kl": total_kl / len(loader)
    }, step=global_step)

5. 日志规范

5.1 推荐日志结构

指标类型	前缀	示例	记录频率
Batch指标	batch/	batch/total_loss	每10-50步
Epoch统计	epoch/	epoch/lr	每个epoch
验证指标	val/	val/cc	每个验证周期

5.2 完整示例

# Batch级别
wandb.log({
    "batch/total_loss": 1.234,
    "batch/loss_L0": 0.456,
    "batch/distance1": 0.789
}, step=global_step)

# Epoch级别
wandb.log({
    "epoch/total_loss": 2.345,
    "epoch/loss_L0": 1.678,
    "epoch/lr": 1e-4
}, step=global_step)

# 验证级别
wandb.log({
    "val/cc": 0.852,
    "val/kl": 1.237,
    "val/sim": 0.914
}, step=global_step)

6. 常见问题处理

6.1 错误排查表

错误现象	解决方案
You must call wandb.init()	确保在所有wandb.log调用前初始化
步骤值非单调递增	使用统一的global_step全局计数器
浏览器无法打开控制台	检查网络连接，使用wandb offline本地模式

6.2 高级配置示例

# 离线调试模式
wandb.init(mode="disabled")

# 分布式训练配置
wandb.init(settings=wandb.Settings(start_method="fork"))

# 恢复中断的训练
wandb.init(resume="allow")

7. 监控与调试

7.1 实时监控命令

# 查看运行状态
wandb status
# 同步离线运行记录
wandb sync ./wandb/run-20240301_123456-abc123

7.2 代码内调试

# 打印控制台URL
print(f"控制台地址: {wandb.run.get_url()}")

# 异常捕获
try:
    wandb.log(data)
except wandb.errors.Error as e:
    print(f"Wandb记录失败: {str(e)}")
    # 可选：将日志写入本地文件备份

8. 成功运行验证

• 预期终端输出

wandb: Currently logged in as: your-account
wandb: Tracking run with wandb version 0.17.5
wandb: Run data is saved locally in /path/to/wandb/run-20240301_123456-abc123
wandb: Syncing run radiant-sunset-42
wandb: 🚀 View run at https://wandb.ai/your-team/your-project/runs/abc123