Trackio documentation

Оповещения

Trackio

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Оповещения

Уведомления Trackio позволяют отмечать важные события во время выполнения. Когда срабатывает уведомление, оно:

Выводится в терминал с цветовой меткой уровня серьёзности
Хранится в базе данных, чтобы к нему можно было обращаться позже через CLI, Python API или HTTP-эндпоинт
Отображается на панели управления через всплывающее окно уведомлений и страницу Reports
Отправлено в вебхук (необязательно) — с нативным форматированием для Slack и Discord

Срабатывание оповещения

Используйте alert() в любом месте после вызова init():

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,
    )

Параметры

Параметр	Тип	По умолчанию	Описание
`title`	`str`	(обязательный)	Короткое название для уведомления.
`text`	`str \\| None`	`None`	Необязательное более подробное описание с деталями.
`level`	`AlertLevel`	`AlertLevel.WARN`	Важность: `INFO`, `WARN` или `ERROR`.
`webhook_url`	`str \\| None`	`None`	Переопределите глобальный 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 выводится красным цветом

Это означает, что оповещения работают «из коробки» без какой-либо настройки — если вы видите логи обучения, вы видите и оповещения.

Панель управления

Уведомления отображаются в двух местах в панели Trackio:

Панель уведомлений — плавающая панель в правом нижнем углу каждой страницы панели управления. Она отображает все уведомления (по всем проектам), поступившие с момента запуска панели управления, при этом самое свежее уведомление находится внизу. Можно фильтровать по уровню серьёзности и разворачивать/сворачивать панель. Панель мигает при поступлении новых уведомлений.
Страница отчётов — На странице отчётов под разделом отчётов находится полная таблица оповещений. Вы можете фильтровать оповещения по запуску (через выпадающий список в боковой панели) и по уровню серьёзности (через группу флажков в боковой панели).

Для запуска панели управления:

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 позволяют отправлять уведомления во внешние сервисы, такие как Slack, Discord или любой HTTP-эндпоинт.

Настройка глобального вебхука

Вы можете задать 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_min_level в trackio.init():

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 предупреждения по-прежнему выводятся/хранятся/отображаются в интерфейсе, но не отправляются в 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 и формирует payload соответствующим образом.

Универсальные вебхуки получают тело запроса POST в формате JSON:

{
    "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

Перейдите на https://api.slack.com/apps и нажмите Create New App → From scratch.
Придумайте название для приложения (например, «Trackio Alerts») и выберите рабочее пространство.
В левой боковой панели нажмите Incoming Webhooks и переключите его в положение On.
Нажмите Добавить новый вебхук в рабочее пространство, выберите канал, в который вы хотите получать уведомления, и нажмите Разрешить.
Скопируйте 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
Контекстная нижняя панель с названием проекта, названием запуска и номером шага

Discord

Создание вебхука Discord

Откройте Настройки сервера → Интеграции → Вебхуки.
Нажмите Новый Webhook.
Придумайте название (например, «Trackio Alerts»), выберите канал и нажмите Copy Webhook URL.

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→