huggingface-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 仪表板，因此实例终止后数据仍会保留。自动创建的 Spaces 默认公开——如果指标不应公开，请传入 private=True。

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

Python API → 警报

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

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

面向 LLM Agent 的关键概念：警报是自主迭代实验的主要机制。Agent 应在训练代码中针对诊断条件插入警报（损失骤增、梯度为 NaN、准确率低、训练停滞）。由于警报会打印到终端，监视训练脚本输出的 Agent 会自动看到这些警报。对于后台运行或脱离终端的运行，Agent 可改用 CLI 轮询。

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

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，即可获得适用于自动化和 LLM Agent 的程序化输出。

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

最简日志设置

import trackio

# Spaces are PUBLIC by default (good for shareable dashboards);
# pass private=True if the metrics should not be public
trackio.init(project="my-project", space_id="username/trackio", private=True)
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 实验工作流

作为 LLM 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"