FunASR GPU 环境 Docker 构建完整教程（基于 CUDA 11.8）

FunASR GPU环境Docker构建完整教程（基于CUDA 11.8）

一、教程目的

本文档详细介绍如何通过Docker构建支持GPU加速的FunASR环境，解决依赖版本兼容、国内源加速、模块缺失等问题，最终实现FunASR服务的正常启动与GPU验证。

二、环境准备

2.1 前提条件

• 操作系统：Ubuntu 22.04（推荐，与基础镜像版本一致）
• 硬件要求：NVIDIA显卡（支持CUDA 11.8，驱动版本≥520.61.05）
• 软件依赖：
  • Docker Engine（20.10+）
  • Docker Compose（2.10+）
  • NVIDIA Container Toolkit（用于Docker GPU透传）

2.2 前期检查

确保NVIDIA驱动与CUDA 11.8兼容：

nvidia-smi  # 输出中需包含 "CUDA Version: 11.8" 或更高兼容版本

确保Docker能识别GPU：

docker run --rm --gpus all nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu22.04 nvidia-smi

三、核心配置文件编写

3.1 Dockerfile配置（最终稳定版）

创建Dockerfile，按以下内容编写（关键步骤含注释说明）：

# 1. 基础镜像：CUDA 11.8 + CuDNN 8（自带CuDNN，无需额外安装，减少依赖冲突）
FROM nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu22.04# 2. 替换Ubuntu apt源为阿里云（加速系统依赖下载，解决官方源超时问题）
RUN sed -i s@/archive.ubuntu.com/@/mirrors.aliyun.com/@g /etc/apt/sources.list && \sed -i s@/security.ubuntu.com/@/mirrors.aliyun.com/@g /etc/apt/sources.list# 3. 安装基础工具（合并命令减少Docker分层，清理缓存减少镜像体积）
RUN apt-get update && apt-get install -y --no-install-recommends \python3 python3-pip ffmpeg  # ffmpeg为FunASR音频处理依赖 \&& ln -s /usr/bin/python3 /usr/bin/python  # 建立python软链接，统一命令 \&& rm -rf /var/lib/apt/lists/*  # 清理apt缓存 \# 4. 配置pip全局使用清华源（国内加速，避免官方源下载慢）&& pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple \&& pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn \# 5. 升级pip（解决旧版本pip安装依赖时的兼容性问题）&& pip install --upgrade pip --default-timeout=1000# 6. 安装GPU版PyTorch（版本2.1.0+cu118已验证：官方源存在+兼容CUDA 11.8+Python 3.10）
# --no-deps：禁用自动依赖，避免下载与CuDNN冲突的nvidia-cudnn-cu12
# -f：指定PyTorch官方CUDA 11.8源，确保版本存在
RUN pip install torch==2.1.0+cu118 torchvision==0.16.0+cu118 torchaudio==2.1.0+cu118 \--no-deps \-f https://download.pytorch.org/whl/cu118/torch_stable.html \--default-timeout=1000# 7. 创建FunASR模型目录并设置权限（避免运行时权限不足）
RUN mkdir -p /models && chmod -R 777 /models# 8. 暴露服务端口（需与Docker Compose配置一致，此处为FunASR默认端口示例）
EXPOSE 5102# 9. 设置工作目录+复制代码+安装项目依赖
WORKDIR /funAsr
COPY . .  # 将本地FunASR代码复制到容器内
# 安装项目依赖，延长超时时间应对大文件下载
RUN pip install -r requirements.txt --default-timeout=1000 -f https://download.pytorch.org/whl/cu118/torch_stable.html# 10. 启动FunASR服务（根据实际启动脚本调整，此处为app.py示例）
CMD ["python", "app.py"]

3.2 requirements.txt配置（最终稳定版）

创建requirements.txt，解决版本冲突、NumPy兼容、FunASR缺失问题：

# 音频处理依赖
ffmpeg_python
# Web服务依赖
Flask
Flask_Cors
flask_restx==1.3.0  # 指定版本避免兼容性问题
# 语音识别依赖（Whisper）
openai_whisper==20240930
# 网络请求依赖
Requests
# PyTorch系列（与Dockerfile版本严格一致！避免重复下载与冲突）
torch==2.1.0+cu118
torchvision==0.16.0+cu118
torchaudio==2.1.0+cu118
# Web服务依赖
Werkzeug
# FunASR核心依赖（ kaldifst用于语音特征处理）
kaldifst
# 异步服务依赖
gevent
# NumPy降级至1.x（解决旧模块编译兼容问题，避免"_ARRAY_API not found"警告）
numpy<2
# FunASR主依赖（关键！之前缺失导致ModuleNotFoundError）
funasr==1.0.4  # 指定稳定版本，参考官方推荐

四、镜像构建与容器验证

4.1 构建Docker镜像

# 1. 清理旧镜像与构建缓存（避免历史缓存干扰，首次构建可跳过）
docker rmi funasr:latest
docker builder prune -f# 2. 构建镜像（--no-cache：不使用缓存，确保依赖最新；-t：指定镜像名）
docker build --no-cache -t funasr:latest .

4.2 启动容器（以Docker Compose为例）

若使用docker-compose.yml（需与Dockerfile端口一致）：

version: "3.8"
services:funasr:image: funasr:latestcontainer_name: ai-funasrrestart: alwaysports:- "5102:5102"  # 端口映射：主机端口:容器端口volumes:- ./models:/models  # 模型目录挂载（可选，持久化模型）deploy:resources:reservations:devices:- driver: nvidiacount: all  # 使用所有GPUcapabilities: [gpu]  # 启用GPU能力

启动命令：

docker-compose up -d funasr

4.3 验证环境正确性

4.3.1 验证GPU是否可用

# 进入容器执行PyTorch GPU检测命令
docker exec -it ai-funasr python -c "import torch; print('GPU可用：', torch.cuda.is_available()); print('PyTorch版本：', torch.__version__); print('CUDA版本：', torch.version.cuda)"

预期输出（无警告且GPU可用）：

GPU可用： True
PyTorch版本： 2.1.0+cu118
CUDA版本： 11.8

4.3.2 验证FunASR依赖是否正常

# 验证funasr模块可导入
docker exec -it ai-funasr python -c "from funasr import AutoModel; print('FunASR导入成功')"

预期输出：

FunASR导入成功

4.3.3 查看服务日志（排查启动异常）

docker logs -f ai-funasr

若日志无ModuleNotFoundError、CUDA error等报错，且显示“Service started”等启动成功信息，则环境正常。

五、常见问题解决（FAQ）

5.1 问题1：PyTorch版本找不到（ERROR: No matching distribution）

错误现象

ERROR: Could not find a version that satisfies the requirement torch==2.2.1+cu118 (from versions: ...)

原因

• 指定的PyTorch版本（如2.2.1+cu118）在当前源中不存在；
• 源地址错误（如清华Anaconda源无cu118版本）。

解决方案

• 改用PyTorch官方CUDA 11.8源（-f https://download.pytorch.org/whl/cu118/torch_stable.html）；
• 选择已验证存在的版本（如torch==2.1.0+cu118），参考官方源查询结果。

5.2 问题2：requirements.txt与Dockerfile PyTorch版本不一致

错误现象

Dockerfile安装torch==2.1.0+cu118，但requirements.txt指定torch==2.2.1+cu118，导致构建失败。

原因

两处版本未统一，pip安装依赖时试图覆盖安装不存在的版本。

解决方案

• 确保requirements.txt中PyTorch系列版本与Dockerfile完全一致（如均为2.1.0+cu118）。

5.3 问题3：NumPy兼容警告（_ARRAY_API not found）

错误现象

A module that was compiled using NumPy 1.x cannot be run in NumPy 2.2.6...

原因

NumPy 2.x与旧模块（如PyTorch组件、kaldifst）编译不兼容。

解决方案

• 在requirements.txt中添加numpy<2，强制使用NumPy 1.x版本。

5.4 问题4：FunASR模块缺失（ModuleNotFoundError: No module named ‘funasr’）

错误现象

File "/funAsr/app.py", line 11, in <module> from funasr import AutoModel
ModuleNotFoundError: No module named 'funasr'

原因

requirements.txt中遗漏funasr依赖。

解决方案

• 在requirements.txt中添加funasr==1.0.4（或官方推荐版本）。

六、注意事项

6.1 NVIDIA容器许可协议

• 使用nvidia/cuda基础镜像即表示接受《NVIDIA Deep Learning Container License》；
• 许可详情可查看容器内文件：docker exec -it ai-funasr cat /NGC-DL-CONTAINER-LICENSE，或访问官方许可页面。

6.2 root用户运行风险

• 容器内默认以root用户运行pip，会提示警告：Running pip as the 'root' user can result in broken permissions；
• 建议：生产环境中在Dockerfile内创建普通用户（如RUN useradd -m funasr && su funasr），避免root权限风险。

6.3 国内源稳定性

• 清华PyPI源（https://pypi.tuna.tsinghua.edu.cn/simple）偶尔可能出现“网页解析失败”或“系统内部异常”；
• 备用方案：改用阿里云PyPI源（https://mirrors.aliyun.com/pypi/simple/），在Dockerfile中修改pip config set global.index-url即可。

6.4 版本兼容性优先

• 避免盲目追求新版本：PyTorch选择2.1.0+cu118、FunASR选择1.0.4均为“验证过兼容”的版本；
• 升级建议：若需升级版本，先通过curl -s https://download.pytorch.org/whl/cu118/torch_stable.html | grep "torch-.*cu118"确认版本存在，再修改配置。

6.5 构建缓存清理

• 每次修改Dockerfile或requirements.txt后，建议执行docker builder prune -f清理缓存；
• 避免旧缓存导致新配置不生效（如依赖未更新、版本未替换）。