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 代码要点解析

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

  1. 初始化 (__init__)：就像打开一个工具箱，这里负责把Qwen3-ASR模型这个“核心工具”从网上下载并加载到你的电脑内存或显卡里。torch_dtype=torch.float16 这个设置是为了在GPU上节省显存，让1.7B的大模型也能在消费级显卡上运行。

  2. 单文件转写 (transcribe_audio)：这是核心的“工作单元”。它做三件事：

    • 读取音频：用librosa库读取文件，并统一转换成模型需要的格式（单声道，16000Hz采样率）。
    • 送入模型：把处理好的音频数据喂给模型。
    • 输出文字：把模型“思考”后产生的文字解码出来。

  3. 批量处理 (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. 总结

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

  1. 核心价值：我们利用 Qwen3-ASR-1.7B 这个强大的本地语音识别模型，实现了隐私安全、离线可用、批量高效的音频转文字功能。它特别适合处理需要保密的会议录音、大量的访谈素材或个人视频字幕制作。

  2. 关键步骤：整个过程分为三步——安装环境、编写脚本、运行处理。脚本的核心是一个类，它封装了模型加载、单文件转写和批量处理的所有逻辑，结构清晰，易于理解和修改。

  3. 效果优势：1.7B版本模型在长句子、复杂逻辑和中英文混合场景下的识别准确率显著优于更小的版本，生成的文本标点更合理，语义更连贯，实用性大大增强。

  4. 灵活扩展：这个脚本只是一个起点。你可以基于它轻松地扩展出更多功能，比如：

    • 将结果自动保存为Word或Excel格式。
    • 增加对视频文件（提取音频）的支持。
    • 开发一个带有图形界面的小软件。
    • 将转写服务集成到你的其他自动化工作流中。

最重要的是，整个流程完全在本地完成，你完全掌控自己的数据。希望这个脚本能成为你处理音频资料的高效助手。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。

# 语音识别
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

四天蒸发近2000亿，宇树科技股价近乎“腰斩”；苹果举办库克告别派对：9月1日正式卸任CEO；Anthropic两款新Claude模型曝光 | 极客头条

avatar AI编程社区
cover

Claude Code反超GitHub Copilot登顶第一、90%程序员已用上Agent，最新AI编码调查报告来了

avatar AI编程社区
cover

如何用好 Claude Code 写后端代码

avatar AI编程社区