【免费下载链接】vllm-metalCommunity maintained hardware plugin for vLLM on Apple Silicon项目地址https://gitcode.com/gh_mirrors/vl/vllm-metal点击查看免费下载在 Apple Silicon 上部署大模型时KV Cache 卸载KV Cache Offloading是 vllm-metal 提供的一项关键能力当 Metal KV 缓存被新请求挤满、旧块被逐出时这些块不会直接丢弃而是被保存到主机内存池、甚至磁盘中。之后当相同前缀再次出现或服务器重启后vllm-metal 会从缓存中恢复这些块免去重复的 prefill 计算让你用内存和磁盘空间换取更长的上下文与更快的首 token 响应。vllm-metal 是为 Apple Silicon Mac 打造的 vLLM 硬件插件基于 MLX 后端运行 vLLM本文带你完整掌握它的 KV Cache 卸载配置方法。为什么要做 KV Cache 卸载统一内存架构下模型权重和 KV 缓存共用同一块内存。当并发请求多、上下文长时KV 缓存很快被挤满旧请求的 KV 块被逐出前缀缓存失守相同前缀的后续请求只能重新计算 prefillTTFT首 token 延迟显著变慢服务器一重启所有缓存全部丢失KV Cache 卸载的思路很直接把被淘汰的 KV 块往更便宜的存储上搬——先搬进可分页的主机内存再落到磁盘。这样更长的上下文和跨重启的复用就不再受限于缓存容量。 关键点主机内存池并不是额外的内存它从--gpu-memory-utilization划定的总预算里扣除。池子越大Metal KV 缓存越小启动日志的内存明细中会显示kv_offload_pool一项方便你核对。两级存储架构内存池 磁盘层vllm-metal 的卸载链路是三级结构层级存储位置特点L1Metal 统一内存中的 KV 缓存速度最快容量最小命中即免重算L2主机内存池匿名 RAMmacOS 没有/dev/shmshared_region.py 用进程内共享的匿名内存实现池区可被系统分页L3磁盘fs层容量最大按内容哈希命名块文件支持跨重启复用调度器侧由 connector.py 中的MetalOffloadingConnector接管实际块拷贝发生在 worker.py磁盘层的私有目录、容量上限与 Spotlight 排除逻辑实现在 fs_tier.py配置翻译与参数校验在 config.py。完整说明见官方文档 docs/kv_offloading.md。快速上手两条命令开启卸载场景一只启用主机内存池vllm serve Qwen/Qwen3-8B --kv-offloading-size 8--kv-offloading-size 8表示 8 GiB 的主机池这个值同时也开启了卸载功能。场景二内存池 50 GiB 磁盘层vllm serve Qwen/Qwen3-8B \ --kv-offloading-size 8 \ --kv-transfer-config {kv_connector_extra_config: {secondary_tiers: [{type: fs, root_dir: /path/to/kv-store, max_size_gib: 50}]}}磁盘层只支持fs文件系统类型obj对象存储依赖的 NIXL 没有 macOS 构建会被直接拒绝。核心配置项详解服务启动参数参数说明--kv-offloading-size N主机池大小GiB同时开启卸载。可省略此时池子默认为两个--max-model-len请求的 KV 量启动日志会报告实际大小--kv-offloading-backend只能是默认的nativelmcache会被拒绝--kv-transfer-config以 JSON 传入次级存储层仅支持fs磁盘层fs tier参数键默认值说明type必填固定为fsroot_dir必填块文件的存放目录max_size_gib卷容量的 10%磁盘上限GiB0表示不限制关于默认池大小的一个小知识不传--kv-offloading-size时两个满长度请求是经过实测的最小无重试池大小4 并发下池满不会丢块调度器会在下一步重试写入该默认值还会被自动压缩到 KV 预算的 1/4 以内并在启动日志中提示。跨重启复用缓存文件按内容寻址 块文件以内容哈希命名。使用默认的--prefix-caching-hash-algo sha256或sha256_cbor时哈希种子是固定的重启后的服务器能直接找到之前写下的块——重启不等于失忆。⚠️ 两个注意点若改用xxhash/xxhash_cbor种子每进程随机重启后将找不到旧块除非设置PYTHONHASHSEED且所有共享同一 store 的服务器保持一致服务器启动时会警告存储以模型名 dtype为键不校验权重本身同名替换 checkpoint 后记得删除root_dir支持范围哪些模型可以用目前仅支持单一完整注意力组的模型GQA / MHA / MQA例如 Qwen3 稠密模型。以下情况会在启动时明确拒绝而不是运行中悄悄出错滑动窗口模型、MLA 模型、KV 缓存分成多组的混合架构模型draft 模型投机解码如 dflash / dsparkPooling池化与语音转写STT模型流水线并行、数据并行以及uni之外的 executor这套限制在 config.py 中逐条校验错误信息会直接告诉你需要去掉哪个参数。生产环境运维清单 磁盘上限写入即将突破上限时先删最久未存/读的块正在读写中的文件绝不删除。上限按进程计算多台服务器请各用独立的root_dir权限安全store 目录自动以0700创建可防止其他用户读取块文件提示内容可从块中恢复Spotlight 与备份块放在.noindex目录内被 Spotlight 跳过Time Machine 默认不排除可自行执行tmutil addexclusion /path/to/kv-store多实例路由配合--kv-events-configenable_kv_cache_events: true可让 KV 感知的路由跟踪每台服务器含磁盘上持有的块磁盘层会自动补上enable_kv_events如何验证卸载的真实收益项目内置了基准工具 tools/benchmark/kv_offload_benchmark.py它针对四个典型负载分别对比卸载开/关负载场景预期no-reuse全不同的 prompt对照组卸载帮不上忙应无差异reuse-fits前缀放得进 KV 缓存对照组前缀缓存已够用应无差异spill_revisit前缀超过缓存容量被挤出后再次访问第二轮 TTFT 明显下降restart同一流量由新进程处理只有配了磁盘层才能恢复两个对照组是刻意设计的如果它们也出现卸载更快说明测到的是排队而非 prefill结果应当作废。运行示例python tools/benchmark/kv_offload_benchmark.py \ --model mlx-community/Qwen2.5-32B-Instruct-4bit --out kv-offload-bench.json⏱️ 注意卸载要发挥作用需要 KV 缓存小到能被溢满。小模型在大内存机器上缓存容量充足压不爆就看不到收益——这是机器特性不是功能问题。总结vllm-metal 的 KV Cache 卸载让 Apple Silicon 上的 vLLM 部署突破了 KV 缓存的容量瓶颈✅ 一条--kv-offloading-size命令即可开启主机内存池✅ 加一个fs磁盘层获得跨请求、跨重启的前缀复用✅ 内存池从总内存预算中透明扣除启动日志全程可审计✅ 限制明确、启动即校验不支持的配置会给出精确的修改建议如果你的工作负载有大量共享前缀多轮对话、RAG 长文档、Agent 场景这套用内存和磁盘换上下文的方案值得马上尝试。更多细节请参考 docs/kv_offloading.md 与内存配置说明 docs/configuration.md。赞分享【免费下载链接】vllm-metalCommunity maintained hardware plugin for vLLM on Apple Silicon项目地址https://gitcode.com/gh_mirrors/vl/vllm-metal点击查看免费下载相关推荐LMCache CPU Offloading 实战指南将 KV Cache 卸载到 CPU 内存加速长上下文推理LMCache CPU Offloading 实战指南将 KV Cache 卸载到 CPU 内存加速长上下文推理 LMCache 将 KV cache 视为人工智能大模型缓存抽象模型推理服务vLLM MooncakeStoreConnector 使用指南基于 Mooncake 分布式存储的 KV Cache 卸载与跨实例前缀缓存共享vLLM MooncakeStoreConnector 使用指南基于 Mooncake 分布式存储的 KV Cache 卸载与跨实例前缀缓存共享 Moonca人工智能大模型模型推理服务推理引擎本地部署Mooncake × llm-d 集成指南在 Kubernetes 上搭建 vLLM KV Cache 卸载与 P/D 传输三层栈Mooncake × llm d 集成指南在 Kubernetes 上搭建 vLLM KV Cache 卸载与 P/D 传输三层栈 Mooncake 是 Ki人工智能大模型模型推理服务后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考