FunASR语音识别实操手册：从安装到API调用的全流程
1. 引言
随着语音交互技术的快速发展，高精度、低延迟的语音识别系统在智能客服、会议记录、字幕生成等场景中发挥着关键作用。FunASR 是一个由阿里巴巴开源的高性能语音识别工具包，支持多种预训练模型和灵活部署方式。本文介绍的FunASR 语音识别 WebUI是基于speech_ngram_lm_zh-cn模型二次开发的中文语音识别系统，由开发者“科哥”封装为可视化界面，极大降低了使用门槛。
本手册将带你完成从环境搭建、服务启动、WebUI操作到API调用的完整流程，帮助你快速上手并集成到实际项目中。
2. 环境准备与安装
2.1 系统要求
- 操作系统：Linux（推荐 Ubuntu 18.04+）、macOS 或 Windows（通过 WSL）
- Python 版本：3.8 - 3.10
- GPU 支持（可选）：
- NVIDIA 显卡 + CUDA 11.7+
- cuDNN 8.0+
- 内存建议：至少 8GB RAM（CPU模式），GPU模式建议 16GB+
2.2 安装依赖
# 创建虚拟环境（推荐） python -m venv funasr-env source funasr-env/bin/activate # Linux/macOS # 或 funasr-env\Scripts\activate # Windows # 升级 pip pip install --upgrade pip # 安装 FunASR 核心库 pip install modelscope funasr torch torchaudio # 若使用 GPU，请安装对应版本的 PyTorch（示例为 CUDA 11.7） pip install torch==1.13.1+cu117 torchaudio==0.13.1+cu117 -f https://download.pytorch.org/whl/torch_stable.html2.3 克隆并安装 WebUI 项目
git clone https://github.com/kege/funasr-webui.git cd funasr-webui # 安装项目依赖 pip install -r requirements.txt # 启动服务 python app/main.py启动成功后，终端会输出如下信息：
Running on local URL: http://localhost:7860 Running on public URL: http://<your-ip>:78603. WebUI 使用详解
3.1 访问地址
服务启动后，在浏览器中访问以下任一地址：
http://localhost:7860或远程访问（需开放端口）：
http://<服务器IP>:7860提示：首次加载可能需要数分钟时间自动下载模型文件，请保持网络畅通。
3.2 界面布局说明
整个界面分为左右两部分：左侧为控制面板，右侧为功能区。
左侧控制面板
模型选择
- Paraformer-Large：大参数量模型，识别准确率高，适合对精度要求高的场景。
- SenseVoice-Small：轻量级模型，响应速度快，适合实时语音转写。
设备选择
- CUDA：启用 GPU 加速，显著提升处理速度（推荐有显卡用户使用）。
- CPU：通用模式，适用于无独立显卡设备。
功能开关
- 启用标点恢复 (PUNC)：自动为识别结果添加句号、逗号等标点符号。
- 启用语音活动检测 (VAD)：自动切分静音段，避免无效内容干扰。
- 输出时间戳：返回每个词或句子的时间区间，便于后期编辑。
操作按钮
- 加载模型：手动触发模型加载或重新加载。
- 刷新：更新当前模型状态显示。
4. 语音识别操作流程
4.1 方式一：上传音频文件识别
步骤 1：准备音频文件
支持格式包括： - WAV (.wav) - MP3 (.mp3) - M4A (.m4a) - FLAC (.flac) - OGG (.ogg) - PCM (.pcm)
推荐参数： - 采样率：16kHz - 位深：16bit - 单声道（Mono）
步骤 2：上传音频
- 在右侧“ASR 语音识别”区域点击“上传音频”按钮；
- 选择本地音频文件；
- 等待上传完成。
步骤 3：配置识别参数
| 参数 | 可选项 | 说明 |
|---|---|---|
| 批量大小（秒） | 60–600 | 默认 300 秒（5 分钟），用于分块处理长音频 |
| 识别语言 | auto, zh, en, yue, ja, ko | 推荐auto自动识别，多语种混合内容适用 |
步骤 4：开始识别
点击“开始识别”按钮，系统将自动进行解码并返回结果。
步骤 5：查看识别结果
结果以三个标签页形式展示：
- 文本结果：纯文本输出，可直接复制使用。
- 详细信息：JSON 格式，包含置信度、时间戳等元数据。
- 时间戳：按
[序号] 开始时间 - 结束时间 (时长)格式列出每段语音的时间范围。
4.2 方式二：浏览器实时录音识别
步骤 1：授权麦克风权限
点击“麦克风录音”按钮，浏览器会弹出权限请求，点击“允许”。
步骤 2：录制语音
- 录音过程中会有波形动画反馈；
- 点击“停止录音”结束录制。
步骤 3：执行识别
与上传文件相同，点击“开始识别”即可处理录音数据。
步骤 4：获取结果
结果展示方式与上传文件一致，支持文本、JSON 和 SRT 字幕导出。
5. 结果导出与高级设置
5.1 下载识别结果
识别完成后，可通过以下按钮下载不同格式的结果：
| 按钮 | 输出格式 | 用途 |
|---|---|---|
| 下载文本 | .txt | 纯文本，便于粘贴使用 |
| 下载 JSON | .json | 包含完整结构化数据，适合程序解析 |
| 下载 SRT | .srt | 视频字幕标准格式，兼容主流播放器 |
所有输出文件保存路径为：
outputs/outputs_YYYYMMDDHHMMSS/例如：
outputs/outputs_20260104123456/ ├── audio_001.wav ├── result_001.json ├── text_001.txt └── subtitle_001.srt每次识别生成独立目录，防止文件覆盖。
5.2 高级功能配置
批量大小调整
对于超过 5 分钟的长音频，建议设置批量大小为 600 秒（10 分钟），系统会自动分段处理并合并结果。
语言识别优化
- 中文为主 → 选择
zh - 英文演讲 → 选择
en - 粤语访谈 → 选择
yue - 多语种混杂 → 使用
auto提高适应性
时间戳应用
启用“输出时间戳”后，可用于： - 视频剪辑中的语音定位 - 自动生成带时间轴的会议纪要 - 构建语音搜索引擎索引
6. API 接口调用指南
除了 WebUI 操作，FunASR 还支持通过 HTTP API 集成到其他系统中。
6.1 API 基础信息
- 协议：HTTP POST
- Content-Type：multipart/form-data
- 接口地址：
http://localhost:7860/asr
6.2 请求参数
| 参数名 | 类型 | 必填 | 描述 |
|---|---|---|---|
| audio_file | file | 是 | 音频文件 |
| model_type | string | 否 | 模型类型，可选paraformer,sensevoice |
| device | string | 否 | 设备类型，cuda或cpu |
| language | string | 否 | 语言代码，默认auto |
| add_punc | boolean | 否 | 是否添加标点，默认 false |
| return_timestamp | boolean | 否 | 是否返回时间戳，默认 false |
6.3 Python 调用示例
import requests url = "http://localhost:7860/asr" files = {'audio_file': open('test.wav', 'rb')} data = { 'model_type': 'paraformer', 'device': 'cuda', 'language': 'zh', 'add_punc': True, 'return_timestamp': True } response = requests.post(url, files=files, data=data) result = response.json() print("识别文本：", result['text']) print("时间戳信息：", result['timestamps'])6.4 返回结果示例
{ "text": "你好，欢迎使用语音识别系统。", "timestamps": [ {"text": "你好", "start": 0.0, "end": 0.8}, {"text": "欢迎使用语音识别系统", "start": 0.8, "end": 3.2} ], "confidence": 0.96 }7. 常见问题与解决方案
7.1 识别准确率低
原因分析与对策： - 音频质量差 → 使用降噪工具预处理 - 语言设置错误 → 明确指定zh或en- 背景噪音大 → 启用 VAD 并配合前端降噪算法 - 发音不清晰 → 建议用户放慢语速、提高音量
7.2 识别速度慢
排查方向： - 是否使用 CPU 模式？→ 切换至 CUDA 加速 - 音频过长？→ 分段处理或减小 batch size - 模型过大？→ 尝试切换为 SenseVoice-Small 模型
7.3 文件上传失败
检查项： - 文件格式是否支持（优先使用 WAV/MP3） - 文件大小是否超过限制（建议 < 100MB） - 浏览器缓存问题 → 清除缓存或更换浏览器重试
7.4 实时录音无声
解决方法： - 确认浏览器已授予麦克风权限 - 检查系统音频输入设备是否正常 - 测试其他录音软件确认硬件可用
7.5 输出乱码或异常字符
处理建议： - 检查音频编码格式是否标准 - 尝试转换为 PCM 编码的 WAV 文件再上传 - 更新 FunASR 至最新版本修复潜在 Bug
8. 性能优化建议
为了获得最佳识别体验，建议遵循以下实践：
- 优先使用 GPU：相比 CPU，推理速度可提升 3–5 倍。
- 合理选择模型：
- 精度优先 → Paraformer-Large
- 速度优先 → SenseVoice-Small
- 音频预处理：
- 统一转为 16kHz 单声道
- 使用 SoX 或 FFmpeg 进行标准化
- 批量处理长音频：利用时间戳实现精准分段。
- 启用标点恢复：提升文本可读性，减少后期编辑成本。
9. 总结
本文全面介绍了基于speech_ngram_lm_zh-cn模型二次开发的 FunASR 语音识别 WebUI 的使用方法，涵盖环境安装、界面操作、两种识别方式（上传文件与实时录音）、结果导出、API 调用及常见问题处理。
该系统具备以下核心优势： -开箱即用：无需编写代码即可完成语音识别任务； -多模型支持：兼顾精度与速度的双模型选择； -多格式导出：满足文本、结构化数据和字幕制作需求； -可扩展性强：提供标准 API 接口，便于集成进企业级应用。
无论是个人学习、科研实验还是商业项目落地，这套方案都能为你提供稳定高效的语音识别能力。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
