FunASR 运行时部署指南：服务路径选型、离线/实时转写部署与上线检查清单-酒店常州论坛

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

FunASR 的runtime目录聚合了面向生产环境的运行时部署方案：从离线文件转写、实时语音听写（含 2pass 双遍纠错）到 OpenAI 兼容服务、vLLM 加速、llama.cpp GGUF 推理等。本文以仓库中的运行时部署指南为骨架，结合一键部署脚本、服务启动脚本、WebSocket 协议文档与 Python 流式服务源码，完整讲解服务路径如何选型、四种转写服务如何部署与验证，以及上线前必须完成的检查项。

先决策再动手：确定模型与协议，再选容器或二进制包

FunASR 运行时部署的第一原则是先确定模型和协议，再选择容器或二进制包。模型决定识别能力与精度边界，协议决定接入方式（HTTP、WebSocket、gRPC、Triton 等），两者共同决定最终选择哪个部署入口。整体选型可参考仓库根目录下的部署矩阵。

同时需要特别注意两点：

固定版本再部署：给出固定版本命令、验证硬件和已知限制，避免"最新即最佳"的假设；
历史记录不构成当前容量承诺：旧发布说明保留在历史记录中，只作为演进参考，不能直接当作当前服务的容量承诺使用。

下表完整列出runtime/readme_cn.md给出的服务路径与边界说明：

需求	入口	边界
Python HTTP 转写	OpenAI 兼容服务	API 兼容、模型质量和实时能力是不同问题。
Fun-ASR-Nano 解码加速	vLLM 指南	原生 vLLM 与 FunASR split-engine 的权重布局和接口契约不同。
本地便携 GGUF 推理	llama.cpp	使用匹配的平台/后端包和 GGUF 模型；构建成功不等于所有设备验证通过。
原生 ONNX CPU 推理	ONNX Runtime	输出字段见 JSONL 与时间戳契约。
统一离线转写与说话人分离	MOSS-Transcribe-Diarize	OpenMOSS 第三方模型，输出匿名说话人标签，不是实时或已知人物身份识别。
长连接流式 / 双遍会话	C++ WebSocket 协议	不能向该端点发送 OpenAI HTTP 请求或其他实现的 WebSocket 消息。
集群内私有 HTTP 服务	Kubernetes 模板	按目标集群配置资源、持久缓存、探针、上传限制和网关策略。

各路径的适用场景解读

OpenAI 兼容服务面向希望以标准 Chat Completions 风格接入的团队，注意"API 兼容"不等于"模型质量等价"，也不同于实时能力，需按实际任务评测；
vLLM 指南面向 Fun-ASR-Nano 的高吞吐解码加速，但原生 vLLM 与 FunASR split-engine 在权重布局和接口契约上并不相同，不能混用；
llama.cpp GGUF主打本地便携推理，必须使用匹配的平台/后端包与对应 GGUF 模型；
ONNX Runtime是纯 CPU 原生推理路径，输出字段格式（含时间戳契约）需以 onnxruntime_binary_output_zh.md 为准；
C++ WebSocket 服务是低延迟流式与双遍（2pass）会话的主入口，协议与其他端点互不通用；
Kubernetes 模板适合集群内私有 HTTP 服务，需自行配置资源、持久缓存、探针、上传限制和网关策略。

中文离线文件转写服务（GPU 版本）

GPU 版本面向需要更高吞吐的离线文件转写场景。部署时按 GPU 部署开发指南配置原生运行时。

需要特别强调的是：它不是 Model Zoo 中每个模型的通用安装方法。每个模型可能有不同的权重格式、前后处理或 ONNX 算子支持情况，因此文档明确要求"用实际镜像、权重和 GPU 复测"，不能因为某个模型在 CPU 或另一张显卡上验证通过就直接类推。

中文实时语音听写服务（CPU 版本）

先跑流式教程，再按协议与多客户端验证

实时语音听写的正确落地顺序是：先运行流式部署教程，再按 WebSocket 协议与对应的多客户端示例验证。

验证时重点检查以下几项：

采样率：实时路径通常要求 16kHz（或按协议指定audio_fs）；
音频分块：流式模型按 chunk 推理，chunk 划分直接影响延迟；
结束消息：音频发送结束后必须发送{"is_speaking": false}结束标志；
重连：断线后的重连行为是否符合业务预期；
会话状态隔离：不同 WebSocket 会话之间的中间状态不得互相污染。

双遍服务与 Nano 流式服务是两个实现

runtime/readme_cn.md明确提示：C++ 双遍服务与 Fun-ASR-Nano Python 流式服务是不同实现。另一个 Nano 实时压测工具使用 Nano 的START/STOP协议，不能用于 C++ 服务；反之亦然。选择压测工具前务必确认目标服务属于哪一套实现。

Docker 一键部署与手动启动

在线（2pass）服务的 Docker 一键部署工具为funasr-runtime-deploy-online-cpu-zh.sh，流程与离线版一致（详见下文离线章节），安装命令示例：

sudo bash funasr-runtime-deploy-online-cpu-zh.sh install --workspace ./funasr-runtime-resources

若希望直接从镜像手动启动，参考在线开发指南。容器内通过run_server_2pass.sh启动funasr-wss-server-2pass，核心命令如下（完整脚本见 run_server_2pass.sh）：

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_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 \ --itn-dir thuduj12/fst_itn_zh \ --hotword /workspace/models/hotwords.txt > log.txt 2>&1 &

与离线版run_server.sh相比，2pass 版多出--online-model-dir参数，用于指定流式（在线）识别模型；离线模型负责在句尾做高精度纠错。

客户端测试与 2pass 参数

python3 funasr_wss_client.py --host "127.0.0.1" --port 10096 --mode 2pass --chunk_size "5,10,5"

其中chunk_size是流式模型的 latency 配置：[5,10,5]表示当前音频解码片段为 600ms，并回看 300ms、右看 300ms；[8,8,4]表示 480ms 片段。mode取值为：

offline：一句话识别（非流式）；
online：实时语音识别（纯流式）；
2pass：实时语音识别，且在说话句尾用离线模型纠错，输出带标点文本。

中文离线文件转写服务（CPU 版本）

一键部署工具（推荐入门）

离线 CPU 版提供一键部署脚本 funasr-runtime-deploy-offline-cpu-zh.sh，完整教程见离线部署教程。该脚本过程分为：安装 Docker、下载 Docker 镜像、启动服务。当前仅支持 Linux 环境，其他环境请参考离线开发指南。

sudo bash funasr-runtime-deploy-offline-cpu-zh.sh install --workspace ./funasr-runtime-resources

安装过程中按提示输入回车即可完成。从脚本源码（第 434-1000 行）可以看到完整的 6 步交互流程：

检查 root 权限与 sudo；
从镜像列表拉取可选 Docker 镜像（列表来源见 docker_offline_cpu_zh_lists）；
依次选择 ASR / VAD / PUNC / LM 模型；
配置宿主机端口（默认 10095）、decoder 线程数与 IO 线程数；
安装 Docker（针对 ubuntu/centos/debian/alios/alinux 分发不同安装命令）并拉取镜像；
构造docker run命令并启动服务，同时把配置持久化到~/.funasr_offline/config。

脚本默认模型组合（见 docker_offline_cpu_zh_lists）：

ASR：damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-onnx（可选时间戳模型、nn 热词模型）；
VAD：damo/speech_fsmn_vad_zh-cn-16k-common-onnx；
PUNC：damo/punc_ct-transformer_cn-en-common-vocab471067-large-onnx；
LM：damo/speech_ngram_lm_zh-cn-ai-wesp-fst。

模型选择说明：在安装部署步骤 2 选择模型时，1 为 paraformer-large 模型，2 为 paraformer-large 时间戳模型，3 为 paraformer-large nn 热词模型。服务端加载热词文件地址为./funasr-runtime-resources/hotwords.txt，每行一个热词，格式为热词权重，例如阿里巴巴 20。

基于 Docker 镜像手动部署与 run_server.sh 参数

若已安装 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

容器内启动funasr-wss-server（完整脚本见 run_server.sh）：

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_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 &

run_server.sh中值得关注的是线程资源的自动推导逻辑（第 13-16 行）：

decoder_thread_num：默认取/proc/cpuinfo中的 CPU 核数，获取失败时回退为 32；
io_thread_num：按(decoder_thread_num + 15) / 16向上取整推导；
model_thread_num：默认 1。

这些参数可通过脚本透传覆盖，例如--decoder-thread-num 32。另外脚本还支持--certfile 0关闭 SSL；默认证书位于ssl_key/server.crt与ssl_key/server.key。

热词与模型变体：

若使用时间戳模型，将--model-dir设为damo/speech_paraformer-large-vad-punc_asr_nat-zh-cn-16k-common-vocab8404-onnx；
若使用 nn 热词模型，设为damo/speech_paraformer-large-contextual_asr_nat-zh-cn-16k-common-vocab8404-onnx；
服务端热词文件为/workspace/models/hotwords.txt（宿主机映射自./funasr-runtime-resources/models/hotwords.txt），每行热词权重，如阿里巴巴 20。

客户端测试与参数详解

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

支持多种输入：音频文件路径（.wav/.pcm/.mp3 等）、视频文件（.mp4，需安装 ffmpeg）以及 Kaldi 风格的多文件列表wav.scp。客户端参数含义：

--host：服务部署机器 IP，默认本机127.0.0.1，跨机部署需改为实际 IP；
--port：部署端口号，默认10095（离线）；
--mode offline：离线文件转写模式；
--audio_in：待转写音频，支持文件路径或wav.scp列表；
--thread_num：并发发送线程数，默认 1；
--ssl：SSL 证书校验开关，默认 1 开启，0 关闭；
--hotword：热词文件，每行热词权重；
--use_itn：是否使用 ITN（逆文本正则化），默认 1 开启，0 关闭。

服务端运维命令

一键部署后可用同一脚本管理服务生命周期：

sudo bash funasr-runtime-deploy-offline-cpu-zh.sh start # 启动已部署的服务 sudo bash funasr-runtime-deploy-offline-cpu-zh.sh stop # 关闭服务 sudo bash funasr-runtime-deploy-offline-cpu-zh.sh remove # 释放服务 sudo bash funasr-runtime-deploy-offline-cpu-zh.sh restart # 重启服务

替换模型并重启（模型须为 ModelScope 上的 ASR/VAD/PUNC 模型，或由其 finetune 得到的模型）：

sudo bash funasr-runtime-deploy-offline-cpu-zh.sh update [--asr_model | --vad_model | --punc_model] <model_id or local model path> # e.g. sudo bash funasr-runtime-deploy-offline-cpu-zh.sh update --asr_model damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch

更新端口与线程参数：

sudo bash funasr-runtime-deploy-offline-cpu-zh.sh update [--host_port | --docker_port] <port number> sudo bash funasr-runtime-deploy-offline-cpu-zh.sh update [--decode_thread_num | --io_thread_num] <the number of threads> sudo bash funasr-runtime-deploy-offline-cpu-zh.sh update [--workspace] <workspace in local> sudo bash funasr-runtime-deploy-offline-cpu-zh.sh update [--ssl] <0: close SSL; 1: open SSL, default:1>

参考服务器配置

官方教程给出的离线服务参考配置（实际容量需以真实镜像、权重与硬件复测为准，详见 benchmark_onnx_cpp.md）：

4 核 vCPU / 8G 内存：单机约 32 路并发；
16 核 vCPU / 32G 内存：单机约 64 路并发；
64 核 vCPU / 128G 内存：单机约 200 路并发。

实时（2pass）服务在同一硬件档次下约为 16 / 32 / 100 路并发。

英文离线文件转写服务（CPU 版本）

英文场景参见英文服务教程与高级配置。部署时的关键提醒是：显式选择英文权重，不要只凭容器名推断语言覆盖——同一个容器镜像可能内置多语言能力，语言能力由实际加载的模型权重决定。

WebSocket 协议要点：消息格式与关键字段

无论离线还是实时服务，都遵循 WebSocket 协议：配置参数与 meta 信息用 JSON，音频数据用 bytes。

离线模式首次通信：

{"mode": "offline", "wav_name": "wav_name", "wav_format":"pcm", "is_speaking": True, "hotwords":"{\"阿里巴巴\":20,\"通义实验室\":30}", "itn":True}

字段说明：

mode：offline表示离线文件转写；
wav_name：待推理音频文件名；
wav_format：音视频文件后缀名，可选 pcm、mp3、mp4 等；
is_speaking：False 表示断句尾点（如 VAD 切割点或一条 wav 结束）；
audio_fs：输入为 pcm 数据时需附带采样率；
hotwords：热词数据（字符串），格式如{"阿里巴巴":20,"通义实验室":30}，热词权重仅在 fst 热词服务下生效；
itn：是否使用 ITN，默认 True；
svs_lang：SenseVoiceSmall 模型语种，默认auto；
svs_itn：SenseVoiceSmall 模型是否开启标点与 ITN，默认 True。

2pass 模式首次通信额外携带chunk_size：

{"mode": "2pass", "wav_name": "wav_name", "is_speaking": True, "wav_format":"pcm", "chunk_size":[5,10,5], "hotwords":"{\"阿里巴巴\":20,\"通义实验室\":30}", "itn":True}

结束标志：音频发送结束后必须发送{"is_speaking": False}。返回结果中，2pass-online表示实时识别结果，2pass-offline表示 2 遍修正结果；若 AM 为时间戳模型，返回timestamp（词级，毫秒）与stamp_sents（句级时间戳及标点信息）字段。

Python WebSocket 快速体验与并发控制

若想用纯 Python 快速体验（不依赖 C++ SDK），可运行 runtime/python/websocket 下的示例。服务端启动：

cd runtime/python/websocket python funasr_wss_server.py --port 10095

从 funasr_wss_server.py 可以看到，Python 版支持按阶段调节并发度，默认值为：

参数	默认值	作用
`--concurrent_vad`	4	VAD 阶段最大并发 generate() 调用
`--concurrent_asr_online`	4	流式 ASR 最大并发
`--concurrent_asr_offline`	2	离线 ASR 最大并发
`--concurrent_punc`	1	标点模型最大并发
`--concurrent_sv`	1	说话人验证最大并发

源码中这些参数通过asyncio.Semaphore实现各阶段限流（第 298-302 行），可用--concurrent_vad / --concurrent_asr_online / --concurrent_asr_offline / --concurrent_punc / --concurrent_sv调节。Python 版本支持多客户端并发（非阻塞推理），输出文本带标点；如需更高吞吐，官方仍推荐上文 C++ 版本服务部署 SDK。

客户端测试（README 提供了离线、流式、2pass 三种模式示例）：

python funasr_wss_client.py --host "127.0.0.1" --port 10095 --mode 2pass --chunk_size "5,10,5" python funasr_wss_client.py --host "127.0.0.1" --port 10095 --mode offline --audio_in "./data/wav.scp" --output_dir "./results"

Python 客户端还支持编程式调用：Funasr_websocket_recognizer(host, port, is_ssl, mode)创建识别器，feed_chunk(data)逐块送入 PCM 并取回结果，close(timeout=3)获取最终结果。

客户端与平台适配

runtime提供了覆盖主流语言与终端的客户端实现：

Python WebSocket、Python HTTP、Java、Go；
浏览器客户端、gRPC、Triton；
Android 与 iOS 是独立移植指南。

使用边界：不同适配器的协议和依赖以各自文档为准，示例代码不自动等于所有目标平台的生产支持。尤其是 Android/iOS 文档，不代表每个桌面发布包都验证过这些设备。

上线检查清单

runtime/readme_cn.md给出了可执行的上线检查清单，逐条落实可显著降低生产事故率：

固定版本：固定代码 commit / 镜像 digest、模型 revision、配置与目标硬件；
验证真实转写：用已知音频检查真实转写和原始返回值，不只检查 health 端点；
分维度评测：分别评测业务音频质量、延迟、并发、内存与失败行为；
安全配置：依据安全指南配置认证、TLS、请求限制和隐私控制；
可回滚：保留上一版模型、产物和配置，并实际演练回滚；
问题上报：按排障清单提交未解决问题；代码发布不能证明用户报告的硬件问题已经解决。

历史发布记录与版本边界

完整历史记录保留了早期 Docker 标签、日期和性能评测引用，适合追踪演进脉络。但新部署应以当前部署手册和明确的验证边界为准，切勿把历史镜像标签或历史评测数字直接当作当前版本的容量承诺。

总结：FunASR 运行时部署的完整决策链是"选模型 → 选协议 → 选入口 → 固定版本 → 复测验证 → 安全加固 → 演练回滚"。离线转写走 SDK_tutorial_zh.md 或 Docker 镜像 +run_server.sh，实时听写走 SDK_tutorial_online_zh.md +run_server_2pass.sh，其余场景（OpenAI 兼容、vLLM、GGUF、ONNX、Triton、Kubernetes）按部署矩阵和上表入口逐个展开，并在上线前完整走一遍检查清单。

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

企业官网建设流程全解析