一、讲解

Qwen3-ASR是阿里通义千问团队开源的语音识别模型系列，支持52种语言和方言的识别、自动语言检测、字/词级时间戳对齐，以及流式/离线两种推理模式。生产级部署方案采用All-in-One Docker镜像，将Qwen3-ASR（1.7B/0.6B）和强制对齐模型Qwen3-ForcedAligner-0.6B打包在一起，实现“运行时零下载”。

核心能力

能力	说明
多语言识别	30种语言 + 22种中文方言，支持自动语言检测
强制对齐时间戳	基于Qwen3-ForcedAligner-0.6B，输出字/词级时间戳，支持11种语言
流式转录	WebSocket实时返回识别结果
双模型选择	1.7B（最高精度）和0.6B（快速高效）

模型架构

Qwen3-ASR采用编码器-解码器架构：

• 音频编码器：将音频转换为Mel频谱图（128 bins）→ Conv2d卷积（8倍下采样）→ 24层Transformer编码器 → 音频特征
• 文本解码器：音频特征注入到文本embedding序列的<|audio_pad|>占位符位置，由28层Qwen3风格解码器（含MRoPE）自回归生成转录文本
• 强制对齐器：独立的0.6B模型，提供字/词级时间戳

MRoPE是Qwen3-ASR的核心位置编码技术，采用交错式（而非分块式）频率分配，分三段[24, 20, 20]对应时间/高度/宽度维度。这一设计对长音频的语义连贯性至关重要。

GPU智能管理

生产级部署方案内置GPU资源管理机制：

• 懒加载：模型在首次API请求时才加载到显存
• 自动卸载：持续空闲（默认600秒）后自动从显存卸载
• 手动释放：支持通过/api/gpu-offload接口主动释放显存
• 模型切换：切换模型时自动释放旧模型再加载新模型

对于长期运行的服务，建议配置systemd进行进程守护，实现崩溃自动恢复和资源隔离。

量化与加速（可选优化）

生产环境可根据GPU型号和性能需求，选择以下加速方案：

优化方式	适用场景	效果
INT8量化（bitsandbytes）	通用GPU	~50%显存降低
FP8量化（torchao）	sm_89+（Hopper/Ada Lovelace）	更高吞吐量
Flash Attention 2	支持架构	注意力计算加速
CUDA Graphs	长时运行服务	内核缓存预热
推测解码	0.6B草稿 + 1.7B验证	解码加速

高可用架构设计

生产级部署建议采用网关+Worker模式：

• 网关进程：接收请求、负载均衡、优先级调度
• Worker进程：执行实际推理，独立回收内存/显存
• 优先级队列：WebSocket实时请求优先于HTTP批量任务
• X-Request-ID链路追踪：贯穿网关→Worker→服务器，便于日志关联和问题排查

---

二、安装

前置条件

• NVIDIA GPU（需安装nvidia-docker）
• CUDA 12.x
• Docker及nvidia-container-toolkit已配置
• 约5.8GB磁盘空间用于模型权重（1.7B约3.4GB + 0.6B约1.2GB + 对齐器约1.2GB）

方式一：Docker一键部署（推荐生产级）

直接拉取并启动All-in-One镜像：

docker run -d --gpus '"device=2"' --name qwen3-asr \
  -p 8250:8200 -p 8251:8201 \
  --restart unless-stopped \
  neosun/qwen3-asr:latest

参数说明：

• --gpus '"device=2"'：指定GPU设备ID，可根据实际情况修改
• -p 8250:8200：映射Web UI和REST API端口
• -p 8251:8201：映射MCP服务端口
• --restart unless-stopped：进程崩溃后自动重启

启动后访问：

• Web UI：http://localhost:8250
• API文档：http://localhost:8250/docs

方式二：Docker Compose（推荐用于定制化配置）

git clone https://github.com/neosun100/Qwen3-ASR.git
cd Qwen3-ASR
bash start.sh  # 自动选择最空闲的GPU

start.sh会通过nvidia-smi查询各GPU的显存使用情况，自动选择最空闲的GPU设备。

方式三：手动下载模型权重（离线环境）

如运行环境无法在线下载模型，可提前手动下载：

# 通过ModelScope下载（国内用户推荐）
pip install -U modelscope
modelscope download --model Qwen/Qwen3-ASR-1.7B --local_dir ./Qwen3-ASR-1.7B
modelscope download --model Qwen/Qwen3-ASR-0.6B --local_dir ./Qwen3-ASR-0.6B
modelscope download --model Qwen/Qwen3-ForcedAligner-0.6B --local_dir ./Qwen3-ForcedAligner-0.6B
通过Hugging Face下载
pip install -U "huggingface_hub[cli]"
huggingface-cli download Qwen/Qwen3-ASR-1.7B --local-dir ./Qwen3-ASR-1.7B
huggingface-cli download Qwen/Qwen3-ASR-0.6B --local-dir ./Qwen3-ASR-0.6B
huggingface-cli download Qwen/Qwen3-ForcedAligner-0.6B --local-dir ./Qwen3-ForcedAligner-0.6B

环境变量配置

复制.env.example为.env并修改：

变量	默认值	说明
GPU_ID	2	GPU设备ID
PORT	8200	API服务端口
MCP_PORT	8201	MCP服务端口
GPU_IDLE_TIMEOUT	600	自动卸载超时（秒），设为0则永久驻留显存

---

三、部署

健康检查

验证服务是否正常运行：

curl http://localhost:8250/health

返回示例包含版本、GPU状态、模型加载状态等信息。

REST API使用

基础语音识别

curl -X POST http://localhost:8250/api/transcribe \
  -F 'file=@audio.wav' \
  -F 'language=auto' \
  -F 'model=Qwen3-ASR-1.7B'

带时间戳的识别

curl -X POST http://localhost:8250/api/transcribe \
  -F 'file=@audio.wav' \
  -F 'language=auto' \
  -F 'model=Qwen3-ASR-1.7B' \
  -F 'return_timestamps=true'

返回示例：

{
  "text": "你好世界",
  "language": "Chinese",
  "timestamps": [
    {"text": "你", "start": 0.0, "end": 0.3},
    {"text": "好", "start": 0.3, "end": 0.5},
    {"text": "世", "start": 0.5, "end": 0.8},
    {"text": "界", "start": 0.8, "end": 1.0}
  ],
  "duration_seconds": 1.0,
  "process_time_seconds": 0.15,
  "rtf": 0.15
}

支持的参数

参数	类型	默认值	说明
file	file	必填	音频文件（WAV/MP3/FLAC/M4A/OGG）
language	string	auto	语言名称或auto自动检测
model	string	Qwen3-ASR-1.7B	Qwen3-ASR-1.7B或Qwen3-ASR-0.6B
return_timestamps	bool	false	是否返回字/词级时间戳
dtype	string	bfloat16	bfloat16或float16

响应Headers中包含性能指标：X-Time-Load（音频加载时间）、X-Time-Process（推理处理时间）、X-Time-Total（总耗时）。

流式转录（WebSocket）

WebSocket端点：ws://localhost:8250/api/transcribe/stream

流式场景的关键配置参数：

参数	默认值	说明
WS_BUFFER_SIZE	14400	累积字节数触发转录（16kHz下约450ms）
WS_WINDOW_MAX_S	6.0	滑动窗口最大秒数，越高准确率越好但GPU负载越大
WS_FLUSH_SILENCE_MS	600	静音填充时长，帮助提交尾部词
ASR_USE_SERVER_VAD	true	服务端VAD，在语音→静音转换时自动刷新

流式转录常见问题：当音频在缓冲区边界处被截断时，可能会导致最后一个词被切断。解决方案包括：

1. 窗口重叠：在相邻转录窗口间保留重叠音频（如最后N毫秒），为模型提供上下文
2. 静音填充：在flush时追加约600ms静音，让模型有足够尾随上下文提交最后单词
3. 合适缓冲区：1.5秒的缓冲区对实时场景偏大，600-800ms可降低延迟

字幕生成（SRT）

扩展部署方案支持SRT字幕生成，两种模式：

• 快速模式：基于segment边界进行启发式词时间估算，无需额外模型，即时完成
• 精确模式：通过ForcedAligner实现词级对齐（约33ms精度），需额外约5.8GB显存

curl -X POST http://localhost:8250/v1/audio/subtitles \
  -F "file=@audio.wav" -F "mode=fast" -o subtitles.srt

参数说明：

• SUBTITLE_MAX_DURATION：单条字幕最大时长（默认7.0秒）
• SUBTITLE_PAUSE_THRESHOLD：触发字幕切分的静音时长（默认0.5秒）
• SUBTITLE_MIN_DURATION：字幕最短显示时长（默认0.833秒）
• SUBTITLE_MIN_GAP：字幕间最小间隔（默认0.083秒）

CJK（中日韩）文字自动优化换行。

翻译功能（音频→文本翻译）

支持音频转录后通过外部LLM进行翻译：

curl -X POST http://localhost:8250/v1/audio/translations \
  -F "file=@audio.wav" -F "language=zh"

配置参数：

• OPENAI_BASE_URL：API地址（Ollama Cloud: https://ollama.com/api，OpenAI: https://api.openai.com/v1）
• OPENAI_API_KEY：API密钥
• TRANSLATE_MODEL：LLM模型名（默认gemma3:12b）
• TRANSLATE_TEMPERATURE：翻译温度（默认0.3）
• TRANSLATE_SRT_TEMPERATURE：SRT翻译温度（默认0.1，更低=更忠实原文）

MCP集成（AI Agent调用）

MCP服务运行在8251端口，支持以下工具：

• transcribe：语音识别

• get_status：获取服务状态

• get_languages：获取支持语言列表

• gpu_offload：释放GPU显存

Claude Desktop / Cursor 配置示例：

json

{
  "mcpServers": {
    "qwen3-asr": {
      "command": "python",
      "args": ["app/mcp_server.py"],
      "env": {
        "MODEL_PATH_QWEN3_ASR_1_7B": "/models/Qwen3-ASR-1.7B"
      }
    }
  }
}

GPU显存管理

• 自动卸载：默认空闲600秒后自动释放显存

• 手动释放：

bash

curl -X POST http://localhost:8250/api/gpu-offload

• 状态查询：

bash

curl http://localhost:8250/api/status

返回GPU使用情况、模型加载状态、支持语言列表等信息。

服务进程守护（systemd）

对于长期运行的服务，建议配置systemd服务，实现进程崩溃后自动恢复和资源隔离：

ini

[Unit]
Description=Qwen3-ASR Service
After=docker.service

[Service]
Restart=always
ExecStart=/usr/bin/docker start -a qwen3-asr
ExecStop=/usr/bin/docker stop qwen3-asr
MemoryLimit=28G

[Install]
WantedBy=multi-user.target

---

四、测试

1. 健康检查

bash

curl http://localhost:8250/health

预期返回HTTP 200，包含版本和服务状态信息。

2. API功能测试

准备一个测试音频文件（如test.wav），执行基础识别：

bash

curl -X POST http://localhost:8250/api/transcribe \
  -F 'file=@test.wav' \
  -F 'language=auto' \
  -F 'model=Qwen3-ASR-0.6B'

预期返回JSON格式的识别结果，包含text字段。

3. 时间戳功能测试

bash

curl -X POST http://localhost:8250/api/transcribe \
  -F 'file=@test.wav' \
  -F 'return_timestamps=true'

预期返回结果中包含timestamps数组，每个元素包含text、start、end字段。

4. 获取支持语言列表

bash

curl http://localhost:8250/api/languages

5. GPU状态查看

bash

curl http://localhost:8250/api/status

预期返回GPU使用情况、模型加载状态、支持语言列表等信息。

6. 长音频处理验证

对于10-20分钟的音频文件，如遇处理异常，需检查分段逻辑。社区经验表明，首个segment如果文件过小（<10KB）可能导致处理失败，建议增加skip逻辑跳过异常segment。

7. WebSocket实时转录测试

建议使用WebSocket客户端工具（如wscat）进行测试：

bash

wscat -c ws://localhost:8250/api/transcribe/stream

发送音频数据后，验证返回的实时识别结果流。

8. 压力测试参考

根据社区测试数据，在NVIDIA H200 NVL上，Qwen3-ASR的运行速度约为实时速度的20倍，1.7B模型与0.6B对齐器合计峰值显存占用< 2GB。建议根据并发需求预留足够的GPU资源。

项目源码中包含完整测试套件：

• tests/test_api.py：22个API测试用例

• tests/test_mcp.py：8个MCP工具测试

运行测试：

bash

# 进入项目目录后执行
pytest tests/

---

附录：常见问题排查

问题	可能原因	解决方案
模型加载失败	网络无法下载模型权重	使用离线模式手动下载模型到指定目录
WebSocket单词截断	缓冲区边界分割词语	启用窗口重叠或静音填充
language=None崩溃	未传language参数时传None到模型	不传language参数，让模型使用默认值
长音频处理失败	首个segment过小(<10KB)	修改分段逻辑跳过异常segment
显存不足	GPU显存小于模型需求	使用0.6B模型或启用INT8量化