Quantatirsk/qwen3-asr

Qwen3‑ASR — 本地语音识别API服务

是什么 – 一个开箱即用的服务器，封装了开源的 Qwen3‑ASR 语音转文本模型（0.6 B 和 1.7 B），并通过熟悉的 OpenAI 兼容 和 阿里云兼容 HTTP 与 WebSocket 端点暴露接口。可在 GPU 上使用官方 vLLM 后端，或在 CPU/macOS 上使用内嵌的 Rust 后端运行，自动根据主机环境选择最佳运行时。

核心功能

• 混合运行时 – GPU → vLLM，CPU/macOS → 基于 Rust 的 QwenASR。
• 说话人分离 – 支持多说话人检测（CAM++ 模型）与自动说话人标注。
• 实时流式传输 – 使用 WebSocket API（Paraformer + Qwen3‑ASR）实现低延迟转录。
• 智能音频处理 – 基于 VAD 的分段、远场降噪、批量推理（GPU 上可提速 2–3 倍）。
• API 兼容性 – 兼容 OpenAI /v1/audio/transcriptions 端点和阿里云语音 REST/WebSocket 协议，现有客户端代码可直接指向本地服务器。
• 资源感知模型选择 – 根据 VRAM 自动选择 0.6 B 或 1.7 B 模型；可通过 QWEN3_ASR_MODEL 覆盖。

如何运行

1. Docker（推荐） – 将 .env.example 复制为 .env，如需 API 密钥可编辑，然后：

   docker-compose up -d               # GPU 镜像（默认）
   # 或仅 CPU
   docker-compose -f docker-compose-cpu.yml up -d
   

   服务可通过 http://localhost:17003 访问，Swagger 文档位于 /docs。
2. 自定义 GPU 构建 – 仓库提供 Dockerfile.gpu 和构建参数，支持 CUDA 12.6、12.8（默认）或 13.0。
3. 离线部署 – 在联网机器上运行 ./scripts/prepare-models.sh，打包生成的 qwen3-asr-models-*.tar.gz，复制到目标主机，解压后使用 Docker Compose 启动。
4. 本地开发 – 安装 Python 3.10+ 后：

   uv sync                     # GPU 环境（CPU 用 ./scripts/sync_cpu_env.sh）
   source .venv/bin/activate
   python start.py
   

   macOS/Apple Silicon 会自动使用 Rust 后端。

使用 API

• OpenAI 风格（POST /v1/audio/transcriptions）：

  from openai import OpenAI
  client = OpenAI(base_url="http://localhost:8000/v1", api_key="my_key")
  with open("audio.wav", "rb") as f:
      resp = client.audio.transcriptions.create(file=f, response_format="verbose_json")
  print(resp.text)
  

• 阿里云风格（POST /stream/v1/asr 或 WebSocket /ws/v1/asr/qwen）。
• 支持的响应格式：json、text、srt、vtt、verbose_json。
• 参数可启用/禁用说话人分离，请求词级时间戳（仅限离线端点），并提供语言提示。

支持的模型

模型 ID	大小	典型 VRAM 需求	说明
qwen3-asr-1.7b	1.7 B	≥ 32 GB	更高精度，多语言（52+ 语种及方言）
qwen3-asr-0.6b	0.6 B	< 32 GB	轻量级，可通过 Rust 在 CPU/macOS 上运行

许可证 – MIT（参见 LICENSE）。

谁会使用它 – 需要一个可自我托管、注重隐私的语音转文本服务，且能使用与 OpenAI 或阿里云语音 API 相同代码调用的开发者，同时希望在不依赖外部云服务的前提下，获得可选的说话人分离和实时流式传输功能。