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 相同程式碼呼叫的開發者，同時希望在不依賴外部雲端服務的前提下，獲得可選的說話人分離與即時串流傳輸功能。