1. 为什么要把 Bonsai 2 27B 塞进 vLLM第一次看到 Bonsai 2 27B 这个模型的时候我脑子里冒出来的第一个念头不是这模型效果怎么样而是27B 的体量还是 ternary 2-bit 量化到底能不能在 vLLM 里跑起来。这个问题的答案并不是简单的能或不能因为 ternary 2-bit 这个量化格式本身就带着很强的实验性质而 vLLM 作为目前主流的高吞吐推理引擎它对量化格式的支持是有明确边界的。先把背景说清楚。Bonsai 2 27B 是一个采用 ternary 2-bit 量化的模型所谓 ternary指的是权重被约束在三个值上——通常是 -1、0、1 这样的三值集合每个权重只需要约 1.58 bit 的信息量就能表示工程上一般按 2-bit 来打包存储。这种量化的好处非常直接27B 参数的模型如果按 FP16 存储大概要 54GB 显存而 ternary 2-bit 理论上能把权重压到 7GB 上下这对消费级显卡或者单卡部署来说是完全不同的量级。但问题也恰恰出在这里。vLLM 的量化支持体系是围绕主流量化方案构建的比如 GPTQ、AWQ、FP8、INT8 这些它们的共同特点是权重布局和反量化逻辑都有相对标准的实现路径。ternary 2-bit 不在这个主流清单里它更像是一个自定义量化格式vLLM 官方并没有现成的 kernel 去直接吃这种权重。所以搬进 vLLM这件事本质上不是简单的模型加载而是一次格式适配和运行时改造。那为什么还要折腾因为 vLLM 带来的东西是别的推理框架很难替代的PagedAttention 带来的显存利用率、continuous batching 带来的吞吐提升、以及 OpenAI 兼容的 API 服务能力。如果你只是想在本地跑个对话llama.cpp 或者 LM Studio 加载 GGUF 就够了但如果你要做一个能扛并发的推理服务vLLM 几乎是绕不开的选择。这就是这次移植的核心动机——把 ternary 2-bit 的显存优势和 vLLM 的服务能力结合起来。需要提前说明的是这次移植不是一键转换那种轻松活。整个过程中你会反复遇到no lm runtime found for model format gguf!这类报错会纠结到底该走 GGUF 路线还是走自定义量化路线会在 CUDA 版本和 vLLM 版本之间反复横跳。这篇文章就是把这一整套账本摊开来讲包括每一步为什么这么做、踩了哪些坑、最后怎么跑通的。适合有一定推理部署经验、想尝试非主流量化格式的读者纯新手建议先把 vLLM 部署常规模型跑通再来。2. ternary 2-bit 与 vLLM 量化体系的错位在哪2.1 ternary 量化的数学本质与存储布局要理解移植的难点得先搞清楚 ternary 2-bit 到底是怎么存权重的。ternary 量化的核心思想是把每个权重映射到 {-1, 0, 1} 三个值配合一个缩放因子scale来恢复数值范围。假设原始权重是 w量化后的三值权重是 q那么反量化就是 w ≈ q * scale其中 scale 通常按每个 group比如 128 个权重一组单独计算。存储上因为一个三值只需要 log2(3) ≈ 1.58 bit工程实现一般用 2 bit 来存一个权重一个字节8 bit能塞下 4 个权重。这就带来一个关键问题权重的排布不再是标准的 FP16 那种每个权重占 2 字节、连续排列的形式而是4 个权重打包进 1 字节、需要位运算解包的形式。反量化的时候kernel 必须先把字节拆成 2-bit 的片段再映射回三值最后乘上 scale。这个布局和 vLLM 现有量化 kernel 的预期是完全不同的。GPTQ 的权重是 INT4 打包AWQ 也是 INT4它们的解包逻辑 vLLM 已经内置了而 ternary 2-bit 的解包逻辑vLLM 里根本没有对应的实现。这就是错位的根源——不是精度问题是数据布局和 kernel 接口对不上。2.2 vLLM 的量化加载链路是怎么走的vLLM 加载一个量化模型大致会经过这么几个环节先读 config 判断量化方法quant_method 字段然后根据方法选择对应的量化配置类接着实例化对应的线性层实现比如 GPTQLinearMethod、AWQLinearMethod最后在 forward 的时候调用对应的 kernel 做反量化和矩阵乘。关键就在选择对应的线性层实现这一步。vLLM 的量化方法注册是白名单式的config 里写的 quant_method 必须在它支持的枚举里否则直接报错或者回退到未量化路径。ternary 2-bit 如果不在这个白名单里你有两条路一是把量化方法伪装成某个已支持的格式让它走已有的 kernel二是自己写一个量化方法类并注册进去。前者省事但容易出精度问题后者干净但工作量大。我一开始想走伪装路线把 ternary 当成 INT4 来处理结果发现反量化出来的数值完全不对——因为 INT4 的解包是每字节两个权重、每个权重 4 bit而 ternary 是每字节四个权重、每个权重 2 bit位宽和打包密度都不一样硬套只会得到一堆垃圾数值。这个弯路走了大概半天才反应过来教训就是量化格式的位宽和打包密度是硬约束不能靠改个名字蒙混过去。2.3 GGUF 路线与自定义路线的取舍既然伪装走不通就得在 GGUF 路线和自定义量化路线之间做选择。GGUF 是 llama.cpp 生态的模型格式它对 ternary 这类非标准量化有比较好的支持很多 ternary 模型都是以 GGUF 形式发布的。但 vLLM 对 GGUF 的支持是有限的而且经常报no lm runtime found for model format gguf!这个错。这个报错的本质是vLLM 的 GGUF 支持依赖于它内部集成的 GGUF 加载器而这个加载器只认特定版本的 GGUF 量化类型。如果你的 GGUF 用的是较新的量化类型比如某些 ternary 变体加载器识别不了就会抛出这个 runtime not found 的错误。我实测下来vLLM 对 GGUF 的支持更像是能用但不完整尤其是遇到非标准量化时踩坑概率很高。自定义路线则是另一套逻辑把 ternary 权重从原始格式可能是 GGUF也可能是 safetensors读出来重新组织成 vLLM 能接受的张量布局然后写一个自定义的量化方法类去处理反量化。这条路工作量大但可控性强而且一旦跑通后续换模型、调参数都方便。我最后选的是自定义路线原因很简单——GGUF 那条路的报错太玄学排查成本反而更高。对比维度GGUF 路线自定义量化路线上手速度快直接加载慢需要写适配代码报错可排查性差runtime not found 难定位好报错基本能对应到具体代码精度控制依赖 GGUF 加载器实现完全自主可控后续维护受 vLLM 版本影响大相对独立适合场景快速验证生产部署3. 移植前的环境盘点与版本对齐3.1 CUDA、PyTorch、vLLM 三者的版本咬合移植这种事环境版本没对齐后面全是白费功夫。ternary 2-bit 的自定义 kernel 需要编译而编译又依赖 CUDA 工具链和 PyTorch 的版本。我这次用的是 CUDA 12.8 配合较新的 vLLM 版本这里有个细节要注意CUDA 12.8 对某些老版本的 PyTorch 支持不好而 vLLM 又对 PyTorch 版本有要求三者必须形成一个兼容的三角。我的建议是先确定 vLLM 版本然后反推 PyTorch 和 CUDA。比如你打算用 vLLM 的某个较新版本它通常会声明支持的 PyTorch 范围你再根据 PyTorch 选 CUDA。不要反过来先装 CUDA 再找 vLLM那样很容易卡在版本不匹配上。我见过有人装了 CUDA 12.8 结果 vLLM 只支持到 12.4 的编译产物最后只能重装。另外提醒一句如果你打算用 Docker 部署vllm/vllm-openai这个镜像的 tag 一定要和你的模型需求对齐。镜像里预装的 vLLM 版本决定了它支持哪些量化方法用错 tag 会出现镜像里能跑常规模型、但加载 ternary 就报错的情况。3.2 显存预算与模型切分策略27B 的模型即使是 ternary 2-bit也不是随便一张卡就能装下的。按 2-bit 打包算权重约 7GB但别忘了还有 KV cache、激活值、以及反量化过程中的临时张量。实际部署时显存占用往往比理论权重大不少。我建议在移植前先做一次显存预算。假设你用单卡 24GB权重 7GBKV cache 取决于序列长度和并发数如果做长上下文服务KV cache 可能吃掉好几 GB。剩下的显存要留给激活和临时缓冲。如果显存紧张可以考虑 tensor parallelism 把模型切到多卡上但要注意 vLLM 的 TP 对自定义量化方法的支持——有些自定义 kernel 在 TP 下需要额外处理切分逻辑不是自动就能工作的。提示在正式移植前先用一个小的 ternary 模型比如 1B 级别跑通整个流程验证你的自定义量化方法类能正确加载和推理再上 27B。直接上大模型一旦报错排查成本会高很多。3.3 依赖库与编译工具的检查清单自定义量化方法涉及 kernel 编译所以编译工具链必须齐全。我列一下这次用到的关键依赖CUDA toolkit要包含 nvcc、gcc/g版本要和 CUDA 兼容、PyTorch 的开发头文件、以及 vLLM 的源码因为要改量化方法注册部分。这里有个容易忽略的点vLLM 安装方式会影响你能不能改源码。如果你用 pip 装的预编译 wheel那量化方法注册的代码是编译进二进制的改起来很麻烦正确做法是从源码安装 vLLM这样你才能往量化方法列表里加自己的实现。我一开始图省事用 pip 装结果发现改不了注册逻辑只能卸载重装源码版。4. 从权重文件到 vLLM 可加载格式的转换实操4.1 解析原始权重GGUF 还是 safetensors第一步是搞清楚你手上的 Bonsai 2 27B 权重是什么格式。如果是 GGUF你需要用 GGUF 的解析库把张量读出来如果是 safetensors直接用 safetensors 库加载就行。ternary 模型的权重通常包含两部分打包后的 2-bit 权重张量以及每组的 scale 张量。读 GGUF 的时候要注意量化类型的标识。GGUF 文件头里会写明每个张量的量化类型ternary 可能有专门的类型编号。如果你读出来的类型和预期不符说明这个 GGUF 用的不是你想象的 ternary 格式得先确认清楚。我遇到过一种情况文件名叫 ternary但实际权重是 INT4 打包的这种名不副实的坑只能靠实际读取张量形状和数值来验证。4.2 权重重排把 2-bit 打包转成 vLLM 期望的布局读出来之后核心工作是把 2-bit 打包的权重转成 vLLM 自定义 kernel 能处理的布局。这里有两种思路一是在加载时就把权重解包成 FP16 或 BF16让 vLLM 走普通路径二是保持 2-bit 打包在 kernel 里做反量化。第一种思路简单但失去了量化的显存优势——解包成 FP16 后权重又变回 54GB等于白量化了。第二种思路才是正解但需要你写 kernel。我的做法是保持 2-bit 打包在自定义的 LinearMethod 里实现反量化逻辑forward 时先把 2-bit 权重解包成三值乘上 scale再做矩阵乘。重排的时候要特别注意 group 的划分。ternary 量化通常按 group 计算 scalegroup size 可能是 128 或 64。你的 kernel 必须和权重文件里的 group 划分一致否则 scale 会对错位置导致数值全乱。这个细节我在第一次实现时搞错了group size 按 128 处理但实际文件是 64结果输出全是乱码排查了好久才发现是 group 对不上。4.3 写一个最小可用的自定义量化方法类vLLM 的量化方法类需要实现几个关键接口创建权重create_weights、处理权重加载process_weights_after_loading、以及 forward 时的 apply 逻辑。我写了一个最小版本核心就是这三块。class TernaryLinearMethod(LinearMethodBase): def create_weights(self, layer, input_size, output_size, params_dtype): # 注册 2-bit 打包权重和 scale 两个参数 layer.register_parameter(qweight, ...) layer.register_parameter(scales, ...) def process_weights_after_loading(self, layer): # 加载后做必要的重排比如把 scale 调整成 kernel 期望的形状 ... def apply(self, layer, x, biasNone): # 反量化 矩阵乘 dequant unpack_ternary(layer.qweight) * layer.scales return x dequant.T这个类写完之后还要在 vLLM 的量化方法注册表里把它加进去让 config 里的 quant_method 能映射到你的类。注册的地方通常在 vLLM 的 quantization 模块里找到那个方法映射的字典加一行就行。注意process_weights_after_loading这个钩子很关键很多重排和预处理逻辑要放在这里而不是 create_weights。因为 create_weights 阶段权重还是空的只有加载完才能拿到真实数值做处理。5. 跑通过程中的报错与排查链路5.1no lm runtime found for model format gguf!的根因这个报错我遇到了不止一次它的触发场景是 vLLM 尝试用 GGUF 加载器加载模型但加载器找不到匹配的 runtime。根因通常有两个一是 GGUF 的量化类型不被当前 vLLM 版本支持二是 vLLM 的 GGUF 支持本身就不完整某些模型结构它压根没实现。排查这个错第一步是确认你的 vLLM 版本是否声明支持 GGUF。有些版本在文档里明确写了 GGUF 支持是实验性的那就别指望它能顺利加载非标准量化。第二步是看 GGUF 文件里的量化类型编号和 vLLM 源码里支持的编号列表对比对不上就是类型不支持。我最后的解决办法是绕开 GGUF 加载器直接走自定义量化路线把 GGUF 当普通权重文件解析不走 vLLM 的 GGUF 代码路径。这样就彻底避开了这个报错。5.2 反量化数值异常从 group size 到字节序数值异常是移植中最难查的一类问题因为报错不会告诉你哪里错了只会给你一堆 NaN 或者离谱的输出。我遇到过的数值异常有两个来源group size 不匹配和字节序问题。group size 前面提过了权重文件按 64 一组算 scale我按 128 处理结果 scale 错位。字节序问题则更隐蔽2-bit 打包时4 个权重在一个字节里的排列顺序高位在前还是低位在前不同实现可能不一样如果你的解包顺序和打包顺序反了解出来的三值就是错的。这个只能靠拿几个已知权重值手动验证——读一个字节按两种顺序解包看哪个结果和预期一致。5.3 显存溢出与 kernel 编译失败的应对显存溢出通常发生在加载阶段因为加载时可能同时存在原始权重和转换后的权重。解决办法是分步加载先加载一部分转换完释放原始数据再加载下一部分。或者用 CPU 内存做中转把权重先转到 CPU 再逐步搬到 GPU。kernel 编译失败则多半是 CUDA 版本或编译选项的问题。报错信息里通常会指出是哪个架构不支持、哪个头文件找不到。我遇到过一次是编译目标架构没指定对加上正确的-gencode参数后就过了。这类问题没有通用解只能看报错具体分析。报错现象可能根因排查方向no lm runtime foundGGUF 类型不支持换自定义路线或降 vLLM 版本输出 NaN/乱码group size 或字节序错手动验证解包逻辑加载时 OOM原始与转换权重共存分步加载、CPU 中转kernel 编译失败架构或头文件问题检查 gencode 和 include 路径6. 移植完成后的性能实测与调优6.1 吞吐与延迟和 FP16 版本的对比跑通之后我做了个简单对比同样的 27B 模型ternary 2-bit 版本和 FP16 版本在 vLLM 下的吞吐和延迟。结果是 ternary 版本在显存占用上有明显优势单卡能装下的并发数更多吞吐自然更高但单次推理的延迟ternary 因为多了反量化的计算比 FP16 略高一点。这个 trade-off 是符合预期的。反量化本身有计算开销但省下来的显存能换更多并发整体吞吐还是赚的。如果你的场景是低并发低延迟ternary 的优势不明显如果是高并发服务显存省下来就是实打实的吞吐提升。6.2 反量化 kernel 的优化空间我最初的反量化实现是先解包成完整张量再矩阵乘这个做法会临时生成一个大的 FP16 张量显存和计算都不划算。优化方向是把解包和矩阵乘融合在 kernel 里边解包边算避免中间张量。vLLM 的一些量化 kernel 就是这么做的可以参考它们的实现思路。另一个优化点是 scale 的应用时机。如果能在解包的同时乘 scale就省了一次单独的乘法。这些优化需要写 CUDA kernel工作量不小但如果你的服务对性能敏感值得投入。6.3 长上下文与并发下的稳定性观察长上下文场景下KV cache 的显存占用会显著上升这时候 ternary 省下来的权重显存就显得更宝贵。我实测在较长上下文下ternary 版本能支持的并发数比 FP16 版本多出不少。但要注意长上下文下反量化的计算量不变延迟会随上下文长度线性增长这是所有模型都有的特性不是 ternary 特有的问题。稳定性方面跑了一段时间没遇到崩溃或数值漂移。唯一要注意的是如果并发很高反量化 kernel 的临时显存分配可能成为瓶颈建议监控显存使用曲线必要时限制最大并发数。7. 这套移植方案能复用到哪些场景ternary 2-bit 的移植思路其实不局限于 Bonsai 2 27B 这一个模型。任何采用非主流量化格式的模型只要你能解析它的权重布局理论上都能用同样的方法搬进 vLLM。核心工作就三块解析权重、写自定义量化方法类、注册到 vLLM。我后来用同样的思路试过其他几个非标准量化的模型流程基本一致区别只在解包逻辑和 group 划分。所以这套方案的价值不在于跑通了某个模型而在于掌握了一套把非标准量化接入 vLLM 的方法论。下次再遇到类似的模型你不用从零开始照着这个账本走一遍就行。最后分享一个我在实际操作中的体会移植这类事情最耗时的从来不是写代码而是排查那些看起来能跑但结果不对的隐蔽问题。所以一定要在早期就建立验证手段——拿几个已知的权重值手动验证解包、用小模型先跑通流程、每一步都打印中间结果。这些笨办法看起来慢但能帮你省下后面几倍的排查时间。