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），仅供参考