FunASR 本地部署三步跑通离线语音转写服务：Docker 一键部署与避坑清单-平芜编程栈

FunASR 本地部署三步跑通离线语音转写服务：Docker 一键部署与避坑清单

【免费下载链接】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 是达摩院开源的语音识别工具包，本文带你完成一次 FunASR 本地部署：用 Docker 在单机上起一个离线文件转写服务，面向手里有会议、客服、培训录音、又不想让音频上传任何云端的你。全程 CPU 即可，不需要 GPU，转写数据不出内网。

适用 / 不适用：先判断该不该用这条路径

这一节帮你在动手前判断方案是否匹配你的需求，避免装完环境才发现方向错了。

✅ 需要离线转写音视频文件（wav、mp3、mp4 等，非 wav 格式依赖 ffmpeg）
✅ 批量转写：用 wav.scp 清单一次处理一个目录的录音
✅ 隐私敏感场景：录音不能外传的合规需求
✅ 机器没有 GPU，只有一台 Linux 服务器
⚠️ 需要边说边出的低延迟实时转写：本文的镜像是离线文件转写，实时场景要走 online/2pass 服务，是另一套部署
⚠️ 要训练或微调自己的模型：用 FunASR 的训练部分，而不是运行时
⚠️ 你的机器是 macOS 且不想碰 Docker：一键脚本面向 Linux 发行版

部署前检查清单：5 分钟查完 6 项

开始之前，这一节帮你排除最常见的三类启动失败：Docker 依赖缺失、端口被占、磁盘不够。

检查项	要求	检查方式
操作系统	Linux（Ubuntu / Debian / CentOS 等）	`cat /etc/os-release`
Docker	已安装且守护进程在运行	`docker info`能打印服务端信息
端口	默认 10095 未被占用（可改）	`ss -tlnp \\| grep 10095`无输出
磁盘	预留 20GB 以上，模型首次运行自动下载	`df -h`
ffmpeg	转写 mp4 等视频格式时才需要	`ffmpeg -version`
网络	首次运行要拉取 VAD / ASR / 标点模型	能访问模型仓库即可

一键部署脚本位于仓库的runtime/deploy_tools/funasr-runtime-deploy-offline-cpu-zh.sh，下面三步都围绕它展开。

三步跑通服务：从克隆到拿到第一句转写

第一步：获取源码

做什么：克隆仓库并进入部署脚本目录。

git clone https://gitcode.com/GitHub_Trending/fun/FunASR cd FunASR/runtime/deploy_tools

判断成功：当前目录能看到funasr-runtime-deploy-offline-cpu-zh.sh。卡住了查哪里：clone 失败基本是网络问题，稍等重试即可。

第二步：一键安装

做什么：以管理员权限执行安装命令。

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

脚本会依次交互：选 Docker 镜像、选 ASR / VAD / 标点 / 语言模型（一路回车用默认，即 Paraformer-large + FSMN-VAD + CT-Transformer 标点模型，覆盖通用中文）、输入宿主机端口（默认 10095）、输入 Y 确认。

判断成功：终端打印 “The service has been started.”，且示例客户端已下载到当前目录的funasr-runtime-resources/samples。卡住了查哪里：两个文件——~/.funasr_offline/progress.txt（模型下载进度）和~/.funasr_offline/server_console.log（服务日志）；如果是端口被占，容器会起不来，先按下一节处理方法解决。另一个细节：SSL 默认开启，客户端以 wss 方式连接，想用明文 ws 就在 install 后追加--ssl 0。

第三步：转写一条音频验证

做什么：用部署时带下来的 Python 客户端转写一条音频。

python3 ../funasr-runtime-resources/samples/python/funasr_wss_client.py --host 127.0.0.1 --port 10095 --mode offline --audio_in 你的.wav

判断成功：终端打印出完整转写文本，客户端收到的最终确认里"is_final": true。批量场景：写一个 wav.scp，每行“录音名音频路径”，--audio_in指向这个 .scp 文件，结果写入--output_dir指定的目录。不想敲命令的话，仓库runtime/html5目录还有一个浏览器测试页，填入 wss 地址即可在网页里转写。

卡住了查哪里：连接超时先查端口和 SSL 开关；长音频迟迟不返回时，注意客户端默认等待 300 秒，可用--result_timeout调大。

高频问题速查：5 个症状对应的原因和解法

服务跑起来之后，这一节帮你把最常踩的坑一次说清，格式统一为现象 → 原因 → 解法。

端口被占，容器起不来现象：install 提示端口已被占用。原因：10095 被其他进程占了。解法：先定位占用进程，再杀进程或换端口。

ss -tlnp | grep 10095

换端口执行sudo bash funasr-runtime-deploy-offline-cpu-zh.sh update --host_port 20095，服务会自动重启。

脚本提示 docker 命令不存在现象：报 “docker: command not found”。原因：Docker 依赖没装。解法：install 流程里自带 Docker 自动安装；若安装失败，手动跑runtime/deploy_tools/install_docker.sh。
mp3 / mp4 转写失败现象：wav 正常、mp3 报错。原因：缺少 ffmpeg。解法：apt 或 yum 安装 ffmpeg，Python 客户端侧还需ffmpeg-python包。
专业术语总被识别错现象：同一批专有名词反复出错。原因：通用模型没见过你的词。解法：在funasr-runtime-resources/models/放一份 hotwords.txt，每行“热词权重”，例如阿里巴巴 20；术语量大的话，用 update 命令把--asr_model换成带 nn 热词的 contextual Paraformer 模型。
想要带时间戳的结果现象：默认输出是纯文本，没有时间戳。原因：默认 ASR 模型不带时间戳。解法：update --asr_model换成时间戳模型 damo/speech_paraformer-large-vad-punc_asr_nat-zh-cn-16k-common-vocab8404-onnx。

性能与调优：16 核 CPU 能扛多少并发

这一节只讲和你直接相关的两个问题：机器够不够用、线程要不要动。

FunASR 官方基准测试（见runtime/docs/benchmark_onnx_cpp.md）显示：16 核 Xeon 机器上，8 路并发转写的 RTF 约 0.0076（fp32），int8 量化后降到约 0.0036；64 路并发下服务依然稳定。也就是说，单台 16 核机器足够支撑一个小团队日常的批量转写量。

需要调整时只看两个参数：解码线程默认等于核心数，IO 线程默认核心数除以 4，通过update --decode_thread_num和update --io_thread_num修改，改完服务自动重启生效。