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

1. 引言

语音识别技术正在改变我们与设备交互的方式，而Qwen3-ASR-1.7B作为一款强大的开源语音识别模型，支持多达52种语言和方言的识别能力。无论你是开发者、研究人员还是技术爱好者，通过Docker部署这个模型都能让你快速体验到先进的语音识别技术。

本教程将手把手指导你在Ubuntu 20.04系统上完成Qwen3-ASR-1.7B的Docker化部署。即使你是Docker新手，跟着步骤走也能轻松搞定。我们将从环境准备开始，一直到模型测试，确保每个环节都清晰易懂。

2. 环境准备与系统要求

在开始部署之前，我们先确认一下系统环境和硬件要求。Ubuntu 20.04是个不错的选择，稳定性好且兼容性强。

2.1 硬件要求

要顺畅运行Qwen3-ASR-1.7B，你的设备最好满足以下配置：

• GPU：NVIDIA显卡（建议RTX 3060或更高型号），至少8GB显存
• 内存：16GB RAM或更多
• 存储：至少20GB可用空间（模型文件较大）
• CPU：4核以上处理器

2.2 软件依赖

确保系统已安装以下基础软件：

# 更新系统包列表
sudo apt update

# 安装基础工具
sudo apt install -y curl wget git python3 python3-pip

3. Docker环境搭建

Docker能让我们的部署过程更加简洁和可重复，避免环境冲突问题。

3.1 安装Docker引擎

首先安装Docker官方版本：

# 添加Docker官方GPG密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# 添加Docker仓库
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

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

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

3.2 安装NVIDIA容器工具包

为了让Docker能够使用GPU，我们需要安装NVIDIA容器工具包：

# 添加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 update
sudo apt install -y nvidia-container-toolkit

# 重启Docker服务
sudo systemctl restart docker

验证NVIDIA容器工具包是否安装成功：

docker run --rm --gpus all nvidia/cuda:11.8.0-base nvidia-smi

如果看到GPU信息输出，说明配置成功。

4. 获取Qwen3-ASR-1.7B模型

现在我们来获取模型文件。Qwen3-ASR-1.7B可以通过多种方式下载，这里使用ModelScope的方式。

4.1 创建项目目录

首先创建一个专门的工作目录：

mkdir -p ~/qwen3-asr-deployment
cd ~/qwen3-asr-deployment

4.2 下载模型文件

使用以下命令下载模型（确保有足够的磁盘空间）：

# 安装ModelScope
pip3 install modelscope

# 下载模型（这会自动处理依赖和模型文件）
python3 -c "
from modelscope import snapshot_download
model_dir = snapshot_download('Qwen/Qwen3-ASR-1.7B')
print(f'模型下载完成，路径: {model_dir}')
"

下载过程可能需要一些时间，取决于你的网络速度。模型大小约3.4GB，请耐心等待。

5. 创建Docker部署配置

接下来我们创建Docker相关的配置文件，确保部署过程标准化。

5.1 编写Dockerfile

创建Dockerfile文件：

# 使用官方PyTorch镜像作为基础
FROM pytorch/pytorch:2.0.1-cuda11.7-cudnn8-runtime

# 设置工作目录
WORKDIR /app

# 安装系统依赖
RUN apt update && apt install -y \
    libsndfile1 \
    ffmpeg \
    && rm -rf /var/lib/apt/lists/*

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

# 复制模型文件和代码
COPY . .

# 暴露服务端口
EXPOSE 8000

# 设置启动命令
CMD ["python", "app.py"]

5.2 创建requirements.txt

创建依赖文件requirements.txt：

torch>=2.0.1
transformers>=4.30.0
modelscope>=1.10.0
qwen-asr[vllm]
fastapi>=0.95.0
uvicorn>=0.21.0
soundfile>=0.12.0
numpy>=1.24.0

5.3 创建应用代码

创建主要的应用文件app.py：

from fastapi import FastAPI, File, UploadFile, HTTPException
from fastapi.responses import JSONResponse
import torch
from qwen_asr import Qwen3ASRModel
import tempfile
import os

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

# 全局变量存储模型实例
model = None

@app.on_event("startup")
async def load_model():
    """启动时加载模型"""
    global model
    try:
        model = Qwen3ASRModel.from_pretrained(
            "/app/models/Qwen3-ASR-1.7B",
            dtype=torch.bfloat16,
            device_map="auto",
            max_inference_batch_size=16,
            max_new_tokens=256,
        )
        print("模型加载成功！")
    except Exception as e:
        print(f"模型加载失败: {str(e)}")
        raise

@app.post("/transcribe")
async def transcribe_audio(file: UploadFile = File(...)):
    """转录上传的音频文件"""
    if not model:
        raise HTTPException(status_code=503, detail="模型未就绪")
    
    # 保存上传的文件到临时文件
    with tempfile.NamedTemporaryFile(delete=False, suffix=".wav") as tmp_file:
        content = await file.read()
        tmp_file.write(content)
        tmp_path = tmp_file.name
    
    try:
        # 使用模型进行转录
        results = model.transcribe(
            audio=tmp_path,
            language=None  # 自动检测语言
        )
        
        # 清理临时文件
        os.unlink(tmp_path)
        
        return JSONResponse({
            "language": results[0].language,
            "text": results[0].text,
            "status": "success"
        })
    except Exception as e:
        # 确保临时文件被清理
        if os.path.exists(tmp_path):
            os.unlink(tmp_path)
        raise HTTPException(status_code=500, detail=f"处理失败: {str(e)}")

@app.get("/health")
async def health_check():
    """健康检查端点"""
    return {"status": "healthy", "model_loaded": model is not None}

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

6. 构建和运行Docker容器

现在一切准备就绪，我们来构建和运行Docker容器。

6.1 构建Docker镜像

在项目目录下执行构建命令：

# 构建镜像（这需要一些时间）
docker build -t qwen3-asr-server .

6.2 运行Docker容器

使用以下命令启动容器：

docker run -d \
  --name qwen3-asr \
  --gpus all \
  -p 8000:8000 \
  -v ~/qwen3-asr-deployment/models:/app/models \
  qwen3-asr-server

参数说明：

• --gpus all：让容器使用所有GPU
• -p 8000:8000：将容器的8000端口映射到主机的8000端口
• -v ...：将本地的模型目录挂载到容器中

6.3 验证容器运行状态

检查容器是否正常运行：

docker ps
docker logs qwen3-asr

如果看到"模型加载成功"的消息，说明部署成功。

7. 测试语音识别服务

现在我们来测试部署好的语音识别服务。

7.1 健康检查

首先检查服务是否正常：

curl http://localhost:8000/health

应该返回类似这样的结果：

{"status":"healthy","model_loaded":true}

7.2 测试语音转录

准备一个测试音频文件，然后使用以下命令测试：

# 使用curl测试（需要准备一个test.wav文件）
curl -X POST "http://localhost:8000/transcribe" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@test.wav"

如果一切正常，你会得到转录结果：

{
  "language": "English",
  "text": "This is a test audio for speech recognition.",
  "status": "success"
}

7.3 使用Python客户端测试

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

import requests

url = "http://localhost:8000/transcribe"

with open("test.wav", "rb") as f:
    files = {"file": ("test.wav", f, "audio/wav")}
    response = requests.post(url, files=files)

print(response.json())

8. 性能优化和实用技巧

为了让服务运行得更高效，这里有一些实用的优化建议。

8.1 GPU内存优化

如果遇到GPU内存不足的问题，可以调整批处理大小：

# 在app.py中调整这些参数
model = Qwen3ASRModel.from_pretrained(
    "/app/models/Qwen3-ASR-1.7B",
    dtype=torch.bfloat16,
    device_map="auto",
    max_inference_batch_size=8,  # 减小批处理大小
    max_new_tokens=128,         # 减少最大生成token数
)

8.2 容器资源限制

为容器设置适当的资源限制：

docker run -d \
  --name qwen3-asr \
  --gpus all \
  -p 8000:8000 \
  -v ~/qwen3-asr-deployment/models:/app/models \
  --memory=16g \
  --cpus=4 \
  qwen3-asr-server

8.3 启用模型缓存

为了加快启动速度，可以启用模型缓存：

# 在Docker run命令中添加缓存目录挂载
-v ~/.cache/huggingface:/root/.cache/huggingface \
-v ~/.cache/modelscope:/root/.cache/modelscope \

9. 常见问题解决

部署过程中可能会遇到一些问题，这里提供一些常见问题的解决方法。

9.1 GPU相关问题

问题：GPU无法在Docker中使用

解决：

# 检查NVIDIA容器工具包是否安装正确
nvidia-ctk --version

# 重新配置NVIDIA容器运行时
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

9.2 内存不足问题

问题：模型加载时出现内存不足错误

解决：尝试使用更小的模型版本（Qwen3-ASR-0.6B）或者增加虚拟内存：

# 增加交换空间
sudo fallocate -l 8G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

9.3 端口冲突问题

问题：8000端口已被占用

解决：使用其他端口：

docker run -d \
  --name qwen3-asr \
  --gpus all \
  -p 8001:8000 \  # 将主机端口改为8001
  -v ~/qwen3-asr-deployment/models:/app/models \
  qwen3-asr-server

10. 总结

通过本教程，我们成功在Ubuntu 20.04上使用Docker部署了Qwen3-ASR-1.7B语音识别模型。整个过程从环境准备开始，包括Docker和NVIDIA环境的配置，到模型下载、容器构建，最后到服务测试和优化。

实际使用下来，这个部署方案还是比较稳定的，能够处理各种语言的语音识别任务。GPU加速效果明显，相比纯CPU推理速度提升很大。如果你在部署过程中遇到问题，大多数情况下通过调整内存设置或者重新配置Docker环境都能解决。

对于想要进一步探索的同学，可以考虑添加Web界面、实现实时语音识别、或者集成到更大的应用系统中。这个基础部署为你提供了一个很好的起点，后续可以根据实际需求进行扩展和优化。

---

获取更多AI镜像

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