Unified Cache 一键部署实战：用 unified-cache-chart 在 Kubernetes 上部署 vLLM 单机、多机与 PD 服务

大模型人工智能缓存【免费下载链接】unified-cache-managementUnified Cache Manager推理记忆数据管理器是一款以KV Cache为中心的推理加速套件其融合了多类型缓存加速算法工具分级管理并持久化推理过程中产生的KV Cache记忆数据扩大推理上下文窗口以实现高吞吐、低时延的推理体验降低每Token推理成本。项目地址https://gitcode.com/ModelEngine/unified-cache-management点击查看免费下载本篇技术指南围绕 Unified Cache ManagerUCM开源仓库中的 Helm Chart「unified-cache-chart」展开讲解如何从一个单机 profile 出发在 CUDA 或 Ascend 集群中准备镜像与存储并一步步完成单机、多机entry worker与 Prefill/DecodePD分离服务的部署、验证与卸载。读完本文你将掌握 Chart 的values.yaml配置层级、roles[]拓扑表达、六种存储来源的取舍、Chart 接管的 vLLM 参数边界以及 Mooncake UCM 组合下 KV 传输身份engine_id/kv_port的生成原理能够独立搭建可复现的推理部署。一、Chart 定位一个 Helm release 部署一个 vLLM 模型unified-cache-chart是 UCM 的 Kubernetes 一键部署包。它与传统「Deployment StatefulSet」形态不同是一个kthena-onlyChart只渲染 Kthena 控制面的ModelServing需要路由时额外渲染ModelServer与ModelRoute推理引擎形态完全由servingEngineSpec.modelSpec.roles[]的形状决定。从 Chart.yaml 可以看到apiVersion: v2type: applicationkubeVersion: 1.19.0能力定位基于 Kthena CRD 支持单机/双机/PD 分离的 vLLM 推理部署。集群级 Kthena controller、Kthena router、CRD、加速器驱动与 device plugin以及可选的 Volcano、Prometheus Operator都需要使用者预先安装Chart 不负责这些基础设施的生命周期。Chart 的核心设计原则是「根values.yaml平台中立、环境私有值全部下沉到 overlay」根配置不绑定任何私有镜像、节点、网络地址或存储后端CUDA 与 Ascend 共用同一套公共接口平台差异资源键、运行时环境变量、Mooncake 协议由models/cuda/与models/ascend/下的 profile 显式声明。详见 README.md。二、Helm 打包与安装前检查2.1 Helm 打包从源码目录直接安装时可以跳过打包。需要分发 Chart 时执行helm lint . \ --set images.imageexample.com/your-vllm-ucm:tag \ -f models/cuda/values-qwen3-0p6b-1e1.yaml helm package . --destination ./dist需要强调helm lint和helm package只检查 Chart 的静态结构。实际的 GPU/NPU、CANN/HCCL、CSI、RDMA 和服务可用性必须到目标集群验证Helm 渲染通过不等于数据面已经连通。2.2 基础组件要求目标集群至少需要Kubernetes 与 Helm 3Kthena controller、router 与ModelServing/ModelServer/ModelRouteCRDCUDA 节点上的 NVIDIA 驱动与 device plugin或 Ascend 节点上的兼容驱动与 device pluginAscend 镜像还需提供与节点驱动匹配的 CANN toolkit、HCCL 和 vLLM Ascend多机或 PD 场景所需的网络与 RDMA 设备使用schedulerName: volcano时已经安装 Volcano开启 ServiceMonitor 时已经安装 Prometheus Operator。安装前可用以下命令核对 CRD 与节点kubectl get crd modelservings.serving.volcano.sh kubectl get crd modelservers.serving.volcano.sh kubectl get crd modelroutes.serving.volcano.sh kubectl get nodes -o wide如果集群没有 Volcano可在 overlay 中覆盖schedulerName为空字符串回落 default-schedulerservingEngineSpec: schedulerName: 如果集群没有ServiceMonitorCRD应关闭对应资源。注意根 values.yaml 中servingEngineSpec.serviceMonitor.enabled默认是true因此无 Prometheus Operator 的集群必须显式关闭servingEngineSpec: serviceMonitor: enabled: false三、安装环境准备镜像、存储与模型3.1 镜像准备源码values.yaml的images.image默认为空。发布包会填写本次最新稳定 vLLM 的默认 CUDA 镜像并在该字段旁以注释列出全部运行时镜像及架构优先 Docker Hub未启用该渠道时使用 GHCR没有稳定 CUDA 候选时默认留空。Ascend、源码安装或选择其他镜像时通过以下任一方式指定完整地址images: image: example.com/your-vllm-ucm:tag或只覆盖当前模型servingEngineSpec: modelSpec: image: example.com/your-vllm-ucm:tag镜像应与所选平台匹配并包含当前 profile 所需的 vLLM、UCM connector 与传输依赖。CUDA 镜像依赖匹配的 CUDA/NCCLAscend 镜像提供 CANN toolkit/HCCL并与节点驱动兼容。PD 使用自建 Mooncake master 时images.mooncakeMasterImage为空会复用images.image也可以显式提供单独镜像。从模板源码看镜像解析在 modelserving.yaml 的chart.getVllmImage中完成images.image与modelSpec.image二者必填其一required校验且支持通过images.registry配置全局仓库前缀——镜像地址已含域名时不会重复拼接前缀。modelSpec.imagePullPolicy未设置时回退到images.pullPolicy再回退到IfNotPresent。3.2 存储准备Chart 不绑定任何 CSI 实现。unifiedcacheStorage与extraStorage共用同一套 schema每个列表项必须包含唯一name和mountPath并在下列六种 source 中只能选择一种Source用途必填字段dynamicPVC通过任意 StorageClass 动态创建 PVCpvcStoragestaticPVC由 Chart 创建静态 PV 与 PVCpvcStorage、csi.driver、csi.volumeHandlepersistentVolumeClaim复用当前 namespace 已存在的 PVCclaimNamehostPath挂载节点路径—csi使用 inline CSI volumedrivernfs使用原生 NFS volumeserver、path先确认集群中的可用对象kubectl get storageclass kubectl get csidriver kubectl get pvc -n inference这些校验不是文档层面的约定而是模板中的硬性fail逻辑。在 _helpers.tpl 的chart.validateStorageItem中每项存储都会检查name/mountPath必填、source 恰好一种、dynamicPVC.pvcStorage必填、staticPVC必须带csi.driver与csi.volumeHandle、csi必须带driver、nfs必须带server与pathchart.validateStorageConfig还会对unifiedcacheStorage与extraStorage两个列表做 name 去重。因此「多 source 渲染失败」「inline CSI 缺 driver 渲染失败」「静态 CSI 缺 volumeHandle 渲染失败」都会在helm template阶段直接报错而不是等到 Pod 起不来。模型权重通常放在storage.extraStorageUCM Posix 缓存放在storage.unifiedcacheStorage。复用已有模型 PVCservingEngineSpec: modelSpec: modelPath: /mnt/model/Qwen3-0.6B storage: extraStorage: - name: models mountPath: /mnt/model persistentVolumeClaim: claimName: existing-model-pvc通过 StorageClass 动态创建缓存 PVCservingEngineSpec: modelSpec: storage: unifiedcacheStorage: - name: ucm-cache mountPath: /mnt/ucm dynamicPVC: storageClass: replace-with-your-rwx-storage-class pvcStorage: 1Ti pvcAccessMode: [ReadWriteMany]replace-with-your-rwx-storage-class是公开示例占位符部署前必须替换成目标集群中实际存在、并支持所需访问模式的 StorageClass。dynamicPVC与staticPVC对应的 PV/PVC 由 pv.yaml 与 pvc.yaml 渲染静态 PV 默认回收策略为Retain动态 PVC 的访问模式未填写时回退ReadWriteOnce。3.3 模型准备modelSpec.modelPath可以是镜像内路径、挂载卷中的目录或镜像能够访问的模型仓库 ID。CUDA 与 Ascend 的自带 profile 都使用/mnt/model/...因此安装前需要用 overlay 将模型存储挂载到/mnt/model或者修改modelPath。根values.yaml不默认挂载 NFS、节点目录或其他模型存储这一点在 values.yaml 的storage.extraStorage默认值空列表中体现得很清楚——模型盘必须由使用者显式提供。四、Helm 参数与配置说明4.1 模型模板配置ProfileCUDA 与 Ascend 各提供七个 profile作为可修改的起点。它们不包含集群私有的镜像和存储。CUDAmodels/cuda/文件拓扑主要用途values-qwen3-0p6b-1e1.yaml单机1 role / 0 worker最小部署与连通性检查values-qwen3-0p6b-1e2.yaml双机1 role / 1 workerentry worker 多机服务values-qwen3-0p6b-1p1-1d1.yamlPD 1P1DMooncake UCM 基础 PDvalues-qwen3-0p6b-2p1-2d1.yamlPD 2P2D单机实例P/D 横向扩展values-qwen3-0p6b-2p2-2d2.yamlPD 2P2D多机实例P/D 每个实例均由 entry worker 组成values-deepseek-r1-awq-single.yaml单机 TPDeepSeek-R1-AWQ 单节点示例values-deepseek-r1-awq-multi.yaml双机 DP × TPDeepSeek-R1-AWQ 多节点示例Ascendmodels/ascend/文件拓扑主要用途models/ascend/values-qwen3-0p6b-1e1.yaml单机1 role / 0 worker最小 Ascend 部署与连通性检查models/ascend/values-qwen3-0p6b-1e2.yaml双机1 role / 1 workerentry worker 多机服务models/ascend/values-qwen3-0p6b-1p1-1d1.yamlPD 1P1DAscend Mooncake UCM 基础 PDmodels/ascend/values-qwen3-0p6b-2p1-2d1.yamlPD 2P2D单机实例P/D 横向扩展models/ascend/values-qwen3-0p6b-2p2-2d2.yamlPD 2P2D多机实例P/D 每个实例均由 entry worker 组成models/ascend/values-deepseek-v3p1-multi.yaml双机 DP × TPDeepSeek-V3.1 多节点示例models/ascend/values-qwen3-235b-multi.yaml双机 DP × TPQwen3-235B 多节点示例推荐的实践是先选择models/cuda/或models/ascend/的某个 profile再维护一个本地 overlay只放环境相关值images: image: example.com/your-vllm-ucm:tag servingEngineSpec: serviceMonitor: enabled: false modelSpec: storage: extraStorage: - name: models mountPath: /mnt/model persistentVolumeClaim: claimName: existing-model-pvc部署时按「根 values → 模型 profile → 环境 overlay」的顺序叠加后一个 values 文件覆盖前一个helm install qwen . -n inference --create-namespace \ -f values.yaml \ -f models/cuda/values-qwen3-0p6b-1e1.yaml \ -f local-overlay.yaml配置归属边界在 DEVELOPER_GUIDE.md 中有清晰约定servingEngineSpec.configs管所有 role 共享的镜像环境变量modelSpec.env管当前模型所有 roleroles[].env管单个 role如 prefill/decode 差异nodeTopologyConfig按指定节点注入网卡与地址变量roles[].vllmArgs管单个 role 的 vLLM CLI flags集群私有内容一律放local-overlay.yaml。4.2modelSpec关键字段字段作用nameKthena/Kubernetes 资源名片段modelPathvllm serve加载的模型路径或仓库 IDmodelNameOpenAI-compatible API 暴露的模型名roles[]描述 entry/worker、prefill/decode 和资源roles[].vllmArgs当前 role 的 vLLM flags每行一项replicasServingGroup 数量dataParallelModestandard或 PD 多机实例使用的hybridpdPD role 配对、传输 connector、路由和身份参数unifiedcacheConfig可选 UCM Posix 配置storageUCM 缓存和模型等公共挂载serviceAccountName引用集群中已经存在的 ServiceAccount命名约束值得提前注意modelSpec.name、roles[].name、存储name只能使用小写字母、数字与-且首尾必须是字母或数字生成的资源名release-modelSpec.name不得超过 63 字符因为会作为 label 值用于 Service selector 与 podAntiAffinityroles[].name最长 12。模板在 modelserving.yaml 中对超长资源名有显式fail保护。Chart不创建 ServiceAccount 或权限绑定。未填写serviceAccountName时Pod 使用 namespace 的默认身份填写后只把名称透传给 PodSpec见 modelserving.yaml 的serviceAccountName渲染分支。4.3 部署形态由roles[]决定一个 role 表示一个逻辑引擎角色。workerReplicas: 0时只有 entry大于零时每个实例由 entry 与 worker 共同组成。modelSpec.replicas控制 ServingGroup 数量roles[].replicas控制 role 实例数。单机roles: - name: engine replicas: 1 workerReplicas: 0双机roles: - name: engine replicas: 1 workerReplicas: 1PDpd: prefill: prefill decode: decode kvTransfer: connector: MooncakeConnectorV1 routerType: mooncake identity: engineIdBase: 0 kvPortBase: 20001 instanceStride: 100 roles: - name: prefill replicas: 1 workerReplicas: 0 - name: decode replicas: 1 workerReplicas: 0roles[].resources原样传给 KubernetesrawResourceRequirements模板不做芯片推断。CUDA profile 申请nvidia.com/gpuAscend profile 使用公开 device plugin 资源键huawei.com/Ascend910RDMA 与 hugepages 同样使用集群实际暴露的资源键。Chart 不负责安装设备插件也不把一种资源键转换成另一种。默认网络形态方面Chart 默认hostNetwork: true适合 RDMA/InfiniBand 多机推理hostIPC: truednsPolicy: ClusterFirstWithHostNet。hostNetwork开启后每个 vLLM 容器声明hostPortcontainerPort(8000)调度器据此保证每节点至多 1 个 vLLM所以 N 个副本需要 ≥N 个节点单模型可用modelSpec.hostNetwork: false关闭。这些默认值都写在根 values.yaml 的servingEngineSpec中。探针方面kthena 形态下仅 entryleader渲染探针worker 是--headless模式、本地无 HTTP 服务因此 workerTemplate 不渲染探针避免「worker 探 leader」的跨 Pod liveness 反模式。默认探针参数servingEngineSpec.probesstartup 初始延迟 300s、周期 20s、失败阈值 180上限约 65 分钟给模型加载留足时间liveness 初始延迟 60s、周期 60s、失败阈值 5readiness 初始延迟 60s、周期 20s、失败阈值 3。探针通过 exec 检查http://127.0.0.1:${POD_PORT}/health可在modelSpec.probes下按模型覆盖。4.4 Chart 接管的 vLLM 参数roles[].vllmArgs只填写 flags每行一项支持空行、#注释、单引号与双引号。以下内容不要填写模型位置与--served-model-name--host、--port和数据并行地址/排名参数--kv-transfer-configMooncake master 的托管环境变量。Chart 为每个 role 生成参数 ConfigMap容器入口再结合 Kthena 注入的 entry/worker 身份形成最终vllm serve命令。托管参数在渲染期和运行期有双重校验渲染期_helpers.tpl的chart.validateVllmArgs扫描vllmArgs文本命中--host、--port、--headless、--data-parallel-address/-dpa、--data-parallel-rpc-port/-dpp、--data-parallel-start-rank/-dpr、--data-parallel-hybrid-lb、--data-parallel-external-lb、--data-parallel-rank、--kv-transfer-config、--served-model-name、--config即fail同时要求并行布局参数使用全名如--tensor-parallel-size不能缩写为--tensor-parallel也不能写点分形式--tensor.parallel.size。运行期入口脚本args-entrypoint.shconfigmap-vllm-args.yaml在拼装 argv 前再次逐 token 校验防止 vLLM 的 argparse 缩写别名绕过渲染期检查。--config始终被禁止避免外部配置绕过托管参数校验存在 Chart KV 配置时--kv-offloading-size与--kv-offloading-backend同样禁止——因为 vLLM 0.18 会在开启原生 KV offloading 时重写已有的kv_transfer_config静默替换 Chart 生成的 connector。详细约束见 Developer Guide。以单机 CUDA profile values-qwen3-0p6b-1e1.yaml 为例vllmArgs只写模型与性能参数vllmArgs: | --tensor-parallel-size 1 --data-parallel-size 1 --pipeline-parallel-size 1 --max-model-len 20000 --block-size 128 --gpu-memory-utilization 0.85 --distributed-executor-backend mp --compilation-config {cudagraph_mode:FULL_AND_PIECEWISE} --no-enable-prefix-caching --trust-remote-code4.5 多机网络autoDetectInterface: true默认时启动脚本根据HOST_IP选择宿主机网卡并在内部为 Gloo、NCCL、HCCL 与 vLLM 设置相应网络变量GLOO_SOCKET_IFNAME、TP_SOCKET_IFNAME、NCCL_SOCKET_IFNAME、HCCL_SOCKET_IFNAME、HCCL_IF_NAME、VLLM_NETWORK_INTERFACE、VLLM_USE_NETIF并从网卡 IPv4 派生HCCL_IF_IP置VLLM_DETECT_MULTI_IP0。显式覆盖的优先级是nodeTopologyConfigforceInterface 自动探测 镜像默认行为。自动探测的实现细节在 node-topology-setup.sh 中采用三级降级策略信号① 优先用ip route get $MASTER_IP找「到 master 的出口网卡」多机最准信号② 按HOST_IP精确归属网卡rank0/单机信号③ 退回默认路由网卡最不可靠。探测结果还会过滤lo/docker*/cni*/flannel*/cali*/veth*/tunl*/kube*/virbr*等虚拟网卡。需要注意非hostNetwork下 Pod 内看不到宿主机网卡脚本会跳过探测并告警VLLM_HOST_IP不会自动派生需要固定 Mooncake/vLLM 注册地址时必须在nodeTopologyConfig中按节点显式设置。当管理网和数据网分离或自动探测选择错误时按 Kubernetes 节点名显式覆盖nodeTopologyConfig: accelerator-node-1: GLOO_SOCKET_IFNAME: ib0 NCCL_SOCKET_IFNAME: ib0 HCCL_SOCKET_IFNAME: ib0 VLLM_NETWORK_INTERFACE: ib0 VLLM_USE_NETIF: ib0 accelerator-node-2: GLOO_SOCKET_IFNAME: ib0 NCCL_SOCKET_IFNAME: ib0 HCCL_SOCKET_IFNAME: ib0 VLLM_NETWORK_INTERFACE: ib0 VLLM_USE_NETIF: ib0按实际平台只设置有意义的 NCCL 或 HCCL 变量CUDA 场景设 NCCLAscend 场景设 HCCL。nodeTopologyConfig中的显式值不会被自动探测覆盖。此外非空的nodeTopologyConfig还会让模板自动为引擎 Pod 追加硬性 nodeAffinity只调度到这些节点、多副本时追加 podAntiAffinity 分散节点对应的节点级环境变量会渲染成release-node-topologyConfigMap按节点名一个 key 一个文件见 configmap-node-topology.yaml入口脚本按$NODE_NAME读取。多机与 Mooncake 通常需要hostNetwork: true并要求所选端口和网卡在节点间可达。五、Helm 服务部署实战5.1 单机 CUDAhelm install qwen-single . \ --namespace inference \ --create-namespace \ --set images.imageexample.com/your-vllm-ucm:tag \ -f models/cuda/values-qwen3-0p6b-1e1.yaml \ -f local-overlay.yaml5.2 多机 CUDAhelm install qwen-multi . \ --namespace inference \ --create-namespace \ --set images.imageexample.com/your-vllm-ucm:tag \ -f models/cuda/values-qwen3-0p6b-1e2.yaml \ -f local-overlay.yaml多机安装前确认workerReplicas对应的节点、GPU、共享模型目录和网络均已准备Helm 不会替集群创建这些基础设施。多机 DP 模式下入口脚本还会按NODE_RANK × 本节点 dp_size_local注入--data-parallel-start-rank防止各节点都默认 start-rank0 导致 worker 与 head 的 rank0 撞号启动握手报HELLO message from remote engine 0, expected it to be local。5.3 单机 Ascendhelm install qwen-ascend . \ --namespace inference \ --create-namespace \ --set images.imageexample.com/your-vllm-ascend-ucm:tag \ -f models/ascend/values-qwen3-0p6b-1e1.yaml \ -f local-overlay.yaml安装前确认节点 allocatable 中存在huawei.com/Ascend910镜像中的 CANN 与节点驱动匹配并且 HCCL 使用的网卡和设备通信路径可用。Ascend profile如 values-qwen3-0p6b-1e1.yaml会在modelSpec.env中声明HCCL_OP_EXPANSION_MODEAIV、HCCL_BUFFSIZE200、PYTORCH_NPU_ALLOC_CONFexpandable_segments:True、VLLM_ASCEND_ENABLE_MLAPO1、HCCL_INTRA_PCIE_ENABLE1等 Ascend 运行时默认值并在入口脚本configmap-entrypoint-common.yaml中自动 source/usr/local/Ascend/ascend-toolkit/set_env.sh保证同一入口同时兼容 CUDA 与 Ascend 运行时镜像。5.4 PD 分离helm install qwen-pd . \ --namespace inference \ --create-namespace \ --set images.imageexample.com/your-vllm-ucm:tag \ -f models/cuda/values-qwen3-0p6b-1p1-1d1.yaml \ -f local-overlay.yamlMooncake profilevalues-qwen3-0p6b-1p1-1d1.yaml会为 prefill/decode 生成独立传输身份并通过 Kthena router 暴露统一入口。启用 UCM 时producer 侧自动叠加UCMConnector生成MultiConnector内部组合传输 connector 与 UCMConnectordecode 侧仍使用纯 Mooncake connector。NIXL connector 不允许同时启用 UCM这一约束在_helpers.tpl的chart.validateKvTransfer中以fail强制保证。CUDA Mooncake profile 的客户端协议是rdmaAscend Mooncake profilevalues-qwen3-0p6b-1p1-1d1.yaml使用ascend并将kvPortBase设为 36000CUDA 为 20001。部署 Ascend PD 时将 profile 路径切换到models/ascend/values-qwen3-0p6b-1p1-1d1.yaml并使用包含 Ascend Mooncake、CANN/HCCL 与 UCM 依赖的镜像。Mooncake master 不申请 NPU但其 Ascend 通信路径仍必须在目标集群验证——protocol: ascend时模板会把宿主机/etc/hccn.conf、/usr/local/Ascend/driver、/usr/local/dcmi只读挂载进 master 容器见 mooncake-master.yaml引擎入口还会校验hccn_tool可执行与/etc/hccn.conf可读。PD 场景下 Chart 还会自动生成 KV 传输配置渲染期configmap-vllm-args.yaml为每个 role 生成kv-transfer.template.json带__UC_ENGINE_ID__/__UC_KV_PORT__哨兵与kv-transfer.meta.json含groupNamePrefix、roleName、prefillReplicas、decodeReplicas、portSpan、identity等元数据运行期Pod 启动前由 resolve-kv-transfer-config.py 结合 Downward API 注入的UC_PD_GROUP_NAME/UC_PD_ROLE_ID把哨兵解析为真实engine_id与kv_port再以--kv-transfer-config传给 vLLM。以 1P1D 为例最终身份形如P0 engine 0 / port 20001D0 engine 1 / port 20101Ascend 为 36000/36100。engine_id从engineIdBase起按「serving group 序号 × 每 group 的 PD 副本数 role 内偏移」计算kv_port从kvPortBase起按instanceStride分配且instanceStride必须覆盖 DP × TP × PP × CP 的保守端口跨度模板会按kvTransferPortSpan自动计算下限并校验端口范围不超过 65535。WORKER_INDEX被刻意忽略同一 role 副本的 entry 与所有 worker 必须解析到同一个 engine ID 与端口基址。NIXL 不使用端口字段只保留 engine 身份。UCM 配置会写入release-ucm-configConfigMap见 configmap-ucm.yamlunifiedcacheConfig.config按 UCM 原生结构透传Chart 只把unifiedcacheStorage[].mountPath按顺序拼接为每个 connector 的storage_backends其余字段保持用户输入。入口脚本把只读模板复制成可写的/vllm-workspace/UnifiedCache/config/ucm_config.runtime.yamlUCM_CONFIG_FILE指向该运行时文件启动过程中不会再根据集群存储对象修改配置。UCMConnector 的运行时实现位于 ucm/integration/vllm/ucm_connector.pyclass UCMConnector其kv_connector_module_path固定为ucm.integration.vllm.ucm_connectorkv_role为kv_bothUCM-only或组合进MultiConnector的 producer 场景。六、部署验证6.1 渲染与对象状态安装前先做静态校验与渲染检查helm lint . --set images.imageexample.com/your-vllm-ucm:tag \ -f models/cuda/values-qwen3-0p6b-1e1.yaml -f local-overlay.yaml helm template qwen . -n inference \ --set images.imageexample.com/your-vllm-ucm:tag \ -f models/cuda/values-qwen3-0p6b-1e1.yaml -f local-overlay.yaml建议把渲染结果输出到临时文件检查最终 argv、资源、卷、路由与 ConfigMap。安装后检查对象状态kubectl get modelserving,modelserver,modelroute -n inference kubectl get pods,svc,pvc -n inference kubectl describe modelserving -n inference name引擎 Service 由 service-engine.yaml 渲染selector 使用modelserving.volcano.sh/name与modelserving.volcano.sh/entry: true标签同时作为 Prometheus 抓取目标ServiceMonitor 按uc-stack.io/service-role: engine-service选择。6.2 模型 APIkubectl port-forward -n inference svc/service-name 8000:80 curl http://127.0.0.1:8000/v1/models curl http://127.0.0.1:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: Qwen3-0.6B, messages: [{role: user, content: Hello}] }请求中的model字段对应modelSpec.modelName为空时回退到modelPath该值同时是vllm --served-model-name、ModelRoute.modelName与ModelServer.model的统一来源。6.3 UCM 与 PD启用 UCM 时检查 ConfigMap、挂载和运行时文件kubectl get configmap -n inference kubectl exec -n inference pod -c vllm -- \ cat /vllm-workspace/UnifiedCache/config/ucm_config.runtime.yamlPD 还需要核对每个逻辑实例的engine_id和 Mooncakekv_port唯一且节点间可达——成功渲染不代表数据面已经连通。可从 Pod 日志确认--kv-transfer-config的最终解析结果以及 Mooncake master 的注册情况。七、Helm 服务卸载helm uninstall release --namespace inference卸载前确认 PV/PVC 的回收策略。persistentVolumeClaim只是引用已有 PVCChart 不创建也不删除该 PVC动态或静态创建的资源遵循模板和集群回收策略静态 PV 默认Retain卸载后 PV/PVC 会保留需按需手工回收。八、常见问题与建议镜像为空通过images.image或modelSpec.image提供完整镜像引用模板在渲染期对空镜像直接required报错。模型路径不存在为/mnt/model配置extraStorage或修改modelPath。PVC Pending检查 StorageClass、访问模式、容量和 CSI controller/node 插件。inline CSI 渲染失败确认csi为对象且包含driver。静态 CSI 渲染失败除driver外还需要volumeHandle。多 source 渲染失败每个 storage item 只能配置六种来源中的一种。Pod 身份无权限Chart 不创建身份或权限确认serviceAccountName引用的对象已存在并由集群管理员授予所需权限。设备资源不足CUDA 检查nvidia.com/gpuAscend 检查huawei.com/Ascend910、device plugin 与节点 allocatable。多机启动卡住检查 GPU/NPU、共享模型目录、hostNetwork、NCCL/HCCL 网卡和 RDMA 可达性确认 DP 的--data-parallel-start-rank注入正确。Ascend 运行时失败检查节点驱动与镜像 CANN toolkit 是否兼容并核对 HCCL 配置和设备文件/etc/hccn.conf、hccn_tool。PD KV 不通检查 connector/routerType 配对、身份跨度、端口冲突和 Mooncake master 地址核对kvPortBase与instanceStride是否覆盖并行端口跨度。vllmArgs被拒绝确认没有填写 Chart 托管参数--host/--port/--kv-transfer-config/--served-model-name/--config等且并行布局参数使用全名。九、推荐阅读与源码延伸Chart README模型示例与安装总览开发者指南配置层级、参数归属、存储校验、生命周期钩子根 values.yaml全部参数的默认值与注释说明Kthena ModelServing 模板PodSpec、探针、亲和性、UCM 卷渲染入口脚本与 KV 传输模板生成运行时拓扑初始化与网卡自动探测KV 传输身份解析器UCMConnector 运行时实现赞分享大模型人工智能缓存【免费下载链接】unified-cache-managementUnified Cache Manager推理记忆数据管理器是一款以KV Cache为中心的推理加速套件其融合了多类型缓存加速算法工具分级管理并持久化推理过程中产生的KV Cache记忆数据扩大推理上下文窗口以实现高吞吐、低时延的推理体验降低每Token推理成本。项目地址https://gitcode.com/ModelEngine/unified-cache-management点击查看免费下载相关推荐vLLM Helm Chart 深度解析用 chart-helm 在 Kubernetes 上部署 vLLM 推理服务vLLM Helm Chart 深度解析用 chart helm 在 Kubernetes 上部署 vLLM 推理服务 本篇基于仓库中的 Helm Chart人工智能大模型模型推理服务推理引擎本地部署vLLM 多节点部署实战基于 Kthena ModelServing 在 Kubernetes 上运行多机推理服务vLLM 多节点部署实战基于 Kthena ModelServing 在 Kubernetes 上运行多机推理服务 本文以 vLLM 仓库中的集成文档 kth人工智能大模型模型推理服务推理引擎本地部署Pulse 在 Kubernetes 上的部署实战Server、Unified Agent、Talos 与 OpenShift 完整指南Pulse 在 Kubernetes 上的部署实战Server、Unified Agent、Talos 与 OpenShift 完整指南 本指南以 docs/可观测性运维后端上一篇网页媒体资源捕获终极手册猫抓扩展四步上手网页视频下载不再求人下一篇网易云NCM转MP3太麻烦免费工具ncmdump拖一下就能解锁全部歌曲创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考