跳到主要内容

可观测性

后端 API​

可观测性功能拆分在 llm_d_lens/monitoring/ 下的五个 FastAPI 路由器中：accelerator/router.py、cluster_stack/router.py、deployment/router.py、gpu_driver/router.py 和 profiling/router.py。

列出加速器可观测性能力​

列出 Lens 支持的加速器可观测性能力，包括访问模式和默认命名空间。

GET /api/v1/monitoring/accelerators

请求：无请求体。

响应：返回一个 AcceleratorCapabilitiesResponse，其中包含支持的加速器系列。

{
  "accelerators": [
    {
      "type": "intel_gpu",
      "display_name": "Intel GPU",
      "access_modes": ["dra", "plugin"],
      "release_name": "xpumd",
      "default_namespace": "intel-xpumd"
    },
    {
      "type": "nvidia_gpu",
      "display_name": "NVIDIA GPU",
      "access_modes": ["plugin", "dra"],
      "release_name": "dcgm-exporter",
      "default_namespace": "dcgm-exporter"
    }
  ]
}

获取加速器可观测性状态​

获取某个加速器系列的可观测性状态，包括 release、组件以及访问模式的健康状况。

GET /api/v1/monitoring/accelerators/{accelerator}/status

请求：无请求体。路径参数：accelerator（str，取值为已注册系列之一：intel_gpu 或 nvidia_gpu）。查询参数：namespace（str，默认值为 intel-xpumd，无论所选加速器是哪个——查询 nvidia_gpu 时，请显式传入 dcgm-exporter 或 NVIDIA release 实际安装到的命名空间）、access_mode（"dra" | "plugin"，可选）以及 cluster_id（str，可选）。

响应：返回一个 AcceleratorStatusResponse。

{
  "accelerator": "intel_gpu",
  "access_mode": "dra",
  "access_modes": [
    {
      "mode": "dra",
      "available": true,
      "detected": true,
      "message": null
    },
    {
      "mode": "plugin",
      "available": false,
      "detected": false,
      "message": "device plugin not installed"
    }
  ],
  "cluster_reachable": true,
  "context": "kind-test",
  "namespace": "intel-xpumd",
  "release": {
    "name": "xpumd",
    "status": "deployed",
    "chart": "xpumd-0.1.0",
    "revision": 1
  },
  "status": "ready",
  "message": "ready",
  "components": [
    {
      "name": "xpumd-controller",
      "status": "ready",
      "kind": "workload",
      "ready": 1,
      "desired": 1,
      "source": "xpumd",
      "diagnostics": []
    }
  ],
  "active_operation_id": null,
  "observed_at": "2026-09-23T08:00:00Z",
  "stale": false
}

安装加速器可观测性​

为受支持的加速器系列安装可观测性组件。

POST /api/v1/monitoring/accelerators/{accelerator}/installations

请求：路径参数 accelerator（str）。可选请求头：Idempotency-Key（str）。可选查询参数：cluster_id（str）。请求体字段为 accelerator、access_mode 和 namespace。

{
  "accelerator": "intel_gpu",
  "access_mode": "dra",
  "namespace": "intel-xpumd"
}

响应：返回已排队安装操作对应的 AcceleratorOperationResponse。

{
  "operation_id": "accel-op-123",
  "kind": "install",
  "status": "queued",
  "phase": "queued",
  "accelerator": "intel_gpu",
  "access_mode": "dra",
  "namespace": "intel-xpumd",
  "started_at": "2026-09-23T08:01:00Z",
  "finished_at": null,
  "exit_code": null,
  "logs": [],
  "error": null
}

获取集群监控技术栈状态​

检查集群级别的 Prometheus/Grafana 监控技术栈（kube-prometheus-stack）是否已安装并就绪。

GET /api/v1/monitoring/cluster-stack/status

请求：无请求体。查询参数：namespace（str，默认值为 llm-d-monitoring）和 cluster_id（str，可选）。

响应：返回一个 ClusterStackStatusResponse。

{
  "cluster": {
    "context": "kind-test",
    "reachable": true,
    "platform": "kubernetes"
  },
  "namespace": "llm-d-monitoring",
  "release": {
    "name": "llmd",
    "status": "deployed",
    "chart": "kube-prometheus-stack-65.0.0",
    "revision": 2
  },
  "status": "ready",
  "message": "ready",
  "components": [
    {
      "name": "grafana",
      "status": "ready",
      "kind": "workload",
      "ready": 1,
      "desired": 1,
      "source": "llmd",
      "diagnostics": []
    }
  ],
  "active_operation_id": null,
  "observed_at": "2026-09-23T08:00:00Z",
  "stale": false
}

运行集群监控技术栈预检​

在不安装任何内容的情况下运行集群监控技术栈的预检检查。在开始安装 Prometheus/Grafana 技术栈之前使用它。

POST /api/v1/monitoring/cluster-stack/installations/preflight

请求：可选查询参数 cluster_id（str）。请求体字段为 namespace、mode、enable_tls 和 reinstall。

{
  "namespace": "llm-d-monitoring",
  "mode": "central",
  "enable_tls": false,
  "reinstall": false
}

响应：返回一个 ClusterStackPreflightResponse，包含阻断性和非阻断性检查项。

{
  "allowed": true,
  "status": "ready",
  "checks": [
    {
      "name": "cluster-reachable",
      "passed": true,
      "message": "cluster is reachable",
      "blocking": true
    }
  ],
  "warnings": [],
  "command_preview": [
    "/path/to/llm-d/guides/recipes/observability/install-prometheus-grafana.sh",
    "--namespace",
    "llm-d-monitoring"
  ]
}

安装集群监控技术栈​

安装或重新安装集群级别的监控技术栈。当需要部署或修复 Prometheus/Grafana 集群监控时使用。

POST /api/v1/monitoring/cluster-stack/installations

请求：可选请求头 Idempotency-Key（str）和可选查询参数 cluster_id（str）。请求体字段为 namespace、mode、enable_tls 和 reinstall。

{
  "namespace": "llm-d-monitoring",
  "mode": "central",
  "enable_tls": false,
  "reinstall": true
}

响应：返回已排队安装或重新安装操作对应的 ClusterStackOperationResponse。

{
  "operation_id": "cluster-stack-op-123",
  "kind": "install",
  "status": "queued",
  "phase": "queued",
  "namespace": "llm-d-monitoring",
  "started_at": "2026-09-23T08:10:00Z",
  "finished_at": null,
  "exit_code": null,
  "logs": [],
  "error": null
}

列出部署监控状态​

列出集群中每个部署的监控状态。使用此接口可以发现哪些执行已安装、启用或处于不健康的可观测性状态。

GET /api/v1/monitoring/deployments

请求：无请求体。必需查询参数：cluster_id（str）。

响应：返回集群级别的部署监控状态，每个执行命名空间对应一个条目。

{
  "cluster_id": "cluster-123",
  "cluster_reachable": true,
  "stack_ready": true,
  "items": [
    {
      "execution_id": "deploy-exec-001",
      "namespace": "llm-d-run-001",
      "cluster_reachable": true,
      "stack_ready": true,
      "status": "enabled",
      "enabled": true,
      "epp_service": {
        "name": "demo-epp",
        "labels": {
          "app.kubernetes.io/name": "demo-epp"
        },
        "service_account": "demo-epp"
      },
      "servicemonitors": ["llm-d-prism-epp-monitor"],
      "podmonitors": ["llm-d-prism-modelserver-monitor"],
      "message": "monitoring enabled"
    }
  ]
}

获取部署监控状态​

获取某个部署执行的监控状态，可选择按集群 id 限定范围。

GET /api/v1/monitoring/deployments/{execution_id}

请求：无请求体。路径参数：execution_id（str）。可选查询参数：cluster_id（str）。

响应：返回单个部署监控状态对象。

{
  "execution_id": "deploy-exec-001",
  "namespace": "llm-d-run-001",
  "cluster_reachable": true,
  "stack_ready": true,
  "status": "enabled",
  "enabled": true,
  "epp_service": {
    "name": "demo-epp",
    "labels": {
      "app.kubernetes.io/name": "demo-epp"
    },
    "service_account": "demo-epp"
  },
  "servicemonitors": ["llm-d-prism-epp-monitor"],
  "podmonitors": ["llm-d-prism-modelserver-monitor"],
  "message": "monitoring enabled"
}

管理部署监控资源​

安装、启用、禁用或卸载某个部署执行的监控资源。

POST /api/v1/monitoring/deployments/{execution_id}/{action}

请求：无请求体。路径参数：execution_id（str）和 action（str，取值为 install、enable、disable 或 uninstall 之一）。可选查询参数：cluster_id（str）。

响应：在所请求的操作完成后，返回与前述相同形状的部署监控状态。

{
  "execution_id": "deploy-exec-001",
  "namespace": "llm-d-run-001",
  "cluster_reachable": true,
  "stack_ready": true,
  "status": "disabled",
  "enabled": false,
  "epp_service": {
    "name": "demo-epp",
    "labels": {
      "app.kubernetes.io/name": "demo-epp"
    },
    "service_account": "demo-epp"
  },
  "servicemonitors": [],
  "podmonitors": [],
  "message": "monitoring disabled"
}

获取 GPU 驱动状态​

获取集群中当前 GPU 驱动的安装状态，包括就绪情况和访问模式。

GET /api/v1/monitoring/gpu-driver/status

请求：无请求体。查询参数：access_mode（"dra" | "plugin"，默认值为 dra）、cluster_id（str，可选）以及 hardware（str，可选——已注册的硬件配置文件 id，例如 intel-xpu；当只注册了一个驱动提供方时可省略）。

响应：返回一个 GpuDriverStatusResponse。

{
  "access_mode": "dra",
  "installed": true,
  "ready": true,
  "cluster_reachable": true,
  "message": "Intel GPU DRA driver is installed and ready."
}

安装 GPU 驱动技术栈​

为所选访问模式安装 Lens 所期望的 GPU 驱动/设备插件技术栈。

POST /api/v1/monitoring/gpu-driver/install

请求：可选查询参数 cluster_id（str）和 hardware（str，已注册的硬件配置文件 id；当只注册了一个驱动提供方时可省略）。请求体字段：access_mode（"dra" | "plugin"）。

{
  "access_mode": "dra"
}

响应：返回一个 GpuDriverInstallResponse。

{
  "access_mode": "dra",
  "applied": true,
  "message": "Applied the Intel GPU DRA driver manifests. It may take a few minutes for pods to become ready."
}

获取部署性能分析流程图​

查询由 Prometheus 支撑的 GPU 空闲/利用率流程图（flow-map），用于特定的部署执行。

GET /api/v1/monitoring/profiling/flow-map

请求：无请求体。必需查询参数：execution_id（str）。可选查询参数：cluster_id（str）。

响应：返回一个包含组件和边（edge）指标的 FlowMapResponse。

{
  "execution_id": "deploy-exec-001",
  "namespace": "llm-d-run-001",
  "prometheus_reachable": true,
  "message": null,
  "components": [
    {
      "role": "epp",
      "label": "EPP",
      "present": true,
      "instances": [
        {
          "name": "demo-epp-5d7d8c9b6f-abcde",
          "request_rate": 1.8,
          "queue_length": 0.2,
          "prefill_inflight": 0.1,
          "decode_inflight": 0.1
        }
      ],
      "request_rate": 1.8,
      "queue_length": 0.2,
      "process_time_ms": 18.4
    },
    {
      "role": "decode",
      "label": "Decode",
      "present": true,
      "instances": [
        {
          "name": "modelserver-decode-0",
          "request_rate": 1.7,
          "output_token_rate": 82.0,
          "kv_cache_usage_perc": 64.5
        }
      ],
      "request_rate": 1.7,
      "output_token_rate": 82.0,
      "kv_cache_usage_perc": 64.5
    }
  ],
  "edges": [
    {
      "id": "epp->decode",
      "source": "epp",
      "target": "decode",
      "request_rate": 1.7,
      "success_request_rate": 1.7,
      "failed_request_rate": 0.0,
      "input_token_rate": 41.0,
      "output_token_rate": 82.0
    }
  ]
}

还存在用于安装预检、操作状态和已解析链接的其他加速器端点；详见 OpenAPI 参考文档。

还存在用于操作状态以及已解析 Grafana/Prometheus 链接的其他 cluster-stack 端点；详见 OpenAPI 参考文档。

完整的请求/响应模式请参见 FastAPI OpenAPI schema（使用 npm run docs:api 重新生成）。

共享的监控行为​

监控服务共享命令 JSON 解析、Service 链接查找、Prometheus 查询传输以及操作运行时机制。下方的现有 Python 入口点和 REST 请求/响应契约保持不变；领域错误、安装阶段、DAO 记录和验证回调仍归属于各自的加速器或 cluster-stack 服务。