观测工具（11）

观测工具只需 read scope。它们是了解平台状态的全套只读入口。

节点

list_nodes()

列出 fleet 中所有 GPU 节点：状态、硬件、GPU 槽位占用。 通常是第一个调用的工具——先看什么硬件在线、哪些卡空闲。

get_node_status(node_id)

单个节点完整状态：硬件、槽位（含 owner job）、最新系统指标快照、心跳时长。 在 list_nodes 之后下钻用。

任务

list_jobs(status?, limit=200)

列出调度队列中的 job。status 过滤： QUEUED / RUNNING / SUCCEEDED / FAILED / CANCELLED / LOST。 status=RUNNING 看在途训练；status=FAILED 找需要诊断的对象。

get_job(job_id)

单个 job：command、资源、状态、exit code、失败原因、所在节点、attempt。 submit_job 返回的 handle 里的 job_id 就是在这里轮询。

Run 观测

get_run_summary(run_id)

run 的压缩语义视图：状态、进度（step/max/epoch）、各指标 latest/best/trend、 健康警告。了解一个 run 的首选入口——先读它，别直接拉原始指标。

query_metrics(run_id, names?, window?, limit=5000)

run 的原始指标时间序列（绘图或自定义分析用）。window 形如 "6h"。 快速了解状态请优先 get_run_summary。

tail_logs(job_id, stream="combined", tail=200)

job 日志的最后 N 行（server 保存尾部；全量日志在 agent 主机）。 失败后读 traceback 用。stream: stdout / stderr / combined。

list_events(run_id?, job_id?, severity?, type?, limit=100)

生命周期 + 检测器事件（OOM、LOSS_SPIKE、过拟合、断连……）。 传 severity="critical" 只看需要立即关注的事。

Checkpoint 与评估

list_checkpoints(run_id)

run 产出的 checkpoint：step、路径、大小、指纹。

list_evaluations(run_id? 或 checkpoint_id?)

评估结果（每个 checkpoint 的评估指标）。挑最优 checkpoint 的原始数据； 结构化视图请用 compare_checkpoints。

指标定义

list_metric_definitions(project_id? 或 experiment_id?)

已注册指标：名称、direction（minimize/maximize）、哪个是 primary。 依赖 best/winner 结论前先调它确认 primary metric（含继承自哪一级）。

典型顺序

list_nodes → submit_job → get_job（直到 run 创建）
→ get_run_summary（首屏）→ query_metrics / tail_logs（需要细节时）
→ list_checkpoints → evaluate_checkpoint → list_evaluations