From 190002dd0e25f0407c997a0d3e9f409d8cc074e8 Mon Sep 17 00:00:00 2001 From: Shaurya Mishra Date: Fri, 14 Aug 2026 11:01:38 +0530 Subject: [PATCH] docs: add concept-to-lab cross-links (addresses #656) Signed-off-by: Shaurya Mishra --- docs/core-concepts/architecture.md | 8 ++++++++ docs/core-concepts/ecosystem-integrations.md | 10 ++++++++++ docs/core-concepts/gpu-driver.md | 8 ++++++++ docs/core-concepts/gpu-stack.md | 9 +++++++++ docs/core-concepts/gpu-virtualization.md | 10 ++++++++++ docs/core-concepts/hami-architecture.md | 9 +++++++++ .../current/core-concepts/architecture.md | 8 ++++++++ .../current/core-concepts/ecosystem-integrations.md | 10 ++++++++++ .../current/core-concepts/gpu-driver.md | 8 ++++++++ .../current/core-concepts/gpu-stack.md | 9 +++++++++ .../current/core-concepts/gpu-virtualization.md | 10 ++++++++++ .../current/core-concepts/hami-architecture.md | 9 +++++++++ 12 files changed, 108 insertions(+) diff --git a/docs/core-concepts/architecture.md b/docs/core-concepts/architecture.md index 9a4e832d8..3a6fbd52c 100644 --- a/docs/core-concepts/architecture.md +++ b/docs/core-concepts/architecture.md @@ -28,3 +28,11 @@ The device-plugin layer obtains the scheduling result from the annotations field ## HAMi-Core {#hami-core} The in-container resource control is responsible for monitoring the resource usage within the container and providing hard isolation capabilities. + +:::tip Try it yourself + +See these components in action with a hands-on lab: + +- [Lab 1: Online Installation of HAMi](/tutorials/labs/online-install) — deploy all four components and verify they are running in your cluster + +::: diff --git a/docs/core-concepts/ecosystem-integrations.md b/docs/core-concepts/ecosystem-integrations.md index 0633034f9..d328f1edb 100644 --- a/docs/core-concepts/ecosystem-integrations.md +++ b/docs/core-concepts/ecosystem-integrations.md @@ -100,3 +100,13 @@ HAMi-core fills it. **KAI Scheduler does the scheduling, HAMi-core does the isol | NVIDIA stacks, gang-scheduled training or batch needing hard isolation | KAI Scheduler | NVIDIA-native gang scheduling, fair queues, fractional GPU, plus HAMi-core hard isolation | > HAMi's own two-level `nvidia.com/priority` is a **runtime** preemption mechanism scoped to a single GPU. If you need **scheduling-level** multi-level priority across a queue of jobs, combine HAMi with one of the partners above. See the [FAQ](../faq/faq.md) for details. + +:::tip Try it yourself + +Try these ecosystem integrations in hands-on labs: + +- [Lab 8: Volcano vGPU with Gang Scheduling and Queues](/tutorials/labs/volcano-vgpu-gang-queue) — deploy Volcano alongside HAMi and test gang scheduling with GPU shares +- [Lab 9: Queue HAMi vGPU Workloads with Kueue](/tutorials/labs/kueue-hami-vgpu) — set up Kueue ResourceFlavors for HAMi vGPUs and enforce queue-level quotas +- [Lab 12: Verify KAI Scheduler and HAMi Memory Isolation on GKE](/tutorials/labs/kai-scheduler-hami-gke) — combine KAI Scheduler with HAMi-core for hard GPU isolation + +::: diff --git a/docs/core-concepts/gpu-driver.md b/docs/core-concepts/gpu-driver.md index 94dcee00a..25d00142f 100644 --- a/docs/core-concepts/gpu-driver.md +++ b/docs/core-concepts/gpu-driver.md @@ -89,3 +89,11 @@ Call chain: - If `lsmod` shows the nvidia module but `nvidia-smi` reports an error, the problem is at the user-space library or permission level Therefore, when troubleshooting GPU issues, it is recommended to start with `lsmod | grep nvidia` to confirm the kernel module status, and then use `nvidia-smi` to check whether user space is functioning normally. + +:::tip Try it yourself + +Explore GPU driver internals with a hands-on lab: + +- [Lab 5: Fake-GPU Scheduling with nvml-mock](/tutorials/labs/nvml-mock) — simulate NVML device discovery and see how the driver layer reports GPU resources to Kubernetes + +::: diff --git a/docs/core-concepts/gpu-stack.md b/docs/core-concepts/gpu-stack.md index 6da4b65f9..fe1d4f315 100644 --- a/docs/core-concepts/gpu-stack.md +++ b/docs/core-concepts/gpu-stack.md @@ -216,3 +216,12 @@ graph LR | **GPU Operator** | NVIDIA Operator, automates deployment and management of the full GPU software stack | | **HAMi** | GPU virtualization middleware, supporting fine-grained partitioning and sharing of memory and compute | | **HAMi Device Plugin** | HAMi's device plugin, replaces the native Device Plugin and supports GPU partition reporting | + +:::tip Try it yourself + +Explore the GPU software stack with hands-on labs: + +- [Lab 1: Online Installation of HAMi](/tutorials/labs/online-install) — walk through every layer of the stack from driver to HAMi scheduler +- [Lab 5: Fake-GPU Scheduling with nvml-mock](/tutorials/labs/nvml-mock) — see how the NVML layer and Device Plugin interact without real GPU hardware + +::: diff --git a/docs/core-concepts/gpu-virtualization.md b/docs/core-concepts/gpu-virtualization.md index cf1047dd5..57ec601a0 100644 --- a/docs/core-concepts/gpu-virtualization.md +++ b/docs/core-concepts/gpu-virtualization.md @@ -248,3 +248,13 @@ Here are some recommended next steps: - Learn about HAMi's [architecture](./architecture.md) - [Install HAMi](../installation/prerequisites.md) in your Kubernetes cluster + +:::tip Try it yourself + +Put these concepts into practice with the following hands-on labs: + +- [Lab 3: GPU Partitioning with HAMi](/tutorials/labs/gpu-partitioning) — partition a single GPU across multiple Pods and verify VRAM limits +- [Lab 7: GPU Isolation on k3s Without the GPU Operator](/tutorials/labs/hami-isolation-k3s) — verify end-to-end memory isolation on a lightweight cluster +- [Lab 6: Run vLLM on HAMi GPU Shares](/tutorials/labs/hami-vllm) — serve an LLM on shared GPU resources with HAMi + +::: diff --git a/docs/core-concepts/hami-architecture.md b/docs/core-concepts/hami-architecture.md index 0354d04e3..d35e51c55 100644 --- a/docs/core-concepts/hami-architecture.md +++ b/docs/core-concepts/hami-architecture.md @@ -360,3 +360,12 @@ Throughout this process, each layer fulfills its role: Kubernetes provides the s | Visualization Layer | HAMi WebUI | GPU resource visualization | Once you understand the responsibilities and dependencies of these components, you can quickly identify which layer has a problem when issues arise in the cluster: if Pods cannot be scheduled, check the scheduling layer; if GPUs are unavailable, check the Runtime Stack; if metrics are missing, check the monitoring layer. + +:::tip Try it yourself + +Explore the HAMi cluster architecture with hands-on labs: + +- [Lab 2: Local Fake GPU Setup](/tutorials/labs/local-fake-gpu) — build a local HAMi cluster without real GPU hardware and inspect each architectural layer +- [Lab 5: Fake-GPU Scheduling with nvml-mock](/tutorials/labs/nvml-mock) — simulate GPU device discovery and trace the scheduling flow through all layers + +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/core-concepts/architecture.md b/i18n/zh/docusaurus-plugin-content-docs/current/core-concepts/architecture.md index 1d22b59d9..8b15ee805 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/core-concepts/architecture.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/core-concepts/architecture.md @@ -29,3 +29,11 @@ HAMi 调度器负责将任务分配给适当的节点和设备。同时，调度 ## HAMi-Core {#hami-core} 容器内资源控制负责监控容器内的资源使用情况，并提供硬隔离能力。 + +:::tip 动手实践 + +通过动手实验来了解这些组件的实际运行： + +- [Lab 1: 在线安装 HAMi](/tutorials/labs/online-install) — 部署全部四个组件，并验证它们在集群中正常运行 + +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/core-concepts/ecosystem-integrations.md b/i18n/zh/docusaurus-plugin-content-docs/current/core-concepts/ecosystem-integrations.md index b7cf53071..a4972f615 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/core-concepts/ecosystem-integrations.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/core-concepts/ecosystem-integrations.md @@ -100,3 +100,13 @@ HAMi-core 补上的就是这一块。**调度交给 KAI Scheduler，隔离交给 | NVIDIA 技术栈、成团调度的训练或批处理、需要硬隔离 | KAI Scheduler | NVIDIA 原生的成团调度、公平队列、GPU 分片，外加 HAMi-core 硬隔离 | > HAMi 自带的两级 `nvidia.com/priority` 是一种**运行时**抢占机制，作用范围是单张 GPU。如果你要对一整列作业做**调度级**的多级优先，那就把 HAMi 和上面任意一个伙伴组合起来用。细节可以看 [FAQ](../faq/faq.md)。 + +:::tip 动手实践 + +通过动手实验体验这些生态集成： + +- [Lab 8: Volcano vGPU 成团调度与队列](/tutorials/labs/volcano-vgpu-gang-queue) — 将 Volcano 与 HAMi 一起部署，测试 GPU 共享下的成团调度 +- [Lab 9: 使用 Kueue 排队 HAMi vGPU 工作负载](/tutorials/labs/kueue-hami-vgpu) — 为 HAMi vGPU 设置 Kueue ResourceFlavor，实施队列级配额 +- [Lab 12: 在 GKE 上验证 KAI Scheduler 与 HAMi 显存隔离](/tutorials/labs/kai-scheduler-hami-gke) — 将 KAI Scheduler 与 HAMi-core 结合，实现硬 GPU 隔离 + +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/core-concepts/gpu-driver.md b/i18n/zh/docusaurus-plugin-content-docs/current/core-concepts/gpu-driver.md index 2cb339135..a98bc2638 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/core-concepts/gpu-driver.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/core-concepts/gpu-driver.md @@ -89,3 +89,11 @@ flowchart TB - 如果 `lsmod` 能看到 nvidia 模块但 `nvidia-smi` 报错，说明问题在用户态库或权限层面 因此在排查 GPU 问题时，建议先从 `lsmod | grep nvidia` 开始确认内核模块状态，再使用 `nvidia-smi` 检查用户态是否正常。 + +:::tip 动手实践 + +通过动手实验深入了解 GPU 驱动： + +- [Lab 5: 使用 nvml-mock 进行 Fake-GPU 调度](/tutorials/labs/nvml-mock) — 模拟 NVML 设备发现，观察驱动层如何向 Kubernetes 上报 GPU 资源 + +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/core-concepts/gpu-stack.md b/i18n/zh/docusaurus-plugin-content-docs/current/core-concepts/gpu-stack.md index 477d998a1..b8b6a0b37 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/core-concepts/gpu-stack.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/core-concepts/gpu-stack.md @@ -216,3 +216,12 @@ graph LR | **GPU Operator** | NVIDIA Operator，自动化部署和管理 GPU 相关的全栈组件 | | **HAMi** | GPU 虚拟化中间件，支持显存和算力的细粒度切分与共享 | | **HAMi Device Plugin** | HAMi 的设备插件，替代原生 Device Plugin，支持 GPU 切分上报 | + +:::tip 动手实践 + +通过动手实验探索 GPU 软件栈： + +- [Lab 1: 在线安装 HAMi](/tutorials/labs/online-install) — 从驱动到 HAMi 调度器，逐层走通整个栈 +- [Lab 5: 使用 nvml-mock 进行 Fake-GPU 调度](/tutorials/labs/nvml-mock) — 无需真实 GPU 硬件，观察 NVML 层和 Device Plugin 如何交互 + +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/core-concepts/gpu-virtualization.md b/i18n/zh/docusaurus-plugin-content-docs/current/core-concepts/gpu-virtualization.md index fbc06f14b..cb0befc4f 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/core-concepts/gpu-virtualization.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/core-concepts/gpu-virtualization.md @@ -249,3 +249,13 @@ GPU2 得分 = ((1+6)/10 + (20+70)/100 + (1000+6000)/8000) × 10 = 24.75 - 学习 HAMi 的[架构设计](./architecture.md) - 在你的 Kubernetes 集群中[安装 HAMi](../installation/prerequisites.md) + +:::tip 动手实践 + +通过以下动手实验将这些概念付诸实践： + +- [Lab 3: 使用 HAMi 进行 GPU 切分](/tutorials/labs/gpu-partitioning) — 将单张 GPU 切分给多个 Pod，并验证显存限制 +- [Lab 7: 在 k3s 上实现 GPU 隔离（无需 GPU Operator）](/tutorials/labs/hami-isolation-k3s) — 在轻量集群上端到端验证显存隔离 +- [Lab 6: 在 HAMi GPU 共享上运行 vLLM](/tutorials/labs/hami-vllm) — 使用 HAMi 共享 GPU 资源来提供大语言模型推理服务 + +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/core-concepts/hami-architecture.md b/i18n/zh/docusaurus-plugin-content-docs/current/core-concepts/hami-architecture.md index e664b6309..ddf8a4c7b 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/core-concepts/hami-architecture.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/core-concepts/hami-architecture.md @@ -360,3 +360,12 @@ sequenceDiagram | 可视化层 | HAMi WebUI | GPU 资源可视化 | 理解了这些组件的职责和依赖关系，当集群出现问题时，你可以快速定位是哪一层出了问题：Pod 无法调度看调度层，GPU 不可用看 Runtime Stack，指标缺失看监控层。 + +:::tip 动手实践 + +通过动手实验探索 HAMi 集群架构： + +- [Lab 2: 本地 Fake GPU 环境搭建](/tutorials/labs/local-fake-gpu) — 无需真实 GPU 硬件，搭建本地 HAMi 集群并逐层检查各架构层 +- [Lab 5: 使用 nvml-mock 进行 Fake-GPU 调度](/tutorials/labs/nvml-mock) — 模拟 GPU 设备发现，追踪调度流程在各层之间的流转 + +:::