安装 InferNex Bridge

本指南介绍如何通过现有的 default AmlCluster,在 arm64 集群上启用 Alauda Build of InferNex Bridge。Alauda AI Platform 负责管理安装;用户无需选择 OLM 通道,也无需手动安装 operator。有关平台版本中包含的版本,请参阅组件矩阵。

前提条件

安装 Alauda Build of InferNex Bridge 之前,请确保目标集群具备所需的平台和推理依赖项。

必需依赖项

依赖项类型描述
Kubernetes 集群平台正在运行且具有管理员访问权限的集群。
KServeOperator使用 KServe LLMInferenceService 入口时必需。此处未指定特定的 Alauda AI Platform Inference Management 版本。
Envoy Gateway 和 Gateway APIOperator / CRDs通过 Gateway API 资源公开推理服务时必需。
Gateway API Inference ExtensionCRDs使用基于 InferencePool 的智能路由时必需。
Alauda Build of LeaderWorkerSetOperator(由 AmlCluster 管理)InferNex Bridge 必需。该控制器会监视 LeaderWorkerSet 资源,并将其用于多节点推理工作负载。通常通过 lws default AmlCluster 中的组件启用;请参阅安装 Alauda AI Platform。
Alauda AI Platform NPU Serving RuntimeOperator(由 AmlCluster 管理)推荐用于 Ascend NPU 推理。它提供 vLLM-Ascend 镜像、ClusterServingRuntime 和 LLMInferenceServiceConfig 资源。在 default AmlCluster 中启用 servingRuntimeNPUOperator;请参阅NPU Serving Runtime 设置。
INFO

InferNex Bridge 由 Alauda AI Platform 通过 default AmlCluster 中的 infernexBridge 组件安装和管理;无需安装 InferNex 主 chart。对于 Ascend 推理,还需启用 servingRuntimeNPUOperator。Alauda AI Platform NPU Serving Runtime 会提供 vLLM-Ascend 镜像、ClusterServingRuntime 和 LLMInferenceServiceConfig;模型文件以及任何特定功能所需的依赖项仍须单独准备。

此 Operator 安装的 CRD

Alauda Build of InferNex Bridge OLM bundle 会安装其托管的弹性编排组件所使用的两个产品 API 和三个 CRD:

CRD此 operator 是否安装
infernexservices.infernex.infernex.io是
infernexserviceconfigs.infernex.infernex.io是
resourcescalinggroups.autoscaling.openfuyao.com是
elasticscalers.elasticscaler.io是
tidals.tidal.io是

以下 CRD 不由此 OLM bundle 安装。请根据下表所示的要求另行安装:

CRD来源项目必需场景安装方法
leaderworkersets.leaderworkerset.x-k8s.ioAlauda Build of LeaderWorkerSetInferNex Bridge 控制器和多节点推理工作负载确保已安装并运行 LeaderWorkerSet。通常通过 default AmlCluster 中的 lws 组件管理;请参阅安装 Alauda AI Platform。
rolebasedgroups.workloads.x-k8s.ioRoleBasedGroup (RBG)明确使用 RoleBasedGroup 的 ResourceScalingGroup 目标从上游 RBG v0.7.0 发布清单 安装。

rolebasedgroups.workloads.x-k8s.io CRD 由上游 RoleBasedGroup (RBG) 项目提供。它是一个有条件的依赖项;Deployment 或 LeaderWorkerSet 目标不需要它。若要安装上游 RBG v0.7.0 控制器和 CRD,请使用带版本号的发布清单:

kubectl apply --server-side -f \
  https://raw.githubusercontent.com/sgl-project/rbg/v0.7.0/deploy/kubectl/manifests.yaml

kubectl wait deployment/rbgs-controller-manager \
  --namespace rbgs-system \
  --for=condition=Available \
  --timeout=5m

kubectl get crd rolebasedgroups.workloads.x-k8s.io \
  -o jsonpath='{range .spec.versions[?(@.name=="v1alpha2")]}{.name}{" served="}{.served}{" storage="}{.storage}{"\n"}{end}'

预期结果为 v1alpha2 served=true storage=true。该清单使用 docker.io/rolebasedgroup/rbgs-controller:v0.7.0-888ade7,它提供了 arm64 镜像。对于断网集群,请将此镜像镜像到集群可访问的 registry,并在应用清单前更新其中的镜像引用。

选择其他版本时,请参阅上游 RBG releases。

启用托管的 Tidal、ElasticScaler 或 ResourceScalingGroup 组件会部署其控制器工作负载。Tidal 和 ElasticScaler 等扩缩策略资源仍须由用户或平台工作流单独创建。

运行时模板和镜像

对于 Ascend 推理,请使用 Alauda AI Platform NPU Serving Runtime,而不要手动安装 vLLM-Ascend 运行时镜像或创建其 ClusterServingRuntime 和 LLMInferenceServiceConfig。按照 NPU Serving Runtime 设置中的说明启用 servingRuntimeNPUOperator;该组件会管理这些资源。

InferNex Bridge 自身的运行时模板和组件镜像仍可能引用其上游仓库。在受限或断网环境中,请验证软件包生成的 ImageWhiteList 包含所需的镜像引用和重写规则,并将 InferNex Bridge 的任何其他镜像镜像到集群可访问的 registry。

配置 ImageWhiteList

上传 InferNex Bridge 软件包时,平台会创建由 operator 管理的 ImageWhiteList。请勿手动创建或删除此对象。由 operator 管理的 ImageWhiteList 对象由 olm-registry 协调,删除后可能会重新创建。

创建推理服务之前,请验证生成的对象包含所需的源镜像引用以及源到目标的重写规则。保留现有的无关条目。

下表列出了预期的仓库映射。每条规则都会保留原始镜像标签。

源仓库<target-registry> 下的目标仓库
cr.openfuyao.cn/openfuyao/cache-indexer3rdparty/openfuyao/cache-indexer
cr.openfuyao.cn/openfuyao/proxy-server3rdparty/openfuyao/proxy-server
cr.openfuyao.cn/openfuyao/hermes-router3rdparty/openfuyao/hermes-router
cr.openfuyao.cn/openfuyao/hermes-router-tokenizer3rdparty/openfuyao/hermes-router-tokenizer
cr.openfuyao.cn/openfuyao/hermes-router-prediction3rdparty/openfuyao/hermes-router-prediction
hub.oepkgs.net/openfuyao/redis3rdparty/openfuyao/redis
cr.openfuyao.cn/openfuyao/tidal3rdparty/openfuyao/tidal
cr.openfuyao.cn/openfuyao/resource-scaling-group3rdparty/openfuyao/resource-scaling-group
cr.openfuyao.cn/openfuyao/elastic-scaler3rdparty/openfuyao/elastic-scaler
cr.openfuyao.cn/openfuyao/eagle-eye-hardware-monitor3rdparty/openfuyao/eagle-eye-hardware-monitor
cr.openfuyao.cn/openfuyao/eagle-eye-hardware-diagnosis3rdparty/openfuyao/eagle-eye-hardware-diagnosis
cr.openfuyao.cn/openfuyao/eagle-eye-network-performance-exporter3rdparty/openfuyao/eagle-eye-network-performance-exporter
hub.oepkgs.net/openfuyao/alpine/kubectl3rdparty/openfuyao/alpine/kubectl

最终对象中的相关部分应如下所示。完整对象还包含其他软件包镜像和平台管理的条目。

apiVersion: app.alauda.io/v1alpha1
kind: ImageWhiteList
metadata:
  name: infernex-bridge
  namespace: cpaas-system
spec:
  repoList:
    - cr.openfuyao.cn/openfuyao/cache-indexer:26.6.0
    - busybox:1.36.1
    - docker.io/library/busybox:1.36.1
  rewriteRules:
    - regexp: ^cr\.openfuyao\.cn/openfuyao/cache\-indexer:(.*)$
      replacement: <target-registry>/3rdparty/openfuyao/cache-indexer:${1}

对于 BusyBox,请在 repoList 中保留 busybox:1.36.1 和 docker.io/library/busybox:1.36.1,但不要添加自定义的 BusyBox 重写规则。平台的 _default 规则会处理短名称和 Docker Hub 规范化。

可以使用以下命令备份并编辑由 operator 管理的对象。如果对象名称不同,请使用 kubectl get imagewhitelist -A 查找。

kubectl get imagewhitelist -n cpaas-system infernex-bridge -o yaml \
  > imagewhitelist-infernex-bridge-backup.yaml

kubectl edit imagewhitelist -n cpaas-system infernex-bridge

工作负载规范中可能仍显示社区源镜像。只有当实际 Pod 的 imageID 指向目标 registry 时,重写才算成功。例如,InferNex Bridge 组件应解析为:

cache-indexer=<target-registry>/3rdparty/openfuyao/cache-indexer@sha256:...

检查 Pod 镜像 ID,验证 InferNex Bridge 组件镜像是否解析到预期的 registry:

kubectl get pods -n <inference-service-namespace> \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\n"}{range .status.initContainerStatuses[*]}  init:{.name}{"="}{.imageID}{"\n"}{end}{range .status.containerStatuses[*]}  {.name}{"="}{.imageID}{"\n"}{end}{end}'

准备模型

InferNex Bridge operator 软件包不包含模型构件。当选择 OCI 模型存储时,请使用 Alauda AI Platform 模型目录准备 ModelCar。请参阅模型存储。

INFO

Alauda OLM bundle 会为发布示例所用的 KServe LLMInferenceService API 版本注册 InferNex Bridge admission webhook,其中包括 serving.kserve.io/v1alpha2。当 KServe LLMInferenceService 上设置了 infernex.io/runtime: "true" 时,此 webhook 用于在准入阶段应用兼容性补丁;它不会创建或协调 LLMInferenceService 资源本身。

可选依赖项

依赖项必需场景描述
NATSEagle-Eye启用 Eagle-Eye 硬件监控、诊断或网络性能采集时必需。Service 必须可通过 nats.nats:4222 访问。
kube-prometheus-stackEagle-Eye平台监控需要抓取并显示 Eagle-Eye 指标时必需。

可选的 EagleEye 可观测性

在 Alauda OLM 模板中,EagleEye 默认处于禁用状态。禁用 EagleEye 不会影响推理引擎、聚合或 prefill-decode 部署模式、Mooncake、cache-indexer 或 PD-Orchestrator。它仅会禁用以下可选的可观测性工作负载:

组件功能
Hardware Monitor在加速器节点上运行并收集硬件状态信息。
Hardware Diagnosis提供硬件诊断处理和诊断日志。
Network Performance Exporter收集网络性能数据,并在端口 8222 上公开指标。

启用 EagleEye 之前,请验证 NATS 已有就绪的 Service 和 endpoint:

kubectl get service -n nats nats
kubectl get endpointslice -n nats -l kubernetes.io/service-name=nats

EagleEye init 容器会连接到 nats.nats:4222。如果此 endpoint 不可用,已启用的 EagleEye Pod 将停留在 init 阶段。

请在 InferNexService 或其引用的 InferNexServiceConfig 中显式启用 EagleEye:

spec:
  components:
    eagleEye:
      hardwareMonitor:
        enabled: true
      hardwareDiagnosis:
        enabled: true
      networkPerformanceExporter:
        enabled: true

应用资源后,请在推理服务命名空间中验证可选工作负载:

kubectl get deployment,daemonset,service -n <inference-service-namespace> \
  -l infernex.io/owner=<infernex-service-name>

预期工作负载包括 EagleEye 硬件诊断 Deployment、硬件监控 DaemonSet 和网络性能导出器 DaemonSet。如果不需要 EagleEye,请将三个子开关都保持为 false。

启用 InferNex Bridge 和 NPU Serving Runtime

Alauda AI Platform 通过现有 default AmlCluster 的 infernexBridge 组件安装和管理 InferNex Bridge。对于 Ascend NPU 推理,还需通过 servingRuntimeNPUOperator 启用 Alauda AI Platform NPU Serving Runtime。将所需设置合并到现有的 AmlCluster 中;不要创建另一个实例:

spec:
  components:
    infernexBridge:
      managementState: Managed
    servingRuntimeNPUOperator:
      managementState: Managed

保存 AmlCluster 并等待协调完成。NPU Serving Runtime 组件会安装 vLLM-Ascend 镜像,并提供服务工作负载所需的 ClusterServingRuntime 和 LLMInferenceServiceConfig 资源。无需通过 OperatorHub 手动安装 InferNex Bridge 或 NPU Serving Runtime operators。

验证

检查 AmlCluster 状态,并确认托管组件及其工作负载均已就绪:

kubectl get amlcluster default
kubectl get pods -n infernex-system
kubectl get crd \
  infernexservices.infernex.infernex.io \
  infernexserviceconfigs.infernex.infernex.io \
  resourcescalinggroups.autoscaling.openfuyao.com \
  elasticscalers.elasticscaler.io \
  tidals.tidal.io
kubectl get clusterservingruntime
kubectl get llminferenceserviceconfig -A

AmlCluster 应报告 Ready / Reconciled,InferNex Bridge 控制器应处于运行状态,全部五个 InferNex Bridge CRD 均应已安装,并且 LLMInferenceService 变更 Webhook 应包含 v1alpha2。托管 servingRuntimeNPUOperator 时,请确认 NPU ClusterServingRuntime 和 LLMInferenceServiceConfig 均已存在。

Community 示例

社区维护的示例请参阅 InferNex Bridge v26.6.0 示例。

升级 InferNex Bridge

Alauda AI Platform 通过 default AmlCluster 中的 infernexBridge 组件管理 InferNex Bridge 的生命周期。请遵循平台的 Alauda AI Platform 组件升级操作步骤;不要通过 OperatorHub 单独升级 operator。升级前,请备份现有自定义资源:

kubectl get infernexservice,infernexserviceconfig -A -o yaml > infernex-bridge-backup.yaml

验证

AmlCluster 协调完成后,验证控制器和 CRD 状态:

kubectl get pods -n infernex-system
kubectl get crd \
  infernexservices.infernex.infernex.io \
  infernexserviceconfigs.infernex.infernex.io \
  resourcescalinggroups.autoscaling.openfuyao.com \
  elasticscalers.elasticscaler.io \
  tidals.tidal.io

回滚

使用平台支持的组件回滚操作步骤,并确认目标版本的 CRD 与集群中已存储的自定义资源兼容。

回滚后,请验证控制器、CRD、推理服务、运行时镜像 ID 以及一个具有代表性的推理请求。自定义资源仍然存在时,请勿删除捆绑的五个 CRD;删除这些 CRD 也会删除已存储的自定义资源。