容器服务在 TKE 上使用 AIBrix 进行多节点分布式推理

概述
﻿AIBrix 是在2025年2月开源的云原生大模型推理控制平面项目，专为优化大规模语言模型（LLM）的生产化部署设计。作为首个深度集成 vLLM 的 Kubernetes 全栈方案，它提供了 LoRA 动态加载、多节点推理、异构 GPU 调度、分布式 KV 缓存等多种核心特性。
分布式推理是指在多个节点或设备上拆分和处理 LLM 模型的技术，这种方法对于单台机器内存无法容纳的大型模型尤其有用。AIBrix 采用 Ray 作为其分布式计算框架，结合 KubeRay 来协调 Ray 集群实现了分布式推理技术。
AIBrix 为管理 RayCluster 引入了两个关键 API，即 RayClusterReplicaSet 和 RayClusterFleet。RayClusterFleet 管理 RayClusterReplicaSet，RayClusterReplicaSet 管理 RayCluster，三者之间的关系与 Kubernetes 的核心概念 Deployment、ReplicaSet、Pod 之间类似，大部分情况下，用户只需要使用 RayClusterFleet。
aibrix-multi-host
﻿
在本文中，我们将介绍如何在 TKE 集群上使用 AIBrix 进行分布式推理。
镜像说明：
本文示例中所使用的镜像为 vllm/vllm-openai，托管在 DockerHub 上，且体积较大（8GB左右）。
在 TKE 环境中，默认会提供免费的 DockerHub 镜像加速服务，因此中国大陆用户也可以直接拉取到镜像，但速度可能较慢。建议将镜像同步至 容器镜像服务 TCR 中提高镜像拉取速度，并在 YAML 文件中替换相应的镜像地址。
操作步骤
1. 创建 TKE 集群
登录 容器服务控制台，参考步骤 创建集群，创建一个 TKE 集群。
集群类型：TKE 标准集群。
Kubernetes 版本：需要大于等于 1.28，建议选择最新版本。本文使用的是 1.30。
基础配置：存储组件需勾选 CFS，如下图所示：
﻿
2. 创建超级节点
在集群列表中，单击集群 ID，进入集群详情页，参考步骤 创建超级节点，创建一个超级节点池。
3. 下载模型
3.1 创建 StorageClass
通过控制台创建 StorageClass：
1. 在集群列表中，单击集群 ID，进入集群详情页。
2. 选择左侧导航中的存储，在 StorageClass 页面单击新建。
3. 在新建存储页面，根据实际需求，创建 CFS 类型的 StorageClass。如下图所示：
﻿
3.2 创建 PVC
通过控制台创建 PVC：
1. 在集群列表中，单击集群 ID，进入集群详情页。
2. 选择左侧导航中的存储，在 PersistentVolumeClaim 页面单击新建。
3. 在新建存储页面，根据实际需求，创建存储模型文件的 PVC。如下图所示：
﻿
3.3 使用 Job 下载模型文件
创建一个 Job 用于下载大模型文件到 CFS。
说明：
本文示例中所用模型为 Qwen2.5-Coder 的 7B 版本。
apiVersion: batch/v1
kind: Job
metadata:
  name: download-model
  labels:
    app: download-model
spec:
  template:
    metadata:
      name: download-model
      labels:
        app: download-model
      annotations:
        eks.tke.cloud.tencent.com/root-cbs-size: "100" # 超级节点系统盘默认只有 20Gi，vllm 镜像解压后会撑爆磁盘，用这个注解自定义一下系统盘容量（超过20Gi的部分会收费）。
    spec:
      containers:
        - name: vllm
          image: vllm/vllm-openai:v0.7.1
          command:
            - modelscope
            - download
            - --local_dir=/data/model/Qwen2.5-Coder-7B-Instruct
            - --model=Qwen/Qwen2.5-Coder-7B-Instruct
          volumeMounts:
            - name: data
              mountPath: /data/model
      volumes:
        - name: data
          persistentVolumeClaim:
            claimName: ai-model # 此处为创建的 PVC 名称
      restartPolicy: OnFailure
4. 安装 AIBrix
参考 AIBrix 的官方文档 Installation | AIBrix，安装 AIBrix。
# Install component dependencies
kubectl create -f https://github.com/vllm-project/aibrix/releases/download/v0.2.1/aibrix-dependency-v0.2.1.yaml
﻿
# Install aibrix components
kubectl create -f https://github.com/vllm-project/aibrix/releases/download/v0.2.1/aibrix-core-v0.2.1.yaml
检查 AIBrix 安装情况，确认所有 Pod 都处于 Running 状态。
kubectl -n aibrix-system get pods
5. 部署模型
创建 RayClusterFleet 部署 Qwen2.5-Coder-7B-Instruct 模型。
5.1. 创建 qwen-coder-7b-instruct.yaml 文件
apiVersion: orchestration.aibrix.ai/v1alpha1
kind: RayClusterFleet
metadata:
  labels:
    app.kubernetes.io/name: aibrix
    app.kubernetes.io/managed-by: kustomize
  name: qwen-coder-7b-instruct
spec:
  replicas: 1
  selector:
    matchLabels:
      model.aibrix.ai/name: qwen-coder-7b-instruct
  strategy:
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%
    type: RollingUpdate
  template:
    metadata:
      labels:
        model.aibrix.ai/name: qwen-coder-7b-instruct
      annotations:
        ray.io/overwrite-container-cmd: "true"
    spec:
      rayVersion: "2.10.0" # 必须匹配容器内的 Ray 版本
      headGroupSpec:
        rayStartParams:
          dashboard-host: "0.0.0.0"
        template:
          metadata:
            annotations:
              eks.tke.cloud.tencent.com/gpu-type: V100 # 指定 GPU 卡型号
              eks.tke.cloud.tencent.com/root-cbs-size: '100' # 超级节点系统盘默认只有 20Gi，vllm 镜像解压后会撑爆磁盘，用这个注解自定义一下系统盘容量（超过20Gi的部分会收费）。
          spec:
            containers:
              - name: ray-head
                image: vllm/vllm-openai:v0.7.1
                ports:
                  - containerPort: 6379
                    name: gcs-server
                  - containerPort: 8265
                    name: dashboard
                  - containerPort: 10001
                    name: client
                  - containerPort: 8000
                    name: service
                command: ["/bin/bash", "-lc", "--"]
                args:
                  - |﻿
                    ulimit -n 65536; 
                    echo head;
                    $KUBERAY_GEN_RAY_START_CMD & KUBERAY_GEN_WAIT_FOR_RAY_NODES_CMDS;
                    vllm serve /data/model/Qwen2.5-Coder-7B-Instruct \\
                      --served-model-name Qwen/Qwen2.5-Coder-7B-Instruct \\
                      --tensor-parallel-size 2 \\
                      --distributed-executor-backend ray \\
                      --dtype=half
                resources:
                  limits:
                    cpu: "4"
                    nvidia.com/gpu: 1
                  requests:
                    cpu: "4"
                    nvidia.com/gpu: 1
                volumeMounts:
                  - name: data
                    mountPath: /data/model
            volumes:
              - name: data
                persistentVolumeClaim:
                  claimName: ai-model # 此处为创建的 PVC 名称
      workerGroupSpecs:
        - replicas: 1
          minReplicas: 1
          maxReplicas: 5
          groupName: small-group
          rayStartParams: {}
          template:
            metadata:
              annotations:
                eks.tke.cloud.tencent.com/gpu-type: V100 # 指定 GPU 卡型号
                eks.tke.cloud.tencent.com/root-cbs-size: '100' # 超级节点系统盘默认只有 20Gi，vllm 镜像解压后会撑爆磁盘，用这个注解自定义一下系统盘容量（超过20Gi的部分会收费）。
            spec:
              containers:
                - name: ray-worker
                  image: vllm/vllm-openai:v0.7.1
                  command: ["/bin/bash", "-lc", "--"]
                  args:
                    ["ulimit -n 65536; echo worker; $KUBERAY_GEN_RAY_START_CMD"]
                  lifecycle:
                    preStop:
                      exec:
                        command: ["/bin/sh", "-c", "ray stop"]
                  resources:
                    limits:
                      cpu: "4"
                      nvidia.com/gpu: 1
                    requests:
                      cpu: "4"
                      nvidia.com/gpu: 1
                  volumeMounts:
                    - name: data
                      mountPath: /data/model
              volumes:
                - name: data
                  persistentVolumeClaim:
                    claimName: ai-model # 此处为创建的 PVC 名称
5.2. 使用 kubectl apply 创建 RayClusterFleet
kubectl apply -f qwen-coder-7b-instruct.yaml
6. 验证 API
当 RayClusterFleet 部署的 Pod 成功运行以后，可以通过 kubectl port-forward 快速验证 API。
# 获取 service 名称
svc=$(kubectl get svc -o name | grep qwen-coder-7b-instruct)
﻿
# 使用 port-forward 功能暴露 API 到本地的 18000 端口
kubectl port-forward $svc 18000:8000
﻿
# 启动另外一个终端，运行如下命令测试 API
curl -X POST "http://localhost:18000/v1/chat/completions" \\
-H "Content-Type: application/json" \\
-d '{
  "model": "Qwen/Qwen2.5-Coder-7B-Instruct",
  "messages": [
    {"role": "system", "content": "你是一个AI编程助手"},
    {"role": "user", "content": "用 Python 实现快速排序算法"}
  ],
  "temperature": 0.3,
  "max_tokens": 512,
  "top_p": 0.9
}'
常见问题
aibrix-kuberay-operator 无法启动，报错 runtime/cgo: pthread_create failed: Operation not permitted
检查 aibrix-kuberay-operator 是否部署在超级节点上，如果 aibrix-kuberay-operator 部署在超级节点上，参见如下两种解决方法：
1. 修改 aibrix-kuberay-operator 的 Deployment，在 Pod Template 中增加以下注解：
eks.tke.cloud.tencent.com/cpu-type: intel # 指定 CPU 类型为 intel
2. 参考 设置工作负载的调度规则，将 aibrix-kuberay-operator 调度到普通节点上。
如何设置 API 密钥限制访问？
vLLM 提供了以下两种方式设置 API 密钥：
1. 设置--api-key 参数。
2. 设置环境变量 VLLM_API_KEY。
修改 RayClusterFleet 的定义，在 headGroupSpec 中按上面任意一种方式设置 API 密钥之后，就需要在请求中带上以下 Header 进行访问：
Authorization: Bearer <VLLM_API_KEY>
﻿
在 TKE 上使用 AIBrix 进行多节点分布式推理

本页目录：

概述

操作步骤

1. 创建 TKE 集群

2. 创建超级节点

3. 下载模型

3.1 创建 StorageClass

3.2 创建 PVC

3.3 使用 Job 下载模型文件

4. 安装 AIBrix

5. 部署模型

5.1. 创建 qwen-coder-7b-instruct.yaml 文件

5.2. 使用 kubectl apply 创建 RayClusterFleet

6. 验证 API

常见问题

aibrix-kuberay-operator 无法启动，报错 `runtime/cgo: pthread_create failed: Operation not permitted`

如何设置 API 密钥限制访问？
