Qwen3-ASR-Toolkit

在日常使用通义千问 ASR（自动语音识别）服务时，一个常见痛点是：API 对单次请求的音频长度限制为 3 分钟。这意味着，一段两小时的讲座或会议录音，无法直接上传，必须手动切分、逐段处理——耗时且容易出错。

为此，阿里推出 Qwen3-ASR-Toolkit —— 一款专为长音频设计的 Python 命令行工具包，现已正式发布于 PyPI。

它基于 DashScope Qwen-ASR API 构建（原 Qwen3-ASR-Flash），通过智能分割与并行调用机制，实现对任意长度音频/视频文件的全自动、高速转录，真正让大模型能力服务于长内容场景。

✅ 支持数小时音视频一键转文字
✅ 自动适配采样率与声道
✅ 基于语音活动检测（VAD）无损切分
✅ 多线程并发，显著提升吞吐效率

无需复杂配置，一条命令即可开始转录。

核心特性一览

工作原理：从文件到文本的完整流水线

Qwen3-ASR-Toolkit 的设计目标是：让用户只关心“输入文件”和“输出文本”。中间所有处理均由工具自动完成，流程如下：

1. 媒体加载
   使用 FFmpeg 解封装输入的音频或视频文件，提取原始音频流。
2. 语音活动检测（VAD）分析
   扫描音频流，识别语音段与静音段，定位最佳切分点。
3. 智能分块
   将音频按语义间隙切割成多个小于 3 分钟的片段，确保每个片段语义完整。
4. 格式标准化
   对每一片段进行重采样（→16kHz）和单声道转换，满足 API 输入要求。
5. 并行 API 调用
   启动线程池，并发发送各片段至 Qwen-ASR API 进行识别。
6. 结果聚合与输出
   按时间顺序合并所有返回文本，生成完整转录结果，保存为 .txt 文件。

整个过程完全自动化，用户无需干预。

快速上手指南

先决条件

• Python 3.8 或更高版本
• FFmpeg（系统级安装）
• DashScope API 密钥

安装 FFmpeg

# Ubuntu/Debian
sudo apt update && sudo apt install ffmpeg

# macOS (使用 Homebrew)
brew install ffmpeg

# Windows
# 下载地址：https://ffmpeg.org/download.html
# 并将其路径添加到系统 PATH 环境变量中

获取 API 密钥

访问 DashScope 控制台 获取你的 DASHSCOPE_API_KEY。

建议设置为环境变量，避免每次传参：

# Linux/macOS
export DASHSCOPE_API_KEY="your_api_key_here"
# （永久生效：写入 ~/.bashrc 或 ~/.zshrc）

# Windows (PowerShell)
$env:DASHSCOPE_API_KEY="your_api_key_here"

安装方式

✅ 推荐：从 PyPI 安装

pip install qwen3-asr-toolkit

安装后即可全局使用 qwen3-asr 命令。

🔧 可选：从源码安装（适用于开发贡献者）

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

使用方法

安装完成后，运行以下命令即可开始转录：

qwen3-asr -i your_video.mp4

支持的主要参数：

输出说明

• 转录结果会实时打印到终端；
• 最终文本自动保存为与输入同名的 .txt 文件，位于相同目录下。

适用场景

Qwen3-ASR-Toolkit 特别适合以下用途：

• 会议记录 → 自动生成会议纪要
• 在线课程 → 提取讲义内容便于复习
• 访谈录音 → 快速整理对话文本
• 播客制作 → 辅助字幕生成与内容索引
• 科研访谈 → 结合 LLM 进行定性分析预处理

结合后续的 NLP 处理流程（如摘要、关键词提取、问答系统），可构建完整的语音信息处理 pipeline。

技术优势总结