qwen-asr

用途

qwen-asr 是一个语音转文字（Speech-to-Text）技能，使用 Qwen3-ASR 模型在本地运行，通过 FastAPI 提供 HTTP 服务。它面向 Apple Silicon 设备优化，适合需要在本地完成音频转录、不希望依赖云端服务的场景。

主要能力

模型：mlx-community/Qwen3-ASR-0.6B-4bit（4 位量化，约 400MB）
运行时：MLX（通过 MPS 实现 Apple Silicon GPU 加速）
服务：FastAPI，默认地址 http://localhost:8100
支持语言：中文、英文、日文、韩文等
支持转录本地音频文件与在线音频 URL
支持指定语言参数

使用方式

首次部署

前置条件：

macOS 且为 Apple Silicon（M1/M2/M3/M4）
Python 3.10+
不需要 Docker（原生运行）

步骤：

创建虚拟环境

cd /path/to/skills/skills/qwen-asr
python3 -m venv venv
source venv/bin/activate

安装依赖

pip install -r service/requirements.txt

模型从 ModelScope/HuggingFace 镜像下载（国内更快）。

启动服务

bash service/start.sh

首次启动时会自动从 hf-mirror.com 下载模型（约 400MB），后续启动使用本地缓存。

验证

# 检查服务健康状态
curl http://localhost:8100/health

# 查看模型信息
curl http://localhost:8100/info

# 测试转录（使用在线音频）
curl -X POST "http://localhost:8100/transcribe_url?audio_url=https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-ASR-Repo/asr_en.wav"

（可选）设为系统服务

macOS 上可以使用 launchd 设置开机自启：

# 创建 plist（自行修改路径）
cat > ~/Library/LaunchAgents/com.qwen.asr.plist << 'PLIST'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.qwen.asr</string>
    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>-c</string>
        <string>cd /path/to/skills/skills/qwen-asr && bash service/start.sh</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/qwen-asr.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/qwen-asr.err</string>
</dict>
</plist>
PLIST

launchctl load ~/Library/LaunchAgents/com.qwen.asr.plist

服务端点

Endpoint	Method	Description
/health	GET	Health check
/info	GET	Model information
/transcribe	POST	Transcribe uploaded audio file
/transcribe_url	POST	Transcribe audio from URL

使用示例

CLI 客户端：

# Transcribe local file
python3 scripts/asr.py audio.wav

# Transcribe from URL
python3 scripts/asr.py --url "https://example.com/audio.wav"

# Specify language
python3 scripts/asr.py audio.wav --lang zh

# Check service status
python3 scripts/asr.py --check

curl：

# Upload file
curl -X POST "http://localhost:8100/transcribe" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@audio.wav"

# From URL with language
curl -X POST "http://localhost:8100/transcribe_url?audio_url=<URL>&language=zh"

Python：

import requests

# From URL
response = requests.post(
    "http://localhost:8100/transcribe_url",
    params={"audio_url": "https://example.com/audio.wav", "language": "zh"}
)
text = response.json()["text"]

# From file
with open("audio.wav", "rb") as f:
    response = requests.post("http://localhost:8100/transcribe", files={"file": f})
text = response.json()["text"]

输出格式

{
  "text": "transcribed text here",
  "chunks": [],
  "processing_time": 0.123
}

服务管理

# Start
bash service/start.sh

# Check status
python3 scripts/asr.py --check

# Stop (find and kill process)
lsof -ti :8100 | xargs kill

适用场景

在 Apple Silicon Mac 上本地转录音频文件
转录在线音频 URL
需要中文、英文、日文、韩文等多语言语音识别的场景
希望通过 HTTP API 或 CLI 集成语音转文字能力的开发场景

限制

仅支持 macOS 且为 Apple Silicon（M1/M2/M3/M4）
需要 Python 3.10+
首次启动需下载约 400MB 模型
首次加载模型约需 10-30 秒
音频格式支持 wav/mp3/ogg/flac
音频过短可能导致转录结果为空

故障排查

问题	解决方法
端口 8100 被占用	lsof -i :8100 找到占用进程，或修改 start.sh 中端口号
模型下载缓慢	脚本已自动设置 HF_ENDPOINT=https://hf-mirror.com
503 Model not loaded	模型仍在加载中，首次约需 10-30 秒
ModuleNotFoundError: mlx	确认使用 Apple Silicon Mac
转录结果为空	检查音频格式（支持 wav/mp3/ogg/flac），或音频可能太短