gRPC接口参考

1.1 Proto 文件与 Client Stub 生成

各 K8s 组件中，Device Plugin、Exporter 与灵骏 Runtime Kit 间的 gRPC 通信共用同一个 Unix Domain Socket（dp2mgr.sock）及同一份 proto 定义。资源管理/监控类 proto 可从开源仓 Device Plugin 组件获取（路径 internal/grpc/api_outer.proto）；Controller 使用独立的 config-daemon.sock 与独立的 proto，位于 Controller 组件的 api/proto/config_service.proto（见第 5 章）。

生成各语言 Client Stub 示例：

# Go（推荐，与组件源码一致）
protoc --go_out=plugins=grpc:. api_outer.proto

# Python
python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. api_outer.proto

# Java
protoc --java_out=. --grpc-java_out=. api_outer.proto

1.2 Go 调用示例

以 Device Plugin 源码中的调用方式为参考：

import (
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
)

socketPath := "unix:///run/amp/eKitC/xdm/sockets/dp2mgr.sock"
conn, err := grpc.Dial(socketPath, grpc.WithTransportCredentials(insecure.NewCredentials()))
if err != nil {
    log.Fatalf("connect failed: %v", err)
}
defer conn.Close()

client := NewXpuDeviceManagerServiceClient(conn)
// 调用示例：查询节点支持的 xPU 类型
resp, err := client.ListSupportedXPUType(context.Background(), &XPUTypeRequest{})

注：示例中的 service / client 名称（XpuDeviceManagerService）为 proto 定义的生成名称，以开源仓 proto 文件为准。

3.1 ListSupportedXPUType

查询当前节点支持的 xPU 设备类型。请求：无参数（空请求）。

响应字段：

3.2 ListAndWatch

流式推送节点设备列表与健康状态变化。请求：无参数（空请求）。

响应字段（流式，每次推送完整设备列表）：

3.3 Allocate

核心资源分配接口，为容器分配 xPU 资源。

请求字段：

devices 为 repeated 结构，表示“为该容器分配多张卡”，每个元素对应一张独立的 GPU 卡分配；当前仅支持同构配置，即所有元素须使用相同的 core/memory/slice 值。minor 字段不填时由灵骏 Runtime Kit 自动分配可用卡号。

设备分配字段（devices[]）：

extender 字段说明：

Allocate 请求中 devices[].extender 为通用扩展字段（map<string, string>），与 ListAndWatch 响应的 extenderResources 形成上行/下行对称设计：ListAndWatch 上行上报设备拓扑，Allocate 下行回传调度器的分配决策。

当前已定义的 Key：

响应字段：

场景字段填写约定：

关键约束：

• core 不填或填 0 表示不开启算力限制（整卡可用）；取值范围 [1,100] 为单卡百分比；多卡场景通过 devices 数组（每元素一张卡）表达；

• memory 在 Allocate 请求中单位为 GiB；ListAndWatch 返回的 totalMemory 单位为 MiB，注意区分；

• core 和 memory 其中之一填 0，表示不限制算力或显存；两者同时为 0 且没有申请其他资源时，按 CPU 容器处理；

• minor 填写则使用指定卡号（适用于有上层调度器的场景）；不填则由灵骏 Runtime Kit 自动分配；

• slice 支持值：1、2、3、4、7（MIG 切分当前支持 A100 与 H800 卡型号）。

featureGates 与 annotations 字段说明：两字段为预留扩展字段（featureGates 为 map<int32, bool>，annotations 为 map<string, string>），当前版本暂未启用具体功能。设计意图：featureGates 用于后续按需开启特性开关，annotations 用于调用方与灵骏 Runtime Kit 之间传递附加上下文信息。标准场景下无需填写，保持为空即可；自定义开发场景下可利用 annotations 传递自定义 KV 信息，Runtime Kit 侧会透传并在响应中回传。

请求示例：

整卡分配（两张卡）：

{ "id": "550e8400-e29b-41d4-a716-446655440000", "devices": [{ "minor": 1 }, { "minor": 2 }] }

时分复用（50% 算力 + 4 GiB 显存）：

{ "id": "550e8400-e29b-41d4-a716-446655440001", "devices": [{ "minor": 1, "core": 50, "memory": 4 }] }

MIG 空分：

{ "id": "550e8400-e29b-41d4-a716-446655440004", "devices": [{ "minor": 1, "slice": 3, "memory": 4 }] }

3.4 extenderResources 与拓扑信息

ListAndWatch 响应中 devices[].extenderResources 为通用扩展字段（map<string, string>），用于 Device Plugin 向调度器传递超出标准字段范围的附加设备属性。

当前已定义的 Key：

topology Value 格式为 JSON 字符串，序列化自 per-device 拓扑对象。XDM 采集硬件/网络拓扑并将其抽象为按距离排序的层级序数，经 ListAndWatch 每张卡的 extenderResources["topology"] 透传给 Device Plugin；DP 按 level 分段翻译为 Node Annotation 与 Label，最终由 Scheduler 消费。对象形如 {"levels": [...]}，levels 为该卡涉及的全部拓扑层级，每个元素描述一个拓扑层级：

PPU M890P per-device 示例（GPU 0）：

{
  "levels": [
    {"level": 1,  "name": "pcieSwitches",    "topo1": [0],  "peers": [0, 1]},
    {"level": 2,  "name": "numaNodes",       "topo2": [0],  "peers": [0, 1]},
    {"level": 3,  "name": "cpuSockets",      "topo3": [0],  "peers": [0, 1, 2, 3]},
    {"level": 11, "name": "hyperNode",       "topo11": "hypernode-001"},
    {"level": 21, "name": "leafSwitch",      "topo21": "asw-001"},
    {"level": 22, "name": "pointOfDelivery", "topo22": "pod-g13-p1"}
  ]
}

M890P 节点内三层（pcieSwitches / numaNodes / cpuSockets）带 peers 与 topoN，rack 层（hyperNode）与网络层（leafSwitch / pointOfDelivery）仅带 topoN 字符串标识。其中 topo1 携带的设备索引由 DP 与调度器翻译为具体的 GPU↔RDMA 设备映射，其余层级同理。

PPU 810E per-device 示例（GPU 0，含节点内卡间互联分层 + PCIe 分层 + 网络层）：

{
  "levels": [
    {"level": 1,  "name": "icnLink2",        "topo1": [0],  "peers": [0, 3]},
    {"level": 2,  "name": "icnLink4",        "topo2": [0],  "peers": [0, 1, 2, 3]},
    {"level": 3,  "name": "icnLink8",        "topo3": [0],  "peers": [0, 1, 2, 3, 4, 5, 6, 7]},
    {"level": 4,  "name": "pcieSwitches",    "topo4": [4],  "peers": [0, 1, 2, 3]},
    {"level": 5,  "name": "numaNodes",       "topo5": [1],  "peers": [0, 1, 2, 3, 8, 9, 10, 11]},
    {"level": 6,  "name": "cpuSockets",      "topo6": [0]},
    {"level": 21, "name": "leafSwitch",      "topo21": "ASW-VM-SQA-G10-P2-S25"},
    {"level": 22, "name": "pointOfDelivery", "topo22": "VM-SQA-G10-P2"}
  ]
}

810E 节点内先按卡间互联分层（icnLink2 / icnLink4 / icnLink8，peers 反映实际链路连接、不一定连续编号），再叠加 PCIe 物理分层（pcieSwitches / numaNodes / cpuSockets），并可携带网络层（leafSwitch / pointOfDelivery）。

字段语义（level/topoN 抽象口径）：

层级按 level 数值升序即为“从近到远”排列，调度器据此在多卡/跨节点场景下优先选择拓扑距离最近的组合；某机型不具备的层级段（如无 rack 段）直接省略。

3.5 Release

释放容器的设备分配记录（与 Allocate 反向操作）。当容器销毁时由 Device Plugin 调用，通知 XDM 回收该容器占用的设备资源。

请求字段：

响应字段：

请求示例：

{ "id": "550e8400-e29b-41d4-a716-446655440000" }

响应示例：

{ "status": 0, "message": "" }

4.1 ListGpuInfo

获取节点 GPU 设备静态信息（型号、UUID、驱动版本等）。

请求字段：

响应字段：

4.2 ExporterGetDataList

按设备和指标 ID 单次拉取指标快照，适用于定时采集场景。

请求字段：

响应字段（dataList[]）：

4.3 ExporterDataStream

长连接流式接口，核心服务按采集周期持续推送指标更新。请求/响应格式与 ExporterGetDataList 相同。客户端须实现重连与指数退避机制（建议起始 1s、倍数 2、上限 30s）。

4.4 ExporterGetConfig

获取 Exporter 采集配置信息。

响应字段：

4.5 ExporterGetStatus

查询 Exporter 运行状态。

响应字段：

5.1 Enable

启用节点上的 Runtime Kit 功能。请求：EnableRequest {}（无参数）。

响应字段（EnableResponse）：

5.2 Disable

禁用节点上的 Runtime Kit 功能。请求：DisableRequest {}（无参数）。响应：DisableResponse（字段同 EnableResponse）。

5.3 QueryStatus

查询节点上 Runtime Kit 功能的启用状态。请求：QueryStatusRequest {}（无参数）。

响应字段（QueryStatusResponse）：

调用示例（Go）：

// 连接 config-daemon Unix Socket
conn, err := grpc.Dial(
    "unix:///run/amp/eKitC/xdm/sockets/config-daemon.sock",
    grpc.WithTransportCredentials(insecure.NewCredentials()),
)
client := configpb.NewAmpConfigServiceClient(conn)

// 启用
resp, err := client.Enable(ctx, &configpb.EnableRequest{})

// 查询状态
status, err := client.QueryStatus(ctx, &configpb.QueryStatusRequest{})
fmt.Println("enabled:", status.Enabled)