qwen3-asr-transcriber

name

qwen3-asr-transcriber

description

Build, deploy, and integrate Qwen3-ASR for multilingual speech recognition, real-time transcription pipelines, and timestamp alignment. Trigger when user mentions: 語音辨識, speech recognition, ASR, transcription, 語音轉文字, Qwen3-ASR, qwen-asr, speech to text, 即時轉錄, 字幕生成, 語音轉錄, audio transcription, real-time ASR, 語音識別, voice to text, qwen-asr Python package, Qwen3ASRModel, streaming ASR, VAD pipeline. Also triggers when user needs to build apps using Qwen3-ASR, process audio files, deploy ASR locally on Windows/Linux with NVIDIA GPU, or integrate ASR into Python or C# applications.

Qwen3 ASR Transcriber Skill

快速決策樹

需要即時串流轉錄？
  ├─ Windows 環境 → VAD Pseudo-Streaming（見「Pseudo-Streaming 方案」）
  └─ Linux + GPU  → vLLM streaming 或 VAD Pseudo-Streaming

需要處理音訊/視訊檔案？
  └─ 使用 ASREngine.transcribe(audio="path/to/file.wav")

模型選擇？
  ├─ VRAM < 4GB  → Qwen/Qwen3-ASR-0.6B + float16
  └─ VRAM ≥ 6GB  → Qwen/Qwen3-ASR-1.7B + bfloat16

需要詞級時間戳？
  └─ Qwen/Qwen3-ForcedAligner-0.6B（需先取得文字結果）

語言？
  ├─ 中文（含方言）→ 設 language=None (自動) 或指定方言代碼
  └─ 其他語言 → 設 language=None 讓模型自動偵測

---

安裝

# Python 3.10+ 必要
pip install -U qwen-asr

# 驗證相容的 transformers 版本（需 >= 4.52）
python -c "import transformers; print(transformers.__version__)"

# CUDA 用戶額外安裝
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

常見安裝問題：

• "model type qwen3_asr not recognized" → pip install -U transformers 升到 4.52+
• Windows 上 FlashAttention 2 安裝困難 → 直接省略 attn_implementation 參數

---

模型選擇指南

模型	VRAM	WER (中文)	速度	推薦場景
Qwen3-ASR-0.6B	~2GB	~5.5%	快	即時轉錄、資源受限
Qwen3-ASR-1.7B	~4GB	~4.2%	中	高精度批次轉錄
Qwen3-ForcedAligner-0.6B	~2GB	N/A	快	詞級時間戳對齊

---

核心程式碼模式

基本批次轉錄

import torch
from qwen_asr import Qwen3ASRModel

# 初始化（第一次執行會自動從 HuggingFace 下載）
model = Qwen3ASRModel.from_pretrained(
    "Qwen/Qwen3-ASR-0.6B",
    dtype=torch.bfloat16,        # GPU: bfloat16 / float16；CPU: float32
    device_map="cuda:0",          # CPU 用「cpu」
    max_new_tokens=256,
)

# 轉錄（支援本地路徑、URL、numpy array）
results = model.transcribe(
    audio="path/to/audio.wav",    # 或 list[str] 批次處理
    language=None,                 # None = 自動偵測
    context=None,                  # 可注入人名/術語
)
print(results[0].text)

Context 注入（提升專有名詞精準度）

results = model.transcribe(
    audio="meeting.wav",
    language="zh",
    context="與會者：張三、李四。專有名詞：Qwen3、語音辨識、FastAPI",
)

封裝為可複用 ASREngine

from dataclasses import dataclass, field
from pathlib import Path
from typing import Iterator
import logging
import numpy as np
import torch

logger = logging.getLogger(__name__)

@dataclass
class Segment:
    start_ms: int
    end_ms: int
    text: str
    language: str = ""

@dataclass
class TranscriptionResult:
    text: str
    language: str
    segments: list[Segment] = field(default_factory=list)

class ASREngine:
    """Qwen3-ASR 推理引擎封裝。"""

    def __init__(
        self,
        model_name: str = "Qwen/Qwen3-ASR-0.6B",
        device: str = "cuda:0",
        dtype: str = "bfloat16",
        max_new_tokens: int = 256,
    ) -> None:
        self._model_name = model_name
        self._device = device
        self._dtype = getattr(torch, dtype)
        self._max_new_tokens = max_new_tokens
        self._model = None

    def load(self) -> None:
        """載入模型（首次呼叫前必須執行）。"""
        from qwen_asr import Qwen3ASRModel
        logger.info("Loading model %s on %s", self._model_name, self._device)
        try:
            self._model = Qwen3ASRModel.from_pretrained(
                self._model_name,
                dtype=self._dtype,
                device_map=self._device,
                max_new_tokens=self._max_new_tokens,
            )
        except Exception:
            logger.warning("GPU load failed, falling back to CPU float32")
            self._model = Qwen3ASRModel.from_pretrained(
                self._model_name,
                dtype=torch.float32,
                device_map="cpu",
                max_new_tokens=self._max_new_tokens,
            )

    def transcribe(
        self,
        audio: str | Path | np.ndarray,
        language: str | None = None,
        context: str | None = None,
    ) -> TranscriptionResult:
        if self._model is None:
            raise RuntimeError("Call ASREngine.load() first")
        results = self._model.transcribe(
            audio=str(audio) if isinstance(audio, Path) else audio,
            language=language,
            context=context,
        )
        raw = results[0]
        return TranscriptionResult(
            text=raw.text,
            language=getattr(raw, "language", language or ""),
        )

    def transcribe_stream(
        self,
        audio_chunks: Iterator[np.ndarray],
    ) -> Iterator[TranscriptionResult]:
        """VAD chunk 逐段推理（Pseudo-Streaming）。"""
        for chunk in audio_chunks:
            yield self.transcribe(chunk)

    @property
    def is_loaded(self) -> bool:
        return self._model is not None

    def unload(self) -> None:
        self._model = None
        torch.cuda.empty_cache()

Pseudo-Streaming（Windows 可行方案）

import queue
import threading
import numpy as np
import sounddevice as sd

SAMPLE_RATE = 16_000
CHUNK_MS    = 100          # 每 100ms 寫入一次
VAD_SILENCE = 0.5          # 靜音持續 0.5s 後切段

class PseudoStreamer:
    """麥克風 → VAD 切段 → ASREngine 逐段推理。"""

    def __init__(self, engine: ASREngine, on_result) -> None:
        self._engine   = engine
        self._on_result = on_result
        self._q: queue.Queue[np.ndarray] = queue.Queue()
        self._running  = False

    def start(self) -> None:
        self._running = True
        t = threading.Thread(target=self._worker, daemon=True)
        t.start()
        with sd.InputStream(
            samplerate=SAMPLE_RATE, channels=1, dtype="float32",
            blocksize=int(SAMPLE_RATE * CHUNK_MS / 1000),
            callback=lambda d, *_: self._q.put(d[:, 0].copy()),
        ):
            t.join()

    def stop(self) -> None:
        self._running = False

    def _worker(self) -> None:
        buf: list[np.ndarray] = []
        silence_frames = 0
        silence_thresh  = int(VAD_SILENCE * 1000 / CHUNK_MS)

        while self._running:
            try:
                chunk = self._q.get(timeout=0.2)
            except queue.Empty:
                continue

            buf.append(chunk)
            rms = float(np.sqrt(np.mean(chunk ** 2)))

            if rms < 0.01:
                silence_frames += 1
            else:
                silence_frames = 0

            if silence_frames >= silence_thresh and buf:
                audio = np.concatenate(buf)
                result = self._engine.transcribe(audio)
                self._on_result(result)
                buf.clear()
                silence_frames = 0

---

長音訊處理

# 使用 librosa 切段後批次推理
import librosa

def transcribe_long_audio(path: str, engine: ASREngine) -> list[TranscriptionResult]:
    audio, sr = librosa.load(path, sr=16_000, mono=True)
    segment_len = 30 * sr  # 30 秒一段
    results = []
    for i in range(0, len(audio), segment_len):
        chunk = audio[i : i + segment_len]
        results.append(engine.transcribe(chunk))
    return results

---

ForcedAligner 時間戳對齊

from qwen_asr import Qwen3ForcedAligner

aligner = Qwen3ForcedAligner.from_pretrained(
    "Qwen/Qwen3-ForcedAligner-0.6B",
    device_map="cuda:0",
)
# 傳入原始音訊 + 已知文字 → 取得詞級時間戳
aligned = aligner.align(
    audio="meeting.wav",
    text="您好今天我們要討論 AI 產品的開發計畫",
)
for word in aligned.words:
    print(f"[{word.start:.2f}-{word.end:.2f}] {word.text}")

---

常見問題排除

症狀	原因	解決方法
model type qwen3_asr not recognized	transformers 版本過舊	pip install -U transformers
CUDA OOM	VRAM 不足	換 0.6B 模型或設 dtype=torch.float16
No module named 'qwen_asr'	套件未安裝	pip install -U qwen-asr
轉錄結果含大量重複句	hallucination	加 postprocess 去重或提高 VAD 閾值
Windows 無法安裝 FlashAttention	不支援	省略 attn_implementation 參數即可
vLLM 在 Windows 崩潰	不原生支援	使用 transformers 後端（本 skill 預設方案）

---

部署方案摘要

方案	Windows	Streaming	VRAM	成本
qwen-asr + transformers	✅	❌（需 VAD 偽串流）	~2-4GB	免費
qwen-asr + vLLM	❌ WSL2/Docker 才可	✅	~4-6GB	免費
DashScope API	✅	✅	無需	付費

推薦（Windows）：qwen-asr + transformers 後端 + Silero VAD Pseudo-Streaming

---

參考資源

• GitHub：https://github.com/QwenLM/Qwen3-ASR
• 0.6B Model Card：https://huggingface.co/Qwen/Qwen3-ASR-0.6B
• 1.7B Model Card：https://huggingface.co/Qwen/Qwen3-ASR-1.7B
• PyPI：https://pypi.org/project/qwen-asr/
• vLLM 部署：https://docs.vllm.ai/projects/recipes/en/latest/Qwen/Qwen3-ASR.html
• Toolkit（長音訊）：https://github.com/QwenLM/Qwen3-ASR-Toolkit