一、基础概念
在 Horizon 模型转换与部署中，涉及三个关键参数：input_shape、input_batch、separate_batch。理解这三个参数的作用与限制，是正确配置模型的前提。
input_shape
input_shape 定义模型输入张量的维度，格式为 N x C x H x W。
单 batch（N=1）：
Plain
1 x 3 x 224 x 224多 batch（N>1，静态）：
Plain
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 推理
配置示例：
Plain
input_shape: 1x3x224x224input_batch: 4最终生成的模型支持 batch=4 的输入。
与直接写 4x3x224x224 的区别：
separate_batch
separate_batch 控制多 batch 情况下，输入数据的内存组织方式。
separate_batch: False（默认）
所有 batch 数据必须在连续内存中一次性送入：
Plain
[ image0 | image1 | image2 | image3 ] → shape: (4, 3, 224, 224)separate_batch: True
每个 batch 独立送入，不要求内存连续：
Plain
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，例如：
Plain
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：
Plain
input_shape: 1x3x224x224input_batch: 4特点与限制：
- 校准数据只需 batch=1，准备简单
- batch size 可以在不同部署场景中灵活调整，只需修改 input_batch
- 推理时实际送入的是 batch=4 的数据，runtime 内部负责调度
- 是工程部署的推荐方式
三、三种部署方案
根据输入数据来源和处理方式的不同，实际部署中对应三种方案。
方案一：静态多 Batch + Featuremap 输入
适用场景：
输入数据已经过外部预处理（resize、归一化等），以 tensor 形式直接输入，不走板端图像处理流水线。模型 shape 固定，batch 不需要变化。
配置：
Plain
input_type_rt: featuremapinput_type_train: featuremap数据准备：
校准数据和推理数据的 shape 必须是 (4, 3, 224, 224)，即每次喂入 4 张已预处理完的图像 tensor，合并在连续内存中。
Plain
# 示例：构造 batch=4 的校准数据import numpy as npbatch_data = np.stack([img0, img1, img2, img3], axis=0) # shape: (4, 3, 224, 224)注意：
不能在此方案中使用板端 resize / crop 等图像预处理操作，一旦 batch > 1 并且使用了图像预处理，编译阶段就会报错：
Plain
Insert image convert/resize for batched input is not allowed方案二：动态多 Batch + Featuremap 输入
适用场景：
同样是预处理好的 tensor 输入，但希望部署更灵活，不想每次改 batch 都重新编译，或者校准数据准备成本较高。
配置：
Plain
input_shape: 1x3x224x224input_type_rt: featuremapinput_type_train: featuremapinput_batch: 4数据准备：
校准数据只需准备 batch=1 的单张图：
Plain
# 校准数据：单张预处理图，shape: (1, 3, 224, 224)calib_data = preprocess(image) # shape: (1, 3, 224, 224)推理时 runtime 会自动将 batch 扩展为 4：
Plain
输入: (1, 3, 224, 224) → runtime 内部扩展 → 实际推理: batch=4这是工程部署最推荐的方式。 配置简单，校准数据准备成本低，部署灵活。
方案三：NV12 图像输入 + separate_batch
适用场景：
输入来自摄像头、图像 pipeline（pyramid / resizer），数据格式为 NV12（YUV420），不经过外部预处理，直接送原始图像帧。
配置：
Plain
input_type_rt: nv12input_batch: 4input_shape: '1x3x224x224'separate_batch: True数据准备：
每帧图像独立送入，不需要拼接为连续 buffer：
Plain
# 每帧独立，shape: (1, 3, 224, 224)# ...关键限制：
- separate_batch 必须设为 True，否则 NV12 输入无法正确处理
四、常见错误与解决方法
错误一：batch>1 时使用了板端图像预处理
报错：
Plain
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
Plain
input_type_rt: featuremapinput_type_train: featuremap错误二：校准数据 shape 与模型不匹配
报错：
Plain
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 匹配：
Plain
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 |