Fun-ASR-MLT-Nano-2512部署教程：Linux环境详细配置步骤

1. 学习目标与前置知识

1.1 教程定位

本文是一篇从零开始的完整部署指南，旨在帮助开发者在Linux系统中成功部署Fun-ASR-MLT-Nano-2512多语言语音识别模型。该模型由阿里通义实验室推出，支持31种语言的高精度识别，适用于跨语种语音转录、远场识别、方言处理等场景。

本教程覆盖：

环境准备
依赖安装
模型加载与修复
Web服务启动
API调用方式
Docker容器化部署
常见问题排查

完成本教程后，您将能够：

在本地或服务器上运行 Fun-ASR-MLT-Nano-2512 的 Web 服务
使用 Python 脚本调用模型进行语音识别
构建并运行 Docker 镜像实现快速迁移
掌握关键 Bug 修复和性能优化技巧

1.2 前置条件

为确保顺利执行本教程，请确认以下基础环境已具备：

操作系统：Ubuntu 20.04 或更高版本（推荐使用 LTS 版本）
Python 版本：3.8 ~ 3.11（建议使用 3.10）
硬件资源：
- 内存 ≥ 8GB
- 磁盘空间 ≥ 5GB（含模型文件）
- GPU（可选，但强烈推荐用于加速推理）
网络连接：需能访问 Hugging Face 或 GitHub 下载模型权重

提示：若无 GPU，也可使用 CPU 进行推理，但首次加载时间较长，且单次推理延迟较高（约 2~3 倍于 GPU）。

2. 环境搭建与依赖安装

2.1 创建独立虚拟环境

为避免依赖冲突，建议使用venv创建隔离的 Python 环境：

python3 -m venv funasr-env source funasr-env/bin/activate

激活后可通过which python和which pip验证是否指向虚拟环境路径。

2.2 安装系统级依赖

Fun-ASR 依赖ffmpeg处理音频格式转换，需提前安装：

sudo apt update sudo apt install -y ffmpeg

验证安装是否成功：

ffmpeg -version

输出应包含版本信息及编译支持项。

2.3 安装 Python 依赖包

进入项目目录后，执行依赖安装命令：

pip install --upgrade pip pip install -r requirements.txt

常见依赖包括：

torch（PyTorch 深度学习框架）
gradio（Web 可视化界面）
transformers（模型加载工具）
soundfile,librosa（音频处理）
tiktoken（多语言分词器）

注意：如使用 GPU，请确保已正确安装 CUDA 驱动，并通过nvidia-smi查看显卡状态。PyTorch 将自动检测可用设备。

3. 项目结构解析与核心修复

3.1 项目目录说明

Fun-ASR-MLT-Nano-2512 的标准项目结构如下：

Fun-ASR-MLT-Nano-2512/ ├── model.pt # 模型权重文件（约 2.0GB） ├── model.py # 主模型定义脚本（含关键逻辑） ├── ctc.py # CTC 解码模块 ├── app.py # Gradio Web 应用入口 ├── config.yaml # 模型配置参数 ├── configuration.json # 模型元信息（HuggingFace 兼容） ├── multilingual.tiktoken # 多语言 BPE 分词表 ├── requirements.txt # Python 依赖清单 └── example/ # 示例音频集合 ├── zh.mp3 # 中文语音示例 ├── en.mp3 # 英文语音示例 ├── ja.mp3 # 日文语音示例 ├── ko.mp3 # 韩文语音示例 └── yue.mp3 # 粤语语音示例

其中model.pt是预训练权重，首次运行时会自动加载至内存。

3.2 关键 Bug 修复：data_src 初始化异常

在原始model.py第 368–406 行存在一个潜在错误，可能导致推理中断：

❌ 问题代码片段（修复前）

try: data_src = load_audio_text_image_video(...) except Exception as e: logging.error(f"Failed to load input: {e}") # 此处未捕获异常即继续执行，data_src 可能未定义 speech, speech_lengths = extract_fbank(data_src, ...)

当音频加载失败时，data_src未被赋值，后续调用extract_fbank将抛出NameError。

✅ 修复方案（推荐写法）

将数据提取逻辑移入try块内，确保变量作用域安全：

try: data_src = load_audio_text_image_video(input_path) speech, speech_lengths = extract_fbank(data_src, sample_rate=16000, mean_norm=True) except Exception as e: logging.error(f"Feature extraction failed: {e}") continue # 跳过当前样本，防止程序崩溃

此修改保证了异常情况下流程可控，提升服务稳定性。

建议：在生产环境中添加重试机制或默认静音填充策略以进一步增强鲁棒性。

4. 启动 Web 服务与交互使用

4.1 启动 Gradio Web 界面

切换到项目根目录并启动服务：

cd /root/Fun-ASR-MLT-Nano-2512 nohup python app.py > /tmp/funasr_web.log 2>&1 & echo $! > /tmp/funasr_web.pid

命令解释：

nohup：允许进程在终端关闭后继续运行
> /tmp/funasr_web.log：重定向标准输出日志
2>&1：合并错误流与输出流
&：后台运行
echo $! > pid：保存进程 ID 便于后续管理

4.2 访问 Web 界面

打开浏览器访问：

http://<your-server-ip>:7860

初始页面加载可能需要30–60 秒，因模型采用懒加载机制（Lazy Load），首次请求才会完成初始化。

使用步骤：

点击“上传音频”按钮，选择.mp3、.wav等支持格式
（可选）手动指定语言（如“中文”、“英文”）
勾选“ITN”选项启用文本正规化（如数字转写）
点击“开始识别”
查看识别结果与时间戳（如有）

提示：可直接使用example/目录下的测试音频验证功能完整性。

5. Python API 调用方式

除了 Web 界面，还可通过编程接口集成到自有系统中。

5.1 加载模型实例

from funasr import AutoModel # 初始化模型 model = AutoModel( model=".", # 当前目录下查找模型 trust_remote_code=True, # 允许加载自定义代码 device="cuda:0" # 自动选择 GPU；若无则 fallback 到 cpu )

参数说明：

trust_remote_code=True：必须开启，否则无法加载model.py中的自定义类
device支持"cpu"、"cuda:0"、"mps"（Mac M系列芯片）

5.2 执行语音识别

res = model.generate( input=["example/zh.mp3"], # 输入音频路径列表 cache={}, # 缓存上下文（可用于长语音分段） batch_size=1, # 批处理大小（GPU 显存足够可设为 2+） language="中文", # 指定语言提升准确率 itn=True # 启用智能文本归一化 ) # 输出结果 print(res[0]["text"]) # 如："今天天气真不错"

返回值为字典列表，包含：

text：识别文本
timestamp：可选的时间对齐信息
lang：检测到的语言类型

最佳实践：对于批量任务，建议设置合理的batch_size并启用pin_memory=True提升数据传输效率。

6. Docker 容器化部署

为实现环境一致性与快速部署，推荐使用 Docker 方式打包应用。

6.1 编写 Dockerfile

FROM python:3.11-slim WORKDIR /app # 安装系统依赖 RUN apt-get update && apt-get install -y \ ffmpeg \ git \ wget \ && rm -rf /var/lib/apt/lists/* # 设置 Python 环境变量 ENV PYTHONDONTWRITEBYTECODE=1 ENV PYTHONUNBUFFERED=1 # 复制依赖文件并安装 COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt # 复制项目代码 COPY . . # 暴露服务端口 EXPOSE 7860 # 启动命令 CMD ["python", "app.py"]

6.2 构建与运行容器

# 构建镜像 docker build -t funasr-nano:latest . # 运行容器（CPU 模式） docker run -d -p 7860:7860 --name funasr funasr-nano:latest # 运行容器（GPU 模式，需 nvidia-docker 支持） docker run -d -p 7860:7860 --gpus all --name funasr funasr-nano:latest

访问http://localhost:7860即可看到 Web 界面。

优势：Docker 部署可实现“一次构建，处处运行”，特别适合边缘设备或多节点集群部署。

7. 性能表现与服务管理

7.1 推理性能指标

指标	数值
模型体积	2.0 GB
参数量	800M
GPU 显存占用（FP16）	~4GB
推理速度（GPU）	~0.7s / 10s 音频
识别准确率（远场噪声）	93%
支持语言数	31 种

说明：在 NVIDIA T4 或 A10 GPU 上实测，CPU 模式下延迟约为 2.0s / 10s 音频。

7.2 服务管理命令

常用运维操作汇总：

# 查看服务进程 ps aux | grep "python app.py" # 实时查看日志 tail -f /tmp/funasr_web.log # 停止服务 kill $(cat /tmp/funasr_web.pid) # 重启服务（一键脚本） kill $(cat /tmp/funasr_web.pid) && \ nohup python app.py > /tmp/funasr_web.log 2>&1 & && \ echo $! > /tmp/funasr_web.pid

建议将重启命令封装为 shell 脚本（如restart.sh），便于日常维护。