# funasr_api

**Repository Path**: lijian8642_admin/funasr_api

## Basic Information

- **Project Name**: funasr_api
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-05-15
- **Last Updated**: 2026-05-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 语音识别系统 (FunASR + SenseVoiceSmall)

## 系统架构

本系统采用前后端分离架构：

```
┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│  用户浏览器     │  HTTP   │  Flask API     │  模型   │  SenseVoice    │
│  (Gradio UI)   │ ──────► │  (asr_api.py)  │ ──────►│  Small 模型    │
│  :7860         │         │  :5000         │         │  GPU推理       │
└─────────────────┘         └─────────────────┘         └─────────────────┘
```

## 文件说明

| 文件 | 功能 |
|------|------|
| `asr_api.py` | Flask API 服务，提供 `/recognize` 接口 |
| `web_asr_gradio.py` | Gradio 网页前端，调用 API 进行识别 |
| `test_api.py` | Python 调用示例 |

## 启动方式

### 1. 启动 API 服务
```bash
python asr_api.py
```
服务地址: http://192.168.0.105:5000

### 2. 启动网页界面
```bash
python web_asr_gradio.py
```
网页地址: http://192.168.0.105:7860

---

## 语音识别原理 (ASR)

### 什么是 ASR?

ASR (Automatic Speech Recognition) 自动语音识别，是将人类语音转换为文本的技术。

### SenseVoiceSmall 模型

本系统使用 **SenseVoiceSmall** 模型，由阿里开源的语音识别模型。

#### 模型特点：
1. **端到端架构** - 直接将音频转换为文本，无需传统语音识别中的多个独立组件
2. **支持多语言** - 中文、英文、粤语、日语、韩语等
3. **中文优化** - 对中文有很好的识别效果，支持中文标点恢复（ITN）
4. **轻量级** - Small 版本适合 GPU 推理

#### 处理流程：

```
音频文件 → 采样率转换 → 分帧 → 特征提取 → 模型推理 → 后处理 → 文本
```

1. **音频预处理**
   - 读取音频文件
   - 转单声道（多声道取平均值）
   - 转 float32 格式
   - 重采样为 16kHz（模型要求）

2. **声学特征提取**
   - 使用 FMMB (Fast Fourier Transform) 提取频谱特征
   - 将音频分成小片段（帧），每帧约 25ms

3. **模型推理**
   - 输入：声学特征序列
   - 输出：文字序列
   - 使用 `language="zh"` 指定中文识别
   - 使用 `use_itn=True` 启用中文标点恢复

4. **后处理**
   - `rich_transcription_postprocess()` 对结果进行格式化
   - 恢复标点符号
   - 去除特殊标记

### 核心技术

- **Transformer 架构** - 使用自注意力机制处理序列数据
- **CTC (Connectionist Temporal Classification)** - 处理输入输出长度不一致的问题
- **热词增强** - 可以通过配置提升特定词汇的识别准确率

---

## API 接口说明

### 识别接口

**URL**: `POST /recognize`

**参数**:
- `file`: 音频文件 (支持 wav, mp3, m4a, flac 等格式)

**返回**:
```json
{
  "success": true,
  "text": "识别结果文本"
}
```

**调用示例 (Python)**:
```python
import requests

url = "http://192.168.0.105:5000/recognize"
with open("test.wav", "rb") as f:
    files = {'file': f}
    response = requests.post(url, files=files)
    print(response.json())
```



---

## 常见问题

### 1. 其他设备无法访问？
- 确保防火墙允许 5000 端口
- API 已配置 `host='0.0.0.0'` 支持局域网访问

### 2. 识别效果不好？
- 音频质量：建议 16kHz 以上采样率
- 噪音：降噪处理可以提升效果
- 方言：SenseVoice 对标准普通话效果较好

### 3. 响应速度慢？
- 音频时长越长，识别时间越长
- 可以考虑使用 GPU 加速

---

## 模型训练与微调

FunASR 支持模型训练和微调，以下是训练数据准备和微调示例。

### 训练数据格式

训练数据采用 **JSONL 格式**，每行一个 JSON 对象：

```json
{"key": "音频ID", "source": "音频路径(本地或URL)", "source_len": 帧数, "target": "音频文本标注", "target_len": 字符数}
```

#### 示例数据 (data/list/train.jsonl)

```json
{"key": "BAC009S0764W0121", "source": "https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav", "source_len": 90, "target": "甚至出现交易几乎停滞的情况", "target_len": 13}
{"key": "BAC009S0916W0489", "source": "https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0916W0489.wav", "source_len": 90, "target": "湖北一公司以员工名义贷款数十员工负债千万", "target_len": 20}
{"key": "ID0012W0014", "source": "https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_en.wav", "source_len": 88, "target": "he tried to think how it could be", "target_len": 8}
```

| 字段 | 说明 |
|------|------|
| `key` | 音频唯一ID |
| `source` | 音频路径（本地路径或 URL） |
| `source_len` | 音频帧数（可选，用于数据过滤） |
| `target` | 音频对应的文本标注 |
| `target_len` | 文本字符数（可选，用于数据过滤） |

#### 验证数据

准备 `val.jsonl`，格式与训练数据相同。

### 微调示例

```bash
# 使用 DeepSpeed 加速微调
torchrun --nproc_per_node 4 funasr/bin/train_ds.py \
  ++model="iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch" \
  ++train_data_set_list="train.jsonl" \
  ++valid_data_set_list="val.jsonl" \
  ++dataset_conf.batch_size=6000 \
  ++dataset_conf.batch_type="token" \
  ++train_conf.max_epoch=50 \
  ++optim_conf.lr=0.0002 \
  ++output_dir="./outputs"
```

### 更多训练示例

官方提供了丰富的训练示例，位于 `funasr/examples/` 目录：

- `industrial_data_pretraining/paraformer/` - Paraformer 模型微调
- `industrial_data_pretraining/sense_voice/` - SenseVoice 模型微调
- `industrial_data_pretraining/paraformer_streaming/` - 流式模型微调
- `industrial_data_pretraining/sanm_kws/` - 关键词检测模型微调
- `aishell/paraformer/` - AISHELL 数据集训练示例

详细文档请参考 [FunASR 官方文档](funasr/docs/tutorial/README_zh.md)。

### 训练数据生成工具

如果已有 `wav.scp` 和 `text.txt` 文件，可使用官方工具转换为 JSONL 格式：

```bash
scp2jsonl \
++scp_file_list='["train_wav.scp", "train_text.txt"]' \
++data_type_list='["source", "target"]' \
++jsonl_file_out="train.jsonl"
```

---

## 模型评估

FunASR 提供了完整的模型评估工具，主要使用 **CER（字符错误率）** 和 **WER（词错误率）** 作为评估指标。

### 评估指标说明

| 指标 | 说明 | 适用语言 |
|------|------|----------|
| **CER** | 字符错误率 (Character Error Rate) | 中文 |
| **WER** | 词错误率 (Word Error Rate) | 英文 |
| **SER** | 句子错误率 (Sentence Error Rate) | 通用 |

**计算公式：**
```
CER = (替换数 + 删除数 + 插入数) / 参考字符总数
WER = (词替换数 + 词删除数 + 词插入数) / 参考词总数
```

**CER 参考标准：**
- < 5%：优秀
- 5-10%：良好
- 10-20%：一般
- > 20%：需要改进

### 方法一：训练时自动验证

在微调命令中指定验证集，训练过程中会自动评估：

```bash
torchrun --nproc_per_node 4 funasr/bin/train_ds.py \
  ++model="iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch" \
  ++train_data_set_list="train.jsonl" \
  ++valid_data_set_list="val.jsonl" \
  ++output_dir="./outputs"
```

训练日志会输出验证集的 loss 和 CER 值。

### 方法二：离线推理评估

训练完成后，使用验证/测试集进行推理并计算 CER。

#### 步骤1：推理生成识别结果

```bash
python funasr/bin/inference.py \
  ++model="your_finetuned_model_path" \
  ++val_data_set_list="val.jsonl" \
  ++output_dir="./inference_result" \
  ++batch_size=16 \
  ++device="cuda"
```

#### 步骤2：计算 CER/WER

使用框架提供的工具计算错误率：

```bash
python funasr/runtime/python/utils/compute_wer.py \
  ref_file \
  hyp_file \
  output_cer_file
```

**参数说明：**
- `ref_file`: 参考文本（ground truth），格式为 `音频ID 文本`
- `hyp_file`: 模型预测结果
- `output_cer_file`: 输出的详细CER报告

**文本格式要求（每行）：**
```
音频ID  文本内容
```

**输出示例：**
```
%WER 5.23 [ 100 / 1912, 50 ins, 30 del, 20 sub ]
%SER 15.00 [ 30 / 200 ]
```

### 方法三：使用评估脚本

框架提供了完整的评估脚本 `test_cer.py`：

```bash
python funasr/runtime/python/utils/test_cer.py \
  --model_dir "./your_finetuned_model" \
  --wav_file "test_wav_list.txt" \
  --output_dir "./eval_output" \
  --backend torch
```

**wav_file 格式：**
```
音频ID1 /path/to/audio1.wav
音频ID2 /path/to/audio2.wav
```

### 方法四：批量评估（推荐）

完整的评估流程示例（参考 `funasr/examples/aishell/paraformer/run.sh`）：

```bash
# 1. 设置参数
inference_device="cuda"
inference_checkpoint="model.pt.avg10"
inference_scp="wav.scp"
inference_batch_size=32

# 2. 运行推理
python funasr/bin/inference.py \
  ++model="${exp_dir}/exp/${model_dir}/${inference_checkpoint}" \
  ++val_data_set_list="${data_dir}/val.jsonl" \
  ++output_dir="${inference_dir}" \
  ++device="${inference_device}" \
  ++batch_size="${inference_batch_size}"

# 3. 后处理文本
python utils/postprocess_text_zh.py ${inference_dir}/text ${inference_dir}/text.proc
python utils/postprocess_text_zh.py ${data_dir}/text ${inference_dir}/text.ref

# 4. 计算 CER
python utils/compute_wer.py \
  ${inference_dir}/text.ref \
  ${inference_dir}/text.proc \
  ${inference_dir}/text.cer

# 5. 查看结果
tail -n 3 ${inference_dir}/text.cer
```

### 常用评估命令汇总

```bash
# 训练时验证
torchrun --nproc_per_node 4 funasr/bin/train_ds.py \
  ++model="iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch" \
  ++train_data_set_list="train.jsonl" \
  ++valid_data_set_list="val.jsonl" \
  ++output_dir="./outputs"

# 推理评估
python funasr/bin/inference.py \
  ++model="./outputs" \
  ++val_data_set_list="val.jsonl" \
  ++output_dir="./eval" \
  ++device="cuda"

# 计算 CER
python funasr/runtime/python/utils/compute_wer.py \
  val.jsonl.ref \
  val.jsonl.hyp \
  result.cer
```

---

## 工作原理

### 系统架构详解

本系统采用前后端分离架构，各组件协同工作实现语音识别功能。

```
┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│  用户浏览器     │  HTTP   │  Flask API     │  模型   │  SenseVoice    │
│  (Gradio UI)   │ ──────► │  (asr_api.py)  │ ──────►│  Small 模型    │
│  :7860         │         │  :5000         │         │  GPU推理       │
└─────────────────┘         └─────────────────┘         └─────────────────┘
```

### 核心技术原理

#### 1. 音频预处理流程

```
原始音频 → 采样率转换 → 声道合并 → 格式转换 → 重采样 → 分帧处理
```

- **采样率转换**：统一转换为 16kHz（模型要求）
- **声道合并**：多声道转单声道
- **分帧**：每帧约 25ms，帧移 10ms

#### 2. 声学特征提取

使用 Fbank 或 MFCC 特征提取器将时域信号转换为频域特征：

```
音频信号 → 预加重 → 加窗(汉明窗) → FFT → Mel滤波器组 → Fbank特征
```

#### 3. 模型推理 (SenseVoiceSmall)

```
输入: Fbank特征序列 [batch, time, dim]
      │
      ▼
┌─────────────────────────────────────┐
│     Encoder (Transformer/Conformer) │  ← 编码器提取上下文特征
│     自注意力机制 + 卷积模块          │
└─────────────────────────────────────┘
      │
      ▼
┌─────────────────────────────────────┐
│     CTC/Attention Decoder           │  ← 解码器输出文字
│     预测每个帧对应的token            │
└─────────────────────────────────────┘
      │
      ▼
输出: 文字序列 ["你", "好", "世", "界"]
```

#### 4. 后处理

- **ITN (Inverse Text Normalization)**：逆文本正则化
- **标点恢复**：添加标点符号
- **特殊标记清理**：移除模型产生的特殊 token

### 关键技术点

| 技术 | 说明 |
|------|------|
| **Transformer** | 自注意力机制，捕获长距离依赖 |
| **CTC** | 处理输入输出长度不一致问题 |
| **VAD** | 语音端点检测，切割长音频 |
| **ITN** | 逆文本正则化，优化输出格式 |

---

## 应用场景与推荐模型

FunASR 框架提供了多种模型，可根据不同场景选择最适合的模型：

### 1. 离线语音转写

**场景**：将音频/视频文件批量转写成文字

**推荐模型**：
- **SenseVoiceSmall** - 多语言支持，含情感识别，推荐 ✅
- **Paraformer-zh** - 中文识别精度高
- **Whisper-large-v3** - 多语言，支持时间戳

**适用场景**：
- 会议记录自动生成
- 视频字幕制作
- 音频内容归档
- 客服通话录音转写

---

### 2. 实时语音识别

**场景**：实时将语音转换成文字，低延迟要求

**推荐模型**：
- **Paraformer-zh-streaming** - 中文实时识别 ✅
- **Paraformer-en-streaming** - 英文实时识别

**适用场景**：
- 实时字幕直播
- 语音输入法
- 语音聊天机器人
- 实时会议纪要

---

### 3. 语音端点检测 (VAD)

**场景**：检测语音的开始和结束位置

**推荐模型**：
- **fsmn-vad** - 实时 VAD，精度高 ✅

**适用场景**：
- 长音频自动分段
- 语音活动检测
- 通话质量分析

---

### 4. 语音唤醒 (KWS)

**场景**：检测特定关键词唤醒设备

**推荐模型**：
- **fsmn-kws** - 离线关键词检测
- **sanm-kws-streaming** - 实时关键词检测 ✅

**适用场景**：
- 智能音箱唤醒 ("小爱同学")
- 车载语音助手
- 智能家居控制

---

### 5. 标点恢复

**场景**：为识别结果添加标点符号

**推荐模型**：
- **ct-punc** - 中英文标点恢复 ✅

**适用场景**：
- 改善转写可读性
- 文本格式化

---

### 6. 时间戳预测

**场景**：获取每个字/词的时间位置

**推荐模型**：
- **fa-zh** - 中文时间戳预测 ✅

**适用场景**：
- 字幕制作（需要时间轴）
- 语音检索
- 音频对齐

---

### 7. 说话人分离

**场景**：识别谁在什么时候说话

**推荐模型**：
- **Cam++** - 说话人确认/分离 ✅

**适用场景**：
- 多人会议记录
- 通话录音分离
- 说话人统计

---

### 8. 情感识别

**场景**：识别语音中的情感状态

**推荐模型**：
- **emotion2vec+large** - 情感识别精度高 ✅

**适用场景**：
- 客服质检
- 语音情绪分析
- 心理健康评估

---

### 9. 多语言识别

**场景**：支持多种语言的语音识别

**推荐模型**：
- **SenseVoiceSmall** - 支持中文/英文/粤语/日语/韩语等多语言 ✅
- **Whisper-large-v3** - 支持上百种语言 ✅
- **Paraformer-en** - 英文专项优化

**适用场景**：
- 跨国会议
- 多语言内容翻译
- 外语学习

---

### 10. 长音频处理

**场景**：处理小时级别的长音频

**推荐组合**：
- **Paraformer + fsmn-vad** - VAD 切割 + ASR ✅
- **SenseVoiceSmall + VAD** - 自动长音频处理

**优化参数**：
```python
model = AutoModel(
    model="SenseVoiceSmall",
    vad_model="fsmn-vad",
    vad_kwargs={"max_single_segment_time": 30000},  # 最大30秒分段
    batch_size_s=300  # 动态batch
)
```

---

### 模型选型参考表

| 场景 | 推荐模型 | 特点 |
|------|----------|------|
| 通用中文转写 | SenseVoiceSmall | 多功能、高精度 |
| 实时中文识别 | Paraformer-zh-streaming | 低延迟 |
| 英文转写 | Paraformer-en / Whisper | 高精度 |
| 多语言 | SenseVoice / Whisper | 覆盖广 |
| 语音唤醒 | sanm-kws-streaming | 实时 |
| 说话人分离 | Cam++ | 高准确 |
| 情感识别 | emotion2vec+large | 4种情感 |
| 标点恢复 | ct-punc | 中英通用 |