FunASR语音识别API文档：参数详解与错误处理-优快云博客

FunASR语音识别API文档：参数详解与错误处理

【免费下载链接】FunASR A Fundamental End-to-End Speech Recognition Toolkit and Open Source SOTA Pretrained Models, Supporting Speech Recognition, Voice Activity Detection, Text Post-processing etc. 项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR

1. 引言

FunASR（Fundamental End-to-End Speech Recognition Toolkit）是一个开源的端到端语音识别工具包，提供了语音识别（Automatic Speech Recognition, ASR）、语音活动检测（Voice Activity Detection, VAD）、文本后处理等功能。本文档详细介绍FunASR语音识别API的参数配置、使用方法及错误处理策略，帮助开发者快速集成和调试语音识别功能。

2. API概览

FunASR提供多种部署方式，包括离线文件转写和实时语音识别，支持WebSocket/gRPC通信协议。核心API类为FunasrApi，主要用于客户端与服务端的交互，支持音频文件转录和流式音频输入。

from funasr_api import FunasrApi

# 初始化API客户端
api = FunasrApi(uri="wss://127.0.0.1:10095")

# 转录音频文件
result = api.rec_file("audio.wav")
print(result)

2.1 核心功能

离线文件转录：支持多种音频/视频格式（如WAV、MP3、MP4），通过FFmpeg进行解码。
实时流式识别：支持PCM音频流输入，低延迟配置（如chunk_size参数）。
热词定制：通过热词文件或API参数提升特定词汇识别准确率。
时间戳输出：返回词级别时间戳，支持字幕生成等场景。

3. 参数详解

3.1 初始化参数（FunasrApi）

参数名	类型	默认值	描述
uri	str	"wss://www.funasr.com:10096/"	WebSocket服务端地址，格式为`ws://host:port`或`wss://host:port`
timeout	int	1000	超时时间（毫秒），超过该时间未收到结果则终止请求
msg_callback	function	None	回调函数，用于实时接收识别结果

示例：

def on_message(msg):
    print(f"实时结果: {msg['text']}")

api = FunasrApi(uri="wss://127.0.0.1:10095", timeout=5000, msg_callback=on_message)

3.2 音频转录参数（rec_file/rec_buf）

参数名	类型	默认值	描述
file_path	str	-	音频文件路径（仅rec_file方法）
audio_buf	bytes	-	音频字节流（仅rec_buf方法）
ffmpeg_decode	bool	False	是否使用FFmpeg解码非PCM格式音频
hotwords	str	""	热词配置，格式为`"{"关键词":权重,...}"`，如`"{"阿里巴巴":20}"`
use_itn	bool	True	是否启用逆文本规范化（Inverse Text Normalization）

示例：

# 转录MP3文件并启用热词
result = api.rec_file("audio.mp3", ffmpeg_decode=True, hotwords='{"通义实验室":30}')

3.3 服务端配置参数（run_server.sh）

服务端启动脚本run_server.sh支持以下关键参数：

参数名	类型	默认值	描述
--model-dir	str	damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-onnx	ASR模型路径或ModelScope模型ID
--vad-dir	str	damo/speech_fsmn_vad_zh-cn-16k-common-onnx	VAD模型路径或ModelScope模型ID
--punc-dir	str	damo/punc_ct-transformer_cn-en-common-vocab471067-large-onnx	标点模型路径或ModelScope模型ID
--hotword	str	""	服务端全局热词文件路径，每行格式为`"关键词权重"`
--port	int	10095	服务监听端口
--certfile	str	../../../ssl_key/server.crt	SSL证书文件路径，设为0禁用SSL

示例：

nohup bash run_server.sh \
  --model-dir damo/speech_paraformer-large-vad-punc_asr_nat-zh-cn-16k-common-vocab8404-onnx \
  --hotword /workspace/models/hotwords.txt \
  --port 10096 > log.txt 2>&1 &

4. WebSocket通信协议

4.1 客户端请求格式

初始化请求（JSON）

{
  "mode": "offline", 
  "wav_name": "test_audio", 
  "is_speaking": true, 
  "wav_format": "mp3", 
  "hotwords": "{\"阿里巴巴\":20}", 
  "itn": true
}

参数说明

mode: 识别模式，"offline"（离线文件）或"2pass"（实时带校正）
wav_name: 音频标识，用于结果匹配
is_speaking: 是否持续发送音频，true表示流式输入，false表示结束

4.2 服务端响应格式

{
  "mode": "offline", 
  "wav_name": "test_audio", 
  "text": "你好，欢迎使用FunASR", 
  "is_final": true, 
  "timestamp": "[[100, 300], [400, 600]]"
}

参数说明

is_final: 是否为最终结果，true表示当前音频处理完成
timestamp: 词级别时间戳，单位为毫秒（需服务端启用时间戳模型）

5. 错误处理

5.1 常见错误类型

错误场景	可能原因	解决方案
连接超时	服务端未启动或网络不通	检查服务状态及端口开放情况
音频解码失败	音频格式不支持或损坏	使用`ffmpeg_decode=True`或转换为PCM格式
识别结果为空	音频无声或音量过小	检查音频文件完整性，提高输入音量
热词不生效	热词格式错误或模型不支持	确认热词格式为JSON字符串，使用支持热词的模型（如`speech_paraformer-large-contextual`）

5.2 异常捕获示例

try:
    result = api.rec_file("invalid_audio.mp3")
    if not result:
        print("识别结果为空，请检查音频文件")
except Exception as e:
    print(f"API调用失败: {str(e)}")
    # 重试逻辑或错误上报

5.3 服务端日志排查

服务端日志位于log.txt，关键错误信息包括：

模型加载失败：检查模型路径或ModelScope网络连接
端口占用：使用--port参数指定未占用端口
线程配置不当：调整--decoder-thread-num和--model-thread-num

6. 高级功能

6.1 时间戳输出

启用时间戳模型（如speech_paraformer-large-vad-punc_asr_nat）后，响应中将包含timestamp和stamp_sents字段：

{
  "timestamp": "[[100, 200], [200, 500]]",
  "stamp_sents": [{"text_seg": "你好", "start": 100, "end": 200}]
}

6.2 批量处理

通过wav.scp文件批量转录多个音频：

python funasr_wss_client.py --audio_in "wav.scp" --output_dir "./results"

wav.scp格式：

audio1 /path/to/audio1.wav
audio2 /path/to/audio2.wav

7. 性能优化

7.1 服务端配置

服务器规格	推荐线程数	并发能力
4核8GB	decoder-thread=8, model-thread=1	32路请求
16核32GB	decoder-thread=16, model-thread=2	64路请求

7.2 客户端优化

批量发送：减少WebSocket连接建立次数
音频预处理：统一采样率（16kHz）和位深（16bit）
异步调用：使用回调函数处理实时结果，避免阻塞主线程

8. 总结

FunASR语音识别API提供了灵活的参数配置和稳定的错误处理机制，支持从离线文件到实时流的多种应用场景。通过合理配置模型参数、优化网络传输和线程管理，可实现高效准确的语音转写服务。如需进一步定制，可参考自定义服务部署文档。

附录：模型下载地址

模型类型	ModelScope地址
基础ASR模型	damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-onnx
带时间戳模型	damo/speech_paraformer-large-vad-punc_asr_nat-zh-cn-16k-common-vocab8404-onnx
热词增强模型	damo/speech_paraformer-large-contextual_asr_nat-zh-cn-16k-common-vocab8404-onnx

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考