---

source: "https://github.com/huggingface/skills/tree/main/skills/huggingface-trackio" name: hugging-face-trackio description: 使用 Trackio 通过 Python 日志记录、告警和 CLI 指标检索来追踪 ML 实验。 risk: unknown

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）

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

→ 参见 references/alerts.md 了解完整的告警 API、webhook 设置和自主代理工作流。

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 代理的程序化输出。

→ 参见 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 实验工作流

作为 LLM 代理自主运行实验时，推荐的工作流为：

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"

限制

• 仅在任务明确匹配上述范围时使用该技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请停下来要求澄清。