介绍 Trackio：来自 Hugging Face 的轻量级实验跟踪库

发布于 2025 年 7 月 29 日

在 GitHub 上更新

144

长话短说 (TL;DR)：Trackio 是一个全新的、开源免费的实验跟踪 Python 库，它提供了一个本地仪表板，并与 Hugging Face Spaces 无缝集成，方便共享和协作。由于 trackio 是 wandb 的直接替代品，你可以使用你已经熟悉的语法开始！

背景

如果你训练过自己的机器学习模型，就会知道在训练期间跟踪指标、参数和超参数，并在之后将它们可视化以更好地理解训练过程是多么重要。

大多数机器学习研究人员使用特定的实验跟踪库来完成这项工作。然而，这些库可能需要付费、设置复杂，或者缺乏快速实验和共享所需的灵活性。

我们为什么转向 Trackio

在 Hugging Face，我们的科研团队已经开始在我们的研究项目中使用 Trackio，并且我们发现它比其他跟踪解决方案有几个关键优势：

易于共享和嵌入：Trackio 使得与同事分享训练进度或使用 iframe 将图表直接嵌入博客文章和文档中变得异常简单。当你想展示特定的训练曲线或指标，而不需要其他人注册账户或浏览复杂的仪表板时，这一点尤其有价值。

标准化和透明度：像 GPU 能耗这样的指标对于跟踪并与社区共享非常重要，这样我们就能更好地了解模型训练的能源需求和环境影响。使用 Trackio，它可以直接从 nvidia-smi 命令获取信息，这使得量化和比较能耗以及将其添加到模型卡片中变得容易。

数据可访问性：与某些将数据锁定在专有 API 后的跟踪工具不同，Trackio 使得提取和分析记录的数据变得非常直接。这对于需要执行自定义分析或将训练指标集成到其研究工作流程中的研究人员至关重要。

实验的灵活性：Trackio 的轻量级设计使我们能够在训练过程中轻松实验新的跟踪功能。例如，我们可以在记录张量时决定何时将张量从 GPU 移动到 CPU，这在需要跟踪模型/中间状态而不影响性能时，显著提高了训练吞吐量。

使用 Trackio

那么，Trackio 是什么，以及如何使用它呢？Trackio 是一个开源 Python 库，它能让你跟踪任何指标，并使用本地的 Gradio 仪表板将其可视化。你还可以将这个仪表板同步到 Hugging Face Spaces，这意味着你可以通过分享一个 URL 轻松地与其他用户共享仪表板。由于 Spaces 可以是私有的或公共的，这意味着你可以公开共享仪表板，或者仅在你的 Hugging Face 组织成员内部共享。

安装

你可以使用 pip 安装 trackio

pip install trackio

或者，如果你更喜欢使用 uv

uv pip install trackio

用法

trackio 被设计为像 wandb 这样的实验跟踪库的直接替代品。其 API 与 wandb.init、wandb.log 和 wandb.finish 兼容，因此你可以在代码中简单地将 trackio 导入为 wandb。

- import wandb
+ import trackio as wandb

这里是一个例子

import trackio
import random
import time

runs = 3
epochs = 8

def simulate_multiple_runs():
    for run in range(runs):
        trackio.init(project="fake-training", config={
            "epochs": epochs,
            "learning_rate": 0.001,
            "batch_size": 64
        })
        for epoch in range(epochs):
            train_loss = random.uniform(0.2, 1.0)
            train_acc = random.uniform(0.6, 0.95)
            val_loss = train_loss - random.uniform(0.01, 0.1)
            val_acc = train_acc + random.uniform(0.01, 0.05)
            trackio.log({
                "epoch": epoch,
                "train_loss": train_loss,
                "train_accuracy": train_acc,
                "val_loss": val_loss,
                "val_accuracy": val_acc
            })
            time.sleep(0.2)
        trackio.finish()

simulate_multiple_runs()

可视化结果

记录完实验后，你可以启动仪表板来可视化你的结果。在终端中运行以下命令：

trackio show

或者，从 Python 启动它

import trackio
trackio.show()

你也可以指定一个项目名称

trackio show --project "my project"

或在 Python 中

trackio.show(project="my project")

通过 🤗 Spaces 共享

要将你的本地仪表板同步到 Hugging Face Spaces，只需向 init 传递一个 space_id

trackio.init(project="fake-training", space_id="org_name/space_name")

如果你在 Spaces 上托管你的仪表板，你可以简单地分享 URL 或使用 iframe 将其嵌入任何地方

<iframe src="https://org_name-space_name.hf.space/?project=fake-training&metrics=train_loss,train_accuracy&sidebar=hidden" width=600 height=600 frameBorder="0"></iframe>

由于 Spaces 可以是私有的或公共的，这意味着你可以公开分享仪表板，或者仅在你的 Hugging Face 组织成员内部共享——这一切都是免费的！

当你将 Trackio 仪表板同步到 Hugging Face Spaces 时，数据会记录到 Spaces 上的一个临时 Sqlite 数据库中。因为如果你的 Space 重启，这个数据库会被重置，所以 Trackio 还会每 5 分钟将 Sqlite 数据库转换为 Parquet 数据集，并将其备份到 Hugging Face 数据集。这意味着你可以随时轻松地在 Hugging Face 数据集中可视化你记录的指标。

提示：你可以通过向 `trackio.init()` 传递 `dataset_id` 来设置这个数据集的名称。

与 🤗 Transformers 和 🤗 Accelerate 集成

Trackio 与 transformers 和 accelerate 等 Hugging Face 库原生集成，因此你只需最少的设置即可记录指标。

使用 transformers.Trainer

import numpy as np
from datasets import Dataset
from transformers import Trainer, AutoModelForCausalLM, TrainingArguments

# Create a fake dataset
data = np.random.randint(0, 1000, (8192, 64)).tolist()
dataset = Dataset.from_dict({"input_ids": data, "labels": data})

# Train a model using the Trainer API
trainer = Trainer(
    model=AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-0.6B"),
    args=TrainingArguments(run_name="fake-training", report_to="trackio"),
    train_dataset=dataset,
)
trainer.train()

使用 accelerate

from accelerate import Accelerator

accelerator = Accelerator(log_with="trackio")
accelerator.init_trackers("fake-training")

...  # Prepare the model, dataloader, etc.

for step, batch in enumerate(dataloader):
    ...  # Your training logic here
    accelerator.log({"training_loss": loss}, step=step)

accelerator.end_training()