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

# 列出 GPU 节点

> 获取咏唱引擎 PIN 中注册的全部 GPU 节点，包括 SSH 访问详情、标签、状态与智能体数量。

使用此接口列出你的咏唱引擎 PIN 集群中的每个 GPU 节点。每个节点条目包含连接详情、标签、当前状态以及已部署智能体的数量。

## 接口

**GET** `/v1/gpu-nodes`

认证：需要 Bearer API 密钥。

## 响应

<ResponseField name="items" type="array" required>
  GPU 节点对象列表。

  <Expandable>
    <ResponseField name="id" type="string" required>
      节点标识符，例如 gn\_abc123de。
    </ResponseField>

    <ResponseField name="name" type="string" required>
      便于识别的节点名称。
    </ResponseField>

    <ResponseField name="ip" type="string" required>
      用于 SSH 的节点 IP 地址。
    </ResponseField>

    <ResponseField name="ssh_port" type="integer">
      SSH 端口（默认 22）。
    </ResponseField>

    <ResponseField name="ssh_user" type="string" required>
      SSH 用户名。
    </ResponseField>

    <ResponseField name="spec" type="string">
      硬件或配置规格摘要。
    </ResponseField>

    <ResponseField name="labels" type="array of strings">
      调度标签。
    </ResponseField>

    <ResponseField name="status" type="string">
      节点状态，例如 active。
    </ResponseField>

    <ResponseField name="agent_count" type="integer">
      部署在此节点上的智能体数量。
    </ResponseField>

    <ResponseField name="created_at" type="string (ISO 8601)">
      创建时间戳。
    </ResponseField>

    <ResponseField name="updated_at" type="string (ISO 8601)">
      最近更新时间戳。
    </ResponseField>
  </Expandable>
</ResponseField>

## 示例

```bash theme={null}
curl -s http://<pin-host>:8001/v1/gpu-nodes \
  -H "Authorization: Bearer $ARIA_PIN_KEY"
```

```json theme={null}
{
  "items": [
    {
      "id": "gn_a1b2c3d4",
      "name": "node-01",
      "ip": "10.0.1.10",
      "ssh_port": 22,
      "ssh_user": "ubuntu",
      "spec": "A100-80G x8",
      "labels": ["training", "a100"],
      "status": "active",
      "agent_count": 2,
      "created_at": "2024-05-01T12:00:00Z",
      "updated_at": "2024-05-10T08:30:00Z"
    }
  ]
}
```