DESCRIBED-PACKED-TENSOR 是在 Payload descriptor 中记录 shape 与 packed format,并以 packed 方式存储小于 WORD 的元素的张量 Value。Value VALUE-ISSUER-2WORD(0x09DL),Issuer 0x00000002 ADHOC,Codec 编号 0x00000601,系列 NUMERIC。
布局
TAG WORD 0000 1001 1101 LLLL Codec 0x09DL
[Length 扩展 TAG] 总计 15 WORD 以上时
Issuer 2 WORD 0x00000002 (ADHOC)
Codec 编号 2 WORD 0x00000601
Payload WORD 1st [version: 4bit][packed-format: 8bit][rank: 4bit]
Payload next [dimension 1: uint32, 2 WORD] ... [dimension rank: uint32, 2 WORD]
Payload 其余 [packed payload octet stream, low-bit-first]
解释
- rank 是 descriptor 的 4bit 值,所以结构上只能表示
0..15。每个 dimension 是非负的 big-endian uint32。逻辑顺序为 C-contiguous row-major。 - 如同 ONNX 的逻辑 tensor 规则,rank 0 的 shape
[]是只有 1 个元素的 scalar,只要有任一 dimension 为 0,元素数即为 0。除此之外元素数是所有 dimension 之积。 - packed-format 固定了 int2/int4、FP4/FP6、特定 FP8 variant 等元素的 encoding 与 bit 宽度。
- 将 payload octet sequence 记为
p[0], p[1], ...,并视为 little-bit-endian 整数P = Σ(p[j] << (8j)),则宽度为w的逻辑元素i为(P >> (i × w)) & ((1 << w) - 1)。即从第一个元素起放入最低位的 bit。 - 在 WORD 中,
p[0]作为第一个 WORD 的高位 octet,p[1]作为低位 octet,依此类推。最后一个已用 octet 中未使用的高位 tail bit 必须为 0,payload octet 数为奇数时,最后一个 WORD 中未使用的低位 octet 必须整体为00。
有效性
- 应用所支持 format 的 bit 宽度后,无 overflow 地计算出的 shape 的 dimension 之积必须与 payload 元素数相符。
- 所需 payload bit 之后的 high tail bit 或 octet padding 只要有一个为 1,即予以拒绝。descriptor、shape、payload 必须完整地容纳在记录 Length 之内。
标准依据与形式地位
- shape、rank 0 scalar、zero dimension 的逻辑含义遵循 ONNX IR Tensor Definition。将 sub-byte 元素从低位 bit 开始放置的规则,遵循官方 ONNX TensorProto schema 的 int2/int4 packing 与 DLPack
DLDataType的 little bit-endian packing。 - 4bit rank、uint32 dimension、version/packed-format field、将 octet 组成 big-endian WORD 的方式、GEUL TAG/Length 是 GEUL 特有的 descriptor。它们不是 ONNX、Apache Arrow tensor、DLPack 本身的 wire·memory serialization。
长度
- 总计是 TAG 1 WORD、Length 扩展 TAG(如有)、Issuer 2 WORD、Codec 编号 2 WORD、Payload 的 WORD 数之和。14 WORD 以下使用直接长度,15 WORD 以上使用
1110·1111扩展长度,扩展 TAG 也计入总数(记录与 TAG WORD)。 - descriptor 为 1 WORD,shape 为
2 × rankWORD,其余是 packed payload。 - 若逻辑元素数为
N、元素宽度为w,则 payload octet 数为ceil(N × w / 8),payload WORD 数为ceil(payload octet 数 / 2)。
示例
- 若是 rank 为 2 的 profile,则 descriptor 之后的 4 WORD 是 shape,其后是 low-bit-first 的 payload octet sequence。元素宽度与实际是否允许,由确定的 format profile 判断。
- 4bit 元素
[1, 2, 3]的 payload octet sequence 是21 03,payload WORD 是2103。第一个元素位于第一个 octet 的低 nibble,最后一个 octet 中未使用的高 nibble 为 0。
未决问题
- version 与 packed-format registry 的取值,以及在可表示的 rank
0..15中要支持的 profile 范围,尚未确定。