> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siflow.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 Python SDK 查询指标

> 使用人工智能平台 Python SDK 查询训练任务指标和通用资源指标。

Python SDK 提供指标查询能力，适用于在脚本中分析训练任务、Pod 或节点的资源使用情况。使用本文示例前，请先完成 [安装并初始化](https://docs.siflow.cn/ai-platform/developer-access/python-sdk-quickstart.md)。

## 查询训练任务指标

### 查询前准备

* 如需查询平台内置指标，无需额外配置。平台默认采集 GPU、CPU、内存、网络、存储和节点侧异常等指标。
* 如需获取自定义指标列表，需要在创建训练任务时配置指标采集端点。详情请参见 [接入训练任务自定义指标](https://docs.siflow.cn/ai-platform/training/collect-training-task-custom-metrics.md)。

### 了解指标类型

训练任务指标分为平台内置指标和自定义指标。SDK 支持查询平台内置指标数据，也支持获取任务自定义指标列表；自定义指标数据需在控制台查看。

| 指标类型 | 来源 | 适用场景 | 查询链路 |
| - | - | - | - |
| 平台内置指标 | 平台默认采集 | 分析 GPU、CPU、内存、网络、存储、节点异常和掉队情况。 | 先获取内置指标列表，再调用 SDK 查询数据。 |
| 自定义指标 | 训练任务 Pod 暴露的 metrics 端口 | 分析训练任务暴露的业务指标，例如请求量、队列长度或训练 loss。 | 通过 SDK 获取自定义指标列表，在控制台查看指标数据。 |

## 获取训练任务指标列表

### 获取平台内置指标列表

使用 `client.tasks.metrics_catalog()` 获取平台内置指标列表。`dimension` 用于指定查询维度，支持 `task`、`pod`、`node`、`all_pods` 和 `all_nodes`。

#### 获取内置指标列表示例

以下示例展示如何获取 `task` 维度支持的内置指标列表。

```python theme={null}
from siflow import SiFlow

client = SiFlow(region="cn-beijing", cluster="auriga")

# 查看某个维度的所有可用内置指标。
catalog = client.tasks.metrics_catalog(dimension="task")

print(f"可用内置指标: {len(catalog)}")
for entry in catalog:
    print(f"  {entry.metric:30} {entry.name:20} ({entry.unit})")

# 输出示例：
#   GpuCoreUsage                   GPU核心使用率         (%)
#   NetworkTxBytes                 网络发送字节数         (Bytes/s)
```

可用维度如下：

| 维度 | 说明 |
| - | - |
| `task` | 整个任务的聚合指标。 |
| `pod` | 单个 Pod 的指标。 |
| `node` | Pod 所在节点的指标。 |
| `all_pods` | 同一任务下所有 Pod 的对比指标。 |
| `all_nodes` | 同一任务相关节点的对比指标。 |

返回结果中：

* `metric` 是查询接口使用的指标名。
* `name` 和 `unit` 用于展示指标名称和单位。
* 不同维度支持的指标范围不同，完整可查询范围以 `client.tasks.metrics_catalog()` 返回为准。

#### 内置指标示例

以下仅列出部分内置指标示例。完整可查询范围以 `client.tasks.metrics_catalog()` 返回结果为准。

| 指标 | 常见用途 |
| - | - |
| `GpuCoreUsage` | 查看 GPU 计算利用率，定位 GPU 是否空转或掉队。 |
| `GpuMemoryUsage` / `GpuMemoryUsed` | 查看显存使用比例和使用量，定位显存不足或显存利用异常。 |
| `SmActive` / `TensorActive` | 查看 GPU 计算引擎活跃度，辅助判断矩阵计算是否充分利用硬件。 |
| `GpuTemp` / `PowerUsage` | 查看 GPU 温度和功耗，辅助判断硬件运行状态。 |
| `XidErrors` / `EccSbe` / `EccDbe` | 查看 GPU 错误计数，辅助定位硬件或驱动异常。 |
| <ul><li>`GpuUtilStraggler`</li><li>`GpuMemoryStraggler`</li><li>`NvlinkTrafficStraggler`</li><li>`PcieTrafficStraggler`</li><li>`RdmaTrafficStraggler`</li></ul> | 查看 GPU、显存、NVLink、PCIe 或 RDMA 维度的掉队情况，辅助定位负载不均或通信异常。 |
| `RdmaHealth` / `RdmaTxBytes` / `RdmaRxBytes` | 查看 RDMA 健康状态和吞吐，辅助定位分布式训练通信问题。 |
| `CpuUsageOfRequest` / `MemUsageOfRequest` | 查看 CPU 和内存使用量相对申请资源的占比。 |
| `CpuUsageOfNode` / `MemUsageOfNode` | 查看 Pod 所在节点整体 CPU 和内存压力。 |
| `NetworkTxBytes` / `NetworkRxBytes` | 查看网络发送和接收速率。 |
| `GpfsReadBytes` / `GpfsWriteBytes` / `GpfsOperations` | 查看 GPFS 读写吞吐和操作速率，辅助定位存储瓶颈。 |
| `DiskReadBytes` / `DiskWriteBytes` / `DiskIoUtil` | 查看本地磁盘读写和 IO 利用率。 |

### 获取任务自定义指标列表

如果训练任务开启了自定义指标采集，可使用 `client.tasks.metrics_catalog_full()` 获取平台内置指标和该任务暴露的自定义指标列表。

#### 获取自定义指标列表示例

以下示例展示如何获取一个正在运行的训练任务暴露的自定义指标列表。

```python theme={null}
from siflow import SiFlow

client = SiFlow(region="cn-beijing", cluster="auriga")

# 获取某个正在运行的任务暴露的自定义指标列表。
catalog = client.tasks.metrics_catalog_full(
    task_name="my-training-job",  # 也可以使用 task_uuid="..."。
    dimension="task",
)

print(f"内置指标: {len(catalog.data)}")
for entry in catalog.data[:3]:
    print(f"  {entry.metric}")

print(f"\n自定义指标: {len(catalog.custom)}")
for entry in catalog.custom:
    print(f"  {entry.metric}")
    print(f"    样本值: {entry.sample_value}")

# 输出示例：
#   requests_total
#     样本值: 12345
#   train_loss
#     样本值: 0.0234
```

返回字段说明如下：

| 字段 | 说明 |
| - | - |
| `data` / `built_in` | 平台内置指标目录，当前通过 `data` 返回；`built_in` 为预留字段。 `dimension` 仅影响内置指标目录，不影响 `custom`。 |
| `custom` | 任务在 `metricsMonitor.endpoints` 上暴露的自定义指标列表。 需指定 `task_name` 或 `task_uuid`，两者不能同时传入；未指定任务时返回空列表。 |
| `custom.metric` | 自定义指标名称。 例如 `requests_total`、`train_loss` 或 `myapp_http_requests_total`。 |
| `custom.sample_value` / `custom.sample_time` | 最近一次样本值和样本时间。 |
| `custom.labels` | 自定义指标自身的标签。 |

`catalog.custom` 仅提供自定义指标列表及样本信息，不能将其中的指标名传入 `client.tasks.metrics()`、Pod 或节点指标查询接口来查询时间序列数据。查看自定义指标数据请参见 [查看训练任务监控](https://docs.siflow.cn/ai-platform/training/view-training-task-monitoring.md#查看自定义指标)。

* 自定义指标列表根据已采集的样本生成，不要求任务仍在运行；没有可用样本时可能返回空列表。
* 平台按 5 分钟采样步长发现自定义指标，查询范围为任务开始到结束的时间；运行中的任务查询到当前时间，尚未开始的任务查询过去 1 小时。此步长不表示列表每 5 分钟刷新一次。

## 查询训练任务指标数据

### 查询平台内置指标数据

获取内置指标名后，使用训练任务指标接口查询时间序列数据。`metrics` 单次请求最多传入 60 个指标。

#### 查询内置指标数据示例

以下示例展示如何查询一个训练任务的 GPU 使用率和请求内存使用量。

```python theme={null}
from siflow import SiFlow

client = SiFlow(region="cn-beijing", cluster="auriga")

response = client.tasks.metrics(
    task_name="my-training-job",
    metrics=["GpuCoreUsage", "MemUsageOfRequest"],
    start_time="2026-10-15 10:00:00",
    end_time="2026-10-15 11:00:00",
)

for metric in response.metrics:
    print(f"指标: {metric.metric}")
    print(f"单位: {metric.unit}")
    print(f"聚合方式: {metric.aggregation}")

    for series in metric.series:
        print(f"标签: {series.labels}")
        for point in series.values:
            print(f"  {point.timestamp}: {point.value}")

# 输出示例：
# 指标: GpuCoreUsage
# 单位: percent
# 聚合方式: avg
# 标签: pod=None node=None gpu=None device=None extra=None
#   1697343600: 85.5
#   1697343660: 87.2
#   1697343720: 84.1
```

#### 按查询目标选择接口

根据要查看的对象选择对应接口：

| 查询目标 | 方法 | 说明 |
| - | - | - |
| 任务级聚合指标 | `client.tasks.metrics()` | 查询一个任务的指标均值或聚合结果。<ul><li>需传入 `task_name`。</li><li>`metrics` 可选，不传时返回当前维度支持的全部指标。</li><li>`include_retries=True` 时包含自动容错重试链路中的 Pod。</li></ul> |
| 单个 Pod 指标 | `client.tasks.pod_metrics()` | 查询一个 Pod 的指标。需传入 `pod_name`；`metrics` 可选。 |
| Pod 所在节点指标 | `client.tasks.node_metrics()` | 查询 Pod 所在节点的指标。需传入 `pod_name`；GPU、RDMA 等节点指标可能按卡或设备返回多条曲线。 |
| 多 Pod 对比 | `client.tasks.all_pods_metric()` | 对比同一任务下多个 Pod 的单项指标。`metric` 只能传入一个指标；`pods` 可选，用于限制参与对比的 Pod。 |
| 多节点对比 | `client.tasks.all_nodes_metric()` | 对比同一任务相关节点的单项指标。<ul><li>`metric` 只能传入一个指标。</li><li>`pods` 可选，用于限制到指定 Pod 所在节点。</li><li>服务端最多返回 10 个节点。</li></ul> |

* **查询一个 Pod 的指标**

```python theme={null}
resp = client.tasks.pod_metrics(
    pod_name="<POD_NAME>",
    metrics=["GpuCoreUsage", "GpuMemoryUsage"],
)

for metric in resp.metrics:
    print(metric.metric, metric.unit, len(metric.series))
```

* **查询 Pod 所在节点的指标**

```python theme={null}
resp = client.tasks.node_metrics(
    pod_name="<POD_NAME>",
    metrics=["GpuTemp", "XidErrors", "CpuUsageOfNode"],
)

print(resp.node_name)
```

* **对比同一任务下多个 Pod 的单项指标**

```python theme={null}
resp = client.tasks.all_pods_metric(
    task_name="<TASK_NAME>",
    metric="GpuCoreUsage",
    pods=["<POD_NAME_1>", "<POD_NAME_2>"],
)

if not resp.metrics:
    raise RuntimeError("当前查询范围没有返回指标")

for series in resp.metrics[0].series:
    if series.values:
        print(series.labels.pod, series.values[-1].value)
```

* **对比同一任务相关节点的单项指标**

```python theme={null}
resp = client.tasks.all_nodes_metric(
    task_name="<TASK_NAME>",
    metric="GpuCoreUsage",
)

if not resp.metrics:
    raise RuntimeError("当前查询范围没有返回指标")

for series in resp.metrics[0].series:
    if series.values:
        print(series.labels.node, series.values[-1].value)
```

### 理解返回结果

训练任务指标查询接口返回 `TaskMetricsResponse`。常用字段如下：

| 字段 | 说明 |
| - | - |
| `meta.start_time` / `meta.end_time` | 服务端实际使用的查询时间范围。 |
| `meta.step` | 服务端实际使用的采样步长。未传入 `step` 时，服务端会根据时间范围自动计算。 |
| `meta.warnings` | 查询级提示，例如时间范围内没有可查询 Pod、步长被调整或结果被截断。 |
| `metrics` | 指标结果列表，按请求中的指标顺序返回。 |
| `metrics[].metric` / `metrics[].unit` | 指标名和单位。 |
| `metrics[].aggregation` | 服务端对该指标使用的聚合方式。 |
| `metrics[].series` | 指标曲线列表。不同查询目标会返回不同数量的曲线。 |
| `series[].labels` | 区分曲线的标签，例如 `pod`、`node`、`gpu` 或 `device`。 |
| `series[].values` | 时间序列点，包含 `timestamp` 和 `value`。 |
| `metrics[].warning` | 单个指标的提示信息。某个指标异常时，其他指标仍可能正常返回。 |

### 按场景分析训练任务指标

#### 识别掉队 Pod

```python theme={null}
resp = client.tasks.all_pods_metric(
    task_name="<TASK_NAME>",
    metric="GpuCoreUsage",
)

if not resp.metrics:
    raise RuntimeError("当前查询范围没有返回 GPU 利用率指标")

latest = {
    series.labels.pod: series.values[-1].value
    for series in resp.metrics[0].series
    if series.values
}
if not latest:
    raise RuntimeError("当前查询范围没有可用于比较的 Pod 指标数据")

avg = sum(latest.values()) / len(latest)

for pod, value in sorted(latest.items(), key=lambda item: item[1]):
    if value < avg * 0.5:
        print(f"slow pod: {pod} = {value}% (avg {avg:.1f}%)")
```

#### 定位可疑 GPU

```python theme={null}
resp = client.tasks.node_metrics(
    pod_name="<SUSPECT_POD_NAME>",
    metrics=["GpuTemp", "XidErrors"],
)

print(f"node: {resp.node_name}")
for metric in resp.metrics:
    for series in metric.series:
        if not series.values:
            continue
        peak = max(point.value for point in series.values)
        if metric.metric == "GpuTemp" and peak > 85:
            print(f"high temperature: GPU {series.labels.gpu}, peak {peak}")
        if metric.metric == "XidErrors" and peak > 0:
            print(f"xid error: GPU {series.labels.gpu}, code {series.labels.extra}")
```

#### 判断节点侧资源压力

可同时查看 Pod 相对申请资源的使用比例，以及 Pod 所在节点的整体资源压力，判断问题是否可能与节点侧资源竞争有关。

```python theme={null}
pod_resp = client.tasks.pod_metrics(
    pod_name="<POD_NAME>",
    metrics=["CpuUsageOfRequest", "MemUsageOfRequest"],
)
node_resp = client.tasks.node_metrics(
    pod_name="<POD_NAME>",
    metrics=["CpuUsageOfNode", "MemUsageOfNode"],
)

def latest_values(response):
    result = {}
    for metric in response.metrics:
        for series in metric.series:
            if series.values:
                result[metric.metric] = series.values[-1].value
                break
    return result


pod_values = latest_values(pod_resp)
node_values = latest_values(node_resp)
print("pod request usage:", pod_values)
print("node usage:", node_values)
```

## 补充：按资源类型查询指标

推荐优先使用训练任务指标接口查询训练任务相关指标。仅当已知 Pod 或节点名称，并需要绕过训练任务对象、按资源类型直接查询时，可使用通用资源指标接口。查询较长时间范围时，建议先获取推荐步长。

以下示例展示如何获取推荐步长，并按 Pod 名称查询 GPU 利用率。

```python theme={null}
start, end = "2026-07-31 05:44:27", "2026-08-04 07:19:18"

step = client.metrics.recommend_time_step(start, end)

resp = client.metrics.query(
    start_time=start,
    end_time=end,
    time_step=step,
    resource_type="Pod",
    metric_type="GpuCoreUsage",
    pod="<POD_NAME>",
)

print(resp)
```

也可以导入模块级函数获取推荐步长：

```python theme={null}
from siflow.resources.metrics import recommend_time_step

step = recommend_time_step("2026-01-01 00:00:00", "2026-12-31 23:59:59")
print(step)
```

查询时需要同时指定 `resource_type` 和 `metric_type`。当 `resource_type="Pod"` 时，传入 `pod`；当 `resource_type="Node"` 时，传入 `node`。

## 相关文档

* [Python SDK 快速开始](https://docs.siflow.cn/ai-platform/developer-access/python-sdk-quickstart.md)
* [使用 Python SDK 管理训练任务](https://docs.siflow.cn/ai-platform/developer-access/manage-training-tasks-with-python-sdk.md)
* [使用 Python SDK 查询日志](https://docs.siflow.cn/ai-platform/developer-access/query-logs-with-python-sdk.md)
* [查看训练任务监控](https://docs.siflow.cn/ai-platform/training/view-training-task-monitoring.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.