FunASR 是阿里巴巴达摩院与中科院自动化所联合开源的工业级语音识别工具包，集成了自动语音识别（ASR）、语音活动检测（VAD）、标点恢复、说话人验证、说话人日志、情感与事件检测等多重功能。它支持从嵌入式设备到云服务器的全场景部署，并提供 OpenAI 兼容的 API 服务。本文将系统介绍 FunASR 的部署与调用方法，涵盖多种部署路径、技术架构、性能优化和实用技巧。

一、核心优势

本地部署的三大价值：

• 数据隐私可控：所有语音数据在本地处理，避免上传至第三方服务器，符合 GDPR 等隐私法规，适合医疗、金融等对数据安全敏感的行业。
• 响应延迟更低：无需网络传输，实时识别延迟可控制在 200ms 以内，适合直播、会议等实时场景。
• 成本可控：一次性部署后，长期使用无需支付云端调用费用。

技术特性：

• 提供 gRPC/WebSocket 双协议接口，支持动态模型加载与多实例并发。
• 通过 Kubernetes 部署时，单节点可承载 200+ 并发连接，资源利用率提升 40%。
• 支持流式处理、多模型架构兼容及低资源环境部署。

技术架构：
FunASR 采用分层架构设计，包含以下核心模块：

• 声学前端模块：集成 WebRTC 降噪、VAD（语音活动检测）及特征提取（FBANK/MFCC）功能，支持实时音频流处理。在 60dB 信噪比环境下，语音增强模块可使 WER（词错率）降低 12%-15%。
• 声学模型层：提供 Conformer、Transformer 等主流架构，支持 CTC（连接时序分类）与 Attention 联合解码，平衡识别速度与准确率。
• 语言模型层：内置 N-gram 统计语言模型及神经语言模型（如 Transformer-XL），支持动态热词注入与领域适配。
• 服务接口层：提供 gRPC/RESTful API 及 WebSocket 流式接口，兼容多平台调用。

二、环境准备

2.1 系统要求

项目	最低配置	推荐配置
操作系统	Linux（Ubuntu 20.04+）或 Windows 10/11（WSL2）	Ubuntu 20.04+
CPU	4 核以上（支持 AVX2 指令集）	8 核以上
内存	8GB（CPU 部署）/ 12GB（GPU 部署）	16GB+
硬盘空间	20GB	50GB+
GPU（可选）	NVIDIA 显卡，CUDA 11.x+，显存 8GB+	16GB+ 显存
Python	3.8+	3.8+

2.2 依赖安装

创建虚拟环境：

conda create -n funasr_env python=3.8
conda activate funasr_env

安装核心依赖：

# 安装 PyTorch（GPU 版本，根据 CUDA 版本选择对应索引）
pip install torch torchaudio torchvision --extra-index-url https://download.pytorch.org/whl/cu118

# 安装 FunASR
pip install funasr

# 系统依赖（Linux）
sudo apt update
sudo apt install -y python3-pip python3-dev libsndfile1 ffmpeg

验证 GPU 可用性：

import torch
print(torch.cuda.is_available())  # True 表示 GPU 可用

三、模型选择

FunASR 提供多种预训练模型，按需选择：

模型	参数量	特点	适用场景
Fun-ASR-Nano-2512	8亿	端到端 ASR，内置标点和时间戳，支持中（7 种方言/26 种口音）+英+日	旗舰模型，推荐首选，需 GPU
Fun-ASR-MLT-Nano-2512	—	支持 31 种语言	多语言场景
SenseVoiceSmall	2.34亿	多任务 ASR，含语言/情绪/事件检测，支持中/英/日/韩/粤	轻量级、多语言
Paraformer	—	经典非自回归模型，AISHELL-1 数据集 CER 为 4.72%	高效批处理
Whisper 系列	—	多语言支持，通过 FunASR 训练框架微调	多语言通用场景

四、部署方式

方式一：Python SDK（最快速）

安装与初始化：

from funasr import AutoModel

# 加载 Fun-ASR-Nano 模型（旗舰推荐）
model = AutoModel(
    model="FunAudioLLM/Fun-ASR-Nano-2512", 
    device="cuda"  # 或 "cpu"
)

单文件推理：

# 支持本地文件路径或网络 URL
result = model.generate(
    input="https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_zh.wav"
)
print(result[0]["text"])  
# 输出：欢迎大家来体验达摩院推出的语音识别模型。

使用 SenseVoiceSmall：

from funasr import AutoModel

model = AutoModel(model="iic/SenseVoiceSmall", device="cuda")
result = model.generate(input="audio.wav")
# 输出包含 <|zh|><|NEUTRAL|><|Speech|> 等标签

方式二：一键部署服务器（零配置）

funasr-server 提供自包含的一键安装方案，无需预装 Python、PyTorch 等依赖：

pip install funasr-server

from funasr_server import FunASR

asr = FunASR()
asr.ensure_installed()  # 一次性安装，约2分钟
asr.start()

# 加载模型
model = asr.load_model("SenseVoiceSmall")

# 推理
result = model("audio.wav")
print(result)  # [{"key": "audio", "text": "<|zh|>...欢迎大家来体验..."}]

model.unload()
asr.stop()

Context Manager 用法：

with FunASR() as asr:
    model = asr.load_model("SenseVoiceSmall")
    result = model("audio.wav")

方式三：API 服务部署

启动 API 服务（一行命令）：

funasr-server --device cuda
# 服务启动于 localhost:8000，提供 OpenAI 兼容接口

Flask 轻量级 API（自定义部署）：

from flask import Flask, request, jsonify
from funasr import AutoModel

app = Flask(__name__)
model = AutoModel(model="FunAudioLLM/Fun-ASR-Nano-2512", device="cuda")

@app.route('/asr', methods=['POST'])
def asr():
    if 'file' not in request.files:
        return jsonify({"error": "No audio file"}), 400
    file = request.files['file']
    audio_path = "./temp.wav"
    file.save(audio_path)
    result = model.generate(input=audio_path)
    return jsonify({"text": result[0]["text"]})

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

RESTful API 端点设计：

接口路径	方法	参数	返回值
/asr/stream	POST	audio: base64 编码的音频数据	text: 识别结果字符串
/asr/batch	POST	file_url: 音频文件 HTTP 地址	批量识别结果

方式四：Docker 部署

All-in-One Docker 镜像（模型已预下载，开箱即用）：

docker run -d \
    --name fun-asr \
    --gpus '"device=0"' \
    -p 8189:8189 \
    --restart unless-stopped \
    neosun/fun-asr:v1.3.1

服务启动约 30 秒，打开 http://localhost:8189 即可使用 Web UI。

Docker Compose 部署：

services:
  fun-asr:
    image: neosun/fun-asr:v1.3.1
    container_name: fun-asr
    restart: unless-stopped
    ports:
      - "8189:8189"
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              device_ids: ["0"]
              capabilities: [gpu]

健康检查：

curl http://localhost:8189/health
# {"status":"healthy","model_loaded":true,"vad_loaded":true,"gpu":{...}}

官方 FunASR 镜像：

# GPU 版本
docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-gpu-0.1.1

# CPU 版本
docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.13

方式五：WebSocket 服务（实时流式识别）

适用于需要低延迟实时转录的场景：

# 启动 WebSocket 服务（监听 0.0.0.0:10095）
./start_server.sh

WebSocket 通信流程：

1. 连接地址：ws://<SERVER_IP>:10095
2. 握手配置（第一帧 JSON）：

{
  "mode": "2pass",              // 推荐 2pass（流式+离线修正）
  "chunk_size": [5, 10, 5],    // 分块大小 [编码器历史, 当前块, 编码器未来]
  "chunk_interval": 10,         // 发送间隔 (ms)
  "audio_fs": 16000,            // 采样率（必须 16000）
  "wav_name": "demo",
  "is_speaking": true,
  "hotwords": "{\"阿里巴巴\": 20, \"达摩院\": 30}",  // 热词配置
  "itn": true                   // 逆文本标准化（数字转汉字等）
}

3. 音频流传输 → 结果接收

Docker WebSocket 服务部署：

docker run -d \
    --name=fun-asr-nano \
    --restart=unless-stopped \
    -p 10096:10096 \
    -e PYTHONUNBUFFERED=1 \
    --gpus=all \
    wangshengjj/fun-asr-nano-2512:latest

方式六：vLLM 高性能推理（极致加速）

vLLM 引擎可将推理速度提升 16–340 倍，同时保持字符错误率（CER）与 PyTorch 完全一致（delta < 0.2%）。

性能基准测试（184 个文件，共 11,541 秒）：

模型	引擎	RTFx	CER
Fun-ASR-Nano	PyTorch（基线）	21	8.06%
Fun-ASR-Nano	vLLM batch	340	8.20%
Fun-ASR-Nano	Offline service（无 SPK）	102	8.14%
GLM-ASR-Nano	vLLM batch	265	12.93%

安装（重要：让 vLLM 管理 PyTorch 版本）：

# 1) 先安装 vLLM（根据驱动 CUDA 版本选择）
# 驱动 CUDA 12.x -> pip install vllm==0.19.1
# 驱动 CUDA >= 13 -> pip install vllm（最新）
pip install "vllm==0.19.1"

# 2) 再安装 FunASR
pip install "funasr>=1.3.0"
cd /path/to/FunASR && pip install -e .
pip install safetensors tiktoken websockets regex

⚠️ 重要：不要手动安装 torch/torchaudio——vLLM 会自带匹配的三件套（torch ↔ torchaudio ↔ torchvision 必须版本一致）。手动安装可能导致 CUDA 版本不匹配而失败。

硬件要求：GPU ≥ 8GB 显存，CUDA ≥ 11.8，推荐 16GB+。

架构说明：FunASR 的 vLLM 集成将 ASR 模型拆分为两个独立运行的组件：

• PyTorch 部分（单 GPU）：音频前端 → 音频编码器 → Adaptor → 音频 Embeddings
• vLLM 引擎：PagedAttention + Continuous Batching + KV Cache 管理 + CUDA Graph + Tensor Parallel（多 GPU）→ Qwen3-0.6B / Llama-2B LLM 解码

离线批处理推理：

from funasr.auto.auto_model_vllm import AutoModelVLLM

model = AutoModelVLLM(
    model="FunAudioLLM/Fun-ASR-Nano-2512",
    hub="ms",  # 或 "hf"
    tensor_parallel_size=2,
    gpu_memory_utilization=0.8,
)
results = model.generate(
    ["audio1.wav", "audio2.wav"],
    language="中文",
    hotwords=["张三", "北京"],
)
for item in results:
    print(f"[{item['key']}] {item['text']}")

命令行批处理：

# 单文件
python demo_vllm.py --input audio.wav --language 中文

# 批量 + 多 GPU Tensor Parallel
python demo_vllm.py --input wav.scp --tensor-parallel-size 4 --batch-size 32

# 热词 + JSONL 输出
python demo_vllm.py --input audio.wav --hotwords 张三 北京 --output results.jsonl

注意：首次运行时，FunASR 会从 model.pt 提取 LLM 权重到 vLLM 兼容目录（如 Qwen3-0.6B-vllm），后续启动会复用已准备好的权重。

五、API 调用参考

REST API 端点

端点	方法	说明
/asr/file	POST	文件批量识别
/asr/stream	POST	流式语音识别
/v1/audio/transcriptions	POST	OpenAI 兼容接口（Whisper API 兼容）

请求示例（Python requests）

import requests

url = "http://localhost:8000/asr/stream"
headers = {"Content-Type": "audio/wav"}
audio_data = open("test.wav", "rb").read()

response = requests.post(url, headers=headers, data=audio_data, stream=True)
for chunk in response.iter_content(chunk_size=1024):
    if chunk:
        print(chunk.decode("utf-8"))  # 实时输出识别结果

双向流式调用（Python SDK）

可直接对音频流进行识别，并实时输出结果。音频流可以来自外部设备（如麦克风）或从本地文件读取，适合需要即时反馈的场景。

高级参数

参数	类型	默认值	说明
language	string	zh	语言（zh/en/multi）
use_itn	bool	False	启用逆文本正则化（添加标点）
hotwords	dict	{}	动态热词，提高特定词汇识别准确率
chunk_size	list	[5,10,5]	流式分块大小

六、性能优化技巧

优化方式	说明
vLLM 引擎	16–340 倍速度提升，适合高吞吐场景
ONNX Runtime	导出 ONNX 模型，在 Intel CPU 上实现加速
批处理推理	多段音频合并为批次处理，减少 GPU 空闲时间
模型量化（INT8）	使用 torch.quantization 进行 INT8 量化，模型体积缩小 4 倍
流式解码优化	调整 chunk_size 与 cache_size 比例（建议 2:1）
TensorRT 加速	启用 TensorRT 进一步加速
Kubernetes 弹性扩容	通过 Docker 容器化 + K8s 实现弹性扩容
GPU 内存优化	vLLM 的 PagedAttention 高效管理显存，支持更大 batch size

七、常见问题与故障排除

7.1 显存与部署限制

1. 显存占用：Fun-ASR-Nano-2512 在 NVIDIA 3090 上启动约占用 2.6GB 显存，有请求时升至 3.9GB。官方暂不支持 FP16 部署。
2. FP16 兼容性：FP16 模式目前在部分环境下存在兼容性问题，暂不推荐开启。

7.2 模型组合限制

• SenseVoiceSmall 可与 VAD 模型（vad_model="fsmn-vad"）组合处理长音频，但不要与标点模型（punc_model="ct-punc"）组合，否则会破坏输出中的特殊标签。

7.3 模型加载问题

1. 模型加载缓慢：如果在 macOS 上遇到 SSL 兼容性警告导致模型加载变慢，可通过相关命令修复。
2. 离线模型加载失败：检查模型文件路径是否正确，网络是否通畅。
3. 禁用自动更新：可设置 disable_update=True 在 AutoModel 中禁用自动更新检查。

7.4 音频与编码问题

1. 本地音频读取报错：确认 funasr 版本为最新，工具包自带 ffmpeg。
2. 输出乱码：检查输入数据和输出结果的编码格式，确保为 UTF-8；验证返回结果的格式，正确解析 JSON 或二进制数据。
3. 推理结果为空：检查数据分布是否匹配、模型配置是否正确、依赖包版本是否与官方文档一致（如 funasr==1.0.22）。

7.5 Windows 部署

建议通过 WSL2 或 Docker 容器化部署。在 Win10 系统可通过 WSL 2 或 Docker 容器化技术实现高效本地部署。

7.6 CUDA 版本匹配

• 驱动 CUDA vs 运行时 CUDA：安装 vLLM 时，需根据 nvidia-smi 显示的驱动 CUDA 版本选择，而非运行时 CUDA。
• 驱动 CUDA 12.x → pip install vllm==0.19.1（自带 torch 2.10 / cu128）
• 驱动 CUDA >= 13 → pip install vllm（最新，自带 torch 2.11 / cu130）
• 如遇 “The NVIDIA driver on your system is too old” 错误，安装匹配驱动 CUDA 版本的 vLLM，或更新 NVIDIA 驱动。

八、模型训练与微调（进阶）

FunASR 训练框架支持：

• 在自定义领域数据上微调任意预训练模型
• 基于 PyTorch DDP 的多 GPU 训练（单机/多机）
• DeepSpeed ZeRO Stage 1/2/3 大模型训练

快速开始微调：

git clone https://github.com/FunAudioLLM/Fun-ASR.git
cd Fun-ASR
pip install -e .

Whisper 微调示例：

python -m funasr.bin.train \
    --model_name whisper-tiny \
    --train_data /path/to/train_data \
    --eval_data /path/to/eval_data

九、快速体验

建议先通过 Colab Quickstart 快速体验，无需本地配置即可在浏览器中转录公开样本或上传自己的音频。