seetrain-ml 0.1.26
深度学习实验跟踪工具
License: MIT
Requires Python: >=3.8
Keywords: deep learning, experiment tracking, pytorch, tensorflow, keras, mlflow, wandb

# SeeTrain

**SeeTrain** 是一个深度学习实验跟踪和框架集成工具，旨在提供统一的接口来适配各种深度学习框架，实现无缝的实验管理和多媒体数据记录。

> **注意**: 本包在 PyPI 上的名称为 `seetrain-ml`，安装时请使用 `pip install seetrain-ml`。

## ✨ 特性

- 📊 **统一实验跟踪**: 提供一致的 API 来记录指标、图像、音频、文本等多媒体数据。
- 🔄 **无缝集成**: 支持与 TensorBoard 和 Weights & Biases (Wandb) 的同步，无需大幅修改现有代码。
- �️ **多媒体支持**: 轻松记录和可视化图像、视频、音频和文本。
- �🚀 **简单易用**: 简洁的接口设计，快速上手。

## 📦 安装

使用 pip 安装：

```bash
pip install seetrain-ml
```

验证安装：

```python
import seetrain
print(f"SeeTrain version: {seetrain.__version__}")
```

## 🚀 快速开始

以下是一个完整的示例，展示了如何初始化实验并记录各种类型的数据：

```python
import time
import random
import seetrain

# 1. 初始化实验
seetrain.init(
    config={
        "learning_rate": 0.02,
        "architecture": "resnet56",
        "dataset": "cifar10",
        "epochs": 10
    }
)

# 2. 模拟训练过程
epochs = 10
for epoch in range(1, epochs + 1):
    # 模拟指标计算
    acc = 1 - 2 ** -epoch - random.random() / epoch
    loss = 2 ** -epoch + random.random() / epoch
    
    # 记录训练指标和多媒体数据
    seetrain.log({
        "train/acc": acc, 
        "train/loss": loss,
        "Preview/text": seetrain.Text(f"Epoch {epoch} finished"),
        # 示例：记录图像 (需替换为真实路径或数据)
        # "Preview/image": seetrain.Image("path/to/image.jpg")
    }, epoch=epoch)
    
    print(f"Epoch {epoch}: loss={loss:.4f}, acc={acc:.4f}")
    time.sleep(0.5)

# 3. 结束实验
seetrain.finish()
```

## 📖 使用指南

### 1. 初始化实验

在训练脚本开始时调用 `seetrain.init()`：

```python
seetrain.init(
    config={  # 实验配置参数 (可选)
        "learning_rate": 0.001,
        "batch_size": 32,
        "model": "ResNet50"
    }
)
```

### 2. 记录数据

使用 `seetrain.log()` 记录各种类型的数据。

#### 记录指标 (Metrics)

支持两种调用方式：

**方式一：字典方式 (推荐)**
通过字典一次性记录多个指标：
```python
seetrain.log({"loss": 0.5, "accuracy": 0.95}, step=100)
```

**方式二：键值对方式**
记录单个指标：
```python
seetrain.log("train/loss", 0.5, step=100)
```

> 💡 **提示**: 使用 `/` 可以对指标进行分组展示，例如 `train/loss`。

#### 记录多媒体 (Multimedia)

SeeTrain 支持记录多种媒体类型，建议使用分组（如 `Preview/image`）来组织数据：

```python
# 记录图像
seetrain.log({
    "Preview/image": seetrain.Image("path/to/image.jpg")
}, step=1)

# 记录视频
seetrain.log({
    "Preview/video": seetrain.Video("path/to/video.mp4")
}, step=1)

# 记录音频
seetrain.log({
    "Preview/audio": seetrain.Audio("path/to/audio.wav", sample_rate=44100, caption="测试音频")
}, step=1)

# 记录文本
seetrain.log({
    "Preview/text": seetrain.Text("这是一个测试文本")
}, step=1)
```

### 3. 第三方集成

SeeTrain 支持自动同步数据到 TensorBoard 和 Wandb，仅需极少的代码改动。

#### Weights & Biases (Wandb) 同步

```python
import seetrain
import wandb

# 开启 Wandb 同步
seetrain.sync_wandb()

# 正常初始化 Wandb
# wandb.init(project="my-project")
```

#### TensorBoard 同步

支持 `tensorboardX` 和 `torch.utils.tensorboard`。

```python
import seetrain

# 方式 A: 如果使用 tensorboardX
try:
    from tensorboardX import SummaryWriter
    seetrain.sync_tensorboardX()
except ImportError:
    pass

# 方式 B: 如果使用 PyTorch 的 tensorboard
try:
    from torch.utils.tensorboard import SummaryWriter
    seetrain.sync_tensorboard_torch()
except ImportError:
    pass

# 正常使用 SummaryWriter
# writer = SummaryWriter('runs/experiment')
```

## 📋 API 说明

### `seetrain.log` 参数详解

- **data**: (Union[Dict, str]) 指标数据字典 或 指标名称。
- **value**: (Any, optional) 指标值，仅在 `data` 是字符串（指标名称）时使用。
- **step**: (int, optional) 训练步数/全局步数。
- **epoch**: (int, optional) 训练轮数。
- **print_to_console**: (bool, optional) 是否将日志打印到控制台，默认为 True。