@no_stp_on_snek: 如果你想试试，可以在这里找到：

@itsjuztin 如果你想要试试看，这里可以获取：https://t.co/lNkX7hMyF7 — # TheTom/llama-cpp-turboquant 来源：https://github.com/TheTom/llama-cpp-turboquant # llama.cpp + TurboQuant+ > 面向生产环境的KV缓存和权重量化，适用于llama.cpp，支持Apple Silicon、NVIDIA CUDA、AMD ROCm和Vulkan等多后端内核。许可证：MIT (https://opensource.org/licenses/MIT) 状态：WIP (https://github.com/TheTom/llama-cpp-turboquant) 编解码论文 (https://github.com/TheTom/turboquant_plus) 这是 ggml-org/llama.cpp (https://github.com/ggml-org/llama.cpp) 的一个分支，集成了 TurboQuant+ 编解码栈 —— Walsh-Hadamard 旋转极坐标量化、注意力门控稀疏反量化以及逐层感知的V压缩策略。编解码设计、校准和验证论文位于 TheTom/turboquant_plus (https://github.com/TheTom/turboquant_plus)；本仓库是 llama.cpp 运行时的集成实现。 ### 血统 —— 为什么是 + TurboQuant+ 的灵感来源于 Google 的原始 TurboQuant 论文（ICLR 2026），该论文引入了 Walsh-Hadamard 旋转极坐标码本量化用于 KV 缓存，并展示了在约1% PPL损失下实现4.6倍压缩。本项目在此基础上做了大量扩展——增加了非对称 K/V 策略（V 是自由的，K 是一切）、逐层感知的 Boundary V 保护、注意力门控稀疏 V 反量化、TQ3_1S / TQ4_1S 权重量化格式、turbo2 / turbo4 层级变体、跨后端内核覆盖（CUDA dp4a、HIP/ROCm RDNA/CDNA、Vulkan coopmat、Metal TurboFlash + V2.1 融合内核）以及一系列针对特定模型家族的质量和运行修复。尾部的 + 表示持续的扩展工作；原始的 TurboQuant 编解码仍是基础。 此分支是附加性的：所有现有的 llama.cpp 量化、模型和后端保持不变。新类型通过标准的 --cache-type-k / --cache-type-v 和 llama-quantize 接口选择加入。 ## 生产部署 本分支的 TurboQuant 集成用于： - LocalAI (https://localai.io) —— 即插即用的 OpenAI 兼容本地推理服务器 - Chronara (https://chronara.io) —— 量子安全的金融科技基础设施，结合 AI 驱动的网络 - AtomicChat (https://atomic.chat/) —— 设备端聊天应用 - 以及其他下游项目 ## 状态 | | | |—|—| | 默认分支 | feature/turboquant-kv-cache | | 领先上游的提交数 | ~300 | | 上游跟踪 | 持续与 ggml-org/llama.cpp master 同步 | | 上游 PR 状态 | 尚未推送上游；作为长期特性分支运行 | — ## 此分支增加的内容 ### 量化类型 | 类型 | 领域 | 近似位数 | 备注 | 论文 | |—|—|—|—|—| | TQ3_1S | 权重 | ~3.5 | 比 q8_0 占用更少显存 | weight-compression-tq4 (https://github.com/TheTom/turboquant_plus/blob/main/docs/papers/weight-compression-tq4.md) | | TQ4_1S | 权重 | ~4.5 | V2.1 融合 Metal 内核；CUDA dp4a 速度提升 3.5 倍（240 t/s vs 68 基线） | weight-compression-tq4 (https://github.com/TheTom/turboquant_plus/blob/main/docs/papers/weight-compression-tq4.md) | | turbo2 | KV 缓存 | ~2.0 | 激进；与 Boundary V 配合使用 | block-size-experiment (https://github.com/TheTom/turboquant_plus/blob/main/docs/papers/block-size-experiment.md) | | turbo3 | KV 缓存 | ~3.5 | ~4.6 倍压缩，PPL 损失 <1.5% | attn-rotation-and-ppl-artifact (https://github.com/TheTom/turboquant_plus/blob/main/docs/papers/attn-rotation-and-ppl-artifact.md) | | turbo4 | KV 缓存 | ~4.5 | 恢复后保真度超越 q4_0 | turbo4-resurrection (https://github.com/TheTom/turboquant_plus/blob/main/docs/papers/turbo4-resurrection.md) | 所有 turbo 格式均使用 Walsh-Hadamard 旋转，随后在 128 元素块上进行极坐标码本量化。为什么在 MSE 驱动的编解码失效时这种方法有效：why-mse-fails-for-kv-quantization (https://github.com/TheTom/turboquant_plus/blob/main/docs/papers/why-mse-fails-for-kv-quantization.md)。 ### 压缩策略 - 自动非对称 K/V 压缩 —— 认识到 V 能容忍激进压缩而 K 不能；默认策略选择互补编解码而非对称。 asymmetric-kv-compression (https://github.com/TheTom/turboquant_plus/blob/main/docs/papers/asymmetric-kv-compression.md) - Boundary V（实验性，逐层感知） —— 当选择 turbo2-V 时自动启用。保护那些激进 V 量化会降低质量的层，其余层保持完全激进。 layer-aware-v-compression (https://github.com/TheTom/turboquant_plus/blob/main/docs/papers/layer-aware-v-compression.md)，moe-v-compression-frontier (https://github.com/TheTom/turboquant_plus/blob/main/docs/papers/moe-v-compression-frontier.md) - 稀疏 V 反量化 —— 对于 softmax 注意力权重低于阈值的那些位置的 V，跳过反量化。在所有 Metal 目标上启用。 sparse-v-dequant (https://github.com/TheTom/turboquant_plus/blob/main/docs/papers/sparse-v-dequant.md) ### 后端覆盖 | 后端 | 量化内核 | Flash Attention | 备注 | |—|—|—|—| | Metal (Apple Silicon) | TQ V2.1 融合，TurboFlash | 是 —— 跨家族的稀疏 V；dk=512 FA 内核用于 Gemma 4 | 在 Apple10 上默认关闭 TurboFlash（回归损坏正在调查）。m5-max-stress-test (https://github.com/TheTom/turboquant_plus/blob/main/docs/papers/m5-max-stress-test.md) | | CUDA (NVIDIA) | TQ4_1S 的 dp4a，warp 协作反量化（每个块计算量减少16倍），多 token / 多 GPU | 是 —— turbo VEC FA（解码速度 +9%）；无需 GGML_CUDA_FA_ALL_QUANTS 即可混合使用 f16/bf16 + q8_0 | 加载时将 TQ4_1S 转换为 q8_0 的路径 | | HIP / ROCm (AMD) | 可移植的 ggml_cuda_dp4a；针对 AMD 的 TQ4_1S 标量半精度路径 | 是 —— 针对量化 KV 强制使用 VEC FA；FA f16 临时缓冲区的池绕过 | RDNA3 (gfx1100)、RDNA4、CDNA3 (MI300X / gfx942)、CDNA4 (MI355X / gfx950)。cross-engine-mi300x (https://github.com/TheTom/turboquant_plus/blob/main/docs/papers/cross-engine-mi300x.md) | | Vulkan | TQ4_1S 权重，turbo2/turbo4 的 SET_ROWS | 使用 turbo3 KV 的 coopmat flash attention | 计算着色器路径；可通过 nix 构建 | ### 模型家族支持 - Gemma 4 —— dk=512 Metal FA 内核，MoE token 路由，op 并发处理 - 大型 MoE —— 支持多达 256 专家路由的内核实例化 - 混合架构（GDN，Mamba） —— 从上游特性分支精选的推测解码 - 所有现有的 llama.cpp 模型家族均完全支持 ### 本分支携带的运行修复 - 修复了 n > 4096 时 turbo / TQ 类型的 CPU vec_dot 堆分配问题 - Apple Silicon 统一内存爆炸修复 - RPC GGML_OP_COUNT 断言修复 - 跨供应商的 -Werror 构建修复 - 针对缺失输入文件的防御性 xxd.cmake 处理 — ## 快速开始 标准的 llama.cpp 构建标志。当匹配的后端编译完成后，TurboQuant 类型会自动生效。 bash # Apple Silicon（Metal） cmake -B build -DGGML_METAL=ON && cmake --build build -j # NVIDIA CUDA cmake -B build -DGGML_CUDA=ON && cmake --build build -j # AMD HIP / ROCm（多架构 fat binary） cmake -B build -DGGML_HIP=ON -DCMAKE_HIP_ARCHITECTURES="gfx1100;gfx942;gfx950" && cmake --build build -j # Vulkan cmake -B build -DGGML_VULKAN=ON && cmake --build build -j ## 使用 ### KV 缓存量化（运行时） KV 缓存类型通过标准的 --cache-type-k / --cache-type-v 标志按 side 选择。 > 从轻度开始，然后逐步压缩。 某些模型家族——小模型、某些 MoE 配置、对量化敏感的指令调优变体——比其他模型更脆弱。首先选择一个轻度的非对称配置，在你特定的模型上验证输出质量（目视 + 在 hold-out 集上测量 PPL），然后如果你有额外的显存余量，可以增加 V 的激进程度。不要从最大压缩开始然后反向工作。 非对称 KV 压缩论文 —— 非对称 K/V 缓存压缩：为什么 V 是自由的，K 是一切 (https://github.com/TheTom/turboquant_plus/blob/main/docs/papers/asymmetric-kv-compression.md) —— 的核心发现驱动了下面所有的配置：V 能容忍激进压缩，K 则不能。始终将 K 保持比 V 更高的精度；绝不要从对称开始。该论文记录了如果你忽略这一点并对 K 进行激进压缩时将会遇到的具体失效模式（某些模型家族的 PPL 爆炸、低比特 K 与注意力旋转的相互作用等）——在考虑步骤 6 之前请先阅读。 更高的 turbo 数字 = 每个元素更多位数 = 压缩较低。V 侧的压缩阶梯是 turbo4（最轻）→ turbo3 → turbo2（最重）。在 K 侧，优先选择 f16 或 q8_0；绝不要一开始就用 turbo K。 推荐，从最保守到最激进： | 步骤 | --cache-type-k | --cache-type-v | 何时使用 | 备注 | |—|—|—|—|—| | 1. 最安全的起点 | f16 | turbo4 | 首次接触任何新模型 | K 保持不变，V 使用最轻的 turbo 层级。如果在此步骤输出不保真，则该模型对量化异常敏感——停止并调查后再继续。 | | 2. 保守 | q8_0 | turbo4 | 在步骤 1 验证安全，希望在不冒太大风险的情况下获得显存收益 | 两侧都较轻。通常与 f16/f16 输出几乎无法区分。 | | 3. 推荐默认 | q8_0 | turbo3 | 大多数密集模型，大多数生产工作负载 | 非对称 KV 压缩论文 (https://github.com/TheTom/turboquant_plus/blob/main/docs/papers/asymmetric-kv-compression.md)中描述的“非对称 turbo”最佳点。K 近乎无损，V 压缩约 4.6 倍。总 KV 比 f16/f16 小约 3-4 倍。 | | 4. 激进 V | q8_0 | turbo2 | 显存受限的长上下文，在步骤 3 验证质量后 | Boundary V 自动启用并保护敏感层。在保护层之外，密集模型的 PPL 损失预计小于 2%。 | | 5. MoE 感知激进 | q8_0 | turbo2 | 大型 MoE 模型（DeepSeek，Qwen3.6，Mixtral 风格） | 相同标志；Boundary V 的逐专家边界保护使其在 MoE 上有效。参见 moe-v-compression-frontier (https://github.com/TheTom/turboquant_plus/blob/main/docs/papers/moe-v-compression-frontier.md)。 | | 6. 不鼓励：对称 K 压缩 | 任意 turbo* | 任意 turbo* | 仅当手中有特定模型的质量验证结果时 | 压缩 K 是模型出问题的地方。非对称论文记录了失效模式。这不是一个起点。 | 示例调用： bash # 步骤 1 —— 最安全的起点（首次接触新模型） llama-cli -m model.gguf --cache-type-k f16 --cache-type-v turbo4 -p "..." # 步骤 3 —— 推荐默认（非对称 turbo） llama-cli -m model.gguf --cache-type-k q8_0 --cache-type-v turbo3 -p "..." # 步骤 4 —— 长上下文下的激进 V llama-cli -m model.gguf --cache-type-k q8_0 --cache-type-v turbo2 -c 131072 -p "..." 如果在步骤之间输出质量下降，回退到前一步。压缩边界是模型特定的——没有全局“最佳”设置。 ### 权重量化（离线） 权重量化在转换时通过 llama-quantize 选择： bash # TQ4_1S —— 推荐用于大多数 CUDA / HIP 部署（dp4a 比基线快 3.5 倍） llama-quantize model.f16.gguf model.tq4_1s.gguf TQ4_1S # TQ3_1S —— 更小，接受约 1-2 PPL 提升 llama-quantize model.f16.gguf model.tq3_1s.gguf TQ3_1S ### 自动行为 以下行为根据所选类型自动激活——无需额外标志： - 自动非对称 K/V —— 当两侧均为 turbo / TQ 类型时，策略选择互补配置而非对称。 - Boundary V（逐层感知） —— 对于任何选择了 turbo2-V 的情况自动启用。 - 稀疏 V 反量化 —— 在 Metal 目标上，对于所有 turbo V 类型，稀疏 V 自动激活。 - Flash Attention —— 对于使用相关后端内核的 turbo KV，自动启用。 请参阅上面链接的论文，以获取针对每个模型进行参数选择的指导。 ## 引用 如果你在作品中使用了此分支或其任何量化类型，请引用 TurboQuant+ 论文库 (https://github.com/TheTom/turboquant_plus/tree/main/docs/papers) 中的相应论文。 ## 许可证 MIT，与上游 llama.cpp 相同。 — ## 近期 API 变更 - libllama API 变更日志 (https://github.com/ggml-org/llama.cpp/issues/9289) - llama-server REST API 变更日志 (https://github.com/ggml-org/llama.cpp/issues/9291) ## 热门话题 - Hugging Face 缓存迁移：使用 -hf 下载的模型现在存储在标准的 Hugging Face 缓存目录中，便于与其他 HF 工具共享。 - 指南：使用 llama.cpp 的新 WebUI (https://github.com/ggml-org/llama.cpp/discussions/16938) - 指南：使用 llama.cpp 运行 gpt-oss (https://github.com/ggml-org/llama.cpp/discussions/15396) - [反馈] 改进 llama.cpp 的打包以支持下游消费者 🤗 - 增加了对原生 MXFP4 格式的 gpt-oss 模型的支持 | PR (https://github.com/ggml-org/llama.cpp/pull/15091) | 与 NVIDIA 合作 (https://blogs.nvidia.com/blog/rtx-ai-garage-openai-oss) | 评论 (https://github.com/ggml-org/llama.cpp/discussions/15095) - llama-server 中的多模态支持已到来： #12898 (https://github.com/ggml-org/llama.cpp/pull/12898) | 文档 - 用于 FIM 补全的 VS Code 扩展：https://github.com/ggml-org/llama.vscode - 用于 FIM 补全的 Vim/Neovim 插件：https://github.com/ggml-org/llama.vim - Hugging Face Inference Endpoints 现已原生支持 GGUF！https://github.com/ggml-org/llama.cpp/discussions/9669 - Hugging Face GGUF 编辑器：讨论 (https://github.com/ggml-org/llama.cpp/discussions/9268) | 工具 (https://huggingface.co/spaces/CISCai/gguf-editor) –– ## 快速开始 开始使用 llama.cpp 非常简单。以下是在你的机器上安装它的几种方法： - 使用 brew, nix 或 winget 安装 llama.cpp - 使用 Docker 运行——参阅我们的 Docker 文档 - 从 releases 页面 (https://github.com/ggml-org/llama.cpp/releases) 下载预构建的二进制文件 - 通过克隆此仓库从源代码构建——查看 我们的构建指南 安装后，你需要一个模型来工作。前往 获取和量化模型 部分了解更多。 示例命令： sh # 使用本地模型文件 llama-cli -m my_model.gguf # 或者直接从 Hugging Face 下载并运行模型 llama-cli -hf ggml-org/gemma-3-1b-it-GGUF # 启动 OpenAI 兼容的 API 服务器 llama-server -hf ggml-org/gemma-3-1b-it-GGUF ## 描述 llama.cpp 的主要目标是在广泛硬件上——本地和云端——以最小设置和最先进的性能实现 LLM 推理。 - 纯 C/C++ 实现，无任何依赖 - Apple Silicon 是一级公民——通过 ARM NEON、Accelerate 和 Metal 框架优化 - 对 x86 架构支持 AVX、AVX2、AVX512 和 AMX - 对 RISC-V 架构支持 RVV、ZVFH、ZFH、ZICBOP 和 ZIHINTPAUSE - 1.5-bit、2-bit、3-bit、4-bit、5-bit、6-bit 和 8-bit 整数量化，用于更快的推理和更少的内存使用 - 自定义 CUDA 内核，用于在 NVIDIA GPU 上运行 LLM（通过 HIP 支持 AMD GPU，通过 MUSA 支持 Moore Threads GPU） - Vulkan 和 SYCL 后端支持 - CPU+GPU 混合推理，部分加速超过总显存容量的大型模型 llama.cpp 项目是开发 ggml (https://github.com/ggml-org/ggml) 库新特性的主要试验场。 模型 通常也支持以下基础模型的微调版本。添加新模型支持的说明：HOWTO-add-model.md #### 纯文本 - [X] LLaMA 🦙 - [x] LLaMA 2 🦙🦙 - [x] LLaMA 3 🦙🦙🦙 - [X] Mistral 7B (https://huggingface.co/mistralai/Mistral-7B-v0.1) - [x] Mixtral MoE (https://huggingface.co/models?search=mistral-ai/Mixtral) - [x] D