FunASR Python WebSocket 客户端详解：基于 funasr_api 对接 2pass 语音识别服务

FunASR Python WebSocket 客户端详解基于 funasr_api 对接 2pass 语音识别服务【免费下载链接】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/funasr_api 模块系统讲解如何用 Python 通过 WebSocket 对接 FunASR 的 2pass 语音识别服务端。读完本文你可以直接复现离线文件转写rec_file / rec_buf与流式实时识别create_stream / feed_chunk / wait_for_end两套调用方式并理解客户端与 2pass 服务端之间的初始化握手、2pass 模式参数chunk_size、chunk_interval 等以及音频分片、ffmpeg 转码等底层实现细节。一、模块定位与适用前提FunASR 的 runtime/funasr_api 是一套面向 Python 的轻量识别器封装库用于访问 FunASR 的 WebSocket 推理服务。根据 README 的说明该客户端目前仅支持 2pass server即同时具备流式识别 离线模型句子修正的混合推理模式这一点在源码中也能得到印证funasr_core.py 在建立连接后发送的初始化消息固定使用mode: 2pass并不会切换为offline或online模式。因此使用本模块的典型前提是服务端已通过 runtime/run_server_2pass.sh 之类的脚本启动funasr-wss-server-2pass进程该脚本默认加载 Paraformer 离线/在线模型、FSMN VAD、标点模型等并监听 10095/10096 端口配置 TLS 证书客户端机器上安装了websocket-client与ffmpeg前者建立 WebSocket 连接后者负责把 mp3 等非 PCM/WAV 格式统一转成 16k 单声道 WAV。整个模块由四个文件协作完成职责划分清晰文件核心类职责funasr_api.pyFunasrApi对外门面Facade提供rec_file/rec_buf/create_streamfunasr_core.pyFunasrCore管理 WebSocket 连接、发送 2pass 初始化消息、后台线程收消息、音频分片发送funasr_stream.pyFunasrStream流式会话对象封装feed_chunk与wait_for_endfunasr_tools.pyFunasrToolsffmpeg 检测与audio2wav转码工具官方示例见 example.py目录中同时附带了asr_example.mp3、asr_example.wav两个测试音频。二、安装依赖按 README 的 Install 章节安装分两步pip install websocket-client apt install ffmpeg -y其中websocket-client提供create_connection/ABNF等 API见 funasr_core.py 顶部的from websocket import ...导入ffmpeg则被 funasr_tools.py 的audio2wav通过子进程调用ffmpeg -i - -ac 1 -ar 16000 -f wav pipe:1即把任意可解码的音频字节流转成16kHz、单声道-ac 1、16bit的 WAV 流——这正是 FunASR 2pass 服务端要求的音频规格。FunasrTools的构造函数还会先执行check_ffmpeg()运行ffmpeg -version若本机没有 ffmpeg 会直接提示安装并退出所以即使只走 WAV/PCM 路径保留 ffmpeg 也是模块能正常初始化的一部分。三、创建识别器FunasrApi 构造函数参数创建一个识别器实例只需要指定服务端地址from funasr_api import FunasrApi rcg FunasrApi( uriwss://www.funasr.com:10096/ )从 funasr_api.py 的签名看构造函数共接受三个参数参数默认值含义uriwss://www.funasr.com:10096/WebSocket 服务地址支持wss://TLS与ws://明文两种协议timeout1000等待识别结果的超时时间秒级语义离线识别时若音频时长更长会自动顺延msg_callbackNone收到服务端消息时的回调函数用于流式场景接收中间结果值得注意的是FunasrCore.__init__中对协议的判断逻辑funasr_core.pywss://地址会构造一个check_hostnameFalse、CERT_NONE的 SSLContext也就是说该客户端为了快速对接自签名证书的服务端如 runtime/ssl_key 中生成的证书而放宽了证书校验。对接ws://明文服务例如本地run_server_2pass.sh未启用证书时的 10095 端口则不需要任何 TLS 上下文。每次调用new_core()都会先关闭旧的funasr_core再新建一条 WebSocket 连接因此一个FunasrApi实例可以串行发起多次识别但不宜在同一条连接上并行处理多个识别任务。四、离线文件识别rec_file 与 rec_buf4.1 两种调用形态README 给出的识别示例对应 example.pyrcg FunasrApi(uriwss://www.funasr.com:10096/) # 方式一直接传文件路径支持 ffmpeg 可解码的多种格式mp3/wav/m4a 等 text rcg.rec_file(asr_example.mp3) print(recognizer by filepath result, text) # 方式二传音频字节 buffer with open(asr_example.wav, rb) as f: audio_bytes f.read() text rcg.rec_buf(audio_bytes) # 非 PCM/WAV 时设置 ffmpeg_decodeTrue print(recognizer by buffer result, text)两者的参数语义来自 funasr_api.pyrec_file(file_path)按文件扩展名自动判断是否需要转码——扩展名为PCM或WAV时直接发送原始字节其他格式一律先经FunasrTools.audio2wav转码funasr_core.py。若 ffmpeg 无法解码会打印错误并终止。rec_buf(audio_buf, ffmpeg_decodeFalse)ffmpeg_decode默认False即默认把传入的 buffer 当作 16k PCM/WAV 直接发送如果 buffer 是 mp3 等非 PCM 格式必须设置ffmpeg_decodeTrue否则服务端将收到无法解析的数据。4.2 底层流程分片发送、结束标记与超时无论文件还是 buffer最终都汇入 FunasrCore.rec_buf。它把音频按固定步长切片发送stride int(60 * 10 / 10 / 1000 * 16000 * 2) # 1920 字节 60ms 的 16k/16bit 单声道 chunk_num (len(audio_bytes) - 1) // stride 1 for i in range(chunk_num): beg i * stride data audio_bytes[beg : beg stride] self.feed_chunk(data) # websocket.send(data, ABNF.OPCODE_BINARY)即每次发送 60ms 的二进制音频块与 2pass 服务端的chunk_interval对齐。发送完毕后get_result()会做三件事funasr_core.py发送 JSON 结束标记{is_speaking: False}通知服务端音频结束、触发离线修正与收尾调用wait_for_result()轮询等待is_finalTrue超时时间会按音频时长自动放大file_dur 字节数/16000/2*100超过timeout时取音频时长关闭连接并只累积mode 2pass-offline消息的text作为最终返回值funasr_core.py——也就是说离线接口拿到的直接是离线模型修正后的最终文本而不含流式中间结果。4.3 与服务端协议的一致性上述 JSON 消息与 runtime/docs/websocket_protocol.md 中 Real-time Speech Recognition 一节完全对应初始化消息带mode/wav_name/chunk_size/is_speaking/hotwords/itn等字段服务端返回2pass-online流式中间结果与2pass-offline修正后结果两类消息最终标记均为{is_speaking: False}。chunk_size如[5,10,5]表示音频切分长度与前后看look-ahead/look-back毫秒数直接决定流式时延配置。五、流式识别create_stream 与消息回调实时场景下客户端边收音频边获取中间结果。README 中的流式示例对应 example.py完整流程如下rcg FunasrApi(uriwss://www.funasr.com:10096/) # 定义消息回调每个服务端消息含 2pass-online 中间结果都会触发 def on_msg(msg): print(stream msg, msg) stream rcg.create_stream(msg_callbackon_msg) with open(asr_example.wav, rb) as f: audio_bytes f.read() # 非 PCM/WAV 格式可用 FunasrTools.audio2wav 先转码 # from funasr_tools import FunasrTools # audio_bytes FunasrTools.audio2wav(audio_bytes) stride int(60 * 10 / 10 / 1000 * 16000 * 2) # 60ms 一块 chunk_num (len(audio_bytes) - 1) // stride 1 for i in range(chunk_num): beg i * stride stream.feed_chunk(audio_bytes[beg : beg stride]) final_result stream.wait_for_end() print(asr_example.wav stream_result, final_result)几个关键点create_stream(msg_callback...)从 funasr_api.py 看它会新建一条 WebSocket 连接并返回FunasrStream对象msg_callback会在 FunasrCore.thread_rec_msg 这个后台接收线程中被逐条调用回调参数是服务端反序列化后的 JSON dict典型字段包括mode2pass-online/2pass-offline、text、is_final、wav_name等。因此实时 UI 通常在这个回调里刷新中间文本。feed_chunk(chunk)透传给 FunasrCore.feed_chunk以ABNF.OPCODE_BINARY二进制帧发送每次建议 60ms1920 字节的 16k/16bit 单声道 PCM。wait_for_end()发送{is_speaking: False}结束标记等待is_final后关闭连接返回最终修正文本funasr_stream.py。与离线接口不同它不会在超时未满足时阻塞file_dur0时按流式语义处理见wait_for_result中的file_dur0分支。连接生命周期FunasrCore.close()负责置结束态并关闭 socket若在同一次识别中创建新的 stream旧的 core 会先被close()再重建funasr_api.py。六、2pass 初始化消息与关键参数FunasrApi的所有识别都跑在 2pass 模式下服务端会话参数在 new_connection 中一次性下发message json.dumps({ mode: 2pass, chunk_size: [int(x) for x in 0,10,5.split(,)], # [0,10,5] encoder_chunk_look_back: 4, decoder_chunk_look_back: 1, chunk_interval: 10, wav_name: funasr_api, is_speaking: True, }) self.websocket.send(message)结合 websocket_protocol.md 的参数表可以逐项解读mode: 2pass实时识别 句子结束时的离线模型修正正是本客户端支持的唯一模式chunk_size: [0,10,5]流式模型的时延配置三元组分别表示切分块、look-ahead、look-back 的毫秒数协议文档示例[5,10,5]对应 600ms 音频块、300ms 前后看chunk_interval: 10音频按 10ms 粒度组织与客户端 60ms6×10ms分片发送保持兼容encoder_chunk_look_back / decoder_chunk_look_backencoder/decoder 侧的历史块回看数量控制流式推理的上下文长度与精度的平衡is_speaking: True声明会话开始处于正在说话状态识别结束前需再发送is_speaking: False。服务端如何消费这些参数可参考 runtime/run_server_2pass.shfunasr-wss-server-2pass进程同时加载 Paraformer 离线模型speech_paraformer-large-vad-punc_asr_nat-zh-cn-16k-common-vocab8404-onnx与在线流式模型...-online-onnx再加 FSMN VAD、标点 CT-Transformer、ITNfst_itn_zh与 ngram 语言模型并支持--hotword热词文件。客户端chunk_size等参数则决定了每个会话的流式切分行为。七、实践要点与常见排查点音频规格服务端按 16kHz、16bit、单声道 PCM 解析音频字节。mp3/wma/m4a 等格式请走rec_file自动转码或rec_buf(buf, ffmpeg_decodeTrue)显式转码并确认本机已安装 ffmpegFunasrTools初始化时会自检。结果语义rec_file/rec_buf/wait_for_end返回的都是2pass-offline修正后的最终文本若需要中间结果必须通过msg_callback接收2pass-online消息。超时离线识别默认timeout1000秒音频时长更长时会自动放大为音频时长长文件请保证服务端处理速度否则可能提前返回不完整结果源码中超时会打印time out!。地址与证书wss://客户端不校验主机名与证书适合对接自签名证书部署本地部署可用ws://明文地址免去证书配置。错误处理风格该库属于轻量工具型封装异常主要打印后以None/空字符串返回如rec_file失败返回None生产代码建议对返回文本做判空处理。八、小结runtime/funasr_api用不到四个 Python 文件就把 FunASR 2pass 服务的客户端调用收敛为三个动词rec_file文件离线转写、rec_buf字节离线转写、create_stream流式实时转写。它的价值在于把 2pass WebSocket 协议中最容易踩坑的部分——TLS 连接建立、初始化 JSON 握手、60ms 二进制分片、is_speaking结束标记、离线修正文本的过滤与超时等待——全部封装在FunasrApi/FunasrCore/FunasrStream/FunasrTools四类之中。配合 example.py 的现成示例、websocket_protocol.md 的完整协议说明以及 run_server_2pass.sh 的服务端启动脚本开发者可以快速在业务系统中集成低时延出中间结果 句子级离线修正的中文语音识别链路。【免费下载链接】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），仅供参考