FunASR 离线文件转写服务的部署与使用指南。内容包括通过 Docker 安装环境、启动服务端服务、配置模型参数，以及 Python、C++、Java 和 HTML 客户端的调用方法。详细说明了热词设置、SSL 证书配置及自定义服务部署流程，适用于语音识别场景下的离线音频转写需求。
FunASR (Automatic Speech Recognition，自动语音识别) 离线文件转写软件包，提供了一款功能强大的语音离线文件转写服务。拥有完整的语音识别链路，结合了语音端点检测、语音识别、标点等模型，可以将几十个小时的长音频与视频识别成带标点的文字，而且支持上百路请求同时进行转写。输出为带标点的文字，含有字级别时间戳，支持 ITN 与用户自定义热词等。服务端集成有 ffmpeg，支持各种音视频格式输入。软件包提供有 html、python、c++、java 与 c#等多种编程语言客户端，用户可以直接使用与进一步开发。
推荐配置为：
官网推荐的安装方式：
# 下载安装脚本
curl -O https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/shell/install_docker.sh
# 执行安装命令
sudo bash install_docker.sh
通过下述命令拉取并启动 FunASR 软件包的 docker 镜像：
# 拉取镜像
sudo docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-cpu-0.4.7
# 创建资源文件夹
mkdir -p ./funasr-runtime-resources/models
# 交互式启动容器
sudo docker run -p 10095:10095 -it --privileged=true \
-v $PWD/funasr-runtime-resources/models:/workspace/models \
registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-cpu-0.4.7
docker 启动之后，进入到 docker 里边启动 funasr-wss-server 服务程序：
# 容器内的操作
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 \
--hotword /workspace/models/hotwords.txt > log.txt 2>&1 &
# 如果您想关闭 ssl，增加参数：--certfile 0
# 如果您想使用 SenseVoiceSmall 模型、时间戳、nn 热词模型进行部署，请设置--model-dir 为对应模型：
# iic/SenseVoiceSmall-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（nn 热词）
# 如果您想在服务端加载热词，请在宿主机文件./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
...
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 &
服务端详细参数介绍可参考官方文档。
下载客户端测试工具目录 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
在服务器上完成 FunASR 服务部署以后，可以通过如下的步骤来测试和使用离线文件转写服务。目前分别支持以下几种编程语言客户端：
若想直接运行 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 关闭
进入 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），如果 client 与服务不在同一台服务器，需要改为部署机器 ip
--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"}
在浏览器中打开 html/static/index.html，即可出现如下页面，支持麦克风输入与文件上传，直接进行体验，需要输入 asr 服务地址 wss://IP:10095/：
报错信息：
I20260303 14:01:36.164183 530 websocket-server.cpp:29] on_tls_init called with hdl: 0x7fb98c010ac0
I20260303 14:01:36.164292 530 websocket-server.cpp:30] using TLS mode: Mozilla Intermediate
[2026-03-03 14:01:36][error] handle_transport_init received error: TLS handshake failed
[2026-03-03 14:01:36][info] asio async_shutdown error: asio.ssl:336462231 (shutdown whilein init (SSL routines, SSL_shutdown))
关掉 SSL 重新启动 funasr 服务：
# 如果您想关闭 ssl，增加参数：--certfile 0
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/。
FunasrWsClient --host localhost --port 10095 --audio_in ./asr_example.wav --mode offline
详细可以参考文档。
# in ubuntu
apt-get install openjdk-11-jdk
cd funasr/runtime/java
# download java lib
make downjar
# compile
make buildwebsocket
# run client
make runclient
# 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"}
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)，如果客户端提供热词，则与客户端提供的热词合并一起使用，服务端热词全局生效，客户端热词只针对对应客户端生效。
# 查看 funasr-wss-server 对应的 PID
ps -x | grep funasr-wss-server
kill -9 PID
替换正在使用的模型或者其他参数，需先关闭 FunASR 服务，修改需要替换的参数，并重新启动 FunASR 服务。其中模型需为 ModelScope 中的 ASR/VAD/PUNC 模型，或者从 ModelScope 中模型 finetune 后的模型。
# 例如替换 ASR 模型为 damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-onnx，则如下设置参数 --model-dir
--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 中下载如下模型：FSMN-VAD 模型，Paraformer-lagre 模型，CT-Transformer 标点预测模型，基于 FST 的中文 ITN，Ngram 中文语言模型。
如果，您希望部署您 finetune 后的模型（例如 10epoch.pb），需要手动将模型重命名为 model.pb，并将原 modelscope 中模型 model.pb 替换掉，将路径指定为 model_dir 即可。
FunASR-runtime 的代码已开源，如果服务端和客户端不能很好的满足您的需求，您可以根据自己的需求进行进一步的开发：
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)
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)
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 为文本
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online