FunASR Python SDK 安装完全指南：从环境创建到离线推理

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/macOS：

python3.11 -m venv .venv . .venv/bin/activate python -m pip install --upgrade pip

• Windows PowerShell：

py -3.11 -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install --upgrade pip

也可以使用已有的 Conda 环境。若使用 Conda，Apple Silicon 上应选用架构一致的 arm64 解释器和 wheel，不要将 x86_64 Conda 环境与 arm64 包混用。

关于版本兼容性，可以从仓库元数据获得两点依据：

• setup.py 声明了python_requires=">=3.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依赖组），不需要再按"可选步骤"安装。模型专属依赖仍需单独处理。两个实用 extras：

标准入门示例不需要这两个 extras。添加 extra 前请查看 setup.py 和所选模型指南，避免在同一环境中混装互不兼容的模型依赖。此外trainextra 提供训练专用模块，llmextra 提供大模型类 ASR（Qwen 系列等）所需依赖，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_DEBUG=1，让每个失败的子模块在导入时打印错误。机制上，funasr/init.py 在包初始化时递归导入全部子模块，任何失败都会被记录到_IMPORT_ERRORS，FUNASR_IMPORT_DEBUG=1时即时打印；如需快速失败可设置FUNASR_STRICT_IMPORT=1。当某个模型组件"未注册"报错时，报错信息会附带已记录的导入失败清单（见 funasr/auto/auto_model.py）。其他可选模型的缺失依赖不一定影响当前模型。批量升级整个环境前，请先阅读常见问题。

4. 模型、缓存与离线使用

模型 ID 与 hub 选择

AutoModel接受模型 ID/别名或已有的本地模型目录。默认hub="ms"使用 ModelScope，hub="hf"使用 Hugging Face。权重与 Python 包分开下载，由 hub 客户端管理缓存；加载后可通过model.model_path查看实际目录。请预留可写磁盘空间，并保留由配置、分词器、前端资源与权重组成的完整目录——缺少任何一部分都会导致加载失败。

离线使用三步走

需要复现或断网运行时：

1. 准备：在允许联网的机器上准备精确模型快照和依赖，记录完整模型 ID、hub revision/commit、许可、软件包版本和文件校验和。VAD、标点、说话人模型也应分别准备。
2. 迁移：传输完整目录与依赖制品，把所有模型别名替换为本地目录，把输入 URL 替换为本地文件，并检查配置是否继续引用远程资源。
3. 验证：设置disable_update=True可跳过 FunASR 启动版本检查，但它不是hub 客户端、模型代码或缺失资源的离线开关。应在禁用外连的环境中验证准备结果。

disable_update的底层行为见 funasr/auto/auto_model.py：AutoModel.__init__会调用check_for_update，后者在未禁用时通过 PyPI JSON API 查询最新版本并提示升级（实现见 funasr/utils/version_checker.py）。因此该开关只影响 FunASR 包自身的启动版本检查，与模型权重下载无关。

离线推理示例

以下 Python 示例要求./models/paraformer-zh中已有完整、审查过的 Paraformer 兼容快照，并准备本地./audio.wav：

from 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( model=str(model_dir), device="cpu", disable_update=True, trust_remote_code=False, ) print(model.generate(input=str(audio)))

源码限制：HF 路径的 revision 转发差异

一个值得注意的实现细节：ModelScope 辅助函数会将model_revision传给下载器，但本工作区的 Hugging Face 辅助函数调用snapshot_download(model)，没有转发 revision（见 funasr/download/download_model_from_hub.py）。因此：

• 不能依赖AutoModel(..., hub="hf", model_revision=...)锁定 HF 版本；
• 正确做法是通过 hub 客户端取得固定快照（如huggingface_hub.snapshot_download指定 revision），再传入本地目录。

5. 信任与许可

• trust_remote_code默认保持False，只有模型确实需要且代码已经审查时才开启。加载器在开启信任后可能安装模型的requirements.txt，ModelScope 路径还可能导入配置的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_update=True、trust_remote_code=False、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