FunASR funasr_torch基于 LibTorch 的高性能 ASR 推理部署完全指南【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR本文以 FunASR 仓库中 runtime/python/libtorch/README.md 为主体系统讲解funasr_torch这一基于 LibTorchPyTorch TorchScript 运行时的轻量级推理部署包从模型导出、安装、Paraformer / SenseVoice 模型加载与推理调用到热词增强、量化加速与 RTF 性能数据并结合仓库源码逐层剖析其内部推理管线帮助你在不依赖完整 FunASR 训练框架的前提下将离线 ASR 模型以更低开销部署到 CPU/GPU 生产环境。1. libtorch 后端在 FunASR 部署体系中的定位FunASR 支持多种推理后端。在 runtime/python/libtorch/README.md 的 Speed 一节中给出了同一 5.53 秒中文语音100 次平均在 Intel Xeon Platinum 8163 CPU 2.50GHz 上的 RTF 对比后端RTF (FP32)Pytorch0.110Libtorch0.048Onnx0.038从这张表可以看出 libtorch 后端的定位它直接加载 TorchScript 导出的模型文件torch.jit.load省去了 Python 侧 PyTorch 解释执行的开销RTF 约为完整 PyTorch 推理的一半不到若追求极致速度还可以选择 ONNX Runtime 后端见 runtime/python/onnxruntime/或开启 int8 量化进一步提速见第 8 节 runtime/docs/benchmark_libtorch.md 中的量化数据。funasr_torch包的核心设计目标是零框架依赖地运行 FunASR 离线模型它只需要model.torchscriptconfig.yamlam.mvn等少数文件配合 funasr_torch/utils/frontend.py 中的 WavFrontend 特征前端即可独立跑通完整的 ASR 推理闭环。2. 安装 funasr_torch2.1 从 PyPI 安装pip install -U funasr_torch文档同时提示国内用户可改用国内镜像源安装。2.2 从源码安装git clone https://gitcode.com/GitHub_Trending/fun/FunASR.git cd FunASR cd funasr/runtime/python/libtorch pip install -e ./仓库中 runtime/python/libtorch/setup.py 声明了该包名为funasr_torch当前源码版本为0.1.3运行时依赖包括librosa onnxruntime1.7.0 scipy numpy1.19.3 kaldi-native-fbank PyYAML5.1.2 torch-quant 0.4.0从源码结构看setup.py中find_packages(include[torch_paraformer*])的打包规则与本地目录名funasr_torch并不完全对应因此官方文档推荐以pip install -e ./的源码 editable 方式安装可以确保直接引用本地funasr_torch/目录规避打包规则带来的模块名偏差。包入口 funasr_torch/init.py 对外只暴露两个推理类from .paraformer_bin import Paraformer from .sensevoice_bin import SenseVoiceSmall实际目录结构如下runtime/python/libtorch/ ├── README.md ├── setup.py ├── demo_paraformer.py # Paraformer 基础 ASR demo ├── demo_contextual_paraformer.py # 热词版 Paraformer demo ├── demo_seaco_paraformer.py # SeacoParaformer demo ├── demo_sensevoice_small.py # SenseVoiceSmall demo └── funasr_torch/ ├── __init__.py ├── paraformer_bin.py # Paraformer / ContextualParaformer / SeacoParaformer ├── sensevoice_bin.py # SenseVoiceSmall └── utils/ ├── frontend.py # WavFrontendfbank LFR CMVN ├── timestamp_utils.py # LFR6 时间戳计算 ├── postprocess_utils.py # 句子级后处理 / ITN 后处理 ├── sentencepiece_tokenizer.py ├── compute_wer.py └── utils.py # CharTokenizer / TokenIDConverter / pad_list 等3. 导出 TorchScript 模型funasr_torch加载的是 TorchScript 模型。README 给出的导出命令为# 先安装 modelscope 与 funasr pip install -U modelscope funasr pip install torch-quant # Optional, for torchscript quantization pip install onnx onnxruntime # Optional, for onnx quantizationpython -m funasr.export.export_model \ --model-name damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch \ --export-dir ./export \ --type torch --quantize True其中--type torch表示导出 TorchScript 格式--quantize True表示同时产出 int8 量化模型依赖torch-quant。3.1 当前仓库中的导出入口当前仓库中导出 CLI 的实际实现位于 funasr/bin/export.py它基于 hydra 接收参数并调用AutoModel.export()model AutoModel(**kwargs) res model.export( inputkwargs.get(input, None), typekwargs.get(type, onnx), # 默认 onnx可指定 torchscript/torch quantizekwargs.get(quantize, False), fallback_numkwargs.get(fallback-num, 5), calib_numkwargs.get(calib_num, 100), # int8 量化的校准样本数 opset_versionkwargs.get(opset_version, 14), )export方法的定义在 funasr/auto/auto_model.py#L1263具体导出逻辑模型 trace/jit 序列化、量化等位于 funasr/utils/export_utils.py。README 中的模块路径与当前仓库的funasr/bin/export.py存在版本差异以当前仓库代码为准。3.2 自动补导出机制值得注意的是funasr_torch各推理类都内置了缺模型自动导出逻辑。以 funasr_torch/paraformer_bin.py 中Paraformer.__init__为例model_file os.path.join(model_dir, model.torchscript) if quantize: model_file os.path.join(model_dir, model_quant.torchscript) if not os.path.exists(model_file): print(.torchscripts does not exist, begin to export torchscript) model AutoModel(modelmodel_dir) model_dir model.export(typetorchscript, quantizequantize, **kwargs)也就是说只要把model_dir指向一个已下载、包含 PyTorch 权重与config.yaml的模型目录构造器就会自动调用AutoModel.export(typetorchscript)补齐 TorchScript 文件无需手工执行导出命令——这是源码层面相对 README 的一个便利性补充。4. 模型目录要求结合 paraformer_bin.py 的加载逻辑不同模型对目录文件的要求如下Paraformer基础版文件作用model.torchscript量化时为model_quant.torchscript通过torch.jit.load加载的声学模型config.yaml读取frontend_conf前端参数、model_conf.predictor_bias、lang等am.mvn声学模型 CMVN 均值/方差统计文件tokens.json词表用于TokenIDConverter将 token id 还原为字符ContextualParaformer / SeacoParaformer热词版if quantize: model_bb_file os.path.join(model_dir, model_bb_quant.torchscript) model_eb_file os.path.join(model_dir, model_eb_quant.torchscript) else: model_bb_file os.path.join(model_dir, model_bb.torchscript) model_eb_file os.path.join(model_dir, model_eb.torchscript)即需要双塔结构文件model_bb.torchscriptencoder-bi 声学编码器与model_eb.torchscriptembedding-bi 热词嵌入编码器分别由torch.jit.load加载为ort_infer_bb/ort_infer_eb两个推理句柄。SenseVoiceSmallfunasr_torch/sensevoice_bin.pymodel.torchscript量化时为model_quant.torchscriptconfig.yaml、am.mvnam.mvn会被注入frontend_conf[cmvn_file]chn_jpn_yue_eng_ko_spectok.bpe.model中文/日文/粤语/英文/韩文多语种的 BPE SentencePiece 词表由 utils/sentencepiece_tokenizer.py 的SentencepiecesTokenizer加载5. Paraformer 基础推理5.1 构造参数Paraformer.__init__的签名与默认值源码见 paraformer_bin.py#L27-L36def __init__( self, model_dir: Union[str, Path] None, # 本地路径或 ModelScope 模型名 batch_size: int 1, # 批大小 device_id: Union[str, int] -1, # -1 表示 CPU0 表示 GPU 卡号 plot_timestamp_to: str , # 非空时输出 timestamp.png 波形时间戳图 quantize: bool False, # True 时加载 model_quant.torchscript cache_dir: str None, # ModelScope 下载缓存目录 **kwargs, ):model_dir若不存在于本地会自动触发 ModelScope 的snapshot_download下载下载失败会抛出带安装提示的RuntimeError。5.2 调用示例仓库提供的 demo_paraformer.pyfrom pathlib import Path from funasr_torch.paraformer_bin import Paraformer model_dir iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch model Paraformer(model_dir, batch_size1) # cpu # model Paraformer(model_dir, batch_size1, device_id0) # gpu wav_path {}/.cache/modelscope/hub/{}/example/asr_example.wav.format(Path.home(), model_dir) result model(wav_path) print(result)5.3 输入输出规范README 与源码签名一致def __call__(self, wav_content: Union[str, np.ndarray, List[str]], **kwargs) - ListInputstr单个 wav 路径、np.ndarray波形数组、List[str]批量 wav 路径由load_data统一经librosa.load(path, sr前端采样率)重采样OutputList每个元素为一个 dict。基础 Paraformer 无时间戳输出时每项形如{preds: 识别文本}若模型输出包含 LFR 预测峰BiCifParaformer 结构源码注释# for BiCifParaformer Inference则每项额外携带timestamp与raw_tokens字段。源码中对应的分支逻辑paraformer_bin.py#L107-L142if len(outputs) 4: # for BiCifParaformer Inference us_alphas, us_peaks outputs[2], outputs[3] else: us_alphas, us_peaks None, None当us_peaks非空时time_stamp_lfr6_onnxutils/timestamp_utils.py把声学 token 的预测峰对齐为字符级时间戳同时若设置了plot_timestamp_to还会调用plot_wave_timestamp用 matplotlib 把波形与逐字时间戳渲染为timestamp.png。对静音/噪声输入推理异常会被捕获并输出空字符串结果logging.warning(input wav is silence or noise)而不会直接抛错中断批量任务。6. 推理管线源码剖析以Paraformer.__call__为主线一次批量推理的完整调用链为wav_content → load_data # librosa 重采样到前端采样率 → extract_feat # WavFrontend.fbank → lfr_cmvnLFR 帧叠加 CMVN 归一化 → pad_feats # 右侧补零至批内最大长度 → ort_infer(feats, feats_len) # torch.jit 模型前向 → decode / decode_one # argmax → 去 blank/sos/eos → ids2tokens → sentence_postprocess # 句子级拼接与后处理其中几个值得注意的实现细节特征前端WavFrontend由config.yaml的frontend_conf驱动extract_feat先做 kaldi fbank再做lfr_cmvn低帧率 LFR 帧叠加 CMVN最终特征张量为torch.float32、长度为torch.int32这是 Paraformer 低帧率设计的落地环节源码见 paraformer_bin.py#L188-L200。CPU/GPU 切换device_id -1时直接在 CPU 上调用self.ort_infer(feats, feats_len)否则feats.cuda()推理后再.cpu()取回输出为(am_scores, valid_token_lens)。解码规则decode_one对am_scores逐帧argmax得到 token 序列包裹sos1 / eos2后构造Hypothesis过滤 blank(0) 与 eos再经TokenIDConverter.ids2tokens还原字符最后按valid_token_num - pred_bias截断——pred_bias取自config.yaml的model_conf.predictor_bias时间戳模型的预测偏置这保证了带时间戳模型与普通模型共用同一套解码路径。批处理外层按batch_size分块循环pad_feats统一右补零长音频批量推理时可控显存/内存峰值。7. 热词增强ContextualParaformer 与 SeacoParaformer仓库通过继承体系提供热词能力ContextualParaformer(Paraformer)与SeacoParaformer(ContextualParaformer)paraformer_bin.py#L246、paraformer_bin.py#L429后者与 Contextual 的调用方式相同。demo_contextual_paraformer.py 与 demo_seaco_paraformer.py 的用法完全一致import torch from funasr_torch.paraformer_bin import ContextualParaformer model_dir iic/speech_paraformer-large-contextual_asr_nat-zh-cn-16k-common-vocab8404 device_id 0 if torch.cuda.is_available() else -1 model ContextualParaformer(model_dir, batch_size1, device_iddevice_id) wav_path {}/.cache/modelscope/hub/{}/example/asr_example.wav.format(Path.home(), model_dir) hotwords 你的热词 魔搭 # 空格分隔的热词列表 result model(wav_path, hotwords) print(result)其双塔热词机制在源码中的工作流程paraformer_bin.py#L326-L397proc_hotword空格切分热词 → 逐字查词表OOV 字符替换为8403unk并打 warning →pad_list补零至max_len10eb_infer热词 id 序列送入model_eb.torchscriptembedding-bi 编码器得到偏置嵌入并在每个热词的有效长度处取向量bb_inferfeats, feats_len, bias_embed三输入送入model_bb.torchscriptencoder-bi输出仍为(am_scores, valid_token_lens)后续解码与基础 Paraformer 相同。8. SenseVoiceSmall 多语言推理SenseVoiceSmall的构造参数sensevoice_bin.py#L32-L41SenseVoiceSmall( model_dir, # 本地路径或 ModelScope 模型名 batch_size1, plot_timestamp_to, quantizeFalse, intra_op_num_threads4, # 推理线程数 cache_dirNone, devicecpu, # 通过 **kwargs 传入如 cuda:0 )仓库 demo demo_sensevoice_small.pyfrom pathlib import Path from funasr_torch import SenseVoiceSmall from funasr_torch.utils.postprocess_utils import rich_transcription_postprocess model_dir iic/SenseVoiceSmall model SenseVoiceSmall(model_dir, devicecuda:0) wav_or_scp [{}/.cache/modelscope/hub/{}/example/en.mp3.format(Path.home(), model_dir)] res model(wav_or_scp, languageauto, use_itnTrue) print([rich_transcription_postprocess(i) for i in res])两个关键调用参数在源码中有明确映射sensevoice_bin.py#L86-L89languagelid_dict {auto: 0, zh: 3, en: 4, yue: 7, ja: 11, ko: 12, nospeech: 13}即支持自动检测或指定中/英/粤/日/韩language也支持传入文本文件路径逐行读取以适配批量不同语言的文件use_itn映射到文本规范化 tagwithitn(14) / woitn(15)控制是否输出逆文本正则化ITN结果输出的 token 序列经SentencepiecesTokenizer按chn_jpn_yue_eng_ko_spectok.bpe.model解码再交由rich_transcription_postprocess做富文本情感/事件标签后处理。9. 性能基准与量化加速9.1 并发压测数据完整的 libtorch 后端 CPU 基准见 runtime/docs/benchmark_libtorch.md。测试集为 Aishell1 test总时长 36108.919 秒环境为 Intel Xeon Platinum 8269CY 2.50GHz16 核-32 线程支持 avx512_vnniParaformer-large 模型结果并发任务数处理耗时(s)RTF加速比1 (torch fp32)35220.097610.31 (torch int8)17460.048420.732 (torch fp32)2360.0066152.732 (torch int8)1140.0032317.464 (torch fp32)2350.0065153.764 (torch int8)1130.0031319.2数据表明两个可叠加的加速杠杆int8 量化让单并发 RTF 从 0.0976 降到 0.0484约 2 倍而多进程并发则进一步把系统级吞吐拉到 300 倍以上的加速比。9.2 基准复现方法该文档给出的复现脚本位于 runtime/python/utils/流程为pip install -U modelscope funasr # 安装压测依赖 git clone https://gitcode.com/GitHub_Trending/fun/FunASR.git cd FunASR cd runtime/python/utils pip install -r requirements.txt # RTF 压测先设置 model、数据路径与输出目录 nohup bash test_rtf.sh log.txt # CER 评测 nohup bash test_cer.sh log.txt 9.3 量化模型的使用方式导出的量化文件在funasr_torch中的启用方式非常直接——构造时加一个参数model Paraformer(model_dir, batch_size1, quantizeTrue) # 加载 model_quant.torchscript model ContextualParaformer(model_dir, batch_size1, quantizeTrue) # 加载 model_bb_quant / model_eb_quant model SenseVoiceSmall(model_dir, quantizeTrue) # 加载 model_quant.torchscript量化导出阶段需要的calib_num默认 100 条校准样本与fallback_num参数见 funasr/bin/export.py#L40-L47。10. 总结与适用前提funasr_torchlibtorch 后端提供了 FunASR 离线 ASR 模型部署的一条轻量路径其适用前提与限制总结如下离线场景该包面向 Paraformer / ContextualParaformer / SeacoParaformer / SenseVoiceSmall 等离线模型输入为整段音频文件路径或波形数组不支持流式增量推理流式部署请见 runtime/python/onnxruntime/ 与 websocket/gRPC 等服务端方案文件自足只需model.torchscript或量化版、config.yaml、am.mvn、词表文件模型缺失 TorchScript 时会自动调用AutoModel.export补齐但自动导出依赖已安装funasr与modelscope量化收益显著在 avx512_vnni 服务器上int8 量化 多并发可将 Paraformer-large 的系统级加速比做到 300 倍以上runtime/docs/benchmark_libtorch.mdCPU 优先基准与 README 中的 Speed 数据均为 CPU 环境Xeon 8163/8269CYGPU 使用通过device_id/device参数开启但仓库未提供 GPU 侧的量化性能数据实际收益需自行压测验证。完整文档与 demo 均可在 runtime/python/libtorch/ 目录下继续深入配合 runtime/quick_start.md 中的运行时总览可以覆盖从单机离线部署到服务端化部署的完整选择面。【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考