企业官网建设流程全解析

AIBrix 多节点推理编排指南：RayClusterFleet 与 StormService 双路径实战

【免费下载链接】aibrixCost-efficient and pluggable Infrastructure components for GenAI inference项目地址: https://gitcode.com/GitHub_Trending/ai/aibrix

导读

当单个 GPU 节点的显存装不下一个大模型时，就需要把模型切分到多个节点上做分布式推理。AIBrix 为此提供了两条互补的编排路径：基于 KubeRay 的RayClusterFleet / RayClusterReplicaSet（适合标准 vLLM 多节点部署，由 Ray 负责进程放置与 worker 协调），以及纯 Kubernetes 原生的StormService（通过podGroupSize实现多角色、多节点分组，无需 KubeRay，适合 Prefill/Decode 分离与引擎原生的多节点后端，如 SGLang、vLLM 配合 MPI/NCCL 与 RDMA）。读完本文，你将掌握两种抽象的选型依据、完整可复制的 YAML 示例、验证命令以及常见故障排查方法。

选型：两种编排抽象怎么选

分布式推理把一个大模型拆分到多节点上执行，首要动机是单机显存放不下超大模型。AIBrix 提供两种编排抽象，二者在orchestration.aibrix.ai/v1alpha1API 组下共存，选型取决于你的部署拓扑与基础设施：

两个抽象并不是二选一的排他方案：KubeRay 对 AIBrix 其余功能是可选的，只在用到 RayClusterFleet / RayClusterReplicaSet 时才需要安装（见 安装指南）。

基于 KubeRay 的编排：RayClusterFleet

为什么把 Ray 和 Kubernetes 组合在一起

管理多节点推理需要在两个层面协调：

• 应用内（intra-application）：细粒度的任务调度、worker 之间的通信，这是 Ray 的强项；
• 集群外（cluster-level）：容器调度、自动扩缩容、滚动更新等标准运维，这是 Kubernetes 的强项。

Ray 擅长前者但依赖外部系统处理集群生命周期；Kubernetes 擅长后者但缺乏分布式计算语义。AIBrix 把两者组合起来：Ray 负责内部分布式计算，Kubernetes 负责副本生命周期与环境搭建。每个应用实例对应一个独立的 Ray 集群，Service 面向代表应用实例的 Ray 集群（而非单个 Pod）进行服务封装。

AIBrix 提供两个 API 来管理 Ray 集群：RayClusterReplicaSet与RayClusterFleet，分别镜像 Kubernetes 的ReplicaSet与Deployment模式。绝大多数情况下，RayClusterFleet是你需要配置的主资源。

分层工作原理

从外到内共四层：

• RayClusterFleet承载Deployment的发布语义：滚动更新或重建策略（Recreate/RollingUpdate）、版本历史（revisionHistoryLimit）、paused、minReadySeconds与进度截止时间（progressDeadlineSeconds）。任何对spec.template的修改都会生成一个新的RayClusterReplicaSet，fleet 按strategy在新旧集合之间迁移副本。
• RayClusterReplicaSet维持固定数量的 KubeRayRayCluster对象存活，消失一个就补一个。它的 spec 是ReplicaSet的子集（replicas、selector、template、minReadySeconds），你通常不会直接创建它。
• RayCluster是 KubeRay 的资源，其 spec 直接取自 fleet 的spec.template.spec，仅在 head/worker Pod 模板上额外加上 fleet-name 标签，因此 KubeRay 支持的一切（rayVersion、headGroupSpec、workerGroupSpecs、rayStartParams）都可用。
• 引擎运行在 head Pod 上，Ray 作为其分布式执行器（vLLM 对应--distributed-executor-backend ray）；worker Pod 只运行ray start，把 GPU 贡献给 Ray 集群。

就绪判定：只有当 KubeRay 报告的RayClusterProvisioned与HeadPodReady两个 condition 都为True，且所有期望的 worker 都就绪时，Ray 集群才算就绪。这两个 condition 由 KubeRay 的RayClusterStatusConditionsfeature gate 产生，AIBrix 的安装命令会显式开启它（见下文前置条件），没有该 gate 的集群永远不会报告 ready 副本。

路由：网关通过model.aibrix.ai/name标签发现模型 Pod，但会忽略带有ray.io/node-type: worker标签的 Pod，因此请求只会被路由到 head Pod。fleet 控制器会为每个 Pod 打上orchestration.aibrix.ai/raycluster-fleet-name标签，便于指标与路由状态映射回所属 fleet。

前置条件

• KubeRay operator：对 AIBrix 其他功能是可选的，仅在用到 RayClusterFleet / RayClusterReplicaSet 时需要。使用安装指南中的 Helm 命令安装，该命令固定使用打过补丁的 operator 镜像并开启就绪判定所依赖的RayClusterStatusConditionsfeature gate：

helm repo add kuberay https://ray-project.github.io/kuberay-helm/ helm repo update helm install kuberay-operator kuberay/kuberay-operator --namespace aibrix-system \ --create-namespace \ --version 1.2.1 \ --set-string 'env[0].name=ENABLE_PROBES_INJECTION' \ --set-string 'env[0].value=false' \ --set fullnameOverride=kuberay-operator \ --set 'featureGates[0].name=RayClusterStatusConditions' \ --set 'featureGates[0].enabled=true' \ --set image.repository=aibrix/kuberay-operator \ --set image.tag=v1.2.1-patch-20250726

• head Pod 与每个 worker Pod 都需要GPU 节点；
• 一个包含 Ray 的引擎镜像：v0.6.6 起官方 vLLM 镜像开箱即用；更早版本见下文"容器镜像要求"。

配置参考

RayClusterFleetSpec定义在 rayclusterfleet_types.go，关键字段如下：

status字段包括replicas、updatedReplicas、readyReplicas、availableReplicas、unavailableReplicas、observedGeneration、conditions与scalingTargetSelector。fleet 暴露 Kubernetesscale子资源（见 类型定义），因此：

kubectl scale rayclusterfleet <name> --replicas=N

并且 PodAutoscaler 可以把kind: RayClusterFleet作为scaleTargetRef直接使用。

需要关注的标签与注解

并行度 sizing：使用 Ray executor 时，引擎的 tensor-parallel 大小必须等于整个 Ray 集群的 GPU 总数（head + workers）。下面的示例在 1 个 GPU 的 head Pod + 1 个 GPU 的 worker Pod 上运行--tensor-parallel-size 2。

RayClusterFleet 完整示例

以下是一个部署两节点分布式推理集群的完整RayClusterFleet示例，源文件见 samples/distributed/fleet-two-node.yaml：

apiVersion: orchestration.aibrix.ai/v1alpha1 kind: RayClusterFleet metadata: name: qwen-coder-7b-instruct labels: app.kubernetes.io/name: aibrix app.kubernetes.io/managed-by: kustomize spec: replicas: 1 selector: matchLabels: model.aibrix.ai/name: qwen-coder-7b-instruct strategy: type: RollingUpdate rollingUpdate: maxSurge: 25% maxUnavailable: 25% template: metadata: labels: model.aibrix.ai/name: qwen-coder-7b-instruct annotations: ray.io/overwrite-container-cmd: "true" spec: rayVersion: "2.10.0" headGroupSpec: rayStartParams: dashboard-host: "0.0.0.0" template: metadata: labels: model.aibrix.ai/name: qwen-coder-7b-instruct spec: containers: - name: ray-head image: vllm/vllm-openai:v0.7.1 command: ["/bin/bash", "-c"] args: - > ulimit -n 65536 && apt update && apt install -y wget net-tools && pip3 install ray[default] pyarrow pandas && echo "[INFO] Starting Ray head node..." && eval "$KUBERAY_GEN_RAY_START_CMD" & echo "[INFO] Waiting for Ray dashboard to be ready..." && until curl --max-time 5 --fail http://127.0.0.1:8265 > /dev/null 2>&1; do echo "[WAITING] $(date -u +'%Y-%m-%dT%H:%M:%SZ') - Ray dashboard not ready yet..."; sleep 2; done && echo "[SUCCESS] Ray dashboard is available!" && vllm serve Qwen/Qwen2.5-Coder-7B-Instruct \ --served-model-name qwen-coder-7b-instruct \ --tensor-parallel-size 2 \ --distributed-executor-backend ray \ --host 0.0.0.0 \ --port 8000 \ --dtype half ports: - containerPort: 6379 name: gcs-server - containerPort: 8265 name: dashboard - containerPort: 10001 name: client - containerPort: 8000 name: service resources: limits: cpu: "4" nvidia.com/gpu: 1 requests: cpu: "4" nvidia.com/gpu: 1 - name: aibrix-runtime image: aibrix/runtime:v0.3.0 command: - aibrix_runtime - --port - "8080" env: - name: INFERENCE_ENGINE value: vllm - name: INFERENCE_ENGINE_ENDPOINT value: http://localhost:8000 - name: PYTORCH_CUDA_ALLOC_CONF value: "expandable_segments:True" ports: - containerPort: 8080 protocol: TCP livenessProbe: httpGet: path: /healthz port: 8080 initialDelaySeconds: 3 periodSeconds: 2 readinessProbe: httpGet: path: /ready port: 8080 initialDelaySeconds: 5 periodSeconds: 10 resources: limits: cpu: "1" requests: cpu: "1" workerGroupSpecs: - groupName: small-group replicas: 1 minReplicas: 1 maxReplicas: 5 rayStartParams: {} template: metadata: labels: model.aibrix.ai/name: qwen-coder-7b-instruct spec: containers: - name: ray-worker image: vllm/vllm-openai:v0.7.1 env: - name: MY_POD_IP valueFrom: fieldRef: fieldPath: status.podIP command: [ "/bin/bash", "-c" ] args: - > ulimit -n 65536 && eval "$KUBERAY_GEN_RAY_START_CMD --node-ip-address=$MY_POD_IP" && tail -f /dev/null lifecycle: preStop: exec: command: [ "/bin/sh", "-c", "ray stop" ] resources: limits: cpu: "4" nvidia.com/gpu: 1 requests: cpu: "4" nvidia.com/gpu: 1 --- apiVersion: v1 kind: Service metadata: name: qwen-coder-7b-instruct labels: model.aibrix.ai/name: qwen-coder-7b-instruct prometheus-discovery: "true" annotations: prometheus.io/scrape: "true" prometheus.io/port: "8080" spec: selector: model.aibrix.ai/name: qwen-coder-7b-instruct ports: - name: serve port: 8000 protocol: TCP targetPort: 8000 - name: http port: 8080 protocol: TCP targetPort: 8080 --- apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: qwen-coder-7b-instruct-router namespace: aibrix-system spec: parentRefs: - group: gateway.networking.k8s.io kind: Gateway name: aibrix-eg namespace: aibrix-system rules: - backendRefs: - group: "" kind: Service name: qwen-coder-7b-instruct namespace: default port: 8000 # or 8000 if you're not using the runtime sidecar weight: 1 matches: - headers: - name: model type: Exact value: qwen-coder-7b-instruct path: type: PathPrefix value: /v1/completions - headers: - name: model type: Exact value: qwen-coder-7b-instruct path: type: PathPrefix value: /v1/chat/completions timeouts: request: 120s

逐段解读这个示例：

• head 容器：先调高文件描述符上限，安装 Ray dashboard 依赖，在后台执行 KubeRay 生成的ray start命令，轮询等待 8265 端口的 Ray dashboard 应答，然后才启动vllm serve（带--distributed-executor-backend ray）。等待 dashboard 至关重要——vLLM 启动时会连接 Ray 集群，head 未就绪则直接失败。
• worker 容器：用自身 Pod IP 执行生成的ray start命令，然后用tail -f /dev/null阻塞保活；preStop钩子调用ray stop，让节点干净地离开集群。
• AI Runtime sidecar（head Pod 上）：在 8080 端口暴露标准化指标，并提供 Pod 的存活与就绪探针（/healthz与/ready），详见 runtime。
• Service：按model.aibrix.ai/name选择 Pod，带prometheus-discovery: "true"标签以便指标被采集。
• HTTPRoute：通过匹配model请求头把模型挂到 AIBrix 网关，与单 Pod 部署的路由形态一致，详见 网关生产配置。

验证部署

# Fleet、它的 ReplicaSet，以及它创建的 KubeRay 集群 kubectl get rayclusterfleet kubectl get rayclusterreplicaset kubectl get raycluster # head 与 worker Pod kubectl get pods -l ray.io/node-type=head kubectl get pods -l ray.io/node-type=worker

fleet 的 CRD 没有额外的打印列，直接对比计数即可：

kubectl get rayclusterfleet qwen-coder-7b-instruct \ -o jsonpath='{.status.readyReplicas}/{.spec.replicas}{"\n"}'

两个数字相等即 fleet 健康。然后像单 Pod 模型一样，通过网关发请求：

kubectl -n envoy-gateway-system port-forward service/envoy-aibrix-system-aibrix-eg-903790dc 8888:80 & curl http://localhost:8888/v1/chat/completions \ -H "Content-Type: application/json" \ -H "model: qwen-coder-7b-instruct" \ -d '{"model": "qwen-coder-7b-instruct", "messages": [{"role": "user", "content": "hello"}]}'

故障排查

Fleet 从不报告 ready 副本。执行kubectl describe raycluster <name>查看Status.Conditions。AIBrix 要求RayClusterProvisioned与HeadPodReady均为True。如果这两个 condition 完全缺失，说明 KubeRay operator 安装时没有开启RayClusterStatusConditionsfeature gate，请按安装指南重装。

Head Pod 反复重启，或 vLLM 报 Ray 连接错误。引擎在 Ray head 就绪前启动了。保留示例中vllm serve前面的 dashboard 等待循环；同时确认模板里的rayVersion与镜像内的 Ray 版本一致，版本不匹配会导致 worker 无法加入。

Worker Pod 一直 Pending。每个 worker 都申请 GPU。用kubectl describe node检查节点容量，确认workerGroupSpecs里的nvidia.com/gpu请求可被满足。

Pod 已 Running 但网关对模型返回错误。网关只路由给带model.aibrix.ai/name且 Ready 的 head Pod。检查标签是否在 head Pod 模板上（而不只是 fleet 上），以及 runtime sidecar（8080 端口/ready）的就绪探针是否通过。

原生 PodSet 编排：StormService

podGroupSize 与确定性分布式环境变量

对于不运行 KubeRay 的部署，或需要显式角色分离（如独立的 Prefill 与 Decode 角色）的分离式架构，AIBrix 提供原生的多节点分组能力StormService。它的核心机制是：在角色模板里设置podGroupSize，让StormService为每个副本实例分配一组同步的 Pod，并注入确定性的分布式环境变量（如$POD_GROUP_INDEX与$PODSET_NAME），从而支持跨节点的引擎原生张量并行（TP）。

关键能力：

• 零外部依赖：直接跑在 Kubernetes 上，无需安装 KubeRay；
• 多角色与分离式支持：在单个服务定义里声明多个角色（如 routing、prefill、decode），每个角色可有独立的资源画像与 pod 组大小；
• 确定性的 rank 与发现：组内 Pod 通过可预测的 headless Service DNS 发现对端，例如${PODSET_NAME}-0.${STORM_SERVICE_NAME}。

从源码看，podGroupSize的最小值为 2、最大值为 100（见 podset_types.go）；当podGroupSize > 1时，RoleSet 控制器会创建内部的PodSet资源（该资源在 podset_types.go 中明确标注为"internal API，由 RoleSet controller 在 podGroupSize > 1 时使用"），以原子组的形式协同管理这批 Pod，并通过PodSetStatus的ReadyPods/TotalPods/Phase呈现整组状态。

此外，StormService还支持Replica与Pooled两种部署模式（stormservice_types.go）：显式spec.mode优先，否则按spec.replicas兼容推断（replicas > 1 为 Replica 模式，否则为 Pooled 模式），并支持RollingUpdate与InPlaceUpdate两种更新策略（类型定义）。

StormService 多节点 TP 示例（PD 分离）

下面是一个完整的 Prefill/Decode 分离多节点张量并行示例：prefill 2 节点、decode 2 节点，podGroupSize: 2，对应--nnodes 2 --tp-size 2，源文件见 samples/disaggregation/sglang/tp-1p1d.yaml：

apiVersion: orchestration.aibrix.ai/v1alpha1 kind: StormService metadata: name: tp-1p1d spec: replicas: 1 updateStrategy: type: InPlaceUpdate stateful: true selector: matchLabels: app: tp-1p1d template: metadata: labels: app: tp-1p1d spec: roles: - name: routing replicas: 1 stateful: true template: spec: containers: - name: mini-lb image: aibrix/sglang-router:v0.1.6 command: [ "sh", "-c" ] args: - | python3 -m sglang_router.launch_router \ --pd-disaggregation \ --policy random \ --service-discovery \ --service-discovery-port 30000 \ --prefill-selector storm-service-name=$STORM_SERVICE_NAME role-name=prefill stormservice.orchestration.aibrix.ai/pod-group-index=0 \ --decode-selector storm-service-name=$STORM_SERVICE_NAME role-name=decode stormservice.orchestration.aibrix.ai/pod-group-index=0 \ --service-discovery-namespace default - name: prefill replicas: 1 podGroupSize: 2 stateful: true template: metadata: annotations: k8s.volcengine.com/pod-networks: | [ { "cniConf":{ "name":"rdma" } } ] labels: model.aibrix.ai/name: qwen3-8B model.aibrix.ai/port: "30000" model.aibrix.ai/engine: sglang spec: containers: - name: prefill image: aibrix/sglang:v0.4.9.post3-cu126-nixl-v0.4.1 command: ["sh", "-c"] args: - | python3 -m sglang.launch_server \ --model-path /models/Qwen3-8B \ --served-model-name qwen3-8B \ --host 0.0.0.0 \ --port 30000 \ --disaggregation-mode prefill \ --disaggregation-transfer-backend=nixl \ --trust-remote-code \ --dist-init-addr "${PODSET_NAME}-0.${STORM_SERVICE_NAME}.default.svc.cluster.local:5000" \ --nnodes 2 \ --node-rank $POD_GROUP_INDEX \ --tp-size 2 \ --mem-fraction-static 0.8 \ --log-level debug env: - name: GLOO_SOCKET_IFNAME value: eth0 - name: NCCL_SOCKET_IFNAME value: eth0 - name: NCCL_IB_DISABLE value: "0" - name: NCCL_IB_GID_INDEX value: "7" - name: NCCL_DEBUG value: "INFO" - name: UCX_TLS value: ^gga volumeMounts: - name: model-vol mountPath: /models - mountPath: /dev/shm name: shared-mem resources: limits: nvidia.com/gpu: 1 vke.volcengine.com/rdma: "1" securityContext: capabilities: add: - IPC_LOCK volumes: - name: model-vol hostPath: path: /root/models type: Directory - emptyDir: medium: Memory name: shared-mem - name: decode replicas: 1 podGroupSize: 2 stateful: true template: metadata: annotations: k8s.volcengine.com/pod-networks: | [ { "cniConf":{ "name":"rdma" } } ] labels: model.aibrix.ai/name: qwen3-8B model.aibrix.ai/port: "30000" model.aibrix.ai/engine: sglang spec: containers: - name: decode image: aibrix/sglang:v0.4.9.post3-cu126-nixl-v0.4.1 command: ["sh", "-c"] args: - | python3 -m sglang.launch_server \ --model-path /models/Qwen3-8B \ --served-model-name qwen3-8B \ --host 0.0.0.0 \ --port 30000 \ --disaggregation-mode decode \ --disaggregation-transfer-backend=nixl \ --trust-remote-code \ --dist-init-addr "${PODSET_NAME}-0.${STORM_SERVICE_NAME}.default.svc.cluster.local:5000" \ --nnodes 2 \ --node-rank $POD_GROUP_INDEX \ --tp-size 2 \ --mem-fraction-static 0.8 \ --log-level debug env: - name: GLOO_SOCKET_IFNAME value: eth0 - name: NCCL_SOCKET_IFNAME value: eth0 - name: NCCL_IB_DISABLE value: "0" - name: NCCL_IB_GID_INDEX value: "7" - name: NCCL_DEBUG value: "INFO" - name: UCX_TLS value: ^gga volumeMounts: - name: model-vol mountPath: /models - mountPath: /dev/shm name: shared-mem resources: limits: nvidia.com/gpu: 1 vke.volcengine.com/rdma: "1" securityContext: capabilities: add: - IPC_LOCK volumes: - name: model-vol hostPath: path: /root/models type: Directory - emptyDir: medium: Memory name: shared-mem

要点拆解：

• routing 角色使用aibrix/sglang-router:v0.1.6运行sglang_router.launch_router，开启--pd-disaggregation与--service-discovery（端口 30000），通过--prefill-selector/--decode-selector分别按storm-service-name、role-name与pod-group-index=0发现对应的 prefill/decode Pod；
• prefill / decode 角色各自podGroupSize: 2、stateful: true，两个节点通过--dist-init-addr "${PODSET_NAME}-0.${STORM_SERVICE_NAME}.default.svc.cluster.local:5000"确定性地互相发现，--node-rank $POD_GROUP_INDEX提供每个节点的 rank，配合--nnodes 2 --tp-size 2完成跨节点张量并行；
• 环境变量部分配置了 RDMA/InfiniBand 相关的 NCCL 参数（NCCL_IB_DISABLE=0、NCCL_IB_GID_INDEX=7、NCCL_DEBUG=INFO、UCX_TLS=^gga等），并在 Pod 网络注解中声明rdmaCNI 网络，体现"引擎原生分布式后端 + RDMA"的典型形态；
• 两个角色共享model-vol（hostPath/root/models）与内存型/dev/shm卷。

更完整的 Prefill/Decode 分离指南见 pd-disaggregation。

容器镜像要求

注意：从v0.6.6起，官方 vLLM 容器镜像发行版已内置运行分布式推理所需的必要包，开箱即用；更早版本请按下面的指引构建兼容镜像。

如果你使用更早的 vLLM 版本，有两个选择：

• 直接使用 AIBrix 构建好的镜像aibrix/vllm-openai:v0.6.1.post2-distributed；
• 按以下步骤自行构建：

FROM vllm/vllm-openai:v0.6.1.post2 RUN apt update && apt install -y wget RUN pip3 install ray[default] ENTRYPOINT [""]

docker build -t aibrix/vllm-openai:v0.6.1.post2-distributed .

小结

AIBrix 的多节点推理能力本质上是"选择适合你拓扑的编排层"：需要 Ray 提供进程级协调与标准 vLLM 部署时选RayClusterFleet（配 KubeRay，开启RayClusterStatusConditionsfeature gate，用model.aibrix.ai/name与ray.io/overwrite-container-cmd等标签/注解完成发现与启动）；需要 PD 分离、多角色架构或纯 K8s 环境时选StormService（用podGroupSize实现多节点分组，靠$POD_GROUP_INDEX/$PODSET_NAME注入确定性 rank 与发现地址）。两条路径共享同一套网关路由与指标体系，可将请求统一收敛到 head Pod（或路由角色），实现多节点与单节点部署的无缝衔接。

延伸阅读

• 分布式推理示例目录：fleet-two-node.yaml两节点 RayClusterFleet 完整清单
• PD 分离示例目录：tp-1p1d.yamlStormService 多节点 TP 示例
• PodAutoscaler 文档：以 RayClusterFleet 为scaleTargetRef的自动扩缩容
• 安装指南：KubeRay operator 的可选安装
• PD 分离指南：基于 StormService 的 Prefill/Decode 分离完整指南
• 运行时 sidecar 文档：head Pod 上的 AI Runtime 指标与探针

【免费下载链接】aibrixCost-efficient and pluggable Infrastructure components for GenAI inference项目地址: https://gitcode.com/GitHub_Trending/ai/aibrix