sherpa-onnx Zipformer 流式识别 3 步跑通从 Required inputs missing 到实时出字【免费下载链接】sherpa-onnxSpeech-to-text, text-to-speech, speaker diarization, speech enhancement, source separation, and VAD using next-gen Kaldi with onnxruntime without Internet connection. Support embedded systems, Android, iOS, HarmonyOS, Raspberry Pi, RISC-V, RK NPU, Axera NPU, Ascend NPU, x86_64 servers, websocket server/client, support 12 programming languages项目地址: https://gitcode.com/GitHub_Trending/sh/sherpa-onnx如果你在 sherpa-onnx 里自己加载 Zipformer 的 ONNX 文件调用 ONNX Runtime 时报了一条Required inputs missing: ...先别怀疑环境——十有八九是缓存输入没喂全。Zipformer 的流式 encoder 不是一进一出的单文件模型它吃 20 多个输入、吐 20 多个输出其中一大半是跨帧的中间状态。这篇按报错场景 → 机制速览 → 3 步实操 → 排错清单的顺序讲清楚这些输入各是什么、谁负责管理它们、以及你实际上需要写多少代码。1. 先认脸三种典型报错分别指向哪一层报错/现象大概率原因去哪看Required inputs missing: cached_key, cached_val, ...直接跑 encoder.onnx但没把全部缓存张量作为输入喂进去下一节输入数量对了但形状报错shape mismatch缓存张量的维度按层数 × 7 类状态堆错了或维度值不是从模型元数据里读的下一节能跑但第二帧起结果乱、识别文本抖动把上一帧输出的缓存丢了、每帧都重新初始化为零上下文断了第 3 节前两条属于没对齐模型契约第三条属于没把状态串起来。分开排查不要混在一起调。上图是 python-api-examples/web/ 里的 Web 演示页面底层跑的正是流式 Zipformer——注意它没有任何初始化缓存的前端按钮因为状态管理完全发生在引擎内部这正是第 3 节要说的。2. 30 秒理解缓存Zipformer 的流式 encoder 到底记住了什么Zipformer 能做流式靠的是每个解码块只回看固定长度的左上下文。为了让第二块音频能接着第一块算encoder 必须把每层算到一半的中间结果存下来等下一块来了再续上。在 sherpa-onnx/csrc/online-zipformer-transducer-model.cc 的GetEncoderInitStates()里可以看到每个 encoder 层有且仅有 7 类缓存cached_len—— 当前左上下文里有多少有效帧整数cached_avg—— 层内归一化用的统计量cached_key/cached_val/cached_val2—— 非因果 attention 存下的 key、valuecached_conv1/cached_conv2—— 时间卷积模块滚出去的部分假设有 N 层那么 encoder 的缓存输入就是N × 7 个张量加上音频特征x一共 N × 7 1 个输入——这就是Required inputs missing名单那么长的原因。各张量维度不需要你背源码里全部是从 ONNX 文件头部的自定义元数据读出来的encoder_dims、attention_dims、num_encoder_layers、cnn_module_kernels、left_context_len。所以排错时有一条捷径开--debug让 sherpa-onnx 把元数据打印出来对照着看哪个输入对不上比手动onnx.checker快得多。3. 实操 3 步用官方 API 把缓存管理整段外包好消息是99% 的场景你不需要手写上面这些张量。C 核心层sherpa-onnx/csrc/已经把建零值缓存 → 每帧喂入 → 回收输出缓存封装在OnlineRecognizer里Python/其他语言的 API 只是薄薄一层封装。以 Python 为例第 1 步拿到四件套。流式 Zipformer 模型是一个 encoder 一个 decoder 一个 joiner tokens下载解压后的目录里长这样encoder-epoch-99-avg-1-chunk-16-left-64.onnxdecoder-epoch-99-avg-1-chunk-16-left-64.onnxjoiner-epoch-99-avg-1-chunk-16-left-64.onnxtokens.txt文件名里的chunk-16和left-64就是第 2 节说的块长与左上下文长度和模型元数据一一对应。第 2 步创建识别器与流。recognizer sherpa_onnx.OnlineRecognizer(config) stream recognizer.create_stream() stream.accept_waveform(16000, waveform)create_stream()内部就是调用GetEncoderInitStates()把 N × 7 个缓存全部填零——初始化缓存为零值这件事你一行都不用写。第 3 步循环喂数据、循环解码。if recognizer.is_ready(stream): recognizer.decode_stream(stream) # 这一帧的缓存会被自动回收到下一帧decode_stream()每次执行完输出里的新缓存会被写回该 stream 的状态下一帧自动接上。识别一条音频结束后调用recognizer.reset(stream)缓存重新归零等价于开始说新的一句话。完整可运行的脚本在 python-api-examples/online-decode-files.py麦克风实时版在 speech-recognition-from-microphone.py对着跑一遍比读 10 页文档有效。4. 排错清单按这个顺序过一遍基本能收敛数输入名用任意 ONNX 工具打印 encoder 的 input 列表和报错里 missing 的名字逐一对。缺哪个补哪个顺序无所谓、名字必须一致。校验缓存数量len(缓存列表) 层数 × 7。层数不确定读元数据num_encoder_layers。核对维度来源维度必须取自该 ONNX 文件自己的元数据不要从别的 chunk 配置的模型抄——chunk-16-left-64和chunk-8-left-128的缓存形状不同。确认帧数与块长对齐encoder 每次消费固定帧数的特征块decode_chunk_len多给少给都会让processed_frames记账错位表现为识别结果越来越歪。确认没有每帧重建 stream新建 stream 或每帧reset()等于主动丢上下文短语音没事长句开始错。最后再怀疑模型本身encoder/decoder/joiner 三个文件必须同批导出文件名里的 epoch 和 chunk 参数一致混用不同批次的文件是隐蔽但常见的翻车点。5. 下一步去哪儿看想读懂缓存是怎么拼进去的sherpa-onnx/csrc/online-zipformer-transducer-model.cc 的RunEncoder()20 来行就是特征 N×7 缓存 → 一次 session.Run。想看 C 侧完整调用链c-api-examples/streaming-zipformer-c-api.c 是最小的端到端工程cxx-api-examples/streaming-zipformer-cxx-api.cc 是带 RTF 统计的版本。想在网页上直接体验python-api-examples/web/ 提供上传和录音两个页面起个服务即可。关键词检测同样复用这套流式 Zipformer 缓存机制参考 keywords-spotter-buffered-tokens-keywords-c-api.c。记住一句话收尾Zipformer 的复杂输入只是把流式状态显式化了而状态管理恰恰是 sherpa-onnx 替你干完的脏活——你负责把 16k 的采样点按时喂进去就行。【免费下载链接】sherpa-onnxSpeech-to-text, text-to-speech, speaker diarization, speech enhancement, source separation, and VAD using next-gen Kaldi with onnxruntime without Internet connection. Support embedded systems, Android, iOS, HarmonyOS, Raspberry Pi, RISC-V, RK NPU, Axera NPU, Ascend NPU, x86_64 servers, websocket server/client, support 12 programming languages项目地址: https://gitcode.com/GitHub_Trending/sh/sherpa-onnx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考