ONNX 4 位整数类型UINT4 / INT4完全指南低位量化、打包格式与算子支持【免费下载链接】onnxOpen standard for machine learning interoperability项目地址: https://gitcode.com/gh_mirrors/onn/onnx导读本文围绕 ONNX 标准中自onnx1.17.0引入的两种 4 位整数数据类型——UINT4无符号取值范围 [0, 15]与INT4有符号补码表示取值范围 [-8, 7]展开系统讲解它们在 LLM 权重量化weight-only quantization与激活量化场景中的设计动机、与 Cast 算子的转换规则、字节内打包/解包布局以及底层实现细节。读完本文你将掌握 4 位类型的取值范围与位布局、pack/unpack数学公式、ceil(N/2)存储大小的由来并能结合源码理解 ONNX 在 TensorProto、Checker、Python helper 与参考实现中的完整支持链路从而在自己的量化模型流程中正确构造与校验 4 位张量。为什么需要 4 位整数背景与动机低位整数在 LLM 压缩中的价值4 位整数的引入直接源于 2023 年大规模语言模型LLM的量化研究浪潮。虽然 4 位表示的数值范围非常有限但只要精心选择缩放参数scaling parameters就能在权重量化场景下获得很好的精度部分场景下甚至可以对激活值进行量化。ONNX 官方文档列举了三篇关键论文作为设计依据AWQActivation-aware Weight Quantization该工作观察到并非所有权重同等重要通过感知激活值来保护关键salient权重而非依赖反向传播或重建技术通过搜索最优的 per-channel 缩放来保留重要权重从而最小化量化误差。GPTQAccurate Post-Training Quantization for Generative Pre-trained Transformers提出基于近似二阶信息的一次性权重量化方法可将每个权重的位宽压缩到 3~4 位且相比未压缩基线精度损失可忽略不计。Understanding INT4 Quantization for Transformer Models系统研究了将权重与激活同时量化为 4 位即 W4A4的影响。结论是对 encoder-only 与 encoder-decoder 模型W4A4 几乎不带来精度损失但对 decoder-only 模型会造成显著精度下降。该研究还构建了高度优化的端到端 W4A4 encoder 推理流水线支持多种量化策略。正是基于这些背景ONNX 在onnx1.17.0中引入了两种 4 位整数类型用于支撑 4 位数据类型的模型压缩并配套了有限集合的算子支持。两种 4 位类型的精确定义类型全称表示方式取值范围UINT44 位无符号整数普通二进制[0, 15]INT44 位有符号整数二进制补码twos complement[-8, 7]在 protobuf 定义onnx/onnx.proto中两者的枚举值分别为UINT4 21与INT4 22注释明确写明了取值范围与补码表示约定UINT4 21; // Unsigned integer in range [0, 15] INT4 22; // Signed integer in range [-8, 7], using twos-complement representation与 Cast 算子的转换规则文档明确了 4 位类型与其他精度类型之间的转换语义从 4 位转换到任意更高精度类型是精确的exact例如UINT4 → UINT8/INT32/FLOAT、INT4 → INT8/FLOAT都不会引入误差因为高精度类型可以无损表示 4 位范围内的所有值。向 4 位类型的转换是取整 截断先按最近整数、平局取偶数round-to-nearest-integer, ties to even的规则舍入到最接近的整数再截断到 4 位范围。这也意味着超出 [0, 15] 或 [-8, 7] 范围的值会发生溢出环绕。源码佐证Cast 算子的测试覆盖ONNX 仓库的 Cast 算子测试onnx/backend/test/case/node/cast.py直接印证了这一规则测试中定义了FOUR_BIT_TYPES frozenset({UINT4, INT4, FLOAT4E2M1})并显式列出了与 4 位类型相关的合法转换组合包括FLOAT → UINT4、FLOAT16 → UINT4、FLOAT → INT4、FLOAT16 → INT4高精度向 4 位转换需要舍入与截断UINT4 → FLOAT、UINT4 → FLOAT16、UINT4 → UINT84 位向高精度转换精确无损失INT4 → FLOAT、INT4 → FLOAT16、INT4 → INT8。同时cast.py中还特别处理了from_type in (UINT4, INT4) or to_type in (UINT4, INT4)的情况cast.py用于构造合法的 4 位转换测试数据。castlike.py测试同样覆盖了这些类型组合。打包与解包Packing and Unpacking核心字节布局基本规则所有 4 位类型都以2×4bit 打包进 1 个字节的方式存储第一个元素存放在字节的低 4 位4 LSB第二个元素存放在字节的高 4 位4 MSB。假设数组中连续的两个元素为x、y则pack(x, y): y 4 | x 0x0F unpack(z): x z 0x0F, y z 4这里x 0x0F的含义是把x截断/掩码到低 4 位等价于x % 16避免越界位污染相邻元素y 4把y移入高 4 位。奇数元素与填充当 4 位张量的总元素个数N为奇数时最后一个字节的高 4 位会追加 4 位填充padding。因此存储大小为ceil(N/2)字节例如N5时占用ceil(5/2)3字节第 1、2 字节完整存储 4 个元素第 3 字节低 4 位存第 5 个元素高 4 位为填充位。源码佐证Python 侧打包实现onnx/numpy_helper.py中的_pack_4bitx2onnx/numpy_helper.py是文档公式的精确 Python 实现def _pack_4bitx2(array: np.ndarray) - npt.NDArray[np.uint8]: Convert a numpy array to flatten, packed int4/uint4. Elements must be in the correct range. # Create a 1D copy array_flat array.ravel().view(np.uint8).copy() size array.size odd_sized size % 2 1 if odd_sized: array_flat.resize([size 1], refcheckFalse) array_flat 0x0F array_flat[1::2] 4 return array_flat[0::2] | array_flat[1::2]逐行解读将输入展平为 1D 数组并视为uint8视图若元素个数为奇数odd_sized扩展一个元素位以容纳填充array_flat 0x0F对每个元素掩码到低 4 位对应公式中的x 0x0Farray_flat[1::2] 4把偶数索引第 2、4、6…个元素左移 4 位对应y 4array_flat[0::2] | array_flat[1::2]将相邻奇偶元素按位或合并得到 2 元素/字节的打包结果。与此对称helper.py的make_tensoronnx/helper.py在构造 4 位原始张量时会先计算expected_size_bytes ceil(prod(dims) * 4 / 8)并调用numpy_helper._pack_4bitx2(vals)完成打包后再写入raw_data非 raw 模式下onnx/helper.py同样先_pack_4bitx2再填充int32_data等字段。源码佐证Checker 的存储大小校验onnx/checker.cc在模型校验阶段对 4 位类型的raw_data长度做了严格检查onnx/checker.cccase TensorProto::UINT4: case TensorProto::INT4: case TensorProto::FLOAT4E2M1: expected_bytes (nelem 1) / 2; // 2 elements per byte, ceiling division break;这里(nelem 1) / 2正是ceil(N/2)的整数实现当N为偶数时等于N/2当N为奇数时(N1)/2向上取整。若raw_data的字节数与形状推算出的期望字节数不符校验会直接失败从而在模型加载早期拦截错误的 4 位张量。与 2 位类型的对比延伸参考仓库内同系列的 2 位整数文档docs/docsgen/source/technical/int2.md展示了更极致的低位压缩2 位类型以 4×2bit 打包进 1 个字节元素按 LSB→MSB 依次存放存储大小为ceil(N/4)字节。4 位与 2 位打包的差异LSB/MSB 拆分 vs. 顺序铺满说明不同低位类型在 ONNX 中的位布局约定并不完全一致使用时务必以各类型对应的官方定义为准。Python 侧的类型映射在 Python API 中4 位类型通过ml_dtypes库提供对应的 NumPy dtype。onnx/_mapping.pyonnx/_mapping.py中的映射定义如下int(TensorProto.UINT4): TensorDtypeMap( np.dtype(ml_dtypes.uint4), int(TensorProto.INT32), TensorProto.UINT4 ), int(TensorProto.INT4): TensorDtypeMap( np.dtype(ml_dtypes.int4), int(TensorProto.INT32), TensorProto.INT4 ),可以看到TensorProto.UINT4映射为ml_dtypes.uint4TensorProto.INT4映射为ml_dtypes.int4两者都以INT32作为落盘字段即序列化时值存放在int32_data中由于 NumPy 原生没有 4 位 dtype打包表示由numpy_helper._pack_4bitx2以uint8缓冲完成这一点在 onnx/helper.py 的注释中有明确说明NumPy doesnt have INT2/INT4/FP4/FP6. It is packed in couples to UINT8 buffers.支持的算子与使用场景有限算子集合如文档所述4 位类型最初支持有限集合的算子以启用压缩。从仓库证据看UINT4/INT4出现的算子相关文件包括Cast / CastLike类型转换onnx/backend/test/case/node/cast.py、onnx/backend/test/case/node/castlike.pyQuantizeLinear / DequantizeLinear线性量化与反量化onnx/backend/test/case/node/quantizelinear.py、onnx/backend/test/case/node/dequantizelinear.py参考实现见 onnx/reference/ops/op_quantize_linear.py底层 schema 注册与类型约束位于 onnx/defs/tensor/defs.cc类型工具函数位于 onnx/defs/data_type_utils.cc。这符合低位量化模型的典型工作流权重以 4 位打包存储 → DequantizeLinear 反量化为高精度 → 参与常规计算或在推理时由支持 4 位的后端直接消费。典型落地流程结合代码推断结合helper.make_tensor与 checker 校验逻辑一个 4 位权重张量的构造与加载链路可以概括为使用ml_dtypes.uint4/int4生成 NumPy 数组或直接提供合法范围内的 Python 值列表调用onnx.helper.make_tensor(name, TensorProto.INT4/UINT4, dims, vals)内部自动完成_pack_4bitx2打包模型保存后任何读取方如 ONNX Runtime在校验阶段由checker.cc依据ceil(N/2)校验raw_data长度确保字节布局正确运行时通过 Cast / DequantizeLinear 还原为高精度数值参与计算。需要说明的是这一步流程属于从代码结构推导的通用用法具体后端如 ONNX Runtime对 4 位算子的支持程度与执行路径不在本仓库范围内。小结主题关键结论引入版本onnx1.17.0类型与范围UINT4[0, 15]INT4补码 [-8, 7]转换规则4 位 → 高精度精确高精度 → 4 位为最近偶数舍入 截断打包布局低 4 位存第 1 个元素高 4 位存第 2 个元素pack: y4 \| x0x0F存储大小ceil(N/2)字节奇数元素补 4 位填充主要算子Cast / CastLike、QuantizeLinear / DequantizeLinear4 位整数类型是 ONNX 支撑 LLM 低位量化生态的基础设施。理解其补码取值约定、字节打包布局与存储大小公式是正确构造、校验和跨框架交换量化模型的前提。如需进一步了解同系列更低位宽的表示可继续阅读仓库内的 2 位整数类型文档docs/docsgen/source/technical/int2.md与 float4 文档docs/docsgen/source/technical/float4.md。【免费下载链接】onnxOpen standard for machine learning interoperability项目地址: https://gitcode.com/gh_mirrors/onn/onnx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ONNX 4 位整数类型（UINT4 / INT4）完全指南：低位量化、打包格式与算子支持
ONNX 4 位整数类型UINT4 / INT4完全指南低位量化、打包格式与算子支持【免费下载链接】onnxOpen standard for machine learning interoperability项目地址: https://gitcode.com/gh_mirrors/onn/onnx导读本文围绕 ONNX 标准中自onnx1.17.0引入的两种 4 位整数数据类型——UINT4无符号取值范围 [0, 15]与INT4有符号补码表示取值范围 [-8, 7]展开系统讲解它们在 LLM 权重量化weight-only quantization与激活量化场景中的设计动机、与 Cast 算子的转换规则、字节内打包/解包布局以及底层实现细节。读完本文你将掌握 4 位类型的取值范围与位布局、pack/unpack数学公式、ceil(N/2)存储大小的由来并能结合源码理解 ONNX 在 TensorProto、Checker、Python helper 与参考实现中的完整支持链路从而在自己的量化模型流程中正确构造与校验 4 位张量。为什么需要 4 位整数背景与动机低位整数在 LLM 压缩中的价值4 位整数的引入直接源于 2023 年大规模语言模型LLM的量化研究浪潮。虽然 4 位表示的数值范围非常有限但只要精心选择缩放参数scaling parameters就能在权重量化场景下获得很好的精度部分场景下甚至可以对激活值进行量化。ONNX 官方文档列举了三篇关键论文作为设计依据AWQActivation-aware Weight Quantization该工作观察到并非所有权重同等重要通过感知激活值来保护关键salient权重而非依赖反向传播或重建技术通过搜索最优的 per-channel 缩放来保留重要权重从而最小化量化误差。GPTQAccurate Post-Training Quantization for Generative Pre-trained Transformers提出基于近似二阶信息的一次性权重量化方法可将每个权重的位宽压缩到 3~4 位且相比未压缩基线精度损失可忽略不计。Understanding INT4 Quantization for Transformer Models系统研究了将权重与激活同时量化为 4 位即 W4A4的影响。结论是对 encoder-only 与 encoder-decoder 模型W4A4 几乎不带来精度损失但对 decoder-only 模型会造成显著精度下降。该研究还构建了高度优化的端到端 W4A4 encoder 推理流水线支持多种量化策略。正是基于这些背景ONNX 在onnx1.17.0中引入了两种 4 位整数类型用于支撑 4 位数据类型的模型压缩并配套了有限集合的算子支持。两种 4 位类型的精确定义类型全称表示方式取值范围UINT44 位无符号整数普通二进制[0, 15]INT44 位有符号整数二进制补码twos complement[-8, 7]在 protobuf 定义onnx/onnx.proto中两者的枚举值分别为UINT4 21与INT4 22注释明确写明了取值范围与补码表示约定UINT4 21; // Unsigned integer in range [0, 15] INT4 22; // Signed integer in range [-8, 7], using twos-complement representation与 Cast 算子的转换规则文档明确了 4 位类型与其他精度类型之间的转换语义从 4 位转换到任意更高精度类型是精确的exact例如UINT4 → UINT8/INT32/FLOAT、INT4 → INT8/FLOAT都不会引入误差因为高精度类型可以无损表示 4 位范围内的所有值。向 4 位类型的转换是取整 截断先按最近整数、平局取偶数round-to-nearest-integer, ties to even的规则舍入到最接近的整数再截断到 4 位范围。这也意味着超出 [0, 15] 或 [-8, 7] 范围的值会发生溢出环绕。源码佐证Cast 算子的测试覆盖ONNX 仓库的 Cast 算子测试onnx/backend/test/case/node/cast.py直接印证了这一规则测试中定义了FOUR_BIT_TYPES frozenset({UINT4, INT4, FLOAT4E2M1})并显式列出了与 4 位类型相关的合法转换组合包括FLOAT → UINT4、FLOAT16 → UINT4、FLOAT → INT4、FLOAT16 → INT4高精度向 4 位转换需要舍入与截断UINT4 → FLOAT、UINT4 → FLOAT16、UINT4 → UINT84 位向高精度转换精确无损失INT4 → FLOAT、INT4 → FLOAT16、INT4 → INT8。同时cast.py中还特别处理了from_type in (UINT4, INT4) or to_type in (UINT4, INT4)的情况cast.py用于构造合法的 4 位转换测试数据。castlike.py测试同样覆盖了这些类型组合。打包与解包Packing and Unpacking核心字节布局基本规则所有 4 位类型都以2×4bit 打包进 1 个字节的方式存储第一个元素存放在字节的低 4 位4 LSB第二个元素存放在字节的高 4 位4 MSB。假设数组中连续的两个元素为x、y则pack(x, y): y 4 | x 0x0F unpack(z): x z 0x0F, y z 4这里x 0x0F的含义是把x截断/掩码到低 4 位等价于x % 16避免越界位污染相邻元素y 4把y移入高 4 位。奇数元素与填充当 4 位张量的总元素个数N为奇数时最后一个字节的高 4 位会追加 4 位填充padding。因此存储大小为ceil(N/2)字节例如N5时占用ceil(5/2)3字节第 1、2 字节完整存储 4 个元素第 3 字节低 4 位存第 5 个元素高 4 位为填充位。源码佐证Python 侧打包实现onnx/numpy_helper.py中的_pack_4bitx2onnx/numpy_helper.py是文档公式的精确 Python 实现def _pack_4bitx2(array: np.ndarray) - npt.NDArray[np.uint8]: Convert a numpy array to flatten, packed int4/uint4. Elements must be in the correct range. # Create a 1D copy array_flat array.ravel().view(np.uint8).copy() size array.size odd_sized size % 2 1 if odd_sized: array_flat.resize([size 1], refcheckFalse) array_flat 0x0F array_flat[1::2] 4 return array_flat[0::2] | array_flat[1::2]逐行解读将输入展平为 1D 数组并视为uint8视图若元素个数为奇数odd_sized扩展一个元素位以容纳填充array_flat 0x0F对每个元素掩码到低 4 位对应公式中的x 0x0Farray_flat[1::2] 4把偶数索引第 2、4、6…个元素左移 4 位对应y 4array_flat[0::2] | array_flat[1::2]将相邻奇偶元素按位或合并得到 2 元素/字节的打包结果。与此对称helper.py的make_tensoronnx/helper.py在构造 4 位原始张量时会先计算expected_size_bytes ceil(prod(dims) * 4 / 8)并调用numpy_helper._pack_4bitx2(vals)完成打包后再写入raw_data非 raw 模式下onnx/helper.py同样先_pack_4bitx2再填充int32_data等字段。源码佐证Checker 的存储大小校验onnx/checker.cc在模型校验阶段对 4 位类型的raw_data长度做了严格检查onnx/checker.cccase TensorProto::UINT4: case TensorProto::INT4: case TensorProto::FLOAT4E2M1: expected_bytes (nelem 1) / 2; // 2 elements per byte, ceiling division break;这里(nelem 1) / 2正是ceil(N/2)的整数实现当N为偶数时等于N/2当N为奇数时(N1)/2向上取整。若raw_data的字节数与形状推算出的期望字节数不符校验会直接失败从而在模型加载早期拦截错误的 4 位张量。与 2 位类型的对比延伸参考仓库内同系列的 2 位整数文档docs/docsgen/source/technical/int2.md展示了更极致的低位压缩2 位类型以 4×2bit 打包进 1 个字节元素按 LSB→MSB 依次存放存储大小为ceil(N/4)字节。4 位与 2 位打包的差异LSB/MSB 拆分 vs. 顺序铺满说明不同低位类型在 ONNX 中的位布局约定并不完全一致使用时务必以各类型对应的官方定义为准。Python 侧的类型映射在 Python API 中4 位类型通过ml_dtypes库提供对应的 NumPy dtype。onnx/_mapping.pyonnx/_mapping.py中的映射定义如下int(TensorProto.UINT4): TensorDtypeMap( np.dtype(ml_dtypes.uint4), int(TensorProto.INT32), TensorProto.UINT4 ), int(TensorProto.INT4): TensorDtypeMap( np.dtype(ml_dtypes.int4), int(TensorProto.INT32), TensorProto.INT4 ),可以看到TensorProto.UINT4映射为ml_dtypes.uint4TensorProto.INT4映射为ml_dtypes.int4两者都以INT32作为落盘字段即序列化时值存放在int32_data中由于 NumPy 原生没有 4 位 dtype打包表示由numpy_helper._pack_4bitx2以uint8缓冲完成这一点在 onnx/helper.py 的注释中有明确说明NumPy doesnt have INT2/INT4/FP4/FP6. It is packed in couples to UINT8 buffers.支持的算子与使用场景有限算子集合如文档所述4 位类型最初支持有限集合的算子以启用压缩。从仓库证据看UINT4/INT4出现的算子相关文件包括Cast / CastLike类型转换onnx/backend/test/case/node/cast.py、onnx/backend/test/case/node/castlike.pyQuantizeLinear / DequantizeLinear线性量化与反量化onnx/backend/test/case/node/quantizelinear.py、onnx/backend/test/case/node/dequantizelinear.py参考实现见 onnx/reference/ops/op_quantize_linear.py底层 schema 注册与类型约束位于 onnx/defs/tensor/defs.cc类型工具函数位于 onnx/defs/data_type_utils.cc。这符合低位量化模型的典型工作流权重以 4 位打包存储 → DequantizeLinear 反量化为高精度 → 参与常规计算或在推理时由支持 4 位的后端直接消费。典型落地流程结合代码推断结合helper.make_tensor与 checker 校验逻辑一个 4 位权重张量的构造与加载链路可以概括为使用ml_dtypes.uint4/int4生成 NumPy 数组或直接提供合法范围内的 Python 值列表调用onnx.helper.make_tensor(name, TensorProto.INT4/UINT4, dims, vals)内部自动完成_pack_4bitx2打包模型保存后任何读取方如 ONNX Runtime在校验阶段由checker.cc依据ceil(N/2)校验raw_data长度确保字节布局正确运行时通过 Cast / DequantizeLinear 还原为高精度数值参与计算。需要说明的是这一步流程属于从代码结构推导的通用用法具体后端如 ONNX Runtime对 4 位算子的支持程度与执行路径不在本仓库范围内。小结主题关键结论引入版本onnx1.17.0类型与范围UINT4[0, 15]INT4补码 [-8, 7]转换规则4 位 → 高精度精确高精度 → 4 位为最近偶数舍入 截断打包布局低 4 位存第 1 个元素高 4 位存第 2 个元素pack: y4 \| x0x0F存储大小ceil(N/2)字节奇数元素补 4 位填充主要算子Cast / CastLike、QuantizeLinear / DequantizeLinear4 位整数类型是 ONNX 支撑 LLM 低位量化生态的基础设施。理解其补码取值约定、字节打包布局与存储大小公式是正确构造、校验和跨框架交换量化模型的前提。如需进一步了解同系列更低位宽的表示可继续阅读仓库内的 2 位整数类型文档docs/docsgen/source/technical/int2.md与 float4 文档docs/docsgen/source/technical/float4.md。【免费下载链接】onnxOpen standard for machine learning interoperability项目地址: https://gitcode.com/gh_mirrors/onn/onnx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考