asr-eval

中文 ASR 横向评测工具箱 — 用同一套 gold 转写，公平对比 FunASR / Whisper / llama.cpp 的 micro-CER 与 RTFx。

English: Reproducible Mandarin ASR benchmark toolkit — multi-engine CER comparison, out-of-the-box mini testset, OpenASR-style pipeline. See docs/WHY.md.

pip install -e ".[whisper]"
python -m asr_eval setup
python -m asr_eval run --engines faster-whisper-small

| Engine               | micro-CER ↓ | RTFx ↑ | Utterances |
|----------------------|-------------|--------|------------|
| funasr-sensevoice    | 3.45%       | 12.1×  | 3          |
| faster-whisper-small | 18.20%      | 8.3×   | 3          |

📖 手把手教程 · 🚀 5 分钟上手 · 🔌 接入新引擎 · 💬 讨论区

---

目录

• 30 秒判断：适不适合你
• 和 OpenASR / 自己写脚本的区别
• 你能用它做什么
• 5 分钟上手
• 支持的引擎
• 指标口径
• 命令速查
• 参与共建

---

30 秒判断：适不适合你

✅ 适合	❌ 暂时不适合
要对比 中文 ASR 引擎 谁更准、谁更快	主要评 英文 WER → 用 Open ASR Leaderboard
需要 可复现 的 CER 数字（团队/论文/回归测试）	只要在线听写 Demo，不需要 gold 转写
有或愿意准备 人工校对 ref	只有机器字幕、没有 gold
想快速起步，不想从零搭评测流水线	已有成熟内部评测平台且口径已固定

---

和 OpenASR / 自己写脚本的区别

	OpenASR	自己写脚本	asr-eval
语言	英文 WER	随意	中文 micro-CER
规范化	English normalizer	常不一致	FunASR normalize_zh
多引擎	HF 榜单一键跑	每个引擎一套脚本	统一 testset → JSONL → 评分
上手成本	需 ESB 数据集	高	setup 自带迷你中文集
定位	公开排行榜	一次性对比	团队可复现评测工具箱

---

你能用它做什么？

场景	做法
第一次做 ASR 测评	docs/TUTORIAL.md 从零到出报告
对比 FunASR / Whisper / llama.cpp	python -m asr_eval run
用自己的录音 + 人工转写	准备 testset.json
接入公司自研 ASR	docs/ADD_ENGINE.md
理解 CER / micro-CER 口径	docs/METRICS.md

---

5 分钟上手（开箱即用）

第 0 步：环境

git clone https://github.com/lixuanqun/asr-eval.git
cd asr-eval
python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -e ".[whisper]"    # 最小可跑（CPU 友好）
# pip install -e ".[funasr]"   # 中文更强，需下载模型

第 1 步：下载内置迷你测试集

python -m asr_eval setup

生成 data/mini/audio/*.wav + data/mini/testset.json（带 gold ref）。

第 2 步：查看本机可用引擎

python -m asr_eval list-backends

第 3 步：一键推理 + 评分

python -m asr_eval run --setup --engines faster-whisper-small,funasr-sensevoice

输出 runs/summary.md、JSONL manifest、逐句 CER 报告。

testset.json 格式

[
  {
    "id": "001",
    "audio_path": "data/mini/audio/001.wav",
    "ref": "欢迎大家来体验达摩院推出的语音识别模型",
    "duration": 3.5,
    "domain": "mandarin_clean"
  }
]

• ref 必须是人工校对 gold（机器字幕只能做相对比较）
• domain 用于分场景统计（电话 / 嘈杂 / 方言等）

完整流程见 docs/TUTORIAL.md。

---

支持的引擎

引擎名	说明	安装
funasr-sensevoice	SenseVoice 中文多语	pip install -e ".[funasr]"
funasr-paraformer	Paraformer 工业中文	同上
funasr-llamacpp-sensevoice	CPU 二进制 + GGUF	设置 FUNASR_LLAMACPP_BIN
faster-whisper / -turbo / -small	Whisper 对照组	pip install -e ".[whisper]"
whisper-cpp	本地 C++ 二进制	设置 WHISPER_CPP_BIN

完整说明：docs/ENGINES.md · 缺引擎？提交 Engine 请求

---

指标口径（必读）

中文默认 micro-CER（语料级字符错误率），与 FunASR BENCHMARKS 对齐：

1. 去掉 SenseVoice 标签 <|zh|> 等
2. normalize_zh：去标点空白，保留 CJK + 字母数字
3. micro 聚合：Σ编辑距离 / Σ参考字符数（不是每句 CER 的平均）

详见 docs/METRICS.md

---

命令速查

python -m asr_eval setup                              # 下载迷你测试集
python -m asr_eval list-backends                        # 查看可用引擎
python -m asr_eval infer --engine funasr-sensevoice --testset data/mini/testset.json
python -m asr_eval score --results-dir runs/results
python -m asr_eval run --engines funasr-sensevoice,faster-whisper-turbo

---

工程结构

asr-eval/
├── asr_eval/
│   ├── backends/       # 可插拔 ASR 引擎
│   ├── normalizer/     # 中文文本规范化
│   ├── metrics/        # micro-CER
│   ├── runner.py       # infer → JSONL → score
│   └── cli.py          # python -m asr_eval
├── docs/               # 教程、指标、引擎说明
└── data/mini/          # setup 后生成

---

参与共建

欢迎 Star ⭐、提 Issue、提交 PR！

• 接入新引擎（Sherpa-ONNX、PaddleSpeech、自研 ASR）→ CONTRIBUTING.md
• 测评经验 / 选型讨论 → Discussions
• 文档不清楚 → 直接开 Issue

---

参考与致谢

• FunASR · Open ASR Leaderboard · jiwer · asr-bench

License

MIT