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/FunASRFunASR 提供的离线文件转写服务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为环节默认模型 IDASR英文版damo/speech_paraformer-large_asr_nat-en-16k-common-vocab10020-onnxVADdamo/speech_fsmn_vad_zh-cn-16k-common-onnxPUNCdamo/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 计算型实例如下可直接用于容量规划配置规格单实例可支撑并发配置 14 核 vCPU / 8 GB 内存约 32 路请求配置 216 核 vCPU / 32 GB 内存约 64 路请求配置 364 核 vCPU / 128 GB 内存约 200 路请求上述并发表达的是可同时处理请求数的上限经验值。其背后的推理吞吐数据可以参见仓库中的 CPUONNX-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]输入宿主机端口100951–65535[4/6]确认全部参数输入Y后参数被持久化[5/6]安装 Docker 并拉取镜像自动执行[6/6]构建并运行容器、加载模型自动执行从源码看几个值得注意的实现细节deploy 脚本线程数自动推导complementParameters函数L578-L617中若未显式设置推理线程数PARAMS_DECODER_THREAD_NUM默认为 CPU 核数脚本顶部兜底值为 32IO 线程数按推理线程数 / 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在启动容器前会调用serverConfigGenerationL1023-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流式/2pass2pass--audio_in音频输入支持单文件路径或wav.scp文件列表不传则从麦克风采集需 PyAudioNone--thread_num并发发送线程子进程数用于并发压测1--sslSSL 证书校验开关1 启用、0 关闭1--hotword热词文件路径每行一个热词加权重e.g.阿里巴巴 20空--use_itn是否启用逆文本归一化ITN1 启用、0 关闭1--audio_fs音频采样率16000--send_without_sleep压测模式不按实时节奏 sleep 发送音频False--output_dir将识别文本写入该目录None--result_timeout等待服务端输入结束确认的超时秒数300.0从源码实现看几个与实操直接相关的行为输入格式自适应record_from_scpL194-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 offlineJava 客户端的完整构建与运行说明见 java readme需要 OpenJDK 11 环境通过make downjar下载依赖 jar、make buildwebsocket编译、make runclient运行源码 FunasrWsClient.java。其支持的参数包括--host必填、--port必填、--audio_inwav 或 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-L1288sudo 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–65536threadNumChange/portChangeL1290-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 后客户端与服务端必须保持一致否则握手失败。其他实用子命令部署脚本还内置了两个教程未展开的辅助命令displayHelpL1424-L1451sudo bash funasr-runtime-deploy-offline-cpu-en.sh client # 交互式运行官方客户端示例Python / Linux Cpp sudo bash funasr-runtime-deploy-offline-cpu-en.sh show # 打印当前所有已保存的部署参数小结与延伸阅读服务链路VADFSMN-VAD ASRParaformer-large ONNX PUNCCT-TransformerWebSocket 协议对外默认端口 10095默认启用 SSL部署funasr-runtime-deploy-offline-cpu-en.sh install一键完成 Docker 安装、镜像拉取、模型选择、容器启动与样例分发参数持久化在~/.funasr_en/客户端Pythonfunasr_wss_client.py、CPP、HTMLh5Server.py、JavaFunasrWsClient.java四种语言支持 wav/pcm/mp3/视频与 wav.scp 批量、热词、ITN、多进程并发压测运维start / stop / restart / remove / update模型、端口、线程、工作目录、SSL覆盖完整生命周期。进一步阅读离线服务进阶从 Docker 镜像手动启动、模型替换、GPU 等SDK_advanced_guide_offline_en.md流式/双通道服务教程SDK_tutorial_online.mdWebSocket 通信协议字段说明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【免费下载链接】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），仅供参考