Qwen3-ASR-0.6B部署教程：Kubernetes集群中部署ASR服务并暴露Ingress

想把一个智能语音识别工具部署到Kubernetes集群里，让它能稳定运行、方便访问，听起来是不是有点复杂？别担心，今天我就带你一步步搞定这件事。

我们用的工具是Qwen3-ASR-0.6B，一个非常轻巧但能力不错的语音转文字工具。它最大的好处是完全在本地运行，你的音频文件不用上传到任何别人的服务器，隐私安全有保障。它还能自动分辨你说话用的是中文还是英文，甚至中英文混着说也能识别。

这篇文章，我会手把手教你怎么把这个工具打包成容器，部署到Kubernetes集群里，并且通过Ingress让外面的人也能方便地访问到它。整个过程我会尽量讲得明白，即使你对Kubernetes不是特别熟，跟着做也能成功。

1. 准备工作：理解我们要做什么

在开始敲命令之前，我们先花几分钟搞清楚整个部署的蓝图。这样后面每一步做起来，你心里都有数。

1.1 核心组件与流程

我们要部署的不仅仅是一个Python应用，而是一个完整的服务。这个服务包含几个关键部分：

1. 语音识别模型（Qwen3-ASR-0.6B）：这是核心大脑，负责把音频转换成文字。它是一个只有6亿参数的“小模型”，但在中文、英文以及中英文混合语音的识别上表现不错，而且对电脑显卡（GPU）的要求不高。
2. Web交互界面（Streamlit）：我们通过一个网页来使用这个工具。你可以在这个网页上上传音频文件（支持WAV、MP3等常见格式），直接在线播放试听，然后一键点击就能看到识别出的文字结果。这个界面是用Streamlit框架做的，非常简洁直观。
3. Kubernetes部署架构：这是今天的重点。我们会把上面这两部分打包在一起，做成一个Docker容器镜像。然后，在Kubernetes集群里，我们至少需要创建以下资源：
   • Deployment：用来定义和管理这个容器副本（Pod）的运行，比如用哪个镜像、需要多少CPU和内存。
   • Service：在集群内部为我们的Pod提供一个固定的访问地址和端口，让其他服务或者Ingress能找到它。
   • Ingress：这是集群的“入口管理员”。它负责接收从集群外部（比如互联网）发来的访问请求，并根据我们设定的规则（比如访问哪个网址），把请求转发给对应的Service，最终到达我们的语音识别服务。

简单来说，用户通过浏览器访问一个网址（比如 asr.yourcompany.com），Ingress接收到请求，转发给Service，Service再引导请求到达运行着我们工具的Pod，最后用户就能在网页上使用语音转文字功能了。

1.2 环境与工具准备

为了完成部署，你需要提前准备好以下几样东西：

• 一个可用的Kubernetes集群：可以是云服务商提供的（如阿里云ACK、腾讯云TKE），也可以是自己用kubeadm、minikube或k3s搭建的测试环境。
• kubectl命令行工具：这是和Kubernetes集群通信的“遥控器”，需要安装并配置好，确保能连接到你的集群。
• Docker环境：用于构建我们的应用镜像。如果你有私有的容器镜像仓库（如Harbor）或使用公有云仓库（如阿里云容器镜像服务ACR、Docker Hub），需要提前登录。
• 基础的YAML文件编写知识：我们主要通过编写YAML配置文件来告诉Kubernetes要创建什么。

好了，理论部分先到这里。接下来，我们进入实战环节。

2. 第一步：构建应用Docker镜像

我们的应用需要运行在容器里，所以首先要为它制作一个“集装箱”——也就是Docker镜像。

2.1 创建应用代码与依赖文件

在你的项目目录下，创建以下文件。你可以直接复制这些内容。

1. 主程序文件 (app.py) 这个文件包含了Streamlit网页界面的所有逻辑和模型调用。

import streamlit as st
import torch
from transformers import AutoModelForSpeechSeq2Seq, AutoProcessor
import librosa
import soundfile as sf
import tempfile
import os
from metrics import metric

# 设置页面为宽屏模式，标题和图标
st.set_page_config(page_title="Qwen3-ASR-0.6B 智能语音识别", page_icon="🎙️", layout="wide")

# 在侧边栏展示模型信息和特点
with st.sidebar:
    st.header("🎙️ Qwen3-ASR-0.6B 语音识别")
    st.markdown("""
    **核心特性：**
    - 🚀 **轻量高效**：6亿参数，专为本地/端侧部署优化
    - 🌐 **语种自适应**：自动检测中文、英文及中英文混合语音
    - 🔒 **隐私安全**：纯本地推理，音频数据不出本地
    - ⚡ **GPU加速**：FP16半精度推理，提升速度
    - 🎵 **格式兼容**：支持 WAV, MP3, M4A, OGG
    """)
    st.divider()
    st.caption("基于阿里云通义千问Qwen3-ASR-0.6B模型开发")

# 应用主标题
st.title("🎙️ Qwen3-ASR-0.6B 智能语音识别工具")
st.markdown("上传音频文件，自动识别其中的语音内容并转换为文字。支持中文、英文及混合语音。")

# 初始化模型和处理器（使用缓存，避免每次点击都重新加载）
@st.cache_resource
def load_model():
    model_id = "Qwen/Qwen3-ASR-0.6B"
    try:
        # 自动选择设备（优先GPU），并加载FP16精度的模型
        model = AutoModelForSpeechSeq2Seq.from_pretrained(
            model_id,
            torch_dtype=torch.float16,
            device_map="auto"
        )
        processor = AutoProcessor.from_pretrained(model_id)
        return model, processor
    except Exception as e:
        st.error(f"加载模型失败: {e}")
        return None, None

model, processor = load_model()

# 文件上传区域
uploaded_file = st.file_uploader(
    "📂 请上传音频文件 (WAV / MP3 / M4A / OGG)",
    type=["wav", "mp3", "m4a", "ogg"]
)

if uploaded_file is not None:
    # 将上传的文件保存为临时文件进行处理
    with tempfile.NamedTemporaryFile(delete=False, suffix=os.path.splitext(uploaded_file.name)[1]) as tmp_file:
        tmp_file.write(uploaded_file.read())
        tmp_path = tmp_file.name

    try:
        # 显示音频播放器
        st.audio(tmp_path)
        st.info(f"已上传文件: **{uploaded_file.name}**")

        # 识别按钮
        if st.button("🎯 开始语音识别", type="primary"):
            if model is None or processor is None:
                st.error("模型未正确加载，请检查。")
            else:
                with st.spinner("正在处理音频并识别内容..."):
                    try:
                        # 使用librosa加载音频，统一为16kHz采样率
                        speech_array, sampling_rate = librosa.load(tmp_path, sr=16000)
                        # 准备模型输入
                        inputs = processor(
                            audio=speech_array,
                            sampling_rate=sampling_rate,
                            return_tensors="pt",
                            padding=True
                        )
                        # 将输入数据移动到与模型相同的设备
                        inputs = inputs.to(model.device)
                        # 生成识别结果
                        generated_ids = model.generate(**inputs)
                        # 解码识别结果
                        transcription = processor.batch_decode(generated_ids, skip_special_tokens=True)[0]

                        # 简单判断语种（根据中文字符比例）
                        chinese_chars = sum('\u4e00' <= c <= '\u9fff' for c in transcription)
                        total_chars = len(transcription) if len(transcription) > 0 else 1
                        chinese_ratio = chinese_chars / total_chars

                        if chinese_ratio > 0.7:
                            detected_lang = "中文"
                        elif chinese_ratio < 0.3:
                            detected_lang = "英文"
                        else:
                            detected_lang = "中英文混合"

                        # 展示结果
                        st.success("✅ 识别完成！")
                        st.subheader("📊 识别结果分析")

                        # 使用columns布局并排显示语种和文本
                        col1, col2 = st.columns([1, 3])
                        with col1:
                            metric(label="检测语种", value=detected_lang, delta="")
                        with col2:
                            st.text_area("转写文本", transcription, height=200)

                    except Exception as e:
                        st.error(f"识别过程中发生错误: {e}")
                    finally:
                        # 处理完成后，删除临时文件
                        os.unlink(tmp_path)
    except Exception as e:
        st.error(f"处理上传文件时出错: {e}")
        if os.path.exists(tmp_path):
            os.unlink(tmp_path)
else:
    st.info("👆 请在上方上传一个音频文件以开始识别。")

2. 依赖文件 (requirements.txt) 这个文件告诉Docker在构建镜像时需要安装哪些Python包。

streamlit>=1.28.0
torch>=2.0.0
transformers>=4.35.0
accelerate>=0.24.0
librosa>=0.10.0
soundfile>=0.12.0

3. Docker镜像构建文件 (Dockerfile) 这是构建镜像的“说明书”，定义了从基础环境到运行应用的全部步骤。

# 使用带有Python的官方镜像作为基础
FROM python:3.10-slim

# 设置工作目录
WORKDIR /app

# 安装系统依赖（libsndfile是soundfile库需要的）
RUN apt-get update && apt-get install -y \
    libsndfile1 \
    && rm -rf /var/lib/apt/lists/*

# 复制依赖文件并安装Python包
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY app.py .

# 下载模型（可选项，也可以在运行时下载。这里预先下载能加速容器启动）
# 注意：这会使镜像体积变大。你也可以选择在应用首次运行时下载（参考app.py中的缓存机制）。
# RUN python -c "from transformers import AutoModelForSpeechSeq2Seq, AutoProcessor; \
#     AutoModelForSpeechSeq2Seq.from_pretrained('Qwen/Qwen3-ASR-0.6B', cache_dir='/app/models'); \
#     AutoProcessor.from_pretrained('Qwen/Qwen3-ASR-0.6B', cache_dir='/app/models')"

# 暴露Streamlit默认端口
EXPOSE 8501

# 设置健康检查（可选，但推荐）
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD python -c "import socket; s = socket.socket(socket.AF_INET, socket.SOCK_STREAM); s.settimeout(5); result = s.connect_ex(('127.0.0.1', 8501)); s.close(); exit(result)"

# 启动命令
CMD ["streamlit", "run", "app.py", "--server.port=8501", "--server.address=0.0.0.0"]

2.2 构建并推送镜像

现在，打开终端，进入包含以上三个文件的目录，执行以下命令。

1. 构建Docker镜像：

   docker build -t your-registry/your-username/qwen3-asr-app:1.0.0 .
   

   请将 your-registry/your-username 替换为你自己的容器镜像仓库地址和用户名，例如 harbor.mycompany.com/ai/qwen3-asr-app 或 docker.io/yourname/qwen3-asr-app。1.0.0 是标签，你可以自定义。

2. 推送镜像到仓库（如果你需要将镜像分享到集群的其他节点，或者使用云上的集群）：

   docker push your-registry/your-username/qwen3-asr-app:1.0.0
   

   执行这条命令前，请确保你已经用 docker login 登录了对应的镜像仓库。

如果你的Kubernetes集群所有节点都能访问你本地构建的镜像（例如使用minikube），或者你打算在构建镜像的机器上直接运行单节点集群，可以跳过推送步骤，在后续YAML文件中使用本地镜像。

镜像准备好之后，Kubernetes的舞台就搭好了。

3. 第二步：编写Kubernetes部署配置文件

我们将创建三个YAML文件，分别对应Deployment、Service和Ingress。你可以把它们放在同一个目录下，例如 k8s-manifests/。

3.1 创建Deployment (deployment.yaml)

Deployment负责创建和管理Pod副本。这里我们只运行1个副本，并为其请求适量的CPU和内存资源。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: qwen3-asr-deployment
  labels:
    app: qwen3-asr
spec:
  replicas: 1 # 根据实际负载调整副本数量
  selector:
    matchLabels:
      app: qwen3-asr
  template:
    metadata:
      labels:
        app: qwen3-asr
    spec:
      containers:
      - name: qwen3-asr-container
        image: your-registry/your-username/qwen3-asr-app:1.0.0 # 请替换为你的实际镜像地址
        ports:
        - containerPort: 8501 # Streamlit默认端口
        resources:
          requests:
            memory: "2Gi"   # 模型加载需要一定内存，可根据实际情况调整
            cpu: "1000m"    # 请求1个CPU核心
          limits:
            memory: "4Gi"   # 内存上限
            cpu: "2000m"    # CPU上限
        # 如果集群有GPU，可以添加以下部分来请求GPU资源，能极大加速推理
        # resources:
        #   limits:
        #     nvidia.com/gpu: 1 # 请求1块NVIDIA GPU
        env:
        - name: TRANSFORMERS_CACHE # 设置模型缓存路径，可加速后续启动
          value: "/app/models"
        livenessProbe: # 存活探针，检查应用是否健康
          httpGet:
            path: /_stcore/health
            port: 8501
          initialDelaySeconds: 60 # 给模型加载留出足够时间
          periodSeconds: 30
        readinessProbe: # 就绪探针，检查应用是否准备好接收流量
          httpGet:
            path: /
            port: 8501
          initialDelaySeconds: 90
          periodSeconds: 20

关键点说明：

• image: 务必替换成你构建并推送的镜像地址。
• resources: 这里设置了资源请求和限制。语音识别模型在推理时对内存有一定要求，2Gi内存请求是一个相对安全的起点。如果你的音频文件很大或并发请求多，可能需要增加。
• livenessProbe 和 readinessProbe: 这是生产环境部署的好习惯。它们让Kubernetes能监控应用的健康状态。注意 initialDelaySeconds 设置得比较长，是为了等待模型加载完成。
• GPU支持：注释部分展示了如何请求GPU。如果你的Kubernetes集群配备了NVIDIA GPU并安装了相应的设备插件（如 nvidia-device-plugin），取消注释并调整资源限制，可以显著提升识别速度。

3.2 创建Service (service.yaml)

Service为Pod提供一个稳定的内部访问点。

apiVersion: v1
kind: Service
metadata:
  name: qwen3-asr-service
spec:
  selector:
    app: qwen3-asr # 这个标签必须和Deployment中Pod的标签匹配
  ports:
  - port: 80        # Service对外暴露的端口
    targetPort: 8501 # 容器内应用监听的端口
    protocol: TCP
  type: ClusterIP   # 默认类型，仅在集群内部可访问

这个Service将在集群内部创建一个DNS名称 qwen3-asr-service，其他Pod可以通过这个名称和80端口访问到我们的语音识别应用。但我们现在需要从集群外部访问，所以还需要Ingress。

3.3 创建Ingress (ingress.yaml)

Ingress是外部流量进入集群的入口。请注意，你的集群必须已经安装了Ingress Controller（如Nginx Ingress Controller、Traefik等），这个配置才能生效。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: qwen3-asr-ingress
  annotations:
    # 以下注解根据你使用的Ingress Controller类型调整
    # 对于Nginx Ingress Controller的常见配置示例：
    nginx.ingress.kubernetes.io/proxy-body-size: "100m" # 允许上传大音频文件
    nginx.ingress.kubernetes.io/proxy-read-timeout: "300" # 设置较长的超时时间，因为模型推理可能需要时间
    nginx.ingress.kubernetes.io/proxy-send-timeout: "300"
spec:
  ingressClassName: nginx # 指定Ingress Class，根据你的环境修改，例如可能是“public”或其它
  rules:
  - host: asr.example.com # 请将此处替换为你想要使用的实际域名
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: qwen3-asr-service
            port:
              number: 80

关键点说明：

• host: 这是最重要的配置之一。你需要将其 asr.example.com 替换成你实际拥有的、并且DNS能解析到你Ingress Controller外部IP或负载均衡器地址的域名。
• ingressClassName: 这需要和你集群中安装的Ingress Controller匹配。常见的如 nginx、alb（AWS）、gce（GCP）等。如果不确定，可以咨询集群管理员或查看现有Ingress资源的配置。
• annotations: 这里的注解是针对Nginx Ingress Controller的。它做了两件重要的事：
  1. 将允许上传的文件大小提高到100MB（proxy-body-size），方便上传较长的音频。
  2. 将代理超时时间设置为300秒（proxy-read-timeout 和 proxy-send-timeout），防止因为模型推理时间稍长导致连接被断开。

4. 第三步：部署到Kubernetes集群并验证

所有配置文件就绪后，我们就可以开始部署了。

1. 应用配置： 在终端中，进入存放YAML文件的目录，执行以下命令：

   kubectl apply -f deployment.yaml
   kubectl apply -f service.yaml
   kubectl apply -f ingress.yaml
   

   或者，如果三个文件在同一个目录下，可以一次性应用：

   kubectl apply -f k8s-manifests/
   

2. 检查部署状态：

   • 查看Pod是否运行成功：

     kubectl get pods -l app=qwen3-asr
     

     你应该看到Pod状态为 Running，并且 READY 是 1/1。如果状态是 ContainerCreating，请稍等片刻，因为首次运行需要拉取镜像和下载模型，可能需要几分钟。如果长时间失败，可以用 kubectl describe pod <pod-name> 和 kubectl logs <pod-name> 查看详情。
   • 查看Service和Ingress：

     kubectl get svc qwen3-asr-service
     kubectl get ingress qwen3-asr-ingress
     

     查看Ingress时，关注 ADDRESS 字段，它显示了Ingress Controller分配的外部IP或主机名。

3. 配置DNS： 获取到Ingress的 ADDRESS 后（假设是 192.168.1.100 或一个负载均衡器地址），你需要将你在Ingress中配置的域名（如 asr.example.com）的DNS A记录指向这个地址。对于测试环境，你也可以直接修改本机的 hosts 文件（C:\Windows\System32\drivers\etc\hosts 或 /etc/hosts），添加一行：

   192.168.1.100 asr.example.com
   

4. 访问与测试： 完成DNS配置后，在浏览器中访问 http://asr.example.com（如果你配置了TLS证书，则是 https://）。 你应该能看到Qwen3-ASR-0.6B的Streamlit界面。尝试上传一个WAV或MP3格式的音频文件，点击播放确认后，再点击“开始语音识别”按钮。稍等片刻，就能看到识别出的文字和检测到的语种了。

5. 总结与后续建议

恭喜你！你已经成功地将一个本地语音识别服务部署到了Kubernetes生产环境中，并通过Ingress提供了外部访问能力。我们来回顾一下关键步骤和学到的要点：

1. 理解架构：我们明确了从用户访问到服务响应的完整链路：浏览器 -> Ingress -> Service -> Pod (应用容器)。
2. 容器化应用：编写了Dockerfile，将Python应用及其依赖打包成可移植的镜像，这是云原生部署的基础。
3. 定义K8s资源：通过Deployment、Service、Ingress三种核心资源，分别定义了应用的运行实例、内部访问方式和外部暴露方式。
4. 关注生产细节：在配置中考虑了资源限制（防止应用失控）、健康检查（自动恢复）、超时与文件大小（提升用户体验）等生产级要素。

后续优化建议：

• 配置管理：将模型ID、资源限制等参数抽取为ConfigMap或环境变量，便于不同环境（开发、测试、生产）的配置管理。
• 持久化存储：如果模型文件很大，可以考虑使用PersistentVolume来存储模型缓存，避免每次Pod重启都重新下载。
• 安全性：
  • 为Ingress配置TLS证书，启用HTTPS加密通信。
  • 考虑在Ingress层面增加基础认证或与OAuth集成。
  • 严格限制Pod的服务账户权限。
• 可观测性：集成日志收集（如Fluentd+Elasticsearch）和监控（如Prometheus+Grafana），方便排查问题和观察性能。
• 自动伸缩：如果预计会有波动的访问量，可以为Deployment配置Horizontal Pod Autoscaler (HPA)，根据CPU或内存使用率自动调整Pod副本数量。
• GPU支持：如果业务对识别速度要求高，且集群有GPU，务必在Deployment中配置GPU资源请求，这将带来数量级的性能提升。

通过这个实战项目，你不仅部署了一个实用的语音识别工具，更掌握了一套将AI应用进行容器化并在Kubernetes上编排部署的标准方法。这套方法可以推广到几乎任何类似的AI模型服务上。

---

获取更多AI镜像

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