| 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 讓模型自動偵測
安裝
pip install -U qwen-asr
python -c "import transformers; print(transformers.__version__)"
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
model = Qwen3ASRModel.from_pretrained(
"Qwen/Qwen3-ASR-0.6B",
dtype=torch.bfloat16,
device_map="cuda:0",
max_new_tokens=256,
)
results = model.transcribe(
audio="path/to/audio.wav",
language=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
VAD_SILENCE = 0.5
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
長音訊處理
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
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
參考資源
