FunASR 离线文件转写服务开发指南
1. 简介
FunASR（Automatic Speech Recognition）离线文件转写软件包提供了一套功能完整的语音识别链路。它集成了语音端点检测（VAD）、语音识别、标点预测等模型，能够将长音频或视频转换为带标点的文字，并支持字级别时间戳输出。服务端集成 ffmpeg，兼容多种音视频格式，支持上百路并发请求。
推荐硬件配置如下：
- 基础型：4 核 vCPU，8G 内存，单机约支持 32 路请求
- 标准型：16 核 vCPU，32G 内存，单机约支持 64 路请求
- 高性能型：64 核 vCPU，128G 内存，单机约支持 200 路请求
2. 快速上手
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 镜像拉取与启动
创建资源目录并拉取镜像：
mkdir -p ./funasr-runtime-resources/models
交互式启动容器：
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 服务端启动
进入容器后启动服务程序。默认开启 SSL，如需关闭可添加 --certfile 0 参数。
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 &
注意：
- 热词文件格式为每行一个，例如
阿里巴巴 20。建议热词长度不超过 10，个数不超过 1k，权重 1~100。 - 若需使用 SenseVoiceSmall 模型或开启时间戳，请调整
--model-dir参数。 - 日志中若出现
Unable to open hotwords file且未设置热词，可忽略该警告。
3. 客户端用法详解
部署完成后，可通过 Python、C++、Java 或 HTML 网页版进行调用。
3.1 Python 客户端
下载测试工具包：
wget https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/sample/funasr_samples.tar.gz
运行示例：
python3 funasr_wss_client.py --host "127.0.0.1" --port 10095 --mode offline --audio_in "../audio/asr_example.wav"
常用参数说明：
--host: 服务 IP，默认为本机--port: 端口号，默认 10095--mode: 模式，offline表示离线文件转写--audio_in: 音频文件路径或 wav.scp 列表--ssl: 是否开启 SSL 校验，默认 1--use_itn: 是否启用数字文本转换，默认 1
若遇到 ModuleNotFoundError: No module named 'websockets'，请安装依赖：
pip install websockets==13.1
3.2 C++ 客户端
进入 samples/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 服务地址，如 ws://IP:10095/。若遇到 TLS 握手失败，请参照服务端部分关闭 SSL 证书。
3.4 Java 客户端
FunasrWsClient --host localhost --port 10095 --audio_in ./asr_example.wav --mode offline
Linux/Unix 环境下构建步骤：
cd funasr/runtime/java
make downjar
make buildwebsocket
make runclient
4. 服务端用法详解
4.1 启动参数
run_server.sh 支持灵活配置，核心参数包括：
--model-dir: 模型 ID 或本地路径--port: 监听端口，默认 10095--decoder-thread-num: 解码线程数，影响最大并发路数--certfile/--keyfile: SSL 证书路径，设为 0 可关闭 SSL--hotword: 全局热词文件路径
4.2 停止服务
ps -x | grep funasr-wss-server
kill -9 <PID>
4.3 热更新与定制
更换模型或参数需先停止服务，修改配置后重启。若使用 ModelScope 模型 ID，服务启动时会自动下载。若使用微调后的模型（如 .pb 文件），需重命名为 model.pb 并指定本地路径。
5. 自定义服务部署
FunASR runtime 代码已开源，支持二次开发。主要接口分为 VAD、ASR、PUNC 三个模块，均基于 ONNX Runtime。
VAD 示例：
FUNASR_HANDLE vad_handle = FsmnVadInit(model_path, thread_num);
FUNASR_RESULT result = FsmnVadInfer(vad_handle, wav_file.c_str(), NULL, 16000);
ASR 示例：
FUNASR_HANDLE asr_handle = FunOfflineInit(model_path, thread_num);
FUNASR_RESULT result = FunOfflineInfer(asr_handle, wav_file.c_str(), RASR_NONE, NULL, 16000);
PUNC 示例：
FUNASR_HANDLE punc_handle = CTTransformerInit(model_path, thread_num);
FUNASR_RESULT result = CTTransformerInfer(punc_handle, txt_str.c_str(), RASR_NONE, NULL);
详细实现可参考 GitHub 仓库中的示例代码。
