【免费下载链接】vllm-metalCommunity maintained hardware plugin for vLLM on Apple Silicon项目地址https://gitcode.com/gh_mirrors/vl/vllm-metal点击查看免费下载vllm-metal 是 vLLM 在 Apple Silicon 上的社区硬件插件其内置的 TurboQuant 功能可以对 KV 缓存做有损量化压缩——默认配置下即可把 KV 缓存压缩约 2.56 倍让同一块统一内存多容纳约 2.5 倍的上下文长度。本文讲清楚 TurboQuant 的量化原理、压缩率怎么选、一行 JSON 如何开启以及配套的 Prefill 加速环境变量。为什么长上下文是 Mac 上跑 LLM 的痛点大模型生成文本时每一层的 KKey和 VValue向量都会被缓存下来供后续注意力计算使用。缓存大小随上下文长度线性增长模型越大、上下文越长占用的显存越多。Apple Silicon 的统一内存虽然比独显更宽裕但 KV 缓存仍然是长上下文场景下最先爆掉的部分。TurboQuant 的思路是KV 缓存不必以 BF16/FP16 全精度存储通过量化把每个元素从 16 bit 压到 2~8 bit从而在同样的内存预算下塞进更多 token。官方在 Llama-3.2-1B、max_model_len32768场景下实测默认压缩配置可让可用上下文扩展约 2.5 倍详见 docs/turboquant.md。TurboQuant 量化原理K 和 V 用不同策略TurboQuant 对 K 和 V 采用了两套不同的量化方案完整文档docs/turboquant.md张量量化方法说明KKey分块仿射量化per-block affine每个小块独立计算缩放因子不做旋转精度损失可控VValueWalsh–Hadamard 旋转 Lloyd-Max 非均匀量化先旋转打散数值分布再映射到预计算的 8 个质心以 3 bit 为例失真更小量化/反量化全部在 Apple Silicon 上通过MLX Metal 内核原生执行不占用 CPU 带宽。Python 侧编解码辅助代码见 vllm_metal/attention/caches/turboquant.py3 bit Lloyd-Max 质心表在 vllm_metal/attention/caches/turboquant.pyMetal 端内核位于 vllm_metal/metal/kernels_v2/turboquant.metal。量化是有损的K 的误差影响注意力权重V 的误差影响加权和结果。位宽越低省得越多但质量风险越大。压缩率怎么选实测数据与质量红线官方在一组 Qwen3-0.6B 几何参数28 层、4 个 KV 头、head_dim128下测得以下压缩率vs FP16完整数据见 docs/turboquant.md配置压缩率定位k_quantq8_0v_quantq3_0默认2.56x质量/体积平衡推荐的起步配置k_quantq5_0v_quantq3_03.37x进一步省内存k_quantq4_0v_quantq3_03.76x低内存选项需验证模型质量k_quantuint2v_quantq3_04.92x激进压缩质量损失明显⚠️质量红线来自官方已知质量下限int2 q2_05.82x已观察到退化重复循环等严重输出问题仅适合容量基准测试不要用于正式服务生产环境上线激进位宽前务必用固定语料对比 BF16 缓存的困惑度perplexity。合法取值在 vllm_metal/config.py 中定义K 支持q8_0 / q5_0 / q4_0 / int2 / uint2等V 支持q2_0 ~ q8_0Lloyd-Max。一键开启 TurboQuant一个 JSON 配置就够TurboQuant 通过 vLLM 标准的--additional-configJSON 开关没有额外的启动参数。最小可用示例摘自 docs/turboquant.mdvllm serve meta-llama/Llama-3.2-1B-Instruct \ --dtype bfloat16 \ --max-model-len 65536 \ --additional-config {turboquant: true, k_quant: q8_0, v_quant: q3_0}三个配置键一目了然键默认值含义turboquantfalse开启 TurboQuant KV 缓存压缩k_quantq8_0K 的量化位宽v_quantq3_0V 的量化位宽支持范围与限制✅ MHA 模型以及 SDPA GDN 线性注意力的混合模型混合模型中只压缩 SDPA 层GDN 递归状态保持原精度❌ MLA 模型不受支持在 MLA 模型上开启会在启动时直接抛NotImplementedError而不是静默降级head dimension 必须是 64 / 128 / 256 / 512FWHT 旋转内核支持的尺寸进阶Prefill 加速环境变量 VLLM_METAL_TQ_PREFILLTurboQuant 压缩后的 KV 页在长上下文 Prefill 时可以按需物化反量化回 FP16/BF16再走高性能 NAX / tiled 注意力内核。准入逻辑何时物化、何时留在压缩路径上实现在 vllm_metal/attention/impls/turboquant_prefill.py短后缀、解码步、推测验证等场景走原有压缩内核历史上下文 ≥ 8192 token 且新 query token 达到校准阈值特定几何下为 64否则max(128, head_dim // 2, ...)时物化路径更快——官方实测 Qwen3-4B 在 M5 Pro 上 TTFT 最高可提速约 4 倍。相关环境变量定义于 vllm_metal/envs.py环境变量默认值作用VLLM_METAL_TQ_PREFILLautoauto在 NAX 可用M5时自动启用1在 M1–M4 上显式启用 tiled 路径0关闭物化VLLM_METAL_TQ_PREFILL_MAX_MIBauto物化工作区上限从gpu_memory_utilization预算内一次性预留不会挤占现有 KV0禁用两个变量都需在 worker 启动前设置。M3 等非 M5 机型默认不开启需要手动设VLLM_METAL_TQ_PREFILL1。源码与测试地图想深入从哪里读起关注点路径压缩原理与全部配置项docs/turboquant.mdPython 侧编解码 / Lloyd-Max 表vllm_metal/attention/caches/turboquant.py融合反量化物化内核封装vllm_metal/attention/caches/turboquant_materialize.pyPrefill 准入策略vllm_metal/attention/impls/turboquant_prefill.pyMetal 量化/反量化内核vllm_metal/metal/kernels_v2/turboquant.metal生产路径回归测试tests/attention/test_turboquant_prefill.py、tests/attention/test_tq_hd128_policy.py内核级基准工具tools/benchmark/tq_lane_verify.py常见问题FAQQ压缩会不会让回答变差量化是有损的影响程度取决于模型、位宽、上下文长度和负载。默认q8_0/q3_0质量风险最小上生产前建议用固定语料与 BF16 缓存对比困惑度。Q开启后内存一定会省 2.5 倍吗压缩的是 KV 缓存部分随上下文线性增长的那部分权重与激活内存不变。上下文越长省出的绝对内存越多。Q和 KV Offloading 能一起用吗可以二者互补TurboQuant 降低单 token 缓存体积KV Offloading见 docs/kv_offloading.md把淘汰块卸载到主机内存/磁盘。小结TurboQuant 是 vllm-metal 上几乎零成本的长上下文利器一行 JSON 开启、默认q8_0/q3_0即可获得 2.56 倍 KV 压缩配合VLLM_METAL_TQ_PREFILL还能在长历史 Prefill 时额外提速。建议从默认位宽起步在自己的目标负载上验证质量后再考虑更激进的压缩配置。赞分享【免费下载链接】vllm-metalCommunity maintained hardware plugin for vLLM on Apple Silicon项目地址https://gitcode.com/gh_mirrors/vl/vllm-metal点击查看免费下载相关推荐TurboQuant M5 Max 128GB 压测实战70B 与 104B 大模型长上下文 KV 缓存压缩全解析TurboQuant M5 Max 128GB 压测实战70B 与 104B 大模型长上下文 KV 缓存压缩全解析 导读 本文是 TurboQuant KV层自适应 KV 缓存压缩TurboQuant 中按层精度分配的实验验证与实战配置层自适应 KV 缓存压缩TurboQuant 中按层精度分配的实验验证与实战配置 导读 本文以 TurboQuant 仓库中的 docs/experimeMLX Quality Suite 上下文规模扩展实测Qwen3.5-2B-8bit 在 TurboQuant turbo4 压缩 KV Cache 下的吞吐与峰值内存MLX Quality Suite 上下文规模扩展实测Qwen3.5 2B 8bit 在 TurboQuant turbo4 压缩 KV Cache 下的吞吐创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考