1. 项目概述为什么要在本地跑一套语音识别模型如果你接触过语音识别应该对云服务不陌生上传音频等接口返回文字按调用量付费。这套流程在Demo阶段很省事但一旦进入量产环境问题就来了——数据隐私、网络延迟、并发成本、接口限流每一个都够让人头疼。所以我一直倾向于在本地部署一套开源模型把语音转写这件事真正握在自己手里。FunASR是阿里达摩院开源的一套语音识别工具链底层集成了包括Paraformer在内的一系列生产级模型。Paraformer这个模型很特别它是非自回归架构跟传统的CTC或者Attention-based自回归模型走的不是一条路。简单理解传统模型一个字一个字往外蹦Paraformer是一次性把整句话的框架推出来再做精修对齐。这就让它在推理速度上有着天然优势同时字错误率还能保持在一个相当能打的水平。这篇文章写的是我在本地从零部署Paraformer的全过程包含环境配置、模型下载、离线推理、API服务启动以及我在实际使用中踩过的坑和解决办法。适合有一台GPU机器NVIDIA显卡哪怕是6G显存的入门卡也够跑、想摆脱云服务依赖的开发者或者需要在内部系统里做语音转写功能的团队参考。只要网络状况正常整个流程确实可以控制在5到10分钟以内前提是别在环境依赖上卡太久。2. FunASR与Paraformer的核心思路解析2.1 Paraformer到底解决了什么问题先花点时间讲明白Paraformer的原理价值这样你在选型的时候心里更有底。传统语音识别模型大多走自回归路线也就是说模型在预测当前字的时候要依赖前面已经生成的所有字。这种方式的优点是准确率高但缺点是慢——推理延迟随句子长度线性增长GPU利用率也上不去。对于一些对实时性要求不高的离线场景还好一旦到了大批量音频转写、会议记录、客服质检这种场景你会明显感觉到算力全耗在“等待上一个字算完”上了。Paraformer的思路是既然语音特征里其实已经包含了足够多的信息那模型能不能一次性预测出整句话的字序列然后再用一个精修器去校对和补全这就是非自回归Non-AutoregressiveNAR架构的核心。Paraformer在编码器提取完语音特征之后通过一个GLMGlobal Language Model模块做一轮全局预测然后再用一个基于注意力机制的精修器逐字校准。这样既保留了精度又把推理并行度拉满了。实际使用中Paraformer的推理速度大约能达到实时率的10倍以上视GPU型号而定。什么意思就是说一分钟的音频它大约两三秒就能转完。这个速度在离线批量处理场景里体验极佳我拿它处理过上千条客服录音一共也就几分钟跑完比起以前用云端接口一条条传整个流程舒服太多。而且Paraformer的开源版本还支持时间戳、标点预测、说话人分离等一系列工程级功能不是那种实验室玩具。2.2 FunASR在整个链路里承担什么角色有个常见的误区很多人以为FunASR就是模型本身。实际上FunASR是一套完整的语音识别工具库它负责的是“模型部署和推理”这层工程化的工作而具体的模型权重则是由ModelScope魔搭社区承载和分发的。你可以把FunASR理解成一个“模型驱动引擎”——它定义好了模型的输入输出格式封装了特征提取、推理流程、后处理逻辑你只需要指定要加载哪个模型它就能自动从ModelScope下载权重并跑起来。它还提供了丰富的工具模块语音活动检测VAD先检测出音频中有语音的片段再把片段送给识别模型既能减少无效计算也能避免静音段被强行解码出莫名其妙的文字。标点预测CT-Transformer识别出的纯文本没有标点通过这个模型自动补上标点和语气词输出结果直接可读。时间戳生成每个字或词在音频中的起止时间方便做字幕对齐或检索。说话人分离Speaker Verification在多人对话场景中区分谁在说话会议纪要场景非常有用。你既可以单独使用其中的某一项比如只做VAD切分也可以把它们串联起来搭一条完整的语音转写管线。这种“乐高积木式”的设计是FunASR最大的工程价值所在。很多公司会直接基于FunASR的API服务做二次开发比如对接工单系统、质检平台或者字幕工具。3. 部署前的环境准备与安装实战3.1 硬件与系统要求先说结论最低配置一张6GB显存的NVIDIA显卡就够了CPU推理也能跑但速度会慢不少。我的部署环境供你参考操作系统Ubuntu 20.04Windows下通过WSL2同样可跑GPUNVIDIA GeForce RTX 3060 12GBCUDA版本11.8Python版本3.10PyTorch版本2.0.1如果显存低于6G比如常见的4G显卡建议优先使用FunASR的量化版Paraformer模型int8精度模型大小会从800MB左右降到200多MB速度反而更快准确率损失控制在1%以内。这种优化细节在官方仓库里有说明实际操作时一定要看。如果你没有N卡只有纯CPU环境那也可以跑但建议放弃“实时”这个期待值。纯CPU推理我家里的老笔记本实测大约能到0.6倍实时率也就是一小时音频要将近两小时才能转完。用来偶尔处理几条音频还行批量场景就得耐心等了。3.2 安装步骤从零到可用的最快路径我推荐用conda创建独立环境这样不会把系统Python搞乱。如果你没装conda直接用Python自带的venv也可以但conda在管理CUDA相关依赖时更省心。# 创建Python 3.10环境 conda create -n funasr python3.10 conda activate funasr # 安装PyTorch这里以CUDA 11.8版本为例 pip install torch2.0.1 torchaudio2.0.2 --index-url https://download.pytorch.org/whl/cu118 # 安装FunASR pip install funasr modelscope这里有几个细节要提醒PyTorch的安装命令要和你本机的CUDA驱动匹配。如果驱动已经是CUDA 12.x装PyTorch 2.1以上版本更合适否则可能出现“CUDA driver version is insufficient”这类报错。怎么确认驱动版本在终端跑nvidia-smi看右上角版本号即可。modelscope是依赖库负责从魔搭社区拉取模型权重。首次执行时会下载几百MB到1GB不等的模型文件如果下载超时可以把MODELSCOPE_CACHE环境变量指向一个有足够磁盘空间的目录避免默认目录空间不足。安装完成后可以用funasr --version验证是否安装成功。如果提示找不到命令多半是conda环境的bin目录没进PATH直接python -m funasr --version即可。装完之后别急着关终端下一步就是验证模型能否正常加载和推理。4. 快速上手第一段音频的识别全流程4.1 模型选择与自动下载FunASR里适配Paraformer的模型有好几个版本我这里只说最常用的两个iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch中文普通话通用模型词汇表8404个token覆盖绝大多数日常对话和通用场景。iic/speech_seaco_paraformer_large_asr_nat-zh-cn-16k-common-vocab8404-pytorch加了热词增强SEACO的版本适合包含大量人名、产品名、专业术语的垂直领域。如果你处理的音频采样率是8kHz比如电话录音需要额外关注模型对采样率的要求。上述模型默认输入16kHz音频8kHz的音频需要先重采样再送进去否则识别效果会大打折扣。FunASR内部有自动重采样逻辑但建议预处理阶段就统一好格式。第一次跑推理时模型会自动从ModelScope下载权重到我本地的缓存目录。这个过程可能有点慢尤其是在网络状况一般的情况。我的建议是提前用modelscope的API手动下载省得推理时干等。from modelscope import snapshot_download model_dir snapshot_download(iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch) print(model_dir)这样执行一次之后模型文件就会保存在本地。后续推理时只要模型目录不变就不会再重复下载。4.2 基础推理代码一行代码出结果安装好依赖、下好模型之后测试流程其实非常短。我写过的最精简的推理脚本如下from funasr import AutoModel # 加载模型 model AutoModel( modeliic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch, vad_modeliic/speech_fsmn_vad_zh-cn-16k-common-pytorch, punc_modeliic/punc_ct-transformer_zh-cn-vocab272727-pytorch, devicecuda ) # 识别单条音频 res model.generate(inputtest.wav) print(res[0][text])注意这里我把VAD模型和标点模型也一并加载了。可能有人会问为什么要集成VAD因为真实世界的音频不可能是“恰好一句话”的干净录音。录音里可能有静音、咳嗽、停顿、环境噪声这些片段直接送进识别器不仅浪费时间还容易让模型产生幻觉输出一些原文根本不存在的字词。VAD模型会把音频切成多个语音片段挨个识别后再拼接效果和速度都能兼顾。生成的res是一个列表每个元素对应一条音频或者一个语音片段的结果。每项包含text识别出的文字timestamp如果启用时间戳这里会返回每个字的起止时间speaker如果启用了说话人分离这里会返回说话人ID4.3 批量处理文件夹级别的音频转写实际操作中我们很少只处理一条音频。更需要的是这样一个场景把目录底下所有录音跑一遍输出一个汇总的文本文件。FunASR的generate接口天然支持批量处理把输入路径换成一个列表就可以import os from funasr import AutoModel model AutoModel( modeliic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch, vad_modeliic/speech_fsmn_vad_zh-cn-16k-common-pytorch, punc_modeliic/punc_ct-transformer_zh-cn-vocab272727-pytorch, devicecuda ) audio_dir ./audios audio_files [ os.path.join(audio_dir, f) for f in os.listdir(audio_dir) if f.endswith((.wav, .mp3, .m4a, .flac)) ] res model.generate(inputaudio_files, batch_size16) for path, r in zip(audio_files, res): text r[text] print(f{path}: {text}) # 同时保存到文件 with open(path .txt, w, encodingutf-8) as f: f.write(text)batch_size这个参数学问很大。它是控制一次同时送几张图这里是几段语音给GPU推理的。调大可以提升GPU利用率但显存不够时容易OOM。以6G显存为例batch_size设置在8到16之间比较稳妥12G显存可以尝试32。值得一提的是generate不仅支持本地音频文件路径还支持URL。也就是说你可以直接传一个https://.../audio.wav的链接FunASR会自动下载后转写。不过我对这个用法持保留态度网络不稳定的情况下还不如先下载到本地再处理。5. 进阶实操直接起一套语音识别API服务5.1 为什么要用API服务的方式很多人会问我代码里直接调generate不就行了为什么要搞一个API服务那是因为在真实项目中语音识别能力要开放给多个业务方使用——比如前端网页要实时转写移动端App要传音频后端服务要做回调。如果每个人都在自己的代码里加载一遍模型一来内存爆炸二来模型反复加载浪费时间。正确的做法是把模型部署成一个常驻内存的服务所有业务方通过HTTP接口或WebSocket接口来调用。FunASR官方就提供了一个开箱即用的服务端你甚至不需要写任何后端代码。我实际用下来一条命令起服务前端直接调接口体验很顺。5.2 快速启动官方API服务FunASR的官方服务由funasr[runtime]这个扩展包提供安装方式和启动命令如下pip install funasr[runtime] # 启动服务指定模型和端口 funasr-service \ --host 0.0.0.0 \ --port 10095 \ --model iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch \ --vad_model iic/speech_fsmn_vad_zh-cn-16k-common-pytorch \ --punc_model iic/punc_ct-transformer_zh-cn-vocab272727-pytorch启动后终端会提示server started然后就可以通过HTTP请求测试了。最原始的方式是用curl直接上传音频文件curl -X POST http://localhost:10095/recognition \ -H Content-Type: application/json \ -d {audio_url: https://example.com/audio.wav}服务端会返回类似这样的JSON响应{ code: 0, data: { text: 今天天气真不错我们去公园散步吧。, timestamp: [[0, 320], [320, 760]] } }这种模式对于后端开发人员来说非常友好不用关心FunASR的Python接口长什么样拿到text字段直接用就行。我实际测试过这个服务在GPU环境下并发能力相当可观。哪怕同时提交几十个音频转写任务它内部有队列机制一个个按顺序处理不会出现崩溃现象。唯一的建议是如果业务方需要大量并发最好在前面加一层消息队列做削峰填谷避免瞬时请求过多导致响应超时。5.3 流式识别实现实时转写离线转写适合处理已录好的音频但如果你要做实时字幕、实时会议记录那就需要流式识别。FunASR也提供了对应的流式模型和接口协议走的是WebSocket。funasr-service \ --host 0.0.0.0 \ --port 10096 \ --model iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch \ --vad_model iic/speech_fsmn_vad_zh-cn-16k-common-pytorch \ --punc_model iic/punc_ct-transformer_zh-cn-vocab272727-pytorch \ --mode online前端或者客户端程序通过WebSocket连接持续发送音频二进制帧服务端会实时返回已识别的文本片段。我做了几个Demo延迟大概在300到500毫秒之间听感上几乎感受不到延迟拿来做个实时字幕是完全够用的。不过要提醒的是流式识别对音频格式要求更为严格通常需要使用16kHz、16bit、单声道的PCM裸流数据。如果前端采集到的是44.1kHz或者48kHz采样率一定要先做重采样再推流否则识别效果惨不忍睹。6. 常见的坑与排查技巧实录6.1 模型下载慢或超时这个是新手最容易卡住的地方。ModelScope默认是从国内CDN下载的大多数情况下速度尚可但也有特殊情况——比如公司网络策略限制、DNS解析异常会出现长时间卡在下载界面的情况。解决办法用modelscope的snapshot_download函数提前下载并且开启断点续传模式。from modelscope import snapshot_download model_dir snapshot_download( iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch, cache_dir/data/models ) print(model_dir)下载完成后把cache_dir保存的路径记下来在使用AutoModel加载时手动指定model为该路径而非模型ID就能跳过下载环节直接加载本地模型。6.2 CUDA out of memory报错信息通常是CUDA out of memory. Tried to allocate 256.00 MiB (GPU 0; 6.00 GiB total capacity; 5.80 GiB already allocated; ...)这个报错在两种场景下非常常见第一种是同时加载了VAD、标点、识别多个模型显存被多个模型瓜分第二种是batch_size设置得太大导致一个批次塞不进显存。解决办法也很简单如果只是做轻量使用可以去掉VAD和标点模型只保留Paraformer主模型。降低batch_size从16降到8、4甚至1找到显存能承受的临界值。启用fp16半精度推理。FunASR的AutoModel加载时支持dtypefp16参数显存占用大约减半速度还能更快。model AutoModel( modeliic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch, dtypefp16, devicecuda )6.3 识别结果出现大量重复或空文本这个坑我踩过几次后来才发现问题出在音频格式上。Paraformer的中文模型要求输入必须是16kHz采样率如果音频是8kHz的电话录音或者44.1kHz的CD音质模型会表现异常输出可能是一堆重复的字或者是空文本。解决思路是在送入模型之前做重采样。命令行可以用ffmpeg快速完成ffmpeg -i input.mp3 -ar 16000 -ac 1 -f wav output_16k.wav如果不想依赖外部工具也可以用Python的librosa库重采样。但一定要注意librosa默认会转成浮点数组写回WAV时要转成16bit整型否则识别结果可能包含大量乱码。6.4 标点模型输出异常符号如果你发现识别结果带上了奇怪的标点比如“”或者“”大概率是输入文本中含有模型不认识的特殊符号比如URL地址、邮件地址、乱码字符。预处理阶段最好把这些内容剔除或者做正则替换后再送去识别。还有一个情况是标点模型本身对口语文本更友好如果输入的是书面化程度很高的文本它反而可能过度添加标点。这种情况不影响主线功能如果追求完美可以对标点模型单独做微调Fair enough。6.5 GPU完全没被利用启动推理时发现GPU利用率始终是0%只有CPU在跑。这个问题的根源基本都在PyTorch版本和CUDA不匹配上。最常见的情况是你安装PyTorch时默认装了CPU版本比如用pip install torch没有指定--index-url结果PyTorch只识别CPU完全用不了显卡。这时候执行以下代码验证import torch print(torch.cuda.is_available()) # 应该是 True print(torch.cuda.get_device_name(0)) # 应该显示你的显卡型号如果输出False说明PyTorch装的是CPU版本需要卸载后重装CUDA对应版本。安装命令我上面已经给过不再赘述。6.6 长音频处理超时或中断处理一小时以上的长音频时服务端偶尔会报连接超时或者进程退出。这个不能完全怪程序长音频文件读入内存后特征矩阵会非常庞大稍微不注意就会内存溢出。我的做法是在进入FunASR之前先用ffmpeg把长音频切成30到60秒的片段分别识别最后再合并结果。这样既降低了内存压力也方便在某个片段出错时单独重试不用整段重新跑。如果原音频有字幕对齐需求记得在切分时保留时间偏移信息。7. 部署完成后的进一步优化建议7.1 用int8量化换取更低显存占用如果你要在低配机器上常驻模型服务强烈建议尝试官方的int8量化模型。量化后的Paraformer模型体积缩小为原来的四分之一左右推理速度还会更快就是准确率略微下降一点。实测在普通话标准口音场景下字错误率从4%左右升到5%左右对于会议记录、字幕生成这类应用场景完全是可以接受的。7.2 使用模型缓存避免多服务重复加载如果你在同一台机器上同时部署了离线识别和流式识别两个服务它们会各自加载一遍同样的模型显存和内存开销都翻倍。合理做法是共享模型缓存路径让操作系统层面通过文件系统缓存复用底层数据虽不能完全避免模型重复加载到显存但至少能减少磁盘I/O和加载时间。7.3 中文方言和英文混合场景Paraformer毕竟以普通话为主偶尔遇到方言或中英混合的句子识别效果会有波动。FunASR社区也提供了英文模型和方言模型如果业务场景有这些需求可以按需切换模型。同一套代码换一个model参数即可这是FunASR让我觉得特别舒服的地方——模型即插即用工程代码几乎零改动。8. 写在最后的一点个人体会我前前后后在不同机器上部署过不下十次FunASR。从第一次被各种环境依赖搞得晕头转向到现在加一条命令就能起服务中间确实踩了够多的坑。但回过头看这套工具链的工程完成度在同级开源项目里已经算相当高了。如果你问我有什么最重要的建议我会说部署前先把模型离线下载好。这一个小动作能避免后面百分之八十的玄学问题。剩下百分之二十大多集中在PyTorch和CUDA版本不匹配上对照我这篇文章里给的方法一步步排查就行。最后再分享一个小技巧在服务器上用官方API服务时建议加一个--certificate配置启用HTTPS或者在前端加一层Nginx做反向代理和鉴权。RSA密钥和令牌验证其实很简单但能让你的语音服务不被随便白嫖。毕竟GPU服务器跑起来也是真金白银的电费防护还是要做足的。好了这次的部署过程就分享到这里。如果你也在自己的机器上跑通了Paraformer或者遇到什么我这篇没提到的怪问题欢迎交流。语音识别这个领域有意思的地方在于模型只是起点真正考验功力的往往是把模型跑到极致性能——祝顺利。
1. 项目概述为什么要在本地跑一套语音识别模型如果你接触过语音识别应该对云服务不陌生上传音频等接口返回文字按调用量付费。这套流程在Demo阶段很省事但一旦进入量产环境问题就来了——数据隐私、网络延迟、并发成本、接口限流每一个都够让人头疼。所以我一直倾向于在本地部署一套开源模型把语音转写这件事真正握在自己手里。FunASR是阿里达摩院开源的一套语音识别工具链底层集成了包括Paraformer在内的一系列生产级模型。Paraformer这个模型很特别它是非自回归架构跟传统的CTC或者Attention-based自回归模型走的不是一条路。简单理解传统模型一个字一个字往外蹦Paraformer是一次性把整句话的框架推出来再做精修对齐。这就让它在推理速度上有着天然优势同时字错误率还能保持在一个相当能打的水平。这篇文章写的是我在本地从零部署Paraformer的全过程包含环境配置、模型下载、离线推理、API服务启动以及我在实际使用中踩过的坑和解决办法。适合有一台GPU机器NVIDIA显卡哪怕是6G显存的入门卡也够跑、想摆脱云服务依赖的开发者或者需要在内部系统里做语音转写功能的团队参考。只要网络状况正常整个流程确实可以控制在5到10分钟以内前提是别在环境依赖上卡太久。2. FunASR与Paraformer的核心思路解析2.1 Paraformer到底解决了什么问题先花点时间讲明白Paraformer的原理价值这样你在选型的时候心里更有底。传统语音识别模型大多走自回归路线也就是说模型在预测当前字的时候要依赖前面已经生成的所有字。这种方式的优点是准确率高但缺点是慢——推理延迟随句子长度线性增长GPU利用率也上不去。对于一些对实时性要求不高的离线场景还好一旦到了大批量音频转写、会议记录、客服质检这种场景你会明显感觉到算力全耗在“等待上一个字算完”上了。Paraformer的思路是既然语音特征里其实已经包含了足够多的信息那模型能不能一次性预测出整句话的字序列然后再用一个精修器去校对和补全这就是非自回归Non-AutoregressiveNAR架构的核心。Paraformer在编码器提取完语音特征之后通过一个GLMGlobal Language Model模块做一轮全局预测然后再用一个基于注意力机制的精修器逐字校准。这样既保留了精度又把推理并行度拉满了。实际使用中Paraformer的推理速度大约能达到实时率的10倍以上视GPU型号而定。什么意思就是说一分钟的音频它大约两三秒就能转完。这个速度在离线批量处理场景里体验极佳我拿它处理过上千条客服录音一共也就几分钟跑完比起以前用云端接口一条条传整个流程舒服太多。而且Paraformer的开源版本还支持时间戳、标点预测、说话人分离等一系列工程级功能不是那种实验室玩具。2.2 FunASR在整个链路里承担什么角色有个常见的误区很多人以为FunASR就是模型本身。实际上FunASR是一套完整的语音识别工具库它负责的是“模型部署和推理”这层工程化的工作而具体的模型权重则是由ModelScope魔搭社区承载和分发的。你可以把FunASR理解成一个“模型驱动引擎”——它定义好了模型的输入输出格式封装了特征提取、推理流程、后处理逻辑你只需要指定要加载哪个模型它就能自动从ModelScope下载权重并跑起来。它还提供了丰富的工具模块语音活动检测VAD先检测出音频中有语音的片段再把片段送给识别模型既能减少无效计算也能避免静音段被强行解码出莫名其妙的文字。标点预测CT-Transformer识别出的纯文本没有标点通过这个模型自动补上标点和语气词输出结果直接可读。时间戳生成每个字或词在音频中的起止时间方便做字幕对齐或检索。说话人分离Speaker Verification在多人对话场景中区分谁在说话会议纪要场景非常有用。你既可以单独使用其中的某一项比如只做VAD切分也可以把它们串联起来搭一条完整的语音转写管线。这种“乐高积木式”的设计是FunASR最大的工程价值所在。很多公司会直接基于FunASR的API服务做二次开发比如对接工单系统、质检平台或者字幕工具。3. 部署前的环境准备与安装实战3.1 硬件与系统要求先说结论最低配置一张6GB显存的NVIDIA显卡就够了CPU推理也能跑但速度会慢不少。我的部署环境供你参考操作系统Ubuntu 20.04Windows下通过WSL2同样可跑GPUNVIDIA GeForce RTX 3060 12GBCUDA版本11.8Python版本3.10PyTorch版本2.0.1如果显存低于6G比如常见的4G显卡建议优先使用FunASR的量化版Paraformer模型int8精度模型大小会从800MB左右降到200多MB速度反而更快准确率损失控制在1%以内。这种优化细节在官方仓库里有说明实际操作时一定要看。如果你没有N卡只有纯CPU环境那也可以跑但建议放弃“实时”这个期待值。纯CPU推理我家里的老笔记本实测大约能到0.6倍实时率也就是一小时音频要将近两小时才能转完。用来偶尔处理几条音频还行批量场景就得耐心等了。3.2 安装步骤从零到可用的最快路径我推荐用conda创建独立环境这样不会把系统Python搞乱。如果你没装conda直接用Python自带的venv也可以但conda在管理CUDA相关依赖时更省心。# 创建Python 3.10环境 conda create -n funasr python3.10 conda activate funasr # 安装PyTorch这里以CUDA 11.8版本为例 pip install torch2.0.1 torchaudio2.0.2 --index-url https://download.pytorch.org/whl/cu118 # 安装FunASR pip install funasr modelscope这里有几个细节要提醒PyTorch的安装命令要和你本机的CUDA驱动匹配。如果驱动已经是CUDA 12.x装PyTorch 2.1以上版本更合适否则可能出现“CUDA driver version is insufficient”这类报错。怎么确认驱动版本在终端跑nvidia-smi看右上角版本号即可。modelscope是依赖库负责从魔搭社区拉取模型权重。首次执行时会下载几百MB到1GB不等的模型文件如果下载超时可以把MODELSCOPE_CACHE环境变量指向一个有足够磁盘空间的目录避免默认目录空间不足。安装完成后可以用funasr --version验证是否安装成功。如果提示找不到命令多半是conda环境的bin目录没进PATH直接python -m funasr --version即可。装完之后别急着关终端下一步就是验证模型能否正常加载和推理。4. 快速上手第一段音频的识别全流程4.1 模型选择与自动下载FunASR里适配Paraformer的模型有好几个版本我这里只说最常用的两个iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch中文普通话通用模型词汇表8404个token覆盖绝大多数日常对话和通用场景。iic/speech_seaco_paraformer_large_asr_nat-zh-cn-16k-common-vocab8404-pytorch加了热词增强SEACO的版本适合包含大量人名、产品名、专业术语的垂直领域。如果你处理的音频采样率是8kHz比如电话录音需要额外关注模型对采样率的要求。上述模型默认输入16kHz音频8kHz的音频需要先重采样再送进去否则识别效果会大打折扣。FunASR内部有自动重采样逻辑但建议预处理阶段就统一好格式。第一次跑推理时模型会自动从ModelScope下载权重到我本地的缓存目录。这个过程可能有点慢尤其是在网络状况一般的情况。我的建议是提前用modelscope的API手动下载省得推理时干等。from modelscope import snapshot_download model_dir snapshot_download(iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch) print(model_dir)这样执行一次之后模型文件就会保存在本地。后续推理时只要模型目录不变就不会再重复下载。4.2 基础推理代码一行代码出结果安装好依赖、下好模型之后测试流程其实非常短。我写过的最精简的推理脚本如下from funasr import AutoModel # 加载模型 model AutoModel( modeliic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch, vad_modeliic/speech_fsmn_vad_zh-cn-16k-common-pytorch, punc_modeliic/punc_ct-transformer_zh-cn-vocab272727-pytorch, devicecuda ) # 识别单条音频 res model.generate(inputtest.wav) print(res[0][text])注意这里我把VAD模型和标点模型也一并加载了。可能有人会问为什么要集成VAD因为真实世界的音频不可能是“恰好一句话”的干净录音。录音里可能有静音、咳嗽、停顿、环境噪声这些片段直接送进识别器不仅浪费时间还容易让模型产生幻觉输出一些原文根本不存在的字词。VAD模型会把音频切成多个语音片段挨个识别后再拼接效果和速度都能兼顾。生成的res是一个列表每个元素对应一条音频或者一个语音片段的结果。每项包含text识别出的文字timestamp如果启用时间戳这里会返回每个字的起止时间speaker如果启用了说话人分离这里会返回说话人ID4.3 批量处理文件夹级别的音频转写实际操作中我们很少只处理一条音频。更需要的是这样一个场景把目录底下所有录音跑一遍输出一个汇总的文本文件。FunASR的generate接口天然支持批量处理把输入路径换成一个列表就可以import os from funasr import AutoModel model AutoModel( modeliic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch, vad_modeliic/speech_fsmn_vad_zh-cn-16k-common-pytorch, punc_modeliic/punc_ct-transformer_zh-cn-vocab272727-pytorch, devicecuda ) audio_dir ./audios audio_files [ os.path.join(audio_dir, f) for f in os.listdir(audio_dir) if f.endswith((.wav, .mp3, .m4a, .flac)) ] res model.generate(inputaudio_files, batch_size16) for path, r in zip(audio_files, res): text r[text] print(f{path}: {text}) # 同时保存到文件 with open(path .txt, w, encodingutf-8) as f: f.write(text)batch_size这个参数学问很大。它是控制一次同时送几张图这里是几段语音给GPU推理的。调大可以提升GPU利用率但显存不够时容易OOM。以6G显存为例batch_size设置在8到16之间比较稳妥12G显存可以尝试32。值得一提的是generate不仅支持本地音频文件路径还支持URL。也就是说你可以直接传一个https://.../audio.wav的链接FunASR会自动下载后转写。不过我对这个用法持保留态度网络不稳定的情况下还不如先下载到本地再处理。5. 进阶实操直接起一套语音识别API服务5.1 为什么要用API服务的方式很多人会问我代码里直接调generate不就行了为什么要搞一个API服务那是因为在真实项目中语音识别能力要开放给多个业务方使用——比如前端网页要实时转写移动端App要传音频后端服务要做回调。如果每个人都在自己的代码里加载一遍模型一来内存爆炸二来模型反复加载浪费时间。正确的做法是把模型部署成一个常驻内存的服务所有业务方通过HTTP接口或WebSocket接口来调用。FunASR官方就提供了一个开箱即用的服务端你甚至不需要写任何后端代码。我实际用下来一条命令起服务前端直接调接口体验很顺。5.2 快速启动官方API服务FunASR的官方服务由funasr[runtime]这个扩展包提供安装方式和启动命令如下pip install funasr[runtime] # 启动服务指定模型和端口 funasr-service \ --host 0.0.0.0 \ --port 10095 \ --model iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch \ --vad_model iic/speech_fsmn_vad_zh-cn-16k-common-pytorch \ --punc_model iic/punc_ct-transformer_zh-cn-vocab272727-pytorch启动后终端会提示server started然后就可以通过HTTP请求测试了。最原始的方式是用curl直接上传音频文件curl -X POST http://localhost:10095/recognition \ -H Content-Type: application/json \ -d {audio_url: https://example.com/audio.wav}服务端会返回类似这样的JSON响应{ code: 0, data: { text: 今天天气真不错我们去公园散步吧。, timestamp: [[0, 320], [320, 760]] } }这种模式对于后端开发人员来说非常友好不用关心FunASR的Python接口长什么样拿到text字段直接用就行。我实际测试过这个服务在GPU环境下并发能力相当可观。哪怕同时提交几十个音频转写任务它内部有队列机制一个个按顺序处理不会出现崩溃现象。唯一的建议是如果业务方需要大量并发最好在前面加一层消息队列做削峰填谷避免瞬时请求过多导致响应超时。5.3 流式识别实现实时转写离线转写适合处理已录好的音频但如果你要做实时字幕、实时会议记录那就需要流式识别。FunASR也提供了对应的流式模型和接口协议走的是WebSocket。funasr-service \ --host 0.0.0.0 \ --port 10096 \ --model iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch \ --vad_model iic/speech_fsmn_vad_zh-cn-16k-common-pytorch \ --punc_model iic/punc_ct-transformer_zh-cn-vocab272727-pytorch \ --mode online前端或者客户端程序通过WebSocket连接持续发送音频二进制帧服务端会实时返回已识别的文本片段。我做了几个Demo延迟大概在300到500毫秒之间听感上几乎感受不到延迟拿来做个实时字幕是完全够用的。不过要提醒的是流式识别对音频格式要求更为严格通常需要使用16kHz、16bit、单声道的PCM裸流数据。如果前端采集到的是44.1kHz或者48kHz采样率一定要先做重采样再推流否则识别效果惨不忍睹。6. 常见的坑与排查技巧实录6.1 模型下载慢或超时这个是新手最容易卡住的地方。ModelScope默认是从国内CDN下载的大多数情况下速度尚可但也有特殊情况——比如公司网络策略限制、DNS解析异常会出现长时间卡在下载界面的情况。解决办法用modelscope的snapshot_download函数提前下载并且开启断点续传模式。from modelscope import snapshot_download model_dir snapshot_download( iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch, cache_dir/data/models ) print(model_dir)下载完成后把cache_dir保存的路径记下来在使用AutoModel加载时手动指定model为该路径而非模型ID就能跳过下载环节直接加载本地模型。6.2 CUDA out of memory报错信息通常是CUDA out of memory. Tried to allocate 256.00 MiB (GPU 0; 6.00 GiB total capacity; 5.80 GiB already allocated; ...)这个报错在两种场景下非常常见第一种是同时加载了VAD、标点、识别多个模型显存被多个模型瓜分第二种是batch_size设置得太大导致一个批次塞不进显存。解决办法也很简单如果只是做轻量使用可以去掉VAD和标点模型只保留Paraformer主模型。降低batch_size从16降到8、4甚至1找到显存能承受的临界值。启用fp16半精度推理。FunASR的AutoModel加载时支持dtypefp16参数显存占用大约减半速度还能更快。model AutoModel( modeliic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch, dtypefp16, devicecuda )6.3 识别结果出现大量重复或空文本这个坑我踩过几次后来才发现问题出在音频格式上。Paraformer的中文模型要求输入必须是16kHz采样率如果音频是8kHz的电话录音或者44.1kHz的CD音质模型会表现异常输出可能是一堆重复的字或者是空文本。解决思路是在送入模型之前做重采样。命令行可以用ffmpeg快速完成ffmpeg -i input.mp3 -ar 16000 -ac 1 -f wav output_16k.wav如果不想依赖外部工具也可以用Python的librosa库重采样。但一定要注意librosa默认会转成浮点数组写回WAV时要转成16bit整型否则识别结果可能包含大量乱码。6.4 标点模型输出异常符号如果你发现识别结果带上了奇怪的标点比如“”或者“”大概率是输入文本中含有模型不认识的特殊符号比如URL地址、邮件地址、乱码字符。预处理阶段最好把这些内容剔除或者做正则替换后再送去识别。还有一个情况是标点模型本身对口语文本更友好如果输入的是书面化程度很高的文本它反而可能过度添加标点。这种情况不影响主线功能如果追求完美可以对标点模型单独做微调Fair enough。6.5 GPU完全没被利用启动推理时发现GPU利用率始终是0%只有CPU在跑。这个问题的根源基本都在PyTorch版本和CUDA不匹配上。最常见的情况是你安装PyTorch时默认装了CPU版本比如用pip install torch没有指定--index-url结果PyTorch只识别CPU完全用不了显卡。这时候执行以下代码验证import torch print(torch.cuda.is_available()) # 应该是 True print(torch.cuda.get_device_name(0)) # 应该显示你的显卡型号如果输出False说明PyTorch装的是CPU版本需要卸载后重装CUDA对应版本。安装命令我上面已经给过不再赘述。6.6 长音频处理超时或中断处理一小时以上的长音频时服务端偶尔会报连接超时或者进程退出。这个不能完全怪程序长音频文件读入内存后特征矩阵会非常庞大稍微不注意就会内存溢出。我的做法是在进入FunASR之前先用ffmpeg把长音频切成30到60秒的片段分别识别最后再合并结果。这样既降低了内存压力也方便在某个片段出错时单独重试不用整段重新跑。如果原音频有字幕对齐需求记得在切分时保留时间偏移信息。7. 部署完成后的进一步优化建议7.1 用int8量化换取更低显存占用如果你要在低配机器上常驻模型服务强烈建议尝试官方的int8量化模型。量化后的Paraformer模型体积缩小为原来的四分之一左右推理速度还会更快就是准确率略微下降一点。实测在普通话标准口音场景下字错误率从4%左右升到5%左右对于会议记录、字幕生成这类应用场景完全是可以接受的。7.2 使用模型缓存避免多服务重复加载如果你在同一台机器上同时部署了离线识别和流式识别两个服务它们会各自加载一遍同样的模型显存和内存开销都翻倍。合理做法是共享模型缓存路径让操作系统层面通过文件系统缓存复用底层数据虽不能完全避免模型重复加载到显存但至少能减少磁盘I/O和加载时间。7.3 中文方言和英文混合场景Paraformer毕竟以普通话为主偶尔遇到方言或中英混合的句子识别效果会有波动。FunASR社区也提供了英文模型和方言模型如果业务场景有这些需求可以按需切换模型。同一套代码换一个model参数即可这是FunASR让我觉得特别舒服的地方——模型即插即用工程代码几乎零改动。8. 写在最后的一点个人体会我前前后后在不同机器上部署过不下十次FunASR。从第一次被各种环境依赖搞得晕头转向到现在加一条命令就能起服务中间确实踩了够多的坑。但回过头看这套工具链的工程完成度在同级开源项目里已经算相当高了。如果你问我有什么最重要的建议我会说部署前先把模型离线下载好。这一个小动作能避免后面百分之八十的玄学问题。剩下百分之二十大多集中在PyTorch和CUDA版本不匹配上对照我这篇文章里给的方法一步步排查就行。最后再分享一个小技巧在服务器上用官方API服务时建议加一个--certificate配置启用HTTPS或者在前端加一层Nginx做反向代理和鉴权。RSA密钥和令牌验证其实很简单但能让你的语音服务不被随便白嫖。毕竟GPU服务器跑起来也是真金白银的电费防护还是要做足的。好了这次的部署过程就分享到这里。如果你也在自己的机器上跑通了Paraformer或者遇到什么我这篇没提到的怪问题欢迎交流。语音识别这个领域有意思的地方在于模型只是起点真正考验功力的往往是把模型跑到极致性能——祝顺利。
