FunASR语音识别API文档：接口调用参数详解

1. 技术背景与应用场景

随着语音交互技术的快速发展，自动语音识别（ASR）在智能客服、会议记录、字幕生成等场景中发挥着关键作用。FunASR 是一个开源的语音识别工具包，基于阿里巴巴达摩院的 Paraformer 和 SenseVoice 模型构建，具备高精度、低延迟的特点。

本文聚焦于FunASR 语音识别 API 的核心调用参数解析，帮助开发者深入理解各参数的作用机制，优化实际应用中的识别效果。该系统基于speech_ngram_lm_zh-cn模型进行二次开发，由“科哥”团队维护，支持本地部署和 WebUI 交互操作，适用于中文为主的多语言识别任务。

2. 核心接口参数详解

2.1 模型选择参数

FunASR 支持多种预训练模型切换，不同模型在精度与速度之间存在权衡：

model_type=paraformer-large
- 基于非自回归架构的大规模模型
- 优势：识别准确率高，适合对质量要求高的场景（如会议转录）
- 资源消耗：GPU 显存 ≥ 8GB，推理时间较长
model_type=sensevoice-small
- 轻量级多语种模型，支持情感识别
- 优势：响应快，适合实时语音处理（如直播字幕）
- 资源消耗：可在 CPU 上运行，显存需求低

建议实践：生产环境中优先使用 GPU 加速，并根据业务需求动态切换模型。

2.2 设备运行模式配置

通过设备参数控制推理后端：

device = "cuda" # 启用 GPU 加速（推荐） # 或 device = "cpu" # 使用 CPU 模式（无 GPU 时备用）

CUDA 模式：需安装 NVIDIA 驱动及 PyTorch CUDA 版本，可提升 3~5 倍推理速度
CPU 模式：兼容性好，但仅适合短音频或低并发场景

2.3 功能开关类参数

启用标点恢复（Punctuation Restoration）

enable_punc = True

开启后自动为识别结果添加逗号、句号等中文标点
基于上下文语义判断断句位置，提升文本可读性
默认关闭；开启后增加约 10% 推理耗时

语音活动检测（VAD）

vad_enabled = True threshold = 0.5 # 音量阈值（0.0 ~ 1.0） min_silence_duration = 1.0 # 最小静音时长（秒）

自动分割连续音频为多个语音片段
过滤无效静音段，减少误识别
可配合batch_size_s参数实现分块识别

输出时间戳信息

output_timestamp = True timestamp_type = "word" # 可选: "word", "sentence"

返回每个词或句子的时间区间[start, end]
应用于视频字幕同步、语音编辑定位等场景
结果以 JSON 格式输出，包含置信度字段

3. 音频输入与处理参数

3.1 批量大小设置（Batch Size）

batch_size_s = 300 # 单位：秒

控制每次处理的最大音频长度（默认 300 秒 ≈ 5 分钟）
范围：60 ~ 600 秒
实际内存占用与音频长度成正比，过大会导致 OOM 错误

工程建议：对于超过 10 分钟的长音频，建议先切片再批量处理。

3.2 支持的音频格式

格式	编码	推荐采样率	备注
WAV	PCM	16kHz	无损，兼容性最好
MP3	MPEG	16kHz	压缩率高，通用性强
FLAC	LPCM	16kHz	无损压缩，体积较小
M4A	AAC	16kHz	苹果生态常用
OGG	Vorbis	16kHz	开源格式，网络传输友好

所有输入音频将被自动重采样至 16kHz
不支持 8kHz 或非标准声道（如 5.1 环绕声）

3.3 音频预处理流程

解码：使用ffmpeg或pydub解析原始音频流
重采样：统一转换为 16kHz 单声道
归一化：调整音量至标准范围（避免过低/爆音）
VAD 分段（若启用）：提取有效语音片段
特征提取：计算梅尔频谱图作为模型输入

4. 语言识别与多语种支持

4.1 语言参数配置

lang = "auto" # 自动检测 # 其他选项： # lang = "zh" # 强制中文 # lang = "en" # 强制英文 # lang = "yue" # 粤语 # lang = "ja" # 日语 # lang = "ko" # 韩语

auto模式依赖声学模型内置的语言分类器
多语种混合内容建议使用SenseVoice-Small模型
强制指定语言可提升特定语种的识别准确率

4.2 中文识别优化策略

由于本系统基于speech_ngram_lm_zh-cn进行二次开发，针对中文场景做了以下增强：

N-Gram 语言模型融合：结合传统统计语言模型，纠正同音词错误（如“公式” vs “攻势”）
热词注入（Hotword Boosting）：
```
hotwords = ["人工智能", "大模型", "语音识别"]
```
提升专业术语出现概率，适用于垂直领域定制
拼音约束解码：利用汉字拼音先验知识优化解码路径

5. 输出格式与结果解析

5.1 文本结果

最简输出形式，返回纯文本字符串：

你好，欢迎使用语音识别系统。这是一个基于 FunASR 的中文语音识别 WebUI。

可直接复制用于后续 NLP 处理
若启用 PUNC，则包含完整标点

5.2 JSON 详细结果

结构化数据输出，包含时间戳、置信度等元信息：

{ "text": "你好 欢迎使用语音识别系统", "segments": [ { "id": 1, "start": 0.0, "end": 0.5, "text": "你好", "confidence": 0.98 }, { "id": 2, "start": 0.5, "end": 2.5, "text": "欢迎使用语音识别系统", "confidence": 0.95 } ] }

confidence字段反映识别可靠性
segments列表可用于逐句分析或编辑

5.3 SRT 字幕文件生成

支持导出标准 SRT 字幕格式，便于嵌入视频：

1 00:00:00,000 --> 00:00:02,500 你好 2 00:00:02,500 --> 00:00:05,000 欢迎使用语音识别系统

时间戳精确到毫秒
兼容主流剪辑软件（Premiere、Final Cut Pro 等）

6. 文件存储与目录结构

所有识别结果自动保存至本地输出目录：

outputs/ └── outputs_YYYYMMDDHHMMSS/ ├── audio_001.wav ├── result_001.json ├── text_001.txt └── subtitle_001.srt

目录名带时间戳，确保唯一性
包含原始音频副本、JSON 详情、TXT 文本、SRT 字幕四类文件
可通过配置修改根路径output_dir

7. 性能优化与避坑指南

7.1 提高识别准确率的实践建议

音频质量优先：
- 使用 16kHz 采样率、单声道 WAV/MP3
- 避免背景噪音、回声干扰
- 录音时保持适当距离（建议 20cm 内）
合理设置参数组合：
- 高精度场景：paraformer-large + enable_punc + output_timestamp
- 实时性要求高：sensevoice-small + cpu_mode

启用热词增强：

hotwords = ["FunASR", "科哥", "WebUI"]

7.2 常见问题排查

问题现象	可能原因	解决方案
识别结果乱码	编码异常或语言错配	检查音频编码，设置正确`lang`
无法上传文件	浏览器限制或格式不支持	转换为 MP3/WAV，检查大小 < 100MB
录音无声	权限未授权或设备故障	允许麦克风权限，测试系统录音功能
识别缓慢	使用 CPU 或模型过大	切换至 CUDA，改用 small 模型
长音频失败	batch_size_s 设置不当	分段处理或调大 batch_size_s