Transformers 中的 VPTQ 超低位宽量化量化模型解读、加载与推理实战【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformersVPTQVector Post-Training Quantization向量后训练量化是一种把 LLM 权重压缩到 2-bit 以下极低比特位宽的后训练量化方案它无需重新训练即可让 70B 甚至 405B 量级模型以小体积、低解码开销的方式高效运行。本文以 Transformers 官方量化文档 vptq.md 为主体结合仓库内 VPTQ 的量化器、配置类与集成测试源码系统讲解 VPTQ 的核心原理、模型命名解码、体积估算、加载推理的完整实战流程以及它在 Transformers 内部的注册与换层机制。读完你将能够自己安装 VPTQ、读懂 VPTQ-community 系列量化模型的命名含义、用from_pretrained一键加载并跑通推理。VPTQ 是什么面向 2-bit 的超低位宽后训练量化Vector Post-Training QuantizationVPTQ是一种**后训练量化PTQ方法核心思路是用向量量化vector quantization**替代传统的逐元素scalar定点量化不再把单个权重四舍五入到几个离散刻度而是把权重向量映射到一组聚类中心centroid上并只保存索引从而实现极低的平均比特位宽。根据 vptq.md 的说明VPTQ 的关键定位包括极低位宽可以把 70B、甚至 405B 参数规模的模型量化到 1–2 bit 左右的权重表示且无需重新训练无需 retraining轻量级量化流程量化 405B 模型大约需要 17 小时属于开销较低的轻量算法敏捷推理解码decoding额外开销低、吞吐高首 Token 时间Time To First Token, TTFT表现良好高性能 KernelVPTQ 提供了面向 NVIDIA 与 AMD GPU 的高效 kernel 用于推理这也是它能低开销解码的底层原因。需要注意上述“1–2 bit”指模型权重表示的平均位宽文档内标注为不含 codebook、参数与 padding 开销的位宽而社区量化模型命名里给出的“等效位宽”是包含多级索引与残差编码后的合计值具体换算方法见下文「解码模型命名」。安装与环境要求VPTQ 以独立的 Python 包发布运行pip install即可安装它随包提供 NVIDIA / AMD GPU 上的高效推理 kernelpip install vptq在 Transformers 侧从源码可以看出运行 VPTQ 量化模型还有三个前置条件全部在 quantizer_vptq.py 的validate_environment中做了强校验必须安装 Accelerate否则抛出ImportError(Using vptq quantization requires Accelerate: pip install accelerate)VPTQ 版本不能低于 0.0.4。版本下限常量VPTQ_MIN_VERSION 0.0.4定义在 import_utils.py对应的可用性检测函数is_vptq_available位于同文件 import_utils.py。若缺失或版本过旧会提示pip install -U vptq必须有可用的 CUDA GPU。代码中直接检查torch.cuda.is_available()否则抛出RuntimeError(GPU is required to run VTPQ quantized model.)。也就是说pip install vptq之外典型的最小运行环境是GPU 主机 PyTorchCUDA 版 Accelerate vptq0.0.4。由于换层发生在 CUDA 上、权重以 VPTQ 专属结构存储CPU 或纯 MPS 环境目前无法加载这类模型。读懂 VPTQ 量化模型命名centroid 数量 → 等效位宽VPTQ-community 社区提供了一批 VPTQ 量化模型模型名本身就是一份“量化参数档案”包含码本centroid规模信息。文档以Meta-Llama-3.1-70B-Instruct-v8-k65536-256-woft为例做了拆解命名片段含义Meta-Llama-3.1-70B-Instruct基础模型名称对应原版架构与权重v8量化变体/版本标识k65536主码本聚类中心数 65536即 2^16256残差码本聚类中心数 256即 2^8woft无 fine-tuning无微调量化模型名中同时携带了 bitwidth 信息不含 codebook、参数与 padding 开销。索引位宽的换算方法是对聚类中心数取 log2 再除以 8bit 转 byte 是后面估算体积时的事这里先算 bitindex主索引log2(65536) 16即 2-bitresidual index残差索引log2(256) 8即 1-bittotal bit-width合计2 1 3-bit。用同样的方法可以验证测试用例与加载示例中用到的模型。例如测试文件 test_vptq.py 里的Meta-Llama-3.1-8B-Instruct-v12-k65536-4096-woft65536 → 2-bit40962^12→ 1.5-bit合计 3.5-bit文档加载示例中的Meta-Llama-3.1-70B-Instruct-v16-k65536-65536-woft则是 2 2 4-bit。也就是说k后面的数字决定主索引位宽最后一个数字决定残差索引位宽两者相加才是模型名对应的等效位宽。估算模型体积位宽 × 参数量知道等效位宽后可以快速估算量化后模型的静态权重体积。公式很简单模型体积 ≈ 参数量 × 等效位宽 / (8 bit/byte)沿用上面的 3-bit 例子70B × 3-bits / 8-bits-per-byte 26.25 GB即在忽略码本codebook、scale/perm 参数与填充padding开销的前提下LLaMA-3.1-70B 的 3-bit VPTQ 模型权重约占 26.25GB 显存/内存。这套估算方法在你挑选部署模型、判断单卡/多卡是否放得下时非常实用。加载 VPTQ 量化模型进行推理在 Transformers 中加载 VPTQ 量化模型与加载普通模型完全一致直接用AutoModelForCausalLM.from_pretrained底层对应PreTrainedModel.from_pretrained传模型 ID、dtype与device_map即可。文档给出的示例from transformers import AutoTokenizer, AutoModelForCausalLM quantized_model AutoModelForCausalLM.from_pretrained( VPTQ-community/Meta-Llama-3.1-70B-Instruct-v16-k65536-65536-woft, dtypeauto, device_mapauto )dtypeauto让框架按权重自身的存储精度加载device_mapauto由 Accelerate 自动调度设备70B 级别模型在单卡显存不足时会自动拆分到多卡——集成测试 test_vptq.py 的test_quantized_model_multi_gpu正是验证了device_mapauto下量化模型可以跨两张 GPU 正确加载与生成。加载后即可配合 Tokenizer 正常调用generatetokenizer AutoTokenizer.from_pretrained(VPTQ-community/Meta-Llama-3.1-70B-Instruct-v16-k65536-65536-woft) input_ids tokenizer(Hello my name is, return_tensorspt).to(cuda) output quantized_model.generate(**input_ids, max_new_tokens32) print(tokenizer.decode(output[0], skip_special_tokensTrue))集成测试 test_vptq.py 对 8B 的 v12 模型做了确定性校验do_sampleFalse时输出与期望结果完全一致说明该路径上的解码是稳定可复现的。保存与再次加载可序列化VPTQ 量化模型支持save_pretrained落盘并重新加载——这由 quantizer_vptq.py 中is_serializable返回True保证。测试 test_vptq.py 演示了完整的 “save → load → generate” 闭环with tempfile.TemporaryDirectory() as tmpdirname: quantized_model.save_pretrained(tmpdirname) model AutoModelForCausalLM.from_pretrained(tmpdirname, device_mapcuda) # 继续 generate输出与加载前一致这在实际部署中的含义是可以把已下载/转换好的 VPTQ 模型缓存成本地目录之后从本地路径离线加载。源码层面VPTQ 在 Transformers 内部是如何被接进来的VPTQ 属于 Transformers 的“加载型”量化后端transformers 本身不做量化requires_calibrationTrue只负责把社区已量化的权重高效地换入模型结构中并跑推理。整个集成可以拆成四层。第一层注册与自动分发在 auto.py 中量化后端以字符串为键注册auto.pyvptq: VptqHfQuantizer把配置字符串映射到量化器实现auto.pyvptq: VptqConfig用于配置类的反序列化。因此只要模型仓库的量化配置文件quantization_config声明quant_method: vptqfrom_pretrained就会自动实例化对应的量化器无需任何手工指定。第二层VptqHfQuantizer 生命周期VptqHfQuantizer 继承自HfQuantizer其关键属性与钩子requires_calibration True表示该方法需要校准数据Transformers 集成并不负责执行量化过程只负责加载已经量化完毕的模型类 docstring 写明 “Enables the loading of prequantized models”validate_environment()加载前检查 Accelerate、vptq0.0.4、CUDA 可用性见上文_process_model_before_weight_loading()在权重加载之前完成模型结构替换——先计算modules_to_not_convert合并了用户传入列表与模型的_keep_in_fp32_modules再调用replace_with_vptq_linear把线性层全部替换is_trainable FalseVPTQ 量化模型当前不支持在 Transformers 内训练/微调只用于推理is_serializable True支持save_pretrained序列化保存。第三层replace_with_vptq_linear 换层replace_with_vptq_linear 是实际的“换层引擎”位于 integrations/vptq.py遍历模型的全部子模块model.named_modules()用should_convert_module结合modules_to_not_convert过滤出需要量化的nn.Linear在torch.device(meta)上下文里读取该层对应的量化参数详见下节实例化来自vptq库的VQuantLinearfrom vptq import VQuantLinear构造参数包括vector_lens、num_centroids、num_res_centroids、group_num、group_size、outlier_size、indices_as_float、enable_norm、enable_perm并固定is_indice_packedTrue、enable_proxy_errorFalse对原模块关闭requires_grad再用model.set_submodule完成替换若一个线性层都没替换成功会打印告警日志提示检查模型结构。可以看到Transformers 并不复刻 VPTQ 的算法内核而是把 vptq 包作为强依赖直接调用其VQuantLinear层——换层后真正的量化 GEMM/decode kernel 由 VPTQ 自己实现。若想自行量化模型而非加载社区量化模型文档说明需要参考 VPTQ 仓库提供的 “VPTQ Quantization Algorithm” 教程离线完成量化与导出一体化流程该流程需要校准无法在 Transformers 内触发。第四层逐层量化参数如何提供换层时的参数来自VptqConfig的两个字典config_for_layers按完整模块名如model.decoder.project_out提供逐层参数shared_layer_config按层类型后缀名如q_proj、k_proj、fc1提供共享参数。查找逻辑见 integrations/vptq.py优先取config_for_layers中该模块名的配置取不到则退回shared_layer_config中按模块名倒数第二段即module_name.rsplit(.)[1]匹配的共享配置。集成测试 test_vptq.py 给出了一个完整的逐层配置例子对facebook/opt-350m的q_proj/k_proj/v_proj/out_proj/fc1/fc2提供group_size128、num_centroids[-1, 128]、vector_lens[-1, 12]的共享配置再对project_out/project_in单独覆盖并用modules_to_not_convert排除lm_head与 24 层fc1最后断言替换前后线性层数量差符合预期——这同时演示了「按层类型共享」与「按模块名特例覆盖」两种粒度。VptqConfig 与 VptqLayerConfig 参数速查配置类定义在 quantization_config.pyVptqConfig顶层配置字段包括enable_proxy_error默认Falsepost_init强制其必须为False直到官方支持训练为止、config_for_layers、shared_layer_config、modules_to_not_convert并设置quant_method QuantizationMethod.VPTQVptqLayerConfig单个线性层的量化参数描述主要字段如下。参数默认值含义enable_normTrue是否为 FP 权重配 scale/bias归一化层enable_permTrue是否对输入通道做置换permute提升量化鲁棒性group_num1向量量化切分的组数group_size-1组大小取决于输出特征维度num_centroids[-1, -1]主码本聚类中心数例如[128, -1]形式按维度分别指定num_res_centroids[-1, -1]残差码本聚类中心数vector_lens[-1, -1]量化时每个聚类中心的向量长度outlier_size0离群值outlier处理数量indices_as_floatFalse索引是否以浮点形式保存微调场景使用is_indice_packedTrue索引是否打包存储post_init强制其必须为True简而言之num_centroids/num_res_centroids决定模型名里kxxxxx-yyyyy对应的位宽group_size/vector_lens决定向量量化把多少个连续权重作为一个向量去匹配码本enable_norm/enable_perm/outlier_size是量化质量与速度的调节旋钮。性能基准参考vptq.md 提供了 LLaMA-2 系列在不同位宽下的实验结果W2 与 C4 为困惑度指标↓ 越低越好AvgQA 为问答平均分↑ 越高越好tok/s 为吞吐、mem 为显存占用、cost/h 为量化耗时成本。文档同时说明该表仅作参考在合理参数下 VPTQ 可以获得更好的精度与推理速度模型bitwidthW2↓C4↓AvgQA↑tok/s↑mem(GB)cost/h↓LLaMA-2 7B2.026.138.0758.239.92.2822.265.957.8759.435.72.483.1LLaMA-2 13B2.025.327.1562.426.94.033.22.185.287.0463.118.54.313.6LLaMA-2 70B2.073.935.7268.69.719.54192.113.925.7168.79.720.0119可观察到的规律仅基于该表数据位宽越低显存占用越小、吞吐越高如 7B 从 2.26-bit 降到 2.02-bit 时 tok/s 由 35.7 提升到 39.9而困惑度随位宽增加有所改善。更详细的原理与算法细节可参考 VPTQ 论文arXiv 2409.17066及 VPTQ 官方提供的在线 Demo 与推理 Notebook。使用限制与注意事项基于文档与源码使用 VPTQ 集成前请留意以下几点仅支持 NVIDIA / AMD GPU 推理且必须有可用 CUDA 设备这是validate_environment的硬性检查纯 CPU 环境无法加载Transformers 只做加载不做量化requires_calibration True量化需要借助 VPTQ 官方算法工具链需要校准数据离线完成仓库内的集成代码不包含量化训练/校准流程不可训练is_trainable False、模块被强制关闭requires_grad并且enable_proxy_error被锁定为False直到官方支持训练为止所以请把它当作纯推理后端环境依赖需要accelerate、PyTorch CUDA 版与vptq0.0.4缺任一都会在加载前抛出明确异常需要社区预量化权重直接对一个普通未量化模型传入VptqConfig会报错——测试 test_vptq.py 的test_raise_if_non_quantized用facebook/opt-125m验证了这一行为。正确姿势是从VPTQ-community的量化仓库加载或用 VPTQ 工具链先把自有模型量化导出。参考阅读路径如需继续深入可在当前仓库中对照阅读以下文件量化文档本体vptq.md量化器实现quantizer_vptq.py换层逻辑replace_with_vptq_linearvptq.py配置类VptqConfig/VptqLayerConfigquantization_config.py量化器注册表auto.py集成测试加载、生成、保存、多卡、换层断言test_vptq.py【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考