EnterpriseAI Platform

本文说明通过 Helm 在可访问 Chart 和镜像仓库的 Kubernetes 集群中部署 HAMi 商业产品。本文不包含离线安装流程。

💡 安装不等于激活。完成 Helm 安装后，组件可以运行；GPU 虚拟化和调度功能需要完成许可证激活后才能正常使用。

为什么选择在线安装

在线安装适用于具备 Kubernetes、Helm 和镜像仓库运维能力，并需要较高配置自由度的客户。组件版本、部署顺序和 values 配置可由客户按照自身基础设施与变更流程自行管理。

密瓜智能准备的 Zarf 离线包更适用于网络隔离或需要统一交付物的环境；当客户具备自主管理能力，并需要自行维护组件版本、镜像来源及配置时，选择在线 Helm 安装更合适。

部署范围与前置条件

组件选择

组件	何时安装	说明
HAMi Enterprise	所有集群	核心调度器与设备插件，必须安装。
NVIDIA GPU Operator	使用 NVIDIA GPU，且集群尚未具备驱动与运行时管理能力	HAMi 与 GPU Operator 的默认 device-plugin 不能同时启用。
昇腾设备插件	使用昇腾节点	在 HAMi 安装完成后部署，复用 HAMi 的设备配置 ConfigMap。
Prometheus 监控栈	需要采集 HAMi 或 GPU 指标，或部署 HAMi AI Platform	集群已有兼容的监控栈时无需重复安装。
HAMi AI Platform	需要平台控制台、工作负载管理和监控视图	可选；依赖 Gateway API 实现和监控能力。

前置检查

Kubernetes 版本不低于 1.24，并且运维终端已配置可用的 kubectl 和 Helm。
NVIDIA 节点应已具备 NVIDIA 驱动和 NVIDIA Container Toolkit，或由 NVIDIA GPU Operator 负责安装。
昇腾节点应先完成厂商驱动与运行时配置，并能被 Kubernetes 识别；本文只安装 HAMi 的昇腾设备插件。
安装 NVIDIA GPU Operator 时，必须禁用其默认 device-plugin，避免与 HAMi 冲突。

kubectl cluster-info
kubectl get nodes -o wide
helm version

在线安装

执行以下命令前，先确认当前 kubeconfig context 指向目标集群。建议将每个 Chart 的 values 文件纳入版本管理；中国大陆镜像仓库、商业 Chart 访问方式和生产环境 values 请向密瓜智能技术支持获取。

安装 NVIDIA GPU Operator（仅 NVIDIA 节点）

集群已安装 GPU Operator 时，不要重复安装，并确认 devicePlugin.enabled=false。GPU Operator 25.10 及更高版本默认启用 CDI；下方示例通过 cdi.enabled=false 显式关闭 CDI，以保持非 CDI 部署方式。如需使用 CDI，请移除该参数，并在安装或升级 HAMi 前按照为 HAMi 启用 NVIDIA CDI 支持完成 HAMi 侧配置。本手册不重复相关参数和验证步骤。cdi.default 自 GPU Operator 25.10 起已废弃并会被忽略。

helm repo add nvidia https://helm.ngc.nvidia.com/nvidia && helm repo update

helm install --wait --generate-name \
  -n gpu-operator --create-namespace \
  nvidia/gpu-operator \
  --set devicePlugin.enabled=false \
  --set dcgmExporter.serviceMonitor.enabled=false \
  --set cdi.enabled=false \
  --version=v25.10.1

部署 HAMi AI Platform 时，保持 dcgmExporter.serviceMonitor.enabled=false，由平台创建 NVIDIA DCGM Exporter 的 ServiceMonitor。仅部署 HAMi Enterprise、不部署 HAMi AI Platform 时，将该参数设置为 true。

示例 values 文件

请自行 mirror NVIDIA GPU Operator 镜像，并替换下方 values 中的镜像信息。

driver:
  repository: your-private-registry/nvidia
  image: driver
  version: "580.105.08"
  imagePullSecrets: [ "your-private-registry-secret" ]
  manager:
    image: k8s-driver-manager
    repository: your-private-registry/nvidia/cloud-native
    version: v0.9.1

toolkit:
  repository: your-private-registry/nvidia/k8s
  image: container-toolkit
  version: v1.18.1
  imagePullSecrets: [ "your-private-registry-secret" ]

devicePlugin:
  enabled: false
  repository: your-private-registry/nvidia
  image: k8s-device-plugin
  version: v0.18.1
  imagePullSecrets: [ "your-private-registry-secret" ]

dcgmExporter:
  repository: your-private-registry/nvidia/k8s
  image: dcgm-exporter
  version: 4.4.2-4.7.0-distroless
  serviceMonitor:
    enabled: false

gfd:
  repository: your-private-registry/nvidia
  image: k8s-device-plugin
  version: v0.18.1
  imagePullSecrets: [ "your-private-registry-secret" ]

migManager:
  repository: your-private-registry/nvidia/cloud-native
  image: k8s-mig-manager
  version: v0.13.1
  imagePullSecrets: [ "your-private-registry-secret" ]

vgpuDeviceManager:
  repository: your-private-registry/nvidia/cloud-native
  image: vgpu-device-manager
  version: v0.4.1
  imagePullSecrets: [ "your-private-registry-secret" ]

vfioManager:
  repository: your-private-registry/nvidia
  image: cuda
  version: 13.0.1-base-ubi9
  imagePullSecrets: [ "your-private-registry-secret" ]
  driverManager:
    image: k8s-driver-manager
    repository: your-private-registry/nvidia/cloud-native
    version: v0.9.1

sandboxDevicePlugin:
  repository: your-private-registry/nvidia
  image: kubevirt-gpu-device-plugin
  version: v1.4.0
  imagePullSecrets: [ "your-private-registry-secret" ]

validator:
  repository: your-private-registry/nvidia
  image: gpu-operator
  imagePullSecrets: [ "your-private-registry-secret" ]

node-feature-discovery:
  image:
    # source: registry.k8s.io/nfd/node-feature-discovery:v0.18.2
    repository: your-private-registry/nfd/node-feature-discovery
    tag: v0.18.2
    pullPolicy: IfNotPresent
  imagePullSecrets:
    - name: your-private-registry-secret

operator:
  repository: your-private-registry/nvidia
  image: gpu-operator
  imagePullSecrets: [ "your-private-registry-secret" ]
  initContainer:
    image: cuda
    repository: your-private-registry/nvidia
    version: 13.0.1-base-ubi9

cdi:
  enabled: false

安装监控栈（按需）

集群尚无 Prometheus 或兼容监控系统，且需要指标采集时，可以安装 kube-prometheus-stack。

helm install prometheus \
  oci://ghcr.io/prometheus-community/charts/kube-prometheus-stack \
  --version 72.3.0 \
  --namespace monitoring \
  --create-namespace \
  --set alertmanager.enabled=false \
  --set grafana.enabled=false

示例 values 文件

请自行 mirror kube-prometheus-stack 镜像，并替换下方 values 中的镜像信息。

global:
  imageRegistry: your-private-registry
  imagePullSecrets:
    - name: your-private-registry-secret

alertmanager:
  enabled: false

grafana:
  enabled: false

安装 HAMi Enterprise

helm install hami \
  oci://dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/charts/hami-enterprise \
  --version 2.9.0-r3 \
  --namespace hami-system \
  --create-namespace

示例 values 文件

以下配置通过 global.imageRegistry 和 global.imagePullSecrets 统一设置镜像仓库和拉取 Secret。请先将 Chart 所需镜像同步到私有仓库，并保持 Chart 默认的 repository 路径。

nameOverride: "hami"
fullnameOverride: "hami"

global:
  imageRegistry: your-private-registry
  imagePullSecrets:
    - your-private-registry-secret
  imageTag: "v2.9.0-r3"

scheduler:
  enabled: true
  leaderElect: false
  service:
    type: ClusterIP

devicePlugin:
  enabled: true
  service:
    type: ClusterIP

完整配置项见 HAMi Helm Chart Values Reference。

安装昇腾设备插件（仅昇腾节点）

本步骤必须在 HAMi 安装完成后执行。以下配置复用 hami-scheduler-device，避免设备配置由多个 Chart 同时管理。

nameOverride: "ascend-device-plugin"
fullnameOverride: "ascend-device-plugin"

image:
  repository: dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/dynamia-ai/ascend-device-plugin
  tag: "v1.3.0"
  pullPolicy: IfNotPresent

config:
  create: false
  existingDeviceConfigMapName: hami-scheduler-device

helm install ascend-device-plugin \
  oci://dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/dynamia-ai/charts/ascend-device-plugin \
  --version 0.1.1 \
  --namespace hami-system \
  -f ascend-device-plugin.yaml

启用 GPU 节点

HAMi device-plugin 仅在带有 gpu=on 标签的节点上启动。对每个需要由 HAMi 管理的 GPU 或昇腾节点执行：

kubectl label nodes <node-name> gpu=on

安装 HAMi AI Platform（可选）

仅在需要平台控制台时执行。本节不适用于只部署 HAMi Enterprise 的集群。

安装 Envoy Gateway

helm install eg \
  oci://docker.io/envoyproxy/gateway-helm \
  --version v1.6.2 \
  --namespace envoy-gateway-system \
  --create-namespace \
  --set global.images.envoyGateway.image=docker.io/envoyproxy/gateway:v1.6.2 \
  --set global.image.ratelimit.image=docker.io/envoyproxy/ratelimit:99d85510 \
  --set config.envoyGateway.gateway.controllerName=gateway.envoyproxy.io/gatewayclass-controller \
  --set config.envoyGateway.provider.type=Kubernetes

安装 HAMi AI Platform

helm install kantaloupe \
  oci://dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/charts/kantaloupe-chart \
  --version 0.20.1 \
  --namespace kantaloupe-system \
  --create-namespace \
  --set fullnameOverride=kantaloupe

示例 values 文件

以下配置通过 global.imageRegistry 和 global.imagePullSecrets 统一设置镜像仓库和拉取 Secret。请先将 Chart 所需镜像同步到私有仓库，并保持 Chart 默认的 repository 路径。生产部署前，还必须替换示例域名、证书名称和 JWT 配置。

fullnameOverride: kantaloupe

global:
  imageRegistry: your-private-registry
  imagePullSecrets:
    - your-private-registry-secret

apiserver:
  leaderElection:
    enabled: false
  logLevel: 5

auth:
  enabled: true
  jwtSecret: dev-secret

cloudtty:
  enabled: true

gateway:
  enabled: true
  hostnames:
    - dashboard.hami.run
  apiserverHostnames:
    - api.hami.run
  apiserverCors:
    enabled: true
    allowCredentials: true
    allowOrigins:
      - https://dashboard.dynamia.ai
      - https://dashboard.hami.run
  envoy:
    proxy:
      image:
        repository: envoyproxy/envoy
        tag: distroless-v1.36.3
    service:
      ports:
        http:
          nodePort: 30080
        https:
          nodePort: 30443
      type: NodePort
  listeners:
    - name: http
      port: 80
      protocol: HTTP
    - name: https
      port: 443
      protocol: HTTPS
      tls:
        certificateRef:
          name: dashboard-hami-run-tls
        redirectFromHttp: true

mpu:
  enabled: false

平台的服务暴露、平台管理员、认证与监控配置见 kantaloupe Helm Chart Values Reference。

安装后检查

核心组件

kubectl -n hami-system get pods
kubectl -n gpu-operator get pods
kubectl -n monitoring get pods
kubectl -n kantaloupe-system get pods

未部署的可选组件对应 Namespace 可能不存在，可忽略其查询结果。已部署组件的 Pod 应处于 Running 或 Completed 状态。

节点与监控

kubectl describe node <node-name>
kubectl api-resources --api-group=monitoring.coreos.com

如果使用 Prometheus，ServiceMonitor 的标签必须匹配 Prometheus.spec.serviceMonitorSelector；如果使用 VictoriaMetrics，标签必须匹配 VMServiceScrape.spec.serviceScrapeSelector。

可以在监控系统中查询以下 NVIDIA 相关指标，确认采集结果非空：

DCGM_FI_DEV_GPU_UTIL
HostCoreUtilization
GPUDeviceCoreAllocated

HAMi AI Platform（可选）

kubectl -n kantaloupe-system get pods
kubectl -n kantaloupe-system get svc

按部署时配置的服务入口访问平台，确认控制台可以正常打开。

许可证申请与激活

获取许可证信息

申请许可证前，任选以下一种方法获取授权申请信息。两种方法作用相同，无需重复执行。

方法一：运行收集脚本

在所有已选组件启动后执行。运行环境需要 kubectl 和 jq。

curl -fsSLO https://public.hami.run/collect-hami-license-info.sh
bash collect-hami-license-info.sh

将脚本输出的 JSON 发送给密瓜智能售前或技术支持以申请许可证。

方法二：通过 HAMi AI Platform 获取（可选）

仅在已安装 HAMi AI Platform 时使用。

使用平台管理员账号登录 HAMi AI Platform。
进入「License 与系统信息」。
按页面提示获取授权申请信息。
将授权申请信息发送给密瓜智能销售或技术支持人员。

导入并验证许可证

通过任一方法申请并收到 License 文件后，将其保存到可以访问目标集群的运维机器，并创建 License Secret：

kubectl create secret generic hami-license \
  --from-file=license=/path/to/license-file \
  -n hami-system

kubectl label secret hami-license \
  hami.io/license="true" \
  -n hami-system

kubectl get secret hami-license -n hami-system
kubectl get events --field-selector involvedObject.name=hami-license -n hami-system

事件中出现 LicenseValid 表示许可证校验通过。NVIDIA 节点还可以检查许可证注册信息：

kubectl get nodes -o custom-columns='NODE:.metadata.name,LICENSE:.metadata.annotations.hami\.io/nvidia-license'

在线示例工作负载验证

运行以下示例前，确认目标集群能够拉取测试镜像 nvidia/cuda:12.4.0-base-ubuntu22.04。如果集群使用私有镜像仓库，请先将该镜像同步到私有仓库，并修改示例中的镜像地址。

kubectl delete pod hami-smoke --ignore-not-found

kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Pod
metadata:
  name: hami-smoke
spec:
  restartPolicy: Never
  containers:
    - name: cuda
      image: nvidia/cuda:12.4.0-base-ubuntu22.04
      command: ["sh", "-c", "nvidia-smi && sleep 30"]
      resources:
        limits:
          nvidia.com/gpu: 1
          nvidia.com/gpumem: 2000
EOF

kubectl wait --for=condition=Ready pod/hami-smoke --timeout=180s
kubectl logs hami-smoke

Pod 进入 Ready 状态且日志正常输出 GPU 信息，表示 HAMi 已完成 GPU 调度，容器内的 NVIDIA 运行时可以正常访问 GPU。验证完成后删除测试 Pod。

kubectl delete pod hami-smoke

常见问题

现象	检查与处理
`hami-device-plugin` 未运行	确认节点已添加 `gpu=on` 标签，并检查 `kubectl -n hami-system get pods`。
`hami-device-plugin` 反复重启	检查 NVIDIA GPU Operator 是否仍启用了默认 device-plugin；应设置 `devicePlugin.enabled=false`。
镜像拉取失败	检查目标集群到镜像仓库的网络连通性、镜像地址和标签，以及所需的 `imagePullSecrets`。
查不到 HAMi 指标	检查 Prometheus 或 VictoriaMetrics 的监控对象选择器是否匹配 ServiceMonitor 标签。
工作负载持续 Pending	检查许可证是否已激活、节点是否已添加 `gpu=on` 标签、可用加速器资源，以及 `kubectl describe pod` 输出的事件。

获取支持

邮箱：info@dynamia.ai
售前 / 技术支持：400-026-7800
已签订商业合同的客户可通过专属支持渠道提交问题。

部署范围与前置条件

组件选择​

前置检查​

在线安装

安装 NVIDIA GPU Operator（仅 NVIDIA 节点）​

示例 values 文件​

安装监控栈（按需）​

示例 values 文件​

安装 HAMi Enterprise​

示例 values 文件​

安装昇腾设备插件（仅昇腾节点）​

启用 GPU 节点​

安装 HAMi AI Platform（可选）​

安装 Envoy Gateway​

安装 HAMi AI Platform​

示例 values 文件​

安装后检查

核心组件​

节点与监控​

HAMi AI Platform（可选）​

许可证申请与激活

获取许可证信息​

方法一：运行收集脚本​

方法二：通过 HAMi AI Platform 获取（可选）​

导入并验证许可证​

在线示例工作负载验证​

常见问题

获取支持

组件选择

前置检查

安装 NVIDIA GPU Operator（仅 NVIDIA 节点）

示例 values 文件

安装监控栈（按需）

示例 values 文件

安装 HAMi Enterprise

示例 values 文件

安装昇腾设备插件（仅昇腾节点）

启用 GPU 节点

安装 HAMi AI Platform（可选）

安装 Envoy Gateway

安装 HAMi AI Platform

示例 values 文件

核心组件

节点与监控

HAMi AI Platform（可选）

获取许可证信息

方法一：运行收集脚本

方法二：通过 HAMi AI Platform 获取（可选）

导入并验证许可证

在线示例工作负载验证