Linux系统安装FunASR详细教程

系统环境要求

在开始安装FunASR之前，请确保你的Linux系统满足以下要求：

操作系统：Ubuntu 18.04+/CentOS 7+/Debian 10+（64位系统）
Python版本：3.8~3.12（推荐3.9版本）
内存：至少8GB（模型及依赖占用约20GB存储空间）
网络：需要联网下载安装包和模型文件

基础环境准备

更新系统软件包

首先更新系统软件包到最新版本，以确保依赖兼容性：

复制代码

# Ubuntu/Debian系统
sudo apt update && sudo apt upgrade -y

# CentOS/RHEL系统
sudo yum update -y && sudo yum upgrade -y

安装Python环境

如果系统中没有Python 3.8+环境，执行以下命令安装：

复制代码

# Ubuntu/Debian系统
sudo apt install -y python3 python3-pip python3-venv

# CentOS/RHEL系统
sudo yum install -y python3 python3-pip python3-venv

升级pip工具到最新版本：

复制代码

pip3 install --upgrade pip

创建虚拟环境（推荐）

为避免依赖冲突，建议使用Python虚拟环境：

复制代码

# 创建虚拟环境
python3 -m venv funasr_env

# 激活虚拟环境
source funasr_env/bin/activate

注意：后续所有操作都需要在激活的虚拟环境中进行。若要退出虚拟环境，执行deactivate命令。

安装FunASR核心组件

方式一：通过pip快速安装（推荐）

使用pip命令安装FunASR最新稳定版，国内用户建议使用清华镜像源加速：

复制代码

pip3 install -U funasr -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：从源码安装（适合开发调试）

如果需要修改源码或体验最新功能，可以从GitHub克隆源码安装：

复制代码

# 克隆源码仓库
git clone https://github.com/modelscope/FunASR.git && cd FunASR

# 以可编辑模式安装
pip3 install -e ./ -i https://pypi.tuna.tsinghua.edu.cn/simple

安装模型管理工具

若需要使用工业级预训练模型，需安装ModelScope和Hugging Face Hub：

复制代码

pip3 install -U modelscope huggingface_hub -i https://pypi.tuna.tsinghua.edu.cn/simple

安装必要依赖

安装PyTorch

根据系统是否有GPU选择对应的安装命令：

复制代码

# CPU版本（无GPU时使用）
pip3 install torch torchaudio -i https://pypi.tuna.tsinghua.edu.cn/simple

# GPU版本（需已安装CUDA，以CUDA 11.7为例）
pip3 install torch torchaudio --index-url https://download.pytorch.org/whl/cu117

安装音频处理依赖

FunASR需要ffmpeg处理音频文件，执行以下命令安装：

复制代码

# Ubuntu/Debian系统
sudo apt install -y ffmpeg

# CentOS/RHEL系统
sudo yum install -y ffmpeg

# 安装Python音频库
pip3 install soundfile librosa -i https://pypi.tuna.tsinghua.edu.cn/simple

验证安装

安装完成后，执行以下命令验证是否安装成功：

复制代码

# 下载测试音频文件
wget https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example.wav -O asr_example.wav

# 运行语音识别测试
python3 -c "from funasr import AutoModel; model = AutoModel(model='paraformer-zh'); result = model.generate(input='asr_example.wav'); print('识别结果:', result)"

首次运行会自动下载约600MB的预训练模型，耐心等待下载完成后，若输出类似以下结果，则表示安装成功：

复制代码

识别结果: [{'text': '欢迎使用阿里巴巴达摩院开源的语音识别工具包FunASR'}]

部署WebSocket服务（可选）

若需要搭建语音识别服务供其他程序调用，可部署WebSocket服务：

安装WebSocket依赖

复制代码

pip3 install websockets==10.4 -i https://pypi.tuna.tsinghua.edu.cn/simple

获取服务脚本

复制代码

# 克隆源码仓库（已克隆可跳过）
git clone https://github.com/modelscope/FunASR.git && cd FunASR

# 进入WebSocket服务目录
cd runtime/python/websocket

启动服务端

复制代码

# 关闭SSL验证（测试环境使用）
python3 funasr_wss_server.py --certfile 0

服务启动成功后，会监听本地10095端口，可通过lsof -i:10095命令验证端口是否正常监听。

Docker容器化部署（适合生产环境）

对于企业级应用，推荐使用Docker容器化部署，确保环境一致性：

安装Docker

复制代码

# 下载安装脚本
curl -O https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/shell/install_docker.sh

# 执行安装
sudo bash install_docker.sh

拉取FunASR镜像

复制代码

sudo docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-cpu-0.4.6

创建模型目录并启动容器

复制代码

# 创建模型存储目录
mkdir -p ./funasr-runtime-resources/models

# 启动容器，映射10095端口和模型目录
sudo docker run -p 10095:10095 -it --privileged=true \
  -v $PWD/funasr-runtime-resources/models:/workspace/models \
  registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-cpu-0.4.6

在容器内启动服务

容器启动后会自动进入交互模式，执行以下命令启动服务：

复制代码

cd FunASR/runtime

nohup bash run_server.sh \
  --certfile 0 \
  --download-model-dir /workspace/models \
  --vad-dir damo/speech_fsmn_vad_zh-cn-16k-common-onnx \
  --model-dir damo/speech_paraformer-large-vad-punc_asr_nat-zh-cn-16k-common-vocab8404-onnx \
  --punc-dir damo/punc_ct-transformer_cn-en-common-vocab471067-large-onnx \
  --lm-dir damo/speech_ngram_lm_zh-cn-ai-wesp-fst \
  --itn-dir thuduj12/fst_itn_zh > log.txt 2>&1 &

查看服务启动日志：

复制代码

tail -f log.txt

当日志中出现"模型初始化成功"字样时，表示服务已正常启动。

常见问题解决

依赖安装失败

若安装过程中出现依赖冲突，尝试指定具体版本安装：

复制代码

# 例如指定torch版本
pip3 install torch==1.13.1 torchaudio==0.13.1 -i https://pypi.tuna.tsinghua.edu.cn/simple

模型下载缓慢或失败

可手动从ModelScope下载模型，地址：https://modelscope.cn/models?page=1\&tasks=automatic-speech-recognition\&type=audio

下载后解压到指定目录，使用时通过model参数指定本地路径：

复制代码

from funasr import AutoModel
model = AutoModel(model="/path/to/local/model")

权限问题

若出现权限错误，避免使用sudo（会导致虚拟环境失效），建议调整目录权限：

复制代码

chmod -R 755 ~/funasr_env

FunASR官方网站：https://www.funasr.com/
GitHub仓库：https://github.com/modelscope/FunASR