如何使用自己的模型

本文说明如何把自有模型接入 FBB ModelZoo，复用现有 application/<scene>/run.sh 完成数据准备、模型转换和板端工程打包。

本文档专注接入自有模型流程：目录约定、metadata.yaml 字段、最小配置改动、检查项。具体场景的 CLI、配置字段完整含义、外部路径请到对应场景 README（如图像分类：application/image_classification/README.md）。

适用范围

当前仓库以图像分类场景为参考实现，已验证的模型格式包括 ONNX、TFLite float32、TFLite int8。新增模型时优先复用已有场景和数据集；只有输入输出语义或板端业务流程不同（例如检测、分割），才需要新增 application/<new_scene> 目录。

公共应用模板的复用范围是单输入、单输出、无状态模型。更换模型时可以调整输入 shape、dtype、布局和量化参数。若存在输入或输出张量数量变化、状态张量循环、特殊后处理或批处理，都需要在场景目录中提供对应的处理代码，不能只修改 metadata.yaml。

如果连续推理需要把上一帧的结果传给下一帧，请在模型文件条目中设置 streaming_state: true。这个字段表示“流式推理需要保存跨帧状态”；普通模型不要设置它。

编译阶段会在 output/.../generated/*/src/app_model_contract.json 留下一份由 metadata.yaml 生成的 I/O 契约快照，便于确认当前模型是否仍可直接复用默认模板；该文件属于生成产物，不需要手工维护或提交。其中 input_count / output_count 只用于核对模型边界；即使契约记录了多个 inputs / outputs，默认模板也不会自动填充或后处理这些张量，仍需由场景 adapter 显式实现。

目录放置

把自有模型放在独立模型目录下：

models/<scene>/<model_name>/
├── README.md
├── configs/
│   └── config.<CHIP_VERSION>.<PLATFORM>.<TOOLCHAIN>[.<variant>].cfg
└── models/
    ├── metadata.yaml
    └── <model-file>

约束：

models/ 只放模型资产和 metadata.yaml；configs/ 只放部署配置。
文件命名中的 variant 区分同一芯片 + 工具链下的量化或精度部署路径（例如 micro_quant、none、pre_quant、float32、int8）。
没有强制要求每个 CHIP_VERSION × TOOLCHAIN 组合都提供预设——按你要发布的部署路径提供即可。
添加完模型后，需在 models/README.md 的"已收录模型"表中登记一行，以保持索引完整。

metadata.yaml 字段

每个可部署模型文件都需要在 files 下登记输入输出语义和格式：

name: my_model
task: image_classification

application:
  scenario: my_classification_case
  dataset:
    name: my_dataset
  input_domain: image
  output_domain: classification
  classes: [0, 1]

files:
  model.onnx:
    format: onnx
    precision: float32
    role: deployable_model
    input:
      name: input
      shape: [1, 1, 28, 28]
      dtype: float32
      layout: NCHW          # NCHW / NHWC，必须与模型真实输入一致
    output:
      name: output
      shape: [1, 10]
      dtype: float32
      classes: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
    # 只有跨帧保留上一帧状态的流式模型才需要：
    # streaming_state: true

TFLite Micro 模型

需要额外提供运行期信息：

  model-int8.tflite:
    format: tflite
    precision: int8
    tflite_micro:
      arena_size: 51200            # 张量内存池字节数（TFLite Micro 在芯片上为中间张量预留的
                                   # 连续内存区）。不确定时可先估算，运行时若日志报
                                   # AllocateTensors() failed / arena size too small，按报错值上调。
      operator_count: 7            # 模型包含的算子层数；用 netron 打开模型计数，或：
                                   # python -c "import tensorflow as tf; itp=tf.lite.Interpreter('model.tflite'); itp.allocate_tensors(); print(len(itp._get_ops_details()))"
    input:
      name: serving_default_input:0
      shape: [1, 28, 28, 1]
      dtype: int8
      layout: NHWC
    output:
      name: StatefulPartitionedCall:0
      shape: [1, 10]
      dtype: int8

已量化（int8）模型

无论是 tflite-micro int8 还是 mindspore-lite QUANT_MODE=pre_quant，板端示例都通过 metadata 注入量化参数，不能硬编码。pre_quant 部署路径的完整可工作预设见 models/image_classification/mnist-12/configs/config.WS63.RISCV.mindspore-lite.pre_quant.cfg。

    quantization:
      input:
        dtype: int8
        scale: 0.003921568859368563
        zero_point: -128
      output:
        dtype: int8
        scale: 0.21915793418884277
        zero_point: -12

最小配置改动

从已有模型的 configs/ 复制一份预设作为起点：

mkdir -p models/<scene>/my_model/configs
cp models/image_classification/mnist-12/configs/config.WS63.RISCV.mindspore-lite.micro_quant.cfg \
   models/<scene>/my_model/configs/config.WS63.RISCV.mindspore-lite.micro_quant.cfg

至少需要修改：

字段	改成什么
`MODEL_NAME`	模型目录名，例如 `my_model`（决定 `output/<MODEL_NAME>/`）
`MODEL_DIR`	`models/<scene>/my_model/models`
`MODEL_FILE`	本次部署选择的模型文件名
`DATASET_DIR`	对应数据生成脚本目录
`FIRMWARE_OUTPUT`	将路径中的 `mnist-12` 替换为新模型名
`SDK_PATH` / `ADAPTOR_PATH` / `MSLITE_PATH` / `TFLM_PATH` / `COMPILER_PATH` / `ACL_HEADER_PATH`	按本机安装位置填写

MODEL_METADATA 默认 <MODEL_DIR>/metadata.yaml，一般无需显式设置。其它字段（PLATFORM、CHIP_VERSION、TOOLCHAIN、QUANT_MODE 等）跟随预设命名固定，含义与取值见对应场景 README 的"配置字段"小节。

运行

复制预设到场景目录后执行 run.sh，或运行时通过 --config 指定。具体命令见场景 README。

检查项

MODEL_FILE 必须存在于 MODEL_DIR，并在 metadata.yaml 的 files 下登记。
input.layout 和 input.shape 必须和模型真实输入一致；与板端示例代码的预处理保持同样的张量排布 / 精度。
CANN 与 mindspore-lite 量化部署路径需要校准数据，数据目录中应包含 train_data/bin/*.bin（数据生成脚本默认会生成）。
TFLite Micro 模型必须填 tflite_micro.arena_size 与 operator_count，否则编译会失败或运行时报内存不足。
使用 mindspore-lite QUANT_MODE=pre_quant（外部已量化模型）时，必须填写 quantization.input / quantization.output 的 dtype / scale / zero_point。编译脚本会向生成目录中的 ai_main.c 模板注入这些参数，不得硬编码。
安装了 requirements.txt 中的依赖时，run.sh 会生成参考输出（output.npy + output.txt），便于和板端结果比对。