hugging-face-trackio

Trackio - ML 训练实验跟踪

Trackio 是一个用于记录和可视化 ML 训练指标的实验跟踪库。它会同步到 Hugging Face Spaces，以提供实时监控仪表板。

三种接口

任务	接口	参考文档
训练期间记录指标	Python API	references/logging_metrics.md
为训练诊断触发警报	Python API	references/alerts.md
训练结束后或期间获取指标和警报	CLI	references/retrieving_metrics.md

何时使用各接口

Python API → 记录日志

在训练脚本中使用 import trackio 来记录指标：

• 使用 trackio.init() 初始化跟踪
• 使用 trackio.log() 记录指标，或使用 TRL 的 report_to="trackio"
• 使用 trackio.finish() 完成跟踪

关键概念：对于远程／云端训练，请传入 space_id——指标会同步到 Space 仪表板，因此即使实例终止后也会保留。

→ 请参阅 references/logging_metrics.md，了解设置、TRL 集成和配置选项。

Python API → 警报

在训练代码中插入 trackio.alert() 调用，以标记重要事件——类似于插入 print 语句进行调试，但结构化且可查询：

• trackio.alert(title="...", level=trackio.AlertLevel.WARN) — 触发警报
• 三个严重性级别：INFO、WARN、ERROR
• 警报会打印到终端、存储在数据库中、显示在仪表板上，并可选择发送到 Webhook（Slack／Discord）

对大模型 Agent 的关键概念：警报是自主迭代实验的主要机制。Agent 应在训练代码中为诊断条件插入警报（损失突增、NaN 梯度、准确率低、训练停滞）。由于警报会打印到终端，监视训练脚本输出的 Agent 会自动看到它们。对于后台或分离运行，Agent 则可以通过 CLI 轮询。

→ 请参阅 references/alerts.md，了解完整的警报 API、Webhook 设置和自主 Agent 工作流。

CLI → 获取数据

使用 trackio 命令查询已记录的指标和警报：

• trackio list projects/runs/metrics — 查找可用内容
• trackio get project/run/metric — 获取摘要和值
• trackio list alerts --project <name> --json — 获取警报
• trackio show — 启动仪表板
• trackio sync — 同步到 HF Space

关键概念：添加 --json 可生成适合自动化和大模型 Agent 使用的程序化输出。

→ 请参阅 references/retrieving_metrics.md，了解所有命令、工作流和 JSON 输出格式。

最简日志记录设置

import trackio

trackio.init(project="my-project", space_id="username/trackio")
trackio.log({"loss": 0.1, "accuracy": 0.9})
trackio.log({"loss": 0.09, "accuracy": 0.91})
trackio.finish()

最简数据获取

trackio list projects --json
trackio get metric --project my-project --run my-run --metric loss --json

自主 ML 实验工作流

作为大模型 Agent 自主运行实验时，建议使用以下工作流：

1. 设置带警报的训练 — 为诊断条件插入 trackio.alert() 调用
2. 启动训练 — 在后台运行脚本
3. 轮询警报 — 使用 trackio list alerts --project <name> --json --since <timestamp> 检查新警报
4. 读取指标 — 使用 trackio get metric ... 检查特定值
5. 迭代 — 根据警报和指标，停止运行、调整超参数，然后启动新一轮运行

import trackio

trackio.init(project="my-project", config={"lr": 1e-4})

for step in range(num_steps):
    loss = train_step()
    trackio.log({"loss": loss, "step": step})

    if step > 100 and loss > 5.0:
        trackio.alert(
            title="Loss divergence",
            text=f"Loss {loss:.4f} still high after {step} steps",
            level=trackio.AlertLevel.ERROR,
        )
    if step > 0 and abs(loss) < 1e-8:
        trackio.alert(
            title="Vanishing loss",
            text="Loss near zero — possible gradient collapse",
            level=trackio.AlertLevel.WARN,
        )

trackio.finish()

然后从单独的终端／进程中轮询：

trackio list alerts --project my-project --json --since "2025-01-01T00:00:00"