Hugging Face 发布开源免费实验跟踪库 Trackio

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 还会将 Sqlite 数据库转换为 Parquet 数据集，并每 5 分钟备份到 Hugging Face Dataset。这意味着你可以随时轻松地在 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()

无需额外设置——只需接入即可开始跟踪。

设计原则

• API 与流行的实验跟踪库兼容，使迁移到 Trackio 和从 Trackio 迁移都无缝衔接。
• 本地优先：日志和仪表板默认在本地运行和持久化，并可选择托管在 Hugging Face Spaces 上。
• 轻量且可扩展：核心代码库不到 1,000 行 Python 代码，易于理解和修改。
• 免费且开源：所有功能，包括在 Hugging Face 上托管，都是免费的。
• 构建在 🤗 Datasets 和 Spaces 之上，以实现稳健的数据处理和可视化。

后续步骤

Trackio 有意保持轻量，目前处于测试阶段。其他跟踪工具中的某些功能，例如制品管理或复杂可视化，目前尚不可用。如果你希望拥有这些功能，请在此处创建 issue：https://github.com/gradio-app/trackio/issues

鉴于 Trackio 轻量且开源的特性，我们很乐意与机器学习社区合作，设计一个适合我们所有人的实验跟踪产品！