环境要求
- Windows 10/11
- NVIDIA GPU（推荐 RTX 4080 及以上，16GB+ 显存）
- Python 3.12
安装步骤
1. 安装 Python 3.12
系统未预装 Python，使用 winget 安装：
winget install Python.Python.3.12 --accept-source-agreements --accept-package-agreements --silent
踩坑点：winget 安装超时可能导致 Python 环境不完整（报
No module named encodings）。如果遇到此问题，先卸载再重装：winget uninstall Python.Python.3.12 --accept-source-agreements winget install Python.Python.3.12 --accept-source-agreements --accept-package-agreements --silent
安装完成后，Python 路径为：
C:\Users\<用户名>\AppData\Local\Programs\Python\Python312\python.exe
2. 克隆仓库
cd C:\Users\<用户名>\Desktop
git clone https://github.com/QwenLM/Qwen3-ASR.git
cd Qwen3-ASR
3. 安装 qwen-asr 包
国内使用清华镜像源加速：
& "C:\Users\<用户名>\AppData\Local\Programs\Python\Python312\python.exe" -m pip install -U qwen-asr -i https://pypi.tuna.tsinghua.edu.cn/simple
踩坑点：如果直接用
pip install报No matching distribution found for numpy>=1.17，需要先单独安装 numpy：& "C:\Users\<用户名>\AppData\Local\Programs\Python\Python312\python.exe" -m pip install numpy -i https://pypi.tuna.tsinghua.edu.cn/simple
4. 安装 PyTorch CUDA 版本
这是关键步骤。默认安装的 PyTorch 是 CPU 版本，会报错：
AssertionError: Torch not compiled with CUDA enabled
必须从 PyTorch 官方源安装 CUDA 版本：
# 先卸载 CPU 版本
& "C:\Users\<用户名>\AppData\Local\Programs\Python\Python312\python.exe" -m pip uninstall torch -y
# 安装 CUDA 版本（约 3GB，需耐心等待）
& "C:\Users\<用户名>\AppData\Local\Programs\Python\Python312\python.exe" -m pip install torch --index-url https://download.pytorch.org/whl/cu129
踩坑点：
- 不能用
-i https://pypi.tuna.tsinghua.edu.cn/simple和--index-url同时使用，否则会从清华源下载 CPU 版本- 下载约 3GB，超时设置建议 900 秒以上
- 如果超时中断，重新运行命令会断点续传
验证 CUDA 是否可用：
& "C:\Users\<用户名>\AppData\Local\Programs\Python\Python312\python.exe" -c "import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))"
正确输出示例：
2.9.0+cu129
True
NVIDIA GeForce RTX 4080 SUPER
5. 下载模型
使用 ModelScope 下载（国内推荐）：
& "C:\Users\<用户名>\AppData\Local\Programs\Python\Python312\python.exe" -m pip install modelscope -i https://pypi.tuna.tsinghua.edu.cn/simple
& "C:\Users\<用户名>\AppData\Local\Programs\Python\Python312\Scripts\modelscope.exe" download --model Qwen/Qwen3-ASR-1.7B --local_dir "C:\Users\<用户名>\Desktop\qwen3-asr\models\Qwen3-ASR-1.7B"
也可以用 HuggingFace 下载：
& "C:\Users\<用户名>\AppData\Local\Programs\Python\Python312\python.exe" -m pip install -U "huggingface_hub[cli]" -i https://pypi.tuna.tsinghua.edu.cn/simple
& "C:\Users\<用户名>\AppData\Local\Programs\Python\Python312\Scripts\huggingface-cli.exe" download Qwen/Qwen3-ASR-1.7B --local-dir "C:\Users\<用户名>\Desktop\qwen3-asr\models\Qwen3-ASR-1.7B"
6. 启动 Gradio Demo
本地访问：
& "C:\Users\<用户名>\AppData\Local\Programs\Python\Python312\python.exe" "C:\Users\<用户名>\Desktop\qwen3-asr\qwen_asr\cli\demo.py" --asr-checkpoint "C:\Users\<用户名>\Desktop\qwen3-asr\models\Qwen3-ASR-1.7B" --backend transformers
局域网访问（监听 0.0.0.0）：
& "C:\Users\<用户名>\AppData\Local\Programs\Python\Python312\python.exe" "C:\Users\<用户名>\Desktop\qwen3-asr\qwen_asr\cli\demo.py" --asr-checkpoint "C:\Users\<用户名>\Desktop\qwen3-asr\models\Qwen3-ASR-1.7B" --backend transformers --ip 0.0.0.0 --port 8000
启动后访问：
- 本机：
http://localhost:8000 - 局域网其他设备：
http://<本机IP>:8000
启动参数说明
参数说明默认值--asr-checkpoint模型路径或 HuggingFace repo ID必填--aligner-checkpoint强制对齐模型路径（启用时间戳）无--backend推理后端：transformers 或 vllmtransformers--ip监听 IP0.0.0.0--port监听端口8000--cuda-visible-devices使用的 GPU 编号0--backend-kwargs后端参数（JSON 格式）无
启用时间戳功能
需要额外下载对齐模型：
& "C:\Users\<用户名>\AppData\Local\Programs\Python\Python312\Scripts\modelscope.exe" download --model Qwen/Qwen3-ForcedAligner-0.6B --local_dir "C:\Users\<用户名>\Desktop\qwen3-asr\models\Qwen3-ForcedAligner-0.6B"
启动时加上 --aligner-checkpoint：
& "C:\Users\<用户名>\AppData\Local\Programs\Python\Python312\python.exe" "C:\Users\<用户名>\Desktop\qwen3-asr\qwen_asr\cli\demo.py" ^
--asr-checkpoint "C:\Users\<用户名>\Desktop\qwen3-asr\models\Qwen3-ASR-1.7B" ^
--aligner-checkpoint "C:\Users\<用户名>\Desktop\qwen3-asr\models\Qwen3-ForcedAligner-0.6B" ^
--backend transformers ^
--ip 0.0.0.0 --port 8000
使用 vLLM 后端（更快推理）
需要额外安装 vLLM：
& "C:\Users\<用户名>\AppData\Local\Programs\Python\Python312\python.exe" -m pip install -U "qwen-asr[vllm]"
启动：
& "C:\Users\<用户名>\AppData\Local\Programs\Python\Python312\python.exe" "C:\Users\<用户名>\Desktop\qwen3-asr\qwen_asr\cli\demo.py" ^
--asr-checkpoint "C:\Users\<用户名>\Desktop\qwen3-asr\models\Qwen3-ASR-1.7B" ^
--backend vllm ^
--ip 0.0.0.0 --port 8000
常见问题
1. No module named qwen_asr.demo
不要用 python -m qwen_asr.demo，直接运行 demo.py 文件：
& "C:\Users\<用户名>\AppData\Local\Programs\Python\Python312\python.exe" "C:\Users\<用户名>\Desktop\qwen3-asr\qwen_asr\cli\demo.py" ...
2. Torch not compiled with CUDA enabled
PyTorch 是 CPU 版本，需要按步骤 4 重装 CUDA 版本。
3. Could not find platform independent libraries <prefix>
Python 安装不完整，需要卸载后重新安装。
4. pip 下载慢
使用清华镜像源：
-i https://pypi.tuna.tsinghua.edu.cn/simple
5. 模型下载失败
国内推荐使用 ModelScope 而不是 HuggingFace。
完整一键安装脚本
将以下内容保存为 install.ps1，以管理员身份运行：
# 安装 Python（如果未安装）
winget install Python.Python.3.12 --accept-source-agreements --accept-package-agreements --silent
$PYTHON = "C:\Users\$env:USERNAME\AppData\Local\Programs\Python\Python312\python.exe"
$PIP = "$PYTHON -m pip"
# 安装 qwen-asr
& $PYTHON -m pip install numpy -i https://pypi.tuna.tsinghua.edu.cn/simple
& $PYTHON -m pip install -U qwen-asr -i https://pypi.tuna.tsinghua.edu.cn/simple
# 卸载 CPU 版 PyTorch，安装 CUDA 版
& $PYTHON -m pip uninstall torch -y
& $PYTHON -m pip install torch --index-url https://download.pytorch.org/whl/cu129
# 安装 ModelScope 并下载模型
& $PYTHON -m pip install modelscope -i https://pypi.tuna.tsinghua.edu.cn/simple
& "C:\Users\$env:USERNAME\AppData\Local\Programs\Python\Python312\Scripts\modelscope.exe" download --model Qwen/Qwen3-ASR-1.7B --local_dir "C:\Users\$env:USERNAME\Desktop\qwen3-asr\models\Qwen3-ASR-1.7B"
Write-Host "安装完成！启动命令："
Write-Host "& `"$PYTHON`" `"C:\Users\$env:USERNAME\Desktop\qwen3-asr\qwen_asr\cli\demo.py`" --asr-checkpoint `"C:\Users\$env:USERNAME\Desktop\qwen3-asr\models\Qwen3-ASR-1.7B`" --backend transformers --ip 0.0.0.0 --port 8000"
评论