📚 课程目录第4章输入张量获取

输入张量获取：通过input_tensor()接口获取输入张量，理解索引与名称映射

在TFLite Micro的推理流程中，获取输入张量是模型加载后、执行推理前的关键一步。开发者通过input_tensor()接口获得指向输入缓冲区的指针，进而填充待推理的数据。然而，许多初学者在调用该接口时，往往混淆“索引”与“名称”的概念，导致数据写入错误位置或读取到无效地址。本章将深入剖析input_tensor()的底层机制，讲解索引与名称的映射关系，并通过实际案例演示如何正确获取输入张量。

上图展示了TFLite Micro中input_tensor()接口的核心工作流程：模型内部维护一个输入张量列表，每个张量具有唯一的索引和名称；接口通过索引或名称定位到对应的张量描述符，最终返回指向实际数据缓冲区的指针。理解这一映射关系是正确使用接口的前提。

4.1 核心原理：张量描述符与缓冲区管理

TFLite Micro的运行时环境使用TfLiteTensor结构体描述每一个张量。该结构体包含张量的数据类型、维度信息、量化参数以及指向实际数据内存的指针data。模型加载后，解释器（MicroInterpreter）会为所有输入和输出张量分配内存，并建立索引与张量描述符之间的映射表。

input_tensor(index)接口的实现逻辑非常直接：它接收一个整数索引，在内部张量数组中查找对应位置的TfLiteTensor，并返回其指针。值得注意的是，索引的顺序与模型定义时的输入顺序一致，通常从0开始递增。对于单输入模型，索引固定为0；对于多输入模型，则需要根据模型训练时的输入顺序确定索引。

关键数据结构：

typedef struct TfLiteTensor {
  TfLiteType type;          // 数据类型（如kTfLiteFloat32）
  TfLiteIntArray* dims;     // 维度信息
  TfLiteQuantizationParams params; // 量化参数
  char* name;               // 张量名称
  TfLiteAllocationType allocation_type;
  union {
    void* data;             // 数据缓冲区指针
    // ... 其他分配类型
  };
  // ... 其他字段
} TfLiteTensor;

缓冲区地址的分配发生在AllocateTensors()调用阶段。该函数根据张量大小和内存规划器（Memory Planner）的策略，在预先分配的连续内存池中为每个张量划分独立区域。因此，input_tensor()返回的指针在AllocateTensors()之后才有效，且在整个推理生命周期内保持稳定。

4.2 判断方法：索引与名称的获取策略

在实际开发中，开发者可以通过两种方式获取输入张量：按索引访问或按名称查找。下表对比了两种方式的适用场景：

获取方式	API调用	优点	缺点	适用场景
按索引	`input_tensor(0)`	简单直接，无需解析名称	索引顺序需与模型定义一致	单输入模型或输入顺序固定的多输入模型
按名称	遍历查找`name`字段	语义明确，不易混淆	需要额外遍历，性能略低	输入较多或需要动态匹配的场景

对于按名称查找，TFLite Micro没有提供直接的GetInputTensorByName()接口，开发者需要自行遍历所有输入张量，比较name字段。以下是一个典型的实现模式：

TfLiteTensor* GetInputTensorByName(MicroInterpreter* interpreter, const char* name) {
  for (int i = 0; i < interpreter->inputs_size(); ++i) {
    TfLiteTensor* tensor = interpreter->input_tensor(i);
    if (tensor->name != nullptr && strcmp(tensor->name, name) == 0) {
      return tensor;
    }
  }
  return nullptr; // 未找到
}

在模型转换时，输入张量的名称通常由TensorFlow模型定义决定。例如，Keras模型中的Input(shape=(224,224,3), name='image_input')会生成名为image_input的张量。开发者可以通过Netron工具或flatbuffer解析器查看模型中的实际名称。

4.3 案例拆解：多输入模型的张量获取实战

假设我们有一个双输入模型，用于多模态分类任务：一个输入接收图像数据（224×224×3），另一个输入接收文本特征（长度为128的向量）。模型定义如下：

# TensorFlow模型定义（示意）
image_input = Input(shape=(224, 224, 3), name='image_input')
text_input = Input(shape=(128,), name='text_input')
# ... 模型结构 ...
combined = Concatenate()([image_features, text_features])
output = Dense(10, activation='softmax')(combined)
model = Model(inputs=[image_input, text_input], outputs=output)

转换到TFLite Micro后，输入张量列表包含两个元素。根据模型定义顺序，索引0对应image_input，索引1对应text_input。在嵌入式设备上，我们按以下流程获取并填充输入数据：

// 获取输入张量
TfLiteTensor* image_tensor = interpreter->input_tensor(0);
TfLiteTensor* text_tensor = interpreter->input_tensor(1);

// 验证张量属性
printf("Image tensor: name=%s, dims=%d, type=%d\n",
       image_tensor->name, image_tensor->dims->size, image_tensor->type);
printf("Text tensor: name=%s, dims=%d, type=%d\n",
       text_tensor->name, text_tensor->dims->size, text_tensor->type);

// 填充图像数据（假设已从摄像头获取）
memcpy(image_tensor->data.uint8, image_buffer, 224*224*3);

// 填充文本特征
memcpy(text_tensor->data.float32, text_features, 128*sizeof(float));

在实际项目中，我们曾遇到一个典型问题：开发者误以为输入顺序与模型可视化工具中的显示顺序一致，导致图像数据被写入文本张量。通过打印name字段，发现实际顺序与预期相反。解决方法是始终通过名称验证张量身份，而不是盲目依赖索引。

风险提示：在TFLite Micro中，输入张量的索引顺序由模型转换工具决定，可能与训练时的inputs列表顺序不同。建议在首次运行时打印所有输入张量的名称和索引，建立明确的映射关系。

4.4 常见误区与总结复盘

在输入张量获取过程中，开发者常犯以下错误：

忽略索引越界：访问input_tensor(inputs_size())会导致未定义行为。应始终检查索引范围。
在AllocateTensors之前调用：此时张量缓冲区尚未分配，返回的data指针为nullptr。
混淆输入与输出张量：部分开发者误用output_tensor()获取输入数据，导致写入无效内存。
假设名称唯一：某些模型可能包含重名张量，遍历查找时应处理重复情况。

为了帮助开发者快速定位问题，我们总结了一套调试流程：

调用interpreter->inputs_size()获取输入张量总数。
遍历所有输入张量，打印索引、名称、维度和数据类型。
根据打印信息，确认目标张量的索引或名称。
在填充数据前，检查tensor->data是否为nullptr。
填充后，可读取部分数据回验，确保写入正确。

经验建议：对于生产级代码，建议封装一个GetInputTensorByName()辅助函数，并在初始化阶段缓存张量指针。这样既能保证语义清晰，又能避免重复查找带来的性能开销。同时，在张量指针使用前增加断言（assert），确保指针有效。

总结而言，input_tensor()接口是TFLite Micro数据输入的入口，理解索引与名称的映射关系是避免数据错乱的关键。开发者应养成打印张量元信息的习惯，在模型更新或替换时重新验证映射关系，确保推理流程的稳定性。