FunASR 实时语音听写服务开发指南2pass 流式/非流式协同部署与多语言客户端实战【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR本指南以 FunASR 开源仓库中的 runtime/docs/SDK_advanced_guide_online_zh.md 为骨架系统讲解实时语音听写服务online / offline / 2pass的 Docker 部署、run_server_2pass.sh服务端参数调优、热词与 SSL 配置以及 Python / C / HTML / Java / C# 五种客户端的使用方法。读者读完本文可以在本地或云端服务器上独立完成一套支持高并发多路请求、带标点输出、句尾离线纠错的实时语音转写服务并掌握从源码构建镜像、替换模型、编译 runtime 等进阶能力。一、服务整体架构与三种服务模式FunASR 实时语音听写软件包集成了达摩院语音实验室在 ModelScope 社区开源的多个模型能力FSMN-VAD实时语音端点检测定位说话起始与结束输出非静音语音段Paraformer-large 流式 ASRonline以固定间隔实时产出识别文字Paraformer-large 非流式 ASRoffline在说话句尾用高精度转写文字修正输出CT-Transformer 标点预测PUNC为识别结果补全标点ITN逆文本正则化将数字、日期、金额等口语化表达还原为书面格式Ngram 语言模型LM与 FST 热词提升特定领域识别准确率。各模型在服务中协同工作其流程关系如架构图所示客户端音频进入消息队列后FSMN-VAD 实时端点检测模块将非静音段间隔约 600ms交给 Paraformer-online 流式识别产生实时文字当 VAD 检测到句尾时完整语音段交给 Paraformer-offline 非流式识别再经 CT-Transformer 标点预测与 ITN 修正后回传客户端实现实时出字 句尾纠错的效果。依据使用场景不同服务支持三种模式模式说明online实时语音识别边说话边出字延迟低offline非实时一句话转写等语音结束后一次性返回高精度结果2pass实时语音识别 说话句尾采用离线模型纠错兼顾实时性与准确性是本软件包默认推荐模式。模式由客户端--mode参数指定服务端本身同时加载流式与非流式两套 ASR 模型因此一套部署即可支持全部三种模式。镜像版本演进官方持续维护 online CPU 运行时镜像funasr-runtime-sdk-online-cpu-*主要版本更新如下时间详情镜像版本镜像ID2024.10.292pass-offline模式支持SenseVoiceSmall模型funasr-runtime-sdk-online-cpu-0.1.12f5febc5cf13a2024.09.26修复内存泄漏funasr-runtime-sdk-online-cpu-0.1.11e51a36c427712024.05.15适配FunASR 1.0模型结构funasr-runtime-sdk-online-cpu-0.1.101c2adfcff84d2024.03.05docker镜像支持arm64平台升级modelscope版本funasr-runtime-sdk-online-cpu-0.1.94a875e08c7a22024.01.25客户端优化funasr-runtime-sdk-online-cpu-0.1.72aa23805572e2024.01.032pass-offline模式支持Ngram语言模型解码、wfst热词修复crash及内存泄漏funasr-runtime-sdk-online-cpu-0.1.6f99925110d272023.11.09修复无实时结果问题funasr-runtime-sdk-online-cpu-0.1.5b16584b6d38b2023.11.08支持服务端加载热词更新热词通信协议、runtime结构变化适配funasr-runtime-sdk-online-cpu-0.1.4691974017c382023.09.192pass模式支持热词、时间戳、ITN模型funasr-runtime-sdk-online-cpu-0.1.27222c5319bcf2023.08.11修复部分已知bug包括server崩溃等funasr-runtime-sdk-online-cpu-0.1.1bdbdd0b27dee2023.08.071.0 发布funasr-runtime-sdk-online-cpu-0.1.0bdbdd0b27dee二、快速上手基于 Docker 部署1. 安装 Docker如果服务器尚未安装 Docker先执行一键安装脚本curl -O https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/shell/install_docker.sh sudo bash install_docker.shDocker 安装失败可参考仓库内的 docs/installation/docker.md 进行排查。2. 拉取并启动官方镜像sudo docker pull \ registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.13 mkdir -p ./funasr-runtime-resources/models sudo docker run -p 10096:10095 -it --privilegedtrue \ -v $PWD/funasr-runtime-resources/models:/workspace/models \ registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.13说明-p 10096:10095将宿主机 10096 端口映射到容器内服务监听端口 10095-v $PWD/funasr-runtime-resources/models:/workspace/models将宿主机目录挂载为模型下载目录模型会自动下载并持久化到该目录避免每次启动重复下载--privilegedtrue为容器提供必要权限部分环境用于模型文件与设备访问。3. 从源码构建 online CPU 镜像上面 0.1.13 是公开预构建版本。如果需要基于当前 FunASR 源码自行构建使用仓库内的 runtime/dockerfile/Dockerfile.online.cpugit clone https://github.com/modelscope/FunASR.git cd FunASR docker build \ -f runtime/dockerfile/Dockerfile.online.cpu \ -t funasr-online-cpu:local . mkdir -p ./funasr-runtime-resources/models docker run --rm -p 10096:10095 \ -v $PWD/funasr-runtime-resources/models:/workspace/models \ funasr-online-cpu:local该 Dockerfile 将公开的 0.1.13 多架构镜像按 manifest digest 固定为编译与运行工具链然后复制当前 checkout 并重新编译funasr-wss-server-2pass。构建出的容器会直接在 10095 端口启动服务不依赖预构建镜像中的交互式 daemon 包装。构建产物与启动方式可通过 online-cpu-entrypoint.sh 中定义的环境变量覆盖环境变量作用默认值FUNASR_MODEL_DIR非流式offlineASR 模型damo/speech_paraformer-large-vad-punc_asr_nat-zh-cn-16k-common-vocab8404-onnxFUNASR_ONLINE_MODEL_DIR流式onlineASR 模型damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-online-onnxFUNASR_VAD_DIRVAD 端点检测模型damo/speech_fsmn_vad_zh-cn-16k-common-onnxFUNASR_PUNC_DIR标点预测模型damo/punc_ct-transformer_zh-cn-common-vad_realtime-vocab272727-onnxFUNASR_ITN_DIRITN 逆文本正则化模型thuduj12/fst_itn_zhFUNASR_LM_DIRNgram 语言模型damo/speech_ngram_lm_zh-cn-ai-wesp-fstFUNASR_DECODER_THREAD_NUM解码线程数最大并发路数按nproc自动探测FUNASR_IO_THREAD_NUMIO 线程数(decoder_threads 15) / 16FUNASR_MODEL_THREAD_NUM每路识别的内部线程数1FUNASR_PORT容器内服务监听端口10095FUNASR_HOTWORD_FILE热词文件路径${model_root}/hotwords.txt4. 一键部署工具便捷方式仓库 runtime/deploy_tools/funasr-runtime-deploy-online-cpu-zh.sh 提供了交互式一键部署自动完成安装 Docker、拉取镜像、选择模型、映射端口并启动服务全程仅需在提示处输入回车。目前该工具暂时仅支持 Linux 环境sudo bash funasr-runtime-deploy-online-cpu-zh.sh install --workspace ./funasr-runtime-resources部署完成后可用start/stop/restart/remove子命令管理服务用update子命令替换模型或更新端口、线程数、SSL 等参数详见 runtime/docs/SDK_tutorial_online_zh.md。三、服务端启动与参数详解Docker 启动后进入容器执行服务端启动脚本 runtime/run_server_2pass.sh。该脚本位于仓库runtime/目录实际拉起的是 C 编译产物funasr-wss-server-2pass。1. 完整启动命令cd FunASR/runtime nohup bash run_server_2pass.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 \ --online-model-dir damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-online-onnx \ --punc-dir damo/punc_ct-transformer_zh-cn-common-vad_realtime-vocab272727-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 21 如果希望关闭 SSL增加参数--certfile 0如果希望使用SenseVoiceSmall 模型、时间戳或nn 热词模型部署请将--model-dir设置为对应模型iic/SenseVoiceSmall-onnxSenseVoiceSmall识别结果中|zh|、|NEUTRAL|、|Speech|分别为语种、情感、事件信息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-onnxnn 热词服务端加载热词在宿主机文件./funasr-runtime-resources/models/hotwords.txt中配置docker 映射地址为/workspace/models/hotwords.txt每行一个热词格式为热词 权重例如阿里巴巴 20。热词理论上无限制但为兼顾性能与效果建议热词长度不超过 10、个数不超过 1k、权重取值 1~100。仓库默认热词文件示例见 runtime/websocket/hotwords.txt。2. run_server_2pass.sh 参数一览--download-model-dir 模型下载地址通过设置 model ID 从 ModelScope 下载模型 --model-dir modelscope model ID 或者本地模型路径非流式 ASR --online-model-dir modelscope model ID 或者本地模型路径流式 ASR --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 如果客户端提供热词则与客户端提供的热词合并使用 服务端热词全局生效客户端热词只针对对应客户端生效。3. 线程模型并发能力的核心从 run_server_2pass.sh 源码可以看到服务端线程的默认推导逻辑decoder_thread_num$(cat /proc/cpuinfo | grep processor|wc -l) multiple_io16 io_thread_num$(( (decoder_thread_num multiple_io - 1) / multiple_io )) model_thread_num1即decoder-thread-num 默认等于服务器 CPU 逻辑核数io-thread-num 按每 16 个解码线程配 1 个 IO 线程推算。decoder-thread-num决定服务端线程池大小即最大并发路数model-thread-num控制每路识别内部的 ONNX 模型并行度。调优时建议满足decoder-thread-num * model-thread-num ≈ 服务器总线程数避免线程争抢导致吞吐下降。4. 关闭服务# 查看 funasr-wss-server-2pass 对应的 PID ps -x | grep funasr-wss-server-2pass kill -9 PID5. 修改模型及其他参数替换正在使用的模型或参数需先关闭 FunASR 服务修改后重新启动# 例如替换 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 中的 ASR/VAD/PUNC 模型或从 ModelScope 模型 finetune 后的模型。指定 ModelScope model id 时服务会自动下载对应模型含 FSMN-VAD、Paraformer-large 实时/非实时、CT-Transformer 标点、基于 FST 的中文 ITN 等。部署 finetune 后模型的要点如果希望部署自己 finetune 的模型例如10epoch.pb需要手动将模型重命名为model.pb替换原 ModelScope 模型目录下的model.pb并将--model-dir等参数指向该本地模型目录。四、客户端测试与使用服务部署完成后下载客户端测试工具目录sampleswget https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/sample/funasr_samples.tar.gzsamples 中包含 Python、Linux C 等客户端支持音频文件.wav、.pcm以及多文件列表wav.scp输入。以下分别介绍各语言客户端。1. Python 客户端python3 funasr_wss_client.py --host 127.0.0.1 --port 10096 --mode 2pass客户端源码位于 runtime/python/websocket/funasr_wss_client.py其命令行参数说明--host FunASR runtime-SDK 服务部署机器 ip默认为本机 ip127.0.0.1 如果 client 与服务不在同一台服务器需要改为部署机器 ip --port 部署端口号示例中为 10096对应服务端 10095 的宿主机映射 --mode offline 表示推理模式为一句话识别online 表示推理模式为实时语音识别 2pass 表示实时语音识别并且说话句尾采用离线模型进行纠错 --chunk_size 流式模型 latency 配置 [5,10,5]表示当前音频解码片段为 600ms 并且回看 300ms、右看 300ms源码默认 5, 10, 5 --audio_in 需要进行转写的音频文件支持文件路径、文件列表 wav.scp 不传则使用麦克风输入需安装 PyAudio --audio_fs 音频采样率默认 16000 --thread_num 设置并发发送线程数默认为 1 --ssl 设置是否开启 ssl 证书校验默认 1 开启设置为 0 关闭 --hotword 热词文件每行一个热词格式热词 权重阿里巴巴 20 --use_itn 设置是否使用 itn默认 1 开启设置为 0 关闭此外源码还支持--result_timeout等待服务端结束确认的最长秒数默认 300.0、--output_dir结果输出目录、--words_max_print打印字数上限等参数可用于自动化转写与压测场景。2. C 客户端./funasr-wss-client-2pass --server-ip 127.0.0.1 --port 10096 --mode 2pass \ --wav-path ../audio/asr_example.pcm--server-ip FunASR runtime-SDK 服务部署机器 ip默认为本机 ip127.0.0.1 如果 client 与服务不在同一台服务器需要改为部署机器 ip --port 部署端口号 --mode offline / online / 2pass含义同 Python 客户端 --chunk-size 流式模型 latency 配置 [5,10,5] --record 1 表示使用麦克风作为输入默认为 0 --wav-path 需要进行转写的音频文件支持文件路径 --audio-fs pcm 音频采样率 --thread-num 设置并发发送线程数默认为 1 --is-ssl 设置是否开启 ssl 证书校验默认 1 开启设置为 0 关闭 --hotword 热词文件每行一个热词格式热词 权重阿里巴巴 20 --use-itn 设置是否使用 itn默认 1 开启设置为 0 关闭3. HTML 网页客户端在浏览器中打开html/static/index.html即可通过网页进行体验支持麦克风输入与文件上传适合快速演示与内部工具集成。4. Java 客户端FunasrWsClient --host localhost --port 10096 --mode 2pass详细用法参考 runtime/java/readme.md。5. C# 客户端C# 客户端使用方式详见 runtime/docs/SDK_tutorial_online_zh.md与 Java 客户端命令风格一致。更多版本客户端支持含 websocket/grpc 协议细节可参考 runtime/docs/websocket_protocol_zh.md。五、底层原理与源码佐证1. runtime 编译Linux/Unixdocker 镜像内的funasr-wss-server-2pass由 C runtime 编译而来。如需自行编译例如定制模型或调试可参考 runtime/websocket/readme_zh.md# 下载 onnxruntimex64 Linux 1.14.0与 ffmpeg shared 库并解压 # 安装依赖libopenblas-devubuntu或 openblas-develcentoslibssl-dev 或 openssl-devel git clone https://github.com/modelscope/FunASR.git cd FunASR/runtime/websocket mkdir build cd build cmake -DCMAKE_BUILD_TYPErelease .. \ -DONNXRUNTIME_DIR/path/to/onnxruntime-linux-x64-1.14.0 \ -DFFMPEG_DIR/path/to/ffmpeg-master-latest-linux64-gpl-shared make -j 4Windows 平台编译可参考 runtime/websocket/readme_zh.md 中关于 onnxruntime-win-x64、ffmpeg-win64 与 openssl 的配置说明。从源码构建镜像时runtime/dockerfile/Dockerfile.online.cpu 中同样通过cmake -S runtime/websocket -B runtime/websocket/build完成编译并针对 amd64 / arm64 分别选择对应的 onnxruntime 与 ffmpeg 工具链。2. 服务端可执行程序与 SSL服务端实际二进制为funasr-wss-server-2passSSL 证书默认路径为../../../ssl_key/server.crt与../../../ssl_key/server.key对应仓库 runtime/ssl_key 目录。当--certfile 0时脚本会清空 certfile/keyfile 以关闭 SSL。客户端侧可通过--ssl 0/--is-ssl 0对应关闭证书校验。3. 热词的两种生效机制服务端热词通过--hotword指向热词文件全局生效对所有客户端请求有效客户端热词客户端通过--hotword参数附带仅对当前客户端请求生效两者同时存在时自动合并使用。服务端热词通信协议在 0.1.4 版本起已更新见版本历史表实现细节可参考 runtime/docs/websocket_protocol_zh.md。六、注意事项与常见问题端口映射docker 容器内服务默认监听 10095启动容器时通过-p映射到宿主机对外端口如 10096客户端--port需填写宿主机对外端口。模型持久化建议将宿主机目录挂载到/workspace/models避免容器销毁后重新下载模型模型也可直接指定为本地路径。并发能力估算decoder-thread-num默认为 CPU 核数即单机最大并发路数约等于核数如需更高并发需配合 IO 线程与模型线程decoder * model ≈ 总线程数综合调优。SSL 关闭内网或测试环境可通过服务端--certfile 0与客户端--ssl 0同时关闭 SSL降低握手开销。finetune 模型替换必须将 finetune 产物重命名为model.pb并替换原目录同名文件再将--model-dir指向该目录。热词约束建议热词长度不超过 10、个数不超过 1k、权重 1~100兼顾性能与效果权重越高命中时得分加成越大。SenseVoiceSmall 输出语义使用iic/SenseVoiceSmall-onnx时识别结果中的|zh|、|NEUTRAL|、|Speech|分别对应语种、情感、事件信息解析时需按此约定处理。通过以上步骤即可在本地或云端服务器完成一套功能完整的 FunASR 实时语音听写服务既能在说话过程中实时出字又能在句尾用高精度离线模型纠错输出带标点的规范文本并支持多路并发请求与多语言客户端接入。【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考