FunASR语音识别生产部署实战：511MB音频47秒转写，离线落地 8 步、7 坑一次说清

原文链接：FunASR语音识别生产部署实战：511MB音频47秒转写，离线落地 8 步、7 坑一次说清

前面三篇分别讲了中文 ASR 选型、本机搭 FunASR 和长音频实测。这篇进入真正的内网生产环境：一台不通外网的 Ubuntu + NVIDIA GPU 服务器，把 FunASR 跑成稳定服务，再对接工作流编排实现会议纪要。

读完这篇你能得到四样东西：一套可一次性导入的离线交付物清单；业务拓扑、软件结构和请求时序三张图；7 个内网部署常见踩坑及解法；配套镜像、依赖、脚本、工作流 DSL 的网盘资源，照着即可复现。

整件事的核心定位很清晰：音频不出内网、依赖全闭环、服务可自愈。下面按"环境→选型→设计→部署→踩坑→验证→落地"的顺序展开。

一、生产环境、目标定位与技术选型

目标服务器是一台 x86_64 架构主机，配备 NVIDIA 显卡（CUDA 架构），运行 Ubuntu，不通外网。FunASR 推理对显存的占用远低于大模型，属于轻量级 GPU 负载，这就是本次部署的硬件基线。

业务目标可概括成一句话：会议录音不出内网，经语音转写（含说话人区分）后，对接业务系统落地为结构化纪要。之所以走内网离线，本质原因是会议录音、客户访谈这类原始音频不适合出内网。

技术选型如下：

模块	选型	理由
ASR 主模型	SeACo-Paraformer-large	中文公开基准表现稳定，原生支持热词
VAD / 标点 / 说话人	FSMN-VAD + CT-Transformer + CAM++	FunASR 生态内原生组合，模型格式一致
服务框架	FastAPI	暴露 /v1/asr/meeting 等端点，任意客户端可调用
容器/GPU	Docker + NVIDIA Container Toolkit	镜像与权重解耦，换模型无需重建

模型对比与选型过程在第一篇已实测详述，这里直接用结论：SeACo-Paraformer 原生支持字级时间戳与热词，对会议纪要场景价值尤其大；权重只读挂载到 /models，升级模型只需替换卷内文件。

二、架构设计：业务拓扑与软件结构

先看整体业务拓扑：

外部只需一个泛化角色：音频来源或业务系统，通过 HTTP 把音频交给语音模型服务（:10095）。服务内部自上而下是四层------FastAPI 接入层、VAD→ASR→PUNC→CAM++ 模型层、/models 本地只读权重、Docker + GPU 运行时。推理完成后返回结构化转写结果，全程不出内网。

再看软件体系结构：

这张图从上到下就是完整链路：最上面是接入层 FastAPI，暴露 /health 与 /v1/asr/meeting 两个端点；往下是推理层，单 worker 单线程执行器串行执行；再往下串接 VAD→ASR→PUNC→CAM++ 四条模型管线；最底部输出 text、dialogue、speakers、speaker_count 字段。右侧配置层由 config.py 通过环境变量驱动 DEVICE、ENABLE_SPEAKER、INFER_TIMEOUT_S，虚线跨层作用于推理与管线。

单 worker 单线程这个设计很关键：FunASR 部分模型调用并非线程安全，显存竞争易致上下文异常，串行执行以吞吐换稳定。

三、一次会议转写的完整时序

一次完整请求分 4 步：客户端上传录音并 POST /v1/asr/meeting → FunASR 串行调用模型管线 → 返回 dialogue 和 speakers → 客户端对接业务系统生成纪要。

全程没有外网访问，推理完全在目标机 GPU 上完成。

四、离线部署八步流程

整个部署可拆成 8 步：离线安装 Docker → 安装 NVIDIA Container Toolkit → 加载或离线构建 FunASR 镜像 → 复制模型权重到 /models → 启动服务 → /health 健康检查 → curl 单测转写 → 对接业务系统（工作流编排）。

其中 Docker 安装脚本只接受 focal（Ubuntu 20.04）或 bionic（18.04）参数，填 jammy 会直接退出；模型目录要与 docker-compose.yml 的挂载路径对齐，否则 /health 会永远返回 model_ready=false。

下面这段是验证服务是否就绪的最小命令集：

|------------------------------------------------------------------------------------------------------------------------------------------------|
| # 健康检查，期望返回 model_ready=true curl http://127.0.0.1:10095/health # 直接调用会议转写接口 curl -F "file=@meeting.wav" http://127.0.0.1:10095/v1/asr/meeting |

五、7 个真实踩坑与解法

内网离线部署最难的往往不是模型本身，而是依赖闭环、二进制可靠性、资源约束与运行稳定性。下表 7 个坑都来自实际部署，前 3 个最容易复现，单独展开。

坑位与现象	根因	解法
ffmpeg 坏二进制：音频解码失败，/health 却显示正常	构建自检用管道，只看 head 的退出码，坏二进制静默过关	Dockerfile 生成测试音做真实解码自检 + SHELL 切 bash
单线程雪崩：多次调用后服务整体卡死	asyncio.wait_for 只能取消协程，取消不了线程里的 GPU 推理	超时后 os._exit(1)，靠 compose 自动重启拉起
CPU 飙升 5000%：第二次请求耗时翻数倍	线程过订阅，叠加 CAM++ 说话人自动聚类估计	6 个线程变量 = 1 + 显式传 speaker_num
oss2 版本死锁：pip --no-index 离线安装失败	METADATA 要求的版本高于 PyPI 实际最高版本（离线 wheel 的依赖声明版本号比官方库还高，pip 直接拒绝安装）	放宽约束到 >=2.13.10，本地路径不触发该依赖
huggingface_hub 轮子损坏：读 RECORD 时 OSError 中断	wheel 仅 8KB（正常约 417KB），不是合法 zip 包	重下合法轮子 + 全量 testzip 校验闭环
libsndfile 缺失：import soundfile 直接报错	基础镜像 jammy 未带音频库，仅 libgomp1 不够	补 7 个 jammy 音频库 deb 统一安装
GPU 不可见：容器内看不到显卡	nvidia runtime 未配置，或宿主驱动低于 535	nvidia-ctk runtime configure + 升级驱动

5.1 重点分析：ffmpeg 坏二进制（最隐蔽）

这个坑最具欺骗性：构建时 ffmpeg -version | head -n1 的管道只看 head 退出码，坏二进制静默过关；运行时真解码才崩溃，但 /health 不碰 ffmpeg，一直显示健康。修复是在 Dockerfile 里生成测试音做真实解码自检，并把 SHELL 切到 bash 支持 set -o pipefail。

5.2 重点分析：单线程雪崩（设计取舍的副作用）

服务只有一个 worker 线程跑 GPU 推理，某次调用卡在 GPU 上时，asyncio.wait_for 只能取消协程，无法中断线程里的 model.generate()，后续请求全部排队雪崩。修复是超时后 os._exit(1)，靠 restart: unless-stopped 拉起新进程强制释放线程与显存。

5.3 重点分析：CPU 飙升 5000%（两层根因）

这个坑分两层：线程过订阅是表象，把 6 个线程变量设为 1 后 CPU 明显回落；真正根因是 CAM++ 说话人区分------不传 speaker_num 时要对说话人数做聚类自动估计，迭代计算全在 CPU 上，长音频尤其明显。实测显式传入 speaker_num 后彻底根治，CPU 从 5031% 稳定到 50%~400%。知道参会人数务必显式传参。

六、测试验证与性能设计

本环节统一口径只看两个指标：文件大小与耗时。前者定解码显存压力，后者反映吞吐稳定性。

验证分两步，细节见 6.1：/health 就绪、curl 链路通。

6.1 curl 命令行单测：文件大小 × 耗时

用 time 包裹请求、ls -lh 记录文件大小，形成一条可复现的单测。

|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| # 0. 服务就绪 curl -s http://127.0.0.1:10095/health # 1. 记录文件大小（指标一） ls -lh meeting.wav # 2. 第一次请求并计时（指标二：耗时） time curl -s -X POST -F "file=@meeting.wav" \ http://127.0.0.1:10095/v1/asr/meeting -o r1.json # 3. 第二次请求并计时（对照线程限制效果） time curl -s -X POST -F "file=@meeting.wav" \ http://127.0.0.1:10095/v1/asr/meeting -o r2.json # 4. 指定说话人数，绕开 CAM++ 自动聚类 time curl -s -X POST -F "file=@meeting.wav" -F "speaker_num=6" \ http://127.0.0.1:10095/v1/asr/meeting -o r3.json |

实际执行上述命令结果如下图：

实测耗时统计数据见下表：

测试项	文件大小	耗时	说明
第一次	511 MB	47.269s	基线
第二次	511 MB	47.540 s	应接近第一次
指定人数	511 MB	47.726 s	speaker_num 绕过聚类

结论：三次测试同一文件，耗时分别为 47.269s / 47.540s / 47.726s，几乎一致，说明线程限制与 speaker_num 显式传参后吞吐稳定。

语音解析后的结果JSON结构如下：

结论：返回 JSON 的 dialogue 与 speakers 字段完整。

性能参数取 docker-compose.yml 与 config.py 默认值，面向 NVIDIA GPU（CUDA 架构）显存占用的保守配置：

参数	默认值	作用
DEVICE	cuda:0	FunASR 单卡推理即可覆盖转写负载
ENABLE_SPEAKER	1	开启 CAM++ 说话人区分
BATCH_SIZE_S	300	动态批大小，显存富余可上调到 600
INFER_TIMEOUT_S	7200	覆盖 2 小时长录音
shm_size	8gb	避免 PyTorch 多进程共享内存不足
PRELOAD	1	启动即加载模型，避免首请求超时

Paraformer 在 GPU 上可达百倍实时量级，但本方案为稳定选串行单线程；长音频 RTF 会上升，极端情况可用 FUNASR_DEVICE=cpu 兜底。

七、业务落地：从 API 到会议纪要

部署的价值不在"跑通"，而在"用起来"。FunASR 暴露的 /v1/asr/meeting 返回 text、dialogue、speakers 等字段，足以支撑转写、说话人区分与纪要等落地场景。

以我实测的 Dify 工作流为例：上传同一段音频，走「调用 FunASR API → 本地 LLM 生成纪要」流程，业务即落地为结构化纪要。

下面为 Dify 工作流节点配置，采用 Dify 的 HTTP 节点发起 POST 请求：

下面为 Dify 工作流的一次实测效果：上传一段音频，输出指定结构的会议纪要和待办：

实测印证了全链路闭环：/health 正常、curl 单测通过，工作流也能稳定产出纪要。若用带沙箱的代码节点调用，注意 seccomp 会拦截直连私网，让请求走代理放行即可。

工作流 DSL 已放入网盘，读者可直接导入复用。

部署 Checklist（照着勾）

• 离线装好 Docker（安装脚本参数只认 focal / bionic，勿填 jammy）
• 装 NVIDIA Container Toolkit，配置 nvidia runtime
• 加载 / 离线构建 FunASR 镜像
• 模型权重拷到 /models，且挂载路径与 docker-compose.yml 对齐
• docker compose up 启动服务
• curl /health 返回 model_ready=true
• curl /v1/asr/meeting 单测转写通过
• 对接业务系统 / 工作流编排落地纪要

这套方案的核心不是"跑得最快"，而是"无网条件下一次跑通并持续服务"。

如果你也在做语音识别内网部署，欢迎在评论区聊聊：你遇到的最大的坑，是依赖、网络策略，还是 GPU 稳定性？觉得有用的话，点个「在看」、收藏转发，后面继续更新本地 AI 服务落地系列。

资源获取：全部离线部署材料（镜像 tar / 78 个 wheel / 模型权重 / 工作流 DSL 与插件 / 测试音频）已放入网盘，回复关键词"FunASR离线"即可获取；也可点阅读原文直达： 同名【独码侠】。

【欢迎访问我的个人博客主页，这里有我的精选文章和AI大模型日报专栏。👇）