Jimmy Song – HAMi 手册：Kubernetes GPU 资源管理与调度实战

AI 基础设施的 GPU 管理挑战

Jimmy Song — Thu, 04 Jun 2026 08:13:49 +0000

AI 工作负载正在改变基础设施对计算资源的消费方式。当 GPU 成为 AI 集群中最昂贵也最稀缺的资源时，传统的调度方式已经无法胜任。

引言：当 AI 遇见 Kubernetes

过去几年，AI 工作负载经历了从实验到生产的关键转变。大语言模型、图像生成、推荐系统，这些应用无一例外地依赖 GPU 加速。企业 Kubernetes 集群中 GPU 的占比正在快速攀升，但 Kubernetes 的调度能力并没有跟上这一变化。

考虑一个真实场景：一家 AI 公司拥有一个 100 节点的集群，其中 20 个节点配备 GPU。集群上同时运行着模型训练、在线推理、模型评估和开发调试任务。平台团队面对的核心问题是，如何让有限的 GPU 服务尽可能多的工作负载？

这不是一个简单的运维问题。它涉及调度语义、资源抽象和多厂商设备管理等多个层面。

Kubernetes 的 GPU 调度局限

围绕 CPU/Memory 设计的调度器

Kubernetes 的调度器围绕 CPU、内存和 Pod 数量设计，核心抽象是“资源请求”（Requests）和“资源上限”（Limits）。这套机制对 CPU 和内存非常有效，它们是可分割的、可超卖的、可精确计量的。

但 GPU 完全不同。GPU 有显存、有算力核心、有 NVLink 拓扑、有 PCIe 带宽，这些维度无法用一个标量来表示。

GPU 作为不透明设备

Kubernetes 通过 Device Plugin 机制支持 GPU，但它只做了一件事：把整张 GPU 卡作为一个不可分割的设备分配给 Pod。

# Kubernetes 原生方式：独占整张 GPU
apiVersion: v1
kind: Pod
metadata:
 name: llm-inference
spec:
 containers:
 - name: inference
 image: llm-serving:latest
 resources:
 limits:
 nvidia.com/gpu: 1 # 必须申请整张 GPU

这段配置说明了一切，nvidia.com/gpu: 1 意味着这个 Pod 独占一张完整的 GPU。无论它只用了 2GB 显存还是全部 80GB，无论算力只用了 10% 还是跑满，这张卡都不会再分配给其他 Pod。

真实代价

假设一个集群有 8 张 NVIDIA A100（80GB），每张约 15,000 美元，总硬件投入约 12 万美元。在原生调度模式下：

场景	GPU 需求	实际占用	利用率
LLaMA 推理（7B 模型）	14GB 显存，10% 算力	整张 A100	~18%
ResNet 评估	4GB 显存，5% 算力	整张 A100	~5%
Jupyter 开发环境	2GB 显存，间歇性使用	整张 A100	<5%

一张价值 15,000 美元的 A100，可能只被一个用了 2GB 显存的 Jupyter Notebook 独占。这不是个别现象，而是 AI 集群中的常态。

GPU 利用率低的根因分析

GPU 利用率低不是监控问题，而是调度问题。 在深入理解这个论断之前，我们需要分场景分析。

推理任务：显存占用高但计算空闲

在线推理是 GPU 集群中资源浪费最严重的场景。以一个 LLaMA-7B 的推理服务为例：

模型加载阶段：
 - 加载模型权重到 GPU 显存：约 14GB
 - GPU 利用率：短暂峰值后回落

推理服务阶段：
 - 显存占用：14GB（持续）
 - 计算利用率：5-30%（取决于请求 QPS）
 - 空闲时段：显存仍被占用，算力完全空闲

推理服务的特点决定了它的资源使用模式，显存是常驻的，但计算是间歇性的。在独占模式下，这张 GPU 剩余的 66GB 显存和 70% 的算力被完全浪费。

训练任务：静态分配与动态负载不匹配

模型训练看起来应该能充分利用 GPU，但实际情况更复杂：

数据预处理阶段 GPU 闲置，等待 CPU 完成 ETL
小模型微调只用了 GPU 的一部分能力
多轮训练的间隙评估、检查点保存期间 GPU 空闲
训练收敛后期计算密度远低于初始阶段

静态的整卡分配无法适应训练过程中的资源波动。

开发环境：大量闲置但被独占的 GPU

AI 研究人员的开发环境是 GPU 资源的“黑洞”：

研究员启动一个 Jupyter Notebook，加载 GPU 运行时
大部分时间在写代码、查资料、调试逻辑，GPU 完全空闲
但 GPU 被这个会话独占，其他人都无法使用
下班后，Notebook 可能还开着，GPU 继续被独占

一个 50 人的 AI 团队，可能需要 50 张 GPU 来满足开发需求，但任何时刻的实际利用率可能不到 10%。

根因总结

图 5: GPU 利用率低下的根因

异构算力的管理困境

多厂商设备的现实

越来越多的 AI 基础设施需要面对异构加速器：

NVIDIA GPU：A100、H100、L40S、RTX4090 等
华为昇腾 NPU：Ascend 910B 等
寒武纪 MLU ：MLU370 等
海光 DCU：Z100 等
摩尔线程 GPU：MTTS4000 等

在地缘政治和技术主权的背景下，“国产替代”已成为许多企业的战略要求。这意味着一个集群可能同时包含 NVIDIA 和国产加速器。

各自为战的 Device Plugin

每个加速器厂商都提供了自己的 Kubernetes Device Plugin：

NVIDIA → nvidia.com/gpu
华为昇腾 → ascend.com/npu
寒武纪 → cambricon.com/mlu
海光 → hygon.com/dcu

每个 Device Plugin 使用不同的资源名称、不同的配置方式、不同的监控接口。对于平台团队来说，这意味着：

没有统一的资源视图：无法回答“集群里还有多少可用的加速器资源？”
没有统一的调度策略：每个厂商需要独立配置调度规则
没有统一的运维流程：升级、监控、故障排查各不相同
没有统一的应用接口：工作负载需要针对不同厂商分别适配

# 为 NVIDIA GPU 配置的工作负载
apiVersion: v1
kind: Pod
metadata:
 name: inference-nvidia
spec:
 containers:
 - name: app
 resources:
 limits:
 nvidia.com/gpu: 1

---
# 为昇腾 NPU 配置的工作负载，完全不同的资源名称和配置方式
apiVersion: v1
kind: Pod
metadata:
 name: inference-ascend
spec:
 containers:
 - name: app
 resources:
 limits:
 ascend.com/npu: 1

两份配置，两种语义，两套运维流程。当集群中有三种甚至四种加速器时，管理复杂度呈指数级增长。

缺乏一致的资源视图

在异构集群中，一个简单的资源盘点都需要逐厂商查询：

# 查看 NVIDIA GPU 资源
kubectl get nodes -o custom-columns=NAME:.metadata.name,NVIDIA:.status.allocatable.nvidia\\.com/gpu

# 查看昇腾 NPU 资源
kubectl get nodes -o custom-columns=NAME:.metadata.name,ASCEND:.status.allocatable.ascend\\.com/npu

# 没有统一命令能告诉你：集群中总共有多少加速器算力可用？

我们需要什么？

面对上述挑战，AI 基础设施需要一个 GPU 感知的资源管理层。具体来说，它应该提供以下能力：

GPU 感知的资源管理

系统需要理解 GPU 的多维资源模型，显存、算力核心、设备数量都是可独立调度的维度。工作负载应该能够精确表达“我需要 8GB 显存和 30% 算力”，而不是被迫申请整张 GPU。

显存和算力的独立调度

不同工作负载对 GPU 的需求维度不同：

推理任务主要需要显存（加载模型权重）
训练任务主要需要算力（前向/反向传播）
评估任务两者都需要，但量级较小

一个理想的系统应该允许显存和算力独立分配，让不同需求的工作负载能够互补地共享同一张 GPU。

异构设备的统一抽象

平台团队需要一套统一的资源抽象来管理所有加速器：

理想状态：
 统一的资源名称（如 nvidia.com/gpu）
 统一的调度语义（显存、算力、设备数量）
 统一的运维接口（监控、日志、故障排查）
 统一的应用体验（工作负载无需关心底层硬件）

零应用改动的接入方式

最重要的是，这些能力应该对上层应用透明。AI 工程师不应该需要学习新的 SDK 或修改模型代码。他们只需要在 Pod 的 resources.limits 中声明需要的 GPU 资源，就像声明 CPU 和内存一样自然。

图 6: GPU 资源管理需求的演进

小结

本章从 AI 基础设施的实际需求出发，分析了 GPU 管理面临的三大挑战：

Kubernetes 调度局限：原生调度器只能整卡分配 GPU，无法按显存和算力精细调度
GPU 利用率低下：推理、训练、开发环境中大量 GPU 资源被浪费，根因是调度粒度太粗
异构设备管理困难：多厂商加速器各自为战，缺乏统一的资源抽象和调度语义

这三个问题的共同指向是：Kubernetes 需要一个 GPU 感知的资源管理平面，它能够理解 GPU 的多维资源模型，支持显存和算力的独立调度，并为异构设备提供统一抽象。

下一章将介绍 HAMi 项目，一个 CNCF Sandbox 项目，正是为了解决这些问题而生。

HAMi 项目概览

Jimmy Song — Thu, 04 Jun 2026 08:13:53 +0000

HAMi 将 Kubernetes 变成一个 GPU 感知的控制平面，让 AI 工作负载能够按需获取 GPU 资源，而不需要独占整张显卡。

什么是 HAMi

HAMi 是一个 CNCF Sandbox 项目，定位为 GPU Resource Control Plane for Kubernetes。它的核心使命是将 Kubernetes 变成一个 GPU 感知的资源管理平台，让 AI 工作负载能够以显存、算力或设备数量为单位精细地获取 GPU 资源。

一句话概括：HAMi turns Kubernetes into a GPU-aware control plane for AI workloads.

HAMi 不是一个 GPU 驱动，不是 CUDA 的替代品，也不是一个模型服务框架。它专注于一个精确的定位，在 Kubernetes 调度层面解决 GPU 资源的管理和分配问题。

图 3: HAMi 在 Kubernetes 生态中的定位

核心能力

加速器共享

HAMi 允许将一张物理 GPU 切分为多个逻辑单元，分配给不同的工作负载。支持三种维度的资源分配：

按显存分配指定工作负载可使用的显存上限
按算力分配指定工作负载可使用的 GPU 计算核心比例
按设备数量分配指定工作负载可见的 GPU 设备数

apiVersion: v1
kind: Pod
metadata:
 name: ai-inference
spec:
 containers:
 - name: inference
 image: tensorflow-serving:latest
 resources:
 limits:
 nvidia.com/gpu: 3 # 使用 3 个 GPU 设备
 nvidia.com/gpumem: 4000 # 每个设备 4000MB 显存

这个 Pod 使用 3 个 GPU 设备，每个设备分配 4000MB 显存。

资源隔离

每个工作负载的显存和算力使用都被限制在配额范围内：

显存隔离超过配额的显存分配请求会被拒绝，防止一个工作负载耗尽整张 GPU 的显存
算力隔离通过底层机制限制每个工作负载的 GPU 计算时间占比
故障隔离一个工作负载的异常不会影响共享同一 GPU 的其他工作负载

设备感知调度

HAMi 的调度器扩展（Scheduler Extender）能够感知 GPU 的硬件拓扑和设备属性：

拓扑感知优先将 Pod 调度到 NVLink 互联的 GPU 上，提升多卡通信性能
类型感知区分不同型号的 GPU（如 A100 与 T4），按需匹配
策略调度支持 binpack（紧凑装箱）、spread（分散部署）等策略
自定义调度通过 Node Selector、Affinity 等标准 K8s 语义灵活控制

异构统一管理

HAMi 为不同厂商的加速器提供统一的资源抽象：

厂商	设备类型	资源标识	支持状态
NVIDIA	GPU	nvidia.com/gpu	稳定支持
华为昇腾	NPU	huawei.com/Ascend910B3	稳定支持
寒武纪	MLU	cambricon.com/vmlu	稳定支持
海光	DCU	hygon.com/dcunum	稳定支持
摩尔线程	GPU	mthreads.com/vgpu	稳定支持
昆仑芯	XPU	kunlunxin.com/vxpu	稳定支持

表 3: HAMi 支持的异构加速器

无论底层硬件是什么，工作负载都使用统一的资源配置方式。平台团队可以用一套流程管理所有厂商的设备，更多厂商与资源名示例见“异构设备支持”章节。

零应用改造

HAMi 的接入不需要修改应用代码。工作负载使用标准的 Kubernetes 资源声明即可启用 GPU 共享：

# 无需修改应用代码，只需在 resources 中声明
resources:
 limits:
 nvidia.com/gpu: 3 # 使用 3 个 GPU 设备
 nvidia.com/gpumem: 4000 # 4000MB 显存

对于已有的使用 nvidia.com/gpu 的工作负载，HAMi 通过 Mutating Webhook 自动转换资源请求，实现无缝迁移。

生产就绪

HAMi 提供完整的生产环境支持：

Prometheus：指标 GPU 利用率、显存使用、调度延迟等核心指标
WebUI：可视化查看 GPU 资源分配和使用情况
HelmChart：一键安装和升级
事件增强调度：决策、资源分配等关键事件可追踪
多租户支持：通过 Namespace 和 ResourceQuota 实现团队级别的资源配额

应用场景

AI 推理服务：多模型共享 GPU

推理场景是 HAMi 最典型的应用。一个在线服务平台通常需要同时部署多个模型，每个模型的资源需求远低于一张完整 GPU。

实际案例：一个 AI 平台需要同时部署 6 个推理模型（文本分类、图像识别、语音转写等），每个模型需要 8-12GB 显存。在传统模式下需要 6 张 GPU，使用 HAMi 后只需要 2 张 A100（80GB）。

# 模型 A：12GB 显存，20% 算力
apiVersion: apps/v1
kind: Deployment
metadata:
 name: text-classifier
spec:
 replicas: 2
 template:
 spec:
 containers:
 - name: server
 image: text-classifier:latest
 resources:
 limits:
 nvidia.com/gpu: 1 # 使用 1 个 GPU
 nvidia.com/cores: 20 # 20% 算力
 nvidia.com/gpumem: 12000 # 12GB 显存

训练与推理混合部署

在同一集群中混合运行训练和推理任务，最大化 GPU 利用率：

训练任务：在非高峰期使用更多 GPU 资源
推理任务：保持稳定的在线服务
弹性调度：根据实际负载动态调整资源分配

企业 AI 平台：多团队共享

大型企业中多个 AI 团队共享 GPU 集群，需要公平、高效的资源分配：

团队 A（NLP）：运行大语言模型微调
团队 B（视觉）：运行目标检测训练
团队 C（推荐）：运行推荐模型推理
团队 D（研究）：运行实验性模型

HAMi 通过精细的资源分配和隔离，确保每个团队都能获得公平的 GPU 资源，同时最大化集群整体利用率。

主权 AI 基础设施：国产加速器支持

在需要国产化替代的场景中，HAMi 提供了统一的异构管理能力：

同时管理 NVIDIA GPU 和昇腾 NPU
工作负载无需针对不同硬件分别适配
可以制定调度策略，将特定工作负载优先调度到国产加速器
渐进式替代，无需一次性迁移所有工作负载

AI 云服务：GPU-as-a-Service

云服务商和 MLOps 平台可以使用 HAMi 构建 GPU 即服务：

将物理 GPU 切分为多个逻辑单元，按需出租
精确计量每个用户的 GPU 资源使用量
支持弹性伸缩，根据负载自动调整 GPU 分配

与其他方案对比

vs 原生 Kubernetes Device Plugin

维度	原生 Device Plugin	HAMi
资源粒度	整卡	显存/算力/设备数
共享能力	不支持	原生支持
多厂商统一	各自独立	统一抽象
调度策略	无 GPU 感知	拓扑/类型/策略感知
应用改动	无	无

vs NVIDIA MIG (Multi-Instance GPU)

维度	NVIDIA MIG	HAMi
硬件要求	仅 A100/H100 等 Ampere+	支持更广泛的 GPU 型号
切分粒度	固定配额（1g.5gb、2g.10gb 等）	灵活配额（任意显存和算力组合）
多厂商	仅 NVIDIA	多厂商统一
动态调整	需要重启实例	支持动态分配
配置复杂度	需要手动配置 MIG Profile	标准 Kubernetes 资源声明

vs 云厂商 GPU 虚拟化

维度	云厂商方案	HAMi
部署位置	仅限特定云平台	任意 Kubernetes 集群
厂商锁定	强锁定	无锁定
成本	按云厂商定价	开源免费
灵活性	受限于云厂商能力	完全可控
异构支持	通常仅支持该云提供的 GPU	多厂商统一支持

vs GPU 时间片方案

维度	时间片方案	HAMi
隔离性	弱（时间片切换）	强（显存和算力硬隔离）
可预测性	差（性能波动大）	好（配额保障）
显存隔离	通常不支持	支持
适用场景	低负载容忍度高	生产级工作负载

社区与生态

HAMi 是 CNCF Sandbox 项目，拥有活跃的开源社区：

GitHub：https://github.com/project-hami/hami
官方文档：https://project-hami.io/

作为 CNCF Sandbox 项目，HAMi 遵循云原生社区的最佳实践，包括开放的治理流程、清晰的贡献指南和透明的路线图规划。

小结

本章介绍了 HAMi 项目的核心定位和能力：

定位：GPU Resource Control Plane for Kubernetes，CNCF Sandbox 项目
核心能力：加速器共享、资源隔离、设备感知调度、异构统一管理、零应用改造、生产就绪
应用场景：AI 推理服务、训练推理混合、企业 AI 平台、主权 AI 基础设施、AI 云服务
方案优势：相比原生 Device Plugin、MIG、云厂商方案和 GPU 时间片，HAMi 在灵活性、多厂商支持和生产就绪度方面具有显著优势

下一章将进入动手实践环节，带你完成 HAMi 的安装和第一个工作负载的部署。

快速开始

Jimmy Song — Mon, 26 Jan 2026 00:00:00 +0800

本章将带你完成 HAMi 的完整部署流程，从安装到运行第一个 AI 应用，约需要 30 分钟。

安装 HAMi

1. 添加 Helm 仓库

# 添加 HAMi Helm 仓库
helm repo add hami-charts https://project-hami.github.io/hami-charts
helm repo update

# 查看可用的 Chart 版本
helm search repo hami-charts/hami

2. 创建命名空间

# 创建 HAMi 命名空间
kubectl create namespace hami-system

# 验证命名空间创建成功
kubectl get namespace hami-system

3. 安装 HAMi

# 使用默认配置安装
helm install hami hami-charts/hami -n hami-system

# 查看安装状态
kubectl get pods -n hami-system

预期输出：

NAME READY STATUS RESTARTS AGE
hami-device-plugin-nvidia-xxxxx 1/1 Running 0 2m
hami-scheduler-xxxxxxxxx-xxxxx 1/1 Running 0 2m
hami-vgpu-monitor-nvidia-xxxxx 1/1 Running 0 2m

4. 验证安装

# 检查所有组件是否正常运行
kubectl get pods -n hami-system

# 检查 HAMi Scheduler 服务
kubectl get svc -n hami-system

# 查看安装日志
kubectl logs -n hami-system -l app=hami-scheduler --tail=50

5. 检查 GPU 资源

安装成功后，GPU 节点应该注册了 HAMi 的资源：

# 查看节点上的 HAMi GPU 资源
kubectl describe node <gpu-node> | grep hami.io

预期输出：

Capacity:
 hami.io/gpu-memory: 16250
 nvidia.com/gpu: 100
Allocatable:
 hami.io/gpu-memory: 16250
 nvidia.com/gpu: 100

运行第一个 vGPU 应用

示例 1：简单的 CUDA 应用

创建一个使用 vGPU 的简单 CUDA 应用：

# cuda-vector-add.yaml
apiVersion: v1
kind: Pod
metadata:
 name: cuda-vector-add
spec:
 containers:
 - name: cuda-vector-add
 image: nvidia/cuda:12.2-base-ubuntu22.04
 command: ["sh", "-c"]
 args:
 - |
 apt-get update && \
 apt-get install -y cuda-samples-12-2 && \
 cuda-install-samples-12.2.sh --sbin=/usr/local/cuda/bin && \
 /usr/local/cuda/samples/1_Utilities/vectorAdd/vectorAdd
 resources:
 limits:
 # 使用 4 个 GPU 设备
 nvidia.com/gpu: 4
 # 4GB 显存
 nvidia.com/gpumem: 4000
 volumeMounts:
 - name: cuda-libs
 mountPath: /usr/local/cuda
 volumes:
 - name: cuda-libs
 emptyDir: {}
 restartPolicy: OnFailure

部署应用：

# 部署 Pod
kubectl apply -f cuda-vector-add.yaml

# 查看 Pod 状态
kubectl get pod cuda-vector-add

# 查看 Pod 日志
kubectl logs cuda-vector-add

预期输出：

[Vector addition of 50000 elements]
Copy input data from the host to the CUDA device
CUDA kernel launch with 196 blocks of 256 threads
Copy output data from the CUDA device to the host
Test PASSED

示例 2：TensorFlow 推理服务

创建一个 TensorFlow 推理服务：

# tf-inference.yaml
apiVersion: v1
kind: Pod
metadata:
 name: tf-inference
spec:
 containers:
 - name: tensorflow
 image: tensorflow/tensorflow:2.14.0-gpu
 command: ["python"]
 args:
 - |
 -c
 - |
 import tensorflow as tf
 print(f"TensorFlow Version: {tf.__version__}")
 print(f"GPUs Available: {len(tf.config.list_physical_devices('GPU'))}")
 # 创建简单的计算图
 a = tf.constant([[1.0, 2.0], [3.0, 4.0]])
 b = tf.constant([[5.0, 6.0], [7.0, 8.0]])
 c = tf.matmul(a, b)
 print(f"Result:\n{c.numpy()}")
 resources:
 limits:
 # 使用 3 个 GPU 设备
 nvidia.com/gpu: 3
 # 8GB 显存
 nvidia.com/gpumem: 8000
 restartPolicy: OnFailure

部署应用：

# 部署 Pod
kubectl apply -f tf-inference.yaml

# 查看 Pod 状态
kubectl get pod tf-inference

# 查看 Pod 日志
kubectl logs tf-inference

示例 3：多个 Pod 共享 GPU

创建三个共享同一 GPU 的 Pod：

# gpu-shared-apps.yaml
apiVersion: v1
kind: Pod
metadata:
 name: gpu-app-1
spec:
 containers:
 - name: app
 image: nvidia/cuda:12.2-base-ubuntu22.04
 command: ["nvidia-smi"]
 resources:
 limits:
 nvidia.com/gpu: 1 # 使用 1 个 GPU
 nvidia.com/gpumem: 4000 # 4GB 显存
 restartPolicy: Never

---
apiVersion: v1
kind: Pod
metadata:
 name: gpu-app-2
spec:
 containers:
 - name: app
 image: nvidia/cuda:12.2-base-ubuntu22.04
 command: ["nvidia-smi"]
 resources:
 limits:
 nvidia.com/gpu: 1 # 使用 1 个 GPU
 nvidia.com/gpumem: 4000 # 4GB 显存
 restartPolicy: Never

---
apiVersion: v1
kind: Pod
metadata:
 name: gpu-app-3
spec:
 containers:
 - name: app
 image: nvidia/cuda:12.2-base-ubuntu22.04
 command: ["nvidia-smi"]
 resources:
 limits:
 nvidia.com/gpu: 1 # 使用 1 个 GPU
 nvidia.com/gpumem: 4000 # 4GB 显存
 restartPolicy: Never

部署应用：

# 部署所有 Pod
kubectl apply -f gpu-shared-apps.yaml

# 查看所有 Pod 状态
kubectl get pods gpu-app-1 gpu-app-2 gpu-app-3

# 查看调度情况
kubectl describe pod gpu-app-1 | grep "Node:"

验证三个 Pod 都运行在同一个 GPU 节点上。3 个 Pod 各请求 1 个 GPU 和 4000MB 显存，只要节点有 1 张 12GB 以上的 GPU，就可以共享同一张物理 GPU。

监控 vGPU 使用情况

1. 查看 vGPU Monitor 指标

HAMi 提供了 Prometheus 指标：

# 端口转发到本地
kubectl port-forward -n hami-system svc/hami-vgpu-monitor-nvidia-service 41991:41991

# 访问指标
curl http://localhost:41991/metrics | grep vgpu

2. 使用 kubectl 插件查看资源使用

# 查看 Pod 的 GPU 使用情况
kubectl top pod gpu-app-1 --containers

# 查看节点的 GPU 使用情况
kubectl top node <gpu-node>

3. 查看 vGPU 分配情况

# 查看所有使用 GPU 的 Pod
kubectl get pods -A -o json | \
 jq '.items[] | select(.spec.containers[].resources.limits["nvidia.com/gpu"]) | \
 {name: .metadata.name, namespace: .metadata.namespace, gpu: .spec.containers[].resources.limits["nvidia.com/gpu"]}'

常见部署问题

问题 1：Pod 处于 Pending 状态

现象：

kubectl get pod cuda-vector-add
# NAME READY STATUS RESTARTS AGE
# cuda-vector-add 0/1 Pending 0 5m

排查：

# 查看 Pod 事件
kubectl describe pod cuda-vector-add

# 常见原因：
# 1. 资源不足
# 2. 调度器未就绪
# 3. 节点选择器不匹配

解决：

# 检查 HAMi Scheduler 是否运行
kubectl get pods -n hami-system | grep scheduler

# 检查节点资源
kubectl describe node <gpu-node> | grep hami.io

问题 2：Pod 启动失败

现象：

kubectl get pod cuda-vector-add
# NAME READY STATUS RESTARTS AGE
# cuda-vector-add 0/1 CrashLoopBackOff 5 10m

排查：

# 查看 Pod 日志
kubectl logs cuda-vector-add

# 查看 Device Plugin 日志
kubectl logs -n hami-system -l app=hami-device-plugin --tail=50

问题 3：GPU 资源未注册

现象：节点没有 hami.io 资源

排查：

# 检查 Device Plugin Pod
kubectl get pods -n hami-system | grep device-plugin

# 查看 Device Plugin 日志
kubectl logs -n hami-system -l app=hami-device-plugin

解决：

# 重启 Device Plugin
kubectl delete pod -n hami-system -l app=hami-device-plugin

卸载 HAMi

如果需要卸载 HAMi：

# 删除所有使用 HAMi 的 Pod
kubectl delete pods -A -l nvidia.com/gpu

# 卸载 Helm Chart
helm uninstall hami -n hami-system

# 删除命名空间
kubectl delete namespace hami-system

# 删除 Helm 仓库
helm repo remove hami-charts

小结

本章完成了 HAMi 的快速部署：

使用 Helm 安装 Hami
部署了三个示例应用
- CUDA 向量加法
- TensorFlow 推理
- 多 Pod 共享 GPU
学习了监控和故障排查方法

现在你已经成功运行了第一个 vGPU 应用！在下一部分，我们将深入学习 HAMi 的核心概念和工作原理。

参考资料

整体架构

Jimmy Song — Thu, 04 Jun 2026 08:13:37 +0000

HAMi 定位为 Kubernetes 的 GPU 资源控制平面，通过 Webhook、调度器扩展、设备插件和监控四大组件，构建了零侵入的 GPU 感知资源管理体系。

架构设计理念

HAMi 的架构设计遵循三个核心原则：

1.遵循 Kubernetes 扩展机制

HAMi 不修改任何 Kubernetes 核心代码，完全通过标准扩展点接入：

AdmissionWebhook：利用 Mutating Admission Webhook 拦截 Pod 创建请求
SchedulerExtender：通过 HTTP 接口扩展参与调度决策
DevicePlugin：基于 Kubernetes Device Plugin API 注册自定义资源
CRD + Informer：使用自定义资源描述设备状态

这意味着 HAMi 可以在任何标准 Kubernetes 集群上运行，无需定制构建。

2.四组件模型

HAMi 采用经典的四组件架构：

组件	运行形态	职责
Mutating Admission Webhook	Deployment	准入控制与 Pod 注入
Scheduler Extender	Deployment（多副本）	GPU 感知调度决策
Device Plugin	DaemonSet	设备发现、注册与分配
Monitor	DaemonSet	指标采集与暴露

3.零侵入式设计

HAMi 对用户工作负载零侵入：

用户只需在 Pod 的 resources 中声明 GPU 资源需求
不需要修改应用代码或容器镜像
不需要安装额外的运行时依赖
资源隔离通过底层库注入实现，对应用透明

整体架构图

图 9: HAMi 整体架构

架构要点解读：

Webhook 和 Scheduler Extender 以 Deployment 形式运行在控制平面，参与 Pod 的准入和调度决策
Device Plugin 和 Monitor 以 DaemonSet 形式运行在每个 GPU 节点，与硬件直接交互
各组件通过 Kubernetes 注解（Annotation） 协调工作，而非直接 RPC 调用

四大核心组件概述

Mutating Admission Webhook：准入控制与注入

Webhook 在 Pod 创建阶段拦截请求，执行以下操作：

# Webhook 处理逻辑概览
operations:
 - 资源类型转换（limits → requests）
 - 添加调度注解（标记 GPU 类型、资源需求）
 - 注入环境变量（CUDA_VISIBLE_DEVICES 等）
 - 设置 schedulerName 为 HAMi 调度器
 - 配额检查与资源合法性校验

Webhook 的关键在于“零侵入”，用户只需声明资源需求，Webhook 自动完成所有适配工作。

Scheduler Extender：Filter/Score/Bind 三段式调度

HAMi Scheduler Extender 通过 HTTP 接口扩展 Kubernetes 原生调度器：

图 10: 调度器三段式流程

Device Plugin：设备注册、发现、分配

Device Plugin 在每个 GPU 节点上以 DaemonSet 形式运行：

启动时通过 NVML 或厂商 SDK 发现物理 GPU，根据配置计算可分配资源，注册到 Kubelet
运行时通过ListAndWatch持续上报设备状态，响应 Allocate 请求完成设备分配
异常时检测设备故障，标记为 Unhealthy，通知 Kubelet 触发 Pod 迁移

Monitor：指标采集与暴露

Monitor 同样以 DaemonSet 形式运行，负责：

采集每个 Pod 的 GPU 显存使用量、算力利用率
以 Prometheus 指标格式暴露
支持通过 ServiceMonitor 自动接入 Prometheus

端到端数据流

以下是一个 Pod 从提交到运行的完整数据流：

图 11: 端到端数据流

步骤详解

步骤 1：用户提交 Pod

用户提交一个带有 GPU 资源声明的 Pod：

apiVersion: v1
kind: Pod
metadata:
 name: ai-inference
spec:
 containers:
 - name: inference
 image: tensorflow/serving:latest
 resources:
 limits:
 nvidia.com/gpu: 2 # 申请 2 个 GPU 设备
 nvidia.com/gpumem: 4000 # 申请 4000 MB 显存

步骤 2：Webhook 拦截与注入

API Server 在准入控制阶段将 Pod 发送给 HAMi Webhook。Webhook 完成以下处理：

解析容器中的 nvidia.com/gpu、nvidia.com/gpumem 等自定义资源
将 limits 复制到 requests（Kubernetes 要求二者一致）
添加调度注解，如设备类型、核心策略
将 schedulerName 设置为 HAMi 调度器名称

步骤 3：调度器 Filter

kube-scheduler 通过 HTTP 将候选节点列表发送给 HAMi Scheduler Extender 的 /filter 端点。调度器检查每个节点是否满足 GPU 资源需求，过滤掉不满足的节点。

步骤 4：调度器 Score

kube-scheduler 调用 /score 端点，HAMi 调度器根据配置的策略（binpack/spread/topology-aware）对可行节点打分。

步骤 5：调度器 Bind

kube-scheduler 调用 /bind 端点，HAMi 调度器执行绑定操作：

获取节点级锁，防止并发冲突
计算具体的设备分配方案
将分配结果写入 Pod 注解
调用 Kubernetes API 执行绑定
释放锁

步骤 6：DevicePlugin 分配

Kubelet 在创建容器之前，通过 gRPC 调用 Device Plugin 的 Allocate 方法。Device Plugin 读取 Pod 注解中的分配信息，准备容器运行时环境（设备路径、环境变量、挂载点）。

步骤 7：容器启动

Kubelet 使用 Device Plugin 返回的配置创建容器，容器内应用通过标准 CUDA 接口使用 GPU。

步骤 8：Monitor 采集

Monitor 持续采集 GPU 使用指标，以 Prometheus 格式暴露供监控系统消费。

注解协议

HAMi 各组件之间通过 Kubernetes 注解（Annotation）传递信息，这是组件间解耦的核心机制。

调度器写入分配注解

调度器在 Bind 阶段将分配决策写入 Pod 注解：

metadata:
 annotations:
 # 调度器写入的分配注解
 hami.io/bind-node: "gpu-node-01"
 hami.io/device-bind-phase: "allocating"
 hami.io/device-allocated: |
 [
 {
 "type": "NVIDIA",
 "uuid": "GPU-abc123-def456",
 "memory": 4000,
 "cores": 30,
 "numa": 0
 }
 ]

设备插件读取注解完成分配

Device Plugin 在 Allocate 阶段读取这些注解：

// 伪代码：Device Plugin 读取分配注解
func (p *Plugin) Allocate(ctx context.Context, req *pluginapi.AllocateRequest) (*pluginapi.AllocateResponse, error) {
 // 从 Pod 注解中读取调度器的分配决策
 allocation := ParseAllocationAnnotation(pod.Annotations["hami.io/device-allocated"])

 for _, device := range allocation {
 // 准备设备路径
 devicePaths = append(devicePaths, device.DevicePath)
 // 准备环境变量
 envs["CUDA_VISIBLE_DEVICES"] = device.UUID
 }

 return &AllocateResponse{
 Envs: envs,
 Mounts: mounts,
 Devices: devices,
 }, nil
}

注解编码/解码规范

注解键	写入方	读取方	格式
`hami.io/device-allocated`	Scheduler	Device Plugin	JSON 数组
`hami.io/device-bind-phase`	Scheduler	Monitor	字符串（allocating/allocated）
`hami.io/bind-node`	Scheduler	Monitor	节点名称
`hami.io/gpu-type`	Webhook	Scheduler	设备类型标识
`hami.io/node-scheduler-policy`	Webhook	Scheduler	调度策略名称
`hami.io/core-policy`	Webhook	Scheduler	核心分配策略

注解值中的 JSON 使用紧凑编码，不包含换行和多余空格，以避免 Kubernetes Annotation 大小限制（262144 字节）问题。

高可用架构

生产环境中 HAMi 的每个组件都需要考虑高可用：

多副本调度器 + 领导者选举

图 12: 调度器高可用架构

调度器通过 Kubernetes Lease 对象实现领导者选举：

同一时刻只有一个 Scheduler 副本处理调度请求
Leader 通过定期续约 Lease 保持活跃状态
Leader 失效后，Standby 副本在秒级内接管

# 高可用调度器配置
scheduler:
 replicas: 3
 leaderElect:
 enabled: true
 leaseDuration: 15s
 renewDeadline: 10s
 retryPeriod: 2s
 affinity:
 podAntiAffinity:
 requiredDuringSchedulingIgnoredDuringExecution:
 - labelSelector:
 matchLabels:
 app: hami-scheduler
 topologyKey: kubernetes.io/hostname

节点级锁保障并发一致性

在 Bind 阶段，即使只有一个 Leader 调度器在运行，也可能同时处理多个 Pod 的绑定请求。HAMi 使用节点级锁保障同一节点上的资源分配不发生冲突：

// 伪代码：节点级锁机制
func (s *Scheduler) Bind(nodeName string, pod *v1.Pod) error {
 // 获取节点级互斥锁
 lock := s.lockManager.Acquire(nodeName)
 defer lock.Release()

 // 读取节点当前资源使用
 nodeUsage := s.cache.GetNodeUsage(nodeName)

 // 检查资源是否仍然充足
 if !nodeUsage.Fit(pod) {
 return ErrInsufficientResources
 }

 // 计算分配方案并写入注解
 allocation := s.computeAllocation(nodeUsage, pod)
 patchPodAnnotation(pod, allocation)

 // 执行绑定
 return s.client.CoreV1().Pods(pod.Namespace).Bind(ctx, bind, metav1.CreateOptions{})
}

DaemonSet 设备插件

Device Plugin 和 Monitor 以 DaemonSet 形式部署，天然具备节点级高可用：

每个 GPU 节点运行一个 Device Plugin 副本
Pod 异常退出后 Kubernetes 自动重启
单节点故障不影响其他节点的设备分配

# DaemonSet 部署示意
devicePlugin:
 enabled: true
 updateStrategy:
 type: RollingUpdate
 rollingUpdate:
 maxUnavailable: "10%"
 tolerations:
 - key: "nvidia.com/gpu"
 operator: "Exists"
 effect: "NoSchedule"

Webhook 高可用

Webhook 通常部署 2 个以上副本，配合 Service 进行负载均衡：

webhook:
 replicas: 2
 service:
 type: ClusterIP
 port: 443
 affinity:
 podAntiAffinity:
 preferredDuringSchedulingIgnoredDuringExecution:
 - weight: 100
 podAffinityTerm:
 labelSelector:
 matchLabels:
 app: hami-webhook
 topologyKey: kubernetes.io/hostname

Webhook 失效时的保护机制：

配置 failurePolicy: Fail 确保准入失败时拒绝请求（安全优先）
如需更高的可用性，可配置 failurePolicy: Ignore（跳过准入检查，但可能影响调度正确性）

小结

本章从全局视角介绍了 HAMi 的整体架构：

设计理念遵循 Kubernetes 扩展机制、四组件模型、零侵入式设计
四大组件 Webhook（准入注入）、SchedulerExtender（调度决策）、Device Plugin（设备管理）、Monitor（指标采集）
端到端数据流从 Pod 提交到容器运行的完整链路
注解协议组件间通过 Kubernetes Annotation 解耦协作
高可用架构多副本调度器 + 领导者选举、节点级锁、DaemonSet 自愈

在接下来的章节中，我们将逐一深入每个组件的实现细节，从调度器开始。

调度器

Jimmy Song — Thu, 04 Jun 2026 08:13:58 +0000

HAMi Scheduler Extender 是 GPU 资源控制平面的决策引擎，通过 Filter、Score、Bind 三段式流程为每个 Pod 选择最优的 GPU 节点和设备。

调度器架构

Scheduler Extender 模式

Kubernetes 原生调度器不理解 GPU 资源的切分与共享模型。HAMi 通过 Scheduler Extender 模式扩展调度能力：kube-scheduler 在调度过程中通过 HTTP 调用 HAMi 的 Extender 端点，将 GPU 相关的决策委托给 HAMi。

图 7: Scheduler Extender 架构

HTTP 路由

HAMi Scheduler Extender 暴露以下 HTTP 端点：

路由	方法	调用时机	功能
`/filter`	POST	kube-scheduler 过滤阶段	筛选满足 GPU 资源需求的节点
`/score`	POST	kube-scheduler 评分阶段	对可行节点进行 GPU 相关评分
`/bind`	POST	kube-scheduler 绑定阶段	执行 Pod 到节点的绑定
`/webhook`	POST	准入控制阶段	辅助 Webhook 处理
`/healthz`	GET	健康检查	返回组件健康状态
`/readyz`	GET	就绪检查	返回组件就绪状态

节点缓存与 Informer 同步

调度器维护一个内存中的节点资源缓存，通过 Kubernetes Informer 实时同步：

// 伪代码：节点缓存结构
type NodeCache struct {
 sync.RWMutex
 nodes map[string]*NodeInfo
}

type NodeInfo struct {
 Name string
 Devices []DeviceInfo // 节点上的 GPU 设备列表
 Allocatable DeviceUsage // 可分配资源总量
 Used DeviceUsage // 已分配资源量
 Pods []PodAllocation // 已调度到该节点的 Pod
}

// Informer 事件处理
func (c *NodeCache) OnNodeUpdate(oldNode, newNode *v1.Node) {
 c.Lock()
 defer c.Unlock()

 info := parseNodeDevices(newNode)
 c.nodes[newNode.Name] = info
}

func (c *NodeCache) OnPodUpdate(oldPod, newPod *v1.Pod) {
 c.Lock()
 defer c.Unlock()

 if newPod.Spec.NodeName != "" {
 node := c.nodes[newPod.Spec.NodeName]
 node.updateAllocation(newPod)
 }
}

Informer 通过 Watch 机制监听 Node 和 Pod 的变化事件，确保缓存与集群实际状态保持一致，避免每次调度请求都查询 API Server。

Filter 阶段

Filter 阶段的核心任务是：从候选节点列表中筛选出满足 Pod GPU 资源需求的节点。

收集 Pod 资源请求

// 解析 Pod 的 GPU 资源请求
func parsePodGPURequest(pod *v1.Pod) *GPURequest {
 req := &GPURequest{}
 for _, container := range pod.Spec.Containers {
 limits := container.Resources.Limits
 if val, ok := limits[HamivGPU]; ok {
 req.Count += int(val.Value())
 }
 if val, ok := limits[HamivGPUMem]; ok {
 req.Memory += int(val.Value())
 }
 if val, ok := limits[HamivGPUCores]; ok {
 req.Cores += int(val.Value())
 }
 }
 return req
}

遍历候选节点

对每个候选节点，调度器执行一系列检查：

// Filter 阶段伪代码
func Filter(args *extender.ExtenderArgs) (*extender.ExtenderFilterResult, error) {
 pod := args.Pod
 nodes := args.Nodes.Items

 gpuReq := parsePodGPURequest(pod)
 // 无 GPU 请求，跳过过滤
 if gpuReq.Count == 0 {
 return &extender.ExtenderFilterResult{Nodes: args.Nodes}, nil
 }

 feasibleNodes := []v1.Node{}
 failedNodes := map[string]string{}

 for _, node := range nodes {
 nodeInfo := cache.GetNode(node.Name)
 if nodeInfo == nil {
 failedNodes[node.Name] = "节点缓存未找到"
 continue
 }

 // 检查 1：设备类型匹配
 if !matchDeviceType(pod, nodeInfo) {
 failedNodes[node.Name] = "设备类型不匹配"
 continue
 }

 // 检查 2：GPU 资源余量
 if !checkGPUFit(nodeInfo, gpuReq) {
 failedNodes[node.Name] = "GPU 资源不足"
 continue
 }

 // 检查 3：NUMA 亲和性
 if !checkNUMAAffinity(pod, nodeInfo) {
 failedNodes[node.Name] = "NUMA 亲和性不满足"
 continue
 }

 // 检查 4：UUID 白黑名单
 if !checkUUIDFilter(pod, nodeInfo) {
 failedNodes[node.Name] = "UUID 过滤不通过"
 continue
 }

 // 检查 5：设备健康状态
 if !checkDeviceHealth(nodeInfo) {
 failedNodes[node.Name] = "设备不健康"
 continue
 }

 // 检查 6：配额检查
 if !checkQuota(pod.Namespace, gpuReq) {
 failedNodes[node.Name] = "命名空间配额超限"
 continue
 }

 feasibleNodes = append(feasibleNodes, node)
 }

 return &extender.ExtenderFilterResult{
 Nodes: &v1.NodeList{Items: feasibleNodes},
 FailedNodes: failedNodes,
 }, nil
}

设备类型匹配

Pod 可以通过注解指定需要的 GPU 型号：

metadata:
 annotations:
 hami.io/gpu-type: "NVIDIA-A100-SXM4-40GB"

调度器在 Filter 阶段比对注解中的设备类型与节点实际设备，排除不匹配的节点。

NUMA 检查

对于需要多 GPU 的工作负载（如分布式训练），NUMA 拓扑影响数据传输性能：

func checkNUMAAffinity(pod *v1.Pod, node *NodeInfo) bool {
 numaHint := pod.Annotations["hami.io/numa-hint"]
 if numaHint == "" {
 return true // 未指定 NUMA 要求，跳过
 }

 requiredNUMA, _ := strconv.Atoi(numaHint)
 for _, device := range node.Devices {
 if device.NUMANode == requiredNUMA && device.HasEnoughResources(pod) {
 return true
 }
 }
 return false
}

UUID 白黑名单

通过注解控制 Pod 可以使用或排除特定的 GPU 设备：

metadata:
 annotations:
 # 白名单：只使用指定的 GPU
 hami.io/gpu-uuid-include: "GPU-abc123,GPU-def456"
 # 黑名单：排除指定的 GPU
 hami.io/gpu-uuid-exclude: "GPU-xyz789"

健康状态与配额检查

健康状态调度器从 Device Plugin 上报的设备状态中获取健康信息，排除不健康的设备
配额检查结合 Kubernetes ResourceQuota 检查命名空间级别的 GPU 资源配额

Score 阶段

Score 阶段对 Filter 通过的节点进行评分，影响最终的节点选择。

binpack/spread/topology-aware 策略

HAMi 支持三种评分策略，可在全局或 Pod 级别配置：

图 8: 评分策略对比

评分算法

评分的核心是计算每个节点上 GPU 资源的"匹配度"：

// 评分阶段伪代码
func Score(args *extender.ExtenderArgs) (map[string]int64, error) {
 pod := args.Pod
 nodes := args.Nodes.Items
 policy := getScorePolicy(pod) // 从注解或全局配置获取

 scores := map[string]int64{}
 for _, node := range nodes {
 nodeInfo := cache.GetNode(node.Name)
 switch policy {
 case "binpack":
 scores[node.Name] = binpackScore(nodeInfo, pod)
 case "spread":
 scores[node.Name] = spreadScore(nodeInfo, pod)
 case "topology-aware":
 scores[node.Name] = topologyScore(nodeInfo, pod)
 }
 }
 return scores, nil
}

binpack 策略评分

优先将 Pod 调度到 GPU 使用率高的节点，最大化单节点资源利用率：

func binpackScore(node *NodeInfo, pod *v1.Pod) int64 {
 var totalScore int64
 for _, device := range node.Devices {
 // 设备使用率越高，分数越高
 memUsage := float64(device.UsedMemory) / float64(device.TotalMemory)
 coreUsage := float64(device.UsedCores) / float64(device.TotalCores)
 usageScore := int64((memUsage * 0.6 + coreUsage * 0.4) * 100)
 totalScore += usageScore
 }
 return totalScore / int64(len(node.Devices))
}

适用场景：资源受限环境，希望尽量少用节点。

spread 策略评分

优先将 Pod 调度到 GPU 使用率低的节点，实现负载均衡：

func spreadScore(node *NodeInfo, pod *v1.Pod) int64 {
 var totalScore int64
 for _, device := range node.Devices {
 memUsage := float64(device.UsedMemory) / float64(device.TotalMemory)
 coreUsage := float64(device.UsedCores) / float64(device.TotalCores)
 // 使用率越低，分数越高
 usageScore := int64((1 - (memUsage*0.6 + coreUsage*0.4)) * 100)
 totalScore += usageScore
 }
 return totalScore / int64(len(node.Devices))
}

适用场景：多 GPU 分布式训练，需要设备间高速通信。

topology-aware 策略评分

考虑 GPU 拓扑结构，优先选择同一 NUMA 节点或 PCIe 域内的设备：

func topologyScore(node *NodeInfo, pod *v1.Pod) int64 {
 var score int64

 // NUMA 亲和性评分（权重 50%）
 numaScore := calculateNUMAAffinity(node, pod)
 score += numaScore * 50

 // PCIe 距离评分（权重 30%）
 pcieScore := calculatePCIEDistance(node, pod)
 score += pcieScore * 30

 // P2P 互访能力评分（权重 20%）
 p2pScore := calculateP2PCapability(node, pod)
 score += p2pScore * 20

 return score
}

适用场景：多 GPU 分布式训练，需要设备间高速通信。

节点级 vs 卡级策略

HAMi 支持两层评分策略：

# 全局配置
scheduler:
 policy:
 nodeSchedulerPolicy: binpack  # 节点级策略
 gpuSchedulerPolicy: spread  # 卡级策略（在同一节点的多张卡之间）

节点级策略决定选择哪个节点
卡级策略在选定节点后，决定选择哪张 GPU 卡

Bind 阶段

Bind 阶段将 Pod 绑定到选定的节点，并记录设备分配决策。

绑定流程

图 9: Bind 阶段流程

节点加锁

func (s *Scheduler) Bind(args *extender.ExtenderBindingArgs) (*extender.ExtenderBindingResult, error) {
 // 1. 获取节点级互斥锁
 lock := s.lockManager.Acquire(args.NodeName)
 defer lock.Release()

 // 2. 读取节点当前资源状态
 nodeInfo := s.cache.GetNode(args.NodeName)

 // 3. 计算具体的设备分配方案
 pod, _ := s.client.CoreV1().Pods(args.PodNamespace).Get(ctx, args.PodName, metav1.GetOptions{})
 gpuReq := parsePodGPURequest(pod)
 allocation := nodeInfo.ComputeAllocation(gpuReq)

 if allocation == nil {
 return nil, fmt.Errorf("资源不足以分配")
 }

 // 4. 写入分配注解
 allocJSON, _ := json.Marshal(allocation)
 patch := map[string]interface{}{
 "metadata": map[string]interface{}{
 "annotations": map[string]string{
 "hami.io/device-allocated": string(allocJSON),
 "hami.io/device-bind-phase": "allocating",
 "hami.io/bind-node": args.NodeName,
 },
 },
 }
 patchPod(s.client, pod.Name, pod.Namespace, patch)

 // 5. 执行绑定
 bind := &v1.Binding{
 ObjectMeta: metav1.ObjectMeta{Name: args.PodName, UID: args.PodUID},
 Target: v1.ObjectReference{Kind: "Node", Name: args.NodeName},
 }
 err := s.client.CoreV1().Pods(args.PodNamespace).Bind(ctx, bind, metav1.CreateOptions{})

 // 6. 更新本地缓存
 if err == nil {
 s.cache.UpdateAllocation(args.NodeName, allocation)
 }

 return &extender.ExtenderBindingResult{}, err
}

释放锁

锁在 defer lock.Release() 中自动释放，无论绑定成功或失败。这确保：

绑定成功后，其他 Pod 的调度请求能看到最新的资源状态
绑定失败后，资源不会被永久锁定

配额管理

命名空间 ResourceQuota 集成

HAMi 支持通过 Kubernetes 原生 ResourceQuota 限制命名空间级别的 GPU 资源使用：

apiVersion: v1
kind: ResourceQuota
metadata:
 name: gpu-quota
 namespace: ai-team
spec:
 hard:
 nvidia.com/gpu: "10" # 最多 10 个 GPU 设备
 nvidia.com/gpumem: "40000" # 最多 40000 MB 显存
 nvidia.com/cores: "200" # 最多 200% 算力

按命名空间限制设备内存总量

调度器在 Filter 阶段检查当前命名空间已使用的 GPU 资源总量：

func checkQuota(namespace string, req *GPURequest) bool {
 quota := getResourceQuota(namespace)

 used := getNamespaceGPUUsage(namespace)
 if used.Memory+req.Memory > quota.Memory {
 return false // 显存配额超限
 }
 if used.Count+req.Count > quota.Count {
 return false // GPU 数量配额超限
 }
 return true
}

防止资源滥用

配额管理的设计目标：

公平分配多个团队共享集群时，防止单个团队垄断 GPU 资源
成本控制通过配额限制各命名空间的 GPU 使用上限
自助服务团队在配额范围内自主调度，无需管理员干预

事件增强

Pod 事件中显示成功/失败节点数量

调度器在调度完成后，会在 Pod 事件中记录详细的调度信息：

# 查看调度事件
kubectl describe pod ai-inference

# Events:
# Type Reason From Message
# ---- ------ ---- -------
# Normal Scheduled hami-scheduler Successfully assigned ai-inference to gpu-node-01
# Filter: 3/5 nodes feasible, 2 insufficient GPU memory
# Score: node-01=85, node-02=72, node-03=68
# Device: GPU-abc123 (4000MB/30cores allocated)

标准化错误码

错误码	含义	建议操作
`InsufficientGPUMemory`	节点显存不足	扩容 GPU 节点或降低显存请求
`InsufficientGPUCores`	节点算力不足	扩容或降低算力请求
`DeviceTypeMismatch`	设备类型不匹配	检查注解中的设备类型
`DeviceUnhealthy`	设备不健康	检查 GPU 硬件状态
`QuotaExceeded`	命名空间配额超限	联系管理员调整配额
`NUMAUnsatisfied`	NUMA 亲和性不满足	调整 NUMA 拓扑要求
`UUIDFiltered`	UUID 白黑名单过滤	检查 UUID 注解配置

日志分级

调度器使用 klog 分级日志：

# v4 级别：节点摘要
kubectl logs -n hami-system hami-scheduler-xxx -v=4
# I0101 "Filter result" node="gpu-01" feasible=true score=85
# I0101 "Filter result" node="gpu-02" feasible=false reason="InsufficientGPUMemory"

# v5 级别：设备细节
kubectl logs -n hami-system hami-scheduler-xxx -v=5
# I0101 "Device fit check" node="gpu-01" device="GPU-abc123" freeMem=8000 reqMem=4000 fit=true
# I0101 "Device fit check" node="gpu-01" device="GPU-def456" freeMem=2000 reqMem=4000 fit=false

领导者选举与节点锁

领导者选举

多副本调度器通过 Kubernetes Lease 实现领导者选举：

// 领导者选举配置
leaderelection.LeaderElectionConfig{
 Lock: &resourcelock.LeaseLock{
 LeaseMeta: metav1.ObjectMeta{
 Name: "hami-scheduler-leader",
 Namespace: "hami-system",
 },
 Client: client.CoordinationV1(),
 LockConfig: resourcelock.ResourceLockConfig{
 Identity: hostname,
 },
 },
 LeaseDuration: 15 * time.Second,
 RenewDeadline: 10 * time.Second,
 RetryPeriod: 2 * time.Second,
 Callbacks: leaderelection.LeaderCallbacks{
 OnStartedLeading: runScheduler,
 OnStoppedLeading: func() {
 klog.Info("Leader election lost, shutting down")
 os.Exit(1)
 },
 },
}

节点锁实现

type NodeLockManager struct {
 locks map[string]*sync.Mutex
 mu sync.Mutex
}

func (m *NodeLockManager) Acquire(nodeName string) *sync.Mutex {
 m.mu.Lock()
 defer m.mu.Unlock()

 if _, ok := m.locks[nodeName]; !ok {
 m.locks[nodeName] = &sync.Mutex{}
 }
 m.locks[nodeName].Lock()
 return m.locks[nodeName]
}

节点锁保障：即使同一个 Leader 调度器并行处理多个 Pod 的 Bind 请求，同一节点的资源分配操作也是串行执行的。

调度器配置

以下是通过 Helm values.yaml 配置调度器的完整示例：

# values.yaml - 调度器配置
scheduler:
 enabled: true
 nameOverride: "hami-scheduler"

 # 镜像配置
 image:
 repository: projecthami/hami
 tag: v2.5.0
 pullPolicy: IfNotPresent

 # 副本数（建议 >= 2）
 replicas: 3

 # 调度策略
 policy:
 nodeSchedulerPolicy: binpack  # binpack | spread
 gpuSchedulerPolicy: binpack  # binpack | spread | topology-aware

 # 资源超卖配置
 overcommit:
 enabled: true
 deviceMemoryScaling: 1.0 # 显存超卖比例
 deviceCoreScaling: 1.0 # 算力超卖比例

 # 领导者选举
 leaderElect:
 enabled: true
 leaseDuration: 15s
 renewDeadline: 10s
 retryPeriod: 2s

 # 节点缓存同步
 cache:
 resyncPeriod: 300s  # 全量同步周期
 watchTimeout: 30s  # Watch 超时

 # 资源限制
 resources:
 requests:
 cpu: 500m
 memory: 512Mi
 limits:
 cpu: "2"
 memory: 2Gi

 # 优先级
 priorityClassName: "system-cluster-critical"

 # 反亲和性
 affinity:
 podAntiAffinity:
 requiredDuringSchedulingIgnoredDuringExecution:
 - labelSelector:
 matchLabels:
 app: hami-scheduler
 topologyKey: kubernetes.io/hostname

 # 容忍度
 tolerations:
 - key: "node-role.kubernetes.io/control-plane"
 operator: "Exists"
 effect: "NoSchedule"

Scheduler Extender 注册

kube-scheduler 需要配置 Extender 以调用 HAMi：

# kube-scheduler 配置（ConfigMap）
apiVersion: v1
kind: ConfigMap
metadata:
 name: scheduler-config
 namespace: kube-system
data:
 scheduler-config.yaml: |
 apiVersion: kubescheduler.config.k8s.io/v1
 kind: KubeSchedulerConfiguration
 profiles:
 - schedulerName: hami-scheduler
 extenders:
 - urlPrefix: "http://hami-scheduler.hami-system:9000"
 filterVerb: "/filter"
 scoreVerb: "/score"
 bindVerb: "/bind"
 weight: 1
 managedResources:
 - name: nvidia.com/gpu
 - name: nvidia.com/gpumem
 - name: nvidia.com/cores

小结

本章详细介绍了 HAMi Scheduler Extender 的设计与实现：

架构：SchedulerExtender 模式，HTTP 路由，节点缓存与 Informer 同步
Filter：阶段设备类型匹配、资源余量检查、NUMA 亲和性、UUID 过滤、健康状态和配额检查
Score：阶段 binpack/spread/topology-aware 三种评分策略，节点级与卡级双层策略
Bind：阶段节点加锁、分配注解写入、绑定执行、锁释放
配额管理：命名空间 ResourceQuota 集成，防止资源滥用
事件增强：调度详情事件、标准化错误码、分级日志
高可用：领导者选举、节点级锁

在下一章中，我们将深入 Device Plugin 和设备抽象层的实现细节。

设备插件与设备抽象层

Jimmy Song — Thu, 04 Jun 2026 08:13:41 +0000

HAMi Device Plugin 是 GPU 资源控制平面的执行层，在每个 GPU 节点上管理设备的发现、注册、分配与健康检查，设备抽象层则为多厂商异构设备提供统一接口。

设备插件概述

Kubernetes Device Plugin API

Kubernetes Device Plugin 是一种标准的扩展机制，允许第三方硬件供应商将自定义资源（GPU、FPGA、高速网卡等）暴露给 Kubernetes 调度器。

Device Plugin 通过 gRPC 与 Kubelet 通信，遵循以下接口：

// Kubernetes Device Plugin gRPC 接口（简化）
service DevicePlugin {
 // 获取设备列表和状态（持续流式）
 rpc ListAndWatch(Empty) returns (stream ListAndWatchResponse);
 // 为容器分配设备
 rpc Allocate(AllocateRequest) returns (AllocateResponse);
 // 获取设备分配选项
 rpc GetDeviceAllocationOptions(DeviceAllocationOptionsRequest) returns (DeviceAllocationOptionsResponse);
}

HAMi 自研设备插件

HAMi 实现了自己的 Device Plugin，与 NVIDIA 官方 k8s-device-plugin 不兼容。二者不能同时运行在同一个节点上。

HAMi 自研设备插件的原因：

支持资源切分：官方插件只能整卡分配，HAMi 需要支持显存和算力的精细化切分
支持多厂商：官方插件仅支持 NVIDIA，HAMi 需要统一管理 NVIDIA、昇腾、寒武纪等设备
支持共享隔离：HAMi 需要注入底层库实现多 Pod 共享同一 GPU 时的资源隔离

DaemonSet 部署

Device Plugin 以 DaemonSet 形式部署，每个 GPU 节点运行一个实例：

apiVersion: apps/v1
kind: DaemonSet
metadata:
 name: hami-device-plugin
 namespace: hami-system
spec:
 selector:
 matchLabels:
 app: hami-device-plugin
 template:
 spec:
 hostNetwork: true
 hostPID: true
 containers:
 - name: device-plugin
 image: projecthami/hami:v2.5.0
 command: ["hami-device-plugin"]
 volumeMounts:
 - name: device-plugin
 mountPath: /var/lib/kubelet/device-plugins
 - name: dev
 mountPath: /dev
 securityContext:
 privileged: true
 volumes:
 - name: device-plugin
 hostPath:
 path: /var/lib/kubelet/device-plugins
 - name: dev
 hostPath:
 path: /dev
 nodeSelector:
 gpu: "true"

设备插件生命周期

图 5: Device Plugin 生命周期

启动流程

Device Plugin 的启动过程分为三个阶段：

1.加载配置

func (p *Plugin) LoadConfig() error {
 // 从 ConfigMap 加载设备配置
 config := &DeviceConfig{}
 config.NVIDIA.SplitCount = 10 // 每张 GPU 切分为 10 份
 config.NVIDIA.MemoryScaling = 1.0 // 显存缩放因子
 config.NVIDIA.MigStrategy = "single" // MIG 策略
 return nil
}

2.NVML 初始化

func (p *Plugin) InitNVML() error {
 if err := nvml.Init(); err != nil {
 return fmt.Errorf("NVML 初始化失败: %v", err)
 }
 count, err := nvml.GetDeviceCount()
 if err != nil {
 return fmt.Errorf("获取 GPU 数量失败: %v", err)
 }
 klog.Infof("检测到 %d 张 NVIDIA GPU", count)
 return nil
}

3.启动 gRPC 服务器

func (p *Plugin) Start() error {
 // 在 Kubelet device-plugin 目录下创建 Unix Socket
 socketPath := filepath.Join(devicePluginPath, "hami-gpu.sock")
 listener, err := net.Listen("unix", socketPath)

 server := grpc.NewServer()
 pluginapi.RegisterDevicePluginServer(server, p)

 go server.Serve(listener)

 // 注册到 Kubelet
 return p.RegisterWithKubelet()
}

设备发现与注册

使用 NVML 查询物理 GPU

func (p *NvidiaPlugin) DiscoverPhysicalGPUs() ([]PhysicalGPU, error) {
 count, err := nvml.GetDeviceCount()
 if err != nil {
 return nil, err
 }

 gpus := make([]PhysicalGPU, 0, count)
 for i := 0; i < count; i++ {
 handle, err := nvml.NewDeviceByIndex(uint(i))
 if err != nil {
 klog.Warningf("跳过 GPU %d: %v", i, err)
 continue
 }

 uuid, _ := handle.GetUUID()
 name, _ := handle.GetName()
 memory, _ := handle.GetMemoryInfo()
 pciBusID, _ := handle.GetPCIBusID()
 numa, _ := handle.GetNUMANode()

 gpu := PhysicalGPU{
 Index: i,
 UUID: uuid,
 Model: name,
 Memory: memory.Total,
 PCIBusID: pciBusID,
 NUMANode: numa,
 }
 gpus = append(gpus, gpu)

 klog.V(4).Infof("发现 GPU: index=%d uuid=%s model=%s memory=%dMB numa=%d",
 i, uuid, name, memory.Total/1024/1024, numa)
 }
 return gpus, nil
}

根据配置切分设备资源

HAMi 不预创建固定的切分设备，而是通过资源计数的方式注册可分配能力：

func (p *NvidiaPlugin) GenerateDeviceSpecs(gpus []PhysicalGPU, config *DeviceConfig) []*pluginapi.Device {
 var devices []*pluginapi.Device

 for _, gpu := range gpus {
 // 注册每个物理 GPU 的资源能力
 // Kubelet 通过资源名 nvidia.com/gpu 管理设备计数
 device := &pluginapi.Device{
 ID: gpu.UUID,
 Health: pluginapi.Healthy,
 }
 devices = append(devices, device)
 }

 // 通过节点注解上报详细的切分信息
 // 调度器读取注解获取每张卡的可用显存和算力
 return devices
}

注册到 Kubelet

func (p *Plugin) RegisterWithKubelet() error {
 conn, err := grpc.Dial(
 filepath.Join(devicePluginPath, "kubelet.sock"),
 grpc.WithInsecure(),
 )
 if err != nil {
 return err
 }
 defer conn.Close()

 client := pluginapi.NewRegistrationClient(conn)
 _, err = client.Register(context.Background(), &pluginapi.RegisterRequest{
 Version: pluginapi.Version,
 Endpoint: "hami-gpu.sock",
 ResourceName: "nvidia.com/gpu",
 })
 return err
}

资源分配（Allocate）

读取 Pod 分配注解

Device Plugin 在收到 Kubelet 的 Allocate 请求后，首先从 Pod 注解中读取调度器的分配决策：

func (p *Plugin) Allocate(ctx context.Context, req *pluginapi.AllocateRequest) (*pluginapi.AllocateResponse, error) {
 resp := &pluginapi.AllocateResponse{}

 for _, containerReq := range req.ContainerRequests {
 containerResp := &pluginapi.ContainerAllocateResponse{}

 // 从环境变量或 Pod 注解中获取分配信息
 allocation := p.getAllocationFromAnnotation()

 for _, device := range allocation.Devices {
 // 准备设备路径
 containerResp.Devices = append(containerResp.Devices,
 &pluginapi.DeviceSpec{
 HostPath: device.HostPath,
 ContainerPath: device.ContainerPath,
 Permissions: "mrw",
 },
 )

 // 注入环境变量
 containerResp.Envs["CUDA_VISIBLE_DEVICES"] = device.UUID
 containerResp.Envs["NVIDIA_VISIBLE_DEVICES"] = device.UUID

 // 配置显存限制
 if device.MemoryLimit > 0 {
 containerResp.Envs["CUDA_DEVICE_MEMORY_LIMIT"] =
 fmt.Sprintf("%d", device.MemoryLimit)
 }

 // 配置算力限制
 if device.CoreLimit > 0 {
 containerResp.Envs["CUDA_DEVICE_CORE_LIMIT"] =
 fmt.Sprintf("%d", device.CoreLimit)
 }
 }

 // 挂载 CUDA 运行时库和注入库
 containerResp.Mounts = append(containerResp.Mounts,
 &pluginapi.Mount{
 HostPath: "/usr/local/cuda",
 ContainerPath: "/usr/local/cuda",
 ReadOnly: true,
 },
 &pluginapi.Mount{
 HostPath: "/var/lib/hami/vgpu/lib",
 ContainerPath: "/usr/local/vgpu/lib",
 ReadOnly: true,
 },
 )

 resp.ContainerResponses = append(resp.ContainerResponses, containerResp)
 }

 return resp, nil
}

准备容器运行时环境

Allocate 返回的响应包含三类配置：

设备路径注入：

// /dev/nvidia* 设备节点
Devices: []*pluginapi.DeviceSpec{
 {HostPath: "/dev/nvidia0", ContainerPath: "/dev/nvidia0", Permissions: "mrw"},
 {HostPath: "/dev/nvidiactl", ContainerPath: "/dev/nvidiactl", Permissions: "mrw"},
 {HostPath: "/dev/nvidia-uvm", ContainerPath: "/dev/nvidia-uvm", Permissions: "mrw"},
}

环境变量注入：

Envs: map[string]string{
 "CUDA_VISIBLE_DEVICES": "GPU-abc123-def456",
 "NVIDIA_VISIBLE_DEVICES": "GPU-abc123-def456",
 "CUDA_DEVICE_MEMORY_LIMIT": "4000",
 "CUDA_DEVICE_CORE_LIMIT": "30",
}

挂载点注入：

Mounts: []*pluginapi.Mount{
 // CUDA 运行时
 {HostPath: "/usr/local/cuda/lib64", ContainerPath: "/usr/local/cuda/lib64", ReadOnly: true},
 // HAMi 注入库（实现资源隔离）
 {HostPath: "/var/lib/hami/vgpu/lib", ContainerPath: "/usr/local/vgpu/lib", ReadOnly: true},
 // GPU 驱动库
 {HostPath: "/usr/lib/x86_64-linux-gnu/libnvidia-ml.so", ContainerPath: "/usr/lib/x86_64-linux-gnu/libnvidia-ml.so", ReadOnly: true},
}

CDI 支持

Container Device Interface 规范

CDI（Container Device Interface）是容器运行时的设备注入标准，由容器运行时（containerd、CRI-O）直接处理设备注入，无需依赖 NVIDIA container runtime。

HAMi 支持 CDI 模式作为传统 Device Plugin 注入方式的替代方案。

CDI 设备生成与管理

// CDI 设备生成伪代码
func (p *Plugin) GenerateCDIDevices() ([]CDIDevice, error) {
 var cdiDevices []CDIDevice

 for _, gpu := range p.physicalGPUs {
 // 生成 CDI 设备描述符
 cdi := CDIDevice{
 Name: fmt.Sprintf("nvidia.com/gpu=%s", gpu.UUID),
 Type: "nvidia",
 DeviceSpecs: []DeviceSpec{
 {HostPath: fmt.Sprintf("/dev/nvidia%d", gpu.Index), Permissions: "mrw"},
 },
 Mounts: []MountSpec{
 {HostPath: "/usr/local/cuda/lib64", ContainerPath: "/usr/local/cuda/lib64"},
 {HostPath: "/var/lib/hami/vgpu/lib", ContainerPath: "/usr/local/vgpu/lib"},
 },
 Env: map[string]string{
 "CUDA_VISIBLE_DEVICES": gpu.UUID,
 },
 }
 cdiDevices = append(cdiDevices, cdi)
 }

 // 写入 CDI 规范文件
 return cdiDevices, writeCDISpec(cdiDevices)
}

CDI 模式的优势：

标准化遵循容器行业标准，不依赖特定运行时
简洁设备描述与容器运行时解耦
兼容性支持 containerd 1.7+ 和 CRI-O 1.25+

设备抽象层

HAMi 的设备抽象层为多厂商异构设备提供统一的编程接口，是支持多种 GPU/NPU 的核心设计。

经定义设备接口 Devices

// Devices 是所有设备后端必须实现的统一接口
type Devices interface {
 // 健康检查
 GetNodeDevices(node *v1.Node) ([]*DeviceInfo, error)

 // 节点清理（清理已终止 Pod 的设备占用）
 NodeClean(nodeName string) (*NodeUsage, error)

 // 获取资源名称
 ResourceName() string

 // 设备发现
 Discovery() ([]*DeviceInfo, error)

 // 获取节点级锁
 Lock(nodeName string) error

 // 释放节点级锁
 Unlock(nodeName string) error

 // 写入分配注解
 PatchPodAnnotations(pod *v1.Pod, annotations map[string]string) error

 // 评分
 ScoreNode(node *NodeUsage, policy string) int64

 // 检查资源是否满足需求
 Fit(devices []*DeviceInfo, request *GPURequest) bool
}

核心方法说明

方法	调用方	功能
`GetNodeDevices`	Scheduler	获取节点上的设备列表和状态
`NodeClean`	Scheduler	清理已终止 Pod 占用的设备资源
`ResourceName`	Scheduler/Plugin	返回注册的资源名（如 `nvidia.com/gpu`）
`Discovery`	Device Plugin	发现物理设备并生成设备列表
`Lock/Unlock`	Scheduler	获取/释放节点级互斥锁
`PatchPodAnnotations`	Scheduler	将分配决策写入 Pod 注解
`ScoreNode`	Scheduler	根据策略对节点评分
`Fit`	Scheduler	检查设备是否满足 Pod 资源请求

DeviceInfo 数据结构

// DeviceInfo 描述一个物理设备的信息
type DeviceInfo struct {
 ID string // 设备唯一标识（UUID）
 Type string // 设备类型（NVIDIA/Ascend/Cambricon/Hygon）
 Model string // 设备型号（A100/910B/...）
 Memory uint64 // 总显存（字节）
 Cores uint32 // 总算力核心数
 NUMANode int // NUMA 节点编号
 Health bool // 健康状态

 // 拓扑信息
 PCIBusID string // PCI 总线地址
 PCIE PCITopology // PCIe 拓扑信息

 // 资源使用
 UsedMemory uint64 // 已分配显存
 UsedCores uint32 // 已分配算力

 // 运行时信息
 Index int // 设备索引
 HostPath string // 设备路径
}

DeviceUsage 数据结构

// DeviceUsage 描述设备级别的资源使用情况
type DeviceUsage struct {
 DeviceID string // 设备 UUID
 DeviceType string // 设备类型
 Memory uint64 // 总显存
 UsedMemory uint64 // 已用显存
 Cores uint32 // 总算力
 UsedCores uint32 // 已用算力
 NUMANode int // NUMA 节点
 Healthy bool // 健康状态
}

// NodeUsage 描述节点级别的资源使用汇总
type NodeUsage struct {
 NodeName string
 Devices []DeviceUsage
 // 节点级别的聚合指标
 TotalMemory uint64
 UsedMemory uint64
 TotalCores uint32
 UsedCores uint32
}

类图

图 6: 设备抽象层类图

多厂商适配

NVIDIA GPU 适配

NVIDIA 是 HAMi 支持最完善的设备后端，使用 NVML（NVIDIA Management Library）进行设备管理：

type NvidiaDevices struct {
 config *NvidiaConfig
}

func (n *NvidiaDevices) Discovery() ([]*DeviceInfo, error) {
 count, _ := nvml.GetDeviceCount()
 devices := make([]*DeviceInfo, 0, count)

 for i := 0; i < count; i++ {
 handle, _ := nvml.NewDeviceByIndex(uint(i))
 uuid, _ := handle.GetUUID()
 name, _ := handle.GetName()
 mem, _ := handle.GetMemoryInfo()
 numa, _ := handle.GetNUMANode()

 devices = append(devices, &DeviceInfo{
 ID: uuid,
 Type: "NVIDIA",
 Model: name,
 Memory: mem.Total,
 NUMANode: numa,
 Health: true,
 })
 }
 return devices, nil
}

func (n *NvidiaDevices) ResourceName() string {
 return "nvidia.com/gpu"
}

华为昇腾 NPU 适配

type AscendDevices struct {
 config *AscendConfig
}

func (a *AscendDevices) Discovery() ([]*DeviceInfo, error) {
 // 使用华为 Ascend CL SDK 查询 NPU 设备
 count := acl.GetDeviceCount()
 devices := make([]*DeviceInfo, 0, count)

 for i := 0; i < count; i++ {
 info, _ := acl.GetDeviceInfo(i)
 devices = append(devices, &DeviceInfo{
 ID: info.UUID,
 Type: "Ascend",
 Model: info.Model, // e.g., "Ascend 910B"
 Memory: info.Memory,
 NUMANode: info.NUMA,
 Health: info.Healthy,
 })
 }
 return devices, nil
}

func (a *AscendDevices) ResourceName() string {
 return "hami.io/ascend"
}

新增设备后端只需实现统一接口

为 HAMi 添加新的设备后端（如 AMD GPU、Intel GPU），只需实现 Devices 接口：

// 新增设备后端的步骤：
// 1. 实现 Devices 接口
type NewVendorDevices struct {
 // 厂商特定字段
}

func (d *NewVendorDevices) Discovery() ([]*DeviceInfo, error) {
 // 使用厂商 SDK 发现设备
}

func (d *NewVendorDevices) ResourceName() string {
 return "hami.io/newvendor"
}

// 2. 在设备注册表中注册
func init() {
 RegisterDevice("newvendor", &NewVendorDevices{})
}

// 3. 通过 Helm 配置启用
// devicePlugin:
// newvendor:
// enabled: true

这种设计使得 HAMi 的设备支持范围可以持续扩展，而无需修改调度器或 Webhook 的核心逻辑。

设备插件配置

以下是通过 Helm values.yaml 配置设备插件的完整示例：

# values.yaml - 设备插件配置
devicePlugin:
 enabled: true
 nameOverride: "hami-device-plugin"

 # 镜像配置
 image:
 repository: projecthami/hami
 tag: v2.5.0
 pullPolicy: IfNotPresent

 # NVIDIA GPU 配置
 nvidia:
 enabled: true
 # 资源切分配置
 splitCount: 10 # 每张 GPU 的切分份数
 memoryScaling: 1.0 # 显存缩放因子（>1.0 为超卖）
 coreScaling: 1.0 # 算力缩放因子
 # MIG 策略
 migStrategy: "none" # none | single | mixed
 # GPU 计算模式
 computeMode: "Default" # Default | ExclusiveProcess | ExclusiveThread
 # 驱动配置
 driverRoot: "/run/nvidia/driver"
 # CDI 支持
 cdi:
 enabled: false
 vendor: "hami.io"
 class: "gpu"

 # 华为昇腾 NPU 配置
 ascend:
 enabled: false
 splitCount: 4
 memoryScaling: 1.0

 # 寒武纪 MLU 配置
 cambricon:
 enabled: false
 splitCount: 8
 memoryScaling: 1.0

 # 海光 DCU 配置
 hygon:
 enabled: false
 splitCount: 4
 memoryScaling: 1.0

 # DaemonSet 更新策略
 updateStrategy:
 type: RollingUpdate
 rollingUpdate:
 maxUnavailable: "10%"

 # 资源限制
 resources:
 requests:
 cpu: 100m
 memory: 128Mi
 limits:
 cpu: 500m
 memory: 512Mi

 # 容忍度
 tolerations:
 - key: "nvidia.com/gpu"
 operator: "Exists"
 effect: "NoSchedule"

 # 节点选择器
 nodeSelector:
 gpu: "true"

 # 健康检查
 livenessProbe:
 exec:
 command:
 - /bin/sh
 - -c
 - "test -S /var/lib/kubelet/device-plugins/hami-gpu.sock"
 initialDelaySeconds: 30
 periodSeconds: 10
 timeoutSeconds: 5

小结

本章详细介绍了 HAMi Device Plugin 和设备抽象层的设计与实现：

设备插件概述：基于 Kubernetes Device Plugin API，以 DaemonSet 形式运行在每个 GPU 节点
生命周期：Init→Register → ListAndWatch → Allocate 的完整状态机
设备发现与注册：通过 NVML 或厂商 SDK 发现物理设备，注册到 Kubelet
资源分配：读取调度器注解，准备设备路径、环境变量和挂载点
CDI：支持通过 Container Device Interface 标准化设备注入
设备抽象层：统一的Devices接口，DeviceInfo/DeviceUsage 数据结构
多厂商适配：NVIDIA、昇腾、寒武纪、海光等实现，新增后端只需实现统一接口

在下一章中，我们将深入 Webhook 与准入控制的工作机制。

Webhook 与准入控制

Jimmy Song — Thu, 04 Jun 2026 08:28:03 +0000

HAMi Mutating Admission Webhook 是 GPU 资源控制平面的准入守卫，在 Pod 创建阶段拦截请求，自动注入调度所需信息与运行时配置，实现用户零侵入的 GPU 资源管理体验。

Mutating Admission Webhook 概述

在 Pod 创建阶段拦截请求

Kubernetes 的准入控制（Admission Control）机制允许在对象持久化到 etcd 之前拦截和修改请求。HAMi 使用 Mutating Admission Webhook 在 Pod 创建和更新阶段进行拦截。

图 7: Webhook 在准入控制链中的位置

HAMi Webhook 职责：

解析 GPU 资源请求
转换 limits → requests
添加调度注解
注入环境变量
设置 schedulerName
配额检查

注入调度所需信息与运行时配置

Webhook 的核心价值在于"用户零感知"，用户只需声明 GPU 资源需求，Webhook 自动完成以下工作：

确保调度器能识别 GPU 资源请求
为调度器标记设备类型和策略偏好
设置正确的调度器名称
预检资源合法性

零侵入式设计

用户提交的 Pod 定义只需包含标准的资源声明：

# 用户提交的原始 Pod
apiVersion: v1
kind: Pod
metadata:
 name: ai-inference
spec:
 containers:
 - name: inference
 image: tensorflow/serving:latest
 resources:
 limits:
 nvidia.com/gpu: 2
 nvidia.com/gpumem: 4000

Webhook 自动补全后：

# Webhook 注入后的 Pod
apiVersion: v1
kind: Pod
metadata:
 name: ai-inference
 annotations:
 hami.io/gpu-type: "NVIDIA"
 hami.io/device-bind-phase: "pending"
 hami.io/node-scheduler-policy: "binpack"
spec:
 schedulerName: hami-scheduler
 containers:
 - name: inference
 image: tensorflow/serving:latest
 resources:
 limits:
 nvidia.com/gpu: 2
 nvidia.com/gpumem: 4000
 requests:
 nvidia.com/gpu: 2
 nvidia.com/gpumem: 4000

Webhook 工作流程

图 8: Webhook 工作流程

图 9: Webhook 工作流程

解码请求

func (wh *Webhook) Handle(admissionReview *admissionv1.AdmissionReview) *admissionv1.AdmissionResponse {
 // 解码 Pod 对象
 pod := &v1.Pod{}
 if err := json.Unmarshal(admissionReview.Request.Object.Raw, pod); err != nil {
 return admissionResponse(err)
 }

 // 检查是否包含 GPU 资源请求
 if !hasGPURequest(pod) {
 // 无 GPU 请求，直接放行
 return &admissionv1.AdmissionResponse{Allowed: true}
 }

 // 执行注入逻辑
 return wh.mutatePod(pod, admissionReview.Request)
}

校验 Pod

Webhook 首先检查 Pod 是否包含 HAMi 管理的自定义资源：

func hasGPURequest(pod *v1.Pod) bool {
 for _, container := range pod.Spec.Containers {
 resources := container.Resources
 // 检查 limits 和 requests
 for _, resMap := range []v1.ResourceList{resources.Limits, resources.Requests} {
 for name := range resMap {
 if strings.HasPrefix(string(name), "hami.io/") {
 return true
 }
 }
 }
 }
 return false
}

设备适配注入

Webhook 根据节点上安装的设备类型，为 Pod 注入相应的运行时配置：

func (wh *Webhook) mutatePod(pod *v1.Pod, req *admissionv1.AdmissionRequest) *admissionv1.AdmissionResponse {
 var patches []jsonpatch.JsonPatchOperation

 // 1. 资源类型转换
 patches = append(patches, ensureRequestsFromLimits(pod)...)

 // 2. 添加调度注解
 patches = append(patches, addSchedulingAnnotations(pod)...)

 // 3. 设置 schedulerName
 patches = append(patches, setSchedulerName(pod)...)

 // 4. 设备类型匹配与运行时类注入
 patches = append(patches, injectDeviceRuntime(pod)...)

 // 5. 优先级与核心策略注入
 patches = append(patches, injectCorePolicy(pod)...)

 // 6. 配额检查
 if err := checkQuota(pod); err != nil {
 return admissionResponse(err)
 }

 // 构建响应
 patchBytes, _ := json.Marshal(patches)
 return &admissionv1.AdmissionResponse{
 Allowed: true,
 Patch: patchBytes,
 PatchType: func() *admissionv1.PatchType {
 pt := admissionv1.PatchTypeJSONPatch
 return &pt
 }(),
 }
}

主要功能

资源类型转换（limits → requests）

Kubernetes 要求 Pod 的 requests 和 limits 必须同时设置。用户通常只声明 limits，Webhook 自动补全 requests：

func ensureRequestsFromLimits(pod *v1.Pod) []jsonpatch.JsonPatchOperation {
 var patches []jsonpatch.JsonPatchOperation

 for i, container := range pod.Spec.Containers {
 if container.Resources.Requests == nil {
 // 添加整个 requests 字段
 patches = append(patches, jsonpatch.JsonPatchOperation{
 Operation: "add",
 Path: fmt.Sprintf("/spec/containers/%d/resources/requests", i),
 Value: container.Resources.Limits,
 })
 } else {
 // 补充缺失的资源项
 for name, quantity := range container.Resources.Limits {
 if _, ok := container.Resources.Requests[name]; !ok {
 patches = append(patches, jsonpatch.JsonPatchOperation{
 Operation: "add",
 Path: fmt.Sprintf("/spec/containers/%d/resources/requests/%s",
 i, strings.ReplaceAll(string(name), "/", "~1")),
 Value: quantity,
 })
 }
 }
 }
 }
 return patches
}

添加调度注解

Webhook 为 Pod 添加调度所需的注解：

func addSchedulingAnnotations(pod *v1.Pod) []jsonpatch.JsonPatchOperation {
 annotations := map[string]string{
 "hami.io/gpu-type": detectDeviceType(pod),
 "hami.io/device-bind-phase": "pending",
 "hami.io/node-scheduler-policy": getSchedulerPolicy(),
 }

 // 合并用户已有的注解
 if pod.Annotations == nil {
 return []jsonpatch.JsonPatchOperation{{
 Operation: "add",
 Path: "/metadata/annotations",
 Value: annotations,
 }}
 }

 var patches []jsonpatch.JsonPatchOperation
 for key, value := range annotations {
 // 不覆盖用户显式设置的注解
 if _, exists := pod.Annotations[key]; !exists {
 patches = append(patches, jsonpatch.JsonPatchOperation{
 Operation: "add",
 Path: fmt.Sprintf("/metadata/annotations/%s", escapeJSONPatchKey(key)),
 Value: value,
 })
 }
 }
 return patches
}

注入环境变量（CUDA_VISIBLE_DEVICES 等）

Webhook 可以为容器预注入环境变量（部分环境变量由 Device Plugin 在 Allocate 阶段最终确定）：

func injectEnvVars(pod *v1.Pod) []jsonpatch.JsonPatchOperation {
 var patches []jsonpatch.JsonPatchOperation

 envVars := []v1.EnvVar{
 {Name: "NVIDIA_VISIBLE_DEVICES", Value: "all"},
 }

 for i, container := range pod.Spec.Containers {
 for _, env := range envVars {
 if !hasEnvVar(container, env.Name) {
 patches = append(patches, jsonpatch.JsonPatchOperation{
 Operation: "add",
 Path: fmt.Sprintf("/spec/containers/%d/env/-", i),
 Value: env,
 })
 }
 }
 }
 return patches
}

设置 schedulerName

确保使用 GPU 资源的 Pod 被路由到 HAMi 调度器：

func setSchedulerName(pod *v1.Pod) []jsonpatch.JsonPatchOperation {
 if pod.Spec.SchedulerName == "" || pod.Spec.SchedulerName == "default-scheduler" {
 return []jsonpatch.JsonPatchOperation{{
 Operation: "add",
 Path: "/spec/schedulerName",
 Value: "hami-scheduler",
 }}
 }
 return nil
}

配额检查与资源合法性校验

func checkQuota(pod *v1.Pod) error {
 gpuReq := parsePodGPURequest(pod)

 // 检查资源值是否合法
 if gpuReq.Count < 0 || gpuReq.Memory < 0 || gpuReq.Cores < 0 {
 return fmt.Errorf("GPU 资源请求值不能为负数")
 }

 if gpuReq.Count == 0 && gpuReq.Memory > 0 {
 return fmt.Errorf("请求了显存但未请求 GPU 设备")
 }

 // 检查命名空间配额
 quota, err := getResourceQuota(pod.Namespace)
 if err != nil {
 return nil // 无配额配置，跳过
 }

 used := getNamespaceGPUUsage(pod.Namespace)
 if used.Memory+gpuReq.Memory > quota.Memory {
 return fmt.Errorf("命名空间 %s 的 GPU 显存配额超限（已用 %d/%d，请求 %d）",
 pod.Namespace, used.Memory, quota.Memory, gpuReq.Memory)
 }

 return nil
}

Webhook 配置

Helm values.yaml

# values.yaml - Webhook 配置
webhook:
 enabled: true
 nameOverride: "hami-webhook"

 # 镜像配置
 image:
 repository: projecthami/hami
 tag: v2.5.0
 pullPolicy: IfNotPresent

 # 副本数
 replicas: 2

 # 服务配置
 service:
 type: ClusterIP
 port: 443
 targetPort: 9443

 # TLS 证书配置
 tls:
 enabled: true
 # 证书来源：auto | certManager | manual
 source: auto
 # 自动生成证书（使用 Kubernetes CA）
 auto:
 caBundle: null
 # cert-manager 配置
 certManager:
 enabled: false
 issuerRef:
 name: "hami-ca"
 kind: "Issuer"
 # 手动证书
 manual:
 cert: null
 key: null
 caCert: null

 # 准入配置
 admission:
 # 失败策略：Fail（安全优先）或 Ignore（可用性优先）
 failurePolicy: Fail
 # 重新验证策略
 reinvocationPolicy: Never
 # 匹配规则
 rules:
 - apiGroups: [""]
 apiVersions: ["v1"]
 resources: ["pods"]
 operations: ["CREATE", "UPDATE"]
 # 排除的命名空间
 namespaceSelector:
 matchExpressions:
 - key: hami.io/webhook
 operator: NotIn
 values: ["ignore"]

 # 资源限制
 resources:
 requests:
 cpu: 100m
 memory: 128Mi
 limits:
 cpu: 500m
 memory: 512Mi

 # 反亲和性
 affinity:
 podAntiAffinity:
 preferredDuringSchedulingIgnoredDuringExecution:
 - weight: 100
 podAffinityTerm:
 labelSelector:
 matchLabels:
 app: hami-webhook
 topologyKey: kubernetes.io/hostname

TLS 证书管理

Webhook 必须使用 HTTPS，需要 TLS 证书。HAMi 支持三种证书管理方式：

方式 1：自动生成（默认）

HAMi 在安装时自动生成自签名证书，并通过 Job 将证书写入 Secret：

# 自动生成的 Secret
apiVersion: v1
kind: Secret
metadata:
 name: hami-webhook-certs
 namespace: hami-system
type: kubernetes.io/tls
data:
 tls.crt: <base64-encoded-cert>
 tls.key: <base64-encoded-key>

方式 2：cert-manager 集成

# cert-manager Issuer
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
 name: hami-ca
 namespace: hami-system
spec:
 selfSigned: {}

---
# cert-manager Certificate
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
 name: hami-webhook-cert
 namespace: hami-system
spec:
 secretName: hami-webhook-certs
 duration: 8760h  # 1 年
 renewBefore: 720h  # 提前 30 天续签
 issuerRef:
 name: hami-ca
 kind: Issuer
 dnsNames:
 - hami-webhook.hami-system.svc
 - hami-webhook.hami-system.svc.cluster.local

方式 3：手动证书

# 使用已有证书
webhook:
 tls:
 source: manual
 manual:
 cert: |-
 -----BEGIN CERTIFICATE-----
 ...
 -----END CERTIFICATE-----
 key: |-
 -----BEGIN RSA PRIVATE KEY-----
 ...
 -----END RSA PRIVATE KEY-----

MutatingWebhookConfiguration

HAMi 安装时自动创建 MutatingWebhookConfiguration：

apiVersion: admissionregistration.k8s.io/v1
kind: MutatingWebhookConfiguration
metadata:
 name: hami-webhook
 annotations:
 cert-manager.io/inject-ca-from: hami-system/hami-webhook-cert
webhooks:
- name: hami-webhook.hami-system.svc
 clientConfig:
 service:
 name: hami-webhook
 namespace: hami-system
 path: "/webhook"
 port: 443
 caBundle: <ca-bundle>
 rules:
 - apiGroups: [""]
 apiVersions: ["v1"]
 resources: ["pods"]
 operations: ["CREATE", "UPDATE"]
 scope: "Namespaced"
 failurePolicy: Fail
 reinvocationPolicy: Never
 sideEffects: None
 timeoutSeconds: 10
 namespaceSelector:
 matchExpressions:
 - key: hami.io/webhook
 operator: NotIn
 values: ["ignore"]

设备适配注入

遍历容器进行设备类型匹配

Webhook 遍历 Pod 中的每个容器，匹配设备类型：

func detectDeviceType(pod *v1.Pod) string {
 for _, container := range pod.Spec.Containers {
 for name := range container.Resources.Limits {
 switch string(name) {
 case "nvidia.com/gpu":
 return "NVIDIA"
 case "hami.io/ascend":
 return "Ascend"
 case "hami.io/mlu":
 return "Cambricon"
 case "hami.io/dcu":
 return "Hygon"
 }
 }
 }
 return "NVIDIA" // 默认
}

用户也可以通过注解显式指定设备类型：

metadata:
 annotations:
 hami.io/gpu-type: "NVIDIA-A100-SXM4-40GB"

运行时类名注入

如果集群中配置了多种运行时类（RuntimeClass），Webhook 可以根据设备类型设置对应的 RuntimeClass：

func injectRuntimeClass(pod *v1.Pod, deviceType string) []jsonpatch.JsonPatchOperation {
 runtimeClassMap := map[string]string{
 "NVIDIA": "nvidia",
 "Ascend": "ascend",
 "Cambricon": "cambricon",
 "Hygon": "hygon",
 }

 if rc, ok := runtimeClassMap[deviceType]; ok && pod.Spec.RuntimeClassName == nil {
 return []jsonpatch.JsonPatchOperation{{
 Operation: "add",
 Path: "/spec/runtimeClassName",
 Value: rc,
 }}
 }
 return nil
}

优先级与核心策略注入

Webhook 从全局配置或 Pod 注解中读取核心策略，注入到调度注解中：

func injectCorePolicy(pod *v1.Pod) []jsonpatch.JsonPatchOperation {
 var patches []jsonpatch.JsonPatchOperation

 // 默认核心策略（限制算力使用）
 corePolicy := "default" // default | force | none
 if val, ok := pod.Annotations["hami.io/core-policy"]; ok {
 corePolicy = val
 }

 patches = append(patches, jsonpatch.JsonPatchOperation{
 Operation: "add",
 Path: "/metadata/annotations/hami.io~1core-policy",
 Value: corePolicy,
 })

 return patches
}

核心策略说明：

策略	含义	适用场景
`default`	限制算力使用，但允许短时突发	通用推理/训练
`force`	严格限制算力，不允许突发	多租户公平共享
`none`	不限制算力，仅隔离显存	对算力不敏感的任务

配额检查

命名空间 ResourceQuota 校验

Webhook 在准入阶段检查命名空间的 ResourceQuota：

# 定义命名空间 GPU 配额
apiVersion: v1
kind: ResourceQuota
metadata:
 name: gpu-quota
 namespace: ai-team
spec:
 hard:
 nvidia.com/gpu: "10" # 最多 10 个 GPU 设备
 nvidia.com/gpumem: "128000" # 最多 128000 MB 显存
 nvidia.com/cores: "200" # 最多 200% 算力

func getResourceQuota(namespace string) (*GPUQuota, error) {
 quotas, err := client.CoreV1().ResourceQuotas(namespace).List(ctx, metav1.ListOptions{})
 if err != nil {
 return nil, err
 }

 quota := &GPUQuota{}
 for _, q := range quotas.Items {
 for name, quantity := range q.Spec.Hard {
 switch string(name) {
 case "nvidia.com/gpu":
 quota.Count = int(quantity.Value())
 case "nvidia.com/gpumem":
 quota.Memory = int(quantity.Value())
 case "nvidia.com/cores":
 quota.Cores = int(quantity.Value())
 }
 }
 }
 return quota, nil
}

拒绝超额请求

当配额检查失败时，Webhook 返回拒绝响应：

func admissionResponse(err error) *admissionv1.AdmissionResponse {
 return &admissionv1.AdmissionResponse{
 Allowed: false,
 Result: &metav1.Status{
 Status: "Failure",
 Message: err.Error(),
 Code: 403,
 Reason: metav1.StatusReason("GPUQuotaExceeded"),
 },
 }
}

用户在创建 Pod 时会收到明确的错误信息：

kubectl apply -f pod.yaml
# Error from server: error when creating "pod.yaml": admission webhook "hami-webhook.hami-system.svc" denied the request:
# 命名空间 ai-team 的 GPU 显存配额超限（已用 38000/40000，请求 4000）

配额管理的最佳实践：

命名空间	显存配额	用途
ai-inference	256 GB	推理服务
ai-training	512 GB	训练任务
ai-dev	64 GB	开发测试
ai-platform	128 GB	平台服务

故障排查

Webhook 拒绝准入的常见原因

现象	原因	解决方法
Pod 创建被拒绝，错误信息含"GPUQuotaExceeded"	命名空间配额超限	增加配额或降低资源请求
Pod 创建被拒绝，错误信息含"invalid resource"	资源值不合法（负数、零值等）	检查 resources 字段
Pod 创建被拒绝，错误信息含"certificate"	TLS 证书过期或不匹配	重新生成证书
所有 Pod 创建都失败	Webhook 服务不可用	检查 Webhook Pod 状态
Pod 创建成功但未注入注解	Webhook 未匹配（命名空间排除）	检查 namespaceSelector

查看日志

# 查看 Webhook 日志
kubectl logs -n hami-system -l app=hami-webhook

# 正常注入日志
# I0101 "Admission review" pod="default/ai-inference" allowed=true patches=6
# I0101 "Injected annotation" key="hami.io/gpu-type" value="NVIDIA"
# I0101 "Set schedulerName" value="hami-scheduler"

# 拒绝日志
# E0101 "Admission denied" pod="ai-team/big-model" reason="GPUQuotaExceeded"
# E0101 "Namespace quota exceeded" namespace="ai-team" used=38000 limit=40000 request=4000

# 查看详细日志（v5 级别）
kubectl logs -n hami-system -l app=hami-webhook -v=5
# I0101 "Processing container" name="inference" limits="{nvidia.com/gpu:2, nvidia.com/gpumem:4000}"
# I0101 "Generated patch" operation="add" path="/spec/schedulerName" value="hami-scheduler"

临时绕过 Webhook

在调试时，可以通过为命名空间添加标签来绕过 Webhook：

# 为命名空间添加排除标签
kubectl label namespace debug hami.io/webhook=ignore

# 在该命名空间中创建 Pod 将不会被 HAMi Webhook 拦截
kubectl apply -f pod.yaml -n debug

# 调试完成后移除标签
kubectl label namespace debug hami.io/webhook-

检查 Webhook 配置

# 查看 MutatingWebhookConfiguration
kubectl get mutatingwebhookconfiguration hami-webhook -o yaml

# 检查 Webhook 服务端点
kubectl get svc -n hami-system hami-webhook

# 测试 Webhook 连通性
kubectl run curl-test --image=curlimages/curl --rm -it -- \
 curl -k https://hami-webhook.hami-system.svc:443/healthz

证书问题排查

# 查看 Webhook 证书 Secret
kubectl get secret -n hami-system hami-webhook-certs -o yaml

# 检查证书有效期
kubectl get secret -n hami-system hami-webhook-certs \
 -o jsonpath='{.data.tls\.crt}' | base64 -d | openssl x509 -noout -dates

# 如果使用 cert-manager，检查 Certificate 状态
kubectl get certificate -n hami-system

# 重新生成证书（删除 Secret 触发重建）
kubectl delete secret -n hami-system hami-webhook-certs
# 重启 Webhook Pod
kubectl rollout restart deployment -n hami-system hami-webhook

Webhook 不可用的紧急恢复

当 Webhook 不可用导致所有 Pod 创建都失败时，可以临时修改失败策略：

# 临时将 failurePolicy 改为 Ignore
kubectl patch mutatingwebhookconfiguration hami-webhook \
 --type='json' -p='[{"op":"replace","path":"/webhooks/0/failurePolicy","value":"Ignore"}]'

# 注意：恢复后务必改回 Fail
kubectl patch mutatingwebhookconfiguration hami-webhook \
 --type='json' -p='[{"op":"replace","path":"/webhooks/0/failurePolicy","value":"Fail"}]'

注意：failurePolicy: Ignore 仅用于紧急恢复。跳过准入检查意味着 Pod 不会获得 GPU 资源注入，可能导致调度失败。生产环境应确保 Webhook 高可用（多副本 + 反亲和性）。

小结

本章详细介绍了 HAMi Mutating Admission Webhook 的设计与实现：

概述：在 Pod 创建阶段拦截请求，自动注入调度信息和运行时配置
工作流程：解码请求、校验 Pod、设备适配注入、配额检查、返回补丁
主要功能：资源类型转换、调度注解添加、环境变量注入、schedulerName 设置、配额检查
Webhook 配置：Helmvalues.yaml 完整配置、三种 TLS 证书管理方式（自动/cert-manager/手动）
设备适配注入：设备类型匹配、运行时类名注入、优先级与核心策略
配额检查：命名空间 ResourceQuota 校验、拒绝超额请求
故障排查：常见拒绝原因、日志查看、临时绕过方法、证书问题排查

Webhook 是 HAMi “零应用改造"承诺的关键组件：用户只需声明资源请求，Webhook 自动完成所有注入工作。在下一章中，我们将进入第三部分，学习 HAMi 的部署配置与实战使用。

部署配置

Jimmy Song — Thu, 04 Jun 2026 08:13:46 +0000

HAMi 通过 Helm Chart 提供一键部署能力，涵盖调度器、设备插件、Webhook 和监控组件，支持灵活的配置管理。

部署概述

HAMi 采用模块化部署架构，核心组件包括：

组件	部署方式	说明
Scheduler Extender	Deployment（多副本）	GPU 感知调度器扩展
Device Plugin	DaemonSet	每个加速器节点一个实例
Mutating Webhook	Deployment	准入控制与注入
Monitor	Deployment	指标采集与暴露

所有组件通过 Helm Chart 统一管理，一条命令即可完成部署。

前置条件

Kubernetes 集群

Kubernetes >= 1.18
kubectl 命令行工具已配置
集群网络正常，DNS 解析可用

Helm

Helm 3 已安装

helm version
# version.BuildInfo{Version:"v3.14.0", ...}

GPU 节点要求

以 NVIDIA GPU 为例：

项目	要求
GPU 驱动	>= 510.47
CUDA 版本	>= 11.6
容器运行时	nvidia-container-toolkit 已安装
操作系统	Linux（推荐 Ubuntu 20.04+/CentOS 7+）

# 验证 GPU 驱动
nvidia-smi

# 验证容器运行时
nvidia-ctk --version

异构设备要求

设备类型	驱动/运行时
NVIDIA GPU	nvidia-container-toolkit
Ascend NPU	Ascend Docker Runtime
Cambricon MLU	Cambricon Docker Runtime
Hygon DCU	Hygon Docker Runtime

Helm Chart 部署

安装

# 添加 HAMi Helm 仓库
helm repo add hami-charts https://project-hami.github.io/hami-charts
helm repo update

# 安装 HAMi（默认配置）
helm install hami hami-charts/hami -n hami-system --create-namespace

# 验证安装
kubectl get pods -n hami-system

自定义安装

# 下载默认 values 以便自定义
helm show values hami-charts/hami > values.yaml

# 使用自定义配置安装
helm install hami hami-charts/hami -n hami-system -f values.yaml

配置管理

全局配置

# values.yaml - 全局配置
global:
 # 镜像仓库
 imageRegistry: ""
 imagePullSecrets: []

 # HAMi 版本
 version: "v2.5.0"

调度器配置

scheduler:
 enabled: true
 replicas: 2

 image:
 repository: projecthami/hami
 tag: v2.5.0

 # 调度策略
 policy:
 nodeSchedulerPolicy: binpack  # binpack | spread
 gpuSchedulerPolicy: binpack  # binpack | spread | topology

 # 资源超卖配置
 overcommit:
 enabled: true
 deviceMemoryScaling: 1.0 # 显存超卖系数
 deviceCoreScaling: 1.0 # 算力超卖系数

 # 优先级
 priorityClassName: "system-cluster-critical"

 # 反亲和性（高可用）
 affinity:
 podAntiAffinity:
 preferredDuringSchedulingIgnoredDuringExecution:
 - weight: 100
 podAffinityTerm:
 labelSelector:
 matchLabels:
 app: hami-scheduler
 topologyKey: kubernetes.io/hostname

设备插件配置

devicePlugin:
 enabled: true

 image:
 repository: projecthami/hami
 tag: v2.5.0

 # NVIDIA GPU 配置
 nvidia:
 enabled: true
 # GPU 切分配置
 splitCount: 10 # 每张 GPU 最多分配给 10 个 Pod
 # 显存配置
 memory:
 scaling: 1.0 # 显存缩放因子
 # MIG 策略
 migStrategy: "none" # none | single | mixed

 # Ascend NPU 配置
 ascend:
 enabled: false
 # VNPU 配置
 vnpu:
 enabled: false

 # Cambricon MLU 配置
 cambricon:
 enabled: false

 # Hygon DCU 配置
 hygon:
 enabled: false

Webhook 配置

webhook:
 enabled: true

 image:
 repository: projecthami/hami
 tag: v2.5.0

 service:
 type: ClusterIP
 port: 443

 # TLS 证书管理
 certManager:
 enabled: true # 推荐使用 cert-manager

监控配置

monitor:
 enabled: true

 image:
 repository: projecthami/hami
 tag: v2.5.0

 service:
 type: ClusterIP
 port: 41991

 # Prometheus ServiceMonitor
 serviceMonitor:
 enabled: true
 namespace: monitoring
 interval: 15s

设备特定配置

NVIDIA GPU

devicePlugin:
 nvidia:
 enabled: true
 splitCount: 10
 memory:
 scaling: 1.0
 migStrategy: "none"

# 节点标签要求
# kubectl label nodes <node-name> accelerator=nvidia

Ascend NPU

devicePlugin:
 ascend:
 enabled: true
 vnpu:
 enabled: true
 # VNPU 核心配置
 coreResourceName: "huawei.com/Ascend910B3-core"

# 节点标签要求
# kubectl label nodes <node-name> accelerator=ascend

Cambricon MLU

devicePlugin:
 cambricon:
 enabled: true

# 节点标签要求
# kubectl label nodes <node-name> accelerator=cambricon

Hygon DCU

devicePlugin:
 hygon:
 enabled: true

# 节点标签要求
# kubectl label nodes <node-name> accelerator=hygon

手动部署（高级）

如果无法使用 Helm，可以手动部署各组件：

Kubernetes 清单部署

# 下载清单文件
kubectl apply -f https://raw.githubusercontent.com/project-hami/hami/main/charts/hami/templates/scheduler/scheduler.yaml
kubectl apply -f https://raw.githubusercontent.com/project-hami/hami/main/charts/hami/templates/device-plugin/device-plugin.yaml
kubectl apply -f https://raw.githubusercontent.com/project-hami/hami/main/charts/hami/templates/scheduler/webhook.yaml

注意事项

手动部署需自行管理 TLS 证书
需要正确配置 RBAC 权限
建议优先使用 Helm 简化运维

部署验证

检查组件状态

# 检查所有 Pod 状态
kubectl get pods -n hami-system

# 预期输出：
# NAME READY STATUS RESTARTS AGE
# hami-scheduler-xxxxxx-xxxxx 1/1 Running 0 2m
# hami-device-plugin-xxxxx 1/1 Running 0 2m
# hami-webhook-xxxxxx-xxxxx 1/1 Running 0 2m
# hami-monitor-xxxxxx-xxxxx 1/1 Running 0 2m

检查节点设备注册

# 查看节点设备注解
kubectl get node <gpu-node-name> -o jsonpath='{.metadata.annotations}' | jq .

# 检查 GPU 资源
kubectl get nodes -o wide
kubectl describe node <gpu-node-name> | grep -A 10 "Allocatable"

运行测试工作负载

# 创建测试 Pod
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
 name: gpu-test
spec:
 containers:
 - name: cuda
 image: nvidia/cuda:12.0.0-base-ubuntu22.04
 command: ["nvidia-smi"]
 resources:
 limits:
 nvidia.com/gpu: 1
 nvidia.com/gpumem: 2000
 restartPolicy: Never
EOF

# 检查结果
kubectl logs gpu-test

升级策略

# 查看当前版本
helm list -n hami-system

# 升级到新版本
helm repo update
helm upgrade hami hami-charts/hami -n hami-system -f values.yaml

# 查看升级历史
helm history hami -n hami-system

# 回滚
helm rollback hami <revision> -n hami-system

升级注意事项

调度器升级期间，正在运行的 Pod 不受影响
设备插件升级会导致该节点上的 GPU 资源短暂不可用
建议在维护窗口期进行升级
升级前备份 values.yaml

卸载

# 卸载 HAMi
helm uninstall hami -n hami-system

# 清理命名空间
kubectl delete namespace hami-system

小结

本章介绍了 HAMi 的部署与配置：

Helm Chart：一键部署调度器、设备插件、Webhook、监控统一管理
灵活配置：全局、调度器、设备插件、监控、Webhook 各层级独立配置
多厂商支持：通过配置开关启用不同设备后端
部署验证：检查组件状态、设备注册和测试工作负载
升级与回滚：Helm 原生支持滚动升级

下一章将介绍如何在 Pod 中声明 GPU 资源请求。

参考资料

资源请求与分配

Jimmy Song — Thu, 04 Jun 2026 00:00:00 +0800

HAMi 使用标准 Kubernetes 资源请求语义，通过自定义资源字段声明 GPU 资源需求，实现零应用改动的 GPU 资源管理。

GPU 资源模型

HAMi 在 Kubernetes 资源模型基础上扩展了 GPU 资源语义，提供多个维度的资源控制：

资源名	含义	单位	示例
`nvidia.com/gpu`	GPU 设备数量	整数	`3` 表示使用 3 个 GPU 设备
`nvidia.com/gpumem`	显存大小	MB	`4000` 表示 4GB 显存
`nvidia.com/gpumem-percentage`	显存百分比	%	`50` 表示 50% 显存
`nvidia.com/cores`	算力核心占比	%	`30` 表示 30% 算力

注意： 上表中的资源名为 NVIDIA GPU 的默认配置（通过 nvidia.resourceCountName 等参数设置）。不同厂商有不同的默认资源名，例如昇腾 NPU 常见为 huawei.com/Ascend910B3、寒武纪 MLU 为 cambricon.com/vmlu、海光 DCU 为 hygon.com/dcunum 等。资源名可通过 ConfigMap 中的 resourceCountName、resourceMemoryName、resourceCoreName 参数自定义。详见 HAMi 全局配置。

资源声明原则

nvidia.com/gpu 指定要使用的 GPU 设备数量（整数，如 3 表示 3 个 GPU 设备）
nvidia.com/gpumem 或 nvidia.com/gpumem-percentage 指定每个设备的显存配额（二选一）
nvidia.com/cores 可选，限制每个设备的算力使用比例（百分比）

基本用法

按显存和算力分配

最常用的方式，指定 GPU 设备数量和显存大小：

apiVersion: v1
kind: Pod
metadata:
 name: ai-inference
spec:
 containers:
 - name: inference
 image: tensorflow-serving:latest
 resources:
 limits:
 nvidia.com/gpu: 3 # 使用 3 个 GPU 设备
 nvidia.com/gpumem: 4000 # 每个设备分配 4GB 显存

此 Pod 使用 3 个 GPU 设备，每个设备分配 4000MB 显存。

按显存百分比分配

使用百分比而非绝对值，适配不同型号的 GPU：

apiVersion: v1
kind: Pod
metadata:
 name: ai-inference-pct
spec:
 containers:
 - name: inference
 image: pytorch:latest
 resources:
 limits:
 nvidia.com/gpu: 2 # 使用 2 个 GPU 设备
 nvidia.com/gpumem-percentage: 40 # 分配 40% 显存

按设备数量分配

直接申请整张卡：

apiVersion: v1
kind: Pod
metadata:
 name: training-job
spec:
 containers:
 - name: training
 image: pytorch:latest
 resources:
 limits:
 nvidia.com/gpu: 1 # 使用 1 整张 GPU
 nvidia.com/gpumem: 32000 # 分配 32GB 显存

多卡分配

申请多张 GPU：

apiVersion: v1
kind: Pod
metadata:
 name: multi-gpu-training
spec:
 containers:
 - name: training
 image: pytorch:latest
 resources:
 limits:
 nvidia.com/gpu: 4 # 使用 4 张 GPU
 nvidia.com/gpumem: 32000 # 每张卡 32GB 显存

应用场景与示例

场景 1：AI 推理服务

多个模型推理任务共享 GPU，最常见的使用场景：

# 模型 A：轻量级推理
apiVersion: v1
kind: Pod
metadata:
 name: model-a
spec:
 containers:
 - name: serving
 image: model-a:latest
 resources:
 limits:
 nvidia.com/gpu: 1 # 使用 1 个 GPU
 nvidia.com/gpumem: 2000 # 2GB 显存
 nvidia.com/cores: 20 # 20% 算力

---
# 模型 B：中等推理
apiVersion: v1
kind: Pod
metadata:
 name: model-b
spec:
 containers:
 - name: serving
 image: model-b:latest
 resources:
 limits:
 nvidia.com/gpu: 1 # 使用 1 个 GPU
 nvidia.com/gpumem: 4000 # 4GB 显存
 nvidia.com/cores: 30 # 30% 算力

注意： GPU 共享通过多个 Pod 各请求 nvidia.com/gpu: 1 + 部分 nvidia.com/gpumem 实现。调度器将它们分配到同一个 GPU 设备上，只要总显存不超过物理显存。nvidia.com/cores 可选，用于限制每个 Pod 的算力占比。

场景 2：训练与推理混合

同一集群中训练任务和推理任务共存：

# 训练任务：独占大部分 GPU 资源
apiVersion: v1
kind: Pod
metadata:
 name: training-job
spec:
 containers:
 - name: training
 image: pytorch:latest
 resources:
 limits:
 nvidia.com/gpu: 1 # 独占 1 个 GPU
 nvidia.com/gpumem: 40000 # 40GB 显存（A100）

---
# 推理任务：共享 GPU，少量资源
apiVersion: v1
kind: Pod
metadata:
 name: inference-server
spec:
 containers:
 - name: serving
 image: vllm:latest
 resources:
 limits:
 nvidia.com/gpu: 1 # 使用 1 个 GPU
 nvidia.com/gpumem: 8000 # 8GB 显存
 nvidia.com/cores: 20 # 20% 算力

场景 3：开发测试环境

为每个开发人员分配小份额 GPU：

apiVersion: v1
kind: Pod
metadata:
 name: dev-notebook
spec:
 containers:
 - name: jupyter
 image: jupyter/pytorch-notebook:latest
 resources:
 limits:
 nvidia.com/gpu: 1 # 使用 1 个 GPU
 nvidia.com/gpumem: 2000 # 2GB 显存
 nvidia.com/cores: 10 # 10% 算力

10 个开发人员可以共享同一张 24GB 显存的 GPU，每人 2GB 显存 + 10% 算力。

场景 4：指定调度策略

apiVersion: v1
kind: Pod
metadata:
 name: inference-with-policy
 annotations:
 hami.io/node-scheduler-policy: "spread"
 hami.io/gpu-scheduler-policy: "binpack"
spec:
 containers:
 - name: serving
 image: vllm:latest
 resources:
 limits:
 nvidia.com/gpu: 3 # 使用 3 个 GPU 设备
 nvidia.com/gpumem: 4000 # 每个设备 4GB 显存

高级配置

节点亲和性

将工作负载调度到特定 GPU 类型的节点：

spec:
 affinity:
 nodeAffinity:
 requiredDuringSchedulingIgnoredDuringExecution:
 nodeSelectorTerms:
 - matchExpressions:
 - key: gpu-model
 operator: In
 values: ["A100", "A100-80G"]

GPU 类型过滤

metadata:
 annotations:
 hami.io/gpu-type: "A100" # 只使用 A100
 # hami.io/gpu-type: "Ascend910B" # 使用昇腾

UUID 白黑名单

metadata:
 annotations:
 hami.io/gpu-uuid-white-list: "GPU-xxx,GPU-yyy"

优先级与抢占

metadata:
 annotations:
 hami.io/task-priority: "10"
spec:
 priorityClassName: high-priority

资源超卖

在 Helm values.yaml 中配置超卖系数：

scheduler:
 overcommit:
 enabled: true
 deviceMemoryScaling: 1.5 # 显存超卖 1.5 倍
 deviceCoreScaling: 1.2 # 算力超卖 1.2 倍

注意： 超卖会提高利用率但增加资源争用风险，建议只在推理场景使用，并配合监控观察实际利用率。

NVIDIA MIG 支持

NVIDIA Multi-Instance GPU（MIG）提供硬件级隔离：

apiVersion: v1
kind: Pod
metadata:
 name: mig-inference
spec:
 containers:
 - name: serving
 image: vllm:latest
 resources:
 limits:
 nvidia.com/mig-1g.10gb: 1

MIG 模式配置

# values.yaml
devicePlugin:
 nvidia:
 migStrategy: "mixed" # single | mixed | none

常见资源请求模式

场景	nvidia.com/gpu	nvidia.com/gpumem	nvidia.com/cores	说明
轻量推理	1	1000	10	10 个 Pod 共享 1 GPU
标准推理	1	2000-4000	20-30	3-5 个 Pod 共享 1 GPU
大模型推理	1-2	10000-40000	50-100	独占或少量共享
训练任务	1	全部显存	100	独占 GPU
多卡训练	4-8	每卡全显存	100	独占多卡
开发测试	1	500-1000	5-10	多人共享

小结

本章介绍了 HAMi 的资源请求与分配：

资源模型：nvidia.com/gpu、nvidia.com/gpumem 等字段声明 GPU 资源需求
基本用法：按显存、百分比、设备数量分配
应用场景：推理服务、训练推理混合、开发测试、指定策略
高级配置：亲和性、类型过滤、优先级、超卖
MIG：支持硬件级隔离

参考资料

Kubernetes 资源管理

调度策略

Jimmy Song — Thu, 04 Jun 2026 08:27:56 +0000

HAMi 提供两级调度策略：节点级和 GPU 卡级，支持 binpack、spread、拓扑感知和动态 MIG，满足从成本优化到性能极致的不同需求。

调度策略概述

HAMi 的调度策略分为两个层级：

┌─────────────────────────────────────────────┐
│ 节点级策略（Node Policy） │
│ 控制 Pod 在不同节点间的分布 │
│ 策略：binpack | spread │
├─────────────────────────────────────────────┤
│ GPU 卡级策略（GPU Policy） │
│ 控制 Pod 在同一节点上的不同 GPU 卡间分布 │
│ 策略：binpack | spread | topology │
└─────────────────────────────────────────────┘

节点级策略：决定 Pod 放到哪个节点
GPU 卡级策略：决定 Pod 使用节点上的哪张 GPU

两级策略独立配置，可以灵活组合。

BinPack 密集策略

优先将 Pod 调度到资源利用率最高的节点或 GPU 卡，实现"装箱"效果。

适用场景

降低成本：减少使用的节点数，节省电力和运维成本
最大化利用率：集中工作负载，留出空闲节点
GPUaaS: 提高每张 GPU 的共享密度

工作原理

3 张 GPU 当前使用情况：
 GPU-0: ████████░░ 80% 使用
 GPU-1: ████░░░░░░ 40% 使用
 GPU-2: ░░░░░░░░░░ 0% 使用

BinPack 选择：GPU-0（使用率最高，剩余空间仍可容纳新 Pod）

配置

# values.yaml
scheduler:
 policy:
 nodeSchedulerPolicy: binpack  # 节点级 binpack
 gpuSchedulerPolicy: binpack  # 卡级 binpack

# 或通过 Pod 注解指定
metadata:
 annotations:
 hami.io/node-scheduler-policy: "binpack"
 hami.io/gpu-scheduler-policy: "binpack"

Spread 分散策略

优先将 Pod 调度到资源利用率最低的节点或 GPU 卡，实现"分散"效果。

适用场景

高可用：工作负载分散到不同节点，单节点故障影响更小
负载均衡：均匀分配资源，避免热点
推理服务：多个推理实例分散部署，提高可用性

工作原理

3 张 GPU 当前使用情况：
 GPU-0: ████████░░ 80% 使用
 GPU-1: ████░░░░░░ 40% 使用
 GPU-2: ░░░░░░░░░░ 0% 使用

Spread 选择：GPU-2（使用率最低，有最多可用空间）

配置

# values.yaml
scheduler:
 policy:
 nodeSchedulerPolicy: spread  # 节点级 spread
 gpuSchedulerPolicy: spread  # 卡级 spread

拓扑感知策略

利用 GPU 互连拓扑（NVLink、NVSwitch、PCIe）优化设备选择，将需要协作的多卡工作负载放在通信延迟最低的设备组合上。

适用场景

大模型训练：多卡之间频繁通信，拓扑影响吞吐
分布式训练：AllReduce 等集合通信对延迟敏感
多卡推理：Tensor Parallel 需要低延迟设备间通信

工作原理

GPU 拓扑示例：
 GPU-0 ←→ GPU-1 : NVLink（高带宽）
 GPU-2 ←→ GPU-3 : NVLink（高带宽）
 GPU-0 ←→ GPU-2 : PCIe（低带宽）

需要 2 卡的训练任务 → 优先选择 GPU-0 + GPU-1（NVLink 互联）

配置

# values.yaml
scheduler:
 policy:
 gpuSchedulerPolicy: topology  # 卡级拓扑感知

前提条件

需要 NVIDIA GPU
需要安装 NVML 库
调度器能够读取 GPU 拓扑信息

动态 MIG 策略

在支持 MIG 的 NVIDIA GPU 上，根据工作负载需求动态创建 MIG 实例。

适用场景

强隔离需求：MIG 提供硬件级隔离，每个实例完全独立
多租户环境：不同租户之间零干扰
混合负载：不同大小的任务使用不同 MIG profile

MIG Profile 类型

Profile	GPU 切片	显存	适用场景
1g.10gb	1/7	10GB	轻量推理
2g.20gb	2/7	20GB	中等推理
3g.40gb	3/7	40GB	较重推理
4g.40gb	4/7	40GB	大模型推理
7g.80gb	7/7	80GB	独占整卡

配置

# values.yaml
devicePlugin:
 nvidia:
 migStrategy: "mixed" # 启用 MIG

# Pod 使用 MIG 实例
apiVersion: v1
kind: Pod
metadata:
 name: mig-inference
spec:
 containers:
 - name: serving
 image: vllm:latest
 resources:
 limits:
 nvidia.com/mig-2g.20gb: 1

混合策略

两级策略独立配置，灵活组合：

节点级策略	卡级策略	效果	典型场景
binpack	binpack	聚集 + 填充	成本优化、GPUaaS
binpack	spread	聚集 + 分散	同节点多 GPU 均衡
spread	binpack	分散 + 填充	高可用 + 单卡高密度
spread	spread	全分散	高可用、负载均衡
spread	topology	分散 + 拓扑	训练集群最佳实践

配置示例

# 训练集群：节点分散 + 拓扑感知
scheduler:
 policy:
 nodeSchedulerPolicy: spread
 gpuSchedulerPolicy: topology

---
# 推理集群：节点聚集 + 卡级分散
scheduler:
 policy:
 nodeSchedulerPolicy: binpack
 gpuSchedulerPolicy: spread

策略选择指南

图 3: 调度策略决策流程

场景推荐

场景	推荐策略	原因
AI 云服务（GPUaaS）	binpack/binpack	最大化 GPU 密度，降低成本
企业推理平台	spread/spread	高可用，单节点故障影响小
大模型训练	spread/topology	分散到多节点 + 拓扑优化通信
开发测试环境	binpack/binpack	集中使用少量 GPU
训练推理混合	binpack/spread	集中使用节点 + 卡级分散推理
多租户平台	spread/spread	隔离 + 均衡

自定义策略开发

HAMi 支持通过设备抽象层的 ScoreNode 接口开发自定义调度策略：

// ScoreNode 接口定义
type Devices interface {
 ScoreNode(
 node string,
 podDevices PodDevices,
 previous float32,
 policy string,
 ) float32
}

开发步骤

实现设备后端的 ScoreNode 方法
注册自定义策略名称
在配置中指定策略名称

小结

本章介绍了 HAMi 的调度策略体系：

两级调度：节点级和 GPU 卡级策略独立配置
BinPack：聚集优先，适合成本优化
Spread：分散优先，适合高可用
拓扑感知：利用 GPU 互联拓扑，适合训练
动态 MIG：提供硬件级隔离，适合多租户
混合策略：灵活组合，覆盖各种场景

参考资料

NVIDIA MIG 文档

异构设备支持

Jimmy Song — Thu, 04 Jun 2026 08:27:44 +0000

AI 基础设施不会永远只有 NVIDIA。HAMi 通过统一设备抽象层，将多种异构加速器纳入 Kubernetes 的统一调度与管理。

为什么需要统一资源层？

异构 AI 集群面临的核心挑战：

各厂商独立的 Device Plugin：每个厂商有自己的资源模型和调度语义
缺乏统一调度视图：无法在多厂商集群中实现一致的调度策略
运维复杂度高：不同设备需要不同的管理工具和运维流程
迁移成本大：从 NVIDIA 迁移到其他加速器需要大量适配工作

HAMi 通过可插拔的设备抽象层，为多厂商异构加速器提供统一的调度与资源分配体验：一套流程、多厂商支持。

支持的设备一览

根据 HAMi 官方最新文档，当前支持 11 类设备，其中 Teco DPU 仍处于适配验证阶段。

厂商	设备类型	资源名示例	内存隔离	核心隔离	多卡	状态
NVIDIA	GPU	`nvidia.com/gpu`	✅	✅	✅	生产可用
华为 Ascend	NPU	`huawei.com/Ascend910B3`	✅	✅	—	生产可用
寒武纪	MLU	`cambricon.com/vmlu`	✅	✅	—	生产可用
海光	DCU	`hygon.com/dcunum`	✅	✅	—	生产可用
天数智芯	GPU	`iluvatar.ai/BI-V100-vgpu`	✅	✅	—	生产可用
摩尔线程	GPU	`mthreads.com/vgpu`	✅	✅	—	生产可用
沐曦	GPU	`metax-tech.com/gpu`	✅	✅	—	生产可用
燧原	GCU	`enflame.com/gcu`	✅	✅	—	生产可用
昆仑芯	XPU	`kunlunxin.com/vxpu`	✅	✅	—	生产可用
瀚博半导体	GPU	`vastaitech.com/va`	✅	✅	—	生产可用
Teco	DPU	待官方公布	进行中	进行中	—	适配中

说明：不同厂商的资源 key 并不统一，部分设备还会把型号编码直接放进资源名中，因此生产环境应以对应厂商示例 YAML 为准。

NVIDIA GPU 支持

NVIDIA GPU 是 HAMi 支持最完整的设备后端，功能覆盖所有调度和隔离能力。

配置

# values.yaml
devicePlugin:
 nvidia:
 enabled: true
 splitCount: 10
 memory:
 scaling: 1.0
 migStrategy: "none"

使用示例

apiVersion: v1
kind: Pod
metadata:
 name: nvidia-inference
spec:
 containers:
 - name: serving
 image: vllm:latest
 resources:
 limits:
 nvidia.com/gpu: 3
 nvidia.com/gpumem: 4000

特殊能力

MIG：支持 single/mixed 模式
拓扑感知调度：NVLink/NVSwitch 拓扑优化
CDI：支持 Container Device Interface 规范
完整监控：通过 NVML 采集详细指标

华为昇腾 NPU 支持

华为 Ascend NPU 是国产 AI 加速器的重要选项，HAMi 提供完整的调度和 VNPU 软切分支持。

配置

# values.yaml
devicePlugin:
 ascend:
 enabled: true
 vnpu:
 enabled: true
 coreResourceName: "huawei.com/Ascend910B3-core"

使用示例

apiVersion: v1
kind: Pod
metadata:
 name: ascend-inference
spec:
 containers:
 - name: serving
 image: ascend-inference:latest
 resources:
 limits:
 huawei.com/Ascend910B3: 1
 huawei.com/Ascend910B3-memory: 2000

VNPU 软切分

Ascend NPU 支持基于 libvnpu.so 的软切分，实现显存与算力的细粒度共享：

显存配额（NPU_MEM_QUOTA）环境变量注入
算力配额（NPU_PRIORITY）环境变量注入
通过 limiter 进程实现资源限制
与 HAMi 调度器无缝集成

支持的芯片型号

Ascend 910B、910B3、310P 等

寒武纪 MLU 支持

配置

devicePlugin:
 cambricon:
 enabled: true

使用示例

apiVersion: v1
kind: Pod
metadata:
 name: mlu-inference
spec:
 containers:
 - name: serving
 image: cambricon-inference:latest
 resources:
 limits:
 cambricon.com/vmlu: 1
 cambricon.com/mlu370.smlu.vmemory: 20
 cambricon.com/mlu370.smlu.vcore: 10

海光 DCU 支持

配置

devicePlugin:
 hygon:
 enabled: true

使用示例

apiVersion: v1
kind: Pod
metadata:
 name: dcu-inference
spec:
 containers:
 - name: serving
 image: hygon-inference:latest
 resources:
 limits:
 hygon.com/dcunum: 1
 hygon.com/dcucores: 60
 hygon.com/dcumem: 2000

其他已支持设备

除 NVIDIA、Ascend、MLU、DCU 外，HAMi 还支持以下设备后端：

厂商	设备类型	资源名示例	Helm 开关
Iluvatar	GPU	`iluvatar.ai/BI-V100-vgpu`、`iluvatar.ai/BI-V100.vMem`	`devicePlugin.iluvatar.enabled`
Mthreads	GPU	`mthreads.com/vgpu`、`mthreads.com/sgpu-memory`	`devicePlugin.mthreads.enabled`
MetaX	GPU	`metax-tech.com/gpu`	`devicePlugin.metax.enabled`
燧原	GCU	`enflame.com/gcu`	`devicePlugin.enflame.enabled`
昆仑芯	XPU	`kunlunxin.com/vxpu`、`kunlunxin.com/vxpu-memory`	`devicePlugin.kunlun.enabled`
Vast.ai	GPU	`vastaitech.com/va`	`devicePlugin.vastai.enabled`
Teco	DPU	待官方公布	适配中

这些设备同样复用 HAMi 的统一调度链路，只是具体资源 key、注解和值域由厂商插件定义。

异构混合部署

在同一集群中使用多种厂商的设备：

# NVIDIA 节点
kubectl label nodes node-nvidia-01 accelerator=nvidia

# Ascend 节点
kubectl label nodes node-ascend-01 accelerator=ascend

# MLU 节点
kubectl label nodes node-mlu-01 accelerator=cambricon

设备类型过滤

通过注解指定 Pod 使用的设备类型：

# 使用 NVIDIA GPU
metadata:
 annotations:
 hami.io/gpu-type: "nvidia"

---
# 使用昇腾 NPU
metadata:
 annotations:
 hami.io/gpu-type: "Ascend910B3"

---
# 使用寒武纪 MLU
metadata:
 annotations:
 hami.io/gpu-type: "cambricon"

统一监控

不同厂商的设备指标通过 HAMi Monitor 统一暴露：

# 查看所有设备的资源使用
kubectl get nodes -o wide

# 查看特定节点的设备注解
kubectl get node <node-name> -o jsonpath='{.metadata.annotations}' | jq .

新增设备后端

HAMi 的设备抽象层采用插件式设计，新增设备后端只需：

实现 Devices 接口
在调度器配置中注册初始化函数
编写对应的设备插件

// 设备接口（需实现的方法）
type Devices interface {
 CommonWord() string
 GetResourceNames() ResourceNames
 GetNodeDevices(node) ([]*DeviceInfo, error)
 Fit(devices, request, pod, nodeInfo, allocated) (bool, map[string]ContainerDevices, string)
 ScoreNode(node, podDevices, previous, policy) float32
 // ...
}

小结

本章介绍了 HAMi 的异构设备支持：

统一设备抽象层：一套调度流程，多厂商支持
11 类设备支持：NVIDIA、Ascend、Cambricon、Hygon、Iluvatar、Mthreads、MetaX、Enflame、Kunlunxin、Vast.ai，以及适配中的 Teco DPU
异构混合部署：同一集群多种设备，统一调度
可扩展架构：新增设备只需实现统一接口

参考资料

监控与可观测性

Jimmy Song — Thu, 04 Jun 2026 08:27:40 +0000

HAMi 提供端到端的可观测性：Prometheus 指标、Grafana 仪表盘、WebUI 和增强事件，帮助你掌握 GPU 资源使用全貌。

监控体系概览

图 3: 监控体系概览

HAMi 的可观测性覆盖四个层面：

层面	能力	用途
指标	Prometheus 端点	GPU 资源使用、调度性能
可视化	Grafana + WebUI	实时监控、资源规划
事件	Pod 事件增强	调度结果追踪、问题定位
日志	分级日志	调试、故障排查

Prometheus 指标

GPU 资源指标

指标名	含义	标签
`hami_vgpu_memory_usage_bytes`	GPU 显存使用量	pod, namespace, device, container
`hami_vgpu_utilization_percent`	GPU 算力使用率	pod, namespace, device, container
`hami_gpu_memory_total_bytes`	物理 GPU 显存总量	node, device
`hami_gpu_memory_used_bytes`	物理 GPU 显存使用量	node, device

调度器指标

指标名	含义
`hami_scheduler_filter_duration_seconds`	Filter 阶段耗时
`hami_scheduler_score_duration_seconds`	Score 阶段耗时
`hami_scheduler_bind_duration_seconds`	Bind 阶段耗时
`hami_scheduler_bind_success_total`	绑定成功次数
`hami_scheduler_bind_failure_total`	绑定失败次数

设备插件指标

指标名	含义
`hami_device_plugin_allocate_duration_seconds`	Allocate 耗时
`hami_device_plugin_device_count`	注册设备数量
`hami_device_plugin_healthy_status`	设备健康状态

指标端点配置

# values.yaml
monitor:
 enabled: true
 service:
 type: ClusterIP
 port: 41991
 serviceMonitor:
 enabled: true
 namespace: monitoring
 interval: 15s
 path: /metrics

# 手动查询指标
kubectl port-forward -n hami-system svc/hami-monitor 41991:41991
curl http://localhost:41991/metrics

Grafana 仪表盘

部署 Grafana

如果集群中没有 Grafana：

helm repo add grafana https://grafana.github.io/helm-charts
helm install grafana grafana/grafana -n monitoring --create-namespace

导入 HAMi 仪表盘

打开 Grafana UI
导航到 Dashboards → Import
输入 HAMi 仪表盘 JSON（或从 GitHub 获取）
选择 Prometheus 数据源
点击 Import

关键面板

GPU 集群概览：节点 GPU 总量、使用量、利用率
Pod 资源使用：每个 Pod 的显存和算力占用
调度器性能：Filter/Score/Bind 耗时分布
设备健康 GPU：健康状态和故障告警

WebUI

HAMi 提供内置 WebUI，直观展示 GPU 资源分配情况。

访问方式

# Port-forward 访问
kubectl port-forward -n hami-system svc/hami-webui 8080:80

# 浏览器访问
# http://localhost:8080

功能

集群 GPU 资源总览
节点级 GPU 使用详情
Pod 级资源分配视图
实时刷新

事件增强

HAMi 在 Pod 事件中注入调度详情，帮助快速定位问题。

查看调度事件

kubectl describe pod <pod-name> -n <namespace>

事件中包含：

Events:
 Type Reason Age From Message
 ---- ------ ---- ---- -------
 Normal Scheduled 10s hami-scheduler Successfully assigned pod to node-01
 GPU: 1/3, Memory: 4000MB
 Score: 85, Policy: binpack
 Normal DeviceAllocated 10s hami-device-plugin Allocated GPU-0 on node-01

失败事件示例

Events:
 Type Reason Age From Message
 ---- ------ ---- ---- -------
 Warning FailedScheduling 5s hami-scheduler 0/3 nodes available:
 node-01: GPU memory insufficient (requested 8000MB, available 4000MB)
 node-02: device type mismatch (requested A100, has T4)
 node-03: quota exceeded (namespace ai-team)

日志系统

调度器日志

# 查看调度器日志
kubectl logs -n hami-system deployment/hami-scheduler

# 增加日志级别
kubectl edit deployment -n hami-system hami-scheduler
# 添加参数: --v=5

日志级别

级别	内容	用途
v=4	节点摘要	日常运维
v=5	设备细节、评分过程	问题排查
v=6	详细调试信息	深度调试

设备插件日志

kubectl logs -n hami-system daemonset/hami-device-plugin -c nvidia

结构化日志

调度器输出标准化错误码，便于自动化分析：

E0604 scheduler.go:724] Failed to schedule pod
 error_code=SCHED_INSUFFICIENT_GPU_MEMORY
 pod=ai-inference
 node=node-01
 requested=8000MB
 available=4000MB

告警规则

GPU 资源告警

apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
 name: hami-gpu-alerts
 namespace: monitoring
spec:
 groups:
 - name: hami-gpu
 rules:
 - alert: GPUMemoryUsageHigh
 expr: hami_gpu_memory_used_bytes / hami_gpu_memory_total_bytes > 0.95
 for: 10m
 labels:
 severity: warning
 annotations:
 summary: "GPU memory usage exceeds 95% on {{ $labels.node }}"

 - alert: GPUNoAvailableMemory
 expr: (hami_gpu_memory_total_bytes - hami_gpu_memory_used_bytes) < 1073741824
 for: 5m
 labels:
 severity: critical
 annotations:
 summary: "Less than 1GB GPU memory available on {{ $labels.node }}"

调度异常告警

 - alert: ScheduleFailureRate
 expr: rate(hami_scheduler_bind_failure_total[5m]) / rate(hami_scheduler_bind_success_total[5m]) > 0.1
 for: 10m
 labels:
 severity: warning
 annotations:
 summary: "HAMi scheduler failure rate exceeds 10%"

系统健康检查

健康端点

# 调度器健康检查
curl http://hami-scheduler:8080/healthz

# 就绪检查
curl http://hami-scheduler:8080/readyz

自动化检查脚本

#!/bin/bash
# hami-health-check.sh

echo "=== HAMi Health Check ==="

# 1. 检查 Pod 状态
echo "--- Component Status ---"
kubectl get pods -n hami-system -o wide

# 2. 检查调度器健康
echo "--- Scheduler Health ---"
kubectl exec -n hami-system deployment/hami-scheduler -- wget -qO- http://localhost:8080/healthz

# 3. 检查 GPU 节点
echo "--- GPU Nodes ---"
kubectl get nodes -l accelerator=nvidia -o wide

# 4. 检查设备注册
echo "--- Device Registration ---"
for node in $(kubectl get nodes -l accelerator=nvidia -o name); do
 echo "$node:"
 kubectl get $node -o jsonpath='{.status.allocatable}' | grep hami
done

小结

本章介绍了 HAMi 的监控与可观测性体系：

Prometheus 指标：GPU 资源、调度器、设备插件多维度指标
Grafana 仪表盘：可视化 GPU 使用和调度性能
WebUI：内置资源总览界面
事件增强：Pod 事件中包含调度详情
日志系统：分级日志和标准化错误码
告警规则：资源、调度和设备健康告警

参考资料

生产环境部署

Jimmy Song — Thu, 04 Jun 2026 08:27:52 +0000

生产环境部署需要关注高可用、安全、容量规划和升级策略，确保 GPU 资源管理平台的稳定运行。

生产环境架构

资源规划

组件	CPU	内存	副本数
Scheduler	500m-1000m	512Mi-1Gi	2-3
Device Plugin	200m-500m	256Mi-512Mi	DaemonSet
Webhook	200m-500m	256Mi-512Mi	2
Monitor	200m-500m	256Mi-512Mi	1-2

高可用配置

调度器高可用

scheduler:
 replicas: 3
 # 领导者选举（默认启用）
 leaderElection:
 enabled: true
 leaseDuration: 15s
 renewDeadline: 10s
 retryPeriod: 2s

 # 反亲和性，调度器 Pod 分散到不同节点
 affinity:
 podAntiAffinity:
 requiredDuringSchedulingIgnoredDuringExecution:
 - labelSelector:
 matchLabels:
 app: hami-scheduler
 topologyKey: kubernetes.io/hostname

 # 资源限制
 resources:
 requests:
 cpu: 500m
 memory: 512Mi
 limits:
 cpu: "1"
 memory: 1Gi

Webhook 高可用

webhook:
 replicas: 2
 affinity:
 podAntiAffinity:
 preferredDuringSchedulingIgnoredDuringExecution:
 - weight: 100
 podAffinityTerm:
 labelSelector:
 matchLabels:
 app: hami-webhook
 topologyKey: kubernetes.io/hostname

设备插件

设备插件以 DaemonSet 运行，天然具备高可用，节点级别的故障不影响其他节点。

devicePlugin:
 # DaemonSet 自动调度到每个 GPU 节点
 tolerations:
 - key: nvidia.com/gpu
 operator: Exists
 effect: NoSchedule

安全配置

RBAC 权限

HAMi 自动创建所需 RBAC 权限：

# 调度器需要的权限
rules:
- apiGroups: [""]
 resources: ["pods", "nodes", "namespaces"]
 verbs: ["get", "list", "watch"]
- apiGroups: [""]
 resources: ["pods/binding"]
 verbs: ["create"]
- apiGroups: [""]
 resources: ["pods"]
 verbs: ["patch", "update"]

TLS 证书

webhook:
 certManager:
 enabled: true # 推荐：自动签发和轮换证书

网络策略

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
 name: hami-system-policy
 namespace: hami-system
spec:
 podSelector: {}
 policyTypes:
 - Ingress
 - Egress
 ingress:
 - from:
 - namespaceSelector:
 matchLabels:
 name: hami-system
 - namespaceSelector:
 matchLabels:
 name: monitoring
 egress:
 - to:
 - namespaceSelector: {} # 允许访问 API Server

生产级 Helm 配置

# production-values.yaml
global:
 imageRegistry: ""
 imagePullSecrets: []

scheduler:
 enabled: true
 replicas: 3
 image:
 repository: projecthami/hami
 tag: v2.5.0
 pullPolicy: IfNotPresent
 policy:
 nodeSchedulerPolicy: binpack
 gpuSchedulerPolicy: binpack
 overcommit:
 enabled: true
 deviceMemoryScaling: 1.0
 resources:
 requests:
 cpu: 500m
 memory: 512Mi
 limits:
 cpu: "1"
 memory: 1Gi
 priorityClassName: system-cluster-critical
 affinity:
 podAntiAffinity:
 requiredDuringSchedulingIgnoredDuringExecution:
 - labelSelector:
 matchLabels:
 app: hami-scheduler
 topologyKey: kubernetes.io/hostname

devicePlugin:
 enabled: true
 image:
 repository: projecthami/hami
 tag: v2.5.0
 nvidia:
 enabled: true
 splitCount: 10
 memory:
 scaling: 1.0
 migStrategy: "none"
 resources:
 requests:
 cpu: 200m
 memory: 256Mi
 limits:
 cpu: 500m
 memory: 512Mi

webhook:
 enabled: true
 replicas: 2
 certManager:
 enabled: true
 resources:
 requests:
 cpu: 200m
 memory: 256Mi
 limits:
 cpu: 500m
 memory: 512Mi

monitor:
 enabled: true
 serviceMonitor:
 enabled: true
 namespace: monitoring
 interval: 15s
 resources:
 requests:
 cpu: 200m
 memory: 256Mi
 limits:
 cpu: 500m
 memory: 512Mi

容量规划

GPU 资源评估

评估公式：

 所需 GPU 数量 = SUM(每种场景的 Pod 数 × 每 Pod 显存) / (每张 GPU 显存 × 目标利用率)

示例：
 - 推理场景：100 Pod × 4GB = 400GB
 - A100 GPU：80GB × 80% 利用率 = 64GB 可用
 - 所需 GPU = 400GB / 64GB ≈ 7 张

调度器性能估算

集群规模	节点数	GPU 数	调度器 CPU	调度器内存
小型	< 10	< 20	500m	512Mi
中型	10-50	20-100	1 core	1Gi
大型	50-200	100-500	2 core	2Gi
超大	> 200	> 500	4 core	4Gi

升级策略

滚动升级

# 升级前检查
helm list -n hami-system
kubectl get pods -n hami-system

# 执行升级
helm repo update
helm upgrade hami hami-charts/hami -n hami-system -f production-values.yaml

# 监控升级过程
kubectl rollout status deployment/hami-scheduler -n hami-system
kubectl rollout status deployment/hami-webhook -n hami-system

回滚

# 查看历史版本
helm history hami -n hami-system

# 回滚到指定版本
helm rollback hami 1 -n hami-system

升级注意事项

调度器滚动升级期间，正在运行的 Pod 不受影响
设备插件升级会导致该节点 GPU 短暂不可用，逐节点升级
Webhook 升级期间新 Pod 创建可能短暂失败
升级前在测试环境验证

最佳实践清单

调度器 2-3 副本 + 反亲和性
Webhook 2 副本 + 反亲和性
cert-manager 自动管理 TLS 证书
配置资源限制（CPU/内存）
设置 priorityClassName 为 system-cluster-critical
启用 ServiceMonitor 对接 Prometheus
配置 Pod 反亲和性分散部署
规划命名空间配额
准备告警规则
升级前备份 values.yaml

小结

本章介绍了 HAMi 的生产环境部署：

高可用架构：多副本 + 领导者选举 + 反亲和性
安全配置：RBAC、TLS、网络策略
容量规划：GPU 资源评估和调度器性能估算
升级策略：Helm 滚动升级和回滚
最佳实践：生产部署检查清单

参考资料

故障排查

Jimmy Song — Thu, 04 Jun 2026 08:28:00 +0000

系统化的故障排查方法论，从问题现象出发，快速定位根因并解决。

系统化排查流程

图 3: 故障排查流程

部署问题

Pod 无法启动

# 检查 Pod 状态
kubectl get pods -n hami-system

# 查看事件
kubectl describe pod <pod-name> -n hami-system

# 常见原因
# - 镜像拉取失败（ImagePullBackOff）
# - 资源不足（Pending）
# - 节点选择器不匹配

Webhook 证书错误

# 检查证书
kubectl get secret -n hami-system -l app=hami-webhook

# 检查 Webhook 配置
kubectl get mutatingwebhookconfiguration -l app=hami-webhook -o yaml

# 重新生成证书（使用 cert-manager）
kubectl delete certificate -n hami-system hami-webhook-cert
# cert-manager 会自动重新签发

调度器健康检查失败

# 检查健康端点
kubectl exec -n hami-system deployment/hami-scheduler -- wget -qO- http://localhost:8080/healthz

# 查看日志
kubectl logs -n hami-system deployment/hami-scheduler --tail=100

设备插件注册失败

# 检查设备插件状态
kubectl get pods -n hami-system -l app=hami-device-plugin

# 查看设备插件日志
kubectl logs -n hami-system daemonset/hami-device-plugin

# 常见原因
# - kubelet socket 不存在或权限不对
# - NVML 初始化失败（驱动问题）
# - 设备路径不存在

调度问题

Pod 一直 Pending

# 1. 查看 Pod 事件
kubectl describe pod <pod-name>

# 2. 查看调度器日志
kubectl logs -n hami-system deployment/hami-scheduler | grep <pod-name>

# 3. 增加日志级别（v5 显示设备细节）
kubectl edit deployment -n hami-system hami-scheduler
# 添加 --v=5 参数

常见调度失败原因

错误信息	原因	解决方案
GPU memory insufficient	显存不足	减少请求量或增加 GPU
device type mismatch	设备类型不匹配	检查 `hami.io/gpu-type` 注解
quota exceeded	命名空间配额超限	增加 ResourceQuota 或减少请求
no healthy device	设备不健康	检查 GPU 状态和驱动
node locked	节点锁未释放	等待或手动清理节点注解

节点过滤失败

# 查看节点设备注解
kubectl get node <node-name> -o jsonpath='{.metadata.annotations}' | jq .

# 检查节点 GPU 资源
kubectl describe node <node-name> | grep -A 20 "Allocatable"

# 检查 GPU 健康状态
nvidia-smi -q -d HEALTH

资源分配问题

资源请求无法满足

# 查看集群 GPU 资源总量
kubectl get nodes -o json | jq '.items[].status.allocatable'

# 查看已分配资源
kubectl get pods -A -o json | jq '[.items[] | select(.spec.containers[].resources.limits["nvidia.com/gpu"] != null)]'

显存/算力分配不正确

# 查看 Pod 注解中的分配信息
kubectl get pod <pod-name> -o jsonpath='{.metadata.annotations}' | jq .

# 检查容器内可见的 GPU
kubectl exec <pod-name> -- nvidia-smi
kubectl exec <pod-name> -- env | grep CUDA

设备问题

GPU 不被识别

# 在 GPU 节点上检查
nvidia-smi # 驱动是否正常
nvidia-smi -q -d P2P # GPU 间通信

# 检查设备文件
ls -la /dev/nvidia*

# 检查容器运行时
nvidia-ctk --version

设备健康检查失败

# 检查 GPU 健康状态
nvidia-smi -q -d HEALTH

# 查看设备插件健康检查日志
kubectl logs -n hami-system daemonset/hami-device-plugin | grep -i health

# 手动触发节点清理
kubectl annotate node <node-name> hami.io/device-cleanup="true"

硬件兼容性

问题	检查	解决
驱动版本过低	`nvidia-smi`	升级到 >= 510.47
CUDA 版本不兼容	`nvcc --version`	升级到 >= 11.6
MIG 模式不匹配	`nvidia-smi -mig`	检查 MIG 配置
NVML 初始化失败	设备插件日志	检查驱动安装

运行时问题

容器内看不到 GPU

# 检查环境变量
kubectl exec <pod-name> -- env | grep -E "CUDA|NVIDIA"

# 检查设备挂载
kubectl exec <pod-name> -- ls -la /dev/nvidia*

# 检查注解
kubectl get pod <pod-name> -o jsonpath='{.metadata.annotations}' | jq .

CUDA 错误

# 常见 CUDA 错误
# CUDA_ERROR_OUT_OF_MEMORY → 显存不足，减少 nvidia.com/gpumem
# CUDA_ERROR_NO_DEVICE → 设备不可见，检查设备插件
# CUDA_ERROR_INVALID_DEVICE → 设备 ID 错误，检查 CUDA_VISIBLE_DEVICES

调试工具

kubectl 命令集

# 查看所有 HAMi 组件状态
kubectl get all -n hami-system

# 查看调度器日志（带时间戳）
kubectl logs -n hami-system deployment/hami-scheduler --timestamps --tail=200

# 查看设备插件日志
kubectl logs -n hami-system daemonset/hami-device-plugin -c nvidia --tail=200

# 查看 Webhook 日志
kubectl logs -n hami-system deployment/hami-webhook --tail=200

# 查看节点设备注解
kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.annotations.*}{"\n"}{end}'

性能分析

# 启用 pprof（需要在启动参数中添加）
kubectl port-forward -n hami-system deployment/hami-scheduler 6060:6060

# 查看 CPU profile
go tool pprof http://localhost:6060/debug/pprof/profile

# 查看内存 profile
go tool pprof http://localhost:6060/debug/pprof/heap

标准化错误码

错误码	含义	排查方向
`SCHED_INSUFFICIENT_GPU_MEMORY`	显存不足	减少请求或增加 GPU
`SCHED_DEVICE_TYPE_MISMATCH`	设备类型不匹配	检查注解
`SCHED_QUOTA_EXCEEDED`	配额超限	调整 ResourceQuota
`SCHED_NO_HEALTHY_DEVICE`	无健康设备	检查 GPU 状态
`SCHED_NODE_LOCKED`	节点锁定	等待或清理锁
`DP_ALLOCATE_FAILED`	设备分配失败	检查设备插件日志
`DP_NVML_INIT_FAILED`	NVML 初始化失败	检查驱动
`WH_QUOTA_CHECK_FAILED`	配额检查失败	检查 ResourceQuota
`WH_INVALID_RESOURCE`	无效资源请求	检查资源字段

社区支持

GitHub Issues：https://github.com/project-hami/hami/issues
Discord：HAMi 社区 Discord

提交 Issue 时建议附上：

# 收集诊断信息
kubectl cluster-info
kubectl get nodes -o wide
kubectl get pods -n hami-system -o wide
kubectl logs -n hami-system deployment/hami-scheduler --tail=100
kubectl describe pod <problematic-pod>

小结

本章介绍了 HAMi 的故障排查体系：

系统化流程：从问题现象到根因定位
部署问题：Pod 启动失败、证书错误、注册失败
调度问题：Pending、过滤失败、评分异常
设备问题：GPU 不识别、健康检查失败、兼容性
调试工具：kubectl 命令集、pprof 性能分析
错误码标准化：错误码辅助快速定位

参考资料

性能调优

Jimmy Song — Thu, 04 Jun 2026 08:27:48 +0000

性能调优的目标是最大化 GPU 利用率、最小化调度延迟、确保工作负载稳定运行。

性能指标与目标

指标	度量方式	目标值
调度延迟	Pod 创建到 Running 的时间	< 5s
GPU 利用率	实际计算时间 / 总时间	> 70%
显存利用率	已用显存 / 总显存	> 60%
调度成功率	成功绑定 / 总调度请求	> 99%
设备分配延迟	Allocate 调用耗时	< 500ms

调度性能优化

策略选择

策略	调度速度	利用率	适用场景
binpack	快	高	推理集群、成本优化
spread	快	中	高可用场景
topology-aware	慢	高	训练集群

binpack 策略计算最简单，调度速度最快。拓扑感知需要查询 GPU 拓扑信息，增加调度延迟。

节点缓存优化

HAMi 调度器通过 Informer 缓存节点和 Pod 信息，避免重复查询 API Server：

scheduler:
 # 缓存同步间隔（影响缓存新鲜度）
 cacheSyncPeriod: 30s

 # 节点设备缓存刷新间隔
 deviceCacheRefreshPeriod: 30s

并发调度

scheduler:
 # 并发调度协程数
 concurrentSchedules: 10

批量处理

对于大量 Pod 同时调度的场景（如 Deployment 扩容），建议：

使用优先级确保关键工作负载先调度
配置 Pod Disruption Budget 避免批量驱逐

资源配置优化

显存分配策略

原则：显存请求应略大于实际使用量（预留 10-20% 安全余量）

推理场景：
 - 模型权重 + KV Cache + 框架开销 = 实际显存需求
 - 请求显存 = 实际需求 × 1.1

训练场景：
 - 模型权重 + 梯度 + 优化器状态 + 激活值 = 实际需求
 - 建议独占 GPU，不共享

算力分配比例

# 推理场景：算力共享效果好
resources:
 limits:
 nvidia.com/gpu: 1 # 使用 1 个 GPU
 nvidia.com/cores: 30 # 30% 算力限制
 nvidia.com/gpumem: 4000 # 4GB 显存

# 训练场景：不共享算力
resources:
 limits:
 nvidia.com/gpu: 1 # 独占
 nvidia.com/gpumem: 40000 # 40GB 显存

超卖配置调优

scheduler:
 overcommit:
 enabled: true
 # 推理场景可以适度超卖
 deviceMemoryScaling: 1.2 # 显存超卖 20%
 deviceCoreScaling: 1.0 # 算力不超卖

 # 注意：超卖会增加资源争用风险
 # 建议配合监控观察实际利用率

切分数量优化

devicePlugin:
 nvidia:
 # splitCount 决定每张 GPU 最多分配给几个 Pod
 # 值越大，共享密度越高，但每个 Pod 获得的算力越少
 splitCount: 10 # 默认值

 # 推理场景推荐：5-20（根据模型大小调整）
 # 开发场景推荐：10-20（多人共享）
 # 训练场景推荐：1（独占）

系统级调优

NUMA 亲和性

GPU 和 CPU 的 NUMA 拓扑影响数据传输性能：

# 查看 NUMA 拓扑
lscpu | grep NUMA
nvidia-smi topo -m

# 确保 Pod 调度到 GPU 所在的 NUMA 节点
# HAMi 的拓扑感知调度可以自动处理

# 启用拓扑感知
scheduler:
 policy:
 gpuSchedulerPolicy: topology

CPU 管理策略

# 对性能敏感的工作负载使用 static CPU 管理策略
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
cpuManagerPolicy: static

内核参数

# 增加 GPU 相关的内存锁定限制
ulimit -l unlimited

# 调整 I/O 调度器（推荐使用 none/mq-deadline）
cat /sys/block/nvme0n1/queue/scheduler

# 禁用 GPU 的自适应电源管理（性能优先）
nvidia-smi -pm 1 # 启用 Persistence Mode
nvidia-smi -pl 300 # 设置功率限制

网络优化

多卡训练场景对网络带宽敏感：

# 检查 NCCL 环境变量
export NCCL_DEBUG=INFO
export NCCL_SOCKET_IFNAME=eth0 # 指定网络接口
export NCCL_IB_DISABLE=0 # 启用 InfiniBand（如果可用）

性能基准测试

调度器基准测试

# 批量创建 Pod 测试调度吞吐
for i in $(seq 1 100); do
 cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
 name: bench-$i
spec:
 containers:
 - name: bench
 image: busybox
 command: ["sleep", "3600"]
 resources:
 limits:
 nvidia.com/gpu: 1
 nvidia.com/gpumem: 1000
 restartPolicy: Never
EOF
done

# 测量调度延迟
kubectl get pods -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.startTime}{"\n"}{end}'

GPU 利用率基准测试

# 在 Pod 内运行 GPU 压力测试
kubectl exec <pod-name> -- python3 -c "
import torch
# 创建张量占用显存
x = torch.randn(10000, 10000, device='cuda')
# 矩阵运算测试算力
for _ in range(1000):
 y = torch.matmul(x, x)
print('Benchmark complete')
"

vLLM 推理基准测试

# 使用 vLLM benchmark 工具
python -m vllm.entrypoints.openai.api_server \
 --model <model-name> \
 --tensor-parallel-size 2 \
 --gpu-memory-utilization 0.9

# 使用 benchmark_client 测试吞吐
python benchmark_serving.py \
 --model <model-name> \
 --dataset-name random \
 --random-input-len 1024 \
 --random-output-len 256 \
 --num-prompts 1000

大规模集群优化

节点数量扩展

扩展建议：
 - 每增加 50 个 GPU 节点，调度器增加 0.5 core CPU
 - 监控调度延迟，超过 5s 时考虑扩容调度器
 - 使用 topology-aware 策略时，调度延迟会随节点数增加

GPU 数量扩展

扩展建议：
 - 单节点 8 GPU 是常见配置
 - 超过 100 张 GPU 时考虑分区域调度
 - 使用 nodeSelector/affinity 限制调度范围

调度器性能瓶颈分析

# 启用 pprof
kubectl port-forward -n hami-system deployment/hami-scheduler 6060:6060

# CPU 分析（30 秒采样）
curl -o cpu.prof http://localhost:6060/debug/pprof/profile?seconds=30
go tool pprof cpu.prof

# 内存分析
curl -o mem.prof http://localhost:6060/debug/pprof/heap
go tool pprof mem.prof

性能调优清单

选择合适的调度策略（推理→binpack，训练→topology）
配置合理的 splitCount（推理 5-20，训练 1）
显存请求预留 10-20% 安全余量
启用 NUMA 亲和性（拓扑感知策略）
设置 GPU Persistence Mode
监控实际 GPU 利用率，调整超卖系数
大规模集群使用分区调度
定期运行性能基准测试

小结

本章介绍了 HAMi 的性能调优方法：

调度优化：策略选择、缓存、并发
资源配置：显存、算力、超卖、切分数量
系统级调优：NUMA、CPU、内核、网络
基准测试：调度器吞吐、GPU 利用率、vLLM
大规模优化：节点扩展、分区调度

参考资料

常见问题

Jimmy Song — Thu, 04 Jun 2026 08:27:30 +0000

安装与部署

HAMi 最低 Kubernetes 版本要求是什么？

Kubernetes >= 1.18。HAMi 通过标准的 Scheduler Extender 和 Device Plugin API 与 Kubernetes 集成，不需要修改 Kubernetes 源码。

是否需要卸载 NVIDIA 官方设备插件？

是的。 HAMi 使用自研设备插件，与 NVIDIA 官方设备插件不兼容。安装 HAMi 前需要先卸载 nvidia-device-plugin：

kubectl delete daemonset nvidia-device-plugin-daemonset -n kube-system

如何验证安装是否成功？

# 检查所有组件状态
kubectl get pods -n hami-system

# 检查 GPU 节点是否注册设备
kubectl describe node <gpu-node> | grep hami

# 运行测试 Pod
kubectl run gpu-test --image=nvidia/cuda:12.0.0-base-ubuntu22.04 \
 --restart=Never --command -- nvidia-smi \
 --limits=nvidia.com/gpu=1,nvidia.com/gpumem=2000

如何在离线环境部署？

提前拉取 HAMi 镜像并导入到离线仓库
使用 helm template 生成 YAML 清单
在离线环境中 kubectl apply 清单文件

# 生成清单
helm template hami hami-charts/hami -n hami-system -f values.yaml > hami.yaml

# 在离线环境应用
kubectl apply -f hami.yaml

资源配置

nvidia.com/gpu 和 nvidia.com/gpumem 的含义？

nvidia.com/gpu：GPU 设备数量。值 N 表示使用 N 个 GPU 设备，每个设备分配 nvidia.com/gpumem 指定的显存
nvidia.com/gpumem：显存大小，单位 MB。如 4000 表示 4GB

如何按百分比分配显存？

使用 nvidia.com/gpumem-percentage 替代 nvidia.com/gpumem：

resources:
 limits:
 nvidia.com/gpu: 1 # 使用 1 个 GPU
 nvidia.com/gpumem-percentage: 40 # 该 GPU 的 40% 显存

资源超卖如何配置？

在 Helm values.yaml 中设置超卖系数：

scheduler:
 overcommit:
 enabled: true
 deviceMemoryScaling: 1.5 # 显存超卖 1.5 倍
 deviceCoreScaling: 1.2 # 算力超卖 1.2 倍

超卖增加资源争用风险，建议只在推理场景使用并配合监控。

一个 GPU 最多分配给多少个 Pod？

由 splitCount 配置决定：

devicePlugin:
 nvidia:
 splitCount: 10 # 最多 10 个 Pod 共享 1 张 GPU

实际限制取决于 GPU 显存大小和每个 Pod 的显存请求。

调度策略

binpack 和 spread 如何选择？

场景	推荐策略	原因
成本优化	binpack	集中使用 GPU，减少空闲资源
高可用	spread	分散负载，单节点故障影响小
GPUaaS	binpack	最大化 GPU 密度
训练集群	spread + topology	分散 + 拓扑优化

拓扑感知策略需要什么条件？

NVIDIA GPU
已安装 NVML 库
多卡节点有 NVLink/PCIe 拓扑信息
工作负载需要多卡协作（如分布式训练）

如何指定调度策略？

通过 Pod 注解：

metadata:
 annotations:
 hami.io/node-scheduler-policy: "binpack"
 hami.io/gpu-scheduler-policy: "spread"

或在 Helm values.yaml 中设置全局默认策略。

调度失败如何排查？

# 查看 Pod 事件
kubectl describe pod <pod-name>

# 查看调度器日志（v5 显示设备细节）
kubectl logs -n hami-system deployment/hami-scheduler | grep <pod-name>

多厂商设备

支持哪些厂商的设备？

当前官方文档列出的设备包括 NVIDIA GPU、华为昇腾 NPU、寒武纪 MLU、海光 DCU、天数智芯 GPU、摩尔线程 GPU、沐曦 GPU、燧原 GCU、昆仑芯 XPU、瀚博半导体 GPU，以及适配中的 Teco DPU。

如何在同一集群使用多种设备？

为不同设备节点打标签
通过 hami.io/gpu-type 注解指定设备类型

kubectl label nodes node-nvidia accelerator=nvidia
kubectl label nodes node-ascend accelerator=ascend

国产设备需要注意什么？

确保驱动和容器运行时已正确安装
不同设备的资源名可能不同（如 huawei.com/Ascend910B3 vs nvidia.com/gpu）
部分设备的多卡支持可能尚未启用
参考各厂商的 HAMi 适配文档

性能与稳定性

GPU 共享对性能有影响吗？

有影响，但取决于场景：

推理场景影响通常很小（<10%），因为推理主要是显存占用，计算时间短
训练场景不建议共享，训练对算力和带宽要求高
关键因素：共享的 Pod 数量和算力/显存分配比例

如何评估性能影响？

# 1. 独占 GPU 运行基准测试
# 2. 共享 GPU 运行相同测试
# 3. 对比吞吐量和延迟

# 使用 nvidia-smi 监控 GPU 利用率
watch -n 1 nvidia-smi

生产环境推荐配置？

调度器 2-3 副本 + 反亲和性
设备插件 DaemonSet
Webhook 2 副本
启用 Prometheus 监控
配置资源限制和优先级

如何处理 GPU 故障？

HAMi 通过健康检查自动检测 GPU 故障：

设备插件检测到 GPU 不健康
自动将故障 GPU 从资源池中移除
已调度到故障 GPU 的 Pod 会被标记为异常
修复硬件后，设备插件自动重新注册

升级与迁移

如何升级 HAMi 版本？

helm repo update
helm upgrade hami hami-charts/hami -n hami-system -f values.yaml

升级期间正在运行的 Pod 不受影响。

从原生 K8s GPU 调度迁移到 HAMi？

卸载 NVIDIA 官方设备插件
安装 HAMi Helm Chart
将 Pod 的 nvidia.com/gpu 改为 nvidia.com/gpu + nvidia.com/gpumem
逐步迁移，两种方式可以暂时共存

其他

HAMi 与 K8s DRA 的关系？

DRA（Dynamic Resource Allocation）是 Kubernetes 1.26+ 引入的新设备管理机制。HAMi 目前使用 Scheduler Extender 模式，同时提供了可选的 DRA 支持（hami-dra 子 Chart）。两者可以互补。

是否支持 Windows 容器？

目前不支持。HAMi 的设备插件依赖 Linux 特定的设备路径和运行时。

如何参与社区贡献？

GitHub：https://github.com/project-hami/hami
Discord: https://discord.gg/Amhy7XmbNq

术语表

Jimmy Song — Thu, 04 Jun 2026 08:27:35 +0000

Kubernetes 术语

Pod：Kubernetes 最小调度单元，包含一个或多个容器。

Node：Kubernetes 集群中的工作节点，运行 Pod 和工作负载。

Scheduler：Kubernetes 控制平面组件，负责将 Pod 调度到合适的节点。

Device Plugin：Kubernetes 设备插件框架，允许第三方设备厂商向 kubelet 注册设备资源。

Admission Webhook：准入控制 Webhook，在对象持久化前拦截和修改请求。分为 Mutating（修改）和 Validating（校验）两种。

ResourceQuota：命名空间级别的资源配额限制，控制资源使用总量。

ConfigMap：存储非敏感配置数据的 Kubernetes 对象。

Informer：Kubernetes 客户端缓存机制，通过事件驱动保持本地缓存与 API Server 同步。

DaemonSet：确保每个（或特定）节点运行一个 Pod 副本的控制器。

Scheduler Extender：调度器扩展机制，通过 HTTP 接口扩展默认调度器的 Filter/Score/Bind 流程。

RBAC：Role-Based Access Control，基于角色的访问控制。

Affinity / Anti-Affinity：亲和性/反亲和性规则，控制 Pod 调度到哪些节点。

GPU 术语

GPU：Graphics Processing Unit，图形处理单元，广泛用于 AI 计算的并行处理器。

VRAM / 显存：Video Random Access Memory，GPU 专用内存，存储模型权重、激活值等数据。

CUDA：Compute Unified Device Architecture，NVIDIA 的 GPU 并行计算平台和编程模型。

NVML：NVIDIA Management Library，NVIDIA GPU 管理库，提供 GPU 监控和管理 API。

SM (Streaming Multiprocessor)：流多处理器，GPU 的计算核心单元。

MIG (Multi-Instance GPU)：NVIDIA A100/H100 等 GPU 的硬件级分区功能，将一张 GPU 切分为多个独立实例。

NVLink：NVIDIA 的高速 GPU 互联技术，带宽远高于 PCIe。

NVSwitch：NVIDIA 的 GPU 交换芯片，支持多 GPU 全互联。

NUMA (Non-Uniform Memory Access)：非统一内存访问，多处理器系统中内存访问延迟不一致的架构。

PCIe：Peripheral Component Interconnect Express，GPU 与 CPU 通信的标准总线接口。

Persistence Mode：NVIDIA GPU 的持久化模式，保持 GPU 驱动加载状态，减少初始化延迟。

HAMi 术语

HAMi：Heterogeneous AI Computing Virtualization Middleware，异构 AI 计算虚拟化中间件。CNCF Sandbox 项目。

Scheduler Extender（调度器扩展器）：HAMi 的调度组件，通过 HTTP 接口扩展 Kubernetes 调度器，实现 GPU 感知的 Filter/Score/Bind。

Device Plugin（设备插件）：HAMi 的设备管理组件，以 DaemonSet 运行在每个加速器节点上，负责设备发现、注册和资源分配。

Monitor（监控器）：HAMi 的监控组件，采集 GPU 资源使用指标并通过 HTTP 暴露给 Prometheus。

Webhook：HAMi 的准入控制组件，拦截 Pod 创建请求，注入调度器名称和设备相关配置。

注解协议（Annotation Protocol）：HAMi 组件间通过 Pod/Node 注解传递设备分配信息的编码规范。

Filter/Score/Bind：调度三段式流程。Filter 过滤可行节点，Score 评分排序，Bind 绑定 Pod 到最优节点。

DeviceInfo：设备信息数据结构，描述 GPU ID、显存、核心数、NUMA、健康状态等。

DeviceUsage：设备使用量数据结构，描述设备已分配的显存、核心数和关联的 Pod 信息。

Fit：设备匹配算法，判断节点上的设备能否满足 Pod 的资源请求。

节点锁（Node Lock）：基于节点注解的并发控制机制，防止多个调度器同时绑定同一节点。

领导者选举（Leader Election）：多副本调度器通过 Kubernetes Lease 机制选举活跃实例，避免调度冲突。

超卖（Overcommit）：资源超分配策略，允许分配的显存/算力总量超过物理资源。

切分（Split）：将一张物理 GPU 按显存和算力拆分为多份，供多个 Pod 共享使用。

设备术语

NVIDIA GPU：NVIDIA 的图形处理器，如 A100、H100、A10、T4 等。HAMi 支持最完整的设备后端。

Ascend NPU：华为昇腾神经网络处理器，如 910B2、910B3 等。支持 VNPU 软切分。

Cambricon MLU：寒武纪机器学习单元，如 MLU370 等。

Hygon DCU：海光深度计算单元，国产 AI 加速器。

AMD GPU：AMD 的图形处理器，如 Instinct MI250 等。

Moore Threads XPU：摩耳线程的扩展处理器单元。

Enflame GCU：炎魂的通用计算单元。

AWS Neuron：AWS 的专用 AI 推理/训练芯片（Inferentia/Trainium）。

Vast.ai：Vast.ai 平台的 GPU 加速器。

调度策略术语

binpack：密集策略，优先调度到资源利用率最高的节点/GPU，实现装箱效果。

spread：分散策略，优先调度到资源利用率最低的节点/GPU，实现负载均衡。

topology-aware：拓扑感知策略，利用 GPU 互联拓扑（NVLink/NVSwitch）优化设备组合选择。

动态 MIG：根据工作负载需求动态创建/销毁 MIG 实例的策略。

节点级策略（Node Policy）：控制 Pod 在不同节点间分布的策略（binpack/spread）。

GPU 卡级策略（GPU Policy）：控制 Pod 在同一节点的不同 GPU 卡间分布的策略。

CDI (Container Device Interface)：容器设备接口规范，标准化容器运行时的设备注入方式。

监控术语

Prometheus：开源监控系统和时序数据库，HAMi 通过 HTTP 端点暴露指标供其采集。

Grafana：开源可视化平台，用于创建 GPU 资源监控仪表盘。

ServiceMonitor：Prometheus Operator 的自定义资源，定义指标采集目标和间隔。

pprof：Go 语言性能分析工具，用于分析调度器的 CPU 和内存使用。