Trackio CLI 指标检索实战指南用 trackio 命令查询与自动化你的 Hugging Face 实验数据【免费下载链接】skillsGive your agents the power of the Hugging Face ecosystem项目地址: https://gitcode.com/GitHub_Trending/skills7/skillsTrackio 是 Hugging Face 生态中一款轻量、免费、wandb 兼容的实验追踪库而在本仓库的huggingface-trackioskill 中它被定位为 LLM Agent 驱动 ML 训练的核心工具链之一训练中用 Python API 写指标、发告警训练中/后用trackioCLI 直接检索。本文聚焦其检索侧——CLI 的完整命令体系、JSON 输出结构、基于 jq 的自动化脚本以及面向 LLM Agent 的发现—探索—查询—轮询—快照闭环工作流读完即可在终端和 Agent 场景中熟练取回任何一条指标。trackioCLI 允许你在终端中直接查询 Trackio 实验追踪数据无需启动 MCP 服务器即可完成全部读取操作。本文对应仓库中的 retrieving_metrics.md并与 SKILL.md、logging_metrics.md、alerts.md 相互配合构成 Trackio 的写指标、发告警、取数据三件套。快速命令参考下表覆盖了日常使用中最常调用的命令也是后续所有实操章节的索引任务命令列出项目trackio list projects列出运行trackio list runs --project name列出指标trackio list metrics --project name --run name列出系统指标trackio list system-metrics --project name --run name列出告警trackio list alerts --project name [--run name] [--level level] [--since timestamp]获取项目摘要trackio get project --project name获取运行摘要trackio get run --project name --run name获取指标值trackio get metric --project name --run name --metric name获取指定 step 指标trackio get metric ... --metric name --step N获取 step 邻域指标trackio get metric ... --metric name --around N --window W获取全部指标快照trackio get snapshot --project name --run name --step N获取系统指标trackio get system-metric --project name --run name打开仪表盘trackio show [--project name]同步到 Spacetrackio sync --project name --space-id space_id从命令结构可以看出CLI 遵循先list发现、再get取值的两级模型list负责枚举项目、运行、指标、系统指标与告警get负责取回具体实体project / run / metric / snapshot / system-metric的详细数据。这与 SKILL.md 中描述的接口分工一致——CLI 是训练完成或进行中的读通道而 Python API 是训练过程中的写通道。List 系列命令发现实验资产list命令用于探索本地数据库中已经存在的实验数据所有命令都支持--json输出trackio list projects # 列出所有项目 trackio list projects --json # JSON 输出 trackio list runs --project name # 列出项目下的运行 trackio list runs --project name --json # JSON 输出 trackio list metrics --project name --run name # 列出运行的所有指标 trackio list metrics --project name --run name --json trackio list system-metrics --project name --run name # 列出系统指标GPU 等 trackio list system-metrics --project name --run name --json trackio list alerts --project name # 列出告警 trackio list alerts --project name --run name --json # 按运行过滤 trackio list alerts --project name --level error --json # 按级别过滤 trackio list alerts --project name --json --since ts # 按时间戳增量轮询使用要点list projects是最常用的入口命令用于确认本地数据库中存在哪些实验项目返回值是一个项目名数组。list runs --project name需要项目名作为前置条件因此标准流程是先list projects再list runs。list alerts的--level可选值为info、warn、error与 alerts.md 中定义的三个告警级别一一对应--since接受 ISO 时间戳用于只取某时间点之后的新告警——这是 Agent 做增量轮询的关键参数。Get 系列命令取回具体数据get命令是检索的核心负责返回具体实体的详细内容trackio get project --project name # 项目摘要 trackio get project --project name --json # JSON 输出 trackio get run --project name --run name # 运行摘要 trackio get run --project name --run name --json trackio get metric --project name --run name --metric name # 指标值 trackio get metric --project name --run name --metric name --json trackio get metric ... --metric name --step 200 # 精确 step 取值 trackio get metric ... --metric name --around 200 --window 10 # ±10 步窗口 trackio get metric ... --metric name --at-time ts --window 60 # ±60 秒窗口 trackio get snapshot --project name --run name --step 200 --json # 某 step 的全部指标 trackio get snapshot --project name --run name --around 200 --window 5 --json # 窗口内快照 trackio get snapshot --project name --run name --at-time ts --window 60 --json trackio get system-metric --project name --run name # 全部系统指标 trackio get system-metric --project name --run name --metric name # 指定系统指标 trackio get system-metric --project name --run name --json这里需要重点理解三种时间定位方式--step N精确到某个训练步step。适合已知告警或事件发生在第 N 步、需要读取该步确切值的情形。--around N --window W以第 N 步为中心、左右各取 W 步的窗口。默认窗口大小为 10。适合在告警触发后回看这个点前后发生了什么。--at-time ts --window W以 ISO 时间戳为中心、左右各取 W 秒的窗口。适合用告警的时间戳反查当时的指标状态。get snapshot与get metric的区别在于snapshot一次返回某个 step或窗口内的全部指标而metric只返回单一指标的时间序列。在排查某一步发生了什么时snapshot是效率最高的工具。Dashboard 与 Sync 命令可视化与远端同步Dashboardtrackio show # 启动仪表盘 trackio show --project name # 加载指定项目 trackio show --theme theme # 自定义主题 trackio show --mcp-server # 启用 MCP 服务器模式 trackio show --color-palette #FF0000,#00FF00 # 自定义颜色show启动本地 Gradio 仪表盘用于可视化浏览指标曲线与告警。--mcp-server可以在仪表盘模式下同时启用 MCP 服务器将 Trackio 能力暴露给 MCP 客户端Agent--color-palette接受逗号分隔的十六进制颜色用于自定义曲线配色。Synctrackio sync --project name --space-id space_id # 同步到 HF Space trackio sync --project name --space-id space_id --private # 创建私有 Space trackio sync --project name --space-id space_id --force # 覆盖已有数据库sync将本地项目数据同步到 Hugging Face Space。这一点与 logging_metrics.md 中本地 SQLite 默认存储的机制相衔接本地训练时数据落在 SQLite 中需要持久化/共享时用sync推送到 Space 仪表盘。--force用于覆盖 Space 中已存在的旧数据库--private用于创建私有 Space默认自动创建的 Space 是公开的需要注意指标隐私。在 trackio_guide.md 的 Jobs 场景中这一机制被进一步描述为训练时指标以亚秒级小批次流式写入 SpaceSpace 不可达时指标每约 30 秒溢出spill到 HF BucketSpace 仪表盘每约 15 秒从 Bucket 摄取溢出指标训练结束时trackio.finish()排空所有待同步指标确保数据完整落盘。输出格式人性化文本与结构化 JSON所有list与get命令都支持两种输出格式Human-readable默认格式化文本适合终端直接查看。JSON--json结构化 JSON适合程序化使用与 LLM Agent 消费。在 Agent 与自动化场景中SKILL.md 明确给出关键提示始终加上--json它是让输出可被程序解析、可被 Agent 理解的前提。常见实战模式发现项目与运行# 列出所有可用项目 trackio list projects # 列出项目中的运行 trackio list runs --project my-project # 获取项目概览 trackio get project --project my-project --json检查运行详情# 获取包含全部指标摘要的运行信息 trackio get run --project my-project --run my-run --json # 列出可用指标 trackio list metrics --project my-project --run my-run # 获取具体指标值 trackio get metric --project my-project --run my-run --metric loss --json查询系统指标# 列出系统指标GPU 等 trackio list system-metrics --project my-project --run my-run # 获取全部系统指标数据 trackio get system-metric --project my-project --run my-run --json # 获取指定系统指标如 GPU 利用率 trackio get system-metric --project my-project --run my-run --metric gpu_utilization --json系统指标GPU 利用率、显存等在本地训练与 Jobs 远程训练中都会被自动采集。根据 trackio_guide.md 的说明当检测到 NVIDIA GPU 且安装了nvidia-ml-py时标准 Jobs GPU 环境即满足Trackio 会自动记录 GPU 利用率与显存指标——这正是上述system-metric命令的数据来源。自动化脚本jq 管道CLI 的--json输出与jq天然配合可以写出紧凑的自动化脚本# 提取最新一条指标值 LATEST_LOSS$(trackio get metric --project my-project --run my-run --metric loss --json | jq -r .values[-1].value) # 导出运行摘要到文件 trackio get run --project my-project --run my-run --json run_summary.json # 用 jq 过滤运行如只看以 train 开头的运行 trackio list runs --project my-project --json | jq .runs[] | select(startswith(train))从 JSON 输出结构下文详述可以看到get metric的values数组元素形如{step: N, timestamp: ..., value: X}因此jq .values[-1].value可以精确取出最新一条指标值而list runs的 JSON 输出形如{project: ..., runs: [run1, run2]}jq .runs[]即可逐条过滤。LLM Agent 完整工作流针对 Agent 自主迭代实验的场景文档给出了一条六步闭环流程# 1. 发现可用项目 trackio list projects --json # 2. 探索项目结构 trackio get project --project my-project --json # 3. 检查具体运行 trackio get run --project my-project --run my-run --json # 4. 查询指标值 trackio get metric --project my-project --run my-run --metric accuracy --json # 5. 轮询告警用 --since 实现高效增量轮询 trackio list alerts --project my-project --json --since 2025-06-01T00:00:00 # 6. 告警在 step N 触发时取该点前后全部指标 trackio get snapshot --project my-project --run my-run --around 200 --window 5 --json这条工作流与 alerts.md 中推荐的 Agent 模式完全对应训练代码中埋入trackio.alert()诊断告警loss 发散、NaN、训练停滞等→ Agent 用--since增量轮询告警 → 告警触发后用get snapshot --around观察该点全部指标 → 依据ERROR/WARN/INFO级别决定停止、调整超参数还是继续监控。当 Agent 直接监视训练脚本终端输出时告警会自动打印到终端无需轮询只有后台/分离运行的训练才需要走 CLI 轮询通道。错误处理命令会对输入做校验并返回清晰的错误信息项目缺失Error: Project name not found.运行缺失Error: Run name not found in project project.指标缺失Error: Metric name not found in run run of project project.所有错误都以非零退出码结束并写入 stderr。这意味着在 Shell 脚本中可以直接用退出码判断查询是否成功配合21可将错误信息捕获用于日志或告警。关键选项速查选项说明--project项目名大多数命令必需--run运行名运行级命令必需--metric指标名指标级命令必需--json输出 JSON 而非人性化文本--step精确 step 过滤get metric、get snapshot--around窗口过滤的中心 stepget metric、get snapshot--at-time窗口过滤的中心 ISO 时间戳get metric、get snapshot--window窗口大小配合--around为 ±步数配合--at-time为 ±秒数默认 10--level告警级别过滤info、warn、errorlist alerts--since过滤该 ISO 时间戳之后的告警list alerts--theme仪表盘主题show--mcp-server启用 MCP 服务器模式show--color-palette逗号分隔的十六进制颜色show--private创建私有 Spacesync--force覆盖已有数据库syncJSON 输出结构详解掌握各命令的 JSON 结构是写自动化脚本和 Agent 提示词的基础。以下是文档给出的权威结构List Projects{projects: [project1, project2]}List Runs{project: my-project, runs: [run1, run2]}Project Summary{ project: my-project, num_runs: 3, runs: [run1, run2, run3], last_activity: 100 }last_activity可用于判断项目最近活跃度例如 Agent 决定是否优先关注某个老项目。Run Summary{ project: my-project, run: my-run, num_logs: 50, metrics: [loss, accuracy], config: {learning_rate: 0.001}, last_step: 49 }config对应 logging_metrics.md 中trackio.init(config{...})记录的配置字典metrics数组则直接来自训练中trackio.log()写入的键名。Metric Values{ project: my-project, run: my-run, metric: loss, values: [ {step: 0, timestamp: 2024-01-01T00:00:00, value: 0.5}, {step: 1, timestamp: 2024-01-01T00:01:00, value: 0.4} ] }values数组按 step 升序排列每个元素包含step、timestampISO 格式与value三个字段。这是自动化提取最新值.values[-1].value或某 step 的值配合--step/--around的直接依据。告警的 JSON 结构可在 alerts.md 中找到形如{project: ..., run: ..., level: ..., since: ..., alerts: [{run, title, text, level, step, timestamp}]}其中level取值为info/warn/errorAgent 可据此快速分级决策。从写入到读取的完整闭环将上述检索能力放入 Trackio 的完整生命周期中一次实验的标准闭环是写入训练脚本中trackio.init(projectmy-project, config{...})→ 循环内trackio.log({...})→ 结束时trackio.finish()见 logging_metrics.md。告警训练循环内插入trackio.alert(title..., leveltrackio.AlertLevel.WARN/ERROR)标记异常见 alerts.md。读取终端或 Agent 使用本指南的全部list/get命令取回数据配合--json与jq实现自动化。可视化/同步trackio show本地看板或trackio sync --space-id推送 HF Space 实现持久化看板与多端共享。在仓库的 train_sft_example.py 中可以看到这一闭环的落地形态脚本以report_totrackio接入 TRLtrackio.init传入项目名与 Space 配置训练结束后trackio.finish()确保最终指标同步并打印 Space 看板地址。这也再次印证了读取侧的 CLI 命令与写入侧的 Python API 是同一份本地 SQLite 数据或同步后的 Space 数据库的两种访问方式——写侧负责采集读侧负责消费共同支撑起训练—监控—诊断—迭代的自动化实验循环。【免费下载链接】skillsGive your agents the power of the Hugging Face ecosystem项目地址: https://gitcode.com/GitHub_Trending/skills7/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考