Lệnh CLI

Trackio cung cấp một bộ lệnh CLI toàn diện, cho phép bạn truy vấn thông tin về dự án, run, metric và Space mà không cần khởi động server MCP. Các lệnh hoạt động trên dữ liệu cục bộ theo mặc định, hoặc trên một HF Space từ xa khi có --space. Điều này đặc biệt hữu ích cho các LLM agent và script tự động hóa. Với đầu ra JSON có cấu trúc và khả năng truy cập dữ liệu thử nghiệm một cách lập trình, Trackio được thiết kế để hỗ trợ các thử nghiệm ML tự chủ do LLM thực hiện.

Truy vấn các Space từ xa

Tất cả các lệnh list, get và query đọc dữ liệu dashboard đều hỗ trợ truy vấn một Hugging Face Space từ xa thay vì dữ liệu cục bộ. Truyền cờ --space kèm theo ID Space hoặc URL đầy đủ:

# Using a Space ID
trackio list projects --space username/my-space

# Using a Space URL
trackio list projects --space https://huggingface.co/proxy/username-my-space.hf.space

# Works with any list/get/query command
trackio get metric --project "my-project" --run "my-run" --metric "loss" --space username/my-space

Đối với Spaces riêng, hãy truyền --hf-token hoặc đảm bảo bạn đã đăng nhập qua huggingface-cli login:

trackio list projects --space username/private-space --hf-token hf_xxxxx

Lưu ý: Các lệnh show, status, sync, freeze, skills, registry và list spaces không hỗ trợ --space. Hãy sử dụng trackio list spaces để khám phá các bảng điều khiển Trackio trên Hugging Face Hub, sau đó truyền một trong những ID Space đó vào các lệnh như trackio list projects --space username/my-space.

Lệnh Registry

Tạo một registry và, khi hữu ích, định nghĩa một bộ sưu tập có kiểu trước khi liên kết vào đó:

trackio registry create models --description "Models we deploy"
trackio registry create-collection models/churn-model --type model --description "Churn predictor"

Liên kết một phiên bản artifact cục bộ, nâng cấp một phiên bản collection bằng cách di chuyển một alias, hoặc hủy liên kết một phiên bản:

trackio registry link models/churn-model experiments/resnet:v3 --alias staging
trackio registry promote models/churn-model production v0
trackio registry unlink models/churn-model v0

Kiểm tra các bộ sưu tập và lịch sử kiểm toán của chúng:

trackio registry list models
trackio registry show models/churn-model
trackio registry events models

Tất cả các lệnh registry đều chấp nhận --bucket-id org/bucket cho registry dựa trên bucket và --json cho đầu ra có cấu trúc. --alias có thể lặp lại. Mục tiêu có thể được viết dưới dạng models/churn-model hoặc registry-models/churn-model.

Lệnh link phân giải project/artifact:version-or-alias từ dữ liệu Trackio cục bộ; bỏ qua phần hậu tố để phân giải latest. Việc phát hành một artifact chỉ tồn tại trên một Space từ xa vẫn sử dụng API Python để Trackio có thể ghi lại tọa độ lưu trữ từ xa của nguồn.

Lệnh Đồng bộ

Tải một dự án cục bộ lên một Hugging Face Space:

trackio sync --project "my-project" --space-id "username/space_id"

Triển khai dưới dạng Space tĩnh (đọc từ một HF Bucket, không cần máy chủ):

trackio sync --project "my-project" --space-id "username/space_id" --sdk static

Static Spaces phục vụ dữ liệu trực tiếp từ trình duyệt và do đó yêu cầu dữ liệu snapshot công khai. --sdk static --private không được hỗ trợ; hãy sử dụng Gradio SDK mặc định cho các bảng điều khiển riêng tư.

Đồng bộ tất cả các dự án có dữ liệu chưa được đồng bộ đến các Spaces được cấu hình của chúng:

trackio sync --all

Lệnh Freeze

Tạo một bản sao tĩnh chỉ đọc từ một Space Gradio đang hoạt động:

trackio freeze --space-id "username/my-space" --project "my-project"

Chỉ định Space đích tùy chỉnh:

trackio freeze --space-id "username/my-space" --project "my-project" --new-space-id "username/my-snapshot"

Lưu ý: Nguồn phải là một Gradio Space có bucket được gắn tại /data. Nếu Space đích đã tồn tại và không phải là Trackio static Space, freeze sẽ từ chối ghi đè lên nó. Space đã đóng băng là một bản chụp. Các chỉ số đồng bộ về sau đến Gradio Space gốc sẽ không xuất hiện trong static Space đã đóng băng trừ khi bạn chạy lại freeze. Các bản chụp đóng băng tĩnh yêu cầu dữ liệu đích phải công khai, do đó trackio freeze --private không được hỗ trợ.

Bump

Nâng cấp một Space Trackio hiện có lên phiên bản Trackio được cài đặt cục bộ:

trackio bump username/my-space

trackio bump --space username/my-space thực hiện cùng một tác vụ.

Space sẽ tạm dừng trong khi nâng cấp, do đó các tác vụ huấn luyện vẫn tiếp tục ghi log vào hộp thư bucket của Space. Cơ sở dữ liệu của nó được sao lưu vào trackio-backups/ trong cùng bucket, pin Trackio được cập nhật, và Space khởi động lại để phiên bản mới thực hiện việc di chuyển dữ liệu. Nếu Space sau nâng cấp không khởi động được hoặc báo cáo ít dòng hơn trước, bản sao lưu và các tệp Space trước đó sẽ được khôi phục.

Để giữ nguyên Space gốc, hãy sao chép nó cùng bucket của nó vào một Space mới chạy phiên bản local thay thế:

trackio bump username/my-space --new-space username/my-space-v2 --new-bucket username/my-space-v2-bucket

Lưu ý: bump hỗ trợ các Gradio Spaces chạy Trackio 0.21.0 trở lên với một bucket được gắn tại /data, và không bao giờ hạ cấp một Space. Các Space cũ lưu trữ dữ liệu của chúng trong một Hugging Face Dataset thay vì một bucket.

Lệnh Liệt kê

Liệt kê tất cả các dự án

Liệt kê tất cả các dự án khả dụng:

trackio list projects

Đầu ra ở định dạng JSON:

trackio list projects --json

Danh sách không gian Trackio

Danh sách các Spaces trên bảng điều khiển Trackio do tài khoản và các tổ chức Hugging Face của bạn sở hữu:

trackio list spaces

Đầu ra ở định dạng JSON:

trackio list spaces --json

Liệt kê các Trackio Spaces dưới một namespace người dùng hoặc tổ chức cụ thể:

trackio list spaces --author "username-or-org"

Hạn chế số lượng Spaces được trả về:

trackio list spaces --limit 10

Đối với Spaces riêng, hãy truyền --hf-token hoặc đảm bảo bạn đã đăng nhập qua huggingface-cli login.

Liệt kê các lần chạy cho một Dự án

Liệt kê tất cả các lần chạy trong một dự án cụ thể:

trackio list runs --project "my-project"

Đầu ra ở định dạng JSON:

trackio list runs --project "my-project" --json

Liệt kê các chỉ số cho một lần chạy

Liệt kê tất cả các chỉ số được theo dõi trong một lần chạy cụ thể:

trackio list metrics --project "my-project" --run "my-run"

Đầu ra ở định dạng JSON:

trackio list metrics --project "my-project" --run "my-run" --json

Liệt kê các chỉ số hệ thống cho một lần chạy

Liệt kê tất cả các chỉ số hệ thống (ví dụ: chỉ số GPU) cho một lần chạy cụ thể:

trackio list system-metrics --project "my-project" --run "my-run"

Đầu ra ở định dạng JSON:

trackio list system-metrics --project "my-project" --run "my-run" --json

Danh sách báo cáo

Liệt kê các báo cáo markdown trong một dự án (trên tất cả các lần chạy):

trackio list reports --project "my-project"

Liệt kê các báo cáo markdown cho một lần chạy cụ thể:

trackio list reports --project "my-project" --run "my-run"

Đầu ra ở định dạng JSON:

trackio list reports --project "my-project" --run "my-run" --json

Danh sách Traces

Liệt kê traces (phiên agent hoặc hội thoại) trên tất cả các lần chạy trong một dự án:

trackio list traces --project "my-project"

Mỗi hàng hiển thị trạng thái của trace, độ trễ theo thời gian thực, chi phí, số lượng thao tác và yêu cầu của người dùng đã khởi tạo nó. Lọc theo run, step hoặc văn bản:

trackio list traces --project "my-project" --run "production"
trackio list traces --project "my-project" --step 12
trackio list traces --project "my-project" --search "rate limit"

Tìm kiếm khớp với nội dung thông báo, metadata của trace, và tên, loại, model, trạng thái, và lỗi của mỗi span. Kiểm soát thứ tự và phân trang:

trackio list traces --project "my-project" --sort step_desc --limit 100 --offset 50

--sort chấp nhận request_time_desc (mặc định), request_time_asc, step_asc, và step_desc. Thêm --json sẽ bao gồm một bản tổng hợp summary cho mỗi trace.

Lệnh

Lấy Trace

Hiển thị một trace cùng với cây thực thi đầy đủ của nó:

trackio get trace --project "my-project" --trace-id "fe04ed264a8a4bd6afcf266b56d9297e"

Trace fe04ed264a8a4bd6afcf266b56d9297e
  Run:      production
  Totals:   error | 25.0s | $0.33 | 101338 in / 1804 out tokens | 21 operation(s)

Execution:
  answer-research-question [span]  25.0s
    generate-research-response [span]  23.7s
      acquire-sandbox [span]  914ms
      dispatch-model-request [span]  2.18s
        provider-request [generation]  2.18s  my-model  8347->239 tok  $0.03
      ERROR run-bash-command [tool]  168ms
        -> {"exit_code": 2, "stderr": "hf datasets list: error: unrecognized arguments: --full"}

--trace-id nhận id ngắn được in ra bởi trackio list traces hoặc id đầy đủ đã được lưu. Thêm --json để xem trace hoàn chỉnh, bao gồm đầu vào và đầu ra của span.

Lấy Tóm tắt Trace

Gom mọi span theo tên thao tác để xem độ trễ, token và chi phí nằm ở đâu, và thao tác nào bị lỗi:

trackio get trace-summary --project "my-project"

operation                  | kind       | calls | errors | avg_ms  | max_ms  | input_tokens | output_tokens | cost_usd
provider-request           | generation | 205   | 0      | 3380.8  | 5535.0  | 2915829      | 63020         | 9.6928
run-bash-command           | tool       | 157   | 25     | 818.4   | 1548.0  | 0            | 0             | 0.0
acquire-sandbox            | span       | 48    | 0      | 2438.6  | 10615.0 | 0            | 0             | 0.0

Hạn chế với một lần chạy bằng --run, hoặc xuất các dòng có thể đọc được bằng máy bằng --json. Đối với bất kỳ điều gì mà rollup không bao phủ, hãy truy vấn trực tiếp bảng traces bằng trackio query project — spans là một cột JSON, vì vậy json_each hoạt động.

Lấy Tóm tắt Dự án

Lấy bản tóm tắt chi tiết của một dự án, bao gồm số lượng lần chạy và hoạt động gần đây:

trackio get project --project "my-project"

Đầu ra ở định dạng JSON:

trackio get project --project "my-project" --json

Tóm tắt bao gồm:

• Tên dự án
• Số lần chạy
• Danh sách tất cả các lần chạy
• Hoạt động gần nhất (bước tối đa trên tất cả các lần chạy)

Lấy Tóm tắt Chạy

Lấy bản tóm tắt chi tiết của một lần chạy cụ thể, bao gồm các chỉ số và cấu hình:

trackio get run --project "my-project" --run "my-run"

Đầu ra ở định dạng JSON:

trackio get run --project "my-project" --run "my-run" --json

Tóm tắt bao gồm:

• Tên dự án và tên chạy
• Số lượng mục nhật ký
• Bước cuối cùng
• Danh sách tất cả các chỉ số
• Cấu hình chạy (không bao gồm các trường nội bộ)

Lấy Giá Trị Chỉ Số

Lấy tất cả các giá trị cho một chỉ số cụ thể trong một lần chạy:

trackio get metric --project "my-project" --run "my-run" --metric "loss"

Đầu ra ở định dạng JSON:

trackio get metric --project "my-project" --run "my-run" --metric "loss" --json

Đầu ra bao gồm:

• Số bước
• Thời gian
• Giá trị chỉ số

Lọc theo Bước hoặc Thời gian

Bạn có thể lọc các giá trị chỉ số theo một bước cụ thể hoặc một cửa sổ quanh một bước/mốc thời gian. Điều này hữu ích để kiểm tra các chỉ số quanh thời điểm cảnh báo được kích hoạt.

# Get metric at exactly step 200
trackio get metric --project "my-project" --run "my-run" --metric "loss" --step 200

# Get metrics in a window around step 200 (±10 steps, the default)
trackio get metric --project "my-project" --run "my-run" --metric "loss" --around 200

# Get metrics in a window around step 200 (±50 steps)
trackio get metric --project "my-project" --run "my-run" --metric "loss" --around 200 --window 50

# Get metrics within ±60 seconds of a timestamp
trackio get metric --project "my-project" --run "my-run" --metric "loss" --at-time "2025-06-01T12:05:30" --window 60

Lấy Bản chụp Chỉ số

Lấy mọi chỉ số tại hoặc quanh một bước hoặc mốc thời gian trong một lần gọi duy nhất. Đây là cách nhanh nhất để một tác nhân hiểu được trạng thái của một lần chạy tại một thời điểm cụ thể — chẳng hạn, ngay khi một cảnh báo được kích hoạt.

# All metrics at step 200
trackio get snapshot --project "my-project" --run "my-run" --step 200 --json

# All metrics in a window around step 200 (±5 steps)
trackio get snapshot --project "my-project" --run "my-run" --around 200 --window 5 --json

# All metrics within ±60 seconds of a timestamp
trackio get snapshot --project "my-project" --run "my-run" --at-time "2025-06-01T12:05:30" --window 60 --json

Ví dụ về đầu ra JSON:

{
  "project": "my-project",
  "run": "my-run",
  "around": 200,
  "window": 5,
  "metrics": {
    "loss": [
      {"step": 196, "timestamp": "2025-06-01T12:04:50", "value": 0.42},
      {"step": 200, "timestamp": "2025-06-01T12:05:30", "value": 0.45}
    ],
    "accuracy": [
      {"step": 196, "timestamp": "2025-06-01T12:04:50", "value": 0.88},
      {"step": 200, "timestamp": "2025-06-01T12:05:30", "value": 0.87}
    ],
    "lr": [
      {"step": 196, "timestamp": "2025-06-01T12:04:50", "value": 0.0001},
      {"step": 200, "timestamp": "2025-06-01T12:05:30", "value": 0.0001}
    ]
  }
}

Lấy Giá Trị Chỉ Số Hệ Thống

Lấy giá trị chỉ số hệ thống cho một lần chạy. Nếu không cung cấp tên chỉ số, tất cả các chỉ số hệ thống sẽ được trả về:

# Get all system metrics
trackio get system-metric --project "my-project" --run "my-run"

# Get a specific system metric
trackio get system-metric --project "my-project" --run "my-run" --metric "gpu_utilization"

Đầu ra ở định dạng JSON:

trackio get system-metric --project "my-project" --run "my-run" --metric "gpu_utilization" --json

Lấy nội dung báo cáo

In mục báo cáo markdown cho một tên báo cáo cụ thể trong một lần chạy:

trackio get report --project "my-project" --run "my-run" --report "training_report"

Đầu ra ở định dạng JSON:

trackio get report --project "my-project" --run "my-run" --report "training_report" --json

Lệnh truy vấn

Sử dụng trackio query khi bạn cần một truy vấn SQL chỉ đọc tổng quát mà chưa được bao phủ bởi trackio list hoặc trackio get.

Chạy truy vấn trên cơ sở dữ liệu của dự án

trackio query project --project "my-project" --sql "SELECT run_name, MAX(step) AS last_step FROM metrics GROUP BY run_name ORDER BY last_step DESC"

Đầu ra ở định dạng JSON:

trackio query project --project "my-project" --sql "SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name" --json

Truy vấn một Space từ xa:

trackio query project --project "my-project" --sql "SELECT COUNT(*) AS num_alerts FROM alerts" --space username/my-space --json

trackio query chỉ hỗ trợ các truy vấn SELECT, WITH và PRAGMA schema an toàn ở chế độ chỉ đọc.

Các ví dụ kiểm tra schema phổ biến:

# Inspect table columns
trackio query project --project "my-project" --sql "PRAGMA table_info(metrics)"

# Inspect indexes
trackio query project --project "my-project" --sql "PRAGMA index_list(alerts)"

# List tables
trackio query project --project "my-project" --sql "SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name"

Phản hồi bao gồm:

• project
• query
• columns
• rows
• row_count

Để xem bố cục đầy đủ của SQLite và parquet, hãy xem Lưu trữ Schema và Truy vấn Trực tiếp.

Định dạng đầu ra

Tất cả các lệnh list, get và query hỗ trợ hai định dạng đầu ra:

1. Dễ đọc (mặc định): Đầu ra văn bản định dạng phù hợp để xem trên terminal
2. JSON (với cờ --json): Đầu ra JSON có cấu trúc, phù hợp để xử lý bằng chương trình

Xử lý lỗi

Các lệnh CLI bao gồm xác thực và xử lý lỗi toàn diện:

• Nếu dự án không tồn tại, một thông báo lỗi sẽ được hiển thị
• Nếu một run không tồn tại trong một dự án, một thông báo lỗi sẽ được hiển thị
• Nếu một chỉ số không tồn tại trong một lần chạy, một thông báo lỗi sẽ được hiển thị
• Nếu một báo cáo không tồn tại trong một lần chạy, một thông báo lỗi sẽ được hiển thị
• Nếu truy vấn không chỉ đọc, CLI sẽ thoát với một lỗi

Tất cả các lỗi được ghi ra stderr và lệnh thoát với mã thoát khác không.

Quy trình làm việc mẫu

Dưới đây là quy trình làm việc điển hình để khám phá dữ liệu Trackio của bạn:

# 1. List all projects
trackio list projects

# 2. List runs in a project
trackio list runs --project "my-project"

# 3. Get project summary
trackio get project --project "my-project"

# 4. Get run summary
trackio get run --project "my-project" --run "my-run"

# 5. List metrics in the run
trackio list metrics --project "my-project" --run "my-run"

# 6. Get specific metric values
trackio get metric --project "my-project" --run "my-run" --metric "loss"

# 7. Get all metrics at a specific step (e.g. where an alert fired)
trackio get snapshot --project "my-project" --run "my-run" --step 200 --json

# 8. Get system metrics (if available)
trackio list system-metrics --project "my-project" --run "my-run"

# 9. List reports in a run
trackio list reports --project "my-project" --run "my-run"

# 10. Print report markdown in terminal
trackio get report --project "my-project" --run "my-run" --report "training_report"

# 11. Run a direct SQL query
trackio query project --project "my-project" --sql "SELECT run_name, MAX(step) AS last_step FROM metrics GROUP BY run_name"

Truy vấn một Space từ xa

Quy trình tương tự cũng hoạt động với một Space từ xa — chỉ cần thêm --space:

# List projects on a remote Space
trackio list projects --space username/my-space

# Get metric values from a remote Space
trackio get metric --project "my-project" --run "my-run" --metric "loss" --space username/my-space --json

Các trường hợp sử dụng

LLM Agents

Các lệnh CLI này đặc biệt hữu ích cho các tác nhân LLM cần:

• Khám phá các dự án và lượt chạy khả dụng
• Truy vấn giá trị chỉ số theo chương trình
• Kiểm tra các chỉ số xung quanh một cảnh báo bằng get snapshot hoặc get metric --around
• Chạy SQL trực tiếp cho các trường hợp không được bao phủ bởi các lệnh có cấu trúc
• Nhận bản tóm tắt mà không cần khởi động máy chủ
• Phân tích đầu ra JSON có cấu trúc để xử lý tiếp

Tự động hóa

Bạn có thể sử dụng các lệnh này trong các kịch bản shell và các pipeline tự động hóa:

#!/bin/bash
PROJECT="my-project"
RUN="my-run"

# Get the latest loss value
LATEST_LOSS=$(trackio get metric --project "$PROJECT" --run "$RUN" --metric "loss" --json | jq -r '.values[-1].value')
echo "Latest loss: $LATEST_LOSS"

Tích hợp với các công cụ khác

Định dạng đầu ra JSON giúp dễ dàng tích hợp với các công cụ khác:

# Pipe to jq for filtering
trackio list runs --project "my-project" --json | jq '.runs[] | select(startswith("train"))'

# Export to file
trackio get run --project "my-project" --run "my-run" --json > run_summary.json