AIBrix 在火山引擎 VKE 上的部署指南从集群安装到 PD 分离推理【免费下载链接】aibrixCost-efficient and pluggable Infrastructure components for GenAI inference项目地址: https://gitcode.com/GitHub_Trending/ai/aibrix导读本文基于 AIBrix 官方文档 docs/source/getting_started/installation/vke.rst 编写完整讲解如何在火山引擎Volcano EngineVKEVolcano Engine Kubernetes Engine集群中安装 AIBrix并打通「TOS 模型下载 → 基础模型部署 → Prefill-DecodePD分离部署 → 网关推理验证」的端到端链路。读完本文你将掌握 VKE 专属 overlay 的用法、TOS 凭据的创建方式以及如何通过一条 curl 命令验证随机路由与 PD 路由两种推理模式。为什么需要 VKE 专属部署方案AIBrix 本身是云中立cloud-agnostic的推理基础设施官方在 安装总览 中明确说明AIBrix installation does rely on other cloud specific features. Its fully compatible with vanilla Kubernetes.即可运行于原生 Kubernetes。但在火山引擎 VKE 场景下直接使用默认清单会遇到三个现实问题镜像拉取不可达默认清单中的 Envoy Gateway、KubeRay、Redis、gateway-plugins 等镜像来自 Docker Hub / quay.io 等海外仓库在火山引擎地域拉取不稳定甚至失败负载均衡地址族与节点调度需要定制VKE 集群的 LoadBalancer Service 与 GPU 节点标签vke.node.gpu.schedulenvidia与社区默认配置不同模型存储使用火山引擎对象存储 TOS需要额外的凭据与下载器支持。为此仓库在 config/overlays/vke 下提供了专门的 Kustomize overlay将上述定制以 patch 方式集中管理。overlay 的目录结构如下config/overlays/vke/ ├── default/ # 覆盖 config/default定制核心组件 │ ├── envoy_proxy_patch.yaml │ ├── gateway_plugins_patch.yaml │ └── kustomization.yaml └── dependency/ # 覆盖 config/dependency定制依赖组件 ├── envoy_gateway_patch.yaml └── kustomization.yaml一、前置条件一个已就绪并可用的 VKE 集群Kubernetes 版本满足 AIBrix 与 Envoy Gateway 要求本机已安装kubectl与helm且能访问集群已准备火山引擎 TOS 的 Access Key 与 Secret Key用于下载模型集群中存在带 GPU 的工作节点用于运行 vLLM 推理 Pod。二、安装 AIBrix 到 VKE第 1 步安装依赖组件VKE overlay依赖组件Envoy Gateway、KubeRay、Redis 等通过 Kustomize overlay 安装命令如下kubectl apply -k config/overlays/vke/dependency --server-side--server-side采用服务端 apply避免大清单在客户端出现的注解膨胀问题。这条命令实际做了两件事见 config/overlays/vke/dependency/kustomization.yaml引入公共依赖目录../../../dependency即 config/dependency包含 envoy-gateway 与 kuberay-operator通过images替换将所有依赖镜像指向火山引擎镜像仓库aibrix-cn-beijing.cr.volces.com/aibrix/*如envoyproxy/gateway→aibrix-cn-beijing.cr.volces.com/aibrix/gateway:v1.2.8通过 envoy_gateway_patch.yaml 以 ConfigMap 形式下发 EnvoyGateway 配置其中关键一项是开启extensionApis.enableEnvoyPatchPolicy: true——这是 AIBrix gateway-plugin 能注入 Envoy 过滤器链的前提该要求与 通用安装文档 中 helm 安装 Envoy Gateway 时设置的--set config.envoyGateway.extensionApis.enableEnvoyPatchPolicytrue一致。第 2 步安装 AIBrix 主组件Helm依赖就绪后使用 Helm 安装 AIBrix 主组件并显式传入 VKE 专用 values 文件helm install aibrix dist/chart -f dist/chart/vke.yaml -n aibrix-system --create-namespacedist/chart/vke.yaml是随发行版提供的 VKE 定制 values结合 config/overlays/vke/default 中的 patch安装后核心组件会具备以下 VKE 特性镜像仓库统一替换controller-manager、gateway-plugins、metadata-service、runtime、Redis、busybox 等全部指向aibrix-cn-beijing.cr.volces.com/aibrix/*版本以 default/kustomization.yaml 中的newTag为准Envoy 代理定制envoy_proxy_patch.yaml将 Envoy Proxy 的 Service 固定为IPv4单栈LoadBalancerEnvoy 与 shutdown-manager 容器镜像替换为火山引擎仓库版本并设置资源请求/限制同时通过节点亲和性nodeAffinity将网关 Pod 调度到非 GPU 节点——配置中的key: vke.node.gpu.schedule, operator: NotIn, values: [nvidia]正是 VKE 用于标记 GPU 节点的标签确保 CPU 密集型的网关流量不挤占 GPU 节点gateway-plugins 定制gateway_plugins_patch.yaml同样通过节点亲和性避免调度到 GPU 节点并注入面向 VKE 场景的插件环境变量例如关闭 GPU 优化器追踪AIBRIX_GPU_OPTIMIZER_TRACING_FLAGfalse、设置字符级前缀缓存分词器AIBRIX_PREFIX_CACHE_TOKENIZER_TYPEcharacter、前缀缓存块大小 128 / 块数 200000以及负载均衡不均衡最小间隔AIBRIX_LOAD_BALANCE_IMBALANCE_MIN_GAP16、前缀缓存标准差因子AIBRIX_PREFIX_CACHE_STANDARD_DEVIATION_FACTOR2。第 3 步等待组件就绪kubectl -n aibrix-system get pods kubectl -n envoy-gateway-system get pods等待 controller-manager、gateway、gateway-plugins、metadata-service 等 Pod 全部进入Running/Ready状态后再进行下一步。三、在 TOS 中准备模型并创建集群凭据AIBrix 的模型下载依赖火山引擎对象存储 TOS。假设你的模型已上传至 TOS 桶本文示例桶为aibrix-artifact-testing路径为models/DeepSeek-R1-Distill-Llama-8B/接下来在集群中创建凭据 Secretkubectl create secret generic tos-credential --from-literalTOS_ACCESS_KEYYOUR_ACCESS_KEY --from-literalTOS_SECRET_KEYYOUR_SECRET_KEY该 Secret 会被后续 Deployment 的 initContainer 以secretKeyRef方式引用key 分别为TOS_ACCESS_KEY与TOS_SECRET_KEY因此 Secret 名称必须为tos-credential且创建于 Deployment 所在命名空间本文示例为default。源码视角TOS 下载器如何工作AIBrix 的模型下载能力实现在 python/aibrix/aibrix/downloader/tos.py 中。TOSDownloaderV1的关键逻辑包括URI 解析_parse_bucket_info_from_uri通过urlparse(uri, schemetos)将tos://bucket/path拆分为桶名与桶内路径凭据解析优先级download_extra_config.ak/sk/endpoint/region优先其次回退到环境变量DOWNLOADER_TOS_ACCESS_KEY、DOWNLOADER_TOS_SECRET_KEY、DOWNLOADER_TOS_ENDPOINT、DOWNLOADER_TOS_REGION——这与 sample 中通过环境变量注入的用法一致断点续传与校验下载前通过head_object获取 ETag 与文件大小调用need_to_download判断本地文件是否已完整元数据文件记录于.meta已存在则跳过下载过程中先写.part临时文件完成后原子替换为目标文件并保存元数据并发下载num_threads对应环境变量DOWNLOADER_NUM_THREADS决定分片线程数配合part_chunksize实现 TOS 分片并发传输。因此在模型较大时可像 sample 一样适当调大DOWNLOADER_NUM_CONNECTIONS与DOWNLOADER_NUM_THREADS以缩短下载时间。四、部署基础单角色模型将以下内容保存为model.yaml完整文件见 samples/quickstart/vke/model.yaml然后执行kubectl apply -f model.yamlapiVersion: apps/v1 kind: Deployment metadata: name: deepseek-r1-distill-llama-8b labels: model.aibrix.ai/name: deepseek-r1-distill-llama-8b model.aibrix.ai/port: 8000 spec: replicas: 1 strategy: rollingUpdate: maxSurge: 1 maxUnavailable: 1 type: RollingUpdate selector: matchLabels: model.aibrix.ai/name: deepseek-r1-distill-llama-8b template: metadata: labels: model.aibrix.ai/name: deepseek-r1-distill-llama-8b model.aibrix.ai/port: 8000 annotations: prometheus.io/path: /metrics prometheus.io/port: 8000 prometheus.io/scrape: true spec: initContainers: - command: - aibrix_download - --model-uri - tos://aibrix-artifact-testing/models/DeepSeek-R1-Distill-Llama-8B/ - --local-dir - /models/ env: - name: DOWNLOADER_NUM_CONNECTIONS value: 16 - name: DOWNLOADER_NUM_THREADS value: 16 - name: DOWNLOADER_ALLOW_FILE_SUFFIX value: json, safetensors - name: TOS_ACCESS_KEY valueFrom: secretKeyRef: key: TOS_ACCESS_KEY name: tos-credential - name: TOS_SECRET_KEY valueFrom: secretKeyRef: key: TOS_SECRET_KEY name: tos-credential - name: TOS_ENDPOINT value: https://tos-s3-cn-beijing.ivolces.com - name: TOS_REGION value: cn-beijing image: aibrix-public-release-cn-beijing.cr.volces.com/aibrix/runtime:v0.5.0 name: init-model volumeMounts: - mountPath: /models name: model-hostpath containers: - name: vllm-openai image: aibrix-public-release-cn-beijing.cr.volces.com/vllm/vllm-openai:0.11.0 imagePullPolicy: Always command: - vllm - serve - /models/DeepSeek-R1-Distill-Llama-8B/ - --port - 8000 - --uvicorn-log-level - warning - --trust-remote-code - --served-model-name - deepseek-r1-distill-llama-8b - --disable-fastapi-docs volumeMounts: - mountPath: /models name: model-hostpath resources: limits: nvidia.com/gpu: 1 cpu: 12 memory: 48G requests: nvidia.com/gpu: 1 cpu: 12 memory: 48G livenessProbe: httpGet: path: /health port: 8000 scheme: HTTP failureThreshold: 3 periodSeconds: 5 successThreshold: 1 timeoutSeconds: 1 readinessProbe: httpGet: path: /health port: 8000 scheme: HTTP failureThreshold: 5 periodSeconds: 5 successThreshold: 1 timeoutSeconds: 1 startupProbe: httpGet: path: /health port: 8000 scheme: HTTP failureThreshold: 30 periodSeconds: 5 successThreshold: 1 timeoutSeconds: 1 volumes: - name: model-hostpath hostPath: path: /data01/models/ type: DirectoryOrCreate --- apiVersion: v1 kind: Service metadata: labels: model.aibrix.ai/name: deepseek-r1-distill-llama-8b prometheus-discovery: true annotations: prometheus.io/scrape: true prometheus.io/port: 8080 name: deepseek-r1-distill-llama-8b # Note: The Service name must match the label value model.aibrix.ai/name in the Deployment namespace: default spec: ports: - name: serve port: 8000 protocol: TCP targetPort: 8000 - name: http port: 8080 protocol: TCP targetPort: 8080 selector: model.aibrix.ai/name: deepseek-r1-distill-llama-8b type: ClusterIP关键点解析模型发现三件套Deployment 与 Service 必须带有model.aibrix.ai/name标签且Service 名称必须与标签值完全一致deepseek-r1-distill-llama-8bmodel.aibrix.ai/port标签声明推理端口8000AIBrix gateway 据此自动发现后端并路由TOS 下载 initContainer使用aibrix/runtime镜像执行aibrix_download--model-uri指向 TOS 路径--local-dir为挂载目录/models/通过secretKeyRef从tos-credential注入密钥并显式指定TOS_ENDPOINThttps://tos-s3-cn-beijing.ivolces.com与TOS_REGIONcn-beijing需按你的 TOS 地域调整DOWNLOADER_ALLOW_FILE_SUFFIXjson, safetensors可过滤只下载推理必需的文件避免拉取全部仓库内容vLLM 服务配置主容器使用vllm/vllm-openai:0.11.0以--served-model-name deepseek-r1-distill-llama-8b暴露 OpenAI 兼容接口--trust-remote-code用于支持部分需要远程代码的模型DeepSeek-R1-Distill-Llama-8B 场景需要资源声明 1 张 GPU、12 核 CPU、48G 内存健康检查三层探针均探测 vLLM 的/health接口startupProbe的failureThreshold: 30、periodSeconds: 5意味着最多给模型 150 秒的冷启动窗口避免大模型加载期间被误杀主机路径共享模型hostPath: /data01/models/让 initContainer 下载的模型直接落盘供主容器复用同一批 Pod 落在相同节点时无需重复下载。生产环境建议替换为共享存储如 TOS FUSE / PVC指标采集prometheus.io/*注解开启 vLLM 与 8080 端口的指标抓取prometheus-discovery: true标签便于 AIBrix 控制面按模型聚合指标。五、部署 Prefill-DecodePD分离模型PD 分离Prefill-Decode Disaggregation将推理拆分为 prefill 与 decode 两个角色各自独立扩缩容是长上下文与高吞吐场景的常见优化。在 VKE 上通过StormService声明式部署 1P1D1 个 prefill 1 个 decode拓扑。将以下内容保存为pd-model.yaml完整文件见 samples/quickstart/vke/pd-model.yaml然后执行kubectl apply -f pd-model.yamlapiVersion: orchestration.aibrix.ai/v1alpha1 kind: StormService metadata: name: vllm-1p1d spec: replicas: 1 updateStrategy: type: InPlaceUpdate stateful: true selector: matchLabels: app: vllm-1p1d template: metadata: labels: app: vllm-1p1d spec: roles: - name: prefill replicas: 1 stateful: true template: metadata: labels: model.aibrix.ai/name: deepseek-r1-distill-llama-8b model.aibrix.ai/port: 8000 model.aibrix.ai/engine: vllm spec: containers: - name: prefill image: aibrix-public-release-cn-beijing.cr.volces.com/aibrix/vllm-openai:v0.10.2-aibrix-v0.5.0-nixl-0.7.1-20251123 command: [sh, -c] args: - | vllm serve \ --host 0.0.0.0 \ --port 8000 \ --uvicorn-log-level warning \ --model /models/DeepSeek-R1-Distill-Llama-8B \ --served-model-name deepseek-r1-distill-llama-8b env: - name: PYTHONHASHSEED value: 1047 - name: VLLM_SERVER_DEV_MODE value: 1 - name: VLLM_NIXL_SIDE_CHANNEL_HOST value: 0.0.0.0 - name: VLLM_NIXL_SIDE_CHANNEL_PORT value: 5558 - name: VLLM_WORKER_MULTIPROC_METHOD value: spawn - name: VLLM_ENABLE_V1_MULTIPROCESSING value: 0 - name: GLOO_SOCKET_IFNAME value: eth0 - name: NCCL_SOCKET_IFNAME value: eth0 resources: limits: nvidia.com/gpu: 1 requests: nvidia.com/gpu: 1 securityContext: capabilities: add: - IPC_LOCK volumeMounts: - mountPath: /models name: model-hostpath volumes: - name: model-hostpath hostPath: path: /root/models type: DirectoryOrCreate - name: decode replicas: 1 stateful: true template: metadata: labels: model.aibrix.ai/name: deepseek-r1-distill-llama-8b model.aibrix.ai/port: 8000 model.aibrix.ai/engine: vllm spec: containers: - name: decode image: aibrix-public-release-cn-beijing.cr.volces.com/aibrix/vllm-openai:v0.10.2-aibrix-v0.5.0-nixl-0.7.1-20251123 command: [sh, -c] args: - | vllm serve \ --host 0.0.0.0 \ --port 8000 \ --uvicorn-log-level warning \ --model /models/DeepSeek-R1-Distill-Llama-8B \ --served-model-name deepseek-r1-distill-llama-8b \ --kv-transfer-config {kv_connector:NixlConnector,kv_role:kv_both} env: - name: PYTHONHASHSEED value: 1047 - name: VLLM_SERVER_DEV_MODE value: 1 - name: VLLM_NIXL_SIDE_CHANNEL_HOST value: 0.0.0.0 - name: VLLM_NIXL_SIDE_CHANNEL_PORT value: 5558 - name: VLLM_WORKER_MULTIPROC_METHOD value: spawn - name: VLLM_ENABLE_V1_MULTIPROCESSING value: 0 - 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 resources: limits: nvidia.com/gpu: 1 requests: nvidia.com/gpu: 1 securityContext: capabilities: add: - IPC_LOCK volumeMounts: - mountPath: /models name: model-hostpath volumes: - name: model-hostpath hostPath: path: /root/models type: DirectoryOrCreate关键点解析StormService 多角色编排orchestration.aibrix.ai/v1alpha1的 StormService 在spec.roles下声明prefill与decode两个角色各 1 副本stateful: true保证角色身份稳定updateStrategy.type: InPlaceUpdate表示原地更新AIBrix 的 StormService 控制器支持原地更新参见 samples/orchestration/stormservice-inplace-update.yaml两角色同模型同服务名prefill 与 decode 使用相同的--served-model-name deepseek-r1-distill-llama-8b但 decode 额外追加--kv-transfer-config {kv_connector:NixlConnector,kv_role:kv_both}——这是 vLLM 的 KV 传输配置kv_both表示 decode 节点同时承担 KV 的发送与接收通过 NixlConnector 在 prefill 与 decode 之间搬运 KV cache基于 NIXL 的高性能传输层NIXL 侧信道两侧均设置VLLM_NIXL_SIDE_CHANNEL_HOST0.0.0.0与VLLM_NIXL_SIDE_CHANNEL_PORT5558用于 NIXL 建立侧信道VLLM_ENABLE_V1_MULTIPROCESSING0、VLLM_WORKER_MULTIPROC_METHODspawn与PYTHONHASHSEED1047是 vLLM 多进程稳定性相关配置网络协议栈prefill 设置GLOO_SOCKET_IFNAMEeth0、NCCL_SOCKET_IFNAMEeth0decode 额外启用 RDMA/InfiniBand 相关配置NCCL_IB_DISABLE0、NCCL_IB_GID_INDEX7、NCCL_DEBUGINFO、UCX_TLS^gga适合 VKE 上启用 RDMA 的高性能节点若你的节点没有 RDMA需要按实际网络调整这些环境变量IPC_LOCK 能力securityContext.capabilities.add: [IPC_LOCK]允许容器锁定内存配合大页/锁页内存使用模型共享与基础模型类似通过hostPath: /root/models共享模型目录PD 场景中模型可预先下载到节点或由部署流程先行拉取。六、通过网关验证推理模型就绪后通过 Envoy 网关的 LoadBalancer IP 发起推理请求。VKE overlay 已将 Envoy Proxy Service 固定为 IPv4 单栈 LoadBalancer可直接取到外部 IPLB_IP$(kubectl get svc/envoy-aibrix-system-aibrix-eg-903790dc -n envoy-gateway-system -ojsonpath{.status.loadBalancer.ingress[0].ip}) ENDPOINT${LB_IP}:80 curl http://${ENDPOINT}/v1/chat/completions \ -H Content-Type: application/json \ -H routing-strategy: random \ # change to pd if you deployed in disaggregation mode -d { model: deepseek-r1-distill-llama-8b, messages: [ {role: system, content: You are a helpful assistant.}, {role: user, content: help me write a random generator in python} ] }要点Service 名称envoy-aibrix-system-aibrix-eg-903790dc是 AIBrix 在envoy-gateway-system命名空间下创建的 Envoy 网关 Service名称中的哈希由 Envoy Gateway 生成以实际集群中查询到的为准routing-strategy 请求头这是 AIBrix gateway 的路由策略开关。random随机选择后端实例适用于单角色基础模型部署若部署的是 PD 分离模型本文第五节的 StormService请将请求头改为pd网关会将请求路由到 prefill/decode 分离的拓扑上model 字段必须与--served-model-name即deepseek-r1-distill-llama-8b一致网关据此匹配模型后端返回 200 且包含choices[0].message.content即为推理成功。七、常见问题与排查思路镜像拉取失败确认所有镜像均来自*.cr.volces.com仓库若自建 VKE 私仓请相应修改 overlay 中的images替换规则与 Helm values。模型下载失败检查tos-credentialSecret 是否存在且 key 名正确TOS_ACCESS_KEY/TOS_SECRET_KEY确认TOS_ENDPOINT与TOS_REGION与桶所在地域匹配可通过kubectl logs pod -c init-model查看aibrix_download的报错凭据、桶不存在等错误分别对应 tos.py 中的ArgNotCongiuredError与ModelNotFoundError。网关 Pod 被调度到 GPU 节点VKE 的 GPU 节点标签若不是vke.node.gpu.schedulenvidia请调整 envoy_proxy_patch.yaml 与 gateway_plugins_patch.yaml 中的节点亲和性表达式。PD 模式请求失败确认请求头为routing-strategy: pd且 StormService 的 prefill/decode 均处于 ReadyKV 传输问题可从 decode 容器的NCCL_DEBUG日志中定位。推理超时大模型冷启动较慢检查startupProbe的 150 秒窗口是否足够必要时调大failureThreshold。总结本文完整覆盖了 AIBrix 在火山引擎 VKE 上的部署路径通过 config/overlays/vke 专属 overlay 完成镜像仓库与网关定制、以 Helm 安装主组件、创建 TOS 凭据并经 initContainer 拉取模型、分别以原生 Deployment 与 StormService 部署基础/PD 分离模型最后通过 Envoy 网关以random/pd路由验证推理。整套流程可直接复用于生产 VKE 集群也可作为理解 AIBrix 云厂商适配机制的参考范例。【免费下载链接】aibrixCost-efficient and pluggable Infrastructure components for GenAI inference项目地址: https://gitcode.com/GitHub_Trending/ai/aibrix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考