Hugging Face's logo

Trackio documentation

警报

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

警报

Trackio 警报允许你在运行期间标记重要事件。当警报触发时，它会：

  1. 带有颜色编码的严重性标签，打印到终端
  2. 存储在数据库中，以便之后通过 CLI、Python API 或 HTTP 端点进行查询
  3. 通过浮动警报面板和报告页面在仪表板中显示
  4. 发送至 Webhook（可选）—— 支持 Slack 和 Discord 的原生格式

触发警报

在调用 init() 之后，可以在任何位置使用 alert()：

import trackio

trackio.init(project="my-project")

# ... inside your training loop ...
if val_loss > 2.0:
    trackio.alert(
        title="Validation loss spike",
        text=f"val_loss={val_loss:.4f} exceeded threshold 2.0",
        level=trackio.AlertLevel.ERROR,
    )

参数

参数类型默认描述
titlestr（必需）警报的简短标题。
textstr \| NoneNone可选的更详细描述。
levelAlertLevelAlertLevel.WARN严重程度：INFO、WARN 或 ERROR。
webhook_urlstr \| NoneNone仅针对此警报覆盖全局 webhook URL。

告警级别

from trackio import AlertLevel

AlertLevel.INFO   # Informational — nothing is wrong
AlertLevel.WARN   # Warning — something may need attention
AlertLevel.ERROR  # Error — something is definitely wrong

终端输出

每条警报都会立即打印到终端，并带有颜色编码的标签：

[TRACKIO WARN] Validation loss spike: val_loss=2.3412 exceeded threshold 2.0 (step 42)
  • INFO 以蓝色显示
  • WARN 以黄色显示
  • ERROR 以红色显示

这意味着警报开箱即用，无需任何配置——只要您能看到训练日志，就能看到警报。

仪表板

Alerts 会在 Trackio 仪表板中的两个位置显示：

  1. 告警面板 — 位于每个仪表板页面右下角的浮动面板。它显示自仪表板启动以来收到的所有告警（跨所有项目），最新的告警显示在底部。您可以按严重程度级别进行筛选，并展开或折叠该面板。当有新告警到达时，面板会闪烁提示。

  2. 报告页面 — 报告页面在报告部分下方包含一个完整的警报表格。您可以通过侧边栏下拉菜单按运行筛选警报，并通过侧边栏复选框组按严重程度级别筛选。

要启动仪表板：

trackio show --project "my-project"

查询警报

CLI

# List all alerts for a project
trackio get alerts --project "my-project"

# Filter by run
trackio get alerts --project "my-project" --run "brave-sunset-0"

# Filter by level
trackio get alerts --project "my-project" --level error

# Only alerts after a specific timestamp (useful for polling)
trackio get alerts --project "my-project" --since "2025-06-01T00:00:00"

# JSON output for programmatic consumption
trackio get alerts --project "my-project" --json

检查告警周围的指标

当警报触发时，您通常希望查看该时刻所有指标的状态。使用 trackio get snapshot 可获取警报所在步骤或时间戳前后所有指标的数据：

# An alert fired at step 200 — get all metrics in a ±5 step window
trackio get snapshot --project "my-project" --run "brave-sunset-0" --around 200 --window 5 --json

# Or inspect a single metric around the alert's timestamp
trackio get metric --project "my-project" --run "brave-sunset-0" --metric "loss" --at-time "2025-06-01T12:05:30" --window 60 --json

有关完整的过滤选项列表，请参阅 CLI Commands 页面。

Python API

import trackio

api = trackio.Api()

# All alerts in a project
alerts = api.alerts("my-project")

# Filter by run and level
alerts = api.alerts("my-project", run="brave-sunset-0", level="error")

# Only new alerts since a timestamp
alerts = api.alerts("my-project", since="2025-06-01T12:00:00")

# From a Run object
runs = api.runs("my-project")
run_alerts = runs[0].alerts(level="warn")

HTTP API

如果 Trackio 仪表板正在运行（本地或 Space 上），您可以通过 /get_alerts 端点查询警报：

import httpx2

alerts = httpx2.post(
    "http://127.0.0.1:7860/api/get_alerts",
    json={
        "project": "my-project",
        "run": None,
        "level": "error",
        "since": "2025-06-01T00:00:00",
    },
).json()["data"]

Webhooks

Webhooks 允许您将警报推送到 Slack、Discord 或任何 HTTP 端点等外部服务。

设置全局 Webhook

您可以设置一个适用于运行中所有警报的 webhook URL：

选项 1：在 trackio.init() 中

trackio.init(
    project="my-project",
    webhook_url="https://hooks.slack.com/services/T.../B.../xxx",
)

选项 2：环境变量

export TRACKIO_WEBHOOK_URL="https://hooks.slack.com/services/T.../B.../xxx"
# No webhook_url needed — picks up the env var automatically
trackio.init(project="my-project")

当希望在不更改代码的情况下为所有项目使用相同的 webhook 时，使用环境变量会非常方便。

仅向 Webhooks 发送更高严重级别的警报

如果只想为重要警报设置 webhook，请在 trackio.init() 中设置 webhook_min_level：

trackio.init(
    project="my-project",
    webhook_url="https://hooks.slack.com/services/T.../B.../xxx",
    webhook_min_level=trackio.AlertLevel.WARN,
)

当 webhook_min_level=AlertLevel.WARN 时：

  • INFO 警报仍会打印/存储/在 UI 中显示，但不会发送到 webhook
  • WARN 和 ERROR 警报会发送到 webhook

您也可以通过环境变量全局配置此项：

export TRACKIO_WEBHOOK_MIN_LEVEL="warn"

按告警覆盖

将 webhook_url 直接传递给 trackio.alert()，即可为单个警报覆盖全局设置，或将特定警报发送到不同的频道：

trackio.alert(
    title="Checkpoint saved",
    text="Saved model at step 5000",
    level=trackio.AlertLevel.INFO,
    webhook_url="https://discord.com/api/webhooks/123456/abcdef",
)

Webhook 负载

Trackio 会根据 URL 自动检测服务，并相应地格式化负载。

通用 Webhook 接收 JSON POST 请求体：

{
    "level": "warn",
    "title": "Validation loss spike",
    "text": "val_loss=2.34 exceeded threshold 2.0",
    "project": "my-project",
    "run": "brave-sunset-0",
    "step": 42,
    "timestamp": "2025-06-15T14:30:00+00:00"
}

Slack 和 Discord 会收到富格式消息（参见下文各节）。

Webhooks 在后台线程中发送，因此 trackio.alert() 永远不会阻塞您的训练循环。

Slack

创建 Slack Webhook

  1. 前往 https://api.slack.com/apps，点击 Create New App → From scratch。
  2. 为应用命名（例如“Trackio Alerts”），并选择你的工作区。
  3. 在左侧边栏中，点击 Incoming Webhooks 并将其切换为 On。
  4. 点击 将新 Webhook 添加到工作区，选择要接收警报的频道，然后点击 允许。
  5. 复制 webhook URL。它看起来像这样： 
    https://hooks.slack.com/services/TXXXXX/BXXXXX/XXXXXXXXXX

与 Trackio 配合使用

trackio.init(
    project="my-project",
    webhook_url="https://hooks.slack.com/services/T.../B.../xxx",
)

trackio.alert(
    title="Training complete",
    text="Final val_accuracy: 0.94",
    level=trackio.AlertLevel.INFO,
)

它看起来是什么样的

Trackio 会发送包含以下内容的 Slack Block Kit 消息：

  • 带有表情符号和严重级别的醒目标题（例如，“⚠️ [WARN] Loss spike”）
  • 一个可选的描述部分，包含您的 text
  • 显示项目名称、运行名称和步骤编号的上下文页脚
image

Discord

创建 Discord Webhook

  1. 打开 服务器设置 → 集成 → Webhooks。
  2. 点击 新建 Webhook。
  3. 为其命名（例如“Trackio Alerts”），选择频道，然后单击 Copy Webhook URL。
  4. URL 格式如下： 
    https://discord.com/api/webhooks/123456789/ABCDEFghijklmnop

与 Trackio 配合使用

trackio.init(
    project="my-project",
    webhook_url="https://discord.com/api/webhooks/123456789/ABCDEFghijklmnop",
)

trackio.alert(
    title="GPU temperature critical",
    text="GPU 0 reached 95°C",
    level=trackio.AlertLevel.ERROR,
)

它看起来是什么样的

Trackio 会发送包含以下内容的 Discord Embed 消息：

  • 按颜色区分的侧边栏（蓝色表示 INFO，黄色表示 WARN，红色表示 ERROR）
  • 带有表情符号和严重级别的标题
  • 包含 text 的描述
  • 包含项目名称、运行名称和步骤编号的页脚
Update on GitHub

←API 和 MCP 服务器 ML Agents→