Hugging Face's logo

Trackio documentation

Cảnh báo

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Cảnh báo

Cảnh báo Trackio cho phép bạn đánh dấu các sự kiện quan trọng trong một lần chạy. Khi một cảnh báo được kích hoạt, nó sẽ:

  1. Được in ra terminal kèm nhãn mức độ nghiêm trọng có mã màu
  2. Được lưu trong cơ sở dữ liệu để có thể truy vấn sau đó qua CLI, API Python hoặc điểm cuối HTTP
  3. Hiển thị trên bảng điều khiển thông qua một bảng thông báo nổi và trang Báo cáo
  4. Gửi đến webhook (tùy chọn) — với định dạng gốc cho Slack và Discord

Kích hoạt Cảnh báo

Sử dụng alert() ở bất kỳ đâu sau khi gọi 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,
    )

Tham số

Tham sốLoạiMặc địnhMô tả
titlestr(bắt buộc)Tiêu đề ngắn cho cảnh báo.
textstr \| NoneNoneMô tả dài hơn tùy chọn với các chi tiết.
levelAlertLevelAlertLevel.WARNMức độ nghiêm trọng: INFO, WARN hoặc ERROR.
webhook_urlstr \| NoneNoneGhi đè URL webhook toàn cục chỉ cho cảnh báo này.

Mức độ cảnh báo

from trackio import AlertLevel

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

Đầu ra của Terminal

Mọi cảnh báo đều được in ra terminal ngay lập tức, kèm theo nhãn có mã màu:

[TRACKIO WARN] Validation loss spike: val_loss=2.3412 exceeded threshold 2.0 (step 42)
  • INFO được in bằng màu xanh lam
  • WARN được in màu vàng
  • ERROR được in màu đỏ

Điều này có nghĩa là các cảnh báo hoạt động ngay lập tức mà không cần thiết lập — nếu bạn có thể xem nhật ký huấn luyện của mình, bạn cũng có thể xem các cảnh báo.

Bảng điều khiển

Các cảnh báo xuất hiện ở hai vị trí trong bảng điều khiển Trackio:

  1. Bảng thông báo — Một bảng nổi ở góc dưới bên phải của mọi trang bảng điều khiển. Nó hiển thị tất cả các thông báo (trên tất cả các dự án) đã đến kể từ khi bảng điều khiển được khởi chạy, với thông báo mới nhất ở cuối. Bạn có thể lọc theo mức độ nghiêm trọng và mở rộng/thu gọn bảng. Bảng sẽ nhấp nháy khi có thông báo mới đến.

  2. Trang Báo cáo — Trang Báo cáo bao gồm bảng cảnh báo đầy đủ bên dưới phần báo cáo. Bạn có thể lọc cảnh báo theo lần chạy (thông qua menu thả xuống ở thanh bên) và theo mức độ nghiêm trọng (thông qua nhóm hộp kiểm ở thanh bên).

Để khởi chạy bảng điều khiển:

trackio show --project "my-project"

Truy vấn Cảnh báo

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

Kiểm tra các chỉ số xung quanh một cảnh báo

Khi một cảnh báo được kích hoạt, bạn thường muốn xem toàn bộ các chỉ số trông như thế nào tại thời điểm đó. Sử dụng trackio get snapshot để lấy mọi chỉ số tại hoặc quanh bước hoặc mốc thời gian của cảnh báo:

# 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

Xem trang Lệnh CLI để biết danh sách đầy đủ các tùy chọn lọc.

API Python

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

Nếu bảng điều khiển Trackio đang chạy (trên máy cục bộ hoặc trên một Space), bạn có thể truy vấn cảnh báo qua endpoint /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 cho phép bạn đẩy cảnh báo đến các dịch vụ bên ngoài như Slack, Discord hoặc bất kỳ điểm cuối HTTP nào.

Đặt Webhook Toàn cục

Bạn có thể đặt một URL webhook áp dụng cho mọi cảnh báo trong một lần chạy:

Tùy chọn 1: Trong trackio.init()

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

Tùy chọn 2: Biến môi trường

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

Biến môi trường tiện lợi khi bạn muốn dùng cùng một webhook cho tất cả các dự án mà không cần thay đổi mã.

Gửi Chỉ Các Cảnh Báo Nghiêm Trọng Hơn Đến Webhooks

Nếu bạn chỉ muốn webhook cho các cảnh báo quan trọng, hãy đặt webhook_min_level trong trackio.init():

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

Với webhook_min_level=AlertLevel.WARN:

  • Các cảnh báo INFO vẫn được in/lưu/hiển thị trong giao diện người dùng, nhưng không được gửi đến webhook
  • Các cảnh báo WARN và ERROR được gửi đến webhook

Bạn cũng có thể cấu hình điều này trên toàn cục bằng một biến môi trường:

export TRACKIO_WEBHOOK_MIN_LEVEL="warn"

Ghi đè cho từng cảnh báo

Truyền webhook_url trực tiếp vào trackio.alert() để ghi đè cài đặt toàn cục cho một cảnh báo duy nhất, hoặc để gửi một cảnh báo cụ thể đến một kênh khác:

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 Payload

Trackio tự động phát hiện dịch vụ từ URL và định dạng payload tương ứng.

Webhook chung nhận thân bài POST dạng 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 và Discord nhận các tin nhắn định dạng phong phú (xem các mục bên dưới).

Webhooks được gửi trong một luồng nền nên trackio.alert() không bao giờ chặn vòng lặp huấn luyện của bạn.

Slack

Tạo Webhook Slack

  1. Truy cập https://api.slack.com/apps và nhấp vào Create New App → From scratch.
  2. Đặt tên cho ứng dụng (ví dụ: “Trackio Alerts”) và chọn workspace của bạn.
  3. Trong thanh bên trái, nhấp vào Incoming Webhooks và bật On.
  4. Nhấp vào Thêm Webhook mới vào Workspace, chọn kênh bạn muốn nhận cảnh báo, sau đó nhấp vào Cho phép.
  5. Sao chép URL webhook. Nó có dạng: 
    https://hooks.slack.com/services/TXXXXX/BXXXXX/XXXXXXXXXX

Sử dụng với 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,
)

Nó trông như thế nào

Trackio gửi các thông báo Block Kit của Slack với:

  • Tiêu đề nổi bật với emoji và mức độ nghiêm trọng (ví dụ: “⚠️ [WARN] Loss spike“)
  • Một phần mô tả tùy chọn với text của bạn
  • Chân trang ngữ cảnh hiển thị tên dự án, tên chạy và số bước
image

Discord

Tạo Webhook Discord

  1. Mở Cài đặt máy chủ → Tích hợp → Webhooks.
  2. Nhấp vào Webhook mới.
  3. Đặt tên cho nó (ví dụ: “Trackio Alerts”), chọn kênh và nhấp vào Copy Webhook URL.
  4. URL có dạng: 
    https://discord.com/api/webhooks/123456789/ABCDEFghijklmnop

Sử dụng với 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,
)

Nó trông như thế nào

Trackio gửi các tin nhắn Embed Discord với:

  • Thanh bên có mã màu (xanh dương cho INFO, vàng cho WARN, đỏ cho ERROR)
  • Tiêu đề có emoji và mức độ nghiêm trọng
  • Mô tả với text của bạn
  • Phân trang chân trang với tên dự án, tên chạy và số bước
Update on GitHub

←API và MCP Server ML Agents→