Horizon 模型多 Batch 配置

一、基础概念

在 Horizon 模型转换与部署中，涉及三个关键参数：input_shape、input_batch、separate_batch。理解这三个参数的作用与限制，是正确配置模型的前提。

1. input_shape

input_shape 定义模型输入张量的维度，格式为 N x C x H x W。

单 batch（N=1）：

多 batch（N>1，静态）：

第一维 N 就是 batch size。直接在 input_shape 里写多少，模型就固定接受多少张图。

2. input_batch

input_batch 不是对 input_shape 的替代，而是一种扩展机制：把一个 batch=1 的模型，在编译阶段扩展成 batch=N 的模型。

使用前提：

input_shape 第一维必须为 1
原始 ONNX 模型本身需支持 batch 推理

配置示例：

最终生成的模型支持 batch=4 的输入。

与直接写 4x3x224x224 的区别：

方式	说明
input_shape: 4x3x224x224	静态多 batch，shape 固定，校准数据也必须是 batch=4
input_shape: 1x3x224x224 + input_batch: 4	动态多 batch，校准数据只需 batch=1，更灵活

3. separate_batch

separate_batch 控制多 batch 情况下，输入数据的内存组织方式。

separate_batch: False（默认）

所有 batch 数据必须在连续内存中一次性送入：

separate_batch: True

每个 batch 独立送入，不要求内存连续：

在配置了input_batch参数时，该参数配置才有效。
这个选项主要用于 NV12 / pyramid 图像输入场景，因为摄像头出来的帧天然是一帧一帧独立的，无法合并为连续 buffer。

二、两种模型导出形态

明确了三个参数之后，模型导出主要对应两种形态。

形态一：静态多 Batch 模型

input_shape 直接写目标 batch size，例如：

编译时 batch 就固定了。

特点与限制：

batch size 不可修改
校准数据（calibration data）的 shape 必须与之完全匹配，即也需要是 (4, 3, 224, 224)
不支持 input_batch 参数（两者冲突）
不涉及 separate_batch，输入本身就是连续 tensor

形态二：动态多 Batch 模型

input_shape 保持 batch=1，用 input_batch 指定目标 batch size：

特点与限制：

校准数据只需 batch=1，准备简单
batch size 可以在不同部署场景中灵活调整，只需修改 input_batch
推理时实际送入的是 batch=4 的数据，runtime 内部负责调度
是工程部署的推荐方式

三、三种部署方案

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

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

适用场景：

输入数据已经过外部预处理（resize、归一化等），以 tensor 形式直接输入，不走板端图像处理流水线。模型 shape 固定，batch 不需要变化。

配置：

数据准备：

校准数据和推理数据的 shape 必须是 (4, 3, 224, 224)，即每次喂入 4 张已预处理完的图像 tensor，合并在连续内存中。

注意：

不能在此方案中使用板端 resize / crop 等图像预处理操作，一旦 batch > 1 并且使用了图像预处理，编译阶段就会报错：

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

适用场景：

同样是预处理好的 tensor 输入，但希望部署更灵活，不想每次改 batch 都重新编译，或者校准数据准备成本较高。

配置：

数据准备：

校准数据只需准备 batch=1 的单张图：

推理时 runtime 会自动将 batch 扩展为 4：

这是工程部署最推荐的方式。 配置简单，校准数据准备成本低，部署灵活。

方案三：NV12 图像输入 + separate_batch

适用场景：

输入来自摄像头、图像 pipeline（pyramid / resizer），数据格式为 NV12（YUV420），不经过外部预处理，直接送原始图像帧。

配置：

数据准备：

每帧图像独立送入，不需要拼接为连续 buffer：

关键限制：

separate_batch 必须设为 True，否则 NV12 输入无法正确处理

四、常见错误与解决方法

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

报错：

原因：

input_type_rt 设置为 nv12 或 yuv 等图像类型，同时 batch > 1。板端图像预处理不支持批量操作。

解决方法：

改为 featuremap 输入，在外部完成预处理再送入模型：
或者将separate_batch 设为 True

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

报错：

原因：

模型是静态 batch=4（input_shape: 4x3x224x224），但校准数据准备的是 batch=1 的 .npy 文件。

解决方法：

重新打包校准数据，使 shape 与 input_shape 匹配：

或者改用动态多 batch 方案（方案二），从根本上规避这个问题。

五、方案对比与选型建议

方案	输入类型	input_shape	input_batch	separate_batch
静态多 batch	featuremap	4x3x224x224	不使用	不适用
动态多 batch	featuremap	1x3x224x224	4	不适用
NV12 图像输入	nv12	1x3x224x224	4	True