Qwen3-ASR-1.7B在Ubuntu20.04上的Docker部署教程

1. 引言

语音识别技术正在改变我们与设备交互的方式，从智能助手到实时字幕，都离不开这项核心技术的支持。今天我们要介绍的Qwen3-ASR-1.7B，是一个支持52种语言和方言的强大语音识别模型，它不仅能准确识别普通话、英语，还能处理各种方言和口音。

对于开发者来说，最头疼的往往不是模型本身，而是如何快速、稳定地部署这些复杂的AI模型。传统的部署方式需要安装各种依赖、配置环境变量，一不小心就会遇到版本冲突、依赖缺失等问题。而Docker容器化部署正好能解决这些痛点，它让部署过程变得像搭积木一样简单。

本文将手把手教你如何在Ubuntu 20.04系统上，使用Docker快速部署Qwen3-ASR-1.7B模型。无论你是AI初学者还是有一定经验的开发者，都能跟着教程顺利完成部署。

2. 环境准备

在开始部署之前，我们需要确保系统环境满足基本要求。Ubuntu 20.04是一个比较稳定的LTS版本，兼容性很好，适合作为生产环境。

2.1 系统要求

首先检查你的系统配置：

• Ubuntu 20.04或更高版本
• 至少16GB内存（推荐32GB）
• 至少50GB可用磁盘空间
• NVIDIA显卡（支持CUDA 11.0+）
• Docker和NVIDIA容器工具包

2.2 安装Docker

如果你的系统还没有安装Docker，可以通过以下命令快速安装：

# 更新软件包列表
sudo apt-get update

# 安装必要的依赖
sudo apt-get install -y apt-transport-https ca-certificates curl software-properties-common

# 添加Docker官方GPG密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

# 添加Docker仓库
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

# 安装Docker
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io

# 将当前用户添加到docker组（避免每次都要sudo）
sudo usermod -aG docker $USER
newgrp docker

2.3 安装NVIDIA容器工具包

由于我们需要使用GPU加速，还要安装NVIDIA的Docker支持：

# 添加NVIDIA包仓库
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

# 安装nvidia-container-toolkit
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

# 重启Docker服务
sudo systemctl restart docker

3. 获取模型文件

Qwen3-ASR-1.7B模型文件比较大（约3.4GB），我们可以通过ModelScope来下载。这里提供两种方式，你可以选择其中一种。

3.1 方式一：直接下载

如果你想要手动下载模型文件，可以使用以下命令：

# 创建模型存储目录
mkdir -p ~/models/Qwen3-ASR-1.7B
cd ~/models/Qwen3-ASR-1.7B

# 使用wget下载（需要你有下载链接）
# wget [模型下载链接] -O model.safetensors

3.2 方式二：使用ModelScope下载

更推荐的方式是使用ModelScope的Python库来下载：

# 安装ModelScope
pip install modelscope

# 下载模型
from modelscope import snapshot_download
model_dir = snapshot_download('Qwen/Qwen3-ASR-1.7B')
print(f'模型下载到: {model_dir}')

下载完成后，记下模型文件的路径，我们后面会用到。

4. 编写Docker部署脚本

现在我们来创建Docker部署所需的文件。首先创建一个项目目录来存放所有相关文件。

4.1 创建项目结构

mkdir qwen3-asr-docker
cd qwen3-asr-docker

4.2 创建Dockerfile

创建一个名为Dockerfile的文件，内容如下：

# 使用官方Python基础镜像
FROM nvidia/cuda:11.8.0-runtime-ubuntu20.04

# 设置环境变量
ENV DEBIAN_FRONTEND=noninteractive
ENV PYTHONUNBUFFERED=1

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    python3.8 \
    python3-pip \
    python3.8-venv \
    git \
    wget \
    && rm -rf /var/lib/apt/lists/*

# 创建工作目录
WORKDIR /app

# 复制requirements文件
COPY requirements.txt .

# 安装Python依赖
RUN pip3 install --no-cache-dir -r requirements.txt

# 复制模型文件（如果模型文件不大可以直接复制，大的话建议挂载卷）
# COPY model/ /app/model/

# 暴露端口
EXPOSE 8000

# 启动命令
CMD ["python3", "app.py"]

4.3 创建requirements.txt

创建依赖文件requirements.txt：

torch>=2.0.0
transformers>=4.30.0
modelscope>=1.10.0
qwen-asr[vllm]>=0.1.0
fastapi>=0.100.0
uvicorn>=0.22.0

4.4 创建启动脚本

创建app.py作为我们的应用入口：

from fastapi import FastAPI
from qwen_asr import Qwen3ASRModel
import torch
import os

app = FastAPI(title="Qwen3-ASR-1.7B API")

# 初始化模型
@app.on_event("startup")
async def load_model():
    global model
    model_path = os.getenv("MODEL_PATH", "/app/model")
    print(f"Loading model from: {model_path}")
    
    model = Qwen3ASRModel.from_pretrained(
        model_path,
        dtype=torch.bfloat16,
        device_map="auto",
        max_inference_batch_size=32,
        max_new_tokens=256,
    )
    print("Model loaded successfully!")

@app.get("/")
async def root():
    return {"message": "Qwen3-ASR-1.7B API is running"}

@app.post("/transcribe")
async def transcribe_audio(audio_url: str):
    try:
        results = model.transcribe(
            audio=audio_url,
            language=None  # 自动检测语言
        )
        return {
            "language": results[0].language,
            "text": results[0].text,
            "status": "success"
        }
    except Exception as e:
        return {"error": str(e), "status": "error"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

5. 构建和运行Docker容器

现在一切准备就绪，我们可以开始构建和运行Docker容器了。

5.1 构建Docker镜像

在项目目录下运行：

docker build -t qwen3-asr-1.7b .

这个过程可能会花费一些时间，因为需要下载基础镜像和安装依赖。

5.2 运行Docker容器

镜像构建完成后，使用以下命令运行容器：

docker run -d \
  --name qwen3-asr \
  --gpus all \
  -p 8000:8000 \
  -v /path/to/your/model:/app/model \
  -e MODEL_PATH=/app/model \
  qwen3-asr-1.7b

请将/path/to/your/model替换为你实际下载的模型文件路径。

5.3 使用docker-compose（推荐）

为了更方便管理，我们可以使用docker-compose。创建docker-compose.yml文件：

version: '3.8'

services:
  qwen3-asr:
    build: .
    container_name: qwen3-asr-1.7b
    ports:
      - "8000:8000"
    volumes:
      - ./model:/app/model
    environment:
      - MODEL_PATH=/app/model
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    restart: unless-stopped

然后运行：

docker-compose up -d

6. 测试部署效果

容器运行起来后，我们来测试一下是否部署成功。

6.1 检查容器状态

docker ps

你应该能看到qwen3-asr容器正在运行。

6.2 测试API接口

使用curl测试API：

curl -X POST "http://localhost:8000/transcribe" \
  -H "Content-Type: application/json" \
  -d '{"audio_url":"https://example.com/audio.wav"}'

请将URL替换为你要测试的音频文件地址。

6.3 使用Python客户端测试

你也可以创建一个简单的Python脚本来测试：

import requests
import json

url = "http://localhost:8000/transcribe"
headers = {"Content-Type": "application/json"}
data = {
    "audio_url": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-ASR-Repo/asr_en.wav"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

print(f"识别语言: {result['language']}")
print(f"识别文本: {result['text']}")

7. 常见问题解决

在部署过程中可能会遇到一些问题，这里列举几个常见的解决方法。

7.1 GPU内存不足

如果遇到GPU内存不足的错误，可以尝试减小batch size：

model = Qwen3ASRModel.from_pretrained(
    model_path,
    dtype=torch.bfloat16,
    device_map="auto",
    max_inference_batch_size=8,  # 减小batch size
    max_new_tokens=256,
)

7.2 模型加载慢

第一次加载模型可能会比较慢，这是正常的，因为需要将模型加载到GPU内存中。

7.3 端口冲突

如果8000端口已经被占用，可以修改docker-compose.yml中的端口映射：

ports:
  - "8001:8000"  # 将主机端口改为8001

8. 总结

通过这个教程，我们成功地在Ubuntu 20.04上使用Docker部署了Qwen3-ASR-1.7B模型。整个过程虽然涉及多个步骤，但每个步骤都相对 straightforward。

Docker部署的优势很明显：环境隔离、依赖管理、易于迁移和扩展。一旦配置好Dockerfile和docker-compose文件，后续的部署就变得非常简单，只需要几条命令就能完成。

实际使用中，你可能还需要考虑一些生产环境的优化，比如添加健康检查、设置资源限制、配置日志监控等。但基于这个基础部署，你已经可以开始体验Qwen3-ASR-1.7B强大的语音识别能力了。

建议你先从简单的音频文件开始测试，熟悉模型的性能特点后，再逐步尝试更复杂的应用场景。如果遇到问题，可以查看容器日志来排查错误原因。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。