企业官网建设流程全解析

• 人工智能
• 语音
• 音频
• NLP
• 媒体生成

paddlespeech.cli是 PaddleSpeech 内置的命令行工具模块，它将声音分类、声纹识别、语音识别、语音翻译、语音合成、标点恢复等语音应用场景的预训练模型封装为一条条可直接执行的命令，让开发者无需编写 Python 代码即可完成模型预测。本文以 paddlespeech/cli/README_cn.md 为主线，结合 paddlespeech/cli 目录下的入口、执行器与参数解析源码，完整讲解每个子命令的用法、关键参数、底层执行流程以及批量推理等进阶技巧。

一、命令行工具的整体设计：从一条命令到一次推理

PaddleSpeech 的命令行工具本质上是一个"命令分发器 + 任务执行器"的组合：

• 命令分发：由 paddlespeech/cli/entry.py 实现。paddlespeech命令启动后，_execute()会逐段匹配用户输入的子命令（如paddlespeech asr、paddlespeech tts），找到对应的_entry并实例化执行；执行成功返回状态码 0，失败返回 1。
• 命令注册：由 paddlespeech/cli/base_commands.py 中的_commands字典统一注册。当前仓库中注册了 9 类任务命令：asr（语音识别）、cls（声音分类）、st（语音翻译）、text（文本后处理）、tts（语音合成）、vector（声纹/向量）、kws（关键词唤醒）、ssl（自监督预训练）、whisper（Whisper 识别/翻译），README 中以示例形式重点介绍了前 6 类。
• 统一执行器抽象：所有任务都继承自 paddlespeech/cli/executor.py 中的抽象类BaseExecutor，它规定了四个标准阶段——_init_from_path（加载模型与资源）、preprocess（输入预处理）、infer（模型推理）、postprocess（结果后处理），命令行入口execute()与 Python API 入口__call__()共用同一套推理逻辑。

也就是说，命令行工具与 Python API（paddlespeech.cli各 Executor 类）共享同一套模型资源管理（CommonTaskResource）和预训练模型仓库，首次运行某条命令时，工具会自动下载对应模型到本地缓存目录，之后再次使用将直接读取本地文件，无需重复下载。

二、先看帮助：paddlespeech help

安装并配置好 PaddleSpeech 后，在终端执行：

paddlespeech help

工具会打印所有已注册子命令及其简要说明，输出格式为：

Usage: paddlespeech <command> <options> Commands: asr Speech to text infer command. cls Audio classification infer command. ...

这一行为由HelpCommand实现（见 paddlespeech/cli/base_commands.py），它会遍历命令字典中带_description的注册项并逐行打印。此外，paddlespeech version可以查看当前安装包的版本号与 commit id，paddlespeech stats --task asr等命令可以列出对应任务支持的预训练模型清单（按"模型-数据集-语言-采样率"等维度组织的表格）。

三、声音分类：paddlespeech cls

声音分类（Audio Classification）用于判断一段音频属于哪一类声音，例如环境声、音乐、人声等。基本用法：

paddlespeech cls --input input.wav

从 paddlespeech/cli/cls/infer.py 的CLSExecutor可以看到，该命令支持以下常用参数：

从源码看，分类流程是：先按配置中的sample_rate等参数读取音频并计算LogMelSpectrogram对数梅尔谱特征（见preprocess），再送入 CNN14 等模型得到 logits，最后由postprocess中的_generate_topk_label输出形如标签 分数的结果。需要批量分类时，也可以把多条音频路径写入.txt文件作为--input传入。

四、声纹识别：paddlespeech vector

声纹识别（Speaker Verification）用于提取说话人音频的声纹向量（embedding），可进一步做说话人确认、1:1 打分等任务。基本用法：

paddlespeech vector --task spk --input input_16k.wav

VectorExecutor（见 paddlespeech/cli/vector/infer.py）支持两种--task：

• spk：默认任务，从单条音频中提取声纹向量并输出；
• score：打分任务，输入必须是一条包含两个 wav 路径的记录（例如通过.txt或标准输入传入enroll.wav test.wav），工具会分别提取两条音频的声纹向量，再用余弦相似度（paddle.nn.CosineSimilarity，见get_embeddings_score）计算相似度分数。

关键参数包括--model（默认ecapatdnn_voxceleb12）、--sample_rate（当前固定支持 16000）、--ckpt_path、--config、--device等。预处理阶段使用melspectrogram提取 FBank 特征并进行均值归一化（feature_normalize），推理阶段由 ECAPA-TDNN backbone 输出固定维度的说话人向量。

五、语音识别：paddlespeech asr

语音识别（ASR）是 PaddleSpeech 最核心的能力之一，将语音转换为文字。基本用法：

paddlespeech asr --lang zh --input input_16k.wav

ASRExecutor（见 paddlespeech/cli/asr/infer.py）的参数非常丰富：

底层推理细节值得注意：

• 输入校验与重采样：_check()会用soundfile读取音频并核对采样率；若输入音频采样率与模型要求不一致，工具会提示是否自动重采样，使用--yes可跳过交互确认（源码中给出的转换建议是sox转为 16k/16bit/单声道 wav）。
• 特征提取：preprocess中通过Transformation按配置计算 FBank 特征；对于deepspeech2类模型还会自动下载语言模型（download_lm）用于解码。
• 时长限制：Transformer/Conformer 类模型根据编码器最大位置编码长度与子采样率推算max_len，超出限制的音频会被拒绝，因此输入音频不宜过长。
• RTF 统计：启用--rtf后，工具统计每次推理的起止时间与音频时长，最后打印样本数与平均 RTF（实现于 paddlespeech/cli/executor.py 的show_rtf）。

六、语音翻译（英-中）：paddlespeech st

端到端语音翻译（Speech Translation）可以直接把英语语音翻译为中文文本：

paddlespeech st --input input_16k.wav

需要注意：该命令暂不支持 Windows 系统（README 中已明确标注）。原因在源码中也很清楚——STExecutor（见 paddlespeech/cli/st/infer.py）在初始化时会下载一套 Kaldi 工具二进制（kaldi_bins，一个 Linux 环境的 tar.gz 包）并注入PATH与LD_LIBRARY_PATH环境变量，用于音频特征计算（如kaldiio相关的 ark 特征读写），因此依赖 Linux 环境。

该命令的主要参数有--model（默认fat_st_ted）、--src_lang（源语言，默认en）、--tgt_lang（目标语言，默认zh）、--sample_rate（固定 16000）、--config、--ckpt_path、--device等。README 中对应任务的官方示例位于 examples/ted_en_zh/st1，感兴趣可以对照查看完整的训练与推理脚本。

七、语音合成：paddlespeech tts

语音合成（Text-to-Speech）将文本转换为自然语音并保存为 wav 文件：

paddlespeech tts --input "你好，欢迎使用百度飞桨深度学习框架！" --output output.wav

TTSExecutor（见 paddlespeech/cli/tts/infer.py）的参数体系分为"声学模型（am）"与"声码器（voc）"两部分：

从源码看，合成流程分为三段：文本前端（frontend）将中文/英文文本转为音素序列（get_frontend+run_frontend）；声学模型将音素序列预测为梅尔频谱（多说话人模型还会拼接spk_id）；声码器将梅尔频谱还原为波形并拼接输出。支持 ONNX 的模型集合（ONNX_SUPPORT_SET）包括fastspeech2_*、speedyspeech_csmsc及pwgan_*、hifigan_*、mb_melgan_csmsc等，启用--use_onnx时需保证所选的--am与--voc均在该集合内。合成结果通过soundfile以声学模型配置的采样率写出。

八、文本后处理：标点恢复

语音识别结果通常是没有标点的连续文本，标点恢复（Punctuation Restoration）为这类文本自动补全标点，提升可读性。基础用法：

paddlespeech text --task punc --input 今天的天气真不错啊你下午有空吗我想约你一起去吃饭

快速标点恢复版本（使用轻量级模型，推理更快）：

paddlespeech text --task punc --input 今天的天气真不错啊你下午有空吗我想约你一起去吃饭 --model ernie_linear_p3_wudao_fast

TextExecutor（见 paddlespeech/cli/text/infer.py）支持的参数包括--task（当前仅punc）、--model（默认ernie_linear_p7_wudao，可选快速版ernie_linear_p3_wudao_fast）、--lang（zh或en）、--config、--ckpt_path、--punc_vocab（标点词表）、--device等。

从源码可以看到两类模型的内部差异：

• 旧版模型（ernie_linear_p7_wudao、ernie_linear_p3_wudao）通过_init_from_path初始化，使用ernie-1.0tokenizer；
• 新版模型（名称中带fast的ernie_linear_p3_wudao_fast）通过_init_from_path_new初始化，直接加载ErnieLinear模型，并使用更快的ernie-3.0-mini-zhtokenizer。

推理时，preprocess会先清洗文本（小写化、剔除标点外的特殊字符），再由 tokenizer 切分；infer得到每个位置的标点类别 logits 后取 argmax；postprocess将预测的标点符号插回原文。标点列表来自预训练模型自带的punc_vocab词表，模型会根据上下文为每个字符预测是否添加标点以及添加哪种标点。

九、批量输入与更多进阶用法

命令行工具并非只能处理单个输入。BaseExecutor.get_input_source（见 paddlespeech/cli/executor.py）支持三类输入来源：

1. 单个文件路径：最常用的方式，如--input a.wav；
2. 批量任务文件：.job、.txt、.scp后缀的文件会被逐行解析，每行格式为id 路径（或单字段路径），逐条推理后按id输出结果；配合-d / --job_dump_result可以把结果写入<输入文件>.job.done；
3. 标准输入（stdin）：不传--input时，工具会读取标准输入中的每一行作为任务，适合在 shell 管道中串联使用。

此外，所有 Executor 都同时暴露了同名 Python API（__call__），因此命令行用法可以无缝迁移到 Python 脚本中，例如：

from paddlespeech.cli.asr import ASRExecutor asr = ASRExecutor() result = asr(audio_file="input_16k.wav", lang="zh", sample_rate=16000) print(result)

模型资源的下载与缓存逻辑见 paddlespeech/cli/utils.py（download_and_decompress、load_state_dict_from_url）与 paddlespeech/cli/download.py（get_path_from_url支持 MD5 校验与断点续传），每个任务通过CommonTaskResource按模型-语言-采样率等标签定位官方预训练模型；第一次运行某命令时只需等待模型下载完成，之后即可离线使用。

十、小结

PaddleSpeech 命令行工具把"声音分类 → 声纹识别 → 语音识别 → 语音翻译 → 语音合成 → 标点恢复"这条完整的语音处理链路浓缩成了几条直观的命令。理解 paddlespeech/cli 中entry.py的命令分发、executor.py的统一执行器抽象，以及各任务 Executor 的参数与推理管线，就能在原型验证、批量评测、服务部署等场景中快速上手；而kws、ssl、whisper等其余已注册命令同样遵循这套模式，可以参照本文介绍的参数风格进一步探索。

• 人工智能
• 语音
• 音频
• NLP
• 媒体生成