FunASR 模型注冊(cè)機(jī)制完全指南從注冊(cè)表到 AutoModel 的自定義模型接入實(shí)戰(zhàn)【免費(fèi)下載鏈接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/fun/FunASR本文系統(tǒng)講解 FunASR 開源語音識(shí)別工具包中的模型注冊(cè)Model Registration機(jī)制如何通過tables.register把自定義 Python 實(shí)現(xiàn)掛接到配置名如何滿足AutoModel的推理/訓(xùn)練/導(dǎo)出契約以及如何安全加載經(jīng)過審查的自定義代碼與權(quán)重。讀完本文你將掌握自定義模型接入 FunASR 的兩條完整路徑直接注冊(cè)與模型目錄解析并具備通過源碼核驗(yàn)注冊(cè)行為、排查注冊(cè)沖突與遠(yuǎn)程代碼加載問題的實(shí)戰(zhàn)能力。注冊(cè)的本質(zhì)連接 Python 實(shí)現(xiàn)與配置名在 FunASR 中注冊(cè)只做一件事把一個(gè) Python 類與一個(gè)配置名registry key綁定起來。它不會(huì)下載權(quán)重、不會(huì)讓任意 Transformers 模型自動(dòng)變得兼容、不提供訓(xùn)練/導(dǎo)出支持也不認(rèn)證模型質(zhì)量。理解這一點(diǎn)是使用注冊(cè)機(jī)制的前提——文檔明確列出了本指南所依賴的四個(gè)核心組件均位于倉庫源碼中檢查在案的注冊(cè)表funasr/register.py統(tǒng)一入口funasr/auto/auto_model.pyHub 加載器funasr/download/download_model_from_hub.py動(dòng)態(tài)導(dǎo)入器funasr/utils/dynamic_import.py從源碼結(jié)構(gòu)看整個(gè)注冊(cè)系統(tǒng)圍繞 funasr/register.py 中的RegisterTables類展開它定義了model_classes、frontend_classes、encoder_classes、decoder_classes、tokenizer_classes、dataset_classes、index_ds_classes、batch_sampler_classes等多張注冊(cè)表并在模塊底部實(shí)例化全局單例tables。AutoModel、訓(xùn)練器以及各類組件均通過這個(gè)全局tables對(duì)象查表取類。命名規(guī)則與導(dǎo)入順序注冊(cè)表是全局的順序即命運(yùn)注冊(cè)裝飾器的用法在構(gòu)造之前被導(dǎo)入的類上使用裝飾器tables.register(model_classes, YourUniqueModelName) class YourModel(torch.nn.Module): ...其中tables來自funasr.register。第二個(gè)參數(shù)是精確、區(qū)分大小寫的注冊(cè)表鍵省略時(shí)使用 Python 類名作為鍵。funasr/register.py 中的register實(shí)現(xiàn)揭示了幾點(diǎn)關(guān)鍵行為允許新表名register內(nèi)部用hasattr(self, register_tables_key)判斷若表不存在則setattr自動(dòng)創(chuàng)建并打 debug 日志。這意味著一個(gè)拼寫錯(cuò)誤不會(huì)報(bào)錯(cuò)而是悄悄創(chuàng)建一張無人消費(fèi)的空表——這正是文檔反復(fù)強(qiáng)調(diào)每個(gè)消費(fèi)者各有自己的契約的原因把類注冊(cè)進(jìn)encoder_classes并不會(huì)讓它成為完整的AutoModel模型。返回原類裝飾器最終return target_class不改變類的行為。記錄源碼位置裝飾器通過inspect.getfile與inspect.getsourcelines記錄類的源文件與行號(hào)存入register_tables_key _meta元數(shù)據(jù)表供tables.print展示。鍵沖突與覆蓋語義鍵存放在進(jìn)程級(jí)全局字典中。已存在的鍵會(huì)被覆蓋且只打一條 debug 日志而不是報(bào)錯(cuò)——所以導(dǎo)入及其順序至關(guān)重要。因此使用組織/項(xiàng)目專屬命名并加沖突保護(hù)不要為無關(guān)的自定義模型使用SenseVoiceSmall、Paraformer、FunASRNano這類名字。查看注冊(cè)狀態(tài)tables.print(model) # 顯示注冊(cè)元數(shù)據(jù)注冊(cè)名 / 類名 / 類位置 active tables.model_classes[name] # 獲取當(dāng)前生效的實(shí)現(xiàn)print方法funasr/register.py會(huì)渲染一個(gè)表格列出注冊(cè)名、類名、類位置格式為funasr/xxx/model.py:行號(hào)源碼中用正則把絕對(duì)路徑裁剪為倉庫內(nèi)相對(duì)路徑。最小本地契約示例一個(gè)不需要權(quán)重的回顯模型下面的例子放在一個(gè)可導(dǎo)入的custom_model_demo.py中建議放在臨時(shí)目錄然后在安裝好本倉庫的環(huán)境里執(zhí)行python custom_model_demo.py。它故意返回輸入文本而非語音識(shí)別結(jié)果不需要權(quán)重、音頻、Hub 下載或 GPU。為什么必須帶參數(shù)因?yàn)锳utoModel.inference在結(jié)尾會(huì)執(zhí)行next(model.parameters()).device來獲取設(shè)備信息見 funasr/auto/auto_model.py一個(gè)完全沒有參數(shù)的玩具模型會(huì)在這條路徑上報(bào)錯(cuò)。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])預(yù)期的最終打印列表是[hello, world]。這只是一個(gè)接線檢查wiring check文檔中對(duì)應(yīng)的聚焦測(cè)試會(huì)在臨時(shí)文件中執(zhí)行這段代碼、針對(duì)檢入的實(shí)現(xiàn)進(jìn)行驗(yàn)證但不會(huì)驗(yàn)證任何語音模型。為什么model_conf{}是關(guān)鍵model_conf{}的存在是刻意的在AutoModel.build_model中funasr/auto/auto_model.py只要model_conf in kwargs就會(huì)跳過download_model的 Hub/配置解析。因此這里的model是已注冊(cè)的類鍵而不是模型目錄或 Hub ID。自定義模塊需要你自己先導(dǎo)入在直接注冊(cè)路徑上添加remote_code并不會(huì)觸發(fā)導(dǎo)入。解析后的 kwargs 會(huì)合并覆蓋到model_conf之上并傳給構(gòu)造函數(shù)其中包括已構(gòu)建好的 tokenizer/frontend 對(duì)象、設(shè)備信息以及詞匯表/輸入尺寸。因此構(gòu)造函數(shù)的簽名要像真實(shí)模型一樣接受合適的具名參數(shù)加上**kwargs。推理與訓(xùn)練契約AutoModel如何調(diào)用你的模型下表總結(jié)了本倉庫this checkout中AutoModel對(duì)自定義模型的調(diào)用契約接口本倉庫中的契約模型對(duì)象通常是torch.nn.Module必須支持.to(...)、.eval()和.parameters()。構(gòu)造函數(shù)配置因模型而異。inference輸入無 VAD 時(shí)AutoModel將輸入分批為data_in與key兩個(gè)列表并在torch.no_grad()下調(diào)用model.inference(**batch, **kwargs)見 funasr/auto/auto_model.py。當(dāng)data_typefbank且只有一條數(shù)據(jù)時(shí)直接把特征對(duì)象傳入data_in并額外提供data_lengthsinput_len。tokenizer/frontend 是已解析的對(duì)象或None。模型級(jí)返回值返回二元組(results, meta_data)results是list[dict]meta_data是字典。ASR 場(chǎng)景下results中的每個(gè) dict 需含字符串key與text字段并保持輸入順序/鍵不變。直接返回裸的結(jié)果 dict 列表是錯(cuò)的AutoModel會(huì)把其第一項(xiàng)當(dāng)作整批結(jié)果。元數(shù)據(jù)可選的load_data、extract_feat、batch_data_time。對(duì)音頻而言batch_data_time是以秒為單位的正時(shí)長(zhǎng)不是毫秒為 0 會(huì)在計(jì)時(shí)代碼中造成除零缺省時(shí)使用內(nèi)部-1哨兵值就像上面的非音頻玩具模型此時(shí)測(cè)不到有意義的 RTF。對(duì)外返回AutoModel.generate(...)返回展平后的結(jié)果列表。時(shí)間戳等附加字段因模型而異注冊(cè)本身不承諾提供它們。VAD、標(biāo)點(diǎn)、說話人、流式等集成需要額外兼容行為和獨(dú)立測(cè)試。訓(xùn)練實(shí)現(xiàn)可微分的forward字段名與數(shù)據(jù)集 collator 的具名張量字段一致。Trainer 從模型輸出解包(loss, stats, weight)SenseVoice 與 Nano 使用force_gatherable把標(biāo)量搬到設(shè)備并轉(zhuǎn)成張量見 funasr/train_utils/device_funcs.py 的force_gatherable。上面這個(gè)玩具模型故意沒有訓(xùn)練 forward。導(dǎo)出Export utility 調(diào)用模型的export隨后調(diào)用模型專屬的export_dummy_inputs、輸入/輸出名與動(dòng)態(tài)軸等方法支持 onnx、torchscript、bladedisc、onnx_fp16 等類型。僅注冊(cè)并不會(huì)實(shí)現(xiàn)這些。自定義模型必須自行實(shí)現(xiàn)音頻加載、特征準(zhǔn)備、tokenization/解碼與批處理按需。正確姿勢(shì)是從一個(gè)相近的真實(shí)模型復(fù)制契約而不是復(fù)制其能力卻無實(shí)現(xiàn)。訓(xùn)練場(chǎng)景下還需實(shí)現(xiàn)/配置配套的數(shù)據(jù)集與損失函數(shù)參見 training。加載經(jīng)過審查的自定義代碼與權(quán)重兩條截然不同的路徑路徑一直接注冊(cè)Direct registration導(dǎo)入你的模塊像玩具示例那樣傳鍵與model_conf。若需要權(quán)重提供兼容的 tokenizer/frontend/配置以及已存在的init_param。此路徑不做任何 Hub 代碼導(dǎo)入。路徑二模型目錄解析Model-directory resolution傳入經(jīng)過審查的本地目錄或 Hub ID且不帶model_conf。加載器讀取configuration.json文件元數(shù)據(jù)或config.yaml解析模型鍵/資源并加載權(quán)重。一個(gè)簡(jiǎn)單的本地config.yaml目錄通常還需要model.pt以及所有被引用的 tokenizer/frontend 資源。任意的 HF 權(quán)重文件夾不會(huì)自動(dòng)成為 FunASR 模型目錄。第二條路徑對(duì)應(yīng) ModelScope 接口下面的示例不是一個(gè)自包含的可運(yùn)行示例models/custom-asr必須已包含兼容且經(jīng)過審查的配置與權(quán)重custom_asr_model.py必須注冊(cè)精確的配置鍵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))兩個(gè) Hub 加載器的差異務(wù)必核對(duì)看 funasr/download/download_model_from_hub.py 的源碼實(shí)現(xiàn)ModelScope 路徑download_from_ms第 44-119 行trust_remote_codeTrue時(shí)會(huì)導(dǎo)入remote_code缺省模塊名為model。它會(huì)讀取configuration.json含file_path_metas資源映射或config.yaml并自動(dòng)把目錄下的model.pt、tokens.txt/tokens.json、seg_dict、bpe.model、am.mvn、jieba_usr_dict等解析進(jìn) kwargs還會(huì)在信任標(biāo)志下安裝目錄里的requirements.txt。Hugging Face 路徑download_from_hf第 122-188 行也能解析配置與安裝 requirements但不會(huì)調(diào)用import_module_from_path。不要假設(shè)remote_code會(huì)在 HF 路徑被執(zhí)行——應(yīng)在hubhf構(gòu)造前顯式導(dǎo)入你審查過的自定義模塊或走帶完整配置的直接注冊(cè)路徑。import_module_from_pathfunasr/utils/dynamic_import.py的行為細(xì)節(jié)支持模塊/文件路徑以及以http開頭的 URL 下載把文件所在目錄追加到sys.path按 basename 導(dǎo)入相對(duì)路徑相對(duì)于當(dāng)前工作目錄解析而不是自動(dòng)相對(duì)于權(quán)重目錄由于按 basename 導(dǎo)入且 Python 有導(dǎo)入緩存basename 沖突可能選中已加載的模塊——請(qǐng)使用互不相同的模塊名并核實(shí)最終生效的類該 helper打印導(dǎo)入異常而不是重新拋出所以必須自己檢查錯(cuò)誤與注冊(cè)表狀態(tài)。另外本地config.yaml回退對(duì)init_param的處理在兩個(gè) Hub 間也不同ModelScope 保留已有的顯式路徑Hugging Face 則總是賦值為目錄下的model.pt。務(wù)必核對(duì)解析后的路徑不要假設(shè)你選中的 checkpoint 覆蓋項(xiàng)保留了下來。真實(shí)示例與邊界倉庫中的真實(shí)模型是理解契約的最好教材SenseVoiceSmall 實(shí)現(xiàn)在 funasr/models/sense_voice/model.py 中以tables.register(model_classes, SenseVoiceSmall)注冊(cè)展示了訓(xùn)練forwardforce_gatherable、推理inference與導(dǎo)出export的完整集成。參考它時(shí)要保留其模型專屬配置與 tokenizer 假設(shè)。Nano demo1.py展示了trust_remote_codeTrue、remote_code./model.py、hubms的用法并假設(shè)運(yùn)行于 recipe 目錄。其本地實(shí)現(xiàn)注冊(cè)FunASRNano并導(dǎo)入同級(jí)ctc、tools模塊——這會(huì)覆蓋內(nèi)置實(shí)現(xiàn)兩者并非所有特性包括內(nèi)置 LoRA都可互換。務(wù)必審計(jì)最終生效的類與 checkpoint 鍵。MOSS 適配器集成第三方 OpenMOSS 模型并在forward中明確拒絕訓(xùn)練。它證明了已注冊(cè)不等于支持微調(diào)或?qū)С觥Ｔ嫉淖?cè)教程與通用教程仍是有效的歷史參考當(dāng)其中示例與當(dāng)前源碼行為不一致時(shí)以本文上述的當(dāng)前源碼行為為準(zhǔn)。安全與驗(yàn)證遠(yuǎn)程代碼有執(zhí)行權(quán)trust_remote_codeTrue意味著允許 Python 代碼執(zhí)行Hub 加載器在信任標(biāo)志下還可能安裝模型目錄的requirements.txt。本地目錄并不天然可信。必須審查源碼、依賴與權(quán)重序列化格式使用隔離環(huán)境不要加載不受信任的 pickle checkpoint切勿把不受信任的 URL、模塊名或配置插值進(jìn)這套工作流當(dāng)遠(yuǎn)程 revision 處理不可靠時(shí)保留一份帶哈希的審查過的本地快照——在本倉庫中model_revision并非所有加載器路徑上的通用鎖定手段例如 get_or_download_model_dir_hf 直接調(diào)用snapshot_download而未傳入 revision。加載前務(wù)必核實(shí)生效的注冊(cè)鍵/類/源碼位置確認(rèn)模型/配置/tokenizer 的精確兼容性檢查缺失或意外的權(quán)重——注意AutoModel中ignore_init_mismatch默認(rèn)為 True而一個(gè)不存在的直接init_param只會(huì)打印錯(cuò)誤、不保證構(gòu)造失敗見 funasr/auto/auto_model.py所以請(qǐng)自行驗(yàn)證 checkpoint 是否存在。在訓(xùn)練/導(dǎo)出/部署前測(cè)試單條數(shù)據(jù)、多條數(shù)據(jù)、錯(cuò)誤處理與目標(biāo)流水線。另外FunASR 軟件的 MIT 許可不能替代模型或上游組件的許可。針對(duì)文檔契約的聚焦檢查語法、倉庫鏈接、無下載的玩具契約可以這樣運(yùn)行python -m pytest -q tests/test_training_docs_contract.py需要明確這些檢查不認(rèn)證任意自定義代碼的正確性、真實(shí) ASR 質(zhì)量、GPU 訓(xùn)練、真實(shí) checkpoint 恢復(fù)或?qū)С黾嫒菪浴鼈冎皇墙泳€的語法級(jí)保障。真正可靠的注冊(cè)永遠(yuǎn)是審查過的代碼 核驗(yàn)過的權(quán)重 跑通的目標(biāo)流水線三者的結(jié)合。【免費(fèi)下載鏈接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/fun/FunASR創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考