FunASR Python SDK 安裝完全指南從環境創建到離線推理【免費下載鏈接】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本指南以from funasr import AutoModel工具庫路徑為主線系統講解 FunASR 的完整安裝流程獨立虛擬環境創建、PyTorch 與 FunASR 雙通道安裝PyPI 包 / 源碼可編輯安裝、導入與依賴驗證、模型緩存與離線推理以及信任邊界與許可合規。讀完本文你將能在一臺新機器上從零搭建可復現的 FunASR 推理環境并掌握驗證安裝、排查導入失敗、準備離線模型快照的完整方法。本文檔配套英文版見 docs/installation/installation.md。若只需 Fun-ASR-Nano 的原生推理可走 Transformers 5.17.0 快速開始——它加載獨立的-hf權重不要求安裝 FunASR 工具庫本頁的AutoModel路徑與之在依賴、參數和輸出上不可混用。需要打包好的 C 服務時請先閱讀 Docker 與運行時鏡像安裝完成后再進入 SDK 教程。1. 創建獨立環境推薦在干凈的虛擬環境中安裝避免污染系統 Python 或與既有項目依賴沖突。以下命令以已安裝的 Python 3.11 為例但這不表示所有模型或后端都支持所有 Python 版本。Linux/macOSpython3.11 -m venv .venv . .venv/bin/activate python -m pip install --upgrade pipWindows PowerShellpy -3.11 -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install --upgrade pip也可以使用已有的 Conda 環境。若使用 CondaApple Silicon 上應選用架構一致的 arm64 解釋器和 wheel不要將 x86_64 Conda 環境與 arm64 包混用。關于版本兼容性可以從倉庫元數據獲得兩點依據setup.py 聲明了python_requires3.7.0但這只是打包層面的下限實際解析出的依賴如新版numpy、transformers和具體模型可能要求更高版本。pyproject.toml 僅定義構建后端setuptools.build_meta它不是鎖定的推理環境聲明不要把它當作依賴清單閱讀。2. 先安裝 PyTorch再選擇一種 FunASR 安裝方式FunASR 核心包不會替你選擇torch與torchaudio的構建。請根據解釋器、操作系統和加速設備在 PyTorch 官方安裝頁或版本兼容參考中選擇匹配的版本。不要僅憑本機 CUDA toolkit 版本判斷 wheel 是否兼容——需要以 PyTorch 官方發布的 wheel 構建為準。這一點在源碼中也有印證funasr/__init__.py的懶加載機制中若在導入AutoModel時發現torch缺失會拋出明確提示要求先安裝平臺匹配的 torch 構建如 CUDA 12.6 的--index-url https://download.pytorch.org/whl/cu126參見 funasr/init.py。方式一PyPI 使用已發布軟件包python -m pip install --upgrade funasr注意事項該命令從已配置的索引安裝可用軟件包不是當前 Git 工作區。當前源碼文檔中的模型或功能未必已包含在發行包中。需要復現時應將不鎖版本的安裝命令改為已驗證的精確版本。當前工作區版本記錄在 funasr/version.txt當前為1.4.15但不能據此證明索引上已有該版本。可編輯安裝直接導入該目錄中的源碼請記錄 commit 和本地修改它不會另存一份代碼。方式二源碼使用當前工作區及配套示例在已有 FunASR 倉庫根目錄執行python -m pip install -e . git rev-parse HEAD尚無工作區時可以先克隆倉庫再安裝git clone https://github.com/modelscope/FunASR.git cd FunASR python -m pip install -e .源碼安裝適合需要使用examples/、runtime/等配套資源或體驗未發布功能的場景——倉庫中的examples/、runtime/和文檔并不都會隨 PyPI 包安裝。依賴與 extras 說明本工作區已將modelscope和huggingface_hub列為核心依賴見 setup.py 的install依賴組不需要再按可選步驟安裝。模型專屬依賴仍需單獨處理。兩個實用 extrasextra提供內容適用場景knfkaldi-native-fbank無 torchaudio 時的特征提取回退后端Ascend NPU / aarch64 服務器等沒有匹配 torchaudio wheel 的環境sileroSilero VAD使用 Silero VAD 模型標準入門示例不需要這兩個 extras。添加 extra 前請查看 setup.py 和所選模型指南避免在同一環境中混裝互不兼容的模型依賴。此外trainextra 提供訓練專用模塊llmextra 提供大模型類 ASRQwen 系列等所需依賴all為聚合 extra。3. 驗證解釋器和導入在之后用于推理的同一個已激活環境中執行python -c import sys; print(sys.executable); print(sys.version) python -m pip --version python -m pip check python -c import funasr, torch, torchaudio; from funasr import AutoModel; print(funasr:, funasr.__version__, funasr.__file__); print(torch:, torch.__version__, torchaudio:, torchaudio.__version__); print(CUDA available:, torch.cuda.is_available()); print(AutoModel import OK)這些命令僅檢查依賴和導入不是模型下載或推理測試。判斷要點funasr.__file__應指向預期安裝位置檢查 PyPI 環境時請避開其他源碼工作區的導入遮蔽例如不要在環境變量中讓本地源碼目錄搶先于已安裝包被 import。導入成功或設備可用不代表某個模型已經在該設備上驗證通過教程場景建議顯式使用 CPU 起步。本源碼工作區出現注冊或導入失敗時可以這樣排查import funasr print(funasr.get_import_errors())或是在啟動 Python 前設置FUNASR_IMPORT_DEBUG1讓每個失敗的子模塊在導入時打印錯誤。機制上funasr/init.py 在包初始化時遞歸導入全部子模塊任何失敗都會被記錄到_IMPORT_ERRORSFUNASR_IMPORT_DEBUG1時即時打印如需快速失敗可設置FUNASR_STRICT_IMPORT1。當某個模型組件未注冊報錯時報錯信息會附帶已記錄的導入失敗清單見 funasr/auto/auto_model.py。其他可選模型的缺失依賴不一定影響當前模型。批量升級整個環境前請先閱讀常見問題。4. 模型、緩存與離線使用模型 ID 與 hub 選擇AutoModel接受模型 ID/別名或已有的本地模型目錄。默認hubms使用 ModelScopehubhf使用 Hugging Face。權重與 Python 包分開下載由 hub 客戶端管理緩存加載后可通過model.model_path查看實際目錄。請預留可寫磁盤空間并保留由配置、分詞器、前端資源與權重組成的完整目錄——缺少任何一部分都會導致加載失敗。離線使用三步走需要復現或斷網運行時準備在允許聯網的機器上準備精確模型快照和依賴記錄完整模型 ID、hub revision/commit、許可、軟件包版本和文件校驗和。VAD、標點、說話人模型也應分別準備。遷移傳輸完整目錄與依賴制品把所有模型別名替換為本地目錄把輸入 URL 替換為本地文件并檢查配置是否繼續引用遠程資源。驗證設置disable_updateTrue可跳過 FunASR 啟動版本檢查但它不是hub 客戶端、模型代碼或缺失資源的離線開關。應在禁用外連的環境中驗證準備結果。disable_update的底層行為見 funasr/auto/auto_model.pyAutoModel.__init__會調用check_for_update后者在未禁用時通過 PyPI JSON API 查詢最新版本并提示升級實現見 funasr/utils/version_checker.py。因此該開關只影響 FunASR 包自身的啟動版本檢查與模型權重下載無關。離線推理示例以下 Python 示例要求./models/paraformer-zh中已有完整、審查過的 Paraformer 兼容快照并準備本地./audio.wavfrom pathlib import Path from funasr import AutoModel model_dir Path(./models/paraformer-zh).resolve() audio Path(./audio.wav).resolve() assert model_dir.is_dir(), model_dir assert audio.is_file(), audio model AutoModel( modelstr(model_dir), devicecpu, disable_updateTrue, trust_remote_codeFalse, ) print(model.generate(inputstr(audio)))源碼限制HF 路徑的 revision 轉發差異一個值得注意的實現細節ModelScope 輔助函數會將model_revision傳給下載器但本工作區的 Hugging Face 輔助函數調用snapshot_download(model)沒有轉發 revision見 funasr/download/download_model_from_hub.py。因此不能依賴AutoModel(..., hubhf, model_revision...)鎖定 HF 版本正確做法是通過 hub 客戶端取得固定快照如huggingface_hub.snapshot_download指定 revision再傳入本地目錄。5. 信任與許可trust_remote_code默認保持False只有模型確實需要且代碼已經審查時才開啟。加載器在開啟信任后可能安裝模型的requirements.txtModelScope 路徑還可能導入配置的remote_code見 funasr/download/download_model_from_hub.py。本地目錄并不天然可信。使用獨立環境、審查過的制品和最小文件系統/網絡權限。不要把 hub 憑據寫進腳本、鏡像、日志或問題反饋使用 hub 客戶端支持的認證方式。FunASR 軟件采用 MIT 許可模型權重采用各自條款請查看精確模型卡和模型倉庫。只有模型卡采用時模型許可協議才適用。第三方模型保留各自來源與許可。6. 安裝完成后的下一步安裝與驗證完成后進入 第一次轉寫教程 完成首個推理示例。如果需要將模型封裝為服務或部署到生產環境可參考 Docker 與運行時鏡像若遇到導入失敗、依賴沖突等問題先查閱常見問題。倉庫中 tests/test_docs_funasr_install_commands.py 與 tests/test_learning_docs_contract.py 會持續校驗本文檔中的關鍵安裝標記sys.executable、funasr.__file__、pip check、disable_updateTrue、trust_remote_codeFalse、snapshot_download(model)等確保文檔與代碼行為保持一致可作為你驗證環境時的對照參考。【免費下載鏈接】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），僅供參考