指标与 Primary Metric

指标是 GPUPlane 观测与诊断的原料：diagnose_run、异常检测、checkpoint 推荐全都从指标读出。训练脚本接入指标的门槛被刻意做到最低——三级接入，按改造意愿任选。

三级指标接入

级别	方式	训练代码改动	适用
L1	TensorBoard 目录实时 tail	零（已有 TB 日志即可）	存量项目、快速接入
L2	SDK 直报 `run.log(...)`	加几行	新项目，最可靠
L3	NVML 系统指标（util/显存/温度/功耗）	零	自动覆盖所有平台 job

三级互补：L3 永远在线，L1 覆盖“已经写了 TB”的项目，L2 提供最精确的语义。

L2：SDK 用法

from gpuctl import run

run.init(project="qwen-sft", experiment="lr-2e5", config={...})  # 平台 job 内自动 attach，可省略
run.log({"train/loss": loss.item()}, step=step)                  # 有界队列，绝不阻塞/抛错
run.log_checkpoint(path, step=step)                              # 只登记，不搬运文件
run.finish()

SDK 的三条保证：平台 dispatch 的 job 内零配置（env 自动注入）；平台外裸跑自动注册 source=sdk 的 run；无 server 时静默降级为本地 jsonl spool，训练脚本行为完全不变。

命名约定

指标名用 / 命名空间：train/loss、eval/loss、eval/accuracy。诊断与推荐逻辑默认认识 train/* 与 eval/* 两个前缀。

Primary Metric：唯一的“最佳”标准

所有“哪个最好”的判断（get_best_checkpoint / compare_runs / compare_checkpoints）都由一个 primary metric 驱动——不做多目标。

解析顺序：experiment → project → global 继承（global 默认 eval/loss 最小化，或 eval/accuracy 最大化）。设置入口：Experiments UI、MCP set_primary_metric、或 PUT /api/v1/primary-metric。

跨范围比较只用所有 run 的共同范围：

比较范围	使用的 primary metric
同 experiment 内	experiment 级设置
同 project 跨 experiment	project 级设置
跨 project	global 默认，或显式传 `metric` 参数

评估优先于训练期 best

get_best_checkpoint 优先使用评估结果（成功 EVALUATION 的 primary metric）；没有评估时回退到训练 run 的 best 值（保存 best checkpoint 那一 step 的指标）。回退更弱——那是训练集指标，不是 held-out 评估。宣布胜出前先跑 evaluate_checkpoint。

常见 primary metric 选择

指标	direction	场景
`eval/loss`	minimize	大多数训练的默认值
`eval/accuracy`	maximize	分类任务，人类直觉友好
`val_bpb`	minimize	LM 预训练惯例
`perplexity`	minimize	LM 评估

其余指标照常被记录、照常出现在 diagnose_run 的 convergence 分析里—— 只是不驱动“最佳”排名。

查询与存储

写入收口在 server 单进程（SQLite 单写者），批量事务。
查询按时间窗自动选 raw 或 rollup（?window=1h → raw；7d → 1 分钟 rollup），对调用方透明。
list_metric_definitions(project_id=…) 返回当前生效的 primary 及其来源（哪一级继承来的）。

导入历史实验

已有实验（TB events + checkpoints + 日志）可以离线导入为 IMPORTED run：

uv run gpuctl import-run ~/experiments/old-run --project legacy