FunASR语音识别二次开发镜像使用指南与实操案例
1. 快速入门与环境准备
1.1 镜像简介
本文介绍的镜像为FunASR 语音识别基于 speech_ngram_lm_zh-cn 二次开发构建 by 科哥，是一款专为中文语音识别优化的 WebUI 封装版本。该镜像在原始 FunASR 框架基础上集成了语言模型（N-gram LM）、标点恢复、语音活动检测（VAD）等能力，并提供了图形化操作界面，极大降低了部署和使用门槛。
镜像特点：
- 支持多格式音频输入（WAV、MP3、M4A 等）
- 提供 Paraformer-Large 和 SenseVoice-Small 双模型选择
- 内置 VAD + PUNC + 时间戳输出功能
- 支持实时录音与文件上传两种识别方式
- 输出支持 TXT、JSON、SRT 字幕格式导出
1.2 启动镜像服务
假设您已安装 Docker 环境，可通过以下命令拉取并运行该镜像：
# 拉取镜像 sudo docker pull <镜像仓库地址>/funasr-speech-ngram-lm-zhcn:koge # 创建模型挂载目录 mkdir -p ./funasr_models # 启动容器（映射端口7860，挂载模型目录） sudo docker run -it --gpus all \ -p 7860:7860 \ -v $PWD/funasr_models:/workspace/models \ <镜像仓库地址>/funasr-speech-ngram-lm-zhcn:koge说明：
--gpus all表示启用 GPU 加速（需宿主机安装 NVIDIA 驱动及 nvidia-docker），若仅使用 CPU 可移除此参数。
启动成功后，终端将显示服务监听信息，表明 WebUI 已就绪。
2. WebUI 界面详解与核心功能
2.1 访问与登录
服务启动后，在浏览器中访问：
http://localhost:7860如需远程访问，请替换localhost为服务器 IP 地址：
http://<服务器IP>:7860页面加载完成后，即可进入主界面。
2.2 主界面结构解析
头部区域
- 标题：FunASR 语音识别 WebUI
- 描述：基于 FunASR 的中文语音识别系统
- 版权信息：webUI二次开发 by 科哥 | 微信：312088415
该部分为固定展示内容，保留开发者信息以符合开源协议要求。
2.3 控制面板功能详解（左侧）
模型选择
| 模型名称 | 特点 | 推荐场景 |
|---|---|---|
| Paraformer-Large | 高精度、大参数量 | 对准确率要求高的正式任务 |
| SenseVoice-Small | 响应快、资源占用低 | 实时交互或边缘设备 |
默认选中 SenseVoice-Small，用户可根据实际需求切换。
设备选择
- CUDA：利用 GPU 进行推理加速，显著提升长音频处理速度
- CPU：适用于无独立显卡的环境，兼容性更强但性能较低
系统会自动检测 GPU 状态，若有可用 CUDA 设备则默认勾选。
功能开关
- ✅启用标点恢复 (PUNC)
自动为识别结果添加句号、逗号等标点符号，提升可读性。 - ✅启用语音活动检测 (VAD)
自动分割静音段落，避免无效识别，提高效率。 - ✅输出时间戳
在结果中标注每句话的起止时间，便于后期对齐编辑。
建议三项均开启以获得完整功能体验。
模型状态与操作按钮
- 显示当前模型是否已成功加载（✓ / ✗）
- “加载模型”按钮用于手动触发模型初始化或重新加载
- “刷新”按钮更新当前状态显示
3. 使用流程详解：从上传到输出
3.1 方式一：上传音频文件识别
步骤 1：准备音频文件
支持格式包括：
.wav,.mp3,.m4a,.flac,.ogg,.pcm
推荐参数：
- 采样率：16kHz
- 单声道（Mono）
- 位深：16bit
高质量音频有助于提升识别准确率，尤其在嘈杂环境中。
步骤 2：上传音频
点击 ASR 区域的“上传音频”按钮，选择本地文件上传。支持拖拽操作，上传完成后自动显示波形图预览。
步骤 3：配置识别参数
- 批量大小（秒）：默认 300 秒（5 分钟），最大支持 600 秒
- 作用：控制每次送入模型的音频长度，过长可能导致内存溢出
- 识别语言：
auto：自动检测（推荐）zh：强制中文识别en：英文yue：粤语ja：日语ko：韩语
混合语种建议使用auto，纯中文内容可指定zh提升稳定性。
步骤 4：开始识别
点击“开始识别”按钮，系统将执行以下流程：
- 若启用 VAD，则先进行语音段落切分
- 调用选定模型进行 ASR 解码
- 若启用 PUNC，则追加标点预测
- 若启用时间戳，则生成词级/句级时间区间
处理进度可在界面上方查看。
步骤 5：查看识别结果
结果分为三个标签页展示：
文本结果
显示最终转录文本，支持一键复制。
示例：
你好，欢迎使用语音识别系统。这是一个基于 FunASR 的中文语音识别 WebUI。详细信息（JSON）
包含完整结构化数据，字段如下：
{ "text": "识别文本", "segments": [ { "start": 0.0, "end": 2.5, "text": "你好", "confidence": 0.98 } ] }适用于程序调用或进一步分析。
时间戳
以[序号] 开始时间 - 结束时间 (时长)格式展示：
[001] 0.000s - 0.500s (时长: 0.500s) [002] 0.500s - 2.500s (时长: 2.000s)常用于视频字幕制作或语音对齐。
3.2 方式二：浏览器实时录音识别
步骤 1：授权麦克风权限
点击“麦克风录音”按钮，浏览器会弹出权限请求框，点击“允许”。
注意：部分浏览器（如 Safari）可能限制非 HTTPS 页面获取麦克风权限。
步骤 2：录制语音
录制过程中可看到实时音量条反馈。点击“停止录音”结束录制。
步骤 3：启动识别
与上传模式相同，点击“开始识别”即可处理录音数据。
步骤 4：查看结果
结果展示方式与上传模式一致，支持三类输出查看。
4. 结果导出与高级设置
4.1 下载识别结果
识别完成后提供三种格式下载：
| 按钮 | 文件格式 | 用途 |
|---|---|---|
| 下载文本 | .txt | 纯文本记录，适合文档整理 |
| 下载 JSON | .json | 结构化数据，便于程序处理 |
| 下载 SRT | .srt | 视频字幕标准格式，可直接导入剪辑软件 |
所有文件统一保存至：
outputs/outputs_YYYYMMDDHHMMSS/例如：
outputs/outputs_20260104123456/ ├── audio_001.wav ├── result_001.json ├── text_001.txt └── subtitle_001.srt每次识别创建独立目录，防止覆盖。
4.2 高级功能配置建议
批量大小调整策略
| 音频长度 | 推荐 batch_size |
|---|---|
| < 1分钟 | 60 秒 |
| 1~3分钟 | 120 秒 |
| 3~5分钟 | 300 秒 |
| > 5分钟 | 分段处理 |
过大的 batch_size 可能导致 OOM（内存溢出），尤其是在 CPU 模式下。
语言识别最佳实践
- 中文普通话 →
zh - 英文会议 →
en - 粤语访谈 →
yue - 多语种混杂 →
auto
正确设置语言可避免误识别（如将“苹果”识别成“Apple”）。
时间戳应用场景
- 视频剪辑：精准定位台词位置
- 教学录音：标记知识点时间节点
- 法庭笔录：还原发言顺序与间隔
启用后可在 JSON 和 SRT 中获取时间信息。
5. 常见问题排查与优化建议
5.1 识别不准确怎么办？
原因分析与解决方案：
| 问题现象 | 可能原因 | 解决方法 |
|---|---|---|
| 错别字多 | 音频质量差 | 使用降噪工具预处理 |
| 漏识严重 | VAD 过于敏感 | 关闭 VAD 或更换模型 |
| 乱码出现 | 编码异常或语言错配 | 检查音频编码，确认语言设置 |
| 数字错误 | 未启用 ITN | 确保语言模型包含 itn_dir |
提升准确率的通用建议：
- 使用 16kHz 采样率、单声道 WAV 格式
- 减少背景噪音（推荐使用 Audacity 降噪）
- 发音清晰、语速适中
- 优先选用 Paraformer-Large 模型
5.2 识别速度慢如何优化？
性能瓶颈判断：
| 现象 | 判断依据 | 优化方案 |
|---|---|---|
| 延迟高 | 使用 CPU 模式 | 切换至 CUDA 设备 |
| 卡顿频繁 | 显存不足 | 降低 batch_size |
| 启动慢 | 模型未缓存 | 首次加载后复用 |
提速技巧：
- 启用 GPU 加速（NVIDIA 显卡 + CUDA）
- 使用 SenseVoice-Small 替代 Large 模型
- 分段处理超长音频（>5分钟建议切片）
5.3 其他常见问题
| 问题 | 检查项 |
|---|---|
| 无法上传文件 | 文件格式是否支持？大小是否超过限制？ |
| 录音无声 | 浏览器是否授权？麦克风是否被占用？ |
| 模型加载失败 | 是否挂载了正确的模型路径？磁盘空间是否充足？ |
| 页面无法访问 | 端口 7860 是否被防火墙屏蔽？Docker 是否正常运行？ |
6. 服务管理与退出方式
6.1 停止服务
在运行容器的终端中按下：
Ctrl + C或在其他终端执行：
pkill -f "python.*app.main"也可通过 Docker 命令停止容器：
docker stop <container_id>6.2 快捷键汇总
| 操作 | 快捷键 |
|---|---|
| 停止服务 | Ctrl + C |
| 刷新页面 | F5 或 Ctrl + R |
| 复制文本 | Ctrl + C |
| 粘贴音频 | Ctrl + V（部分浏览器支持） |
7. 总结
本文全面介绍了FunASR 语音识别基于 speech_ngram_lm_zh-cn 二次开发构建 by 科哥镜像的使用方法与实战技巧。该镜像通过 WebUI 封装大幅简化了 FunASR 的使用流程，具备以下优势：
- ✅ 图形化操作，零代码基础也可上手
- ✅ 支持双模型切换，兼顾精度与速度
- ✅ 完整集成 VAD、PUNC、LM 等模块
- ✅ 多格式导出满足不同下游需求
- ✅ 开源免费，承诺永久可用
无论是用于会议纪要转写、教学录音整理，还是视频字幕生成，该镜像都能提供稳定高效的语音识别支持。
未来可拓展方向包括：
- 集成自定义热词库
- 支持批量任务队列
- 添加 REST API 接口供外部调用
掌握本指南内容后，用户可在 10 分钟内完成部署并投入实际使用。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
