手把手部署FunASR语音识别WebUI｜集成speech_ngram_lm_zh-cn实战
1. 引言：为什么选择FunASR + WebUI？
在语音识别（ASR）领域，FunASR是由 ModelScope 推出的开源语音基础工具包，支持离线/在线语音识别、端点检测（VAD）、标点恢复、语言模型增强等多种功能。其基于 ONNX 的推理方案具备高性能、低延迟的特点，广泛应用于智能客服、会议转录、字幕生成等场景。
然而，原生 FunASR 主要面向开发者提供 SDK 和服务端接口，缺乏直观的操作界面。为此，社区开发者“科哥”基于speech_ngram_lm_zh-cn模型进行了二次开发，构建了FunASR 语音识别 WebUI，极大降低了使用门槛。
本文将带你从零开始： - 部署 FunASR WebUI 环境 - 集成中文 N-gram 语言模型提升识别准确率 - 实践上传音频与实时录音两种识别方式 - 导出文本、JSON、SRT 字幕文件 - 解决常见问题并优化性能
本文适用于希望快速搭建本地语音识别系统的 AI 工程师、产品经理或科研人员。
2. 环境准备与镜像拉取
2.1 系统要求
| 组件 | 推荐配置 |
|---|---|
| 操作系统 | Ubuntu 20.04 / 22.04 LTS |
| CPU | Intel i5 及以上 |
| 内存 | ≥ 8GB |
| 显卡（可选） | NVIDIA GPU（CUDA 支持）用于加速 |
| 存储空间 | ≥ 20GB（含模型缓存） |
| Docker | 已安装（版本 ≥ 20.10） |
2.2 安装 Docker（如未安装）
# 更新包索引 sudo apt-get update # 安装必要依赖 sudo apt-get install -y apt-transport-https ca-certificates curl gnupg-agent software-properties-common # 添加 Docker 官方 GPG 密钥 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg # 添加仓库 echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # 安装 Docker CE sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io # 验证安装 sudo docker --version2.3 创建本地目录并拉取镜像
该 WebUI 基于官方 FunASR 镜像进行二次封装，已预集成speech_ngram_lm_zh-cn中文语言模型。
# 创建模型挂载目录 mkdir -p ./funasr-runtime-resources/models # 拉取镜像（请替换为实际可用镜像地址） sudo docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-cpu-0.4.6⚠️ 注意：若使用 GPU 版本，请确保已安装 NVIDIA Container Toolkit，并使用
gpu标签的镜像。
3. 启动容器与服务部署
3.1 启动 Docker 容器
sudo docker run -it --privileged=true \ -p 7860:7860 \ -p 10095:10095 \ -v $PWD/funasr-runtime-resources/models:/workspace/models \ registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-cpu-0.4.6 \ /bin/bash说明： --p 7860:7860：映射 WebUI 端口 --p 10095:10095：映射 ASR 服务 WebSocket 端口 --v ...：挂载本地模型目录，便于持久化和热更新
3.2 进入容器并启动 ASR 服务
进入容器后执行以下命令：
cd /workspace/FunASR/runtime nohup bash run_server.sh \ --download-model-dir /workspace/models \ --model-dir damo/speech_paraformer-large-vad-punc_asr_nat-zh-cn-16k-common-vocab8404-onnx \ --vad-dir damo/speech_fsmn_vad_zh-cn-16k-common-onnx \ --punc-dir damo/punc_ct-transformer_cn-en-common-vocab471067-large-onnx \ --lm-dir damo/speech_ngram_lm_zh-cn-ai-wesp-fst \ --itn-dir thuduj12/fst_itn_zh \ --port 10095 \ --certfile 0 \ --hotword /workspace/models/hotwords.txt > asr_server.log 2>&1 &关键参数解析： ---lm-dir damo/speech_ngram_lm_zh-cn-ai-wesp-fst：启用中文 N-gram 语言模型，显著提升专业术语和长句识别准确率 ---certfile 0：关闭 SSL，避免浏览器访问异常 ---hotword：支持加载热词文件（每行格式：关键词 权重，如人工智能 30）
查看日志确认服务启动成功：
tail -f asr_server.log预期输出包含：
INFO: Started server on port 10095 INFO: Model loaded successfully: paraformer-large4. 启动 WebUI 并访问界面
4.1 启动 WebUI 应用
在容器内运行 WebUI 主程序：
cd /workspace/webui python app.main.py --host 0.0.0.0 --port 7860 --asr-host localhost --asr-port 10095若提示缺少依赖，请先安装：
pip install gradio websockets numpy torch onnxruntime-gpu -i https://pypi.tuna.tsinghua.edu.cn/simple4.2 访问 WebUI 界面
打开浏览器访问：
http://localhost:7860或远程访问：
http://<你的服务器IP>:7860成功加载后将看到如下界面： - 标题：FunASR 语音识别 WebUI - 控制面板：模型选择、设备切换、功能开关 - 音频上传区与麦克风按钮 - 结果展示区（文本、JSON、时间戳）
5. 使用流程详解
5.1 方式一：上传音频文件识别
步骤 1：上传音频
点击「上传音频」按钮，支持格式包括： -.wav,.mp3,.m4a,.flac,.ogg,.pcm- 推荐采样率：16kHz - 单文件建议 ≤ 100MB
步骤 2：设置识别参数
| 参数 | 推荐值 | 说明 |
|---|---|---|
| 模型选择 | Paraformer-Large | 高精度模式 |
| 设备选择 | CUDA（如有GPU） | 提升解码速度 |
| 语言 | auto或zh | 自动检测或指定中文 |
| 批量大小 | 300秒 | 最大支持5分钟分段处理 |
| 启用PUNC | ✅ 开启 | 自动添加逗号、句号等标点 |
| 输出时间戳 | ✅ 开启 | 用于生成字幕 |
步骤 3：开始识别
点击「开始识别」按钮，等待处理完成。识别进度会在页面显示。
步骤 4：查看结果
结果分为三个标签页： -文本结果：纯净文字内容，可直接复制 -详细信息：JSON 格式，包含每个词的置信度、时间戳 -时间戳：按句子划分的时间区间列表
示例输出：
[001] 0.000s - 1.200s (时长: 1.200s) [002] 1.200s - 3.500s (时长: 2.300s)5.2 方式二：浏览器实时录音识别
步骤 1：授权麦克风权限
点击「麦克风录音」按钮，浏览器会弹出权限请求，点击「允许」。
步骤 2：录制语音
- 对着麦克风清晰说话
- 点击「停止录音」结束录制
录音数据仅在本地浏览器中处理，不上传至第三方服务器，保障隐私安全。
步骤 3：提交识别
点击「开始识别」，系统自动发送音频流至 ASR 服务端进行解码。
步骤 4：获取结果
同上传文件流程，可在下方查看文本、JSON 和时间戳信息。
6. 结果导出与高级功能
6.1 下载识别结果
识别完成后，可通过三个按钮下载不同格式的结果：
| 按钮 | 文件格式 | 用途 |
|---|---|---|
| 下载文本 | .txt | 文档编辑、内容提取 |
| 下载 JSON | .json | 程序解析、结构化分析 |
| 下载 SRT | .srt | 视频字幕嵌入、剪辑定位 |
所有输出文件保存路径为：
outputs/outputs_YYYYMMDDHHMMSS/例如：
outputs/outputs_20260104123456/ ├── audio_001.wav ├── result_001.json ├── text_001.txt └── subtitle_001.srt6.2 高级功能配置
调整批量大小（Batch Size）
- 默认：300 秒（5 分钟）
- 范围：60 ~ 600 秒
- 作用：控制每次送入模型的音频长度，影响内存占用与响应速度
小技巧：对于长录音（>30分钟），建议手动切片为 5 分钟片段分别处理。
设置语言类型
| 选项 | 适用场景 |
|---|---|
auto | 多语种混合内容 |
zh | 纯中文语音 |
en | 英文演讲、访谈 |
yue | 粤语方言 |
ja | 日语播客 |
选择正确语言可提升识别准确率 10%~20%。
启用时间戳输出
开启后，结果中会返回每个词或短语的时间偏移量，适用于： - 自动生成视频字幕 - 会议纪要定位发言段落 - 教学音频重点标注
7. 性能优化与问题排查
7.1 提高识别准确率的四大策略
| 方法 | 操作说明 | 效果评估 |
|---|---|---|
| 使用 N-gram LM | 启用speech_ngram_lm_zh-cn模型 | +15% 准确率 |
| 添加热词 | 在hotwords.txt中添加行业术语 | 关键词错误率↓50% |
| 清晰发音 | 保持语速适中、减少背景噪音 | 错别字减少 |
| 预处理降噪 | 使用 Audacity 或 FFmpeg 降噪 | 信噪比提升 |
示例热词文件（hotwords.txt）：
大模型 30 Transformer 25 深度学习 20 AI Agent 307.2 加快识别速度的方法
| 场景 | 优化措施 |
|---|---|
| 无 GPU 环境 | 切换为SenseVoice-Small模型 |
| 长音频处理 | 分段上传，每段 < 5 分钟 |
| 多并发需求 | 增加--decoder-thread-num参数 |
| 冷启动慢 | 提前下载模型到/workspace/models |
切换小模型命令示例：
--model-dir iic/SenseVoiceSmall-onnx7.3 常见问题与解决方案
| 问题现象 | 可能原因 | 解决方法 |
|---|---|---|
| 页面无法访问 | 端口未映射或防火墙拦截 | 检查-p 7860:7860是否生效 |
| 上传失败 | 文件过大或格式不支持 | 转换为 WAV/MP3，压缩至 <100MB |
| 识别乱码 | 编码错误或语言设置不当 | 设置语言为zh，检查音频编码 |
| 麦克风无响应 | 浏览器权限被拒 | 清除站点权限并重新授权 |
| 模型加载失败 | 网络不通或磁盘满 | 检查网络连接与存储空间 |
| 返回空结果 | 音频静音或信噪比极低 | 重新录制，提高音量 |
8. 总结
本文完整演示了如何部署FunASR 语音识别 WebUI，并集成speech_ngram_lm_zh-cn中文语言模型实现高精度识别。通过图形化界面，即使是非技术人员也能轻松完成语音转文字任务。
核心要点回顾： 1.环境部署：使用 Docker 快速构建隔离环境，避免依赖冲突 2.模型集成：启用 N-gram 语言模型显著提升中文识别质量 3.双模识别：支持上传文件与实时录音两种输入方式 4.多格式导出：一键生成 TXT、JSON、SRT 文件，满足多样化需求 5.性能调优：结合硬件条件灵活选择模型与参数配置
未来可扩展方向： - 集成 Whisper 模型做对比评测 - 构建 RESTful API 供 SpringBoot 等后端调用 - 增加说话人分离（diarization）功能 - 支持批量任务队列处理
掌握这套部署方案，你就可以在本地快速搭建一个企业级语音识别系统，无需依赖云端 API，兼顾效率与数据安全。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
