Qwen3-ASR-Toolkit

😊 重要提示

Qwen3-ASR 现已开源🎉🎉🎉。欢迎访问GitHub和博客获取更多信息。开源模型的功能与 API 相当，支持免费、快速的本地部署。Qwen3-ASR 开源模型包含两款强大的一体化语音识别模型（0.6B/1.7B），支持52 种语言和方言的语言识别与 ASR，以及一款新颖的非自回归语音强制对齐模型，可在 11 种语言中实现文本-语音对齐。其强大的性能足以提供极具吸引力的语音转文字能力。欢迎使用！

概述

这是一款先进的高性能 Python 命令行工具包，用于调用 Qwen-ASR API（原名 Qwen3-ASR-Flash）。该实现通过智能分割长音频/视频文件并并行处理，突破了 API 对音频长度 3 分钟的限制，从而能够快速转录长达数小时的内容。

🚀 核心功能

• 突破 3 分钟限制：无缝转录任意长度的音频和视频文件，绕过官方 API 的时长限制。
• 智能音频分割：利用**语音活动检测（VAD）**在自然的静音处将音频分割成有意义的片段，确保单词和句子不会被生硬地截断。
• 高速并行处理：借助多线程技术，同时向 Qwen-ASR API 发送多个音频片段，大幅缩短长文件的总转录时间。
• 智能后处理：自动检测并去除常见的 ASR 幻觉和重复性伪影，生成更干净、更准确的转录文本。
• SRT 字幕生成：基于 VAD 分段自动生成带时间戳的**.srt 字幕文件**，非常适合为视频内容添加字幕。
• 自动音频重采样：自动将任何采样率和声道数的音频转换为 Qwen-ASR API 所需的 16kHz 单声道格式。您无需担心预处理问题，可直接使用任何音频文件。
• 通用媒体支持：由于依赖 FFmpeg，几乎支持所有音频和视频格式（如 .mp4、.mov、.mkv、.mp3、.wav、.m4a 等）。
• 简单易用：直观的命令行界面让您只需一条命令即可开始使用。

⚙️ 工作原理

该工具采用稳健的流程，为长篇媒体内容提供快速且准确的转录：

1. 加载媒体：脚本首先加载您的媒体文件，无论是本地文件还是远程 URL。
2. 基于 VAD 的分块：利用语音活动检测（VAD）分析音频流，识别静音段。
3. 智能分割：根据检测到的静音将音频分割成较小的片段。每个片段的时长控制在 3 分钟的 API 限制以内，并允许用户自定义目标时长（默认 120 秒），以避免句子被截断。
4. 并行 API 调用：启动线程池，使用 DashScope Qwen-ASR API 并发上传和处理这些音频片段。
5. 结果聚合与清洗：收集所有片段的转录文本，重新排序后进行后处理，去除重复内容和幻觉现象。
6. 输出生成：最终清理后的转录文本会打印到控制台，并保存为 .txt 文件。还可选择生成带时间戳的 .srt 字幕文件。

🏁 快速入门

按照以下步骤，在您的本地机器上设置并运行该项目。

先决条件

• Python 3.8 或更高版本。
• FFmpeg：脚本需要系统中安装 FFmpeg 来处理媒体文件。
  • Ubuntu/Debian：sudo apt update && sudo apt install ffmpeg
  • macOS：brew install ffmpeg
  • Windows：从 FFmpeg 官方网站下载，并将其添加到系统的 PATH 中。
• DashScope API 密钥：您需要阿里云 DashScope 的 API 密钥。

  • 您可以从 DashScope 控制台获取密钥。如果您是首次调用通义千问的 API 服务，可以参考此网站上的教程创建自己的 API 密钥。

  • 为了更好的安全性和便利性，强烈建议将您的 API 密钥设置为名为 DASHSCOPE_API_KEY 的环境变量。脚本会自动使用该变量，您无需在命令中传递 --api-key 参数。

    Linux/macOS：

    export DASHSCOPE_API_KEY="your_api_key_here"
    

    (若要永久生效，请将该行添加到 ~/.bashrc、~/.zshrc 或 ~/.profile 文件中。)

    Windows（命令提示符）：

    set DASHSCOPE_API_KEY="your_api_key_here"
    

    Windows（PowerShell）：

    $env:DASHSCOPE_API_KEY="your_api_key_here"
    

    (若要在 Windows 上永久设置，请在“开始”菜单中搜索“编辑系统环境变量”，并将 DASHSCOPE_API_KEY 添加到您的用户变量中。)

安装

我们推荐直接从 PyPI 安装该工具，这是最简单的设置方式。

选项 1：从 PyPI 安装（推荐）

只需在终端中运行以下命令，即可安装该软件包，并使 qwen3-asr 命令在整个系统中可用。

pip install qwen3-asr-toolkit

选项 2：从源代码安装

如果您想安装最新的开发版本或参与项目贡献，也可以从源代码安装。

1. 克隆仓库：

   git clone https://github.com/QwenLM/Qwen3-ASR-Toolkit.git
   cd Qwen3-ASR-Toolkit
   

2. 安装软件包：

   pip install .
   

📖 使用方法

安装完成后，您可以直接在终端中使用 qwen3-asr 命令。默认情况下，工具会打印进度信息。

命令

qwen3-asr -i <input_file_or_url> [-key <api_key>] [-j <num_threads>] [-c <context>] [-d <duration>] [-t <tmp_dir>] [--save-srt] [-s]

参数

参数	短选项	描述	必需/可选
--input-file	-i	要转录的本地媒体文件路径或远程 URL（http/https）。	必需
--context	-c	用于引导 ASR 模型的文本上下文，以提高特定术语的识别准确度。	可选，默认值：""
--dashscope-api-key	-key	您的 DashScope API 密钥。	可选（如果已设置 DASHSCOPE_API_KEY）
--num-threads	-j	用于 API 调用的并发线程数。	可选，默认值：4
--vad-segment-threshold	-d	每个 VAD 分割音频块的目标时长（秒）。	可选，默认值：120
--tmp-dir	-t	用于存储临时分块文件的目录路径。	可选，默认值：~/qwen3-asr-cache
--save-srt	-srt	除了 .txt 文件外，还会生成并保存带时间戳的 SRT 字幕文件。	可选
--silence	-s	静默模式。在终端上抑制详细的进度和分块信息。	可选

输出

完整的转录结果将打印到终端（除非处于 --silence 模式），同时也会保存为与输入文件同目录下的 .txt 文件。例如，如果您处理的是 my_video.mp4，输出将保存为 my_video.txt。

如果使用了 --save-srt 标志，则会在同一目录下创建对应的 my_video.srt 字幕文件。

---

✨ 示例

以下是一些使用该工具的示例。

1. 本地文件的基本转录

使用默认的 4 个线程转录视频文件。此命令假设您已设置 DASHSCOPE_API_KEY 环境变量。

qwen3-asr -i "/path/to/my/long_lecture.mp4"

2. 转录远程音频文件

直接从 URL 处理音频文件。

qwen3-asr -i "https://somewebsite.com/audios/podcast_episode.mp3"

3. 生成 SRT 字幕文件

使用 --save-srt（或 -srt）标志，可在生成纯文本转录的同时生成带时间戳的字幕文件。这非常适合视频字幕制作。

qwen3-asr -i "/path/to/my/documentary.mp4" -srt

此命令将创建 documentary.txt 和 documentary.srt。

4. 增加并发数并传递 API 密钥

使用 8 个并行线程转录长音频文件，并通过命令行直接传递 API 密钥。

qwen3-asr -i "/path/to/my/podcast_episode_01.wav" -j 8 -key "your_api_key_here"

5. 提供上下文并自定义分块时长

如果您的音频包含特定术语，可以使用 -c 标志。如果您希望字幕片段更短、更频繁，可以使用 -d 设置较小的分块时长。

qwen3-asr -i "/path/to/my/tech_talk.mp4" -c "Qwen-ASR、DashScope、FFmpeg" -d 60 -srt

此命令会尝试将音频分割为约 60 秒的分块，从而生成更精细的字幕。

6. 在静默模式下运行

使用 -s 或 --silence 标志，可以防止进度详情打印到终端。最终的转录结果仍将保存到文件中。

qwen3-asr -i "/path/to/my/meeting_recording.m4a" -s

🌍 其他语言的实现

虽然本项目提供了一个功能齐全的 Python 工具包，我们也在其他编程语言中提供了实现，以展示如何在不同的技术栈中应用相同的逻辑核心。我们热烈欢迎社区贡献更多语言的示例！

☕ Java 示例

我们在本仓库的 examples/java-example 目录中提供了一个独立的 Java 版本示例。该示例展示了如何使用 Java 实现工具包的关键功能——包括基于 VAD 的音频分块、并行 API 请求以及结果聚合。对于希望将 Qwen-ASR 集成到其应用程序中的 Java 开发人员来说，这是一个很好的起点。

如何贡献您的版本

如果您已在其他语言中实现了类似的工具包（例如 Go、Rust、C#、JavaScript/Node.js），我们非常乐意将其收录！请打开一个拉取请求，将您的实现添加到 examples 目录中。有关贡献的更多详细信息，请参阅下方的 贡献 部分。

🤝 贡献

欢迎贡献！如果您有任何改进建议，请随时 fork 本仓库，创建特性分支并提交拉取请求。您也可以开一个带有“enhancement”标签的问题。

📄 许可证

本项目采用 MIT 许可证授权——详情请参阅 LICENSE 文件。

Qwen3-ASR-Toolkit 快速上手指南

Qwen3-ASR-Toolkit 是一个高性能的 Python 命令行工具，专为调用通义千问语音识别（Qwen-ASR）API 设计。它通过智能切片和并行处理技术，突破了官方 API 单次 3 分钟的音频长度限制，支持对任意时长的音视频文件进行快速、准确的转录，并自动生成带时间戳的字幕文件。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：3.8 或更高
• 核心依赖：FFmpeg（用于处理音视频文件）
  • Ubuntu/Debian: sudo apt update && sudo apt install ffmpeg
  • macOS: brew install ffmpeg
  • Windows: 从 FFmpeg 官网 下载并将 bin 目录添加到系统环境变量 PATH 中。
• API 密钥：需要阿里云 DashScope 的 API Key。
  • 获取地址：DashScope 控制台
  • 推荐配置：将密钥设置为环境变量 DASHSCOPE_API_KEY，以便在命令中无需重复输入。
    • Linux/macOS:

      export DASHSCOPE_API_KEY="your_api_key_here"
      

    • Windows (PowerShell):

      $env:DASHSCOPE_API_KEY="your_api_key_here"
      

安装步骤

推荐使用 PyPI 进行安装，最简单快捷：

pip install qwen3-asr-toolkit

注：国内用户若遇下载缓慢，可使用清华源加速安装：

pip install qwen3-asr-toolkit -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后，终端即可直接使用 qwen3-asr 命令。

基本使用

1. 转录本地音视频文件

假设您已配置好环境变量 DASHSCOPE_API_KEY，运行以下命令即可转录一个长视频：

qwen3-asr -i "/path/to/my/long_lecture.mp4"

执行成功后，当前目录下将生成同名的 .txt 文本文件（如 long_lecture.txt）。

2. 生成带时间轴的字幕文件

添加 -srt 参数，可同时生成标准的 SRT 字幕文件，适用于视频配音：

qwen3-asr -i "/path/to/my/documentary.mp4" -srt

这将同时输出 documentary.txt 和 documentary.srt。

3. 转录网络链接音频

直接支持 HTTP/HTTPS 链接作为输入：

qwen3-asr -i "https://somewebsite.com/audios/podcast_episode.mp3"

常用参数说明

参数	简写	说明	默认值
--input-file	-i	输入文件路径或 URL (必填)	-
--save-srt	-srt	生成 SRT 字幕文件	否
--num-threads	-j	并行线程数，提升长文件处理速度	4
--context	-c	上下文提示词，优化专有名词识别	""
--silence	-s	静默模式，不输出详细进度日志	否

高级示例：使用 8 个线程加速，并指定专业术语上下文：

qwen3-asr -i "/path/to/tech_talk.mp4" -j 8 -c "Qwen-ASR, DashScope" -srt