一、基础概念详解

在 Horizon 模型转换与部署流程中，有三个关键参数必须透彻理解：input_shape、input_batch、separate_batch。只有清晰掌握它们各自的功能与约束条件，才能正确完成模型配置的第一步。

1. input_shape 参数解析

   input_shape 负责定义模型输入张量的维度，格式固定为 N x C x H x W。单 batch（N=1）时，配置为 1 x 3 x 224 x 224；多 batch（N>1，静态）时，则配置为 4 x 3 x 224 x 224。第一维 N 即 batch size，在 input_shape 中设定的数值决定了模型固定接收的图像数量。

2. input_batch 扩展机制

   input_batch 并非用于替代 input_shape，而是一种编译阶段的扩展机制——它能将一个 batch=1 的模型扩展为 batch=N 的模型。使用该参数需满足两个前提：input_shape 的第一维必须为 1，且原始 ONNX 模型本身支持 batch 推理。配置示例：input_shape: 1x3x224x224，input_batch: 4，最终生成的模型支持 batch=4 的输入。它与直接写 4x3x224x224 的区别将在后文详细展开。

3. separate_batch 内存组织方式

   separate_batch 决定在多 batch 场景下输入数据的内存组织方式。设为 False（默认值）时，所有 batch 数据必须位于连续内存中一次性送入，形状为 (4, 3, 224, 224)；设为 True 时，每个 batch 独立送入，无需内存连续，每个形状为 (1, 3, 224, 224)。该选项仅在配置了 input_batch 参数时生效，主要用于 NV12 / pyramid 图像输入场景——因为摄像头发送的帧天然是一帧一帧独立的，无法合并为连续 buffer。

二、两种模型导出形态

理清三大参数后，模型导出对应两种形态。

形态一：静态多 Batch 模型

直接通过 input_shape 设定目标 batch size，例如 4x3x224x224，编译时 batch 即固定。特点：batch size 不可修改；校准数据（calibration data）的 shape 必须完全匹配，即也需要是 (4, 3, 224, 224)；不支持 input_batch 参数（两者冲突）；不涉及 separate_batch，输入本身为连续 tensor。

形态二：动态多 Batch 模型

input_shape 保持 batch=1，通过 input_batch 指定目标 batch size，例如 input_shape: 1x3x224x224，input_batch: 4。特点：校准数据只需 batch=1，准备简单；batch size 可在不同部署场景中灵活调整，仅需修改 input_batch；推理时实际送入的是 batch=4 的数据，runtime 内部负责调度。这也是工程部署中较为推荐的方式。

三、三种部署方案

根据输入数据来源和处理方式的不同，实际部署对应三种方案。

方案一：静态多 Batch + Featuremap 输入

适用场景：输入数据已完成外部预处理（resize、归一化等），以 tensor 形式直接输入，不走板端图像处理流水线。模型 shape 固定，batch 无需变化。配置为 input_type_rt: featuremap，input_type_train: featuremap。数据准备时，校准数据和推理数据的 shape 必须是 (4, 3, 224, 224)，即每次喂入 4 张已预处理完成的图像 tensor，合并于连续内存中。需特别注意：不能在此方案中使用板端 resize / crop 等图像预处理操作，一旦 batch > 1 且使用了图像预处理，编译阶段即会报错：Insert image convert/resize for batched input is not allowed。

方案二：动态多 Batch + Featuremap 输入

适用场景：同样是预处理好的 tensor 输入，但希望部署更灵活——不想每次修改 batch 都重新编译，或校准数据准备成本较高。配置示例：input_shape: 1x3x224x224，input_type_rt: featuremap，input_type_train: featuremap，input_batch: 4。数据准备时，校准数据只需准备 batch=1 的单张图，推理时 runtime 会自动将 batch 扩展为 4。这是工程部署最推荐的方式——配置简单，校准数据准备成本低，部署灵活。

方案三：NV12 图像输入 + separate_batch

适用场景：输入来自摄像头、图像 pipeline（pyramid / resizer），数据格式为 NV12（YUV420），不经过外部预处理，直接送入原始图像帧。配置如下：input_type_rt: nv12，input_batch: 4，input_shape: '1x3x224x224'，separate_batch: True。数据准备时，每帧图像独立送入，无需拼接为连续 buffer。关键限制：separate_batch 必须设为 True，否则 NV12 输入无法正确处理。

四、常见错误与解决方法

错误一：batch>1 时使用板端图像预处理

报错信息类似：error: insert image convert/resize for batched input is not allowed, got 4 ERROR *** ERROR-OCCUR-DURING hbdk.insert_image_convert ***。原因很简单：input_type_rt 设置为 nv12 或 yuv 等图像类型，同时 batch > 1，板端图像预处理不支持批量操作。解决方法有两种：要么改为 featuremap 输入，在外部完成预处理后再送入模型；要么将 separate_batch 设为 True。

错误二：校准数据 shape 与模型不匹配

报错信息类似：ERROR cannot reshape array of size 602112 into shape (1,3,224,224) ERROR The file batch_00000.rgb.npy load failed。根源在于：模型是静态 batch=4（input_shape: 4x3x224x224），但校准数据准备的是 batch=1 的 .npy 文件。解决方法：重新打包校准数据，使 shape 与 input_shape 匹配；或者改用动态多 batch 方案（方案二），从根本上规避该问题。

五、方案对比与选型建议

最后，将三种方案放在一起对比，便于选型参考。