EnterpriseAI Platform

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

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

为什么选择在线安装

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

网络隔离环境请参阅对应的离线部署手册。本文适用于可访问 Chart 和镜像仓库、需要自行维护组件版本、镜像来源及配置的在线 Helm 安装。

部署范围与前置条件

组件选择

组件	何时安装	说明
HAMi Enterprise	所有集群	核心调度器与设备插件，必须安装。
NVIDIA GPU Operator	需要由 GPU Operator 管理 NVIDIA 组件时按需安装；节点已有兼容的驱动、Toolkit 和运行时配置时可跳过	HAMi 与 GPU Operator 的默认 device-plugin 不能同时启用。
昇腾设备插件	使用昇腾节点	在 HAMi 安装完成后部署，复用 HAMi 的设备配置 ConfigMap。
Prometheus 监控栈	需要指标采集，且集群没有兼容的 Prometheus 或 VictoriaMetrics 时	集群已有兼容的监控栈时无需重复安装。
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 指向目标集群，并将各节的示例 values 保存为命令中引用的文件。下文使用已验证可匿名访问的杭州 ACR 镜像；HAMi 的 kube-scheduler 使用 Chart 默认的阿里云国内镜像。若集群只能使用内部仓库，请将对应镜像同步到内部仓库，并配置拉取凭据。

安装 HAMi Enterprise

helm install hami \
  oci://dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/charts/hami-enterprise \
  --version 2.10.0-r2 \
  --namespace hami-system \
  --create-namespace \
  -f hami-enterprise-values.yaml

示例 values 文件

下方 values 让 HAMi Enterprise 和证书 Job 从杭州 ACR 拉取镜像。kube-scheduler 保持 Chart 默认的阿里云国内镜像，Chart 按集群 Kubernetes 版本选择 tag。

nameOverride: "hami"
fullnameOverride: "hami"

global:
  imageTag: "v2.10.0-r2"

scheduler:
  enabled: true
  leaderElect: false
  extender:
    image:
      registry: dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public
  patch:
    imageNew:
      registry: dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public
  service:
    type: ClusterIP

devicePlugin:
  enabled: true
  image:
    registry: dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public
  monitor:
    image:
      registry: dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public
  service:
    type: ClusterIP

使用非 NVIDIA 设备时，必须在 HAMi values 的 devices 下启用对应厂商。昇腾节点至少配置：

devices:
  ascend:
    enabled: true
    hamiVnpuCore: true

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

安装 NVIDIA GPU Operator（仅 NVIDIA 节点）

NVIDIA GPU Operator 是可选组件。节点准备和较复杂的 values 配置请参阅 HAMi NVIDIA GPU 节点准备文档。安装或复用 GPU Operator 时，关闭其内置 device-plugin（devicePlugin.enabled=false）和 CDI（cdi.enabled=false）。当前 HAMi Enterprise 使用 scheduler.useDownward，与 CDI 不兼容。调整已有集群的 CDI 配置前，先评估运行中的 GPU 工作负载。

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 \
  --version v25.10.1 \
  -f gpu-operator-values.yaml

示例 values 文件

下方 values 使用杭州 ACR 的非驱动镜像，并设置 driver.enabled=false，适用于节点已安装兼容 NVIDIA 驱动的情况。杭州 ACR 不提供 nvidia/driver 镜像。若需要 GPU Operator 安装驱动，请参考上方节点准备文档，配置可访问的驱动镜像来源。

driver:
  enabled: false

toolkit:
  repository: dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/nvidia/k8s
  image: container-toolkit
  version: v1.18.1
  imagePullSecrets: []

devicePlugin:
  enabled: false
  repository: dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/nvidia
  image: k8s-device-plugin
  version: v0.18.1
  imagePullSecrets: []

dcgmExporter:
  repository: dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/nvidia/k8s
  image: dcgm-exporter
  version: 4.4.2-4.7.0-distroless
  serviceMonitor:
    enabled: false

gfd:
  repository: dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/nvidia
  image: k8s-device-plugin
  version: v0.18.1
  imagePullSecrets: []

migManager:
  repository: dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/nvidia/cloud-native
  image: k8s-mig-manager
  version: v0.13.1
  imagePullSecrets: []

vgpuDeviceManager:
  repository: dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/nvidia/cloud-native
  image: vgpu-device-manager
  version: v0.4.1
  imagePullSecrets: []

vfioManager:
  repository: dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/nvidia
  image: cuda
  version: 13.0.1-base-ubi9
  imagePullSecrets: []
  driverManager:
    image: k8s-driver-manager
    repository: dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/nvidia/cloud-native
    version: v0.9.1

sandboxDevicePlugin:
  repository: dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/nvidia
  image: kubevirt-gpu-device-plugin
  version: v1.4.0
  imagePullSecrets: []

validator:
  repository: dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/nvidia
  image: gpu-operator
  imagePullSecrets: []

node-feature-discovery:
  image:
    repository: dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/nfd/node-feature-discovery
    tag: v0.18.2
    pullPolicy: IfNotPresent
  imagePullSecrets: []

operator:
  repository: dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/nvidia
  image: gpu-operator
  imagePullSecrets: []
  initContainer:
    image: cuda
    repository: dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/nvidia
    version: 13.0.1-base-ubi9

cdi:
  enabled: false

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

本步骤必须在 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.4.1"
  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.2.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://dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/envoyproxy/gateway-helm \
  --version v1.6.2 \
  --namespace envoy-gateway-system \
  --create-namespace \
  --set global.images.envoyGateway.image=dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/envoyproxy/gateway:v1.6.2 \
  --set global.images.ratelimit.image=dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/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 \
  -f kantaloupe-values.yaml

示例 values 文件

下方 values 让平台组件、CloudTTY 和 Envoy Proxy 使用杭州 ACR 的公开镜像。生产部署前，还需填写实际域名、证书名称和 JWT 配置。

fullnameOverride: kantaloupe

global:
  imageRegistry: dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public

apiserver:
  leaderElection:
    enabled: false
  logLevel: 5

auth:
  enabled: true
  jwtSecret: <JWT_SIGNING_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。

安装监控栈（按需）

监控为可选项。仅在需要采集指标且集群尚无兼容监控系统时，安装 kube-prometheus-stack；已有 Prometheus 或 VictoriaMetrics 时，按“节点与监控”章节接入现有系统。

helm install prometheus \
  oci://dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/charts/kube-prometheus-stack \
  --version 72.3.0 \
  --namespace monitoring \
  --create-namespace \
  --set alertmanager.enabled=false \
  --set grafana.enabled=false \
  -f kube-prometheus-stack-values.yaml

示例 values 文件

下方 values 让 kube-prometheus-stack 使用杭州 ACR 已同步的公开镜像，无需为这些镜像配置 imagePullSecrets。

global:
  imageRegistry: dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public

alertmanager:
  enabled: false

grafana:
  enabled: false

安装后检查

核心组件

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

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

许可证申请与激活

获取许可证信息

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

方法一：运行收集脚本

HAMi 核心组件就绪后即可执行；无需等待按需安装的 GPU Operator、昇腾或监控组件。运行环境需要 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'

在线示例工作负载验证

下方验证 Pod 使用杭州 ACR 中公开的 CUDA 测试镜像。仅在 NVIDIA 节点上运行；若集群使用内部仓库，请将该镜像同步到内部仓库，并替换下方 image 地址。

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: dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/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` 输出的事件。

获取支持

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

部署范围与前置条件

组件选择​

前置检查​

在线安装

安装 HAMi Enterprise​

示例 values 文件​

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

示例 values 文件​

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

启用 GPU 节点​

安装 HAMi AI Platform（可选）​

安装 Envoy Gateway​

安装 HAMi AI Platform​

示例 values 文件​

安装监控栈（按需）​

示例 values 文件​

安装后检查

核心组件​

节点与监控​

HAMi AI Platform（可选）​

许可证申请与激活

获取许可证信息​

方法一：运行收集脚本​

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

导入并验证许可证​

在线示例工作负载验证​

常见问题

获取支持

组件选择

前置检查

安装 HAMi Enterprise

示例 values 文件

安装 NVIDIA GPU Operator（仅 NVIDIA 节点）

示例 values 文件

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

启用 GPU 节点

安装 HAMi AI Platform（可选）

安装 Envoy Gateway

安装 HAMi AI Platform

示例 values 文件

安装监控栈（按需）

示例 values 文件

核心组件

节点与监控

HAMi AI Platform（可选）

获取许可证信息

方法一：运行收集脚本

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

导入并验证许可证

在线示例工作负载验证