tencent cloud

容器服务

动态与公告
产品动态
公告
产品发布记录
产品简介
产品概述
产品优势
产品架构
应用场景
产品功能
基本概念
原生 Kubernetes 名词对照
容器服务高危操作
地域和可用区
开源组件
购买指南
购买指引
购买 TKE 标准集群
购买原生节点
购买超级节点
快速入门
新手指引
快速创建一个标准集群
入门示例
容器应用部署 Check List
集群配置
标准集群概述
集群管理
网络管理
存储管理
节点管理
GPU 资源管理
远程终端
应用配置
工作负载管理
服务和配置管理
组件和应用管理
弹性伸缩
容器登录方式
可观测配置
运维可观测性
成本洞察和优化
调度配置
调度组件概述
资源利用率优化调度
业务优先级保障调度
Qos 感知调度
安全和稳定性
容器服务安全组设置
身份验证和授权
应用安全
多集群管理
计划升级
备份中心
云原生服务指南
云原生 etcd
Prometheus 监控服务
TKE Serverless 集群指南
TKE 注册集群指南
实践教程
集群
Serverless 集群
调度
安全
服务部署
网络
发布
日志
监控
运维
Terraform
DevOps
弹性伸缩
容器化
微服务
成本管理
混合云
AI
故障处理
节点磁盘爆满排障处理
节点高负载排障处理
节点内存碎片化排障处理
集群 DNS 解析异常排障处理
集群 Kube-Proxy 异常排障处理
集群 API Server 网络无法访问排障处理
Service&Ingress 网络无法访问排障处理
Service&Ingress 常见报错和处理
Nginx Ingress 偶现 Connection Refused
CLB Ingress 创建报错排障处理
Pod 网络无法访问排查处理
Pod 状态异常与处理措施
授权腾讯云售后运维排障
CLB 回环问题
API 文档
History
Introduction
API Category
Making API Requests
Elastic Cluster APIs
Resource Reserved Coupon APIs
Cluster APIs
Third-party Node APIs
Relevant APIs for Addon
Network APIs
Node APIs
Node Pool APIs
TKE Edge Cluster APIs
Cloud Native Monitoring APIs
Scaling group APIs
Super Node APIs
Other APIs
Data Types
Error Codes
TKE API 2022-05-01
常见问题
TKE 标准集群
TKE Serverless 集群
运维类
隐患处理
服务类
镜像仓库类
远程终端类
事件类
资源管理类
服务协议
TKE Service Level Agreement
TKE Serverless Service Level Agreement
联系我们
词汇表
文档容器服务实践教程AI在 TKE 上使用 AIBrix 进行多节点分布式推理

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

PDF
聚焦模式
字号
最后更新时间： 2025-04-30 16:01:17

概述

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。

在本文中，我们将介绍如何在 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 模型。
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 名称

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 上部署 AI 大模型下一篇: TACO LLM 推理加速引擎

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈