ONNX Runtime 怎样查看模型输入名称与形状

ONNX Runtime 里不要靠猜测模型输入名来构造 feeds。加载模型后，直接遍历 InferenceSession.get_inputs()，就能拿到每个输入的 NodeArg 元数据：name 是输入键，type 是 ONNX 类型描述，shape 是静态或动态形状。读取这些信息后，再用同一个名称建立输入字典，能避开“输入名不存在”和“数组维度不匹配”两类常见问题。

官方文档：https://onnxruntime.ai/docs/api/python/api_summary.html

最小做法是先创建 InferenceSession，再遍历 session.get_inputs()；每个 NodeArg 的 name、type、shape 就是构造输入映射前应确认的契约。

先把模型输入契约读出来

InferenceSession 是 ONNX Runtime 加载和运行模型的主要对象。本文只关注元数据查询，不讨论执行提供者、GPU 绑定或性能调优。下面的代码只负责读取模型描述，适合放在接入新模型时的准备阶段。

import onnxruntime as ort

# 只加载模型并读取会话信息，不在这里执行推理。
session = ort.InferenceSession("model.onnx")

# 输入节点按模型中的定义返回，每一项都是 NodeArg。
for node in session.get_inputs():
    print(node.name, node.type, node.shape)

关键点是 get_inputs() 返回一个输入元数据列表，而不是已经准备好的数组。列表中的每个元素对应模型图的一个输入节点，因此它适合先用于生成接入层的配置或调试日志。

逐项读取 name、type 和 shape

NodeArg 里最常用的三个属性分别解决不同问题：

• name：构造输入字典时使用的键，必须与模型输入名称一致。
• type：模型声明的 ONNX 类型，例如 tensor(float)，用于检查输入数据类型方向。
• shape：张量各维度的描述，可能是整数，也可能包含 None 或字符串形式的动态维度。

为了让结果更容易复制到日志或配置中，可以把元数据整理成普通字典。这里不把动态维度强行转成整数，因为它们代表模型允许在运行时决定的尺寸。

def collect_input_metadata(session):
    """收集输入元数据，保留动态维度的原始表达。"""
    metadata = []
    for node in session.get_inputs():
        # name 用来做 feeds 的键，type 和 shape 用来做输入契约提示。
        metadata.append({
            "name": node.name,
            "type": node.type,
            "shape": list(node.shape),
        })
    return metadata


for item in collect_input_metadata(session):
    print(item)

这段代码的输出只描述模型接口，不代表模型已经成功推理。若要保存到配置文件，建议保留原始的维度值，以便后续区分固定批大小和动态批大小。

动态维度不要当成固定数字

常见的动态形状会把批大小、序列长度或图像尺寸写成 None、batch、height 之类的占位信息。读取时可以把“是否动态”单独标记出来，而不是使用一个固定样例形状覆盖所有情况。

def describe_shape(shape):
    """为每个维度保留值，并标出需要运行时决定的维度。"""
    dimensions = []
    for index, value in enumerate(shape):
        # 整数表示静态尺寸，其他值只作为动态维度的提示。
        is_dynamic = not isinstance(value, int)
        dimensions.append({
            "index": index,
            "value": value,
            "dynamic": is_dynamic,
        })
    return dimensions


for node in session.get_inputs():
    print(node.name, describe_shape(node.shape))

如果后续业务只允许某个批大小或某个分辨率，应在业务层明确限制并给出错误提示；不能把模型元数据中的动态维度误读成“任意形状都可以”。类型、维度数量和具体元素数量仍然要与模型算子约束相容。

按读取到的名称构造输入映射

真正准备输入数组时，最容易犯的错是把自己熟悉的 input 当成键名。正确做法是使用 get_inputs() 读出的 name，再把数组放入字典。示例保留了一个固定形状，实际尺寸应以你读到的元数据和模型约定为准。

import numpy as np

input_nodes = session.get_inputs()
if len(input_nodes) != 1:
    raise ValueError("示例只处理单输入模型，请先按名称分别准备多个输入")

input_node = input_nodes[0]

# 这里的形状只是示例，接入真实模型时应根据输入契约准备数据。
features = np.zeros((1, 3), dtype=np.float32)
feeds = {input_node.name: features}

# 需要执行推理时，再把 feeds 传给 session.run；本文不依赖运行结果。
print("feed key:", input_node.name)
print("feed shape:", features.shape)

如果模型有多个输入，就分别遍历节点并按名称建立映射。若数组的 dtype 与 node.type 不一致，或者数组形状与固定维度不一致，应在提交给运行时前主动报错，这比等到执行阶段看到笼统异常更容易定位。

输出元数据也可以一起确认

输入检查完成后，可以用同样方式读取 session.get_outputs()。这一步不需要运行模型，适合在服务启动时打印接口摘要，确认输出名称和后续解析逻辑一致。

def print_io_metadata(session):
    """同时打印输入和输出的接口元数据。"""
    for label, nodes in (("input", session.get_inputs()), ("output", session.get_outputs())):
        for node in nodes:
            # NodeArg 的三个属性足够构成一条简洁的 IO 契约。
            print(label, node.name, node.type, node.shape)


print_io_metadata(session)

可以把这份摘要写入应用日志或启动检查结果，但不要把日志里的示例值当作所有模型都适用的固定答案。模型换版后，输入数量、节点名称和动态维度都可能发生变化。

常见问题

为什么 feeds 的键名不能随便写？

因为键名对应模型图中的输入节点名称。应以 session.get_inputs() 返回的 name 为准，而不是依据文件名或业务字段名猜测。

shape 中出现字符串是不是读取失败？

不一定。字符串通常是动态维度的符号名称，表示该维度需要由实际输入决定。固定维度仍要按原值匹配，动态维度则要结合模型和业务约束处理。

只看输入元数据就能保证推理成功吗？

不能。它能确认输入名称、类型和形状契约，但数据内容、算子支持、运行设备和模型本身的完整性仍需由实际接入流程负责。

小结

ONNX Runtime 查看模型输入名称与形状的核心只有三步：创建 InferenceSession，遍历 get_inputs()，读取每个 NodeArg 的 name、type 和 shape。先把这份输入契约读清楚，再按真实名称构造 feeds，遇到多输入模型或动态维度时就能把问题拆成可定位的字段，而不是反复试错。