SpringBoot实战：如何用FunASR实现实时语音转文字（附完整代码）

SpringBoot实战：用FunASR构建高可用实时语音转写服务

最近在为一个在线教育平台做功能升级，需要将老师的实时授课音频同步转成文字，生成课堂字幕和笔记。在技术选型时，我深入调研了几个主流的语音识别方案，最终选择了FunASR。它吸引我的点很明确：开源、支持实时流式识别、对中文优化友好，并且官方提供了相对完整的服务端和客户端生态。不过，从Docker部署到与SpringBoot项目无缝集成，再到处理生产环境中的稳定性问题，这中间确实有不少细节需要打磨。今天，我就把自己趟过的路、踩过的坑，以及最终沉淀下来的一套可落地方案，完整地分享出来。

这篇文章面向的是有一定Java和SpringBoot开发经验，需要在项目中快速引入实时语音识别能力的工程师。无论是构建智能客服的对话分析、在线会议的实时纪要，还是像我遇到的课堂字幕场景，这套架构和代码都能提供一个坚实的起点。我们不只讲“怎么做”，更会探讨“为什么这么做”，以及如何让它更健壮。

1. 理解FunASR：不只是另一个语音识别库

在动手之前，我们有必要先厘清FunASR的定位和核心优势。它并非一个简单的API调用封装，而是一个集成了语音端点检测（VAD）、语音识别（ASR）、标点恢复、语言模型等模块的完整工具包。这意味着，你拿到的不只是一个“听写”工具，而是一个能理解语音流上下文、智能断句并添加标点的“理解”系统。

对于实时场景，FunASR的“2pass”模式尤为关键。简单来说，它结合了流式识别的低延迟和非流式识别的高精度。当用户说话时，系统会进行快速的流式识别，给出即时文字；当检测到一句话结束时（通过VAD），系统会利用整句话的上下文信息，对刚才的流式识别结果进行一次“纠错”和“精修”，从而在速度和准确率之间取得很好的平衡。

几个核心概念：

• VAD (Voice Activity Detection)： 判断音频流中哪些部分是有效的人声，哪些是静音或噪音。这直接决定了识别的效率和准确性。
• Paraformer： FunASR默认使用的流式与非流式一体化端到端识别模型，对中文场景有很好的支持。
• 热词（Hotwords）： 你可以预先注入一些业务相关的专有名词或高频词（如产品名、技术术语），并赋予权重，模型在识别时会优先考虑这些词，显著提升特定领域的识别准确率。

注意： FunASR的模型文件通常较大（如Paraformer-large模型约300MB+），官方推荐使用Docker进行服务化部署，这能很好地解决环境依赖和资源隔离问题。我们的集成方案也将基于此展开。

2. 服务端部署：Docker化与生产级配置

将FunASR服务化是第一步，也是保证稳定性的基石。官方提供了预构建的Docker镜像，让部署变得异常简单。但生产环境需要考虑更多，比如模型管理、日志、资源监控等。

2.1 基础部署与模型准备

首先，我们需要拉取镜像并启动容器。这里我选择CPU版本的镜像，它对服务器要求更友好。如果你对延迟有极致要求且资源充足，可以考虑GPU版本。

# 1. 拉取官方CPU镜像
sudo docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.13

# 2. 在宿主机创建目录，用于持久化存储模型和热词文件
mkdir -p /opt/funasr/models
mkdir -p /opt/funasr/logs

# 3. 创建一个热词文件示例 (可选，但强烈推荐)
echo -e "SpringBoot 15\n微服务 10\nDocker 10\nKubernetes 8" > /opt/funasr/models/hotwords.txt

接下来是启动容器的命令。这里有几个关键参数需要解释：

# 4. 启动Docker容器
sudo docker run -d \
  --name funasr-server \
  --restart unless-stopped \
  -p 10095:10095 \
  -v /opt/funasr/models:/workspace/models \
  -v /opt/funasr/logs:/workspace/logs \
  registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.13 \
  bash -c "cd /workspace/FunASR/runtime && nohup bash run_server_2pass.sh \
    --download-model-dir /workspace/models \
    --model-dir damo/speech_paraformer-large-vad-punc_asr_nat-zh-cn-16k-common-vocab8404-onnx \
    --online-model-dir damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-online-onnx \
    --vad-dir damo/speech_fsmn_vad_zh-cn-16k-common-onnx \
    --punc-dir damo/punc_ct-transformer_zh-cn-common-vad_realtime-vocab272727-onnx \
    --hotword /workspace/models/hotwords.txt \
    --certfile 0 \
    >> /workspace/logs/server.log 2>&1 & tail -f /workspace/logs/server.log"

参数解析表：

参数	说明	生产环境建议
-p 10095:10095	将容器内的WebSocket服务端口映射到宿主机。	可考虑使用Nginx反向代理，并配置SSL。
-v /opt/funasr/models:/workspace/models	挂载模型目录，避免每次重启重新下载。	必须，加速启动并保证一致性。
-v /opt/funasr/logs:/workspace/logs	挂载日志目录，方便排查问题。	必须，用于监控和调试。
--download-model-dir	指定模型下载和缓存的目录。	指向挂载的宿主机目录。
--model-dir	离线（2pass第二遍）模型路径。	使用默认的Paraformer-large模型，精度高。
--online-model-dir	在线（流式）模型路径。	配套的流式版本。
--certfile 0	关闭SSL。简化内网测试，生产环境应配置正式证书。	内网测试可用，公网务必启用SSL。
--hotword	指定热词文件路径。	根据业务定制，能大幅提升专业词汇识别率。

执行后，通过 docker logs -f funasr-server 观察日志，看到“model init finished”等字样即表示服务启动成功。首次启动会因为下载模型而较慢，后续