AIBrix 进阶 Kubernetes 部署指南PVC 模型缓存 生产级资源配置实战DeepSeek-R1-Distill-Llama-8B 示例【免费下载链接】aibrixCost-efficient and pluggable Infrastructure components for GenAI inference项目地址: https://gitcode.com/GitHub_Trending/ai/aibrix导读本文基于 AIBrix 官方文档《Advanced Kubernetes Examples》docs/source/getting_started/advanced-k8s-examples.rst展开演示在 Kubernetes 上以PVCPersistent Volume Claim持久化缓存 HuggingFace 模型权重、并通过精细化的资源配额、三阶段健康探针与 Prometheus 监控注解把 vLLM 推理服务以生产级标准部署到 AIBrix 集群的完整方案。读完本文你将掌握如何搭建带安全策略的独立命名空间、如何为 vLLM 配置模型缓存卷与共享内存、如何编写 liveness/readiness/startup 探针与 GPU/CPU/内存配额以及如何让模型服务被 AIBrix 网关识别并被 Prometheus 自动发现。一、为什么需要进阶的 Kubernetes 部署模式AIBrix 的核心定位是面向 GenAI 推理的成本高效、可插拔基础设施组件。在真实生产环境中仅仅把 vLLM 跑起来远远不够还需要解决三个高频问题模型权重的重复拉取与下载抖动大模型权重动辄数 GB 到数百 GB每次 Pod 重建都从 HuggingFace 重新下载既慢又浪费带宽资源与稳定性的失控风险vLLM 服务在模型加载阶段 CPU、内存压力极大若没有合理的 requests/limits 与探针保护集群调度和故障自愈都会出问题可观测性与路由接入的缺失模型服务必须通过标准标签被 AIBrix 网关发现并通过指标端点被 Prometheus 抓取否则无法参与智能路由与弹性伸缩。本示例DeepSeek-R1-Distill-Llama-8B vLLM正是针对以上问题给出的最小完整参考实现覆盖四个关键能力PVC Caching—— 30Gi 持久化存储挂载到/root/.cache/huggingface模型只下载一次Pod 重建后即挂即用Resource Limits—— 显式声明 GPU / CPU / Memory 的 limits 与 requestsHealth Monitoring—— 多阶段startup liveness readiness探针与失败阈值配置Metrics Integration—— 通过 Prometheus 注解完成服务发现。二、完整示例清单逐对象解析以下清单由 4 个 Kubernetes 对象组成可通过一个文件整体kubectl apply -f交付Namespace→Deployment→Service→PersistentVolumeClaim。2.1 命名空间与安全策略NamespaceapiVersion: v1 kind: Namespace metadata: labels: pod-security.kubernetes.io/enforce: baseline pod-security.kubernetes.io/audit: restricted pod-security.kubernetes.io/warn: restricted name: aibrix-system-llm命名空间aibrix-system-llm通过Pod Security AdmissionPSA三层标签声明安全策略enforce: baseline强制基线策略拒绝明显危险的能力如特权容器、hostPID 等保证部署可运行audit: restricted对违反 restricted最严格策略的 Pod 记录审计日志但不阻断warn: restricted对违反 restricted 策略的 Pod 向客户端返回警告。这种强制宽松 审计严格的组合适合推理集群既不会因为 restricted 策略误伤 vLLM 等依赖共享内存/设备插件的镜像又能持续暴露安全风险。2.2 vLLM 模型部署DeploymentapiVersion: apps/v1 kind: Deployment metadata: labels: model.aibrix.ai/name: deepseek-r1-distill-llama-8b model.aibrix.ai/port: 8000 name: deepseek-r1-distill-llama-8b namespace: aibrix-system-llm spec: replicas: 1 selector: matchLabels: model.aibrix.ai/name: deepseek-r1-distill-llama-8b template: metadata: labels: model.aibrix.ai/name: deepseek-r1-distill-llama-8b spec: volumes: - name: cache-volume persistentVolumeClaim: claimName: deepseek-r1-distill-llama-8b - name: shm emptyDir: medium: Memory sizeLimit: 2Gi containers: - command: - vllm - serve - --host - 0.0.0.0 - --port - 8000 - --uvicorn-log-level - warning - --model - deepseek-ai/DeepSeek-R1-Distill-Llama-8B - --served-model-name - deepseek-r1-distill-llama-8b - --max-model-len - 12288 image: vllm/vllm-openai:v0.9.0 imagePullPolicy: IfNotPresent name: vllm-openai ports: - containerPort: 8000 protocol: TCP resources: limits: cpu: 8 memory: 20G nvidia.com/gpu: 1 requests: cpu: 2 memory: 6G nvidia.com/gpu: 1 volumeMounts: - mountPath: /root/.cache/huggingface name: cache-volume - name: shm mountPath: /dev/shm livenessProbe: httpGet: path: /health port: 8000 scheme: HTTP failureThreshold: 3 periodSeconds: 5 successThreshold: 1 timeoutSeconds: 3 initialDelaySeconds: 30 readinessProbe: httpGet: path: /health port: 8000 scheme: HTTP failureThreshold: 5 periodSeconds: 5 successThreshold: 1 timeoutSeconds: 3 initialDelaySeconds: 30 startupProbe: httpGet: path: /health port: 8000 scheme: HTTP failureThreshold: 30 periodSeconds: 5本 Deployment 是整套方案的心脏几个要点值得展开1vLLM 启动参数vllm serve监听0.0.0.0:8000--uvicorn-log-level warning降低日志噪音--model deepseek-ai/DeepSeek-R1-Distill-Llama-8B指向 HuggingFace 上的模型仓库 ID--served-model-name deepseek-r1-distill-llama-8b对外暴露的模型名必须与model.aibrix.ai/name标签保持一致保证网关路由与模型名解析一致--max-model-len 12288显式约束最大序列长度防止显存被长序列打爆该值需按实际模型与显存调整。2双卷设计cache-volume挂载 PVCdeepseek-r1-distill-llama-8b到/root/.cache/huggingface。HuggingFacetransformers的缓存目录正是~/.cache/huggingfacevLLM 首次加载时会自动把模型权重落入该目录从而把模型权重冻结在持久卷中之后每次重启/扩容都直接从本地磁盘读取shmemptyDirmedium: Memory的 2Gi 共享内存卷挂载到/dev/shm。vLLM 在张量并行与部分算子如 PagedAttention 相关中依赖/dev/shmKubernetes 默认的 64Mi shm 极易成为瓶颈这是大模型推理部署中一个非常常见但隐蔽的坑。3资源配额requests2 CPU / 6G 内存 / 1 张 GPU作为调度与 QoS 基线limits8 CPU / 20G 内存 / 1 张 GPU锁定上限。CPU 的 requests 与 limits 差距2→8允许突发使用 CPU 进行 prefill 计算而内存上限保护节点不被 OOM 拖垮GPU 显式声明nvidia.com/gpu: 1由 NVIDIA Device Plugin 调度。4三阶段探针详见第五节。2.3 服务暴露与指标发现ServiceapiVersion: 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 namespace: aibrix-system-llm 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: ClusterIPService 是可被网关路由与可被监控发现的关键入口selector通过model.aibrix.ai/name: deepseek-r1-distill-llama-8b精确选中模型 Pod该标签必须在 Deployment 的spec.selector.matchLabels与 Pod template labels 中完全一致同时暴露serve8000推理流量与http8080指标/辅助流量两个端口prometheus-discovery: true标签 prometheus.io/scrape: true、prometheus.io/port: 8080注解是常见的 Prometheus 服务发现kubernetes_sd约定采集器发现该 Service 后会向 8080 端口抓取指标。2.4 模型缓存卷PersistentVolumeClaimapiVersion: v1 kind: PersistentVolumeClaim metadata: name: deepseek-r1-distill-llama-8b namespace: aibrix-system-llm spec: accessModes: - ReadWriteOnce resources: requests: storage: 30Gi volumeMode: Filesystem storageClassName: defaultReadWriteOnce单节点读写与单副本 vLLM Deployment 的语义匹配30Gi为 DeepSeek-R1-Distill-Llama-8B约 8B 参数fp16 权重约 16GB 级及后续扩展预留充足空间volumeMode: Filesystem显式声明文件系统卷storageClassName: default使用集群默认 StorageClass ——该值必须与集群实际配置匹配否则 PVC 会一直处于 Pending。三、model.aibrix.ai/name与model.aibrix.ai/port标签AIBrix 网关的路由契约示例中反复出现的model.aibrix.ai/name与model.aibrix.ai/port并非普通标签而是 AIBrix 系统的核心路由契约。在源码 pkg/constants/model.go 中定义如下// ModelLabelName is the label for identifying the model name ModelLabelName model.aibrix.ai/name // ModelLabelPort is the label for specifying the service port ModelLabelPort model.aibrix.ai/port从源码结构看AIBrix 网关插件正是通过读取 Pod/Service 上的这两个标签来确定哪个 Pod 服务哪个模型、监听哪个端口从而把/v1/chat/completions等请求路由到正确的推理实例。例如 pkg/utils/util.go 中从 Pod 标签解析模型端口的逻辑portStr, ok : pod.Labels[constants.ModelLabelPort] if !ok { return 0, fmt.Errorf(no %s label found, constants.ModelLabelPort) }同时 pkg/utils/pod.go 提供了GetModelPortForPod供路由决策时取用。这意味着标签拼写错误或 Deployment/Service 之间标签不一致将直接导致模型无法被发现或路由失败——这正是原文档Usage Notes中强调Model name labels must match across Deployment/Service的底层原因。在仓库的 samples/deepseek-r1 系列样例中这一约定贯穿始终无论是单机部署的deepseek-r1-huggingface.yaml、PVC 方式的deepseek-r1-pvc.yaml还是 671B 多机分布的RayClusterFleet清单都在 metadata、selector、pod template 三处成对出现model.aibrix.ai/name与model.aibrix.ai/port: 8000。四、PVC 缓存 vs 其他模型存储方案如何选择本文档示例选择了PVC 缓存 HuggingFace 模型这一模式。仓库中 samples/deepseek-r1/README.md 给出了更完整的存储选型对比可以帮助你理解该模式在整体方案中的位置存储方案说明参考样例HuggingFace 直连无需卷Pod 直接在线拉取权重大模型不推荐张量尺寸不一导致大量随机读网络/I/O 效率低deepseek-r1-huggingface.yamlPersistent Volume本文示例通过 CSI 挂载 PVC权重常驻持久卷Pod 重建免下载deepseek-r1-pvc.yaml对象存储S3/GCS AIBrix AI RuntimeRuntime 自动把权重从对象存储下载到宿主机卷灵活可扩展deepseek-r1-ai-runtime.yaml本地盘HostPath InitContainer 预下载适合对性能/安全有特殊要求的场景deepseek-r1-local-nvme.yaml对比可见PVC 缓存模式在部署简单与免重复下载之间取得了最佳平衡它不需要额外的 AI Runtime 或下载器组件只需一个标准 PVC 挂载到 HuggingFace 缓存目录vLLM 自身即完成权重的落盘与复用。仓库中的deepseek-r1-pvc.yaml展示的 671B 场景则将 PVC 挂载到/models/deepseek并以vllm serve /models/deepseek直接加载本地权重——两种做法路径不同~/.cache/huggingface隐式缓存 vs 显式模型目录但思想一致让模型权重常驻持久卷避免网络重复拉取。五、三阶段健康探针守护模型加载的慢启动大模型服务的健康检查与传统 Web 服务最大的不同在于启动极慢vLLM 需要加载权重、构建 KV cache、预热 CUDA context单是下载加载就可能耗时数分钟。如果只用 readiness 探针探针在超时前就会把 Pod 标记为不健康并触发重启形成永远起不来的循环。本示例用三个阶段探针解决该问题探针判定目标本示例配置失败后果startupProbe容器是否完成初始化权重加载等periodSeconds: 5×failureThreshold: 30即最多等待 150s超时则按restartPolicy重启容器期间 liveness 不生效livenessProbe容器是否存活initialDelaySeconds: 30之后每 5s 探测一次failureThreshold: 3连续 3 次失败则 kubelet 重启容器readinessProbe是否可接收流量每 5s 一次failureThreshold: 5连续 5 次失败则从 Service Endpoints 摘除不转发流量三者都请求/health端点vLLM OpenAI Server 内置健康检查关键设计startupProbe承担漫长启动期的兜底——它给了最多150 秒30 次 × 5s的启动窗口窗口内 liveness 探针不会触发误杀三个探针都设置了initialDelaySeconds: 30避开模型加载初期/health尚未就绪的时段原文档明确提示Probe delays accommodate model loading time (30s initial delay)readinessProbe的失败阈值5高于 liveness3避免瞬时抖动导致 Pod 被频繁摘除。与之对比仓库 samples/deepseek-r1/deepseek-r1-pvc.yaml 中 671B 模型的startupProbe配置为initialDelaySeconds: 180、periodSeconds: 10、failureThreshold: 150即最长允许1500 秒启动——模型越大启动窗口越需要放宽这也是按模型规模调整探针参数的最佳实践例证。六、部署步骤与验证将完整清单保存为advanced-k8s-examples.yaml后执行kubectl apply -f advanced-k8s-examples.yaml验证顺序建议# 1. 确认 PVC 已绑定Pending 说明 storageClassName 与集群不匹配 kubectl -n aibrix-system-llm get pvc deepseek-r1-distill-llama-8b # 2. 观察 Pod 状态ContainerCreating → Running首次启动需等待权重下载 kubectl -n aibrix-system-llm get pods -w # 3. 确认探针就绪 kubectl -n aibrix-system-llm describe pod pod-name | grep -A5 Probe\|Readiness # 4. 验证推理服务 kubectl -n aibrix-system-llm port-forward svc/deepseek-r1-distill-llama-8b 8000:8000 curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: deepseek-r1-distill-llama-8b, messages: [{role: user, content: Hello}] }首次请求若长时间无响应优先检查startupProbe是否仍在等待窗口内以及kubectl logs中权重下载进度。模型权重下载完成后删除 Pod 再重建即可验证 PVC 缓存生效重建后的 Pod 将直接从持久卷加载权重启动时间大幅缩短且不会产生新的外网下载流量。七、使用注意事项来自原文档原文档在Usage Notes中给出了四条必须遵守的约束这里结合源码与配置逐一说明Model name labels must match across Deployment/Servicemodel.aibrix.ai/name必须在 Deployment 的 metadata、selector、Pod template 以及 Service 的 selector 中完全一致。这是 AIBrix 网关发现模型并正确路由的前提参见 pkg/constants/model.go 的标签定义PVC storage class should match cluster configurationstorageClassName: default是占位约定实际部署必须改为集群真实存在的 StorageClass否则 PVC 无法绑定Pod 将长期停留在 PendingAdjustmax-model-lenaccording to actual model requirements--max-model-len 12288是按 8B 模型与单卡显存估算的值更换模型或 GPU 时必须重新评估设置过大可能 OOM过小会截断长上下文请求Probe delays accommodate model loading time (30s initial delay)所有探针均设置了 30s 的initialDelaySeconds配合 startupProbe 的 150s 窗口覆盖模型权重下载与加载的慢启动过程切勿在模型加载阶段触发误杀重启。八、小结本文档示例虽然只是一个单 Deployment PVC的迷你清单却浓缩了 AIBrix 生产化部署的四大要素持久化模型缓存PVC解决重复下载问题、显式资源配额保障调度与稳定性、三阶段探针驯服慢启动、标准标签与 Prometheus 注解打通路由与观测。其中model.aibrix.ai/name/model.aibrix.ai/port标签是 AIBrix 网关路由的契约见 pkg/constants/model.go 与 pkg/utils/util.goPVC 挂载路径则与 HuggingFace 缓存目录语义对齐。以此为起点你可以进一步探索仓库中的进阶资源通过 samples/deepseek-r1 系列样例学习 671B 大模型的 RayClusterFleet 多机部署、AI Runtime 对象存储下载模式通过 config/samples 中的podautoscaler、kvcache样例为你的模型叠加弹性伸缩与 KV cache 能力将能跑起来升级为跑得稳、省得下、可观测。【免费下载链接】aibrixCost-efficient and pluggable Infrastructure components for GenAI inference项目地址: https://gitcode.com/GitHub_Trending/ai/aibrix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
AIBrix 进阶 Kubernetes 部署指南：PVC 模型缓存 + 生产级资源配置实战（DeepSeek-R1-Distill-Llama-8B 示例）
AIBrix 进阶 Kubernetes 部署指南PVC 模型缓存 生产级资源配置实战DeepSeek-R1-Distill-Llama-8B 示例【免费下载链接】aibrixCost-efficient and pluggable Infrastructure components for GenAI inference项目地址: https://gitcode.com/GitHub_Trending/ai/aibrix导读本文基于 AIBrix 官方文档《Advanced Kubernetes Examples》docs/source/getting_started/advanced-k8s-examples.rst展开演示在 Kubernetes 上以PVCPersistent Volume Claim持久化缓存 HuggingFace 模型权重、并通过精细化的资源配额、三阶段健康探针与 Prometheus 监控注解把 vLLM 推理服务以生产级标准部署到 AIBrix 集群的完整方案。读完本文你将掌握如何搭建带安全策略的独立命名空间、如何为 vLLM 配置模型缓存卷与共享内存、如何编写 liveness/readiness/startup 探针与 GPU/CPU/内存配额以及如何让模型服务被 AIBrix 网关识别并被 Prometheus 自动发现。一、为什么需要进阶的 Kubernetes 部署模式AIBrix 的核心定位是面向 GenAI 推理的成本高效、可插拔基础设施组件。在真实生产环境中仅仅把 vLLM 跑起来远远不够还需要解决三个高频问题模型权重的重复拉取与下载抖动大模型权重动辄数 GB 到数百 GB每次 Pod 重建都从 HuggingFace 重新下载既慢又浪费带宽资源与稳定性的失控风险vLLM 服务在模型加载阶段 CPU、内存压力极大若没有合理的 requests/limits 与探针保护集群调度和故障自愈都会出问题可观测性与路由接入的缺失模型服务必须通过标准标签被 AIBrix 网关发现并通过指标端点被 Prometheus 抓取否则无法参与智能路由与弹性伸缩。本示例DeepSeek-R1-Distill-Llama-8B vLLM正是针对以上问题给出的最小完整参考实现覆盖四个关键能力PVC Caching—— 30Gi 持久化存储挂载到/root/.cache/huggingface模型只下载一次Pod 重建后即挂即用Resource Limits—— 显式声明 GPU / CPU / Memory 的 limits 与 requestsHealth Monitoring—— 多阶段startup liveness readiness探针与失败阈值配置Metrics Integration—— 通过 Prometheus 注解完成服务发现。二、完整示例清单逐对象解析以下清单由 4 个 Kubernetes 对象组成可通过一个文件整体kubectl apply -f交付Namespace→Deployment→Service→PersistentVolumeClaim。2.1 命名空间与安全策略NamespaceapiVersion: v1 kind: Namespace metadata: labels: pod-security.kubernetes.io/enforce: baseline pod-security.kubernetes.io/audit: restricted pod-security.kubernetes.io/warn: restricted name: aibrix-system-llm命名空间aibrix-system-llm通过Pod Security AdmissionPSA三层标签声明安全策略enforce: baseline强制基线策略拒绝明显危险的能力如特权容器、hostPID 等保证部署可运行audit: restricted对违反 restricted最严格策略的 Pod 记录审计日志但不阻断warn: restricted对违反 restricted 策略的 Pod 向客户端返回警告。这种强制宽松 审计严格的组合适合推理集群既不会因为 restricted 策略误伤 vLLM 等依赖共享内存/设备插件的镜像又能持续暴露安全风险。2.2 vLLM 模型部署DeploymentapiVersion: apps/v1 kind: Deployment metadata: labels: model.aibrix.ai/name: deepseek-r1-distill-llama-8b model.aibrix.ai/port: 8000 name: deepseek-r1-distill-llama-8b namespace: aibrix-system-llm spec: replicas: 1 selector: matchLabels: model.aibrix.ai/name: deepseek-r1-distill-llama-8b template: metadata: labels: model.aibrix.ai/name: deepseek-r1-distill-llama-8b spec: volumes: - name: cache-volume persistentVolumeClaim: claimName: deepseek-r1-distill-llama-8b - name: shm emptyDir: medium: Memory sizeLimit: 2Gi containers: - command: - vllm - serve - --host - 0.0.0.0 - --port - 8000 - --uvicorn-log-level - warning - --model - deepseek-ai/DeepSeek-R1-Distill-Llama-8B - --served-model-name - deepseek-r1-distill-llama-8b - --max-model-len - 12288 image: vllm/vllm-openai:v0.9.0 imagePullPolicy: IfNotPresent name: vllm-openai ports: - containerPort: 8000 protocol: TCP resources: limits: cpu: 8 memory: 20G nvidia.com/gpu: 1 requests: cpu: 2 memory: 6G nvidia.com/gpu: 1 volumeMounts: - mountPath: /root/.cache/huggingface name: cache-volume - name: shm mountPath: /dev/shm livenessProbe: httpGet: path: /health port: 8000 scheme: HTTP failureThreshold: 3 periodSeconds: 5 successThreshold: 1 timeoutSeconds: 3 initialDelaySeconds: 30 readinessProbe: httpGet: path: /health port: 8000 scheme: HTTP failureThreshold: 5 periodSeconds: 5 successThreshold: 1 timeoutSeconds: 3 initialDelaySeconds: 30 startupProbe: httpGet: path: /health port: 8000 scheme: HTTP failureThreshold: 30 periodSeconds: 5本 Deployment 是整套方案的心脏几个要点值得展开1vLLM 启动参数vllm serve监听0.0.0.0:8000--uvicorn-log-level warning降低日志噪音--model deepseek-ai/DeepSeek-R1-Distill-Llama-8B指向 HuggingFace 上的模型仓库 ID--served-model-name deepseek-r1-distill-llama-8b对外暴露的模型名必须与model.aibrix.ai/name标签保持一致保证网关路由与模型名解析一致--max-model-len 12288显式约束最大序列长度防止显存被长序列打爆该值需按实际模型与显存调整。2双卷设计cache-volume挂载 PVCdeepseek-r1-distill-llama-8b到/root/.cache/huggingface。HuggingFacetransformers的缓存目录正是~/.cache/huggingfacevLLM 首次加载时会自动把模型权重落入该目录从而把模型权重冻结在持久卷中之后每次重启/扩容都直接从本地磁盘读取shmemptyDirmedium: Memory的 2Gi 共享内存卷挂载到/dev/shm。vLLM 在张量并行与部分算子如 PagedAttention 相关中依赖/dev/shmKubernetes 默认的 64Mi shm 极易成为瓶颈这是大模型推理部署中一个非常常见但隐蔽的坑。3资源配额requests2 CPU / 6G 内存 / 1 张 GPU作为调度与 QoS 基线limits8 CPU / 20G 内存 / 1 张 GPU锁定上限。CPU 的 requests 与 limits 差距2→8允许突发使用 CPU 进行 prefill 计算而内存上限保护节点不被 OOM 拖垮GPU 显式声明nvidia.com/gpu: 1由 NVIDIA Device Plugin 调度。4三阶段探针详见第五节。2.3 服务暴露与指标发现ServiceapiVersion: 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 namespace: aibrix-system-llm 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: ClusterIPService 是可被网关路由与可被监控发现的关键入口selector通过model.aibrix.ai/name: deepseek-r1-distill-llama-8b精确选中模型 Pod该标签必须在 Deployment 的spec.selector.matchLabels与 Pod template labels 中完全一致同时暴露serve8000推理流量与http8080指标/辅助流量两个端口prometheus-discovery: true标签 prometheus.io/scrape: true、prometheus.io/port: 8080注解是常见的 Prometheus 服务发现kubernetes_sd约定采集器发现该 Service 后会向 8080 端口抓取指标。2.4 模型缓存卷PersistentVolumeClaimapiVersion: v1 kind: PersistentVolumeClaim metadata: name: deepseek-r1-distill-llama-8b namespace: aibrix-system-llm spec: accessModes: - ReadWriteOnce resources: requests: storage: 30Gi volumeMode: Filesystem storageClassName: defaultReadWriteOnce单节点读写与单副本 vLLM Deployment 的语义匹配30Gi为 DeepSeek-R1-Distill-Llama-8B约 8B 参数fp16 权重约 16GB 级及后续扩展预留充足空间volumeMode: Filesystem显式声明文件系统卷storageClassName: default使用集群默认 StorageClass ——该值必须与集群实际配置匹配否则 PVC 会一直处于 Pending。三、model.aibrix.ai/name与model.aibrix.ai/port标签AIBrix 网关的路由契约示例中反复出现的model.aibrix.ai/name与model.aibrix.ai/port并非普通标签而是 AIBrix 系统的核心路由契约。在源码 pkg/constants/model.go 中定义如下// ModelLabelName is the label for identifying the model name ModelLabelName model.aibrix.ai/name // ModelLabelPort is the label for specifying the service port ModelLabelPort model.aibrix.ai/port从源码结构看AIBrix 网关插件正是通过读取 Pod/Service 上的这两个标签来确定哪个 Pod 服务哪个模型、监听哪个端口从而把/v1/chat/completions等请求路由到正确的推理实例。例如 pkg/utils/util.go 中从 Pod 标签解析模型端口的逻辑portStr, ok : pod.Labels[constants.ModelLabelPort] if !ok { return 0, fmt.Errorf(no %s label found, constants.ModelLabelPort) }同时 pkg/utils/pod.go 提供了GetModelPortForPod供路由决策时取用。这意味着标签拼写错误或 Deployment/Service 之间标签不一致将直接导致模型无法被发现或路由失败——这正是原文档Usage Notes中强调Model name labels must match across Deployment/Service的底层原因。在仓库的 samples/deepseek-r1 系列样例中这一约定贯穿始终无论是单机部署的deepseek-r1-huggingface.yaml、PVC 方式的deepseek-r1-pvc.yaml还是 671B 多机分布的RayClusterFleet清单都在 metadata、selector、pod template 三处成对出现model.aibrix.ai/name与model.aibrix.ai/port: 8000。四、PVC 缓存 vs 其他模型存储方案如何选择本文档示例选择了PVC 缓存 HuggingFace 模型这一模式。仓库中 samples/deepseek-r1/README.md 给出了更完整的存储选型对比可以帮助你理解该模式在整体方案中的位置存储方案说明参考样例HuggingFace 直连无需卷Pod 直接在线拉取权重大模型不推荐张量尺寸不一导致大量随机读网络/I/O 效率低deepseek-r1-huggingface.yamlPersistent Volume本文示例通过 CSI 挂载 PVC权重常驻持久卷Pod 重建免下载deepseek-r1-pvc.yaml对象存储S3/GCS AIBrix AI RuntimeRuntime 自动把权重从对象存储下载到宿主机卷灵活可扩展deepseek-r1-ai-runtime.yaml本地盘HostPath InitContainer 预下载适合对性能/安全有特殊要求的场景deepseek-r1-local-nvme.yaml对比可见PVC 缓存模式在部署简单与免重复下载之间取得了最佳平衡它不需要额外的 AI Runtime 或下载器组件只需一个标准 PVC 挂载到 HuggingFace 缓存目录vLLM 自身即完成权重的落盘与复用。仓库中的deepseek-r1-pvc.yaml展示的 671B 场景则将 PVC 挂载到/models/deepseek并以vllm serve /models/deepseek直接加载本地权重——两种做法路径不同~/.cache/huggingface隐式缓存 vs 显式模型目录但思想一致让模型权重常驻持久卷避免网络重复拉取。五、三阶段健康探针守护模型加载的慢启动大模型服务的健康检查与传统 Web 服务最大的不同在于启动极慢vLLM 需要加载权重、构建 KV cache、预热 CUDA context单是下载加载就可能耗时数分钟。如果只用 readiness 探针探针在超时前就会把 Pod 标记为不健康并触发重启形成永远起不来的循环。本示例用三个阶段探针解决该问题探针判定目标本示例配置失败后果startupProbe容器是否完成初始化权重加载等periodSeconds: 5×failureThreshold: 30即最多等待 150s超时则按restartPolicy重启容器期间 liveness 不生效livenessProbe容器是否存活initialDelaySeconds: 30之后每 5s 探测一次failureThreshold: 3连续 3 次失败则 kubelet 重启容器readinessProbe是否可接收流量每 5s 一次failureThreshold: 5连续 5 次失败则从 Service Endpoints 摘除不转发流量三者都请求/health端点vLLM OpenAI Server 内置健康检查关键设计startupProbe承担漫长启动期的兜底——它给了最多150 秒30 次 × 5s的启动窗口窗口内 liveness 探针不会触发误杀三个探针都设置了initialDelaySeconds: 30避开模型加载初期/health尚未就绪的时段原文档明确提示Probe delays accommodate model loading time (30s initial delay)readinessProbe的失败阈值5高于 liveness3避免瞬时抖动导致 Pod 被频繁摘除。与之对比仓库 samples/deepseek-r1/deepseek-r1-pvc.yaml 中 671B 模型的startupProbe配置为initialDelaySeconds: 180、periodSeconds: 10、failureThreshold: 150即最长允许1500 秒启动——模型越大启动窗口越需要放宽这也是按模型规模调整探针参数的最佳实践例证。六、部署步骤与验证将完整清单保存为advanced-k8s-examples.yaml后执行kubectl apply -f advanced-k8s-examples.yaml验证顺序建议# 1. 确认 PVC 已绑定Pending 说明 storageClassName 与集群不匹配 kubectl -n aibrix-system-llm get pvc deepseek-r1-distill-llama-8b # 2. 观察 Pod 状态ContainerCreating → Running首次启动需等待权重下载 kubectl -n aibrix-system-llm get pods -w # 3. 确认探针就绪 kubectl -n aibrix-system-llm describe pod pod-name | grep -A5 Probe\|Readiness # 4. 验证推理服务 kubectl -n aibrix-system-llm port-forward svc/deepseek-r1-distill-llama-8b 8000:8000 curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: deepseek-r1-distill-llama-8b, messages: [{role: user, content: Hello}] }首次请求若长时间无响应优先检查startupProbe是否仍在等待窗口内以及kubectl logs中权重下载进度。模型权重下载完成后删除 Pod 再重建即可验证 PVC 缓存生效重建后的 Pod 将直接从持久卷加载权重启动时间大幅缩短且不会产生新的外网下载流量。七、使用注意事项来自原文档原文档在Usage Notes中给出了四条必须遵守的约束这里结合源码与配置逐一说明Model name labels must match across Deployment/Servicemodel.aibrix.ai/name必须在 Deployment 的 metadata、selector、Pod template 以及 Service 的 selector 中完全一致。这是 AIBrix 网关发现模型并正确路由的前提参见 pkg/constants/model.go 的标签定义PVC storage class should match cluster configurationstorageClassName: default是占位约定实际部署必须改为集群真实存在的 StorageClass否则 PVC 无法绑定Pod 将长期停留在 PendingAdjustmax-model-lenaccording to actual model requirements--max-model-len 12288是按 8B 模型与单卡显存估算的值更换模型或 GPU 时必须重新评估设置过大可能 OOM过小会截断长上下文请求Probe delays accommodate model loading time (30s initial delay)所有探针均设置了 30s 的initialDelaySeconds配合 startupProbe 的 150s 窗口覆盖模型权重下载与加载的慢启动过程切勿在模型加载阶段触发误杀重启。八、小结本文档示例虽然只是一个单 Deployment PVC的迷你清单却浓缩了 AIBrix 生产化部署的四大要素持久化模型缓存PVC解决重复下载问题、显式资源配额保障调度与稳定性、三阶段探针驯服慢启动、标准标签与 Prometheus 注解打通路由与观测。其中model.aibrix.ai/name/model.aibrix.ai/port标签是 AIBrix 网关路由的契约见 pkg/constants/model.go 与 pkg/utils/util.goPVC 挂载路径则与 HuggingFace 缓存目录语义对齐。以此为起点你可以进一步探索仓库中的进阶资源通过 samples/deepseek-r1 系列样例学习 671B 大模型的 RayClusterFleet 多机部署、AI Runtime 对象存储下载模式通过 config/samples 中的podautoscaler、kvcache样例为你的模型叠加弹性伸缩与 KV cache 能力将能跑起来升级为跑得稳、省得下、可观测。【免费下载链接】aibrixCost-efficient and pluggable Infrastructure components for GenAI inference项目地址: https://gitcode.com/GitHub_Trending/ai/aibrix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考