# dudu ASR 模型评估框架

横向对比**云端 gummy**（DashScope `gummy-realtime-v1`）与**本地开源模型**（faster-whisper /
SenseVoice / Paraformer），重点覆盖**中英混说（code-switching）**，产出三类指标：

| 维度 | 指标 |
|---|---|
| 准确率 | **MER**（中英混合错误率，headline）/ CER（字级）/ WER（词级） |
| 速度 | 首包延迟、定稿延迟、RTF（处理时长 / 音频时长） |
| 资源 | 本地：峰值内存 / 平均 CPU / 模型大小；云端：成本(¥/分钟) |

## 安装

```bash
cd eval
python -m venv .venv && source .venv/bin/activate
pip install -e .                 # 核心管线（含云端 gummy 评估能力）
pip install -e '.[whisper]'      # 加 faster-whisper 本地引擎
pip install -e '.[funasr]'       # 加 SenseVoice / Paraformer（含 torch）
pip install -e '.[all]'          # 全部本地引擎
```

## 跑评估

```bash
# 冒烟：每个数据集取 5 条，只跑 gummy + whisper-small
rbw get dashscope-api-key | python -m asr_eval run --sample-limit 5 --engines gummy,whisper-small

# 只验证 gummy 连通
rbw get dashscope-api-key | python -m asr_eval run --engines gummy --datasets custom --sample-limit 3

# 全量（放开 sample_limit、在 config.yaml 里 enable 想跑的引擎/数据集）
rbw get dashscope-api-key | python -m asr_eval run --config config.yaml
```

> gummy 的 API key 优先读环境变量 `DASHSCOPE_API_KEY`，否则读 stdin 首行——
> 遵全局规则用 `rbw get dashscope-api-key | ...` 管道传入，不落盘、不写 env 文件。

报告写到 `results/<时间戳>/`：`report.md`（终端友好）、`report.html`（表格）、
`report.json`（机器可读）、`results.jsonl`（每条样本明细，便于 debug 个案）。

## 配置（`config.yaml`）

- **数据集**：公共集统一 `type: hf`，差异全在配置（`hf_id`/`split`/`text_field`/`lang`）——
  广覆盖 / 换数据集只改配置不动代码。预置 ASCEND（中英混说）、AISHELL-1（纯中）、LibriSpeech（纯英）。
- **自定义集**：`type: custom` 指向 JSONL manifest，把自录/业务音频按 `manifests/custom.example.jsonl`
  格式丢进来即可与公共集同管线评估。
- **引擎**：`enabled` 开关；本地引擎可选 `device`（cpu / 苹果芯片可试 mps）、whisper 的 `compute_type`。

## 设计要点

- **gummy 协议**对照后端 `server/internal/asr/gummy.go` 移植（run-task/finish-task、`transcription`
  与 `sentence` 双字段、`sentence_end` 的 bool/字符串兼容、3200B/16k/pcm 分帧）。
- **错误率语料级聚合**：累加 S/D/I/N 再求率，不对每条样本求率再平均（短句不会被放大）。
- **评分前归一化**：去标点、英文小写、繁→简、全/半角统一，否则中英混说分数失真。
- **公平性声明**：流式(gummy) vs 离线(本地)延迟口径不同（gummy RTF 含推流倍速与网络）；
  资源仅本地引擎测量，含 Python 进程基底——报告会标注硬件环境。

## 已知约束

- ASCEND 在 HuggingFace 开放；AISHELL/LibriSpeech 首次会下载（数 GB，已 gitignore）。
- SEAME（更权威的中英混说集）需 LDC 付费授权，默认不含；有授权可加一个 hf/custom 适配条目。
- 本地模型权重大（whisper-large ≈1.5GB、SenseVoice ≈900MB），按需 enable。