3、张量基础：张量的概念、形状、数据类型、内存布局（NCHW/NHWC）及与NumPy的对应关系

在ONNX Runtime的推理链路中，张量（Tensor）是所有数据交换的通用语言。无论是输入图片、文本特征，还是模型输出的分类概率、检测框坐标，最终都以张量的形式在内存中排列。理解张量的本质，不仅是为了读懂API文档，更是为了在模型部署时正确预处理数据、解读输出结果，并规避因维度顺序或数据类型不匹配而引发的隐性错误。本章将从张量的核心属性出发，深入剖析形状、数据类型与内存布局，并建立与NumPy数组的对应关系，为后续的输入输出处理打下坚实基础。

张量核心属性与内存布局映射关系 张量 Tensor 多维数组 + 数据类型 形状 Shape 维度顺序与长度 如 [1,3,224,224] 数据类型 Dtype float32 / int64 / uint8 精度与内存占用 内存布局 Layout NCHW / NHWC 通道与空间维顺序 步长 Strides 每个维度跨越的字节数 决定内存访问效率 NumPy 对应关系 np.ndarray ↔ onnxruntime.Tensor · 共享内存 · 零拷贝转换

3.1 张量的核心概念与本质

张量是ONNX Runtime中数据的基本载体，可以理解为带数据类型和维度信息的多维数组。在数学上，标量是0阶张量，向量是1阶张量，矩阵是2阶张量，而深度学习中的图像、视频、序列数据则对应3阶及以上的高阶张量。在ONNX Runtime的C++接口中，张量由 Ort::Value 封装；在Python接口中，则通过 onnxruntime.OrtValue 或直接使用NumPy数组进行交互。

理解张量需要抓住四个核心属性：形状（Shape）、数据类型（Data Type）、内存布局（Memory Layout）和步长（Strides）。形状定义了每个维度的大小，数据类型决定了每个元素占用的字节数及解释方式，内存布局规定了多维索引到一维内存地址的映射规则，而步长则是这种映射的具体数值表达。在ONNX Runtime中，张量默认是连续内存的，即行优先（C风格）存储，这与NumPy的默认行为一致。

3.2 形状（Shape）：维度顺序的语义

形状是张量最直观的属性，通常用一个整数列表表示。在ONNX Runtime中，输入输出的形状信息通过 get_shape() 方法获取。对于视觉模型，最常见的形状格式为 [N, C, H, W] 或 [N, H, W, C] ，其中N代表批量大小（Batch Size），C代表通道数（Channel），H代表高度（Height），W代表宽度（Width）。

判断形状是否正确，需要结合模型的输入要求。ONNX Runtime在 run() 调用时会进行严格的形状校验，如果输入形状与模型定义的输入形状不匹配，会抛出类似 Unexpected input data type. Actual: (tensor(float)) , expected: (tensor(double)) 或形状不匹配的错误。因此，在预处理阶段，必须明确模型期望的维度顺序。

模型类型 常见输入形状 维度含义 典型数据源
图像分类 (ResNet) [1, 3, 224, 224] 1张图，RGB三通道，高224，宽224 解码后的图片像素
目标检测 (YOLOv5) [1, 3, 640, 640] 1张图，RGB三通道，高640，宽640 缩放/填充后的图像
文本分类 (BERT) [1, 128] 1个样本，序列长度128 Token ID序列
语音识别 (RNN) [1, 200, 80] 1个样本，200帧，80维特征 梅尔频谱特征
经验提醒：在ONNX Runtime中，动态轴（Dynamic Axis）允许输入形状在推理时变化。例如， [None, 3, 224, 224] 表示批量维度可变。但静态形状（Static Shape）的模型在优化和内存分配上更高效。如果模型支持动态形状，务必在 session_options 中设置 optimized_model_filepath 以缓存优化后的模型，避免每次推理都重新优化。

3.3 数据类型（Dtype）：精度与内存的权衡

数据类型决定了张量中每个元素的存储格式和取值范围。ONNX Runtime支持多种数据类型，包括 float32 、 float64 、 int8 、 int16 、 int32 、 int64 、 uint8 、 bool 等。在Python接口中，ONNX Runtime与NumPy的数据类型一一对应： np.float32 对应 tensor(float) ， np.int64 对应 tensor(int64) ， np.uint8 对应 tensor(uint8) 。

选择合适的数据类型至关重要。对于深度学习推理， float32 是默认精度，但 float16 （半精度）在支持FP16加速的GPU上可以显著提升吞吐量。ONNX Runtime提供了 ORT_ENABLE_FP16 等图优化选项，但需要确保模型中的算子支持FP16计算。对于分类标签或索引等整数数据，使用 int64 是标准做法，因为ONNX的 ArgMax 等算子输出默认就是 int64 。

import numpy as np
import onnxruntime as ort

# 创建ONNX Runtime输入张量（推荐直接使用NumPy数组）
input_data = np.random.randn(1, 3, 224, 224).astype(np.float32)  # 必须显式指定float32
print("NumPy dtype:", input_data.dtype)  # float32

# 获取模型输入信息
session = ort.InferenceSession("model.onnx")
input_name = session.get_inputs()[0].name
input_shape = session.get_inputs()[0].shape
input_type = session.get_inputs()[0].type
print(f"模型输入: {input_name}, 形状: {input_shape}, 类型: {input_type}")

# 类型不匹配示例（错误演示）
try:
    wrong_data = input_data.astype(np.float64)
    outputs = session.run(None, {input_name: wrong_data})
except Exception as e:
    print(f"类型错误: {e}")
风险提示：ONNX Runtime对输入数据类型非常敏感。即使NumPy数组可以自动转换类型，但ONNX Runtime不会隐式转换。如果模型期望 float32 而传入 float64 ，会直接抛出异常。此外， int32 与 int64 也不兼容，必须严格匹配模型定义。建议在预处理管线中统一使用 astype() 显式转换。

3.4 内存布局：NCHW与NHWC的底层差异

内存布局描述的是多维数组在物理内存中的排列顺序。对于图像数据，两种主流布局是NCHW（通道优先）和NHWC（通道最后）。在NCHW布局中，内存访问顺序是：先遍历所有通道的第一个像素，再遍历第二个像素，以此类推；而在NHWC布局中，每个像素的所有通道值在内存中是连续的。

这种差异直接影响推理性能。在CPU上，NHWC布局通常更友好，因为CPU的SIMD指令（如AVX）可以高效地同时处理多个通道的数据；而在GPU上，NCHW布局由于与cuDNN等库的优化内核匹配更好，往往能获得更快的卷积计算速度。ONNX Runtime默认使用NCHW布局（与PyTorch一致），但可以通过 session_options 或模型转换工具（如ONNX Converter）调整。

布局 维度顺序 内存访问模式 适用硬件 典型框架
NCHW N → C → H → W 通道间跨度大，通道内连续 GPU (CUDA) PyTorch, Caffe
NHWC N → H → W → C 像素内通道连续 CPU (ARM/AVX) TensorFlow

在ONNX Runtime中，内存布局通常由模型本身决定。如果模型是从PyTorch导出的，输入输出默认是NCHW；如果是从TensorFlow导出的，则可能是NHWC。在预处理时，必须根据模型的实际要求进行转置。例如，将HWC格式的图片数据转换为CHW：

# 假设从OpenCV读取的图像是HWC格式 (height, width, channels)
import cv2
image = cv2.imread("image.jpg")  # 形状: (H, W, 3), dtype: uint8
print("原始形状:", image.shape)  # (480, 640, 3)

# 转换为CHW格式 (C, H, W)
chw_image = image.transpose(2, 0, 1)  # 变为 (3, 480, 640)
print("转置后形状:", chw_image.shape)

# 添加批量维度并转为float32
input_tensor = chw_image[np.newaxis, :, :, :].astype(np.float32)  # (1, 3, 480, 640)
# 注意：还需要进行归一化（如除以255）和均值方差标准化

3.5 与NumPy的对应关系及零拷贝转换

ONNX Runtime的Python接口设计为与NumPy无缝协作。实际上， session.run() 的输入输出可以直接使用NumPy数组，ONNX Runtime内部会通过缓冲区协议（Buffer Protocol）实现零拷贝或最小拷贝的数据共享。这意味着，当你将一个NumPy数组传递给ONNX Runtime时，它不会复制数据，而是直接引用内存地址，从而大幅降低预处理开销。

这种对应关系体现在三个层面：数据类型映射、形状语义一致、内存连续性要求。ONNX Runtime要求输入张量必须是连续内存（C-contiguous）。如果NumPy数组是通过切片或转置得到的非连续视图，ONNX Runtime会抛出 ValueError 。此时，需要调用 np.ascontiguousarray() 强制转换为连续数组。

实战场景：图像分类模型的完整输入处理
假设我们有一个ResNet50的ONNX模型，输入要求为 [1, 3, 224, 224] 的float32张量，像素值归一化到[0,1]区间。以下是标准处理流程：
  1. 使用OpenCV或PIL读取图像，得到HWC格式的uint8数组。
  2. 将图像缩放至224×224尺寸。
  3. 将HWC转换为CHW： img.transpose(2, 0, 1) 。
  4. 添加批量维度： img[np.newaxis, :, :, :] 。
  5. 转换为float32并归一化： img.astype(np.float32) / 255.0 。
  6. 应用ImageNet的均值方差标准化： (img - mean) / std ，其中mean=[0.485, 0.456, 0.406]，std=[0.229, 0.224, 0.225]。
  7. 确保数组连续： np.ascontiguousarray(img) 。
完成以上步骤后，即可将数组直接作为 session.run() 的输入。

3.6 常见误区与调试技巧

在实际部署中，张量处理相关的错误占据了推理故障的很大比例。以下是几个高频误区及对应的排查方法：

  • 误区一：忽略数据类型匹配。模型期望float32，却传入float64。排查方法：打印 session.get_inputs()[0].type ，与输入数组的 dtype 对比。
  • 误区二：维度顺序错误。将HWC数据直接输入要求CHW的模型。排查方法：检查输入形状是否与模型定义一致，使用 transpose() 调整。
  • 误区三：非连续内存导致异常。对转置后的数组直接传入。排查方法：调用 np.ascontiguousarray() ，或使用 arr.flags['C_CONTIGUOUS'] 检查连续性。
  • 误区四：批量维度缺失。单张图片输入时忘记添加batch维度。排查方法：确认输入形状的维度数量，使用 np.expand_dims() 或 reshape() 添加。
调试利器：ONNX Runtime提供了 session.get_inputs() 和 session.get_outputs() 方法，可以获取每个输入输出的名称、形状、类型。在开发阶段，建议打印这些信息并与实际数据对比。此外，可以使用 onnxruntime.tools.check_onnx_model 工具在推理前验证模型完整性。

3.7 总结与最佳实践

张量处理是ONNX Runtime部署的基石。掌握形状、数据类型、内存布局三个核心维度，并熟练运用NumPy进行转换，可以避免绝大多数输入输出错误。最佳实践包括：在预处理管线中统一使用 float32 ；始终显式指定 dtype ；在传递数据前检查 flags['C_CONTIGUOUS'] ；对于图像数据，明确模型期望的布局（NCHW或NHWC）并保持一致。通过本章的学习，你应该能够独立完成从原始数据到ONNX Runtime输入张量的完整转换，并正确解读模型输出张量的含义。

← 上一章 📖 返回目录 下一章 →