README.md

---
license: mit
library_name: axera
pipeline_tag: audio-classification
tags:
- speaker-embedding
- speaker-verification
- speaker-diarization
- campplus
- speech
---

# campplus.AXERA

CAM++ 说话人声纹模型 Axera 推理demo。

- [x] Python 推理（axengine，`python/example.py`）
- [x] C++ 可执行文件（`bin/campplus_ax650`）
- [x] 一键运行脚本（`run_ax650.sh`）

源码（模型转换 + C++ 源码）见 GitHub：
[campplus.AXERA](https://github.com/AXERA-TECH/campplus.AXERA)

## 支持模型

| 模型 | 输入 | 输出 | axmodel 大小 | 量化精度 |
|------|------|------|------|------|
| CAM++ (speech_campplus_sv_zh_en_16k-common_advanced) | feature [1,360,80] | embedding [1,192] | 10.5 MB | U16+SmoothQuant，embedding cosine 0.9957 |

## 目录结构

```
campplus.AXERA/
├── models/
│   ├── campplus.axmodel    # AX650 量化模型
│   └── model_meta.json
├── bin/
│   └── campplus_ax650      # C++ 可执行文件
├── python/
│   ├── campplus_sdk/       # 声纹 SDK（inference + clustering）
│   ├── example.py          # 验证 / 提取 / 聚类 demo
│   └── requirements.txt    # numpy torch torchaudio axengine
├── samples/                # 示例音频（ModelScope 官方示例）
├── run_ax650.sh            # 一键运行（Python / C++）
├── configuration.json
└── README.md
```

## 快速开始（AX650 板端）

```bash
# 下载本仓库到板端后：
bash run_ax650.sh                     # C++ 1:1 说话人验证（samples 示例）
bash run_ax650.sh python              # Python 1:1 说话人验证
bash run_ax650.sh cpp a.wav b.wav     # C++ 自定义音频
bash run_ax650.sh python a.wav b.wav  # Python 自定义音频
```

## Python 推理

### 环境

```bash
conda create -n campplus python=3.10
conda activate campplus

# 安装 axengine (https://github.com/AXERA-TECH/pyaxengine/releases/latest)
pip install axengine-x.x.x-py3-none-any.whl

pip install -r python/requirements.txt
```

### 1:1 说话人验证

```bash
python3 python/example.py --models-dir models --wav1 a.wav --wav2 b.wav
```

输出 cosine 相似度（同人 ≈ 0.67，不同人 ≈ 0.06，越高越可能是同一说话人）：

```
cosine similarity: 0.6726
```

### 声纹提取 + 说话人聚类

```bash
python3 python/example.py --models-dir models --audio meeting.wav --diarize
```

按 1.5 s / 0.75 s 滑窗提取 embedding，谱聚类输出：

```
Speaker_0: [0.00 35.25]
Speaker_1: [35.25 70.47]
```

## C++ 推理（bin/ 可执行文件）

```bash
export LD_LIBRARY_PATH=/soc/lib:${LD_LIBRARY_PATH:-}
./bin/campplus_ax650 --models-dir models --wav1 a.wav --wav2 b.wav
./bin/campplus_ax650 --models-dir models --audio meeting.wav --output meeting.embed.bin
```

特征提取（kaldi-native-fbank，snip_edges=true / dither=0 / povey / mean_nor）
与 Python 版（torchaudio kaldi fbank）逐点对齐（主机实测 cosine 0.99999986）；
板端 C++ 与 Python 提取的 embedding cosine = 0.99999955。

## 性能（AX650N 实测）

| 指标 | 数值 |
|------|------|
| NPU 单次推理（[1,360,80] → [1,192]） | 2.559 ms（ax_run_model 实测） |
| C++ 端到端（fbank + NPU） | 28.2 ms/chunk |
| Python 端到端（torchaudio fbank + axengine） | 72.1 ms/chunk |

### RTF（vad_example.wav 70.47s / 93 chunks）

| 推理路径 | 耗时 | RTF |
|------|------|------|
| C++ | 2.620 s | 0.037 |
| Python | 6.71 s | 0.095 |

> RTF = 推理耗时 / 音频时长（不含模型加载，RTF < 1.0 即可实时）

## 精度（板端实测 vs ONNX 参考）

| 路径 | cosine |
|------|--------|
| C++ embedding vs ONNX（93 chunks） | 0.9941（per-chunk min 0.9912） |
| Python axengine vs ONNX | 0.9950 – 0.9966 |
| 1:1 验证（同人 speaker1_a/b） | 0.6685（C++）/ 0.6668（Python），参考 ≈ 0.67 |
| 1:1 验证（不同人 speaker1_a/2_a） | 0.0638（C++），参考 ≈ 0.06 |

## 模型转换复现

按 GitHub 仓库 [model_convert](https://github.com/AXERA-TECH/campplus.AXERA/tree/main/model_convert)
说明：ModelScope 权重 → ONNX（onnxsim/onnxslim，torch/ONNX cosine 1.0）→
真实音频 FBank 校准（5 段真实语音 30 组）→ Pulsar2 U16+SmoothQuant 量化
（embedding cosine 0.9957，gate 0.99）。

## 参考

- [3D-Speaker](https://github.com/modelscope/3D-Speaker)
- [3D-Speaker-MT.axera](https://github.com/AXERA-TECH/3D-Speaker-MT.axera)
- [campplus.AXERA](https://github.com/AXERA-TECH/campplus.AXERA)（源码仓）
- [Magnetar](https://github.com/AXERA-TECH/Magnetar) — AXERA 模型部署 agent 工具