Qwen3-ASR-1.7B 昇腾 NPU 部署指南

本文档从环境检查到镜像构建、容器运行、接口调用写全流程，按顺序执行即可在华为云昇腾910B NPU 上完成部署并跑通转录。

一、项目简介

本项目在华为云昇腾910B NPU上部署 Qwen3-ASR-1.7B 语音识别服务，提供 HTTP API，接口风格与同仓库 Whisper 部署一致，便于统一网关或替换。

模型信息:

• 模型: Qwen/Qwen3-ASR-1.7B
• 参数量: 约 1.7B
• 支持: 52 种语言与方言（含 30 种语言、22 种中文方言及多地区英语口音）
• 许可证: Apache 2.0

二、硬件与环境要求

三、前置准备（环境检查）

在构建镜像和运行容器之前，请先在宿主机上确认以下环境正常。

3.1 确认 NPU 与驱动

在终端执行：

npu-smi info

若能看到 NPU 型号、显存等信息，说明驱动正常。若报错或找不到命令，请先安装昇腾驱动与 CANN，参考：
https://www.hiascend.com/software/cann

3.2 确认 CANN 环境（可选，容器内通常已配置）

若在宿主机上需要用到 CANN：

source /usr/local/Ascend/ascend-toolkit/set_env.sh

3.3 确认 Docker

docker --version

若无 Docker，可安装（以 Ubuntu 为例）：

sudo apt-get update
sudo apt-get install -y docker.io
sudo usermod -aG docker $USER   # 当前用户加入 docker 组，需重新登录生效

3.4 确认 NPU 设备节点

ls -l /dev/davinci*

应能看到至少 /dev/davinci0。后续运行容器时会通过 --device=/dev/davinci0 把该设备挂进容器。

3.5 是否需要先 pip 安装依赖？

不需要。 本方案使用 Docker 部署，所有 Python 依赖（qwen-asr、torch、FastAPI 等）都在镜像构建时装进容器，宿主机上只要具备：

• Docker
• NPU 驱动 / CANN（见 3.1、3.2）
• （可选）用于下载模型的工具

宿主机不需要安装 qwen-asr、torch、transformers 等，也不用建虚拟环境。

唯一可能用到 pip 的情况：若你使用 ./scripts/download_model.sh 下载模型，需要在宿主机上安装 HuggingFace 命令行工具：

• HuggingFace：pip install "huggingface_hub[cli]"

若你改用手动下载或不提前下载（让容器首次启动时从 HuggingFace 拉取），则宿主机上连这个都不需要装。

四、项目结构说明

部署时主要用到的是项目根目录和 scripts 下的脚本，其余为代码与配置。

Qwen3-ASR-1.7B/
├── api/                    # 服务代码（无需手动改）
│   ├── main.py             # FastAPI 主服务
│   ├── model_loader.py     # 模型加载（支持 NPU）
│   └── inference.py        # 推理封装
├── config/
│   └── config.yaml         # 服务与模型配置
├── scripts/                # 部署与测试脚本（小白重点用这里）
│   ├── download_model.sh   # 第一步：下载模型
│   ├── build.sh            # 第二步：构建镜像
│   ├── deploy.sh           # 第三步：启动容器
│   ├── test_transcribe.sh           # 用本地音频文件测试转录
│   ├── test_metrics.sh              # 调用 /health、/metrics 监控接口
│   └── test_with_official_audio.sh  # 用官方示例音频 URL 测试本地接口
├── test_audio/               # 本地测试音频（提交时由 .gitattributes 用 Git LFS 跟踪）
├── .gitattributes            # Git LFS：test_audio/*.wav 等走 LFS
├── Dockerfile              # 昇腾 NPU 镜像定义
├── requirements.txt
└── README.md               # 本文档

重要概念:

• 宿主机: 你登录的华为云 NPU 服务器。
• 模型目录: 宿主机上存放模型的路径，例如 /data0/workspace，下面再放子目录 Qwen3-ASR-1.7B。
• 容器: Docker 跑起来的服务进程；会把「宿主机模型目录」挂载到容器内的 /app/models，这样容器就能读到模型。

五、部署流程（四步走）

下面四步按顺序执行即可完成「从镜像到脚本调用」的全流程。

第一步：下载模型（推荐提前做）

模型需放在宿主机上，再通过挂载给容器使用。首次部署建议先下载模型，避免容器内拉取失败或过慢。

在项目根目录执行（把 /data0/workspace 换成你实际要放模型的目录）：

cd Qwen3-ASR-1.7B
chmod +x scripts/*.sh
./scripts/download_model.sh /data0/workspace

脚本会提示选择下载方式：

• 1) GitCode：国内加速推荐
• 2) HuggingFace：官方原版，需先 pip install "huggingface_hub[cli]"

下载完成后，模型会在 /data0/workspace/Qwen3-ASR-1.7B（或你指定的目录下的 Qwen3-ASR-1.7B）。
若不下载，也可以直接跑容器，首次启动时会尝试从 HuggingFace 拉取（可能较慢或受网络影响）。

手动下载示例 (GitCode):

# 使用 GitCode 镜像仓库下载
git clone https://atomgit.com/hf_mirrors/Qwen/Qwen3-ASR-1.7B.git /data0/workspace/Qwen3-ASR-1.7B

手动下载示例 (HuggingFace):

# HuggingFace
pip install -U "huggingface_hub[cli]"
huggingface-cli download Qwen/Qwen3-ASR-1.7B --local-dir /data0/workspace/Qwen3-ASR-1.7B

确认目录存在且内有 config.json 等文件即可：

ls /data0/workspace/Qwen3-ASR-1.7B

第二步：构建 Docker 镜像

在项目根目录执行：

cd Qwen3-ASR-1.7B
./scripts/build.sh

或直接使用 Docker 命令：

cd Qwen3-ASR-1.7B
docker build -t qwen3-asr-ascend:latest .

• -t qwen3-asr-ascend:latest 表示镜像名为 qwen3-asr-ascend，标签为 latest。
• 首次构建会拉取昇腾基础镜像并安装依赖，可能需几分钟到十几分钟，属正常现象。
• 构建成功后执行 docker images | grep qwen3-asr 应能看到该镜像。

第三步：启动容器（运行服务）

启动容器时需把宿主机上的模型目录挂载进容器，并指定使用哪张 NPU 卡。

使用脚本（推荐）:

cd Qwen3-ASR-1.7B
./scripts/deploy.sh /data0/workspace 0 8002

参数含义：

• 第 1 个参数：宿主机上模型父目录（例如 /data0/workspace，其下有 Qwen3-ASR-1.7B）
• 第 2 个参数：NPU 设备号（0 表示使用 /dev/davinci0）
• 第 3 个参数：宿主机端口（8002 表示通过 http://localhost:8002 访问服务）

不传参时默认等价于：./scripts/deploy.sh /data0/workspace 0 8002。

手动执行等价命令（宿主机若有 CANN 驱动，请挂载 driver 与可选 add-ons，不要挂载整个 Ascend，否则会覆盖镜像内 nnal/atb/set_env.sh 导致报错）:

docker run -d \
  --name qwen3-asr-api \
  --device=/dev/davinci0 \
  --restart=unless-stopped \
  -p 8002:8000 \
  -v /data0/workspace:/app/models \
  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
  -e LOCAL_MODEL_PATH=/app/models/Qwen3-ASR-1.7B \
  -e DEVICE=npu \
  -e NPU_VISIBLE_DEVICES=0 \
  -e ASCEND_RT_VISIBLE_DEVICES=0 \
  -e ASCEND_DEVICE_ID=0 \
  qwen3-asr-ascend:latest

参数简要说明：

若模型目录或端口不同，只需把 /data0/workspace、8002、davinci0 换成你的实际路径、端口和设备号即可。deploy.sh 会检测宿主机 /usr/local/Ascend/driver 和 add-ons 并仅挂载这两项。

查看是否启动成功:

docker ps | grep qwen3-asr

应能看到名为 qwen3-asr-api 的容器在运行。
首次启动会加载模型，可能需要 1～2 分钟，可看日志：

docker logs -f qwen3-asr-api

看到类似「模型加载成功」或服务已监听 8000 端口即可进行下一步。

第四步：验证服务并调用转录接口

4.1 健康检查

在宿主机或能访问该机的机器上执行（端口与上一步一致，这里以 8002 为例）：

curl http://localhost:8002/health

正常会返回 JSON，例如：

{
  "status": "healthy",
  "model_loaded": true,
  "npu_available": true,
  "cuda_available": false,
  "version": "1.0.0"
}

model_loaded 为 true 表示模型已加载，npu_available 为 true 表示 NPU 可用。

4.2 用官方示例音频测试（推荐）

使用 Qwen3-ASR 官方示例音频（自动下载后请求本地接口），无需准备本地文件：

cd Qwen3-ASR-1.7B
chmod +x scripts/*.sh
./scripts/test_with_official_audio.sh 8002

• 第一个参数：服务端口（默认 8002）
• 第二个参数（可选）：主机或完整 API 地址，如 192.168.1.100 或 http://192.168.1.100:8002

脚本会：健康检查 → 下载官方中文/英文示例（asr_zh.wav / asr_en.wav）→ 请求本地转录接口并打印结果。官方示例地址：https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-ASR-Repo/。

4.3 用本地音频文件测试

可将测试音频放在项目下的 test_audio/ 目录，再执行：

./scripts/test_transcribe.sh test_audio/your.wav 8002

或任意路径：./scripts/test_transcribe.sh /path/to/your/audio.wav 8002

• 第一个参数：音频文件路径
• 第二个参数：服务端口（默认 8002）

脚本会先调 /health 检查服务，再上传音频并打印转录结果（JSON 和纯文本）。

4.4 调用监控与健康检查接口

./scripts/test_metrics.sh [端口] [health|metrics|all]

• 不传参：默认端口 8002，先输出 /health 再输出 /metrics（Prometheus 格式）。
• 第二参数可选：health 仅健康检查，metrics 仅拉取指标，all 两者都要（默认）。

示例：./scripts/test_metrics.sh 8002 metrics 只拉取 Prometheus 指标。

若要把 test_audio/ 里的音频提交到 Git：已配置 .gitattributes，该目录下的 .wav、.mp3 等会通过 Git LFS 跟踪，避免大文件撑大仓库。首次使用需安装并初始化 LFS：git lfs install，再正常 git add、git commit 即可。

4.5 用 curl 手动调用

转录（返回 JSON）:

curl -X POST "http://localhost:8002/v1/audio/transcriptions" \
  -F "file=@/path/to/audio.wav" \
  -F "model=Qwen3-ASR-1.7B" \
  -F "language=zh" \
  -F "response_format=json"

只返回文本:

curl -X POST "http://localhost:8002/v1/audio/transcriptions" \
  -F "file=@/path/to/audio.wav" \
  -F "model=Qwen3-ASR-1.7B" \
  -F "response_format=text"

把 /path/to/audio.wav 换成实际音频路径即可。

4.6 在浏览器中查看 API 文档

若本机或内网能访问该服务器，可在浏览器打开：

• 接口文档: http://<服务器IP>:8002/docs
• 健康检查: http://<服务器IP>:8002/health

六、API 接口说明（供脚本或业务调用）

服务与 Whisper 部署保持同一套风格，便于替换或统一网关。

转录请求参数（form-data）:

• file: 音频文件（必填）
• model: 可选，默认 Qwen3-ASR-1.7B
• language: 可选，如 zh、en，不传则自动检测
• response_format: 可选，json（默认）、text、verbose_json

转录响应示例（response_format=json）:

{
  "text": "识别出的文本内容",
  "language": "zh"
}

七、环境变量（可选）

运行容器时可通过环境变量微调行为，常用如下：

八、常见问题排查

1. 报错「qwen-asr 未正确安装或导入失败」

• 日志里会附带真实导入异常（例如 libascend_hal.so: cannot open shared object file）。
• 若异常含 libascend_hal.so 或 CANN 相关：说明容器内缺少 NPU 驱动库。宿主机需已安装 CANN，并只挂载 driver（及可选 add-ons），勿挂载整个 /usr/local/Ascend（否则会覆盖镜像内 nnal/atb/set_env.sh 导致 “set_env.sh: No such file or directory”）：

  # 宿主机上确认存在
  ls /usr/local/Ascend/driver
  # 使用 deploy.sh 时会自动挂载 driver 与 add-ons；若手动 docker run，请加：
  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver

  然后停掉旧容器、用新参数重新跑：./scripts/deploy.sh /data1/develop/models/Qwen 0 8002。
• 若无 libascend_hal 等字样：多为镜像里未装上 qwen-asr（例如用了旧镜像）。请重新构建镜像后再启动：

  cd Qwen3-ASR-1.7B
  docker build --no-cache -t qwen3-asr-ascend:latest .
  docker stop qwen3-asr-api 2>/dev/null; docker rm qwen3-asr-api 2>/dev/null
  ./scripts/deploy.sh /data1/develop/models/Qwen 0 8002

2. 容器起不来或马上退出

• 执行 docker logs qwen3-asr-api 看报错。
• 常见原因：NPU 设备未挂载（检查 --device=/dev/davinci0）、宿主机没有 /dev/davinci0、端口被占用（换一个 -p 端口）。

3. 健康检查返回但 model_loaded 为 false

• 多为模型未加载成功。查看日志：docker logs -f qwen3-asr-api。
• 确认挂载路径正确：宿主机存在 /data0/workspace/Qwen3-ASR-1.7B 且内有 config.json 等；LOCAL_MODEL_PATH 为 /app/models/Qwen3-ASR-1.7B。
• 若 qwen-asr 暂不支持 device_map=npu:0，日志中会看到尝试 auto 或 cpu，服务仍可能能启动（可能较慢）。

4. 报错「/usr/local/Ascend/nnal/atb/set_env.sh: No such file or directory」

• 说明挂载了整个 /usr/local/Ascend，覆盖了镜像内的 nnal/atb 等目录，而宿主机上可能没有该脚本。
• 处理：只挂载 driver（及可选 add-ons），不要挂载整个 Ascend。使用 deploy.sh 时会自动只挂载 driver 与 add-ons；若手动运行，请用 -v /usr/local/Ascend/driver:/usr/local/Ascend/driver，不要用 -v /usr/local/Ascend:/usr/local/Ascend。

5. halGetDeviceInfo failed drvRet=4 / NPU 不可用，已回退到 CPU

• 现象：日志里大量 halGetDeviceInfo failed: drvRet=4、Can't get ascend_hal device count、Runtime boot failed，并出现「DEVICE=npu 但 NPU 不可用，将回退到 CPU」和「Qwen3-ASR 模型加载成功 (device_map=cpu)」。
• 说明：服务已正常启动并在 CPU 上运行，可照常调用转录接口，只是推理在 CPU 上会较慢。容器内驱动/运行时无法访问 NPU（drvRet=4 通常表示设备未找到或驱动不匹配）。
• 可选处理：
  1. 暂时用 CPU：若可接受速度，可显式设 DEVICE=cpu 再启动容器，减少每次健康检查触发的 RUNTIME 报错刷屏，例如：

     docker run -d ... -e DEVICE=cpu ...

  2. 排查 NPU：在宿主机执行 npu-smi info 确认 NPU 与驱动正常；确认宿主机 CANN/驱动版本与基础镜像 quay.io/ascend/vllm-ascend:v0.11.0rc0 兼容；参考华为云/昇腾文档中「容器内使用 NPU」的官方说明（设备透传、驱动挂载、版本匹配等）。

6. npu-smi 或 /dev/davinci0 不存在

• 需在宿主机安装昇腾驱动与 CANN，并确认 NPU 设备节点存在。参考华为官方文档。

7. 端口被占用

• 换一个宿主机端口，例如：./scripts/deploy.sh /data0/workspace 0 8003，后续访问用 http://localhost:8003。

8. 想重新部署

• 先停并删容器，再重新执行 deploy：

  docker stop qwen3-asr-api
  docker rm qwen3-asr-api
  ./scripts/deploy.sh /data0/workspace 0 8002

九、生产环境示例（资源与日志）

若需限制 CPU/内存并持久化日志，可参考：

docker run -d \
  --name qwen3-asr-api \
  --device=/dev/davinci0 \
  --restart=unless-stopped \
  -p 8002:8000 \
  --cpus="8" \
  --memory="16g" \
  -v /data0/workspace:/app/models \
  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
  -v /data/logs/qwen3-asr:/app/logs \
  -e LOCAL_MODEL_PATH=/app/models/Qwen3-ASR-1.7B \
  -e DEVICE=npu \
  -e NPU_VISIBLE_DEVICES=0 \
  -e ASCEND_RT_VISIBLE_DEVICES=0 \
  -e ASCEND_DEVICE_ID=0 \
  -e WORKERS=1 \
  qwen3-asr-ascend:latest

其中 /data/logs/qwen3-asr 为宿主机日志目录，可按需修改。

十、参考链接

• Qwen3-ASR-1.7B 模型页
• Qwen3-ASR GitHub
• 本仓库 whisper-large-v3-turbo 部署结构