FunASR 模型注册机制完全指南从注册表到 AutoModel 的自定义模型接入实战【免费下载链接】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 开源语音识别工具包中的模型注册Model Registration机制如何通过tables.register把自定义 Python 实现挂接到配置名如何满足AutoModel的推理/训练/导出契约以及如何安全加载经过审查的自定义代码与权重。读完本文你将掌握自定义模型接入 FunASR 的两条完整路径直接注册与模型目录解析并具备通过源码核验注册行为、排查注册冲突与远程代码加载问题的实战能力。注册的本质连接 Python 实现与配置名在 FunASR 中注册只做一件事把一个 Python 类与一个配置名registry key绑定起来。它不会下载权重、不会让任意 Transformers 模型自动变得兼容、不提供训练/导出支持也不认证模型质量。理解这一点是使用注册机制的前提——文档明确列出了本指南所依赖的四个核心组件均位于仓库源码中检查在案的注册表funasr/register.py统一入口funasr/auto/auto_model.pyHub 加载器funasr/download/download_model_from_hub.py动态导入器funasr/utils/dynamic_import.py从源码结构看整个注册系统围绕 funasr/register.py 中的RegisterTables类展开它定义了model_classes、frontend_classes、encoder_classes、decoder_classes、tokenizer_classes、dataset_classes、index_ds_classes、batch_sampler_classes等多张注册表并在模块底部实例化全局单例tables。AutoModel、训练器以及各类组件均通过这个全局tables对象查表取类。命名规则与导入顺序注册表是全局的顺序即命运注册装饰器的用法在构造之前被导入的类上使用装饰器tables.register(model_classes, YourUniqueModelName) class YourModel(torch.nn.Module): ...其中tables来自funasr.register。第二个参数是精确、区分大小写的注册表键省略时使用 Python 类名作为键。funasr/register.py 中的register实现揭示了几点关键行为允许新表名register内部用hasattr(self, register_tables_key)判断若表不存在则setattr自动创建并打 debug 日志。这意味着一个拼写错误不会报错而是悄悄创建一张无人消费的空表——这正是文档反复强调每个消费者各有自己的契约的原因把类注册进encoder_classes并不会让它成为完整的AutoModel模型。返回原类装饰器最终return target_class不改变类的行为。记录源码位置装饰器通过inspect.getfile与inspect.getsourcelines记录类的源文件与行号存入register_tables_key _meta元数据表供tables.print展示。键冲突与覆盖语义键存放在进程级全局字典中。已存在的键会被覆盖且只打一条 debug 日志而不是报错——所以导入及其顺序至关重要。因此使用组织/项目专属命名并加冲突保护不要为无关的自定义模型使用SenseVoiceSmall、Paraformer、FunASRNano这类名字。查看注册状态tables.print(model) # 显示注册元数据注册名 / 类名 / 类位置 active tables.model_classes[name] # 获取当前生效的实现print方法funasr/register.py会渲染一个表格列出注册名、类名、类位置格式为funasr/xxx/model.py:行号源码中用正则把绝对路径裁剪为仓库内相对路径。最小本地契约示例一个不需要权重的回显模型下面的例子放在一个可导入的custom_model_demo.py中建议放在临时目录然后在安装好本仓库的环境里执行python custom_model_demo.py。它故意返回输入文本而非语音识别结果不需要权重、音频、Hub 下载或 GPU。为什么必须带参数因为AutoModel.inference在结尾会执行next(model.parameters()).device来获取设备信息见 funasr/auto/auto_model.py一个完全没有参数的玩具模型会在这条路径上报错。import torch from funasr import AutoModel from funasr.register import tables MODEL_NAME DocsEchoModelV1 if MODEL_NAME in tables.model_classes: raise RuntimeError(fRegistry collision: {MODEL_NAME}) tables.register(model_classes, MODEL_NAME) class DocsEchoModel(torch.nn.Module): def __init__(self, **kwargs): super().__init__() self.anchor torch.nn.Parameter(torch.zeros(1), requires_gradFalse) def inference( self, data_in, data_lengthsNone, keyNone, tokenizerNone, frontendNone, **kwargs, ): results [ {key: sample_key, text: str(value)} for sample_key, value in zip(key, data_in) ] return results, {} if __name__ __main__: model AutoModel( modelMODEL_NAME, model_conf{}, devicecpu, disable_updateTrue, disable_pbarTrue, ) result model.generate(input[hello, world], data_typetext) assert [row[text] for row in result] [hello, world] assert all(isinstance(row[key], str) for row in result) print([row[text] for row in result])预期的最终打印列表是[hello, world]。这只是一个接线检查wiring check文档中对应的聚焦测试会在临时文件中执行这段代码、针对检入的实现进行验证但不会验证任何语音模型。为什么model_conf{}是关键model_conf{}的存在是刻意的在AutoModel.build_model中funasr/auto/auto_model.py只要model_conf in kwargs就会跳过download_model的 Hub/配置解析。因此这里的model是已注册的类键而不是模型目录或 Hub ID。自定义模块需要你自己先导入在直接注册路径上添加remote_code并不会触发导入。解析后的 kwargs 会合并覆盖到model_conf之上并传给构造函数其中包括已构建好的 tokenizer/frontend 对象、设备信息以及词汇表/输入尺寸。因此构造函数的签名要像真实模型一样接受合适的具名参数加上**kwargs。推理与训练契约AutoModel如何调用你的模型下表总结了本仓库this checkout中AutoModel对自定义模型的调用契约接口本仓库中的契约模型对象通常是torch.nn.Module必须支持.to(...)、.eval()和.parameters()。构造函数配置因模型而异。inference输入无 VAD 时AutoModel将输入分批为data_in与key两个列表并在torch.no_grad()下调用model.inference(**batch, **kwargs)见 funasr/auto/auto_model.py。当data_typefbank且只有一条数据时直接把特征对象传入data_in并额外提供data_lengthsinput_len。tokenizer/frontend 是已解析的对象或None。模型级返回值返回二元组(results, meta_data)results是list[dict]meta_data是字典。ASR 场景下results中的每个 dict 需含字符串key与text字段并保持输入顺序/键不变。直接返回裸的结果 dict 列表是错的AutoModel会把其第一项当作整批结果。元数据可选的load_data、extract_feat、batch_data_time。对音频而言batch_data_time是以秒为单位的正时长不是毫秒为 0 会在计时代码中造成除零缺省时使用内部-1哨兵值就像上面的非音频玩具模型此时测不到有意义的 RTF。对外返回AutoModel.generate(...)返回展平后的结果列表。时间戳等附加字段因模型而异注册本身不承诺提供它们。VAD、标点、说话人、流式等集成需要额外兼容行为和独立测试。训练实现可微分的forward字段名与数据集 collator 的具名张量字段一致。Trainer 从模型输出解包(loss, stats, weight)SenseVoice 与 Nano 使用force_gatherable把标量搬到设备并转成张量见 funasr/train_utils/device_funcs.py 的force_gatherable。上面这个玩具模型故意没有训练 forward。导出Export utility 调用模型的export随后调用模型专属的export_dummy_inputs、输入/输出名与动态轴等方法支持 onnx、torchscript、bladedisc、onnx_fp16 等类型。仅注册并不会实现这些。自定义模型必须自行实现音频加载、特征准备、tokenization/解码与批处理按需。正确姿势是从一个相近的真实模型复制契约而不是复制其能力却无实现。训练场景下还需实现/配置配套的数据集与损失函数参见 training。加载经过审查的自定义代码与权重两条截然不同的路径路径一直接注册Direct registration导入你的模块像玩具示例那样传键与model_conf。若需要权重提供兼容的 tokenizer/frontend/配置以及已存在的init_param。此路径不做任何 Hub 代码导入。路径二模型目录解析Model-directory resolution传入经过审查的本地目录或 Hub ID且不带model_conf。加载器读取configuration.json文件元数据或config.yaml解析模型键/资源并加载权重。一个简单的本地config.yaml目录通常还需要model.pt以及所有被引用的 tokenizer/frontend 资源。任意的 HF 权重文件夹不会自动成为 FunASR 模型目录。第二条路径对应 ModelScope 接口下面的示例不是一个自包含的可运行示例models/custom-asr必须已包含兼容且经过审查的配置与权重custom_asr_model.py必须注册精确的配置键from funasr import AutoModel model AutoModel( model./models/custom-asr, hubms, trust_remote_codeTrue, remote_code./custom_asr_model.py, devicecpu, disable_updateTrue, ) print(model.generate(inputdata/audio/heldout.wav))两个 Hub 加载器的差异务必核对看 funasr/download/download_model_from_hub.py 的源码实现ModelScope 路径download_from_ms第 44-119 行trust_remote_codeTrue时会导入remote_code缺省模块名为model。它会读取configuration.json含file_path_metas资源映射或config.yaml并自动把目录下的model.pt、tokens.txt/tokens.json、seg_dict、bpe.model、am.mvn、jieba_usr_dict等解析进 kwargs还会在信任标志下安装目录里的requirements.txt。Hugging Face 路径download_from_hf第 122-188 行也能解析配置与安装 requirements但不会调用import_module_from_path。不要假设remote_code会在 HF 路径被执行——应在hubhf构造前显式导入你审查过的自定义模块或走带完整配置的直接注册路径。import_module_from_pathfunasr/utils/dynamic_import.py的行为细节支持模块/文件路径以及以http开头的 URL 下载把文件所在目录追加到sys.path按 basename 导入相对路径相对于当前工作目录解析而不是自动相对于权重目录由于按 basename 导入且 Python 有导入缓存basename 冲突可能选中已加载的模块——请使用互不相同的模块名并核实最终生效的类该 helper打印导入异常而不是重新抛出所以必须自己检查错误与注册表状态。另外本地config.yaml回退对init_param的处理在两个 Hub 间也不同ModelScope 保留已有的显式路径Hugging Face 则总是赋值为目录下的model.pt。务必核对解析后的路径不要假设你选中的 checkpoint 覆盖项保留了下来。真实示例与边界仓库中的真实模型是理解契约的最好教材SenseVoiceSmall 实现在 funasr/models/sense_voice/model.py 中以tables.register(model_classes, SenseVoiceSmall)注册展示了训练forwardforce_gatherable、推理inference与导出export的完整集成。参考它时要保留其模型专属配置与 tokenizer 假设。Nano demo1.py展示了trust_remote_codeTrue、remote_code./model.py、hubms的用法并假设运行于 recipe 目录。其本地实现注册FunASRNano并导入同级ctc、tools模块——这会覆盖内置实现两者并非所有特性包括内置 LoRA都可互换。务必审计最终生效的类与 checkpoint 键。MOSS 适配器集成第三方 OpenMOSS 模型并在forward中明确拒绝训练。它证明了已注册不等于支持微调或导出。原始的注册教程与通用教程仍是有效的历史参考当其中示例与当前源码行为不一致时以本文上述的当前源码行为为准。安全与验证远程代码有执行权trust_remote_codeTrue意味着允许 Python 代码执行Hub 加载器在信任标志下还可能安装模型目录的requirements.txt。本地目录并不天然可信。必须审查源码、依赖与权重序列化格式使用隔离环境不要加载不受信任的 pickle checkpoint切勿把不受信任的 URL、模块名或配置插值进这套工作流当远程 revision 处理不可靠时保留一份带哈希的审查过的本地快照——在本仓库中model_revision并非所有加载器路径上的通用锁定手段例如 get_or_download_model_dir_hf 直接调用snapshot_download而未传入 revision。加载前务必核实生效的注册键/类/源码位置确认模型/配置/tokenizer 的精确兼容性检查缺失或意外的权重——注意AutoModel中ignore_init_mismatch默认为 True而一个不存在的直接init_param只会打印错误、不保证构造失败见 funasr/auto/auto_model.py所以请自行验证 checkpoint 是否存在。在训练/导出/部署前测试单条数据、多条数据、错误处理与目标流水线。另外FunASR 软件的 MIT 许可不能替代模型或上游组件的许可。针对文档契约的聚焦检查语法、仓库链接、无下载的玩具契约可以这样运行python -m pytest -q tests/test_training_docs_contract.py需要明确这些检查不认证任意自定义代码的正确性、真实 ASR 质量、GPU 训练、真实 checkpoint 恢复或导出兼容性——它们只是接线的语法级保障。真正可靠的注册永远是审查过的代码 核验过的权重 跑通的目标流水线三者的结合。【免费下载链接】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），仅供参考