AI Platform

HAMi 平台版在线部署手册

本文档面向 SRE / 平台工程师，介绍如何在 Kubernetes 集群上部署 HAMi AI Platform ，并完成与 HAMi、Prometheus、NVIDIA GPU Operator、Gateway 等基础组件的对接和功能验证。

⚠️ 安装 ≠ 激活

完成本节的 Helm Charts 安装后，HAMi AI Platform的组件会运行，但 HAMi AI Platform底层的 GPU 虚拟化与调度功能需要激活证书后才能正常使用 。

安装过程本身不依赖证书，您可以先完成部署，再通过后续步骤申请并导入证书。

简而言之：先装软件，后拿证书；不激活则 vGPU 切分与调度功能不可用，验证也会失败。

前置条件清单

类型	要求	验证命令
Kubernetes	≥ 1.24	`kubectl version --short`
容器运行时	containerd、CRI-O 等 Kubernetes CRI 运行时；GPU 节点已配置 NVIDIA Container Toolkit	`kubectl get nodes -o wide`
GPU 驱动	NVIDIA driver ≥ 470（推荐 ≥ 550）	`nvidia-smi`
Prometheus CRD	启用 Prometheus 或 VictoriaMetrics 监控对接时，需要 `monitoring.coreos.com` CRD；选择 `prometheus-crds` 组件可由离线包安装	`kubectl api-resources --api-group=monitoring.coreos.com`
GPU Operator	如已安装，必须设置 `devicePlugin.enabled=false`；离线包内 GPU Operator 已预置该值，推荐版本为 v25.10.1	`helm list -A \| grep gpu-operator`
存储空间	建议大于 30 GB	`df -h`

关键约束：HAMi 自带 device-plugin，与 NVIDIA GPU Operator 内置 device-plugin 冲突。选择离线包内 gpu-operator 组件时已通过包内 values 禁用；使用集群中已有 GPU Operator 时，必须确认 devicePlugin.enabled=false。

相较于 HAMi，AI Platform 平台服务额外依赖了 Kuberentes Gateway API 作为默认的服务暴露方式（配合 envoy-gateway），如果您需要且集群里并没有 Gateway API （通过 kubectl api-resources | grep gateway.networking.k8s.io/v1检查），请先安装。

安装

两种安装路径，按场景选：

在线 OCI 安装（评估、PoC、可通外部网络的集群）
All-in-One 离线一体包（金融/政府/运营商等隔离网络场景）

无论如何安装，最后都需要申请证书并激活。

路径 A：在线 Helm Charts 安装

如果希望使用国内镜像仓库，请联系 Dynamia.ai 的售前/技术支持获取相关信息。

推荐使用版本追踪系统维护集群中所有 Helm Chart releases 的 values 文件。 通过使用 -f example-values.yaml 覆盖 Charts 中默认 values 中与之相对应的 key。

选择好 kubeconfig context 后，开始操作：

如果集群已安装 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=true \
  --set cdi.enabled=false \
  --version=v25.10.1

如果集群里没有 Prometheus 等监控栈，还需要安装，这里展示 prometheus-community/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

安装 dynamia-ai/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

hami-enterprise 常见 Chart 自定义选项如下表，完整 values 配置请见：HAMi Helm Chart Values Reference。

参数	说明	默认值
`dra.enabled`	是否部署启用 DRA	`false`
`scheduler.leaderElect`	是否启用`hami-scheduler`的多节点选举	`true`
`scheduler.replicas`	调整 `hami-scheduler`的实例数量	1
`scheduler.kubeScheduler.image.registry`	`hami-scheduler`所使用的`kube-scheduler`镜像仓库。	`"registry.cn-hangzhou.aliyuncs.com"`
`scheduler.kubeScheduler.image.repository`	`hami-scheduler`所使用的`kube-scheduler`镜像名称。	`"google_containers/kube-scheduler"`
`scheduler.kubeScheduler.image.tag`	`hami-scheduler`所使用的`kube-scheduler`镜像版本。如果不填，chart 会推算一个合适的版本。	`""`

如果集群中没有 Gateway API 实现，安装 envoyproxy/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

安装 dynamia-ai/kantaloupe （AI Platform 平台服务，下称 kantaloupe ）：

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

kantaloupe 由于需要配置功能特性、服务暴露、监控指标采集等功能，配置项较多，请按需配置，完整 values 配置请见 kantaloupe Helm Chart Value Reference。

常见的配置 values 示例如下，你可以拼接多段示例构成完整values文件：

配置默认平台管理员信息

auth:
  jwtSecret: "your-own-jwt-secret"
  bootstrapAdminUsername: "bootstrap-platform-admin"
  bootstrapAdminPassword: "admin12345"
  bootstrapAdminFullName: "Platform Administrator"
  bootstrapAdminEmail: "admin@email.com"

使用 envoy-gateway NodePort 暴露服务，在集群外部使用LoadBalancer（云厂商负载均衡、自建负载均衡等）转发四层流量 。

gateway:
  enabled: true
  hostnames:
    - your-domain.example.com
  apiserverCors:
    enabled: true
    allowCredentials: true
    allowOrigins:
      - https://your-domain.example.com
  envoy:
    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: your-domain-tls-secret
        redirectFromHttp: true

使用 envoy-gateway NodePort 暴露服务，简单 PoC

gateway:
  enabled: true
  listeners:
    - name: http
      port: 80
      protocol: HTTP
  envoy:
    service:
      type: NodePort
      ports:
        http:
          nodePort: 30080

使用云厂商或裸金属服务提供的负载均衡 controller 接手的 LoadBalancer service

gateway:
  enabled: true
  hostnames:
    - your.domain
  listeners:
    - name: http
      port: 80
      protocol: HTTP
    - name: https
      port: 443
      protocol: HTTPS
      tls:
        certificateRef:
          name: your-tls-secret
        redirectFromHttp: true
  envoy:
    service:
      type: LoadBalancer
      ports:
        http: {}
        https: {}

替换 prometheus Query API addr（默认为 http://prometheus-kube-prometheus-prometheus.monitoring.svc.cluster.local:9090）

apiserver:
  prometheusAddr: http://your-prometheus-query-api.com:9090

controllerManager:
  prometheusAddr: http://your-prometheus-query-api.com:9090

路径 B：All-in-One 离线一体包

请联系 Dynamia.ai 的售前/技术支持伙伴获取下载地址和操作手册。

启用 GPU 节点

HAMi device-plugin 仅在带 gpu=on 标签的节点上启动：

kubectl label nodes <node-name> gpu=on

验证：kubectl -n hami-system get pods 应能看到 hami-device-plugin-*、hami-scheduler-* 处于 Running 状态。

监控对接

确保集群里的监控指标系统（kube-prometheus-stack Prometheus，VictoriaMetrics vmagent 等）能采集 HAMi 与 DCGM-Exporter 指标。

如果使用 Prometheus， ServiceMonitor 资源的 metadata.labels 必须与 Prometheus 资源的 spec.serviceMonitorSelector 字段匹配，否则 Prometheus不会采集这些指标。

如果使用 VictoriaMetrics，ServiceMonitor 资源的 metadata.labels必须与 VMServiceScrape 资源的 spec.serviceScrapeSelector 字段匹配，否则 vmagent 不会采集这些指标。

验证指标采集

Exporter	查询指标	预期
`dcgm-exporter`	`DCGM_FI_DEV_GPU_UTIL`	返回非空值
`hami-exporter`	`HostCoreUtilization`	返回非空值
`hami-device-plugin-exporter`	`GPUDeviceCoreAllocated`	返回非空值

除了 exporter 指标，还需要查询 kantaloupe_gpu_temp，验证 Kantaloupe 服务指标是否被正确采集。

证书获取

请完成安装任务，确保所有组件的 Pod 都正常启动后再开始激活流程。

使用平台管理员账号登录 HAMi AI Platform。
进入 License 与系统信息页面
按照页面提示获取授权申请信息。
将授权申请信息发送给密瓜智能销售或交付人员。
根据指引完成激活。

激活后验证

kubectl -n hami-system get pods
kubectl describe node <gpu-node>
kubectl get events --field-selector involvedObject.name=hami-license -n hami-system
kubectl get nodes -o custom-columns='NODE:.metadata.name,LICENSE:.metadata.annotations.hami\.io/nvidia-license'

事件中出现 LicenseValid 表示许可证校验通过。确认已选择组件的 Pod 处于 Running 或 Completed 状态，并确认受管节点已注册加速卡资源。

在线示例工作负载验证

运行以下示例前，确认目标集群能够拉取测试镜像 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 AI Platform验证

# 1. Pod 状态
kubectl -n kantaloupe-system get pods

# 2. 服务可达
kubectl -n kantaloupe-system get svc

HAMi AI Platform 服务暴露后，打开站点，确认前后端正常工作。

创建工作负载

在控制台 工作负载 页面，创建应用（如 gpu-burn）：

创建完成后，确认以下验证项均通过：

创建成功 ，控制台无报错
负载列表 ：应用状态、检索、列表指标与监控面板（GPU SM / GPU MEM / CPU / Memory）正常，时间切换与图表符合预期

应用详情 ：基础信息、资源总览、与监控数据正常；从详情页跳转 GPU / 节点页面，资源总览与监控数据正常

常见问题

现象	可能原因	处理
镜像拉不下来	目标节点无法访问镜像仓库、镜像仓库认证信息缺失或无效，或者镜像地址错误	检查 Pod 事件和实际镜像地址，确认节点能够解析并访问镜像仓库，并配置所需的 `imagePullSecrets`。
`hami-device-plugin` Pod `Pending` 或者不存在	节点未打 `gpu=on` 标签	`kubectl label nodes <node> gpu=on`
`hami-device-plugin` Pod `CrashLoopBackOff`	与 NVIDIA 默认 device-plugin 冲突	禁用 GPU Operator 的 devicePlugin（`--set devicePlugin.enabled=false`）。
查不到 HAMi 指标	`Prometheus` 资源的`serviceMonitorSelector` 与 `ServiceMonitor` 资源中的 label 不匹配	对齐 `prometheus/prometheus-kube-prometheus-prometheus` 的 `spec.serviceMonitorSelector` 和 hami-enterprise 的 serviceMonitor labels。
`nvidia-smi` 报错	GPU 驱动未就绪	检查 `gpu-operator` namespace 下 driver Pod 状态。
示例 workload `Pending`	证书未激活、GPU 不足或节点标签缺失	检查证书、GPU 节点标签和 `kubectl describe pod` 事件
`Gateway` 没有入口地址	Gateway API 或 Envoy Gateway CRD 未就绪、Envoy Gateway release 异常，或 Envoy Service 类型不适配集群	检查 20 个相关 CRD 的 `Established` 状态，运行 `helm status eg -n envoy-gateway-system`，并检查 `Gateway` 条件和 Envoy `Service`。不要通过卸载 CRD release 或删除 CRD 重试。

获取支持

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

前置条件清单​

安装​

路径 A：在线 Helm Charts 安装​

路径 B：All-in-One 离线一体包​

启用 GPU 节点​

监控对接​

验证指标采集​

证书获取​

激活后验证​

在线示例工作负载验证​

HAMi AI Platform验证​

创建工作负载​

常见问题​

获取支持​