FunASR 本地离线语音转写部署完整指南：从 Python 服务到批量转写

FunASR 本地离线语音转写部署完整指南：从 Python 服务到批量转写

【免费下载链接】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

会议录音、客服通话要转成文字，又不想上传云 API。FunASR 可以在 Windows 或 Linux 上跑起一个本地离线语音转写服务：4 个步骤、约 10 分钟，得到一个 WebSocket 转写服务，支持单文件与批量 wav.scp 转写，输出带标点的文本。

FunASR 本地转写能做什么

先说几个帮你判断值不值得装的点：

• 它是一个开源语音识别工具包，覆盖 ASR（识别）、VAD（语音活动检测，即判断哪段音频里有人说话）、PUNC（标点恢复）全链路；本文只用"部署转写服务"这一环
• 纯 CPU 可跑：默认加载中文 paraformer 大模型，不需要 GPU
• 服务端/客户端分离：一个 Python 脚本起服务，客户端通过 WebSocket 送音频，你以后也可以用自己的程序对接
• 三种工作模式：offline（整段文件转写）、online（流式实时）、2pass（流式先出草稿、离线再精修）

能力边界一眼看完：默认模型为中文（paraformer-zh）、16kHz 采样率；音频输入建议用 wav 或 wav.scp 清单，mp3 等其他格式需要本机装有 ffmpeg。

前置条件：Python 环境与依赖清单

必须

• Python 3.8 – 3.13：用python --version确认
• PyTorch ≥ 1.11：pip install torch torchaudio
• funasr 与 modelscope：pip install -U funasr modelscope
• git：用于克隆源码

可选增强

• ffmpeg：转写 mp3、mp4 等非 wav 格式时才需要；Windows 用winget install ffmpeg
• PyAudio：直接用麦克风实时转写时才需要：pip install pyaudio

💡 本文命令在 Windows 上可在 PowerShell 或 cmd 中执行，Linux 下在 bash 执行。跨平台命令统一用bash代码块展示，Windows 专属命令会单独标注cmd或powershell。

部署转写服务：从 0 到跑通的 4 步

步骤 1：克隆源码并安装运行时依赖

做什么：拿到 FunASR 源码，安装 WebSocket 服务端与客户端的依赖。

git clone https://gitcode.com/GitHub_Trending/fun/FunASR cd FunASR/runtime/python/websocket pip install -r requirements_server.txt pip install -r requirements_client.txt

怎么确认成功：目录里能看到funasr_wss_server.py与funasr_wss_client.py两个脚本：

dir funasr_wss_server.py funasr_wss_client.py

ls funasr_wss_server.py funasr_wss_client.py

步骤 2：启动 WebSocket 转写服务

做什么：以 CPU 模式启动服务端。注意脚本默认把模型加载到 GPU（--ngpu 1 --device cuda），无显卡的机器必须显式传 CPU 参数，否则会报 CUDA 相关错误；有 NVIDIA 显卡的机器则去掉--ngpu 0 --device cpu，直接用默认参数启动。首次启动会从 ModelScope 下载 paraformer-zh、VAD、标点、声纹四个模型，耗时取决于带宽，属正常现象。

python funasr_wss_server.py --port 10095 --ngpu 0 --device cpu --ncpu 4

怎么确认成功：下载完成后终端依次出现：

model loaded! (now supports multi-client with non-blocking inference) WS server started at ws(s)://0.0.0.0:10095

⚠️ 服务端默认启用 SSL（默认证书指向runtime/ssl_key/server.crt）。之后客户端连接若报ssl握手类错误，要么客户端保持--ssl 1，要么服务端加--certfile ""关闭 SSL、同时客户端改为--ssl 0。

步骤 3：单文件转写

做什么：另开一个终端，用客户端对本地 wav 发起offline转写。

python funasr_wss_client.py --host "127.0.0.1" --port 10095 --mode offline --audio_in "D:\audio\meeting.wav"

（--audio_in换成你的音频实际路径）

怎么确认成功：终端逐句打印带标点的识别文本；服务端终端对应打印======offline final text:行。

💡 音频不是 16kHz wav 时（如 mp3），客户端原样发送、由服务端用 ffmpeg 解码；若报解码错误，先转成标准 wav：ffmpeg -i input.mp3 -ar 16000 -ac 1 out.wav。

步骤 4：批量转写 wav.scp 清单

做什么：把待转写音频写进 Kaldi 风格清单（每行编号 路径），客户端读清单逐条转写，用--output_dir把结果落到目录。

创建D:\audio\wav.scp，内容为：

demo1 D:\audio\meeting1.wav demo2 D:\audio\call2.wav

执行批量转写：

python funasr_wss_client.py --host "127.0.0.1" --port 10095 --mode offline --audio_in "D:\audio\wav.scp" --output_dir "D:\transcripts"

怎么确认成功：跑完没有超时异常；D:\transcripts目录下生成转写结果文件。客户端等待服务端确认的窗口默认 300 秒，可用--result_timeout调整。

进阶实操：热词定制与并发调优

热词定制：提升领域专有名词识别率

转写老把人名、产品名、内部术语听错时，用--hotword指定热词文件，格式为每行热词 权重，权重越大越优先：

阿里巴巴 20 ModelScope 20 FunASR 30

python funasr_wss_client.py --host "127.0.0.1" --port 10095 --mode offline --audio_in "D:\audio\meeting.wav" --hotword "D:\hotwords.txt"

并发调优：按 CPU 核数配参数

Python 服务端用线程池执行推理，默认--worker_threads取max(4, CPU核数)，各阶段并发度由--concurrent_vad、--concurrent_asr_online、--concurrent_asr_offline等控制。多客户端同时接入时，可按下式调整：线程池不超过物理核数，最耗资源的离线 ASR 并发不超过 2 倍核数，例如 8 核机器：

python funasr_wss_server.py --port 10095 --ngpu 0 --device cpu --ncpu 8 --worker_threads 8 --concurrent_asr_offline 4 --concurrent_vad 8

嫌写客户端麻烦的话，仓库还带了一个浏览器端 Web 客户端（runtime/html5/目录），上传文件即可转写，界面如下：

故障速查：常见报错与处理命令

1. 现象：服务端启动报Address already in use原因：10095 端口被其他进程占用。解决（cmd）：netstat -ano | findstr :10095找到最后一列 PID，taskkill /PID <PID> /F结束进程；或服务端改用--port 10096启动，客户端同步改--port。

2. 现象：客户端连上即断，日志含ssl握手错误原因：服务端默认启用 SSL（wss），客户端却按明文 ws 连接。解决：客户端确认--ssl 1（默认即 1）；若服务端传了--certfile ""关 SSL，客户端必须改--ssl 0，两边保持一致即可。

3. 现象：客户端报ModuleNotFoundError: No module named 'pyaudio'原因：没传--audio_in，客户端进入麦克风推流模式。解决：转写文件就补上--audio_in路径；确需麦克风则pip install pyaudio。

4. 现象：服务端卡在model loading很久，或中途出现下载中断原因：首次启动需从 ModelScope 拉取四个模型包，弱网易断。解决：直接重跑同一条启动命令，已下载的模型走本地缓存不重复拉取；网络受限时参照 docs/installation/installation_zh.md 手动准备模型。

5. 现象：长音频转写到一半报server did not acknowledge end of input原因：客户端等待服务端收尾确认超过默认 300 秒。解决：客户端追加--result_timeout 600，把等待窗口翻倍。

想继续深入？

• WebSocket 客户端/服务端全参数说明：runtime/python/websocket/README.md
• C++ 高并发 SDK（Docker 部署、批量文件转写）：runtime/quick_start_zh.md
• 环境安装与平台差异：docs/installation/installation_zh.md
• 常见问题：docs/reference/FQA.md
• 更多模型与训练示例：examples/

服务端近期已支持多客户端并发限流与声纹识别（speaker_db）参数，如果你的场景是多人会议转写，可以先在runtime/python/websocket/funasr_wss_server.py里看--concurrent_sv相关配置。

挑一段你最头疼的通话录音，把--audio_in指过去跑一遍，再和云端结果对比一下准确率。

【免费下载链接】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