NVIDIA vGPU 切分虚拟化

需要把单张 NVIDIA GPU 切分给多个 pod 共享使用（显存/算力切分）时，部署 HAMi vGPU 方案的步骤

部署安装 / GPU与异构算力

vGPUvgpuGPU虚拟化GPU切分HAMi第四范式nvidia.com/vgpuVGPU_RESOURCEdevicememoryscalinghami-schedulerdevice-pluginGPU共享GPU分片prometheus监控

NVIDIA vGPU 切分虚拟化（HAMi）

CubeStudio 采用第四范式开源的 HAMi 作为 vGPU 虚拟化方案（CUDA 层拦截），对单张 NVIDIA GPU 做切分共享。平台侧配置为 VGPU_RESOURCE（{"vgpu":"nvidia.com/vgpu"}，install/docker/config.py:1217）与 VGPU_DRIVE_TYPE = "vgpu"（install/docker/config.py:1223，注释标注「第四范式解决方案」）；调度侧读取在 myapp/utils/py/py_k8s.py:69-70。

部署步骤

下载 HAMi chart 包：

wget https://githubfast.com/Project-HAMi/HAMi/releases/download/v2.8.0/hami-2.8.0.tgz

用 helm template 渲染出 vgpu.yaml：

helm template vgpu hami \
  --set resourceName=nvidia.com/vgpu \
  --set scheduler.kubeScheduler.imageTag=v1.28.15 \
  --set version=v2.8.0 \
  --set scheduler.overwriteEnv="false" \
  -n kube-system > vgpu.yaml

说明：resourceName=nvidia.com/vgpu 与平台 VGPU_RESOURCE 中的资源名保持一致。scheduler.kubeScheduler.imageTag 需与集群 k8s 版本匹配。仓库内已提供渲染好的样例：install/kubernetes/gpu/vgpu/vgpu.yaml（HAMi 2.8.0），以及按 k8s 版本区分的 vgpu-k8s1.21.yaml、vgpu-k8s1.25.yaml。

修改 vgpu.yaml

对渲染出的 vgpu.yaml 做以下调整：

关闭显存超分，只做切分：将 "devicememoryscaling": 1（即不做显存虚拟化超分，仅做分隔）。该字段在仓库样例中位于 install/kubernetes/gpu/vgpu/vgpu.yaml:50。
节点选择器：将 nodeSelector 改为 vgpu: "true"（仅在打了该标签的节点上启用 vGPU）。
命名空间：添加 namespace: kube-system。
服务暴露类型：服务暴露类型改为 type: ClusterIP，并去掉 nodePort。
type: NodePort 类型的服务改为 ClusterIP，同时注释掉 externalTrafficPolicy: Local。

接入 Prometheus 监控

为 vgpu-hami-scheduler 服务添加注释，将「调度量」等信息同步到 Prometheus：

  annotations:
    prometheus.io/scrape: "true"
    prometheus.io/port: '9395'
    prometheus.io/path: /metrics

为 vgpu-hami-device-plugin-monitor 服务添加注释，将「pod 实际使用情况」信息同步到 Prometheus：

  annotations:
    prometheus.io/scrape: "true"
    prometheus.io/port: '9394'
    prometheus.io/path: /metrics

说明：上述服务名与端口与仓库样例一致——vgpu-hami-scheduler 暴露 9395、vgpu-hami-device-plugin-monitor 暴露 9394（见 install/kubernetes/gpu/vgpu/vgpu.yaml 中对应的 Service 定义）。

Bug 修复：补充 RBAC 权限

为 vgpu-hami-scheduler 角色添加 volumeattachments 权限：

  # 添加 volumeattachments 权限
  - apiGroups: ["storage.k8s.io"]
    resources: ["volumeattachments"]
    verbs: ["get", "list", "watch"]

平台侧调度机制

用户在 Notebook / Pipeline / 推理服务中申请小数卡（如 0.5）时，平台按 VGPU_DRIVE_TYPE 转换为对应的 K8s 资源请求（myapp/utils/py/py_k8s.py:1258-1272）：

驱动类型	资源转换（申请 N 卡，0<N<1）	方案
`vgpu`（默认）	`nvidia.com/gpumem-percentage: N×100` + `nvidia.com/gpucores: N×100`	HAMi，显存与算力按百分比切分
`mgpu`	Pod 注解 `tencent.com/vcuda-core-limit: N×100`	腾讯 vcuda（GPU Manager）方案（`py_k8s.py:1427`）
其他自定义类型	按 `VGPU_RESOURCE` 映射的资源名申请 `N×10`	预留扩展

0 卡隔离：申请 0 卡的容器会注入 GPU_NONE 环境变量（可见 GPU 置空），防止 GPU 镜像看到并占用节点全部卡；
独占模式（申请 ≥1 整卡）：走 gpu: "true" 节点选择，调度尽量聚集，避免卡碎片化。

监控指标样例

HAMi 接入 Prometheus 后的核心指标（完整样例见仓库 install/kubernetes/gpu/vgpu/metric.txt）：

# 每张卡已分配的算力核数（百分比）
GPUDeviceCoreAllocated{deviceidx="0",deviceuuid="GPU-xxxx",nodeid="...",zone="vGPU"} 90
# 每张卡的算力上限
GPUDeviceCoreLimit{...}

全部配置参考

所有配置项参考 HAMi 官方中文文档：https://github.com/Project-HAMi/HAMi/blob/v2.7.1/docs/config_cn.md

最后更新 2026-07-15完整文档以官方仓库为准：GitHub Wiki