Qwen3-ASR-1.7B开源大模型教程：PyTorch 2.5.0 + CUDA 12.4环境配置

Qwen3-ASR-1.7B开源大模型教程PyTorch 2.5.0 CUDA 12.4环境配置1. 引言为什么选择Qwen3-ASR-1.7B如果你正在寻找一个开箱即用、功能强大的语音识别解决方案Qwen3-ASR-1.7B绝对值得你花时间了解。这个由阿里通义千问团队推出的端到端语音识别模型在很多方面都让人眼前一亮。想象一下这样的场景你需要把一段会议录音转成文字但录音里既有中文又有英文还可能夹杂着一些专业术语。传统方案要么需要切换不同模型要么识别准确率不够理想。Qwen3-ASR-1.7B直接解决了这个问题——它支持中、英、日、韩、粤五种语言还能自动检测当前说的是什么语言完全不需要你手动切换。更让人惊喜的是这个模型在完全离线环境下就能运行。这意味着你的音频数据不需要上传到任何云端服务器特别适合处理敏感内容或者在没有网络的环境中使用。模型大小17亿参数听起来不小但实际部署起来比想象中要简单得多。在这篇教程里我会手把手带你完成整个环境配置和部署过程。无论你是语音识别的新手还是有一定经验的开发者都能跟着步骤快速上手。我们用的环境是PyTorch 2.5.0 CUDA 12.4这是目前比较新的组合能充分发挥GPU的性能优势。2. 环境准备你需要什么2.1 硬件要求在开始之前我们先看看需要什么样的硬件环境。Qwen3-ASR-1.7B对硬件的要求比较明确主要是显存和存储空间。显存要求这是最关键的一点。模型推理时大约需要10-14GB的显存。这个数字包含了模型权重5.5GB和推理过程中的临时缓存。如果你用的是RTX 309024GB、RTX 409024GB或者A10040GB/80GB那完全没问题。如果是RTX 308010GB或者RTX 407012GB也能运行但可能需要在一些设置上做些调整。存储空间你需要准备大约15GB的可用磁盘空间。这包括模型文件5.5GB两个分片文件Python环境3-4GB临时文件和工作空间2-3GB其他硬件CPU要求不高现代的多核处理器都能胜任。内存建议16GB以上这样运行起来会更流畅。2.2 软件环境软件环境我们选择的是比较新的组合这样既能保证稳定性又能获得更好的性能。操作系统推荐使用Ubuntu 20.04或22.04。这两个版本都有很好的CUDA支持和社区维护。如果你用Windows也不是不行但Linux环境下的部署会更顺畅一些。Python版本我们使用Python 3.11。这个版本在性能和兼容性上都有不错的表现。不建议用太老的Python版本因为一些新的依赖包可能不支持。CUDA版本CUDA 12.4。这是NVIDIA最新的稳定版本之一对新一代GPU有更好的支持。如果你用的是比较老的GPU比如30系列之前的可能需要用CUDA 11.x版本但整体流程是类似的。PyTorch版本PyTorch 2.5.0。这个版本修复了很多之前的问题而且在推理性能上有明显提升。3. 一步步搭建环境3.1 第一步安装CUDA 12.4CUDA是NVIDIA的GPU计算平台我们需要先把它装好。如果你已经装了其他版本的CUDA建议先卸载干净避免版本冲突。打开终端执行以下命令# 下载CUDA 12.4的安装包 wget https://developer.download.nvidia.com/compute/cuda/12.4.0/local_installers/cuda_12.4.0_550.54.14_linux.run # 给安装包添加执行权限 chmod x cuda_12.4.0_550.54.14_linux.run # 运行安装程序 sudo ./cuda_12.4.0_550.54.14_linux.run安装过程中有几个选项需要注意当问你是否接受许可协议时输入accept然后回车在组件选择界面确保CUDA Toolkit 12.4被选中其他组件可以根据需要选择驱动安装部分如果你已经装了合适的NVIDIA驱动可以取消选择Driver避免重复安装安装完成后需要配置环境变量。编辑你的~/.bashrc文件nano ~/.bashrc在文件末尾添加这几行export PATH/usr/local/cuda-12.4/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda-12.4/lib64:$LD_LIBRARY_PATH export CUDA_HOME/usr/local/cuda-12.4保存退出后让配置生效source ~/.bashrc验证安装是否成功nvcc --version如果看到类似Cuda compilation tools, release 12.4的输出说明CUDA安装成功了。3.2 第二步安装PyTorch 2.5.0PyTorch的安装现在很简单直接用pip就能搞定。但要注意选择正确的版本确保和CUDA 12.4兼容。# 创建并激活Python虚拟环境推荐 python3.11 -m venv asr_env source asr_env/bin/activate # 安装PyTorch 2.5.0 CUDA 12.4 pip install torch2.5.0 torchvision0.20.0 torchaudio2.5.0 --index-url https://download.pytorch.org/whl/cu124这里有几个细节需要注意cu124表示CUDA 12.4一定要写对如果你用的是其他CUDA版本需要调整这个后缀安装过程可能会比较慢因为要下载比较大的文件安装完成后验证PyTorch是否能正确识别GPUimport torch print(fPyTorch版本: {torch.__version__}) print(fCUDA是否可用: {torch.cuda.is_available()}) print(fGPU数量: {torch.cuda.device_count()}) print(f当前GPU: {torch.cuda.get_device_name(0)})如果一切正常你应该能看到类似这样的输出PyTorch版本: 2.5.0cu124 CUDA是否可用: True GPU数量: 1 当前GPU: NVIDIA GeForce RTX 40903.3 第三步安装其他依赖包除了PyTorch我们还需要一些其他的Python包。这些包主要是用于Web服务、音频处理和模型加载。创建一个requirements.txt文件fastapi0.104.1 gradio4.13.0 uvicorn[standard]0.24.0 numpy1.24.3 scipy1.11.4 librosa0.10.1 soundfile0.12.1 transformers4.36.2 accelerate0.25.0 safetensors0.4.1 qwen-asr0.1.0然后一次性安装所有依赖pip install -r requirements.txt这里特别说明一下几个关键的包fastapi和gradio用于构建Web界面和API服务librosa和soundfile处理音频文件qwen-asr这是阿里官方的SDK封装了模型的加载和推理逻辑如果安装qwen-asr时遇到问题可能是因为网络原因。你可以尝试从镜像源安装pip install qwen-asr -i https://pypi.tuna.tsinghua.edu.cn/simple4. 下载和配置模型4.1 获取模型文件Qwen3-ASR-1.7B的模型文件可以从魔搭社区下载。官方提供了两个分片文件总共约5.5GB。我们先创建一个目录来存放模型mkdir -p models/Qwen3-ASR-1.7B cd models/Qwen3-ASR-1.7B如果你能直接访问魔搭社区可以用git命令下载git lfs install git clone https://www.modelscope.cn/qwen/Qwen3-ASR-1.7B.git .如果网络不太稳定也可以手动下载。模型文件通常包括model.safetensors.index.json模型索引文件model-00001-of-00002.safetensors第一个分片model-00002-of-00002.safetensors第二个分片config.json模型配置文件tokenizer.json等分词器文件4.2 验证模型完整性下载完成后最好验证一下文件是否完整。可以检查文件大小和数量# 查看文件列表 ls -lh # 预期的输出应该类似这样 # -rw-r--r-- 1 user user 15K Dec 1 10:30 config.json # -rw-r--r-- 1 user user 2.8G Dec 1 10:30 model-00001-of-00002.safetensors # -rw-r--r-- 1 user user 2.7G Dec 1 10:31 model-00002-of-00002.safetensors # -rw-r--r-- 1 user user 1.2M Dec 1 10:30 tokenizer.json两个.safetensors文件加起来应该是5.5GB左右。如果大小不对可能需要重新下载。5. 编写启动脚本5.1 创建启动脚本为了让使用更方便我们创建一个启动脚本。这个脚本会启动两个服务FastAPI后端和Gradio前端。创建一个名为start_asr_1.7b.sh的文件#!/bin/bash # 设置环境变量 export PYTHONPATH/path/to/your/project:$PYTHONPATH export MODEL_PATH/path/to/models/Qwen3-ASR-1.7B # 激活虚拟环境 source /path/to/asr_env/bin/activate # 启动FastAPI后端服务 echo 启动FastAPI后端服务端口7861... uvicorn asr_api:app --host 0.0.0.0 --port 7861 --reload # 等待后端启动 sleep 5 # 启动Gradio前端服务 echo 启动Gradio前端界面端口7860... python gradio_ui.py记得修改脚本中的路径确保指向你实际的项目目录和模型目录。给脚本添加执行权限chmod x start_asr_1.7b.sh5.2 创建API服务文件接下来创建FastAPI的后端服务。新建一个asr_api.py文件from fastapi import FastAPI, File, UploadFile, HTTPException from fastapi.responses import JSONResponse import torch import torchaudio import numpy as np from typing import Optional import tempfile import os import time # 导入qwen-asr from qwen_asr import QwenASRPipeline app FastAPI(titleQwen3-ASR-1.7B API服务) # 全局变量用于缓存模型 _model None _device None def load_model(): 加载ASR模型 global _model, _device if _model is not None: return _model, _device print(正在加载Qwen3-ASR-1.7B模型...) start_time time.time() # 设置设备 _device cuda if torch.cuda.is_available() else cpu print(f使用设备: {_device}) # 加载模型 try: # 这里需要根据你的实际模型路径调整 model_path /path/to/models/Qwen3-ASR-1.7B _model QwenASRPipeline.from_pretrained( model_path, torch_dtypetorch.float16 if _device cuda else torch.float32, device_map_device ) print(f模型加载完成耗时: {time.time() - start_time:.2f}秒) except Exception as e: print(f模型加载失败: {e}) raise return _model, _device app.on_event(startup) async def startup_event(): 应用启动时加载模型 load_model() app.post(/api/transcribe) async def transcribe_audio( audio_file: UploadFile File(...), language: Optional[str] auto ): 转录音频文件 Args: audio_file: 上传的音频文件WAV格式 language: 语言代码可选值auto, zh, en, ja, ko, yue # 检查文件类型 if not audio_file.filename.lower().endswith(.wav): raise HTTPException(status_code400, detail只支持WAV格式音频文件) # 加载模型 model, device load_model() # 保存上传的文件到临时位置 with tempfile.NamedTemporaryFile(deleteFalse, suffix.wav) as tmp_file: content await audio_file.read() tmp_file.write(content) tmp_path tmp_file.name try: # 读取音频文件 waveform, sample_rate torchaudio.load(tmp_path) # 转换为单声道如果需要 if waveform.shape[0] 1: waveform waveform.mean(dim0, keepdimTrue) # 重采样到16kHz如果需要 if sample_rate ! 16000: resampler torchaudio.transforms.Resample(sample_rate, 16000) waveform resampler(waveform) # 转换为numpy数组 audio_np waveform.numpy().squeeze() # 执行语音识别 start_time time.time() result model( audio_np, languagelanguage, tasktranscribe ) inference_time time.time() - start_time # 清理临时文件 os.unlink(tmp_path) # 返回结果 return JSONResponse({ status: success, language: result.get(language, unknown), text: result.get(text, ), inference_time: f{inference_time:.2f}秒, audio_duration: f{len(audio_np) / 16000:.2f}秒 }) except Exception as e: # 清理临时文件 if os.path.exists(tmp_path): os.unlink(tmp_path) raise HTTPException(status_code500, detailf处理失败: {str(e)}) app.get(/api/health) async def health_check(): 健康检查接口 return {status: healthy, model_loaded: _model is not None} if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port7861)5.3 创建Web界面再创建一个Gradio的前端界面文件gradio_ui.pyimport gradio as gr import requests import json import tempfile import os # API地址 API_URL http://localhost:7861/api/transcribe def transcribe_audio(audio_file, language): 调用API进行语音识别 Args: audio_file: 上传的音频文件 language: 选择的语言 if audio_file is None: return 请先上传音频文件, , try: # 准备文件 files {audio_file: open(audio_file, rb)} data {language: language} # 调用API response requests.post(API_URL, filesfiles, datadata) # 关闭文件 files[audio_file].close() if response.status_code 200: result response.json() # 格式化输出 language_map { zh: 中文, en: 英文, ja: 日语, ko: 韩语, yue: 粤语, auto: 自动检测 } detected_lang result.get(language, auto) display_lang language_map.get(detected_lang, detected_lang) formatted_output f 识别结果 ━━━━━━━━━━━━━━━━━━━ 识别语言{display_lang} 识别内容{result.get(text, )} ━━━━━━━━━━━━━━━━━━━ ⏱️ 处理时间{result.get(inference_time, N/A)} 音频时长{result.get(audio_duration, N/A)} return formatted_output, result.get(text, ), display_lang else: error_msg fAPI调用失败: {response.status_code}\n{response.text} return error_msg, , except Exception as e: return f处理过程中出错: {str(e)}, , # 创建Gradio界面 with gr.Blocks(titleQwen3-ASR-1.7B 语音识别系统, themegr.themes.Soft()) as demo: gr.Markdown(# Qwen3-ASR-1.7B 语音识别系统) gr.Markdown(上传WAV格式音频文件选择识别语言点击开始识别) with gr.Row(): with gr.Column(scale1): # 语言选择 language gr.Dropdown( choices[auto, zh, en, ja, ko, yue], valueauto, label识别语言, infoauto: 自动检测语言zh: 中文en: 英文ja: 日语ko: 韩语yue: 粤语 ) # 音频上传 audio_input gr.Audio( typefilepath, label上传音频文件, info支持WAV格式建议时长5-30秒 ) # 识别按钮 transcribe_btn gr.Button( 开始识别, variantprimary) with gr.Column(scale2): # 结果显示 output_text gr.Textbox( label识别结果, lines10, interactiveFalse ) # 原始文本隐藏用于复制 raw_text gr.Textbox(label原始文本, visibleFalse) detected_lang gr.Textbox(label检测到的语言, visibleFalse) # 示例音频 gr.Markdown(### 示例音频) with gr.Row(): gr.Examples( examples[ [examples/chinese_sample.wav, zh], [examples/english_sample.wav, en], [examples/japanese_sample.wav, ja] ], inputs[audio_input, language], label点击示例快速测试 ) # 绑定事件 transcribe_btn.click( fntranscribe_audio, inputs[audio_input, language], outputs[output_text, raw_text, detected_lang] ) # 说明文字 gr.Markdown( ### 使用说明 1. **上传音频**点击上传按钮选择WAV格式的音频文件 2. **选择语言**如果知道音频语言选择对应选项不确定就选auto 3. **开始识别**点击开始识别按钮等待1-3秒 4. **查看结果**识别结果会显示在右侧文本框 ### 注意事项 - 支持中文、英文、日语、韩语、粤语五种语言 - 自动检测模式auto可以识别音频中的语言类型 - 建议使用16kHz采样率的单声道WAV文件 - 单次处理建议不超过5分钟音频 ) if __name__ __main__: demo.launch( server_name0.0.0.0, server_port7860, shareFalse )6. 启动和测试服务6.1 启动服务现在一切准备就绪我们可以启动服务了。确保你在项目根目录然后运行bash start_asr_1.7b.sh你会看到类似这样的输出启动FastAPI后端服务端口7861... INFO: Started server process [12345] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:7861 (Press CTRLC to quit) 正在加载Qwen3-ASR-1.7B模型... 使用设备: cuda 模型加载完成耗时: 18.23秒 启动Gradio前端界面端口7860... Running on local URL: http://0.0.0.0:7860第一次启动时模型加载需要一些时间大约15-20秒因为要把5.5GB的模型权重加载到GPU显存中。之后再次启动就会快很多。6.2 测试服务打开浏览器访问http://你的服务器IP:7860就能看到Web界面了。我们来做个简单的测试准备测试音频你可以用手机录一段5-10秒的语音保存为WAV格式。如果不想录音也可以用下面的Python代码生成一个测试文件import numpy as np import soundfile as sf # 生成一段测试音频中文 sample_rate 16000 duration 5 # 5秒 t np.linspace(0, duration, int(sample_rate * duration)) # 生成一个简单的音调 audio 0.5 * np.sin(2 * np.pi * 440 * t) # 440Hz的正弦波 # 保存为WAV文件 sf.write(test_audio.wav, audio, sample_rate) print(测试音频已保存为 test_audio.wav)在Web界面上传音频点击上传音频文件区域选择你刚才创建的test_audio.wav文件在语言选择下拉框中选择zh中文或者保持auto开始识别点击 开始识别按钮按钮会变成识别中...并暂时禁用等待1-3秒结果会显示在右侧查看结果 如果一切正常你会看到格式化的识别结果包括检测到的语言和转写的文字。6.3 API接口测试除了Web界面你也可以直接测试API接口。打开另一个终端用curl命令测试# 测试健康检查接口 curl http://localhost:7861/api/health # 上传音频文件进行识别 curl -X POST http://localhost:7861/api/transcribe \ -F audio_filetest_audio.wav \ -F languagezhAPI会返回JSON格式的结果{ status: success, language: Chinese, text: 这是一个测试音频文件, inference_time: 1.23秒, audio_duration: 5.00秒 }7. 常见问题解决在部署和使用过程中你可能会遇到一些问题。这里整理了一些常见问题和解决方法。7.1 模型加载失败问题现象启动时卡在正在加载模型或者报错退出。可能原因和解决显存不足检查GPU显存是否足够10GB。可以用nvidia-smi命令查看。nvidia-smi如果显存不足可以尝试关闭其他占用显存的程序使用torch.float32而不是torch.float16但需要更多显存换用更大显存的GPU模型文件损坏重新下载模型文件确保两个.safetensors文件完整。# 检查文件大小 ls -lh model-*.safetensors # 应该看到两个2.7G左右的文件CUDA版本不匹配确保PyTorch版本和CUDA版本匹配。import torch print(torch.version.cuda) # 应该输出12.47.2 音频处理问题问题现象上传音频后识别失败或者识别结果乱码。可能原因和解决音频格式不支持目前只支持WAV格式。如果是MP3或其他格式需要先转换。# 用pydub转换音频格式 from pydub import AudioSegment # MP3转WAV audio AudioSegment.from_mp3(input.mp3) audio.export(output.wav, formatwav)采样率问题模型要求16kHz采样率。如果音频不是这个采样率可以这样转换import librosa import soundfile as sf # 读取并重采样 y, sr librosa.load(input.wav, sr16000) sf.write(output_16k.wav, y, 16000)音频太长建议单次处理不超过5分钟。如果音频太长可以分段处理import numpy as np def split_audio(audio, sr, segment_duration300): # 300秒5分钟 segment_length segment_duration * sr num_segments int(np.ceil(len(audio) / segment_length)) segments [] for i in range(num_segments): start i * segment_length end min((i 1) * segment_length, len(audio)) segments.append(audio[start:end]) return segments7.3 性能优化建议如果你发现识别速度不够快或者想优化资源使用可以试试这些方法批处理如果需要处理多个音频文件可以批量处理提高效率。# 批量处理示例 def batch_transcribe(audio_files, languageauto): results [] for audio_file in audio_files: result transcribe_audio(audio_file, language) results.append(result) return results调整精度如果显存紧张可以尝试使用8位量化需要模型支持。# 注意Qwen3-ASR-1.7B可能需要特定配置支持8位推理 model QwenASRPipeline.from_pretrained( model_path, torch_dtypetorch.float16, load_in_8bitTrue, # 8位量化 device_mapauto )使用更快的存储如果模型加载很慢可以尝试把模型放在SSD而不是HDD上。8. 实际应用示例8.1 会议录音转文字假设你有一段会议录音需要转成文字稿。录音里可能有不同人的发言还有中英文混杂的情况。import os from datetime import datetime def meeting_transcription(audio_path, output_dirtranscripts): 处理会议录音生成带时间戳的文字稿 Args: audio_path: 会议录音文件路径 output_dir: 输出目录 # 创建输出目录 os.makedirs(output_dir, exist_okTrue) # 生成输出文件名 timestamp datetime.now().strftime(%Y%m%d_%H%M%S) output_file os.path.join(output_dir, fmeeting_{timestamp}.txt) # 识别音频 result transcribe_audio(audio_path, languageauto) # 保存结果 with open(output_file, w, encodingutf-8) as f: f.write(f会议转录记录 - {timestamp}\n) f.write( * 50 \n\n) f.write(f检测语言: {result[language]}\n) f.write(f转录内容:\n\n{result[text]}\n\n) f.write( * 50 \n) f.write(f处理时间: {result[inference_time]}\n) f.write(f音频时长: {result[audio_duration]}\n) print(f转录完成结果已保存到: {output_file}) return output_file # 使用示例 meeting_transcription(meeting_recording.wav)8.2 多语言内容审核如果你需要审核包含多种语言的音频内容可以用自动检测模式def content_moderation(audio_path, keywords): 内容审核检查音频中是否包含敏感关键词 Args: audio_path: 音频文件路径 keywords: 敏感关键词列表 # 识别音频内容 result transcribe_audio(audio_path, languageauto) text result[text].lower() detected_lang result[language] print(f检测到语言: {detected_lang}) print(f转录内容: {text[:200]}...) # 只显示前200字符 # 检查关键词 found_keywords [] for keyword in keywords: if keyword.lower() in text: found_keywords.append(keyword) if found_keywords: print(f⚠️ 发现敏感词: {, .join(found_keywords)}) return False, found_keywords else: print(✅ 内容审核通过) return True, [] # 使用示例 keywords [暴力, 攻击, 违禁, illegal, attack] content_moderation(user_audio.wav, keywords)8.3 集成到现有系统如果你想把语音识别集成到自己的系统中可以这样调用APIimport requests import json class ASRClient: 语音识别客户端 def __init__(self, api_urlhttp://localhost:7861): self.api_url api_url def transcribe(self, audio_path, languageauto): 转录音频文件 with open(audio_path, rb) as f: files {audio_file: f} data {language: language} response requests.post( f{self.api_url}/api/transcribe, filesfiles, datadata ) if response.status_code 200: return response.json() else: raise Exception(fAPI调用失败: {response.status_code}) def batch_transcribe(self, audio_paths, languageauto): 批量转录 results [] for path in audio_paths: try: result self.transcribe(path, language) results.append({ file: path, success: True, result: result }) except Exception as e: results.append({ file: path, success: False, error: str(e) }) return results # 使用示例 client ASRClient() result client.transcribe(test.wav, languagezh) print(f识别结果: {result[text]})9. 总结通过这篇教程你应该已经成功搭建了Qwen3-ASR-1.7B的完整运行环境。我们来回顾一下关键步骤环境搭建的核心要点硬件准备确保有足够的GPU显存10-14GB软件安装正确安装CUDA 12.4和PyTorch 2.5.0模型下载从魔搭社区获取完整的模型文件服务部署配置FastAPI后端和Gradio前端测试验证通过Web界面和API接口测试功能这个方案的主要优势多语言支持一套模型处理五种语言还能自动检测完全离线数据不需要上传到云端保护隐私部署简单预置的镜像和脚本让部署变得很容易性能不错实时因子RTF0.310秒音频只要1-3秒就能处理完实际使用建议音频预处理尽量使用16kHz、单声道的WAV文件分段处理长音频先切成5分钟以内的小段语言选择如果知道音频语言明确指定可以提高准确率错误处理在代码中加入适当的异常处理和重试机制下一步可以探索的方向性能优化尝试批处理、量化等优化手段功能扩展集成VAD语音活动检测分割长音频系统集成把语音识别集成到你的业务系统中定制化如果需要特定领域的识别可以考虑微调模型语音识别技术正在快速发展Qwen3-ASR-1.7B作为一个开源方案为开发者提供了一个很好的起点。无论是做会议转录、内容审核还是构建语音交互应用这个模型都能提供不错的支持。最重要的是整个系统可以在你的本地环境运行不需要依赖任何外部服务。这对于数据安全要求高的场景特别有价值。希望这篇教程能帮助你快速上手。如果在部署过程中遇到问题或者有新的使用心得欢迎分享交流。技术总是在实践中不断进步的动手试试看你会发现语音识别并没有想象中那么复杂。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。