Horizon 模型多 Batch 配置

一、基础概念

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

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 里写多少，模型就固定接受多少张图。

input_batch

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

使用前提：

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

配置示例：

input_shape: 1x3x224x224input_batch: 4

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

与直接写 4x3x224x224 的区别：

separate_batch

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

separate_batch: False（默认）

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

[ image0 | image1 | image2 | image3 ]  →  shape: (4, 3, 224, 224)

separate_batch: True

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

image0  →  shape: (1, 3, 224, 224)
image1  →  shape: (1, 3, 224, 224)
image2  →  shape: (1, 3, 224, 224)
image3  →  shape: (1, 3, 224, 224)

在配置了 input_batch 参数时，该参数配置才有效。

这个选项主要用于 NV12 / pyramid 图像输入场景，因为摄像头出来的帧天然是一帧一帧独立的，无法合并为连续 buffer。

二、两种模型导出形态

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

形态一：静态多 Batch 模型

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

input_shape: 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: 1x3x224x224input_batch: 4

特点与限制：

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

三、三种部署方案

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

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

适用场景：

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

配置：

input_type_rt: featuremapinput_type_train: featuremap

数据准备：

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

# 示例：构造 batch=4 的校准数据import numpy as npbatch_data = np.stack([img0, img1, img2, img3], axis=0)  # shape: (4, 3, 224, 224)

注意：

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

Insert image convert/resize for batched input is not allowed

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

适用场景：

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

配置：

input_shape: 1x3x224x224input_type_rt: featuremapinput_type_train: featuremapinput_batch: 4

数据准备：

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

# 校准数据：单张预处理图，shape: (1, 3, 224, 224)calib_data = preprocess(image)  # shape: (1, 3, 224, 224)

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

输入: (1, 3, 224, 224)  →  runtime 内部扩展  →  实际推理: batch=4

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

方案三：NV12 图像输入 + separate_batch

适用场景：

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

配置：

input_type_rt: nv12input_batch: 4input_shape: '1x3x224x224'separate_batch: True

数据准备：

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

# 每帧独立，shape: (1, 3, 224, 224)# ...

关键限制：

• 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 ***, error message: error detected

原因：

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

解决方法：

改为 featuremap 输入，在外部完成预处理再送入模型：

或者将 separate_batch 设为 True

input_type_rt: featuremapinput_type_train: featuremap

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

报错：

ERROR cannot reshape array of size 602112 into shape (1,3,224,224)
 ERROR The file batch_00000.rgb.npy load failed, please double check the input.

原因：

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

解决方法：

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

import numpy as np
# 原始单张数据single = np.load("calib_single.npy")  # shape: (1, 3, 224, 224)
# 打包为 batch=4batch4 = np.stack([single] * 4, axis=0)  # shape: (4, 3, 224, 224)np.save("calib_batch4.npy", batch4)

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

五、方案对比与选型建议

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