背景描述

本文以 X86 CPU 部署为例，介绍如何在平台中部署 Qwen3-ASR-1.7B，并通过《模型网关》和《模型体验》完成语音转文本。

操作包括准备模型文件和推理镜像、创建推理引擎、部署模型、配置 AI 服务提供者及网关路由、验证语音转文本。

本例所在环境具备 NVIDIA L20，但该模型使用 CPU 推理，配置为 16 核 CPU、64 GiB 内存，部署 1 个副本，不分配 AI 加速卡。

前提条件

已具备目标项目的模型、推理引擎、部署和网关管理权限。
已初始化项目命名空间，并分配足够的项目配额。
有可调度的 X86 CPU 资源；本例每个副本使用 16 核 CPU 和 64 GiB 内存，无需分配 AI 加速卡。
环境能够从 ModelScope 导入模型，或已准备好对应的完整模型文件。
环境中镜像仓库已上传 hub.ecns.io/engines/vllm-openai-cpu:v0.21.0。

本例部署配置

配置项	本例取值
模型来源	ModelScope：`Qwen/Qwen3-ASR-1.7B`
平台模型名称	`Qwen3-ASR-1.7B`
模型文件大小	约 4.38 GiB
推理引擎名称	`asr-vllm-cpu`，新建时可自定义名称
引擎类型/架构	vLLM/X86（amd64）
推理镜像	`hub.ecns.io/engines/vllm-openai-cpu:v0.21.0`
CPU/内存	16 核/64 GiB
AI 加速卡	不分配
副本数	1
自定义环境变量	`VLLM_CPU_KVCACHE_SPACE=30`；部署页面另行填写 `SERVED_MODEL_NAME`
KV Cache 内存卸载	不启用
模型容器路径	`/mnt/models`
容器服务端口	`8000`
服务模型名称	`Qwen3-ASR-1.7B`
AI 服务提供者类型/API 规范	内部/OpenAI
网关路由名称/域名	`all-in-one`/`ai.beacon.ai`，其他环境可自定义
路由模型名称/后端模型名称	`Qwen3-ASR-1.7B`/`Qwen3-ASR-1.7B`

操作步骤

1. 准备推理镜像

在《容器镜像服务》中准备推理镜像 hub.ecns.io/engines/vllm-openai-cpu:v0.21.0，确认目标项目可以使用该镜像，且运行节点能够拉取。

如果需要转存至其他环境，保持镜像内容和版本一致。在《镜像管理》页面进入镜像详情页按平台要求添加 vllm 分类标签，创建引擎时选择 X86 架构、vLLM 类型，AI 加速卡保持不选择。

本例使用的是 vllm-openai-cpu 镜像。复现时应使用记录的镜像及后文启动参数。

注意：使用官方 CUDA 镜像时补齐音频依赖

如果改用 GPU 部署，不能直接使用未补齐音频依赖的官方 CUDA vllm-openai 镜像。官方 CUDA 镜像没有默认安装完整的 vllm[audio] 可选依赖，音频请求可能报：

Invalid or unsupported audio file.

建议基于原镜像制作一个新镜像，并安装与镜像中 vLLM 完全相同版本的 vllm[audio]。例如，基础镜像为 v0.22.1 时，创建以下 Dockerfile：

FROM vllm/vllm-openai:v0.22.1
RUN uv pip install --system "vllm[audio]==0.22.1"

在 Dockerfile 所在目录执行构建和推送命令，将 <registry> 替换为实际镜像仓库地址：

docker build -t <registry>/vllm-openai:v0.22.1-audio .
docker push <registry>/vllm-openai:v0.22.1-audio

然后将部署使用的镜像替换为新镜像。以上是 CUDA 镜像补充依赖的示例；本文 CPU 部署仍使用 vllm-openai-cpu:v0.21.0。

不要安装未指定版本的 vllm[audio]：

# 不推荐
pip install "vllm[audio]"

这可能升级 vLLM、PyTorch 或 CUDA 依赖，破坏原镜像环境。vllm[audio] 的版本必须与基础镜像中的 vLLM 版本一致。

2. 初始化项目并设置配额

项目管理员进入《模型广场》，按提示完成命名空间初始化；已经初始化的项目可跳过。
在《配额管理》中分配本次部署所需的 CPU 和内存配额，容器规格按环境选择安全容器服务对应配置。
确认剩余配额和节点可用资源满足 16 核 CPU、64 GiB 内存。项目内已有其他模型时，应按剩余资源核对。

3. 导入模型文件

进入《模型仓库》，选择公共仓库后，单击 创建导入任务，选择从 ModelScope 导入。
输入原始链接的内容为https://www.modelscope.cn/models/Qwen/Qwen3-ASR-1.7B，点击解析链接，按环境带宽限制需求输入限速大小，点击创建导入任务。
等待导入完成，在《模型仓库》核对模型文件状态为 就绪、处理阶段为 成功。

4. 创建推理引擎

进入《推理引擎》，单击 创建推理引擎。
填写引擎名称，例如 asr-vllm-cpu。
引擎可见性选择公有引擎，类型选择 vLLM。
CPU 设为 16，内存设为 64，AI 加速卡保持不选择，架构选择 X86。
选择镜像 hub.ecns.io/engines/vllm-openai-cpu:v0.21.0。
在“启动命令”中按下面的分行形式填写（已默认填充）：
```
vllm
serve
/mnt/models
```

在“启动参数”中按下面的分行形式填写：

--served-model-name
$(SERVED_MODEL_NAME)
--port
8000
--enable-prompt-tokens-details

添加以下环境变量：

变量名值

VLLM_CPU_KVCACHE_SPACE 30

注意：CPU 镜像启动时需要设置 VLLM_CPU_KVCACHE_SPACE。 如果不设置，vLLM 可能按照宿主机总内存自动分配过大的 KV Cache，超过 Pod 内存限制，导致容器 OOM 重启。

本例 Pod 内存限制为 64 GiB，设置值为 30，表示为 KV Cache 分配约 30 GiB。具体数值应低于 Pod 内存限制，并为模型权重、推理进程和系统运行预留足够内存。

页面中填写上述变量名和值即可，对应的容器环境变量配置为：
```
env:
  - name: VLLM_CPU_KVCACHE_SPACE
    value: "30"
```
点击创建，完成创建。

变量名	值
`VLLM_CPU_KVCACHE_SPACE`	`30`

以上两段分别粘贴到页面的“启动命令”和“启动参数”字段，每个参数或参数值独占一行。$(SERVED_MODEL_NAME) 是容器启动参数中的变量引用，按原样填写，不要直接粘贴到本机 Shell 中执行。后续部署页面会提供变量值。

/mnt/models 对应部署时挂载的模型文件路径；8000 是容器服务端口。启动参数及 VLLM_CPU_KVCACHE_SPACE=30 均按本例配置保留。

5. 创建并部署模型

进入《模型广场》，点击新建模型，填写名称为Qwen3-ASR-1.7B，选择模型可见性为公有模型，模型文件选择绑定已有模型文件，模型文件选择步骤3导入的模型文件，推理引擎选择步骤4创建的推理引擎，点击创建模型。
单击《模型广场》列表中Qwen3-ASR-1.7B卡片中的部署按钮，在新建模型部署的弹框中填写部署名称，例如 Qwen3-ASR-1.7B-deploy，副本数为1。
推理引擎和模型文件会根据新建模型时选择的引擎和模型文件自动填入。
核对模型文件信息与步骤3所导入的模型文件信息一致；核对页面展示的镜像、命令、参数及资源与步骤4 一致。
核对环境变量 VLLM_CPU_KVCACHE_SPACE 的值为 30，KV Cache 内存卸载 选择 不启用。
SERVED_MODEL_NAME 填写 Qwen3-ASR-1.7B，LoRA 微调模型保持为空。
本例配置以继承上述引擎配置为基线，无需另外设置高级覆盖项。如已有部署设置了覆盖项，需展开“高级配置”核对最终命令、参数和环境变量。
单击创建，等待状态变为 就绪。核对副本数为 1，实例运行正常。

SERVED_MODEL_NAME 会由平台注入部署容器，并由引擎中的 --served-model-name 引用。

模型启动或加载异常时，可在部署详情的状态、日志、终端页排查。

6. 创建 AI 服务提供者

进入《AI 服务提供者》，单击 创建AI服务提供者。
填入名称，例如 Qwen3-ASR-1.7B-deploy，服务类型选择 内部。
选择部署选择步骤5创建的模型部署，核对平台生成的访问地址，点击创建，完成创建。
确认提供者状态为 就绪。

7. 配置模型网关

进入《模型网关》，创建路由或编辑已有路由。
本例路由名称为all-in-one，二级域名填写ai，页面与环境域名后缀beacon.ai拼接为ai.beacon.ai。其他环境按实际域名后缀填写；已有该路由时，编辑并添加本模型即可。
添加以下模型与后端映射：

字段取值

对外模型名称 Qwen3-ASR-1.7B

后端 Qwen3-ASR-1.7B-deploy

后端模型名称 Qwen3-ASR-1.7B

优先级 0

权重 1
保存并确认路由就绪。

字段	取值
对外模型名称	`Qwen3-ASR-1.7B`
后端	`Qwen3-ASR-1.7B-deploy`
后端模型名称	`Qwen3-ASR-1.7B`
优先级	`0`
权重	`1`

8. 准备 API Key

《模型体验》页面需要填写 API Key。已有可用密钥时可直接使用；需要新建时：

进入《套餐管理》，创建套餐，“可访问路由”选择上述路由all-in-one，按需设置调用限制。
进入《API Key》，创建密钥并绑定该套餐。
签发后保存密钥，后续在《模型体验》或 API 请求中使用。

在模型体验中验证语音转文本

进入《模型体验》，选择 语音，切换到 语音转文本。
填写有效 API Key。
路由选择 all-in-one，模型选择 Qwen3-ASR-1.7B。
在 选择音频 中点击 上传文件 选择测试音频，也可以点击 麦克风录音 录制一段语音。使用录音时，按浏览器提示允许麦克风访问，并在录制完成后确认页面已显示音频文件。
本例页面使用 .webm 音频。复现时可录制以下语句作为测试音频：
```
今天的天气怎么样？
```
单击 识别，等待返回识别结果。
核对返回文字与音频中的语音内容一致。本例页面返回：
```
今天的天气怎么样？
```

使用其他音频时，应以该音频的实际内容作为核对依据。

约束与注意事项

镜像与参数保持一致：本例为 vllm-openai-cpu:v0.21.0，并设置环境变量 VLLM_CPU_KVCACHE_SPACE=30。更换镜像版本或启动方式后需重新验证。
资源配置以本例为基线：16 核 CPU、64 GiB 内存、1 副本为本例使用的配置。
核对最终生效参数：模型部署可以覆盖引擎配置。排查时同时检查引擎和部署的高级配置；本文复现步骤采用继承引擎的配置，如设置过高级覆盖项，应逐项核对。
验证范围：本文验证 .webm 中文短语音的识别流程；其他音频格式、语言、长音频及并发场景，应另行准备样本验证。
CPU 配置：本例未分配 GPU。VLLM_CPU_KVCACHE_SPACE 是引擎环境变量，与部署页面的“KV Cache 内存卸载”是不同配置项，应分别按本文填写。

语音转文字：Qwen3-ASR-1.7B模型部署和访问