[](https://github.com/gradio-app/trackio/actions/workflows/test.yml)
[](https://pypi.org/project/trackio/)
[](https://pypi.org/project/trackio/)
[](https://twitter.com/trackioapp)
欢迎使用 `trackio`：一个由 Hugging Face 为人类和 AI agent 构建的轻量级、
免费的实验追踪库 🤗。
**既然已经有了其他的实验追踪库，为什么还要用 Trackio？** Trackio 具有一些使其对 agent 特别有用的特性：
* 它是本地优先的，因为你不需要为了记录数据去注册账号
* 日志存储在 SQLite 数据库中（并支持将日志“冻结”为 Parquet），这不仅让 Trackio 能够在并行实验中支持极高的吞吐量，而且
* 提供了易于使用的 CLI 接口来查询数据（包括直接对 SQL 数据进行查询），非常适合 LLM 驱动的分析。
因此，无论你是使用 agent 自主运行整个研究实验，还是仅仅使用 LLM 来分析数据，Trackio 都适合你。
对于人类用户，Trackio _还_ 提供了一个受 Gradio 启发设计的 dashboard，以便你可以查看指标、媒体、表格、警报等：
https://github.com/user-attachments/assets/2683cf27-7520-4fff-9ee9-bdc08a8ca404
### Trackio 的主要功能：
- **API 兼容** `wandb.init`、`wandb.log` 和 `wandb.finish`。可直接替换：只需
import trackio as wandb
并保留你现有的日志记录代码即可。
- **本地优先，云端可选** 设计：dashboard 默认在本地运行。但请注意，你也可以使用 `space_id` 将指标记录到 Hugging Face Space，这_同样_是免费的，并且非常适合协作实验。
- **对 LLM 友好**：考虑到自主 ML 实验而构建，Trackio 包含了一个用于编程访问的 CLI 和一个用于运行管理的 Python API，使得 LLM 能够轻松记录指标并查询实验数据。
- 当 `trackio list` 和 `trackio get` 不够用时，可以使用 `trackio query project --project
--sql "SELECT ..."` 进行只读 SQL 查询
- 请参阅 https://huggingface.co/docs/trackio/storage_schema 了解存储 schema 及直接查询参考
- **免费**：这里的一切，包括托管在 Hugging Face 上，都是免费的！
Trackio 的设计非常轻量且易于_fork_：后端和 API 使用 **Python**，dashboard 使用 **Svelte 5**，因此开发者可以 fork 该仓库并对任意一端进行扩展。
## 安装说明
Trackio 需要 [Python 3.10 或更高版本](https://www.python.org/downloads/)。使用 `pip` 安装：
```
pip install trackio
```
或使用 `uv`：
```
uv pip install trackio
```
## 用法
要开始使用，你可以运行一个简单的示例，该示例会记录一些模拟的训练指标：
```
import trackio
import random
import time
runs = 3
epochs = 8
for run in range(runs):
trackio.init(
project="my-project",
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()
```
运行上述代码后，终端会打印出启动 dashboard 的说明。
`trackio` 的用法在大多数情况下被设计为与 `wandb` 完全相同，因此你可以轻松地在两个库之间切换。
```
import trackio as wandb
```
## 仪表盘
你可以通过在终端中运行以下命令来启动 dashboard：
```
trackio show
```
或者在 Python 中：
```
import trackio
trackio.show()
```
你也可以提供一个可选的 `project` 名称作为参数，以直接加载特定的项目：
```
trackio show --project "my-project"
```
或者在 Python 中：
```
import trackio
trackio.show(project="my-project")
```
你还可以让 Trackio 指向自定义的静态前端目录：
```
trackio show --frontend ./my-trackio-frontend
```
```
import trackio
trackio.show(frontend_dir="./my-trackio-frontend")
```
该目录只需要包含一个 `index.html` 文件。Trackio 会继续在 `/api/*` 下提供相同的后端 API，因此你无需 fork 后端即可替换 UI。如果目录缺失或无效，Trackio 将回退到最小化的启动模板。
要使自定义前端默认在所有地方生效：
```
trackio config set frontend ./my-trackio-frontend
```
使用以下命令重置：
```
trackio config unset frontend
```
## 部署到 Hugging Face Spaces
在调用 `trackio.init()` 时，默认情况下服务将在本地运行，并将项目数据存储在本地计算机上。
但如果你在 `init` 中传入 `space_id`，例如：
```
trackio.init(project="my-project", space_id="orgname/space_id")
```
或
```
trackio.init(project="my-project", space_id="username/space_id")
```
它将根据需要使用现有的或自动部署一个新的 Hugging Face Space。你需要在本地使用 `huggingface-cli` 登录，并且你的 token 需要具有创建 Space 的写入权限。
## 自托管 Trackio 服务器
你可以在自己的机器或基础设施上运行 Trackio dashboard 和 API，并通过 HTTP 将训练任务指向它。从 `trackio.show()` 传入包含写入权限的 URL（可能在查询中包含 `write_token`），或者传入一个基础 URL 加上 `TRACKIO_WRITE_TOKEN` 环境变量。客户端会在请求时发送该 token；它不是你的 Hugging Face token。
```
trackio.init(project="my-project", server_url="http://127.0.0.1:7860?write_token=YOUR_TOKEN")
```
你也可以设置 `TRACKIO_SERVER_URL`（如果 URL 没有查询字符串，则可选择设置 `TRACKIO_WRITE_TOKEN`）。如果同时设置了 `space_id` / `TRACKIO_SPACE_ID` 和 `server_url` / `TRACKIO_SERVER_URL`，Trackio 将使用 Hugging Face Space 并忽略自托管 URL。
请参阅文档：[自托管服务器](https://huggingface.co/docs/trackio/self_hosted_server)。
## 将离线项目同步到 Spaces
如果你一直在本地追踪实验，并希望将它们移动到 Hugging Face Spaces 进行共享或协作，请使用 `sync` 功能：
```
import trackio
trackio.sync(
project="my-project",
space_id="username/space_id",
frontend_dir="./my-trackio-frontend",
)
```
这会将你本地的项目数据库上传到一个新的或现有的 Space 中。该 Space 将显示你所有记录的实验和指标，如果配置或显式传入了自定义前端，它也将被部署到那里。
静态的 Trackio Spaces（`sdk="static"`）是仅限浏览器的只读快照，因此其快照数据必须是公开的。对于私有的 dashboard，请使用默认的 Gradio Space；`sdk="static"` 不支持 `private=True`。
**示例工作流：**
```
import trackio
# 本地开始追踪
trackio.init(project="my-project", config={"lr": 0.001})
trackio.log({"loss": 0.5})
trackio.finish()
# 稍后，同步到 Spaces
trackio.sync(
project="my-project",
space_id="username/my-experiments",
frontend_dir="./my-trackio-frontend",
)
```
## 嵌入 Trackio Dashboard
我们创建 `trackio` 的原因之一是为了能够轻松地将实时 dashboard 嵌入到网站、博客文章或任何其他可以嵌入网页的地方。
如果你将 Trackio dashboard 托管在 Spaces 上，你可以将该 Space 的 URL 作为 IFrame 嵌入。你甚至可以使用查询参数来仅显示特定的项目和/或指标，例如
```