Hugging Face's logo

Trackio documentation

CLI 命令

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

CLI 命令

Trackio 提供了一套全面的 CLI 命令，允许您在无需启动 MCP 服务器的情况下查询项目、运行、指标和 Space 信息。命令默认针对本地数据运行，当提供 --space 时则针对远程 HF Space 运行。这对于 LLM 智能体和自动化脚本尤为有用。凭借结构化的 JSON 输出以及对所有实验数据的程序化访问，Trackio 旨在支持由 LLM 运行的自主 ML 实验。

查询远程 Spaces

所有读取仪表板数据的 list、get 和 query 命令都支持查询远程 Hugging Face Space，而非本地数据。请通过 --space 标志传入 Space ID 或完整 URL：

# 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

对于私有 Spaces，请传入 --hf-token 或确保已通过 huggingface-cli login 登录：

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

注意：show、status、sync、freeze、skills、registry 和 list spaces 命令不支持 --space。请使用 trackio list spaces 来发现 Hugging Face Hub 上的 Trackio 仪表盘，然后将其中一个 Space ID 传递给诸如 trackio list projects --space username/my-space 之类的命令。

注册表命令

创建一个注册表，并在需要时，在将其关联到该注册表之前定义一个类型化集合：

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

将本地工件版本关联、通过移动别名提升集合版本，或取消关联版本：

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

检查集合及其审计历史记录：

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

所有注册表命令都接受 --bucket-id org/bucket 用于基于 bucket 的注册表，以及 --json 用于结构化输出。--alias 可重复使用。目标可以写作 models/churn-model 或 registry-models/churn-model。

link 命令会从本地 Trackio 数据中解析 project/artifact:version-or-alias；省略后缀则会解析 latest。发布仅存在于远程 Space 上的工件时，仍会使用 Python API，以便 Trackio 记录源数据的远程存储坐标。

同步命令

将本地项目上传到 Hugging Face Space：

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

部署为静态 Space（从 HF Bucket 读取，无需服务器）：

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

Static Spaces 直接从浏览器提供数据，因此需要公开的快照数据。不支持 --sdk static --private；对于私有仪表板，请使用默认的 Gradio SDK。

将所有具有未同步数据的项目同步到其配置的 Spaces：

trackio sync --all
标志描述
--project要同步的项目名称（除非使用 --all，否则为必填项）
--space-id要同步到的 HF Space ID（例如 username/space_id）。如果未提供，则使用之前配置的 Space
--all同步所有包含未同步数据的项目
--sdkgradio（默认）用于实时服务器，或 static 用于只读的基于存储桶的 Space
--private如果创建新的 Gradio Space，请将其设为私有。--sdk static 不支持此功能
--force在覆盖现有数据库之前不提示

Freeze 命令

从实时运行的 Gradio Space 创建只读的静态 Space 快照：

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

指定自定义目标 Space：

trackio freeze --space-id "username/my-space" --project "my-project" --new-space-id "username/my-snapshot"
标志描述
--space-id源 Gradio Space ID（必填）
--project要冻结的项目（必填）
--new-space-id目标静态 Space ID。默认为 {space_id}_static
--private不支持静态冻结快照

注意：源必须是一个在 /data 处挂载了存储桶的 Gradio Space。如果目标 Space 已存在且不是 Trackio 静态 Space，freeze 将拒绝覆盖它。 冻结后的 Space 是一个快照。之后同步到原始 Gradio Space 的指标不会显示在冻结的静态 Space 中，除非你再次运行 freeze。 静态冻结快照需要公开的目标数据，因此不支持 trackio freeze --private。

Bump

将现有的 Trackio Space 升级到本地安装的 Trackio 版本：

trackio bump username/my-space

trackio bump --space username/my-space 可以实现相同的功能。

在升级期间，Space 会暂停运行，因此训练任务会继续将日志记录到该 Space 的存储桶收件箱中。其数据库会备份到同一存储桶中的 trackio-backups/ 目录下，其 Trackio 固定版本会被更新，随后 Space 会重启，以便新版本迁移数据。如果升级后的 Space 启动失败或报告的行数少于之前，则会恢复备份以及之前的 Space 文件。

为了保持原始 Space 不变，请将其及其 bucket 复制到一个运行本地版本的新 Space 中：

trackio bump username/my-space --new-space username/my-space-v2 --new-bucket username/my-space-v2-bucket
标志描述
space_id要升级的 Trackio Space（必填，或通过 --space 传入）
--new-space从 space_id 的副本创建此 Space，而不是就地升级
--new-bucket--new-space 的桶。默认值为 {new_space}-bucket

注意： bump 支持在 /data 挂载了存储桶且运行 Trackio 0.21.0 或更高版本的 Gradio Spaces，并且绝不会降级 Space。较旧的 Space 将数据存储在 Hugging Face Dataset 中，而非存储桶中。

列出命令

列出所有项目

列出所有可用项目：

trackio list projects

以 JSON 格式输出：

trackio list projects --json

列出 Trackio Spaces

列出您的 Hugging Face 账户和组织拥有的 Trackio 仪表板 Spaces：

trackio list spaces

以 JSON 格式输出：

trackio list spaces --json

列出特定用户或组织命名空间下的 Trackio Spaces：

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

限制返回的 Spaces 数量：

trackio list spaces --limit 10

对于私有 Spaces，请传入 --hf-token 或确保已通过 huggingface-cli login 登录。

列出项目中的运行

列出特定项目中的所有运行：

trackio list runs --project "my-project"

以 JSON 格式输出：

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

列出某次运行的指标

列出特定运行中跟踪的所有指标：

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

以 JSON 格式输出：

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

列出某次运行的系统指标

列出特定运行的所有系统指标（例如 GPU 指标）：

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

以 JSON 格式输出：

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

列出报告

列出项目中的 markdown 报告（跨所有运行）：

trackio list reports --project "my-project"

列出特定运行的 markdown 报告：

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

以 JSON 格式输出：

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

列出跟踪

列出项目中所有运行中的 traces（智能体或对话会话）：

trackio list traces --project "my-project"

每一行显示该追踪的状态、实际耗时、成本、操作数以及触发它的用户请求。可按运行、步骤或文本进行筛选：

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"

搜索会匹配消息内容、追踪元数据以及每个 span 的名称、类型、模型、状态和错误。您可以控制排序和分页：

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

--sort 接受 request_time_desc（默认值）、request_time_asc、step_asc 和 step_desc。添加 --json 会为每个 trace 包含一个 summary 汇总。

获取命令

获取 Trace

显示一条包含其完整执行树的跟踪：

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 接受 trackio list traces 打印的短 ID 或完整的存储 ID。添加 --json 以获取完整的 trace，包括 span 的输入和输出。

获取 Trace 摘要

按操作名称汇总每个 span，以查看延迟、token 和成本的分布，以及哪些操作会失败：

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

使用 --run 限制为单次运行，或使用 --json 输出机器可读的行。 对于汇总未涵盖的内容，直接使用 trackio query project 查询 traces 表 — spans 是一个 JSON 列，因此 json_each 可用。

获取项目摘要

获取项目的详细摘要，包括运行次数和近期活动：

trackio get project --project "my-project"

以 JSON 格式输出：

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

摘要包括：

  • 项目名称
  • 运行次数
  • 所有运行列表
  • 最后活动（所有运行中的最大步数）

获取运行摘要

获取特定运行的详细摘要，包括指标和配置：

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

以 JSON 格式输出：

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

摘要包括：

  • 项目和运行名称
  • 日志条目数量
  • 最后一步
  • 所有指标列表
  • 运行配置（不包括内部字段）

获取指标值

获取某次运行中特定指标的所有值：

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

以 JSON 格式输出：

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

输出包括：

  • 步骤编号
  • 时间戳
  • 指标值

按步骤或时间筛选

您可以将指标值筛选到特定步骤或步骤/时间戳附近的窗口。这在检查告警触发时间附近的指标时非常有用。

# 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
标志描述
--step N返回恰好为第 N 步的指标
--around N返回步骤 N 附近窗口内的指标
--at-time T返回 ISO 8601 时间戳 T 附近窗口内的指标
--window W窗口大小：--around 为 ±steps，--at-time 为 ±seconds（默认值：10）

获取指标快照

通过单次调用获取所有在某个步骤或时间戳处/附近的所有指标。这是智能体了解特定时间点运行状态的最快方式——例如，在警报触发的那一刻。

# 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

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}
    ]
  }
}

获取系统指标值

获取某次运行的系统指标值。如果未提供指标名称，则返回所有系统指标：

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

以 JSON 格式输出：

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

获取报告内容

打印特定运行中特定报告名称的 Markdown 报告条目：

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

以 JSON 格式输出：

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

查询命令

当您需要一个通用的只读 SQL 查询，且该查询尚未被 trackio list 或 trackio get 覆盖时，请使用 trackio query。

对项目数据库运行查询

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"

以 JSON 格式输出：

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

查询远程 Space：

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

trackio query 仅支持只读的 SELECT、WITH 以及安全的 schema PRAGMA 查询。

常见的模式检查示例：

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

响应包含：

  • project
  • query
  • columns
  • rows
  • row_count

有关完整的 SQLite 和 parquet 布局，请参阅 存储架构和直接查询。

输出格式

所有 list、get 和 query 命令都支持两种输出格式：

  1. 人类可读（默认）：适合在终端中查看的格式化文本输出
  2. JSON（使用 --json 标志）：适合程序化处理的结构化 JSON 输出

错误处理

CLI 命令包含全面的验证和错误处理：

  • 如果项目不存在，则会显示错误消息
  • 如果项目中不存在某个运行，则会显示错误消息
  • 如果某个指标在运行中不存在，则会显示错误消息
  • 如果某个运行中不存在报告，则会显示错误消息
  • 如果查询不是只读的，CLI 将退出并返回错误

所有错误都会写入 stderr，并且该命令会以非零退出码退出。

示例工作流

以下是探索 Trackio 数据的典型工作流程：

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

查询远程 Space

同样的工作流程也适用于远程 Space —— 只需添加 --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

用例

LLM 智能体

这些 CLI 命令对于需要执行以下操作的 LLM 智能体尤其有用：

  • 发现可用的项目和运行
  • 以编程方式查询指标值
  • 使用 get snapshot 或 get metric --around 查看告警周围的指标
  • 对于结构化命令未涵盖的情况，运行直接 SQL
  • 无需启动服务器即可获取摘要
  • 解析结构化 JSON 输出以进行进一步处理

自动化脚本

您可以在 shell 脚本和自动化流水线中使用这些命令：

#!/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"

与其他工具的集成

JSON 输出格式便于与其他工具集成：

# 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
Update on GitHub

←用于管理运行（Runs）的 Python API 日志→