FunASR 离线文件转写服务开发指南

FunASR 离线文件转写服务开发指南

1. 简介

FunASR (Automatic Speech Recognition) 离线文件转写软件包提供了一款功能强大的语音离线文件转写服务。拥有完整的语音识别链路，结合了语音端点检测、语音识别、标点等模型，可以将几十个小时的长音频与视频识别成带标点的文字，而且支持上百路请求同时进行转写。输出为带标点的文字，含有字级别时间戳，支持 ITN 与用户自定义热词等。服务端集成有 ffmpeg，支持各种音视频格式输入。软件包提供有 html、python、c++、java 与 c#等多种编程语言客户端，用户可以直接使用与进一步开发。

推荐配置：

• 配置 1: （X86，计算型），4 核 vCPU，内存 8G，单机可以支持大约 32 路的请求
• 配置 2: （X86，计算型），16 核 vCPU，内存 32G，单机可以支持大约 64 路的请求
• 配置 3: （X86，计算型），64 核 vCPU，内存 128G，单机可以支持大约 200 路的请求

2. 快速上手

2.1 Docker 安装

官网推荐的安装方式：

# 下载安装脚本
curl -O https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/shell/install_docker.sh
# 执行安装命令
sudo bash install_docker.sh

2.2 镜像启动

通过下述命令拉取并启动 FunASR 软件包的 docker 镜像：

# 拉取镜像
sudo docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-cpu-0.4.7
# 创建资源文件夹
mkdir -p ./funasr-runtime-resources/models
# 交互式启动容器
sudo docker run -p 10095:10095 -it --privileged=true \
-v $PWD/funasr-runtime-resources/models:/workspace/models \
registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-cpu-0.4.7

2.3 服务端启动

docker 启动之后，进入到 docker 里边启动 funasr-wss-server 服务程序：

# 容器内的操作
cd FunASR/runtime
nohup bash run_server.sh \
--download-model-dir /workspace/models \
--vad-dir damo/speech_fsmn_vad_zh-cn-16k-common-onnx \
--model-dir damo/speech_paraformer-large-vad-punc_asr_nat-zh-cn-16k-common-vocab8404-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 \
--hotword /workspace/models/hotwords.txt > log.txt 2>&1 &

如果您想关闭 ssl，增加参数：--certfile 0。 如果您想使用 SenseVoiceSmall 模型、时间戳、nn 热词模型进行部署，请设置 --model-dir 为对应模型。 如果您想在服务端加载热词，请在宿主机文件 ./funasr-runtime-resources/models/hotwords.txt 配置热词（docker 映射地址为 /workspace/models/hotwords.txt）：每行一个热词，格式 (热词 权重)：阿里巴巴 20。

服务启动日志示例：

I20260303 11:01:52.311225 56 funasr-wss-server.cpp:516] asr model init finished. listen on port:10095

2.4 客户端测试与使用

下载客户端测试工具目录 samples：

wget https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/sample/funasr_samples.tar.gz

以 Python 语言客户端为例，支持多种音频格式输入（.wav, .pcm, .mp3 等），也支持视频输入 (.mp4 等)，以及多文件列表 wav.scp 输入。

python3 funasr_wss_client.py --host "127.0.0.1" --port 10095 --mode offline --audio_in "../audio/asr_example.wav"

运行结果包含识别文本及时间戳信息。

异常问题处理： 若报错 ModuleNotFoundError: No module named 'websockets'，可尝试安装：

pip install websockets==13.1

3. 客户端用法详解

目前分别支持以下几种编程语言客户端：Python, CPP, HTML 网页版本，Java。

3.1 Python Client

python3 funasr_wss_client.py --host "127.0.0.1" --port 10095 --mode offline \
--audio_in "../audio/asr_example.wav" --output_dir "./results"

命令参数说明：

• --host: FunASR runtime-SDK 服务部署机器 ip，默认为本机 ip（127.0.0.1）
• --port: 10095 部署端口号
• --mode: offline 表示离线文件转写
• --audio_in: 需要进行转写的音频文件，支持文件路径，文件列表 wav.scp
• --thread_num: 设置并发发送线程数，默认为 1
• --ssl: 设置是否开启 ssl 证书校验，默认 1 开启，设置为 0 关闭
• --hotword: 热词文件，每行一个热词，格式 (热词 权重)
• --use_itn: 设置是否使用 itn，默认 1 开启，设置为 0 关闭

3.2 C++ Client

进入 samples/cpp 目录后，可以用 cpp 进行测试：

./funasr-wss-client --server-ip 127.0.0.1 --port 10095 --wav-path ../audio/asr_example.wav

返回 JSON 格式数据，包含识别文本、时间戳等信息。

3.3 HTML 网页版

在浏览器中打开 html/static/index.html，即可出现页面，支持麦克风输入与文件上传，直接进行体验，需要输入 asr 服务地址 wss://IP:10095/。 若遇到 TLS handshake failed 错误，需关闭 SSL 重新启动 funasr 服务（增加参数 --certfile 0），并将地址改为 ws://IP:10095/。

3.4 Java Client

FunasrWsClient --host localhost --port 10095 --audio_in ./asr_example.wav --mode offline

详细可以参考文档。构建环境需安装 Java 环境（如 Ubuntu 下 apt-get install openjdk-11-jdk）。

4. 服务端用法详解

4.1 启动 FunASR 服务

cd /workspace/FunASR/runtime
nohup bash run_server.sh \
--download-model-dir /workspace/models \
--model-dir damo/speech_paraformer-large_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 \
--certfile ../../../ssl_key/server.crt \
--keyfile ../../../ssl_key/server.key \
--hotword ../../hotwords.txt > log.txt 2>&1 &

run_server.sh 命令参数介绍：

• --download-model-dir: 模型下载地址，通过设置 model ID 从 Modelscope 下载模型
• --model-dir: modelscope model ID 或者本地模型路径
• --port: 服务端监听的端口号，默认为 10095
• --decoder-thread-num: 服务端线程池个数 (支持的最大并发路数)
• --io-thread-num: 服务端启动的 IO 线程数
• --certfile: ssl 的证书文件，默认为 ../../../ssl_key/server.crt，如果需要关闭 ssl，参数设置为 0
• --hotword: 热词文件路径，每行一个热词，格式：热词 权重

4.2 关闭 FunASR 服务

ps -x | grep funasr-wss-server
kill -9 PID

4.3 修改模型及其他参数

替换正在使用的模型或者其他参数，需先关闭 FunASR 服务，修改需要替换的参数，并重新启动 FunASR 服务。其中模型需为 ModelScope 中的 ASR/VAD/PUNC 模型，或者从 ModelScope 中模型 finetune 后的模型。 例如替换 ASR 模型为 damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-onnx，则如下设置参数 --model-dir。 如果希望部署您 finetune 后的模型，需要手动将模型重命名为 model.pb，并将原 modelscope 中模型 model.pb 替换掉，将路径指定为 model_dir 即可。

5. 如何定制服务部署

FunASR-runtime 的代码已开源，如果服务端和客户端不能很好的满足您的需求，您可以根据自己的需求进行进一步的开发：

• C++ 客户端：https://github.com/alibaba-damo-academy/FunASR/tree/main/runtime/websocket
• Python 客户端：https://github.com/alibaba-damo-academy/FunASR/tree/main/runtime/python/websocket
• 自定义客户端：参考 websocket 通信协议。

C++ 服务端开发接口示例：

• VAD: FsmnVadInit, FsmnVadInfer
• ASR: FunOfflineInit, FunOfflineInfer
• PUNC: CTTransformerInit, CTTransformerInfer