后端人工智能模型推理服务集群管理可观测性【免费下载链接】gpustackA GPU cluster manager for high-performance AI model serving (vLLM, SGLang) and on-demand SSH-accessible GPU instances.项目地址https://gitcode.com/gh_mirrors/gp/gpustack点击查看免费下载GPUStack 的 Cache Service 是一种共享 KV Cache 服务模型部署将自身的 KV Cache 托管到该服务上而不是各自在推理引擎内独立保存。缓存位于推理引擎之外因此同一 worker 上的多个部署与副本可以复用彼此的公共前缀而 L2 存储后端能把这种复用进一步扩展到服务重启之后与跨节点场景。阅读本文后你将掌握在 GPUStack 中创建缓存服务、将 vLLM / SGLang 部署接入共享缓存、为 Mamba 或 Gated-DeltaNet 这类混合注意力模型正确调优缓存参数以及通过自定义 Provider 文档接管缓存 Provider 目录的完整实战方法。缓存服务是什么架构与适用范围缓存服务Cache Service解决的是多实例、多副本场景下 KV Cache 重复计算的问题。按 cache-service-management.md 的定义一个缓存服务就是一份共享 KV Cache模型部署挂接attach到它上面而不是各自保存 KV Cache缓存保存在推理引擎之外同一 worker 上的部署与副本可以互相复用公共前缀L2 存储后端把复用范围扩展到进程重启之后与跨节点缓存服务仅挂接内置的 vLLM 与 SGLang 后端一个部署只能挂接自己所在集群内的缓存服务。从数据模型看缓存服务的核心结构在 cache_services.py 中定义CacheService含provider_name、provider_version、cluster_id、worker_selector、config、state等字段以及每个 worker 上实际运行的CacheServiceInstance记录component、ports、worker_id、spec_digest等。值得留意的是spec_digest它是对决定容器形态的那部分服务规格provider_versionconfig做的 SHA-256 摘要控制器按实例集合而不是规格去对账规格变更不会触碰正在运行的容器——这正对应了文档中的提示对已有缓存服务的修改只有在其实例被删除并重建后才会生效。创建缓存服务在 GPUStack Web UI 中按以下步骤创建缓存服务进入Cache Service页面点击Add Cache Service按钮并选择一个 Provider输入Name选择Version或选择Custom并填写Container Image自定义版本使用默认版本的启动命令与环境模板因此镜像必须与该命令兼容见 cache-providers.yaml 中 LMCache 的custom_version: true说明填写 Provider 设置例如RAM Size (GiB)——即缓存服务端在内存中保留的缓存容量可选设置Worker Label Selector把服务限定在满足标签条件的 worker 上运行可选添加L2 Storage Backend把缓存溢出到更大的存储层本地目录、Redis / Valkey、或 S3 兼容对象存储。多个后端按优先级排列读优先走第一个写会写入全部可选在Advanced下添加Parameters与Environment Variables。运行多个组件的服务会为每个组件保留独立的参数列表因为每个组件运行的是不同的二进制点击Save。Provider 结构化字段详解内置的 LMCache Provider 在 cache-providers.yaml 中声明了若干结构化字段这些字段会成为表单中的配置项并通过{{字段名}}占位符拼入实际启动命令字段默认值说明ram_sizeRAM Size, GiB20缓存服务端在内存中保留的缓存容量必填最小 1 GiBeviction_policy淘汰策略LRULRU淘汰最近最少使用的分块IsolatedLRU为每个 cache salt 维护独立 LRU 列表并需通过 HTTP API 设置配额noop从不淘汰eviction_trigger_watermark淘汰触发水位0.85触发淘汰的内存使用率0–1eviction_ratio淘汰比例0.1每次触发所淘汰的内存比例0–1chunk_size分块大小留空每个 KV Cache 分块包含的 token 数分块越小复用粒度越细、开销越大留空使用引擎默认值enable_p2pP2P 读取false让每个缓存服务端从对端读取分块而非重新计算把各节点缓存合成一个池会额外启动一个 coordinator 组件用于节点发现这些值最终渲染进 LMCache 服务端的启动命令例如lmcache server --host {{host}} --port {{port}} --l1-size-gb {{ram_size}} --chunk-size {{chunk_size}} --http-host {{host}} --http-port {{metrics_port}} --supported-transfer-mode auto --worker-reap-timeout-seconds 60 --eviction-policy {{eviction_policy}} --eviction-trigger-watermark {{eviction_trigger_watermark}} --eviction-ratio {{eviction_ratio}} --l1-align-bytes 65536 --coordinator-url http://{{component.coordinator.address}} --coordinator-advertise-ip {{worker_ip}} --p2p-advertise-url {{ports.p2p.url}}从 cache_providers.py 可以看到模板支持一系列占位符{{host}}绑定/连接地址、{{port}}组件被寻址的端口、{{metrics_port}}Prometheus 指标端口、{{ports.name}}组件声明的任意端口、{{ram_size}}、{{chunk_size}}等。布尔值渲染为小写true/false某个占位符渲染为空时携带它的整个 flag 会连同一起被丢弃见render_argument的实现。L2 存储后端选型LMCache Provider 声明了三种 L2 后端对应--l2-adapter参数携带的 JSON 配置本地文件系统fs_native把 KV Cache 溢出到 worker 上的本地目录如 NVMe。字段包括base_path默认/var/lib/gpustack/cache/lmcache/l2容器化 worker 上该目录会落在宿主机磁盘容器重建后缓存仍在、max_capacity_gb0 或留空表示不限制、num_workersI/O 线程数即连接器实际的 I/O 队列深度本地磁盘留空即可GPFS/Lustre 等并行文件系统可调高、use_odirect绕过页缓存直接读写磁盘仅在分块字节数是文件系统块大小整数倍时生效否则静默回退为带缓存的 I/O。Redis / Valkeyresp以 Redis 或 Valkey 服务端作为共享 L2缓存服务端重启后缓存仍保留。字段包括host、port、username、password、max_capacity_gb用户名与密码通过LMCACHE_RESP_USERNAME/LMCACHE_RESP_PASSWORD环境变量传递避免把凭据留在命令行上。S3s3以 S3 兼容对象存储AWS S3、MinIO、Ceph RGW作为共享 L2。注意地址采用virtual-hosted 风格——bucket 名是主机名的一部分如kvcache.s3.example.com不支持 path-style 寻址。字段包括s3_endpoint、s3_region、aws_access_key_id、aws_secret_access_key分别通过AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY环境变量传递、disable_tls、max_capacity_gb。CacheServiceConfig.l2_storages是有序列表见 cache_services.py第一个条目是优先的读层所有条目都会接收写入形成级联cascade。将部署挂接到缓存服务创建好缓存服务后把模型部署挂接上去使用内置 vLLM 或 SGLang 后端创建或编辑一个模型部署勾选Enable Extended KV Cache将Cache Backend设置为该缓存服务。只有同一集群内、且与所选后端兼容的缓存服务才会出现在列表中点击Save。每个实例会报告它挂接的缓存服务以及近期的命中率hit rate。如果实例因故在没有缓存的情况下启动——例如其 worker 上没有可用的缓存实例——它会报告共享 KV Cache 未激活而不是失败。部署侧的配置在 models.py 的ExtendedKVCacheConfig中定义class ExtendedKVCacheConfig(BaseModel): enabled: bool False mode: Optional[KVCacheModeEnum] KVCacheModeEnum.LOCAL # local | shared cache_service_id: Optional[int] None # mode 为 shared 时必填 ram_ratio: Optional[float] 1.2 ram_size: Optional[int] None chunk_size: Optional[int] Nonemode为local时是逐实例把 KV Cache 卸载到 CPU 内存的进程内模式mode为shared时才挂接共享缓存服务。值得注意的是chunk_size属于进程内模式在 cache_services.py 的resolve_instance_cache_config中有明确注释——两种模式互斥部署侧的chunk_size绝不能泄漏进共享模式否则会让引擎与它所挂接的服务端使用不同的分块粒度。后端兼容性与注入机制从 cache-providers.yaml 的inference_backend_integrations一节可以看到两端的接入契约vLLM0.25.0框架cuda注入kv_transfer_config连接器LMCacheMPConnector、kv_role: kv_both、lmcache.mp.host/port/mp_transfer_mode并追加--shutdown-timeout 20。该 flag 的存在是为了解决 vLLM 默认--shutdown-timeout 0的问题SIGTERM 时引擎未关闭 CUDA IPC 句柄驱动会把 KV 显存一直记在缓存服务端账上直到服务端回收死 worker20 秒的优雅窗口落在容器停止宽限期 30 秒内能让显存随实例一起释放。SGLang0.5.13框架cuda通过--enable-lmcache与一个 YAML 配置文件挂接连接器从服务端自行读取分块大小同样通过 CUDA IPC 共享 KV。两端的注入都带PYTHONHASHSEED: 0LMCache 的 token 哈希在无法加载 vLLM 哈希函数时会回退到 Python 内置哈希若不固定种子每个引擎进程的哈希结果不同跨实例共享会静默地永远不命中。引擎只能挂接本节点的缓存服务端attach_locality: node_local因为零拷贝路径是 CUDA IPC这也解释了为什么 LMCache 的拓扑是per_node——每个 worker 上都会运行一个缓存服务端实例部署与副本跟随集群 worker 分布。用 LMCache 运行混合注意力模型混合注意力模型hybrid model把循环层——Mamba 或 Gated-DeltaNetGDN线性注意力——与全注意力层交错排列。Qwen3.5 与 Qwen3.6 系列、Qwen3-Next、Kimi-Linear 和 Kimi K3 都属于这一类。循环层持有的不是每 token 一对的 key/value而是固定大小的状态且该状态只能在 block 结束处做快照。因此引擎会以远超通常几个 token的巨大 block 工作block 大小由模型自身决定LMCache 只有在按这些 block 边界为单位存储缓存时才能服务这类模型。两边都不会自行协调不处理的话引擎要么拒绝启动要么挂接后永远记不到命中。第 1 步找到引擎选择的 block 大小vLLM 会不断抬高注意力 block 大小直到注意力 page 至少与循环状态 page 一样大并在部署启动时打印日志Setting attention block size to 544 tokens to ensure that attention page size is mamba page size.这个数字就是N。它由模型、数据类型和并行度共同决定所以要读部署自己的日志而不是假定一个值。下面这些值取自模型自身精度下的单卡运行——仅作为对你看到结果的 sanity check不是查找表模型NQwen/Qwen3.5-0.8B544Qwen/Qwen3.6-27B784moonshotai/Kimi-Linear-48B-A3B-Instruct944moonshotai/Kimi-K3768第 2 步配置缓存服务将Chunk Size设为N或其整数倍。缓存服务端的分块大小必须是引擎 block 大小的整数倍否则缓存注册会失败。在缓存服务端的Parameters中添加--separate-object-groups让每个注意力窗口存成独立的对象组。该开关默认关闭见 cache-providers.yaml 中common_parameters对该 flag 的注释。需要注意分块大小属于缓存服务不属于部署。针对某个N调优的服务仍能服务 block 大小整除它的普通模型但两个N不同的混合注意力模型各自需要一个缓存服务。第 3 步把模型部署到该服务按上文将部署挂接到缓存服务的步骤选择第 2 步创建的缓存服务作为Cache Backend即可。运行中的实例会报告它挂接的服务及其看到的命中率。自定义 Cache Provider可供选择的 Provider 包括本版本内置的以及已安装扩展所贡献的。平台管理员可以用一份自有文档替换整套 Provider——用于固定不同的镜像、新增版本或声明 GPUStack 未随附的 Provider。进入Cache Service页面点击Manage Providers按钮在Provider Source抽屉中选择三种来源之一Yaml File把内容粘贴到编辑器中或点击Import把文件载入编辑器URL填写Source URL。服务端在保存时抓取一次点击Update Now再抓取一次。它必须是http(s)、不能携带凭据、必须直接指向文件本身而不是仓库页面且必须是 UTF-8 编码、不大于 4 MBEmbedded回到本版本随附的 Provider点击Save。从内置文件出发而不是从空编辑器开始警告请从内置文件开始编辑不要从空编辑器开始。自有文档会整体替换现有 Provider 集合——文档未声明的每个 Provider 都会下线包括已安装扩展贡献的 Provider。点击编辑器头部header的Built-in File可下载当前安装实际服务的文档然后在此基础上修改。从实现上看这份内置基线正是 cache_provider_catalog.py 中的builtin_catalog_text()把内置资产gpustack/assets/cache-providers.yaml与每个已安装插件的cache_provider_assets()合并后序列化而成。目录的实际服务形态来自物化表CacheProviderEntry由 leader 从管理员配置的 source 行生成读取方统一查表因此所有服务器看到的是最后一次写入的结果。保存时的校验规则保存时整份文档会被校验任何一项无法服务的声明都会导致整份文档被拒绝包括本版本无法读取的声明会字面渲染出来的占位符placeholder不存在的字段名。最后一条比看起来更重要未知 key 会被静默忽略所以一个把run_command拼写成run_cmd的组件会带着根本没有命令启动。校验层正是为此设计了严格的未知 key 检测——cache_provider_source.py 中的_unknown_keys会遍历嵌套声明报告每个不存在的字段路径load_cache_providers_document在strictTrue模式下配置 API 采用会把任何无法读取的声明连同原因一起抛给管理员。保存还会在以下情况下被拒绝新文档要移除某个仍有缓存服务在运行的 Provider或其版本。报错信息会点名每一个受影响的缓存服务——请先删除这些服务或把它们迁移到新文档仍携带的 Provider/版本上。生效时机与更新机制正在运行的实例保留其启动时的声明。新声明只有在实例被重建后才生效这与 GPUStack 升级时 Provider 变更的生效方式相同。没有任何机制会按计划自动更新 ProviderURL 来源只在保存时和点击Update Now时读取。配置了自有文档期间GPUStack 升级或新装扩展新增的 Provider 不会自动出现——再次下载内置文件就能看到它们新增了什么。从源码看缓存服务的生命周期了解以下几点能帮助你更精准地排障与规划运维状态机CacheServiceStateEnumcache_services.py定义了pending → starting → running/error以及由健康探针驱动的unreachable状态流转。托管服务自身的状态是服务端控制器对其实例状态聚合的结果外部服务未托管实例则由健康检查器在running与unreachable之间翻转。实例对账per-node 组件在每个匹配的 worker 上放置一个实例(cache_service_id, component, worker_id)上的唯一约束保证两次对账不会重复创建同一行replicas拓扑则把配置的副本数调度放置到匹配 worker 上。处于NOT_READY状态的 worker 上的实例行会被保留worker 恢复后会自动重启容器。降级而非失败resolve_instance_cache_config返回的CacheConfigSnapshot带injectedFalse时实例会以未携带共享缓存的降级状态启动reason字段说明原因如未指定缓存服务、服务不存在、或 node-local 不兼容等。这就是文档所述报告缓存未激活而不是失败的实现机制。端口与重启实例的ports映射端口名 → 端口号会被记录下来重启时保持已向对端发布的端口不变见CacheServiceInstanceBase.ports的注释。可观测性缓存服务的指标通过 Provider 声明的default_metrics映射如命中率由lmcache_mp_lookup_hit_tokens_total与lmcache_mp_lookup_requested_tokens_total两个计数器相除得到L1/L2 用量、吞吐量同理查询内置 Prometheus并在 UI 上以服务级聚合与逐实例两种粒度呈现。参考文件索引cache-service-management.md本文依据的官方用户指南原文cache-providers.yaml内置 Provider 目录LMCache 完整声明、L2 后端、引擎注入、指标映射、Mooncake 与 XSKY MeshFusion 占位声明cache_providers.pyProvider/组件/字段/注入的 pydantic 模型与模板渲染、校验逻辑cache_services.py缓存服务与实例的数据模型、状态机、L2 级联语义cache_provider_source.pyProvider SourceYaml/URL/Embedded与严格文档校验、未知 key 检测cache_provider_catalog.py目录物化、内置资产与插件资产的合并、注入渲染cache_services.pyresolve_instance_cache_config实例共享缓存快照的解析与降级决策models.pyExtendedKVCacheConfig部署侧共享/本地 KV Cache 配置。赞分享后端人工智能模型推理服务集群管理可观测性【免费下载链接】gpustackA GPU cluster manager for high-performance AI model serving (vLLM, SGLang) and on-demand SSH-accessible GPU instances.项目地址https://gitcode.com/gh_mirrors/gp/gpustack点击查看免费下载相关推荐vLLM Hybrid KV Cache Manager 深度解析混合注意力模型的 KV Cache 分配与前缀缓存设计vLLM Hybrid KV Cache Manager 深度解析混合注意力模型的 KV Cache 分配与前缀缓存设计 本篇技术指南基于 vLLM 官方设计人工智能大模型模型推理服务推理引擎本地部署LMCache 实战配方为 Qwen3.5 / Qwen3.6 / Qwen3.8 混合注意力模型配置 KV Cache 前缀复用LMCache 实战配方为 Qwen3.5 / Qwen3.6 / Qwen3.8 混合注意力模型配置 KV Cache 前缀复用 本篇技术指南聚焦 LMCa人工智能大模型缓存抽象模型推理服务Doctrine Cache与微服务通信服务间缓存共享策略Doctrine Cache与微服务通信服务间缓存共享策略 你是否在微服务架构中遇到过这些问题服务间数据同步延迟、重复计算导致资源浪费、数据库压力过大Do缓存后端上一篇如何快速安装 ShizukuAndroid 系统权限提升终极指南下一篇Unity-Webview 插件使用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考