cpp/README.md

# Sherpa KWS C++ 推理

本目录提供 AX630C 和 AX650 C++ 推理程序。`kaldi-native-fbank` 在 CPU 端生成
特征，Zipformer encoder、decoder 和 joiner 在 AXERA NPU 上运行。

## 编译环境

需要 Linux、CMake 和 Arm GNU 9.2 AArch64 交叉编译器。AX630C 与 AX650 共用
同一套交叉编译器：

```bash
mkdir -p cpp/toolchains
wget -P cpp/toolchains \
  https://developer.arm.com/-/media/Files/downloads/gnu-a/9.2-2019.12/binrel/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu.tar.xz
tar -xf cpp/toolchains/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu.tar.xz \
  -C cpp/toolchains
```

下载 AX650 和 AX630C BSP：

```bash
bash cpp/download_bsp.sh all
```

脚本使用以下 SDK：

| 平台 | SDK | 编译时目录 |
| --- | --- | --- |
| AX650 | `msp_50_3.10.2.zip` | `cpp/toolchains/ax650n_bsp_sdk/msp/out` |
| AX630C | `msp_20e_3.0.0.zip` | `cpp/toolchains/ax620e_bsp_sdk/msp/out/arm64_glibc` |

## 交叉编译

```bash
export TOOLCHAIN_ROOT="cpp/toolchains/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu"

bash cpp/build_ax650.sh
bash cpp/build_ax630c.sh
```

生成：

```text
cpp/bin/sherpa_kws_ax650
cpp/bin/sherpa_kws_ax630c
```

如 BSP 放在其他目录，可在编译前设置 `BSP_MSP_DIR`。AX650 应指向包含
`include/` 和 `lib/` 的 `msp/out`；AX630C 应指向
`msp/out/arm64_glibc`。

## 板端运行

AX650 单条推理：

```bash
MAX_ACTIVE_PATHS=16 AUDIO=audio/sherpa/zh_2.wav \
bash cpp/run_sherpa_kws_ax650.sh
```

AX630C 单条推理：

```bash
MAX_ACTIVE_PATHS=16 AUDIO=audio/sherpa/zh_2.wav \
bash cpp/run_sherpa_kws_ax630c.sh
```

批量测试：

```bash
MAX_ACTIVE_PATHS=16 bash cpp/run_batch_sherpa_kws_ax650.sh
MAX_ACTIVE_PATHS=16 bash cpp/run_batch_sherpa_kws_ax630c.sh
```

默认使用 chunk-8。设置 `CHUNK_SIZE=16` 可切换 chunk-16。输入音频必须为
16 kHz、单声道、16-bit PCM WAV。

模型目录：

```text
models/650/
models/630C/
```

运行脚本会检查对应平台的 encoder、decoder 和 joiner 模型，避免误用其他平台的
axmodel。AX630C 模型上传后即可直接运行，不需要重新编译 C++ 程序。

## 解码参数

`MAX_ACTIVE_PATHS` 取值范围为 `1` 到 `32`，表示每个输出帧最多保留的候选路径
数量。推荐从 `16` 开始验证，再根据召回率、误报率和 RTF 选择能够稳定唤醒的
最小值。该参数与 `CHUNK_SIZE` 无关。

推理只输出一个 `rtf` 指标。`rtf` 包含 fbank 与模型推理，不包含模型加载和
初始化。

## 新增唤醒词

```bash
python3 scripts/generate_keyword_tokens.py \
  --text 金融动荡 \
  --append
```

关键词文件在运行时读取，不需要重新导出、量化或编译模型。