企业官网建设流程全解析

PaddleSpeech 语音识别（ASR）Demo 实战：命令行与 Python API 快速实现语音转文本

【免费下载链接】PaddleSpeechEasy-to-use Speech Toolkit including Self-Supervised Learning model, SOTA/Streaming ASR with punctuation, Streaming TTS with text frontend, Speaker Verification System, End-to-End Speech Translation and Keyword Spotting. Won NAACL2022 Best Demo Award.项目地址: https://gitcode.com/gh_mirrors/pa/PaddleSpeech

导读

语音识别（Automatic Speech Recognition, ASR）是用计算机程序将语音自动转录为文本的技术，也是语音交互、字幕生成、会议转写等应用的核心环节。本篇文章基于 PaddleSpeech 仓库中的 speech_recognition Demo 文档，完整讲解如何通过一条paddlespeech asr命令或几行 Python 代码，把给定的 WAV 音频文件快速转成文本，并覆盖中文、英文、中英混合（Code-Switch）以及"语音识别 + 标点恢复"组合流水线等实战场景。读完本文，你将掌握 ASRExecutor 的完整调用方式、全部命令行参数的含义与底层实现、预训练模型的选择策略，以及音频输入格式与采样率的处理细节。

一、Demo 概览与能力边界

PaddleSpeech 是一个开源的语音处理工具包，提供自监督学习模型、流式/非流式 ASR（含标点恢复）、流式 TTS、说话人验证、语音翻译与关键词唤醒等能力。本 Demo 聚焦于其中最基本的离线语音识别能力：

• 输入：单个.wav音频文件（要求采样率与模型一致，默认 16k）；
• 输出：识别出的文本字符串；
• 调用方式：命令行paddlespeech asr或 Python 中实例化ASRExecutor。

Demo 的核心执行逻辑集中在 paddlespeech/cli/asr/infer.py 中的ASRExecutor类，它继承自 paddlespeech/cli/executor.py 的BaseExecutor，遵循统一的"参数解析 → 模型初始化 → 输入校验 → 预处理 → 推理 → 后处理"流水线。命令行入口由 paddlespeech/cli/entry.py 负责分发，将paddlespeech asr ...解析并路由到ASRExecutor.execute()。

二、环境安装：三种方式任选

Demo 文档要求先完成 PaddleSpeech 的安装，详细步骤见 安装文档。安装方式按难度分为三档：

简单方式的核心步骤（以 conda 环境为例）：

conda install -y -c conda-forge sox libsndfile bzip2 pip install pytest-runner -i https://pypi.tuna.tsinghua.edu.cn/simple pip install paddlepaddle -i https://mirror.baidu.com/pypi/simple pip install paddlespeech -i https://pypi.tuna.tsinghua.edu.cn/simple

两个常见注意事项（官方文档明确说明）：

• 若下载nltk_data失败，多半是网络原因，可手动下载官方提供的 nltk_data 压缩包解压到${HOME}目录；
• 若提示paddlespeech-ctcdecoders这个 Python 包没有找到，无需担心，该包是非必须的（仅影响 DeepSpeech2 系列模型的解码，不影响其他模型推理）。

三、准备输入：WAV 文件与采样率约定

本 Demo 的输入必须是一个.wav文件，且采样率必须与所选模型保持一致（预训练模型采样率统一为 16k，sample_rate参数可选 8000 或 16000）。

Demo 文档提供了三个示例音频，可以直接下载：

wget -c https://paddlespeech.cdn.bcebos.com/PaddleAudio/zh.wav https://paddlespeech.cdn.bcebos.com/PaddleAudio/en.wav https://paddlespeech.cdn.bcebos.com/PaddleAudio/ch_zh_mix.wav

这三个文件分别用于中文、英文、中英混合（Code-Switch）识别演示。如果输入音频采样率与模型不一致，程序会给出提示并询问是否自动重采样——详见后文--yes参数的说明。

四、命令行快速上手（推荐）

安装完成后，直接使用paddlespeech asr即可完成识别。Demo 文档给出了四类典型用法：

# 中文（使用默认模型 conformer_wenetspeech） paddlespeech asr --input ./zh.wav -v # 英文 paddlespeech asr --model transformer_librispeech --lang en --input ./en.wav -v # 中英混合（Code-Switch） paddlespeech asr --model conformer_talcs --lang zh_en --codeswitch True --input ./ch_zh_mix.wav -v # 中文 ASR + 标点恢复（管道组合） paddlespeech asr --input ./zh.wav -v | paddlespeech text --task punc -v

其中-v用于显示 logger 日志信息；如果不想看到日志，去掉-v即可。最后一条命令把 ASR 的输出通过管道交给paddlespeech text --task punc（标点恢复任务）做二次处理，一次性得到带标点的完整文本，这正是 PaddleSpeech 命令行可以自由组合任务的一大优势。

4.1 查看帮助

paddlespeech asr --help

4.2 命令行参数详解

Demo 文档列出的核心参数如下，结合 infer.py 中的 argparse 定义 可确认它们的默认值与可选范围：

除文档列出的参数外，从源码还可以看到三个额外的实用参数：

• --decode_method：解码方式，可选ctc_greedy_search、ctc_prefix_beam_search、attention、attention_rescoring，默认attention_rescoring（仅 transformer/conformer 类模型支持，见 infer.py）；
• --rtf：打印实时率（Real-time Factor，RTF = 任务耗时 / 音频时长），用于评估推理速度，见 infer.py；
• -d/--job_dump_result：将批量任务结果保存到*.job.done文件，见 executor.py。

4.3 输出示例

# 中文 [2021-12-08 13:12:34,063] [ INFO] [utils.py] [L225] - ASR Result: 我认为跑步最重要的就是给我带来了身体健康 # 英文 [2022-01-12 11:51:10,815] [ INFO] - ASR Result: i knocked at the door on the ancient side of the building

五、Python API 调用

不想用命令行时，可以用几行 Python 代码完成同样的识别。Demo 文档给出的示例：

import paddle from paddlespeech.cli.asr import ASRExecutor asr_executor = ASRExecutor() text = asr_executor( model='conformer_wenetspeech', lang='zh', sample_rate=16000, config=None, # Set `config` and `ckpt_path` to None to use pretrained model. ckpt_path=None, audio_file='./zh.wav', force_yes=False, device=paddle.get_device()) print('ASR Result: \n{}'.format(text))

输出：

ASR Result: 我认为跑步最重要的就是给我带来了身体健康

从源码看，ASRExecutor.__call__()（infer.py）的完整调用链为：

1. paddle.set_device(device)设置推理设备；
2. _init_from_path(...)根据model + lang + codeswitch + sample_rate拼接出资源 tag（如conformer_wenetspeech-zh-16k），从预训练模型注册表加载配置与权重；若指定了config/ckpt_path则加载本地文件（ckpt_path会自动补.pdparams后缀）；
3. _check(...)校验音频文件存在性、格式、时长（默认单次输入时长上限 50 秒）与采样率；若采样率不匹配且force_yes=False，会进入交互式询问（Y/N）；
4. preprocess(...)用soundfile读取音频（PCM16），必要时做 16bit↔32bit 转换与librosa.resample重采样，再按preprocess_config提取 FBank 特征；
5. infer(...)在@paddle.no_grad()下执行模型解码（DeepSpeech2 走 CTC 解码器，conformer/transformer 走 attention_rescoring 等解码方法）；
6. postprocess(...)返回识别文本。

六、预训练模型一览

下表是 Demo 文档列出的、可被命令行与 Python API 直接使用的预训练模型。模型的下载地址、MD5、配置路径与权重路径等元数据均注册在 paddlespeech/resource/pretrained_models.py 的asr_dynamic_pretrained_models字典中，首次使用时按需自动下载到本地模型目录。

6.1 模型选择建议

• 中文首选：conformer_wenetspeech（Demo 默认模型），基于大规模中文语料 WenetSpeech 训练；
• 英文：transformer_librispeech，基于 LibriSpeech 训练，对应--lang en；
• 中英混合/语码转换：conformer_talcs，对应--lang zh_en --codeswitch True。注意源码中有一个约束：codeswitch为True时lang必须是zh_en，否则会抛出"codeswitch is true only in zh_en model"异常（见 infer.py）；
• 在线（流式）场景：名称中含online的模型（如conformer_online_multicn、conformer_online_aishell）适合流式识别需求。

6.2 使用本地配置与权重

如果你有自己的模型，可通过--config和--ckpt_path指定本地文件，此时程序不会自动下载预训练模型：

paddlespeech asr --config ./model.yaml --ckpt_path ./checkpoint --input ./test.wav -v

注意ckpt_path传入的是去掉.pdparams后缀的路径前缀，源码会自动补全后缀（见 infer.py）。

七、进阶玩法与常见问题

7.1 批量识别

paddlespeech asr支持传入.job/.txt/.scp格式的批量任务文件。文件每行格式为id 音频路径，程序会逐条识别并按行输出id 结果；配合-d参数可将结果落盘到*.job.done文件（见 executor.py）。也可以把音频路径通过标准输入管道传入。

7.2 采样率不匹配怎么办

如果输入 WAV 采样率不是模型要求的 16k/8k，_check()会打印警告并询问是否自动重采样：

• 命令行加--yes（或-y）可跳过交互询问，直接自动重采样；
• Python API 设置force_yes=True同理；
• 若不想依赖自动重采样，官方建议用 sox 预先转换：sox input.xx --rate 16k --bits 16 --channels 1 output.wav（8k 时把--rate换成 8000）。

7.3 音频时长限制

从源码看，默认单条音频的最大时长上限约为 50 秒（self.max_len = 50，且会随 transformer 类模型的位置编码与下采样配置动态计算），超时会提示"Please input audio file less then {max_len} seconds"（见 infer.py 与 infer.py）。因此长音频建议先切片再识别。

7.4 ASR + 标点恢复

中文 ASR 的裸输出通常没有标点，PaddleSpeech 提供了独立的标点恢复任务paddlespeech text --task punc，其实现位于 paddlespeech/cli/text/infer.py。管道组合一行即可拿到带标点的文本：

paddlespeech asr --input ./zh.wav -v | paddlespeech text --task punc -v

7.5 观察推理性能

加上--rtf参数即可输出样本数与平均 RTF（任务耗时 / 音频时长），用于评估模型在目标设备上的实时性（实现见 executor.py）：

paddlespeech asr --input ./zh.wav --rtf -v

八、小结

本 Demo 展示了 PaddleSpeech 语音识别能力的最小可用闭环：一条命令或几行 Python 代码即可完成从 WAV 音频到文本的转录，支持中文、英文、中英混合三种语言场景，并可无缝衔接标点恢复、批量识别等进阶能力。其背后由ASRExecutor统一管理模型加载、音频校验、特征提取与解码推理，预训练模型则通过 pretrained_models.py 集中注册、按需下载。如果想要更进一步（如自行训练 ASR 模型、部署流式识别服务或接入 C++ 推理），可以继续阅读仓库中的 examples 目录、流式 ASR 服务 Demo 与 runtime 工程。

【免费下载链接】PaddleSpeechEasy-to-use Speech Toolkit including Self-Supervised Learning model, SOTA/Streaming ASR with punctuation, Streaming TTS with text frontend, Speaker Verification System, End-to-End Speech Translation and Keyword Spotting. Won NAACL2022 Best Demo Award.项目地址: https://gitcode.com/gh_mirrors/pa/PaddleSpeech