当前位置：首页 > news >正文

Qwen3-ASR-1.7B代码实例：Python调用本地模型实现批量音频转文字脚本

news 2026/3/27 4:00:03

Qwen3-ASR-1.7B代码实例：Python调用本地模型实现批量音频转文字脚本

你是不是也遇到过这样的烦恼？手头有一堆会议录音、访谈音频或者视频素材，需要把它们整理成文字稿。手动听写？效率太低。用在线工具？又担心隐私泄露，而且文件一多，上传下载也麻烦。

今天，我就带你用Python写一个脚本，直接在你自己的电脑上，调用强大的Qwen3-ASR-1.7B语音识别模型，实现批量音频转文字。整个过程完全本地运行，你的音频数据不会离开你的电脑，安全又高效。这个1.7B版本的模型，相比之前更小的版本，在处理复杂的长句子、中英文混合内容时，准确率有了质的飞跃。

这篇文章，我会手把手教你从环境搭建到代码编写，最后实现一个能处理文件夹里所有音频文件的实用脚本。即使你之前没怎么接触过语音识别，跟着步骤走，也能轻松搞定。

1. 项目与环境准备

在开始写代码之前，我们需要先把“舞台”搭好。这包括安装必要的软件库，以及准备好核心的语音识别模型。

1.1 核心工具介绍

我们这次的主角是Qwen3-ASR-1.7B。你可以把它理解为一个非常聪明的“耳朵”和“大脑”的结合体。它专门负责听音频，然后把听到的内容转换成文字。这个“1.7B”指的是它有17亿个参数，可以简单理解为它的“知识量”和“理解能力”达到了一个很强的水平，特别擅长处理那些句子很长、结构复杂或者中英文夹杂的语音。

整个工作流程会依赖几个关键的Python库：

Transformers：这是由Hugging Face提供的宝库，我们通过它来加载和使用Qwen3-ASR模型。
Torch (PyTorch)：这是模型运行的计算引擎，尤其是如果你有NVIDIA显卡，它能利用GPU大大加快识别速度。
SoundFile / Librosa：这些是音频处理库，负责读取你硬盘上的MP3、WAV等各种格式的音频文件，并把它们转换成模型能理解的数字信号。

1.2 一步到位：环境安装

打开你的终端或命令提示符，我们用一个命令把需要的包都安装好。建议先创建一个独立的Python虚拟环境，避免包版本冲突。

# 安装核心依赖 pip install transformers torch soundfile librosa

如果你的电脑有NVIDIA显卡，并且已经安装了CUDA，那么torch会自动安装GPU版本。安装完成后，你可以通过下面的代码快速验证一下主要库是否就绪：

import torch print(f"PyTorch版本: {torch.__version__}") print(f"GPU是否可用: {torch.cuda.is_available()}") if torch.cuda.is_available(): print(f"GPU设备: {torch.cuda.get_device_name(0)}")

2. 编写批量转写脚本

环境准备好后，我们就可以动手编写核心脚本了。我们的目标是：指定一个文件夹，脚本能自动找出里面所有的音频文件，然后逐个转写成文字，并把结果保存下来。

2.1 脚本核心代码

创建一个新的Python文件，比如叫做batch_asr.py，然后把下面的代码复制进去。我会逐段为你解释。

import os from pathlib import Path import torch from transformers import AutoModelForSpeechSeq2Seq, AutoProcessor import soundfile as sf import librosa class BatchAudioTranscriber: """ 批量音频转文字工具类 基于 Qwen3-ASR-1.7B 模型 """ def __init__(self, model_name="Qwen/Qwen3-ASR-1.7B", device="cuda"): """ 初始化转写器，加载模型和处理器 Args: model_name: 模型名称，默认为 Qwen3-ASR-1.7B device: 推理设备，cuda 或 cpu """ print(f"正在加载模型 {model_name}...") # 自动选择设备，如果指定了cuda但不可用，则回退到cpu if device == "cuda" and not torch.cuda.is_available(): print("警告：CUDA不可用，将使用CPU进行推理（速度较慢）") device = "cpu" self.device = device self.torch_dtype = torch.float16 if device == "cuda" else torch.float32 # 加载模型和处理器 self.model = AutoModelForSpeechSeq2Seq.from_pretrained( model_name, torch_dtype=self.torch_dtype, low_cpu_mem_usage=True, use_safetensors=True ).to(self.device) self.processor = AutoProcessor.from_pretrained(model_name) print("模型加载完成！") def transcribe_audio(self, audio_path): """ 转写单个音频文件 Args: audio_path: 音频文件路径 Returns: str: 识别出的文本 """ try: # 使用librosa加载音频，自动重采样到模型需要的16kHz speech_array, sampling_rate = librosa.load(audio_path, sr=16000, mono=True) # 准备模型输入 inputs = self.processor( audio=speech_array, sampling_rate=sampling_rate, return_tensors="pt" ).to(self.device, dtype=self.torch_dtype) # 生成识别结果 with torch.no_grad(): generated_ids = self.model.generate(**inputs, max_new_tokens=1024) # 解码识别结果 transcription = self.processor.batch_decode( generated_ids, skip_special_tokens=True )[0] return transcription except Exception as e: print(f"处理文件 {audio_path} 时出错: {e}") return None def transcribe_folder(self, folder_path, output_file="transcriptions.txt"): """ 批量转写文件夹内的所有音频文件 Args: folder_path: 包含音频文件的文件夹路径 output_file: 输出文本文件路径 """ folder = Path(folder_path) # 支持的音频格式 audio_extensions = {'.wav', '.mp3', '.m4a', '.ogg', '.flac', '.aac'} # 查找所有音频文件 audio_files = [] for ext in audio_extensions: audio_files.extend(folder.glob(f"*{ext}")) audio_files.extend(folder.glob(f"*{ext.upper()}")) if not audio_files: print(f"在文件夹 {folder_path} 中未找到支持的音频文件") return print(f"找到 {len(audio_files)} 个音频文件，开始批量转写...") results = [] for i, audio_file in enumerate(audio_files, 1): print(f"[{i}/{len(audio_files)}] 正在处理: {audio_file.name}") transcription = self.transcribe_audio(str(audio_file)) if transcription: results.append({ 'file': audio_file.name, 'text': transcription }) print(f" 转写成功: {transcription[:100]}...") # 只打印前100字符预览 else: print(f" 转写失败") # 保存结果到文件 self._save_results(results, output_file) print(f"\n批量转写完成！结果已保存至: {output_file}") def _save_results(self, results, output_file): """将转写结果保存到文本文件""" with open(output_file, 'w', encoding='utf-8') as f: for item in results: f.write(f"文件: {item['file']}\n") f.write(f"转写内容:\n{item['text']}\n") f.write("-" * 50 + "\n\n") # 使用示例 if __name__ == "__main__": # 初始化转写器，自动使用GPU（如果可用） transcriber = BatchAudioTranscriber(device="cuda") # 指定你的音频文件夹路径 audio_folder = "./my_audio_files" # 修改为你的文件夹路径 # 开始批量转写 transcriber.transcribe_folder(audio_folder, output_file="转写结果.txt")

2.2 代码要点解析

这段代码看起来有点长，但其实结构很清晰，主要分为三个部分：

初始化 (__init__)：就像打开一个工具箱，这里负责把Qwen3-ASR模型这个“核心工具”从网上下载并加载到你的电脑内存或显卡里。torch_dtype=torch.float16这个设置是为了在GPU上节省显存，让1.7B的大模型也能在消费级显卡上运行。
单文件转写 (transcribe_audio)：这是核心的“工作单元”。它做三件事：
- 读取音频：用librosa库读取文件，并统一转换成模型需要的格式（单声道，16000Hz采样率）。
- 送入模型：把处理好的音频数据喂给模型。
- 输出文字：把模型“思考”后产生的文字解码出来。
批量处理 (transcribe_folder)：这是脚本的“大脑”。它会自动扫描你指定文件夹里所有常见格式的音频文件（如.mp3, .wav等），然后一个一个地调用上面的“工作单元”进行处理，最后把所有结果整理好，保存到一个文本文件里。

3. 运行与实战演示

脚本写好了，我们来让它真正跑起来，看看效果。

3.1 准备音频并运行脚本

首先，在你放batch_asr.py脚本的同一个目录下，创建一个名为my_audio_files的文件夹（或者你也可以在代码里修改audio_folder变量指向任何已有的文件夹）。然后，放几个你想要转写的音频文件进去，比如meeting.mp3、interview.wav。

接着，在终端里运行这个脚本：

python batch_asr.py

你会看到类似下面的输出，这表明模型正在加载和运行：

正在加载模型 Qwen/Qwen3-ASR-1.7B... 模型加载完成！ 找到 3 个音频文件，开始批量转写... [1/3] 正在处理: meeting.mp3 转写成功: 好的，我们开始今天的周会。首先回顾一下上周各项目的进展。小李，你先说一下A客户那边的情况... [2/3] 正在处理: interview.wav 转写成功: Q: Could you briefly introduce your research background? A: Sure. My research primarily focuses on... [3/3] 正在处理: presentation.m4a 转写成功: 接下来我们看第三季度的数据报表。从chart上可以明显看出，我们的用户增长率在七月份达到了一个peak... 批量转写完成！结果已保存至: 转写结果.txt

3.2 查看与使用结果

处理完成后，脚本会在当前目录生成一个转写结果.txt文件。用记事本或任何文本编辑器打开它，你会看到结构清晰的转写内容：

文件: meeting.mp3 转写内容: 好的，我们开始今天的周会。首先回顾一下上周各项目的进展。小李，你先说一下A客户那边的情况... -------------------------------------------------- 文件: interview.wav 转写内容: Q: Could you briefly introduce your research background? A: Sure. My research primarily focuses on... --------------------------------------------------

这个文件就是你的最终成果。你可以直接复制里面的文字到文档里编辑，或者用于其他分析。整个过程，你的音频数据从未离开过你的电脑。

4. 进阶技巧与问题排查

基本的脚本能工作后，我们再来看看如何让它更好用，以及遇到问题怎么办。

4.1 让脚本更实用：添加进度与格式支持

最初的脚本已经能用，但我们可以稍作改进，让它更友好。比如，增加一个进度条，并且更灵活地处理各种音频格式。你可以用Python的tqdm库来添加进度条。

pip install tqdm

然后修改transcribe_folder方法中的循环部分：

from tqdm import tqdm # ... 在 transcribe_folder 方法内，替换原来的for循环 ... print(f"找到 {len(audio_files)} 个音频文件，开始批量转写...") results = [] for audio_file in tqdm(audio_files, desc="转写进度"): transcription = self.transcribe_audio(str(audio_file)) if transcription: results.append({'file': audio_file.name, 'text': transcription}) # ... 后续保存代码不变 ...

4.2 常见问题与解决方法

在运行过程中，你可能会遇到下面几个常见问题：

问题：显存不足 (CUDA out of memory)
- 原因：1.7B模型在GPU上运行需要约4-5GB显存。如果你的显卡显存较小（比如只有4GB），可能会报错。
- 解决：在初始化BatchAudioTranscriber时，将device参数改为"cpu"。虽然速度会慢一些，但肯定能运行。
```
transcriber = BatchAudioTranscriber(device="cpu") # 强制使用CPU
```
问题：无法加载模型或下载太慢
- 原因：第一次运行需要从Hugging Face下载模型文件（约3.4GB），如果网络不好会失败或很慢。
- 解决：
  1. 使用国内镜像源，在运行脚本前设置环境变量：
```
# Linux/macOS export HF_ENDPOINT=https://hf-mirror.com # Windows (命令行) set HF_ENDPOINT=https://hf-mirror.com
```
  2. 或者，在代码中指定镜像地址（需要修改 transformers 的下载逻辑，较为复杂，优先推荐方法1）。
问题：某些音频文件识别效果差
- 原因：音频质量太差（如背景噪音大、说话人距离麦克风远）、方言口音重、或语速过快。
- 解决：对于重要的音频，可以先用音频编辑软件（如Audacity）进行降噪、音量标准化等预处理。Qwen3-ASR-1.7B对清晰、标准的普通话和英语支持最好。

5. 总结

通过这个项目，我们完成了一个非常实用的本地批量音频转文字工具。回顾一下整个过程和要点：

核心价值：我们利用Qwen3-ASR-1.7B这个强大的本地语音识别模型，实现了隐私安全、离线可用、批量高效的音频转文字功能。它特别适合处理需要保密的会议录音、大量的访谈素材或个人视频字幕制作。
关键步骤：整个过程分为三步——安装环境、编写脚本、运行处理。脚本的核心是一个类，它封装了模型加载、单文件转写和批量处理的所有逻辑，结构清晰，易于理解和修改。
效果优势：1.7B版本模型在长句子、复杂逻辑和中英文混合场景下的识别准确率显著优于更小的版本，生成的文本标点更合理，语义更连贯，实用性大大增强。
灵活扩展：这个脚本只是一个起点。你可以基于它轻松地扩展出更多功能，比如：
- 将结果自动保存为Word或Excel格式。
- 增加对视频文件（提取音频）的支持。
- 开发一个带有图形界面的小软件。
- 将转写服务集成到你的其他自动化工作流中。