FunASR 离线文件转写服务开发指南
1. 什么是 FunASR
FunASR（Automatic Speech Recognition）离线文件转写软件包提供了一套功能完整的语音识别链路。它结合了语音端点检测（VAD）、语音识别、标点恢复等模型，能够将几十个小时的长音频或视频识别为带标点的文字，并支持字级别的时间戳输出。
服务特性包括：
- 支持上百路并发请求进行转写
- 输出包含标点符号和字级时间戳
- 支持 ITN（逆文本规范化）与用户自定义热词
- 服务端集成 ffmpeg，兼容多种音视频格式输入
- 提供 Python、C++、Java、HTML 等多种语言客户端 SDK
推荐硬件配置如下：
- 入门级：4 核 vCPU，8G 内存，单机约支持 32 路请求
- 进阶级：16 核 vCPU，32G 内存，单机约支持 64 路请求
- 高性能：64 核 vCPU，128G 内存，单机约支持 200 路请求
2. 快速上手
本次实践基于 openEuler 22.03 LTS-SP3 环境，Docker 版本为 27.4.0。
2.1 Docker 安装
使用官方脚本安装 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 运行时镜像并创建资源目录：
# 拉取镜像
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 服务端启动
进入容器后，启动 funasr-wss-server 服务。这里需要注意模型路径映射及 SSL 配置：
# 容器内操作
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 &
参数说明：
--certfile 0：如需关闭 SSL，请增加此参数。--model-dir：若需使用 SenseVoiceSmall 模型或开启时间戳，可替换为对应模型 ID。hotwords.txt：在宿主机配置热词文件（每行格式：热词 权重），建议热词长度不超过 10，数量不超过 1k。
启动日志示例：
I20260303 11:01:52.311225 funasr-wss-server.cpp:516] asr model init finished. listen on port:10095
若需部署 8k 采样率模型，请使用以下命令调整 VAD 及 ASR 模型路径。
2.4 客户端测试
下载官方提供的测试样本：
wget https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/sample/funasr_samples.tar.gz
以 Python 客户端为例，支持 .wav, .mp3, .mp4 等多种格式：
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
运行结果会返回识别文本及字级时间戳：
timestamp: [[880,1120],[1120,1380],...]
text: 欢迎大家来体验达摩院推出的语音识别模型。
3. 客户端用法详解
服务部署完成后，可通过不同语言的 SDK 接入。目前主要支持 Python、C++、HTML 及 Java。
3.1 Python Client
Python 客户端最为常用，参数灵活：
python3 funasr_wss_client.py --host "127.0.0.1" --port 10095 --mode offline \
--audio_in "../audio/asr_example.wav" --output_dir "./results"
关键参数：
--host: 服务 IP，默认本机。--ssl: 是否开启证书校验，默认为 1。--use_itn: 是否启用逆文本规范化，默认为 1。--hotword: 热词文件路径。
实测对比 Whisper 模型，FunASR 在中文场景下的标点恢复和专有名词识别表现更为稳健，但也存在个别语境差异，建议结合业务数据微调。
3.2 C++ Client
进入 samples/cpp 目录进行测试：
./funasr-wss-client --server-ip 127.0.0.1 --port 10095 --wav-path ../audio/asr_example.wav
返回结果为 JSON 格式，包含 text_seg 分段信息及 ts_list 时间戳列表。
3.3 HTML 网页版
浏览器打开 html/static/index.html 即可体验。注意：
- 默认服务开启 SSL，前端地址应为
wss://IP:10095/。 - 若遇到 TLS handshake failed，需在服务端启动时添加
--certfile 0关闭 SSL，并将前端地址改为ws://IP:10095/。
3.4 Java Client
Java 客户端需要编译构建：
cd funasr/runtime/java
make downjar # 下载依赖
make build # 编译
make runclient # 运行
命令行调用示例：
FunasrWsClient --host localhost --port 10095 --audio_in ./asr_example.wav --mode offline
4. 服务端用法详解
4.1 启动与停止
启动脚本已封装了大部分参数，核心是模型路径和线程数配置。停止服务时，先查找进程 PID：
ps -x | grep funasr-wss-server
kill -9 <PID>
4.2 模型热更新与参数调整
更换模型或调整参数需重启服务。支持的模型类型包括 ModelScope 中的 ASR、VAD、PUNC 模型，也支持本地 finetune 后的模型（需重命名为 model.pb）。
常用参数调整：
--decoder-thread-num: 控制最大并发路数。--io-thread-num: IO 线程数。--model-thread-num: ONNX 推理并行线程数。
5. 定制服务部署
FunASR runtime 代码已开源，可根据需求二次开发。
- C++ 客户端: GitHub 仓库
- Python 客户端: GitHub 仓库
- 通信协议: WebSocket 协议文档
若需深度定制 VAD、ASR 或 PUNC 模块，可参考底层 API 调用示例：
// VAD 初始化与推理
FUNASR_HANDLE vad_hanlde = FsmnVadInit(model_path, thread_num);
FUNASR_RESULT result = FsmnVadInfer(vad_hanlde, wav_file.c_str(), NULL, 16000);
// ASR 初始化与推理
FUNASR_HANDLE asr_hanlde = FunOfflineInit(model_path, thread_num);
FUNASR_RESULT result = FunOfflineInfer(asr_hanlde, wav_file.c_str(), RASR_NONE, NULL, 16000);
具体实现细节请参考官方 GitHub 仓库中的 bin 目录下示例代码。
