Apache Arrow 格式规范中的 Tensor 与 SparseTensor：多维数组与稀疏张量的 IPC 数据交换设计

Apache Arrow 格式规范中的 Tensor 与 SparseTensor多维数组与稀疏张量的 IPC 数据交换设计【免费下载链接】arrowApache Arrow is a multi-language toolbox for accelerated data interchange and in-memory processing项目地址: https://gitcode.com/gh_mirrors/arrow12/arrow导读Apache Arrow 的列式格式Columnar Format解决了表格型数据的零拷贝交换问题但并非所有应用场景都适合用列来表达数据。本文聚焦于 Apache Arrow 格式规范中的其他数据结构Other Data Structures——Tensor多维稠密数组类似 NumPy ndarray与SparseTensor稀疏张量讲解它们的 FlatBuffers 协议定义、独立封装的 IPC 消息布局、64 字节对齐规则并结合 C 实现源码说明其内存模型与序列化机制。读完本文你将掌握如何为多维数组和稀疏张量场景复用 Arrow 的进程间通信IPC机制以及 Arrow 各语言实现中这些类型的实际落地方式。定位不属于列式格式的可选数据结构在 docs/source/format/Other.rst 中Apache Arrow 明确声明Tensor与SparseTensor这两类数据结构的元数据定义在 FlatBuffers 协议定义文件中目的是让其他类型的应用也能利用通用的进程间通信机制但它们不被视为列式格式Columnar Format的一部分。由此带来两个重要推论一个 Arrow 列式实现不要求必须实现这些类型二者的完整格式基准是 format/Schema.fbs、format/Tensor.fbs、format/SparseTensor.fbs 这些协议定义文件而列式格式的规范正文则见 docs/source/format/Columnar.rst。从 format/Message.fbs 的MessageHeader联合类型可以看到Arrow 的 IPC 消息头允许承载五种负载union MessageHeader { Schema, DictionaryBatch, RecordBatch, Tensor, SparseTensor }其中RecordBatch是兼容性最好的主流通用类型而Tensor/SparseTensor被官方标注为 EXPERIMENTAL实验性元数据类型实现方可以按需取舍。Tensor固定大小值的多维稠密数组Tensor用于描述固定大小值类型的多维数组如 NumPy 的 ndarray。其 FlatBuffers 定义位于 format/Tensor.fbs核心结构如下table TensorDim { size: long; // 该维度的长度 name: string; // 维度名称可选 } table Tensor { type: Type (required); // 值类型仅支持定宽类型 shape: [TensorDim] (required); // 各维度信息可命名 strides: [long]; // 每个维度前进一个单元所需的字节偏移 data: Buffer (required); // 数据缓冲区的位置与大小 }关键字段语义type值单元的数据类型。官方注释明确目前仅支持定宽值类型不支持字符串或嵌套类型Currently only fixed-width value types are supported, no strings or nested types这与列式格式中丰富的数据类型体系形成对照。shape维度描述列表每个TensorDim携带该维长度与可选的维度名。例如一个 4x5 的矩阵拥有两个维度项。strides沿着每个维度推进一个值单元所需跨越的字节数必须非负。若省略该字段默认按行主序row-majorC 语言风格解释数据。这是 Arrow 实现中判定连续性contiguity的关键输入。data一个Buffer指向张量实际数据所在的内存区域。与 NumPy ndarray 的对应关系从源码结构看该消息类型的设计目标就是与 NumPy ndarray 这类带 shape/strides 的连续内存视图对齐Tensor的shapestridesdata三件套恰好对应 ndarray 的shape/strides/data概念这也是文档中such as a NumPy ndarray的直接含义。C 实现印证在 C 实现中cpp/src/arrow/tensor.h 的Tensor类完整复刻了这一模型工厂方法Tensor::Make(type, data, shape, strides, dim_names)会先执行ValidateTensorParameters参数一致性校验参数不一致时返回Status::Invalid构造时strides为空向量表示数据按行主序排布if this is empty, the data assumed to be row-majoris_contiguous()、is_row_major()C 序、is_column_major()Fortran 序提供排布判断CalculateValueOffset(strides, index)按offset index[i] * strides[i]计算任意索引的字节偏移与消息定义中的 strides 语义完全一致CountNonZero()用于统计非零元素个数为稀疏化转换做准备。SparseTensor元素几乎全为零的多维数组SparseTensor描述绝大多数元素为零的多维数组其定义位于 format/SparseTensor.fbs在Tensor的基础上增加了一个稀疏索引sparse indextable SparseTensor { type: Type (required); // 值类型仅支持定宽类型 shape: [TensorDim] (required); // 各维度信息 non_zero_length: long; // 非零元素个数 sparseIndex: SparseTensorIndex (required); // 稀疏索引联合类型 data: Buffer (required); // 非零值数据缓冲区 } union SparseTensorIndex { SparseTensorIndexCOO, // 坐标格式 SparseMatrixIndexCSX, // 压缩稀疏矩阵格式行/列 SparseTensorIndexCSF // 压缩稀疏纤维格式 }sparseIndex是一个联合类型具体内容取决于使用哪种稀疏格式。协议文件为三种格式提供了非常详尽的注释与数值示例以下逐一说明。坐标格式SparseTensorIndexCOOCOOCoordinate格式将稀疏张量表示为一个N×M 的索引矩阵其中 N 是非零值个数、M 是张量维数table SparseTensorIndexCOO { indicesType: Int (required); // 索引矩阵中值的类型 indicesStrides: [long]; // 索引矩阵各维的字节步长省略则按行主序 indicesBuffer: Buffer (required); // 索引矩阵数据区 isCanonical: bool; // 是否已按行主序排序且无重复项 }协议文件中的示例设 X 是 2x3x4x5 张量含 6 个非零值X[0, 1, 2, 0] : 1 X[1, 1, 2, 3] : 2 X[0, 2, 1, 0] : 3 X[0, 1, 3, 0] : 4 X[0, 1, 2, 1] : 5 X[1, 2, 0, 4] : 6则其索引矩阵为 4×6[[0, 0, 0, 0, 1, 1], [1, 1, 1, 2, 1, 2], [2, 2, 3, 1, 2, 0], [0, 1, 0, 0, 3, 4]]isCanonical语义值得注意当为true时索引矩阵按字典序行主序排序且无重复项协议文件还特别指出这种排序与 TensorFlow 的 SparseTensor 一致但与 SciPycoo_matrix的列主序规范相反SciPy employs column-major order for its coo_matrix。压缩稀疏矩阵格式SparseMatrixIndexCSXCSX 是矩阵专属的压缩稀疏格式通过SparseMatrixCompressedAxis枚举Row/Column选择压缩行还是列对应经典的 CSR / CSC 表示enum SparseMatrixCompressedAxis: short { Row, Column } table SparseMatrixIndexCSX { compressedAxis: SparseMatrixCompressedAxis; // 压缩的轴 indptrType: Int (required); // indptr 数组中值的类型 indptrBuffer: Buffer (required); // 行/列指针数组 indicesType: Int (required); // 索引数组中值的类型 indicesBuffer: Buffer (required); // 列/行索引数组 }协议文件给出的示例矩阵6×4X : [[0, 1, 2, 0], [0, 0, 3, 0], [0, 4, 0, 5], [0, 0, 0, 0], [6, 0, 7, 8], [0, 9, 0, 0]]按行压缩CSR时values(X) [1, 2, 3, 4, 5, 6, 7, 8, 9] indptr(X) [0, 2, 3, 5, 5, 8, 10] indices(X) [1, 2, 2, 1, 3, 0, 2, 3, 1]语义约定第 i 行在数据区中跨越indptr[i]到indptr[i1]indptr数组长度为行数 1且每一行的列索引按字典序排序。全零行如第 4 行通过indptr中连续相等的取值自然表达示例中indptr[3]indptr[4]5。压缩稀疏纤维格式SparseTensorIndexCSFCSFCompressed Sparse Fiber是 CSR 索引的高维推广递归地将张量的每个维度压缩成一组前缀树prefix trees每条从根到叶的路径构成一个非零索引。协议注释引用了 Smith 等人的 KNL 论文作为设计背景table SparseTensorIndexCSF { indptrType: Int (required); indptrBuffers: [Buffer] (required); // 每两个相邻维度对应一个 buffer indicesType: Int (required); indicesBuffers: [Buffer] (required); // 每个张量维度对应一个 buffer axisOrder: [int] (required); // 生成前缀树时的维度遍历顺序 }协议示例设 X 是 2x3x4x5 张量含 8 个非零值其前缀树结构如下0 1 / \ | 0 1 1 / / \ | 0 0 1 1 /| /| | /| | 1 2 0 2 0 0 1 2对应的三段缓冲区indptrBuffers(X) [[0, 2, 3], [0, 1, 3, 4], [0, 2, 4, 5, 8]] indicesBuffers(X) [[0, 1], [0, 1, 1], [0, 0, 1, 1], [1, 2, 0, 2, 0, 0, 1, 2]] axisOrder(X) [0, 1, 2, 3]indptrBuffers[dim][i]与indptrBuffers[dim][i1]之间的取值区间标示了indicesBuffers[dim1]中哪些节点是indicesBuffers[dim][i]的子节点。C 实现印证C 侧 cpp/src/arrow/sparse_tensor.h 提供了SparseTensor基类及SparseTensorCOO、SparseTensorCSR、SparseTensorCSC、SparseTensorCSF等派生容器序列化/反序列化路径位于 cpp/src/arrow/ipc/metadata_internal.cc其中MakeSparseTensorIndexCOO、MakeSparseTensorIndexCSX、MakeSparseTensorIndexCSF三个函数分别把内存中的稀疏索引对象转换为 FlatBuffers 对应的SparseTensorIndex分支与 format/SparseTensor.fbs 的联合类型逐一对应。测试用例见 cpp/src/arrow/sparse_tensor_test.ccIPC 读写测试与模糊语料生成器cpp/src/arrow/ipc/generate_tensor_fuzz_corpus.cc内部调用ipc::WriteTensor则验证了 Tensor/SparseTensor 消息的实际编解码流程。独立封装的 IPC 消息与 64 字节对齐规则Tensor与SparseTensor可以像RecordBatch一样承载在封装式 IPC 消息encapsulated IPC message中传输。该封装格式定义于 docs/source/format/Columnar.rst 的 Encapsulated message format 一节标准布局为continuation: 0xFFFFFFFF metadata_size: int32 metadata_flatbuffer: bytes padding message body32 位连续指示符0xFFFFFFFF标识合法消息自 0.15.0 起引入用于应对 FlatBuffers 的 8 字节对齐要求32 位小端长度前缀标识元数据大小消息体长度必须是 8 的倍数整个序列化消息必须是 8 的倍数。Tensor 的附加对齐要求Other.rst规定写入独立封装standalone encapsulated的 Tensor 消息时在列式规范封装格式的基础上额外要求 tensor body 的起始偏移是 64 的倍数metadata prefix and metadata PADDING tensor body即需要在元数据之后、张量数据体之前插入额外填充使数据体起点对齐到 64 字节。SparseTensor 的附加对齐要求Other.rst对 SparseTensor 的要求更进一步当写入独立封装消息时若目标是共享内存区域稀疏索引sparse index和稀疏张量数据体sparse tensor body的起始偏移都必须对齐到 64 字节的倍数metadata prefix and metadata PADDING sparse index PADDING sparse tensor body即稀疏索引与数据体之间也需要填充对齐。为什么是 64 字节Columnar 规范中的 Buffer Alignment and Padding 一节解释了背景实现被建议在 8 字节或 64 字节边界上对齐分配内存并填充到 8/64 的倍数。64 字节对齐的推荐源于 Intel 性能指南——对齐到 SIMD 寄存器宽度具体来说与主流 x86 架构上最大的 SIMD 指令寄存器AVX-512512 位 64 字节一致从而允许循环内无附加条件检查地使用 SIMD 指令一次将 64 字节载入 512 位寄存器获得数据级并行且填充字节无需特定值。可以推断Tensor/SparseTensor 的 64 字节对齐正是为了在多维数组的高性能数值计算场景中最大化向量化收益。与列式格式的关系和扩展类型参考Tensor/SparseTensor虽然不属于列式格式但 Arrow 社区还提供了一条把张量放进表格的路径在 docs/source/format/CanonicalExtensions.rst 的扩展类型讨论中tensor多维数组可作为Binary类型的扩展类型存储——每个单元格存一个张量并在扩展元数据中记录类型与形状如 JSON 形式的{type: int8, shape: [4, 5]}表示一个 4x5 的 int8 张量。这与 format/Message.fbs 中custom_metadata的设计相呼应扩展类型可借助ARROW:extension:metadata传递语义信息让列式表格也能承载结构化张量数据同时保持标准实现无需了解具体扩展即可搬运数据。小结Tensor与SparseTensor是 Arrow 格式中可选、实验性的数据结构用于让多维数组如 NumPy ndarray和稀疏张量应用复用 Arrow 的 IPC 机制而非列式格式的组成部分二者均复用封装式 IPC 消息格式但要求数据体Tensor或稀疏索引 数据体SparseTensor起始偏移对齐到 64 字节以匹配 AVX-512 等 SIMD 寄存器的访存宽度协议元数据全部由 FlatBuffers 定义权威文件为 format/Tensor.fbs 与 format/SparseTensor.fbsSparseTensor通过联合类型支持 COO、CSR/CSCCSX与 CSF 三种索引格式C 实现cpp/src/arrow/tensor.h、cpp/src/arrow/sparse_tensor.h与 IPC 序列化cpp/src/arrow/ipc/metadata_internal.cc严格遵循协议定义可作为理解该格式或实现其他语言绑定的参考。若需进一步研究建议通读 docs/source/format/Columnar.rst封装消息与对齐规则的权威出处以及 format/Message.fbsMessage 根类型与MessageHeader联合。【免费下载链接】arrowApache Arrow is a multi-language toolbox for accelerated data interchange and in-memory processing项目地址: https://gitcode.com/gh_mirrors/arrow12/arrow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考