FunASR 离线文件转写服务开发指南

如果您想在服务端加载热词，请在宿主机文件 ./funasr-runtime-resources/models/hotwords.txt 配置热词（docker 映射地址为 /workspace/models/hotwords.txt）：

• 每行一个热词，格式 (热词 权重)：阿里巴巴 20（注：热词理论上无限制，但为了兼顾性能和效果，建议热词长度不超过 10，个数不超过 1k，权重 1~100）
• SenseVoiceSmall-onnx 识别结果中'<|zh|><|NEUTRAL|><|Speech|>'分别为对应的语种、情感、事件信息

服务启动时容器内的日志信息示例：

root@485ac2db1a1a:/workspace/FunASR/runtime# tail -f log.txt
warn(RuntimeWarning(msg))
2026-03-03 10:45:35,638 - modelscope - INFO - Use user-specified model revision: v2.0.5
Notice: ffmpeg is not installed. torchaudio is used to load audio
If you want to use ffmpeg backend to load audio, please install it by: sudo apt install ffmpeg # ubuntu
Download [am.mvn]: 100%|██████████|10.9k/10.9k [00:00<00:00, 50.2kB/s]
...
I20260303 11:01:52.311225 56 funasr-wss-server.cpp:516] asr model init finished. listen on port:10095

如果您想定制 ngram，参考文档。如果您想部署 8k 的模型，请使用如下命令启动服务：

cd FunASR/runtime
nohup bash run_server.sh \
--download-model-dir /workspace/models \
--vad-dir damo/speech_fsmn_vad_zh-cn-8k-common-onnx \
--model-dir damo/speech_paraformer_asr_nat-zh-cn-8k-common-vocab8358-tensorflow1-onnx \
--punc-dir damo/punc_ct-transformer_cn-en-common-vocab471067-large-onnx \
--lm-dir damo/speech_ngram_lm_zh-cn-ai-wesp-fst-token8358 \
--itn-dir thuduj12/fst_itn_zh \
--hotword /workspace/models/hotwords.txt > log.txt 2>&1 &

2.4 客户端测试与使用

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

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

我们以 Python 语言客户端为例，进行说明，支持多种音频格式输入（.wav, .pcm, .mp3 等），也支持视频输入 (.mp4 等)，以及多文件列表 wav.scp 输入。

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

运行结果：

Namespace(host='127.0.0.1', port=10095, chunk_size=[5, 10, 5], chunk_interval=10, hotword='', audio_in='../audio/asr_example.wav', audio_fs=16000, send_without_sleep=True, thread_num=1, words_max_print=10000, output_dir=None, ssl=1, use_itn=1, mode='offline')
connect to wss://127.0.0.1:10095
pid0_0: demo: 欢迎大家来体验达摩院推出的语音识别模型。
timestamp: [[880,1120],[1120,1380],[1380,1540],[1540,1780],[1780,2020],[2020,2180],[2180,2480],[2480,2600],[2600,2780],[2780,3040],[3040,3240],[3240,3480],[3480,3699],[3699,3900],[3900,4180],[4180,4420],[4420,4620],[4620,4780],[4780,5195]]
Exception: sent 1000(OK);then received 1000(OK) end

异常问题处理：

# 启动时的报错信息
Traceback (most recent call last):
  File "/home/jsgx/funasr/samples/python/funasr_wss_client.py", line 4, in <module>
    import websockets, ssl
ModuleNotFoundError: No module named 'websockets'
# 1. 安装 websockets
pip install websockets
# 2. 安装兼容性较好的指定版本
pip install websockets==13.1

3.客户端用法详解

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

• Python
• CPP
• html 网页版本
• Java

3.1 python-client

若想直接运行 client 进行测试，可参考如下简易说明，以 python 版本为例：

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

命令参数说明：

• --host: 为 FunASR runtime-SDK 服务部署机器 ip，默认为本机 ip（127.0.0.1），如果 client 与服务不在同一台服务器，需要改为部署机器 ip
• --port: 10095 部署端口号
• --mode: offline 表示离线文件转写
• --audio_in: 需要进行转写的音频文件，支持文件路径，文件列表 wav.scp
• --thread_num: 设置并发发送线程数，默认为 1
• --ssl: 设置是否开启 ssl 证书校验，默认 1 开启，设置为 0 关闭
• --hotword: 热词文件，每行一个热词，格式 (热词 权重)：阿里巴巴 20
• --use_itn: 设置是否使用 itn，默认 1 开启，设置为 0 关闭

对比测试结果：

# 上点儿强度也测试一下 mp3 格式
python3 funasr_wss_client.py --host "127.0.0.1" --port 10095 --mode offline \
--audio_in "./whisperTest.mp3" --output_dir "./results"

3.2 cpp-client

进入 samples/cpp 目录后，可以用 cpp 进行测试，指令如下：

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

命令参数说明：

• --server-ip: 为 FunASR runtime-SDK 服务部署机器 ip，默认为本机 ip（127.0.0.1）
• --port: 10095 部署端口号
• --wav-path: 需要进行转写的音频文件，支持文件路径
• --hotword: 热词文件，每行一个热词，格式 (热词 权重)：阿里巴巴 20
• --thread-num: 设置客户端线程数
• --use-itn: 设置是否使用 itn，默认 1 开启，设置为 0 关闭

执行结果：

{"is_final":false,"mode":"offline","stamp_sents":[{"end":5195,"punc":"。","start":880,"text_seg":"欢 迎 大 家 来 体 验 达 摩 院 推 出 的 语 音 识 别 模 型","ts_list":[[880,1120],[1120,1380],[1380,1540],[1540,1780],[1780,2020],[2020,2180],[2180,2480],[2480,2600],[2600,2780],[2780,3040],[3040,3240],[3240,3480],[3480,3699],[3699,3900],[3900,4180],[4180,4420],[4420,4620],[4620,4780],[4780,5195]]}],"text":"欢迎大家来体验达摩院推出的语音识别模型。","timestamp":"[[880,1120],[1120,1380],[1380,1540],[1540,1780],[1780,2020],[2020,2180],[2180,2480],[2480,2600],[2600,2780],[2780,3040],[3040,3240],[3240,3480],[3480,3699],[3699,3900],[3900,4180],[4180,4420],[4420,4620],[4620,4780],[4780,5195]]","wav_name":"wav_default_id"}

3.3 Html 网页版

在浏览器中打开 html/static/index.html，即可出现如下页面，支持麦克风输入与文件上传，直接进行体验，需要输入 asr 服务地址 wss://IP:10095/。

报错信息处理：

[2026-03-03 14:01:36][error] handle_transport_init received error: TLS handshake failed

关掉 SSL 重新启动 funasr 服务：

cd FunASR/runtime
nohup bash run_server.sh \
--download-model-dir /workspace/models \
--vad-dir damo/speech_fsmn_vad_zh-cn-16k-common-onnx \
--model-dir damo/speech_paraformer-large-vad-punc_asr_nat-zh-cn-16k-common-vocab8404-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 0 \
--hotword /workspace/models/hotwords.txt > log.txt 2>&1 &

asr 地址也需要改为 ws://IP:10095/。

3.4 Java-client

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

详细可以参考文档。

3.4.1 Building for Linux/Unix

1. install java environment

# in ubuntu
apt-get install openjdk-11-jdk

2. Build and run by make

cd funasr/runtime/java
# download java lib
make downjar
# compile
make buildwebsocket
# run client
make runclient

3. Run java websocket client by shell

# full command refer to Makefile runclient usage:
FunasrWsClient [-h][--port PORT][--host HOST][--audio_in AUDIO_IN][--num_threads NUM_THREADS][--chunk_size CHUNK_SIZE][--chunk_interval CHUNK_INTERVAL][--mode MODE]
Where:
--host<string>(required) server-ip
--port<int>(required) port
--audio_in<string>(required) the wav or pcm file path
--num_threads<int> thread number for test
--mode asr mode, support "offline" "online" "2pass"
example: FunasrWsClient --host localhost --port 8889 --audio_in ./asr_example.wav --num_threads 1 --mode 2pass
result json, example like: {"mode":"offline","text":"欢迎大家来体验达摩院推出的语音识别模型","wav_name":"javatest"}

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: 模型下载地址，通过设置 model ID 从 Modelscope 下载模型
• --model-dir: modelscope model ID 或者 本地模型路径
• --vad-dir: modelscope model ID 或者 本地模型路径
• --punc-dir: modelscope model ID 或者 本地模型路径
• --lm-dir: modelscope model ID 或者 本地模型路径
• --itn-dir: modelscope model ID 或者 本地模型路径
• --port: 服务端监听的端口号，默认为 10095
• --decoder-thread-num: 服务端线程池个数 (支持的最大并发路数)，脚本会根据服务器线程数自动配置 decoder-thread-num、io-thread-num
• --io-thread-num: 服务端启动的 IO 线程数
• --model-thread-num: 每路识别的内部线程数 (控制 ONNX 模型的并行)，默认为 1，其中建议 decoder-thread-num*model-thread-num 等于总线程数
• --certfile: ssl 的证书文件，默认为：../../../ssl_key/server.crt，如果需要关闭 ssl，参数设置为 0
• --keyfile: ssl 的密钥文件，默认为：../../../ssl_key/server.key
• --hotword: 热词文件路径，每行一个热词，格式：热词 权重 (例如：阿里巴巴 20)，如果客户端提供热词，则与客户端提供的热词合并一起使用，服务端热词全局生效，客户端热词只针对对应客户端生效。

4.2 关闭 FunASR 服务

# 查看 funasr-wss-server 对应的 PID
ps -x | grep funasr-wss-server
kill -9 PID

4.3 修改模型及其他参数

替换正在使用的模型或者其他参数，需先关闭 FunASR 服务，修改需要替换的参数，并重新启动 FunASR 服务。其中模型需为 ModelScope 中的 ASR/VAD/PUNC 模型，或者从 ModelScope 中模型 finetune 后的模型。

# 例如替换 ASR 模型为 damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-onnx，则如下设置参数
--model-dir damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-onnx
# 设置端口号
--port <port number>
# 设置服务端启动的推理线程数
--decoder-thread-num <decoder thread num>
# 设置服务端启动的 IO 线程数
--io-thread-num <io thread num>
# 关闭 SSL 证书
--certfile 0

执行上述指令后，启动离线文件转写服务。如果模型指定为 ModelScope 中 model id，会自动从 ModelScope 中下载相关模型。

如果，您希望部署您 finetune 后的模型（例如 10epoch.pb），需要手动将模型重命名为 model.pb，并将原 modelscope 中模型 model.pb 替换掉，将路径指定为 model_dir 即可。

5.如何定制服务部署

FunASR-runtime 的代码已开源，如果服务端和客户端不能很好的满足您的需求，您可以根据自己的需求进行进一步的开发：

• c++ 客户端：https://github.com/alibaba-damo-academy/FunASR/tree/main/runtime/websocket
• python 客户端：https://github.com/alibaba-damo-academy/FunASR/tree/main/runtime/python/websocket
• 自定义客户端：如果您想定义自己的 client，参考 websocket 通信协议

c++ 服务端：

VAD

// VAD 模型的使用分为 FsmnVadInit 和 FsmnVadInfer 两个步骤：
FUNASR_HANDLE vad_hanlde = FsmnVadInit(model_path, thread_num);
// 其中：model_path 包含"model-dir"、"quantize"，thread_num 为 onnx 线程数；
FUNASR_RESULT result = FsmnVadInfer(vad_hanlde, wav_file.c_str(), NULL, 16000);
// 其中：vad_hanlde 为 FunOfflineInit 返回值，wav_file 为音频路径，sampling_rate 为采样率 (默认 16k)

使用示例详见：https://github.com/alibaba-damo-academy/FunASR/blob/main/runtime/onnxruntime/bin/funasr-onnx-offline-vad.cpp

ASR

// ASR 模型的使用分为 FunOfflineInit 和 FunOfflineInfer 两个步骤：
FUNASR_HANDLE asr_hanlde = FunOfflineInit(model_path, thread_num);
// 其中：model_path 包含"model-dir"、"quantize"，thread_num 为 onnx 线程数；
FUNASR_RESULT result = FunOfflineInfer(asr_hanlde, wav_file.c_str(), RASR_NONE, NULL, 16000);
// 其中：asr_hanlde 为 FunOfflineInit 返回值，wav_file 为音频路径，sampling_rate 为采样率 (默认 16k)

使用示例详见：https://github.com/alibaba-damo-academy/FunASR/blob/main/runtime/onnxruntime/bin/funasr-onnx-offline.cpp

PUNC

// PUNC 模型的使用分为 CTTransformerInit 和 CTTransformerInfer 两个步骤：
FUNASR_HANDLE punc_hanlde = CTTransformerInit(model_path, thread_num);
// 其中：model_path 包含"model-dir"、"quantize"，thread_num 为 onnx 线程数；
FUNASR_RESULT result = CTTransformerInfer(punc_hanlde, txt_str.c_str(), RASR_NONE, NULL);
// 其中：punc_hanlde 为 CTTransformerInit 返回值，txt_str 为文本

使用示例详见：https://github.com/alibaba-damo-academy/FunASR/blob/main/runtime/onnxruntime/bin/funasr-onnx-offline-punc.cpp