sherpa-onnx 中 WeSpeaker 说话人嵌入模型 ONNX 元数据注入指南从 pretrained 模型到可直接推理的完整流程【免费下载链接】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导读本指南围绕 scripts/wespeaker 目录下的三个脚本展开系统讲解如何把来自 WeSpeaker 预训练模型列表的*.onnx说话人嵌入speaker embedding模型通过注入元数据meta data转换为 sherpa-onnx 可直接加载与推理的模型并给出下载、注入、验证、重命名的完整操作流程与底层原理。读完本文你将掌握add_meta_data.py各参数的确切含义、模型元数据被 sherpa-onnx C 推理引擎消费的源码级机制以及用test.py快速验证声纹相似度的方法。为什么需要给 ONNX 模型注入元数据sherpa-onnx 的设计目标是支持来自不同框架framework的模型。说话人嵌入模型并非只有 WeSpeaker 一家出品为了在同一套推理引擎内统一处理不同框架的模型sherpa-onnx 约定模型自身必须携带描述其输入输出规范的元数据。因此 scripts/wespeaker/README.md 明确强调Caution: You have to add model meta data to*.onnxsince we plan to support models from different frameworks.即必须先把元数据写入*.onnx文件本体sherpa-onnx 才能识别并使用该模型。这个约束在源码中同样可以印证speaker-embedding-extractor-model.cc 在加载模型时会读取framework字段若其取值既不是wespeaker也不是3d-speaker会直接报错退出——可见元数据是模型的身份证缺一不可。目录结构与脚本职责scripts/wespeaker 目录共包含四个文件职责划分如下文件作用README.md说明目录用途与注意事项add_meta_data.py向 ONNX 模型注入元数据核心脚本run.sh一键流程下载模型 → 注入元数据 → 测试 → 重命名test.py用两段 wav 计算说话人相似度验证模型可用性add_meta_data.py元数据注入工具的完整参数说明命令行参数add_meta_data.py通过argparse定义 5 个参数其中 2 个为必填参数必填默认值说明--model是无输入 ONNX 模型路径例如model.onnx--language是无模型支持的语言如Chinese、English--url否WeSpeaker pretrained 文档地址模型下载来源--comment否no comment关于模型的备注--sample-rate否16000模型期望的采样率注入的元数据字段脚本将以下键值对写入 ONNX 模型的metadata_props最终输出形如{ framework: wespeaker, language: language, url: url, comment: comment, sample_rate: sample_rate, output_dim: output_dim, normalize_samples: 0, }各字段含义如下framework固定为wespeaker是 sherpa-onnx 区分模型来源的关键标识language模型支持的语言直接来自--language参数url模型下载地址便于溯源comment模型备注sample_rate模型期望的输入采样率WeSpeaker 系列模型默认为 16000 Hzoutput_dim说话人嵌入向量的维度由脚本自动探测见下文normalize_samplesWeSpeaker 模型统一固定为0表示输入样本保持原始 int16 量程[-32768, 32767]不需要归一化到[-1, 1]。底层实现剖析add_meta_data.py的核心逻辑只有两步注入元数据add_meta_data()使用onnx.load(filename)读取模型通过model.metadata_props.add()逐条追加键值对最后onnx.save(model, filename)原地覆写原文件——注意该操作会直接修改模型文件本身建议先备份原始模型。自动探测输出维度get_output_dim()用onnxruntime.InferenceSession加载模型并打印输入输出张量信息随后执行断言校验模型符合 WeSpeaker 约定输入、输出各只有 1 个张量输入形状前两维为[B, T]batch、时间帧输入第三维必须为80即 80 维 FBank 特征输出第一维为B最终返回o.shape[1]作为嵌入向量维度即output_dim。也就是说脚本会主动校验模型输入是否与 WeSpeaker 的 80 维 FBank 约定一致从源头避免注入元数据后无法推理的模型进入 sherpa-onnx。run.sh从零到可用模型的完整流水线run.sh 是面向模型包维护者的批处理脚本流程清晰可复现第一步下载模型仓库export GIT_LFS_SKIP_SMUDGE1 export GIT_CLONE_PROTECTION_ACTIVEfalse git clone https://huggingface.co/openspeech/wespeaker-models cd wespeaker-models git lfs pull --include *.onnx先关闭 Git LFS 自动下载避免克隆时拉取全部大文件克隆wespeaker-models仓库后仅拉取*.onnx文件再将所有 ONNX 模型移动到上一级目录mv wespeaker-models/*.onnx .第二步为每个模型注入元数据并验证以voxceleb_resnet34.onnx为例完整流程为./add_meta_data.py \ --model ./voxceleb_resnet34.onnx \ --language English \ --url https://wespeaker-1256283475.cos.ap-shanghai.myqcloud.com/models/voxceleb/voxceleb_resnet34.onnx ./test.py --model ./voxceleb_resnet34.onnx \ --file1 ./wespeaker-models/test_wavs/00001_spk1.wav \ --file2 ./wespeaker-models/test_wavs/00024_spk1.wav ./test.py --model ./voxceleb_resnet34.onnx \ --file1 ./wespeaker-models/test_wavs/00001_spk1.wav \ --file2 ./wespeaker-models/test_wavs/00010_spk2.wav这里设计了一个成对验证策略对每个模型固定用同一说话人两段音频00001_spk1与00024_spk1验证相似度应接近 1再用不同说话人00001_spk1与00010_spk2验证相似度应显著更低。第三步按规范重命名验证通过后模型按framework_language_model的约定重命名run.sh 中涉及的全部模型及命名如下原始模型language重命名后voxceleb_resnet34.onnxEnglishwespeaker_en_voxceleb_resnet34.onnxvoxceleb_resnet34_LM.onnxEnglishwespeaker_en_voxceleb_resnet34_LM.onnxvoxceleb_resnet152_LM.onnxEnglishwespeaker_en_voxceleb_resnet152_LM.onnxvoxceleb_resnet221_LM.onnxEnglishwespeaker_en_voxceleb_resnet221_LM.onnxvoxceleb_resnet293_LM.onnxEnglishwespeaker_en_voxceleb_resnet293_LM.onnxvoxceleb_CAM.onnxEnglishwespeaker_en_voxceleb_CAM.onnxvoxceleb_CAM_LM.onnxEnglishwespeaker_en_voxceleb_CAM_LM.onnxcnceleb_resnet34.onnxChinesewespeaker_zh_cnceleb_resnet34.onnxcnceleb_resnet34_LM.onnxChinesewespeaker_zh_cnceleb_resnet34_LM.onnx命名中的_LM后缀表示该模型经过 Large Margin 训练策略优化CAM是另一种声纹网络结构。这种框架_语言_模型名的命名规范与 sherpa-onnx 预编译包、示例脚本中的引用方式保持一致例如 speaker-identification.py 下载的正是wespeaker_zh_cnceleb_resnet34.onnx说明经过本流程产出的模型可以直接被官方示例消费。test.py声纹相似度验证工具的原理test.py 用于验证注入元数据后的模型能否正确提取嵌入并计算相似度输出 0~1 之间的余弦相似度分数。其执行链路可拆解为四步1. 读取 wav 并解析模型元数据read_wavefile() 读取 16-bit、16kHz 的单声道 wav断言采样率与模型元数据中的sample_rate一致然后转换为[-1, 1]区间的 float32 数组OnnxModel.__init__通过model.get_modelmeta().custom_metadata_map读取normalize_samples、sample_rate、output_dim三个元数据字段——这与 sherpa-onnx C 端读取方式同源。2. 按 normalize_samples 还原输入量程WeSpeaker 模型要求输入保持 int16 量程因此if not model.normalize_samples: wave1 wave1 * 32768 wave2 wave2 * 32768即当normalize_samples 0时把[-1, 1]的音频还原为[-32768, 32767]与 add_meta_data.py 中的注释all models from wespeaker expect input samples in the range [-32768, 32767]完全对应。3. 用 kaldi_native_fbank 提取 80 维 FBankcompute_features() 使用kaldi_native_fbank库配置 80 维 FBankmel_opts.num_bins 80关闭 dithersnip_edges False逐帧提取特征堆叠成(T, 80)张量——这与 sherpa-onnx 在 C 侧使用OnlineFbank的提取方式一致。4. 计算余弦相似度similarity np.dot(output1, output2) / (norm(output1) * norm(output2))对两个嵌入向量计算余弦相似度越接近 1 表示两段语音越可能来自同一说话人。run.sh 中用同一说话人≈1、不同说话人显著更低的结果模式来判定模型注入元数据后是否正常。sherpa-onnx 是如何消费这些元数据的注入的元数据并非摆设sherpa-onnx 的推理引擎会在模型加载阶段逐项读取并据此配置预处理读取与校验speaker-embedding-extractor-model.cc 通过SHERPA_ONNX_READ_META_DATA宏读取output_dim、sample_rate、normalize_samples、language并校验framework必须为wespeaker或3d-speaker否则直接SHERPA_ONNX_EXIT(-1)终止驱动特征提取器配置speaker-embedding-extractor-general-impl.h 中的CreateStream()用元数据中的sample_rate与normalize_samples构造FeatureExtractorConfig其中Dim()直接返回元数据中的output_dim驱动输入量程元数据normalize_samples在 sherpa-onnx 中对应结构体 SpeakerEmbeddingExtractorModelMetaData注释明确写着 for wespeaker models, it is 0; for 3d-speaker models, it is 1即 WeSpeaker 与 3D-Speaker 两个框架的模型在输入量程约定上不同全靠元数据区分。这意味着用户拿到经 add_meta_data.py 处理后的模型后无需手工配置采样率、归一化策略和输出维度sherpa-onnx 会完全依据模型内嵌元数据自动完成预处理与后处理适配这也是支持不同框架模型这一设计得以成立的关键。在自有 WeSpeaker 模型上复用的操作建议如果你的模型不在 run.sh 覆盖列表内可套用同一套流程将导出的 ONNX 模型放在本目录下执行./add_meta_data.py --model your_model.onnx --language Language必要时用--sample-rate覆盖默认 16000用./test.py --model your_model.onnx --file1 wav1 --file2 wav2验证同一/不同说话人的相似度是否符合预期按wespeaker_language_model_name.onnx规范重命名即可交给 sherpa-onnx 的 C / Python / Java / C# 等各语言 API 直接加载使用。总结本文完整梳理了 sherpa-onnx 项目中 WeSpeaker 说话人嵌入模型的接入链路add_meta_data.py负责注入framework、language、sample_rate、output_dim、normalize_samples等关键元数据并自动校验 80 维 FBank 输入约定run.sh提供可复现的下载—注入—验证—命名全流程test.py用余弦相似度验证模型可用性而 sherpa-onnx 源码则证明了这些元数据在推理引擎中如何被逐项读取并驱动特征提取。掌握这套流程后任何来自 WeSpeaker 的声纹模型都可以无缝接入 sherpa-onnx 的说话人识别、说话人日志diarization等上层应用。【免费下载链接】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），仅供参考