FunASR 离线文件转写服务实战：Runtime-SDK 一键部署、多语言客户端接入与运维指南-酒店常州论坛

FunASR 离线文件转写服务实战：Runtime-SDK 一键部署、多语言客户端接入与运维指南

【免费下载链接】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 提供的离线文件转写服务（Offline File Transcription Service）基于开源 runtime-SDK 构建，将 VAD 语音端点检测、Paraformer-large 语音识别（ASR）与标点恢复（PUNC）整合为一条完整的语音识别链路，可部署在本地或云服务器上，将数小时级别的音频/视频转写为带标点的文本，并支持数百路并发请求。本文基于仓库中的官方教程 SDK_tutorial_en.md 展开，覆盖一键部署工具 install/start/stop/restart/update 各子命令的真实实现逻辑、Python/CPP/HTML/Java 四类客户端的完整参数说明，以及 SSL、线程数、端口等关键运维参数的源码级解析，帮助读者从零完成部署、压测到生产调参的全过程。

服务定位与架构组成

该服务面向的是离线文件转写场景：给定整段音频或视频文件（.wav、.pcm、.mp3、.mp4 等），服务端在内部完成"语音端点检测 → 识别 → 标点"三级流水线后返回完整文本。与流式识别服务不同，离线模式以吞吐量和转写完整度为优先，因此官方推荐通过 funasr-wss-server 这类 C++ 推理引擎 + WebSocket 协议对外提供能力。

从仓库结构看，服务的各组成部分分别是：

服务端：Docker 镜像内预编译的funasr-wss-server可执行文件，路径为/workspace/FunASR/runtime/websocket/build/bin，源码见 websocket-server-2pass.cpp；
推理链路：ONNX Runtime + 三个 ONNX 模型（ASR / VAD / PUNC），模型清单由 docker_offline_cpu_en_lists 维护；
客户端：Python、CPP、HTML、Java 四种语言示例，部署工具会自动下载客户端样例包到工作目录的samples下。

默认模型组合

部署工具内置的默认模型（见 funasr-runtime-deploy-offline-cpu-en.sh 与 docker_offline_cpu_en_lists）为：

环节	默认模型 ID
ASR（英文版）	`damo/speech_paraformer-large_asr_nat-en-16k-common-vocab10020-onnx`
VAD	`damo/speech_fsmn_vad_zh-cn-16k-common-onnx`
PUNC	`damo/punc_ct-transformer_cn-en-common-vocab471067-large-onnx`

镜像列表当前提供funasr-runtime-sdk-en-cpu-0.1.4 / 0.1.5 / 0.1.6三个版本，部署时默认拉取列表中的最新版本。需要注意：英文版默认 ASR 模型是英文 Paraformer，中文场景请在安装或update阶段显式选择中文模型（例如damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch）。

服务器配置建议

官方教程给出的推荐配置（X86 计算型实例）如下，可直接用于容量规划：

配置	规格	单实例可支撑并发
配置 1	4 核 vCPU / 8 GB 内存	约 32 路请求
配置 2	16 核 vCPU / 32 GB 内存	约 64 路请求
配置 3	64 核 vCPU / 128 GB 内存	约 200 路请求

上述并发表达的是"可同时处理请求数"的上限经验值。其背后的推理吞吐数据可以参见仓库中的 CPU（ONNX-cpp）性能报告 benchmark_onnx_cpp.md：在 Aishell1 test 集（约 36109 秒音频）上，FSMN-VAD + Paraformer-large + CT-Transformer 完整链路在 16 核 Xeon 8369B（带 avx512_vnni）上，int8 量化、32 并发时 RTF 低至约 0.0018，即 1 秒音频约 1.8 毫秒处理时间；在 64 并发下 RTF 基本不再上升，说明推理引擎的并发扩展性良好，多路请求主要消耗的是 CPU 与内存。该报告同时说明 VAD/PUNC 加入后 RTF 仅小幅上升（单路 fp32 从 0.0590 升至 0.0591），即转写全链路相比纯 ASR 几乎零额外推理开销。

云主机新用户可申请的免费试用活动以云厂商当期政策为准；仓库中附有阿里云服务器的申请与开通教程 aliyun_server_tutorial.md，可作为部署前准备服务器的参考。

快速部署（一键工具）

一键部署工具 funasr-runtime-deploy-offline-cpu-en.sh 的完整流程包括：检查 root 权限 → 安装 Docker → 拉取镜像 → 选择模型 → 设置端口 → 创建容器并启动服务 → 下载客户端样例。它要求 Linux 环境（支持 Ubuntu / CentOS / Debian / AliOS / Alinux），需要 root 权限运行。

第一步：下载部署工具

curl -O https://raw.githubusercontent.com/modelscope/FunASR/main/runtime/deploy_tools/funasr-runtime-deploy-offline-cpu-en.sh # 如遇网络问题，中国大陆用户可改用 OSS 镜像地址下载（官方教程中给出的备用地址）

第二步：执行安装与部署

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

执行过程中脚本会分 6 个阶段（[0/6]～[6/6]）进行交互，逐项按下表应答（直接回车即采用默认值）：

阶段	提示内容	默认值 / 说明
[1/6]	选择 Docker 镜像	列表首个（最新版本）
[2/6]	依次选择 ASR / VAD / PUNC 模型	上表默认模型
[3/6]	输入宿主机端口	`10095`（1–65535）
[4/6]	确认全部参数	输入`Y`后参数被持久化
[5/6]	安装 Docker 并拉取镜像	自动执行
[6/6]	构建并运行容器、加载模型	自动执行

从源码看几个值得注意的实现细节（deploy 脚本）：

线程数自动推导：complementParameters函数（L578-L617）中，若未显式设置，推理线程数PARAMS_DECODER_THREAD_NUM默认为 CPU 核数（脚本顶部兜底值为 32），IO 线程数按推理线程数 / 4推导且最少为 1；
配置持久化：saveParams会把所有参数写入~/.funasr_en/config（服务器运行时参数写~/.funasr_en/server_config），这正是后续start/restart能"沿用上次配置"的基础；
模型下载机制：若选择的是 ModelScope 模型 ID，容器启动后会自动把模型下载到容器内/workspace/models（挂载自本地{workspace}/models），首次启动需要等待模型下载；若选择本地模型目录，则通过-v直接挂载进容器；
客户端样例分发：deploySamples函数会在部署完成后下载官方样例包解压到{workspace}/samples（含 python、cpp 客户端与audio/asr_example.wav测试音频），并自动安装客户端依赖（click、ffmpeg、ffmpeg-python、websockets等）。

部署完成后，脚本会提示：样例代码已保存在samples目录，可用sudo bash funasr-runtime-deploy-offline-cpu-en.sh client直接运行客户端示例。

容器内实际生成的服务配置

dockerRun在启动容器前会调用serverConfigGeneration（L1023-L1070）拼装出如下 JSON 并通过DAEMON_SERVER_CONFIG环境变量传给容器，可对照理解每个运维参数如何落到服务端进程：

{"server":[{ "exec":"/workspace/FunASR/runtime/websocket/build/bin/funasr-wss-server", "--model-dir":"<ASR 模型 ID 或容器内路径>", "--vad-dir":"<VAD 模型 ID 或容器内路径>", "--punc-dir":"<PUNC 模型 ID 或容器内路径>", "--download-model-dir":"/workspace/models", "--decoder-thread-num":"32", "--io-thread-num":"8", "--port":"10095", "--certfile":"/workspace/FunASR/runtime/ssl_key/server.crt", "--keyfile":"/workspace/FunASR/runtime/ssl_key/server.key" }]}

当--ssl 0关闭 SSL 时，--certfile/--keyfile会被置为空字符串，容器以明文ws://提供服务。SSL 证书文件位于仓库 runtime/ssl_key 目录（server.crt/server.key）。

客户端测试与使用

Python 客户端

部署完成后，进入样例目录（默认/root/funasr-runtime-resources/samples/python）即可测试：

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

客户端源码见 funasr_wss_client.py，其参数说明（官方教程版本 + 源码中额外可用的参数）如下：

参数	说明	默认值
`--host`	服务部署机 IP，默认本机；跨机部署需改为部署机地址	`localhost`
`--port`	服务端口	`10095`
`--mode`	识别模式：`offline`（离线文件转写）/`online`（流式）/`2pass`	`2pass`
`--audio_in`	音频输入，支持单文件路径或`wav.scp`文件列表；不传则从麦克风采集（需 PyAudio）	`None`
`--thread_num`	并发发送线程（子进程）数，用于并发压测	`1`
`--ssl`	SSL 证书校验开关，1 启用、0 关闭	`1`
`--hotword`	热词文件路径，每行一个热词加权重（e.g.`阿里巴巴 20`）	空
`--use_itn`	是否启用逆文本归一化（ITN），1 启用、0 关闭	`1`
`--audio_fs`	音频采样率	`16000`
`--send_without_sleep`	压测模式：不按实时节奏 sleep 发送音频	`False`
`--output_dir`	将识别文本写入该目录	`None`
`--result_timeout`	等待服务端"输入结束"确认的超时秒数	`300.0`

从源码实现看几个与实操直接相关的行为：

输入格式自适应：record_from_scp（L194-L325）按扩展名区分读取方式——.wav用wave模块解析（自动读取真实采样率随控制消息上报），.pcm按裸流读取，其他扩展名（.mp3、.mp4等）以二进制整体发送并在控制消息中标记wav_format: "others"，由服务端侧解码；
控制协议：客户端先发送一条 JSON 控制消息（含mode、wav_name、audio_fs、wav_format、hotwords、itn等字段），随后分片发送二进制音频块，最后发送{"is_speaking": false, "is_end": true}结束信号，并阻塞等待服务端is_final: true的确认（超时默认 300 秒，可经--result_timeout调整）；
wav.scp 批量输入：--audio_in指向.scp文件时按行解析utt_id wav_path，--thread_num N会把文件列表均分成 N 份子进程并发发送，用于压测并发上限——这与官方"单机数百并发"的能力描述相对应；
热词格式：文件存在时按"词权重"两列解析为 JSON 权重表随控制消息下发；文件不存在时把--hotword的值当作逗号分隔的热词串直接下发，两种用法在源码 L203-L222 中均可确认。

CPP 客户端

进入samples/cpp目录后执行（服务端默认端口 10095）：

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

参数说明：

--server-ip 服务部署机 IP，默认 127.0.0.1；跨机部署需改为部署机地址 --port 部署端口，10095 --wav-path 待转写音频文件路径 --thread_num 并发发送线程数，默认 1 --ssl SSL 证书校验，默认 1 启用、0 关闭 --hotword 热词文件路径，每行一个热词（e.g.: 阿里巴巴 20） --use-itn 是否启用 ITN，默认 1 启用、0 关闭

注意 CPP 客户端参数名与 Python 版本风格略有差异（--server-ip对--host，--wav-path对--audio_in，连字符风格），编写自动化脚本时不要混用。

HTML 客户端

在浏览器中打开样例包内的html/static/index.html即可直接体验，页面支持麦克风实时录音与文件上传两种输入方式，适合作为部署成功后的快速冒烟测试。对应的 Web 服务端脚本为 h5Server.py，静态资源位于 runtime/html5/static 目录。

Java 客户端

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

Java 客户端的完整构建与运行说明见 java readme：需要 OpenJDK 11 环境，通过make downjar下载依赖 jar、make buildwebsocket编译、make runclient运行（源码 FunasrWsClient.java）。其支持的参数包括--host（必填）、--port（必填）、--audio_in（wav 或 pcm 文件路径，必填）、--num_threads（并发线程数）、--mode（支持offline/online/2pass）。返回结果为 JSON，例如：

{"mode":"offline","text":"欢迎大家来体验达摩院推出的语音识别模型","wav_name":"javatest"}

服务运维命令详解

一键工具除install外，还提供完整的服务生命周期管理。以下命令均需在 root 权限下执行。

启动服务（沿用上次部署配置）

重启电脑或 Docker 停止后，用以下命令直接恢复上次部署的配置并启动：

sudo bash funasr-runtime-deploy-offline-cpu-en.sh start

源码中start分支的逻辑是：paramsFromDefault从~/.funasr_en/config读回全部参数 →showAllParams only_show打印当前配置 →dockerRun "start"执行docker restart <容器ID>。也就是说 start 不会重建容器，只按原配置重启。

停止 / 释放 / 重启服务

sudo bash funasr-runtime-deploy-offline-cpu-en.sh stop # 停止服务（docker stop） sudo bash funasr-runtime-deploy-offline-cpu-en.sh remove # 释放服务（docker stop + docker rm，并删除配置文件） sudo bash funasr-runtime-deploy-offline-cpu-en.sh restart # 停止后按上次配置重启

remove在删除容器后会同时清理~/.funasr_en/config与server_config（脚本remove分支，L1656-L1663），如需保留本地模型与样例，请自行备份{workspace}目录。

更换模型并重启

可替换 ASR / VAD / PUNC 三个环节中的任意模型，模型可以是 ModelScope 模型 ID，也可以是本地模型目录路径（脚本会判断是目录还是 ID，走不同的挂载/下载逻辑，见modelChange函数 L1217-L1288）：

sudo bash funasr-runtime-deploy-offline-cpu-en.sh update [--asr_model | --vad_model | --punc_model] <model_id or local model path> # 示例：更换为中文 Paraformer-large sudo bash funasr-runtime-deploy-offline-cpu-en.sh update --asr_model damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch

更新运行参数并重启

可更新的参数包括宿主机/容器端口、推理与 IO 线程数、本地工作目录、SSL 开关：

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

从源码校验规则看：线程数取值范围为 1–1024，端口取值范围为 1–65536（threadNumChange/portChange，L1290-L1326）。update执行完毕会自动dockerStop后重新dockerRun使新配置生效，即所有 update 操作都伴随一次服务重启。

线程参数调优建议：--decode_thread_num是 ONNX Runtime 推理线程数，通常设置为物理核数附近；--io_thread_num是网络 IO 线程数，默认取推理线程数的 1/4。并发路数较多而 CPU 较紧张时可下调推理线程数，避免线程超订。

SSL 设置

服务默认启用 SSL（客户端需以wss://连接，校验默认关闭）。关闭 SSL 的方法：

sudo bash funasr-runtime-deploy-offline-cpu-en.sh update --ssl 0

关闭后客户端对应使用--ssl 0（此时连接为ws://）。从serverConfigGeneration的实现看，SSL 开关直接决定容器内funasr-wss-server的--certfile/--keyfile是否为空，因此切换 SSL 后客户端与服务端必须保持一致，否则握手失败。

其他实用子命令

部署脚本还内置了两个教程未展开的辅助命令（displayHelp，L1424-L1451）：

sudo bash funasr-runtime-deploy-offline-cpu-en.sh client # 交互式运行官方客户端示例（Python / Linux Cpp） sudo bash funasr-runtime-deploy-offline-cpu-en.sh show # 打印当前所有已保存的部署参数

小结与延伸阅读

服务链路：VAD（FSMN-VAD）+ ASR（Paraformer-large ONNX）+ PUNC（CT-Transformer），WebSocket 协议对外，默认端口 10095，默认启用 SSL；
部署：funasr-runtime-deploy-offline-cpu-en.sh install一键完成 Docker 安装、镜像拉取、模型选择、容器启动与样例分发，参数持久化在~/.funasr_en/；
客户端：Python（funasr_wss_client.py）、CPP、HTML（h5Server.py）、Java（FunasrWsClient.java）四种语言，支持 wav/pcm/mp3/视频与 wav.scp 批量、热词、ITN、多进程并发压测；
运维：start / stop / restart / remove / update（模型、端口、线程、工作目录、SSL）覆盖完整生命周期。

进一步阅读：

离线服务进阶（从 Docker 镜像手动启动、模型替换、GPU 等）：SDK_advanced_guide_offline_en.md
流式/双通道服务教程：SDK_tutorial_online.md
WebSocket 通信协议字段说明：websocket_protocol.md
服务端与客户端代码：runtime/websocket/readme.md、runtime/python/websocket/README.md
部署工具其他变体（中文离线版funasr-runtime-deploy-offline-cpu-zh.sh、在线版funasr-runtime-deploy-online-cpu-zh.sh）位于 runtime/deploy_tools

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

企业官网建设流程全解析