Project-HAMi 深度阅读笔记

解决什么问题

• GPU/加速器利用率低：训练、推理、开发任务常常不需要独占整卡，HAMi 支持按显存和核心比例做部分分配。
• 异构设备 API 分裂：不同厂商的 GPU、NPU、MLU、DCU 暴露方式不同，HAMi 试图提供统一的 Kubernetes 入口。
• 调度只看数量不够：AI 设备调度需要考虑节点、卡、显存、核心、NUMA、拓扑和碎片化。
• 原生 Device Plugin 粒度粗：官方 device plugin 往往偏整卡分配；HAMi 使用定制插件和容器内控制层实现细粒度共享与隔离。
• 多租户缺少显存配额：HAMi 支持通过 Kubernetes ResourceQuota 管控 namespace 级 GPU 显存用量。

不是什么

• 不是只支持 NVIDIA 的 vGPU 项目。NVIDIA 是核心场景，但仓库已经覆盖多类异构设备。
• 不是模型推理框架，也不替代 vLLM、TensorRT、PyTorch 或推理网关。
• 不是完全透明的“装上就万无一失”的系统。它依赖定制 device plugin、节点标签、运行时配置、注解协议和各厂商隔离技术。
• 不是所有场景都适合共享。强隔离、安全合规、性能稳定性或大训练任务可能仍需要独占卡。

资源声明模型

用户通常仍然用 Kubernetes Pod 的 resources.limits 声明资源。以 NVIDIA 为例，最常见的资源键包括：

resources:
  limits:
    nvidia.com/gpu: 1
    nvidia.com/gpumem: 3000
    nvidia.com/gpucores: 30

Pod 注解能力

资源键表达“要多少”，注解表达“怎么调度、能用哪些卡、不能用哪些卡、使用哪种 vGPU 模式”。

节点注解协议

HAMi 用 Node 注解作为调度器和 device plugin 的协议层。device plugin 需要周期性上报设备规格，调度器据此构建全局设备视图。

• hami.io/node-handshake-{device-type}：握手状态和时间戳。
• hami.io/node-{device-type}-register：设备列表，包含 UUID、切分数量、显存、核心、类型、NUMA、健康状态等。
• 如果节点长时间未注册，调度器会将对应设备视为不可用。

这个协议的优点是实现简单、贴近 Kubernetes 对象模型；代价是注解内容必须保持一致，时间戳、健康状态和插件上报逻辑会直接影响调度正确性。

Pod 调度结果协议

调度器把最终设备分配结果写回 Pod 注解，节点侧 device plugin 再据此完成容器设备暴露。

• hami.io/devices-to-allocate：每个容器要分配的设备 UUID、设备类型、显存和核心。
• hami.io/device-node：调度目标节点。
• hami.io/device-schedule-time：调度时间。

这使调度决策成为 Kubernetes 对象的一部分，便于插件协作、监控和故障排查。

动态 MIG

动态 MIG 是 HAMi 2.5 之后的重要能力：用户无需提前在节点上创建 MIG 实例，HAMi 可以根据任务需求创建实例、切换 MIG 模板，并把 MIG 与 hami-core 统一到同一资源池。

• 适用于 NVIDIA Blackwell、Hopper、Ampere 等支持 MIG 的设备。
• 节点需要配置 operatingmode: mig。
• Pod 仍可通过 nvidia.com/gpu 和 nvidia.com/gpumem 申请资源。
• 如果未指定模式，任务可能被分配到 MIG 或 hami-core。
• 监控指标会暴露 HAMi 管理的 MIG 实例视图。

多租户配额

虚拟设备数量本身不能准确代表真实显存消耗，因此 HAMi 支持通过 Kubernetes ResourceQuota 对 namespace 级 GPU 显存做限制。

apiVersion: v1
kind: ResourceQuota
metadata:
  name: compute-resources
spec:
  hard:
    limits.nvidia.com/gpumem: 30000

这类能力适合平台团队限制团队/租户的显存总量，避免某个 namespace 因为大量小 vGPU 任务挤占整个集群。

Benchmark 解读

仓库 benchmark 文档使用 vLLM 对 Qwen3-8B 推理场景做对比，环境为 A100-SXM4-40GB 双卡。文档中的关键指标显示，新版本 HAMi 相比旧版本更接近原生 NVIDIA device plugin。

这个 benchmark 的重点不是证明“虚拟化零损耗”，而是说明 HAMi 的共享/隔离机制可以在典型推理负载中做到接近原生的延迟表现。

代码结构速记

• cmd/scheduler：调度器入口、metrics。
• cmd/vGPUmonitor：vGPU 监控组件。
• pkg/scheduler：调度主逻辑、节点管理、Webhook、路由、事件、打分。
• pkg/scheduler/policy：节点和 GPU 打分策略。
• pkg/device：设备抽象接口、Pod/Quota 管理、各设备实现。
• charts/hami：Helm Chart 和默认配置。
• examples：不同厂商设备的 Pod 示例。
• docs/develop：架构、协议、调度策略和路线图。

我会继续追的点

1. 各设备实现之间的隔离语义是否一致，尤其是“核心限制”和“显存限制”的硬度。
2. 动态 MIG 在繁忙节点上的切换代价、失败恢复和与外部 NVIDIA 组件的兼容性。
3. Scheduler extender 在大规模集群中的缓存一致性、leader election、节点锁和事件可观测性。
4. ResourceQuota 对多容器、多设备、多 namespace 场景的边界行为。
5. 和 Volcano、Kubeflow、KServe、Ray、vLLM 平台化栈的集成实践。

快速阅读路线

• README_cn.md：先理解定位、能力、安装和注意事项。
• docs/develop/design.md：看清组件分工。
• docs/develop/protocol.md：理解注解协议。
• docs/config_cn.md：掌握真实可调参数。
• dynamic-mig-support_cn.md：了解 MIG 方向。
• pkg/scheduler/webhook.go 与 score.go：从代码看准入和调度。