FunASR 离线语音转写服务部署与客户端开发实战

• 若需关闭 SSL，增加参数 --certfile 0。
• 若使用 SenseVoiceSmall 模型，设置 --model-dir 为对应模型 ID。
• 热词文件配置在宿主机 ./funasr-runtime-resources/models/hotwords.txt，Docker 映射地址为 /workspace/models/hotwords.txt。每行一个热词，格式为 (热词 权重)，例如 阿里巴巴 20。

日志示例： 服务启动时会下载模型并初始化，日志中会显示各模块加载状态。若遇到 ffmpeg is not installed 警告，可使用 torchaudio 加载音频，或安装 ffmpeg 以提升兼容性。

2.4 客户端测试与使用

下载客户端测试工具目录 samples：

wget https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/sample/funasr_samples.tar.gz

以 Python 语言客户端为例，支持多种音频格式（.wav, .pcm, .mp3 等）及视频输入：

python3 funasr_wss_client.py --host "127.0.0.1" --port 10095 --mode offline --audio_in "../audio/asr_example.wav"

运行结果： 终端将输出识别文本及字级别的时间戳信息。若出现 ModuleNotFoundError: No module named 'websockets'，请执行 pip install websockets==13.1 安装依赖。

3. 客户端用法详解

完成服务部署后，可通过以下步骤测试和使用离线文件转写服务。目前支持以下几种编程语言客户端：

3.1 Python Client

简易调用示例：

python3 funasr_wss_client.py --host "127.0.0.1" --port 10095 --mode offline \
--audio_in "../audio/asr_example.wav" --output_dir "./results"

关键参数：

• --host: 服务部署机器 IP，默认为本机。
• --port: 部署端口号，默认 10095。
• --mode: 设为 offline 表示离线文件转写。
• --audio_in: 音频文件路径或列表文件 wav.scp。
• --ssl: 是否开启 SSL 证书校验，默认 1 开启，0 关闭。
• --hotword: 热词文件路径。
• --use_itn: 是否使用 ITN，默认 1 开启。

效果对比： 在实际测试中，FunASR 对中文口语的识别准确率较高，能够修正部分口语化表达。相比 Whisper 等模型，FunASR 在特定中文场景下表现更为稳定，标点生成能力也较强。

3.2 C++ Client

进入 samples/cpp 目录进行测试：

./funasr-wss-client --server-ip 127.0.0.1 --port 10095 --wav-path ../audio/asr_example.wav

返回结果为 JSON 格式，包含识别文本、时间戳及分段信息。

3.3 HTML 网页版

在浏览器中打开 html/static/index.html，即可体验麦克风输入与文件上传功能。需输入 ASR 服务地址 wss://IP:10095/。

注意： 若遇到 TLS 握手失败错误，需在服务端启动时添加 --certfile 0 关闭 SSL，并将前端地址改为 ws://IP:10095/。

3.4 Java Client

FunasrWsClient --host localhost --port 10095 --audio_in ./asr_example.wav --mode offline

详细构建步骤可参考官方文档。Linux/Unix 环境下需先安装 OpenJDK 环境，然后编译运行。

4. 服务端用法详解

4.1 启动 FunASR 服务

cd /workspace/FunASR/runtime
nohup bash run_server.sh \
--download-model-dir /workspace/models \
--model-dir damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-onnx \
--vad-dir damo/speech_fsmn_vad_zh-cn-16k-common-onnx \
--punc-dir damo/punc_ct-transformer_cn-en-common-vocab471067-large-onnx \
--lm-dir damo/speech_ngram_lm_zh-cn-ai-wesp-fst \
--itn-dir thuduj12/fst_itn_zh \
--certfile ../../../ssl_key/server.crt \
--keyfile ../../../ssl_key/server.key \
--hotword ../../hotwords.txt > log.txt 2>&1 &

run_server.sh 命令参数介绍：

• --download-model-dir: 模型下载地址，支持 ModelScope ID。
• --model-dir, --vad-dir, --punc-dir, --lm-dir, --itn-dir: 各组件模型路径或 ModelScope ID。
• --port: 监听端口，默认 10095。
• --decoder-thread-num: 线程池个数，控制最大并发路数。
• --io-thread-num: IO 线程数。
• --model-thread-num: 推理线程数，建议 decoder-thread-num * model-thread-num 等于总线程数。
• --certfile, --keyfile: SSL 证书与密钥路径，设为 0 可关闭 SSL。
• --hotword: 热词文件路径，服务端热词全局生效。

4.2 关闭 FunASR 服务

ps -x | grep funasr-wss-server
kill -9 PID

4.3 修改模型及其他参数

替换模型或参数需先停止服务，修改配置后重新启动。若指定 ModelScope 中的 Model ID，服务会自动下载相应模型。

对于微调后的模型（如 10epoch.pb），需手动重命名为 model.pb 并替换原文件，指定 model_dir 路径即可。

5. 如何定制服务部署

FunASR-runtime 代码已开源，若标准服务无法满足需求，可进行二次开发。

• C++ 客户端: GitHub 仓库
• Python 客户端: GitHub 仓库
• 自定义客户端: 参考 WebSocket 通信协议文档。

C++ 服务端开发示例：

VAD 模型使用：

// VAD 模型的使用分为 FsmnVadInit 和 FsmnVadInfer 两个步骤
FUNASR_HANDLE vad_hanlde = FsmnVadInit(model_path, thread_num);
FUNASR_RESULT result = FsmnVadInfer(vad_hanlde, wav_file.c_str(), NULL, 16000);

ASR 模型使用：

// ASR 模型的使用分为 FunOfflineInit 和 FunOfflineInfer 两个步骤
FUNASR_HANDLE asr_hanlde = FunOfflineInit(model_path, thread_num);
FUNASR_RESULT result = FunOfflineInfer(asr_hanlde, wav_file.c_str(), RASR_NONE, NULL, 16000);

PUNC 模型使用：

// PUNC 模型的使用分为 CTTransformerInit 和 CTTransformerInfer 两个步骤
FUNASR_HANDLE punc_hanlde = CTTransformerInit(model_path, thread_num);
FUNASR_RESULT result = CTTransformerInfer(punc_hanlde, txt_str.c_str(), RASR_NONE, NULL);

更多示例详见官方 GitHub 仓库。