你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：开始使用 Azure AI 语音 CLI

本文介绍如何使用 Azure AI 语音 CLI（也称 SPX）访问语音转文本、文本转语音和语音翻译等语音服务，而无需编写任何代码。 语音 CLI 随时可投入生产，可通过 .bat 或 shell 脚本，用其自动化语音服务中的简单工作流。

本文假定你具备命令提示符窗口、终端或 PowerShell 的相关工作知识。

注意

在 PowerShell 中，停止分析令牌 (--%) 应位于 spx 之后。 例如，运行 spx --% config @region 查看当前区域配置值。

下载并安装

Windows

按照以下步骤在 Windows 上安装语音 CLI：

1. 安装适用于你的平台的 Microsoft Visual C++ Redistributable for Visual Studio 2019。 首次安装此包时，可能需要重启。

2. 安装 .NET 6。

3. 通过输入以下命令，使用 .NET CLI 安装语音 CLI：

   dotnet tool install --global Microsoft.CognitiveServices.Speech.CLI
   

   若要更新语音 CLI，请输入以下命令：

   dotnet tool update --global Microsoft.CognitiveServices.Speech.CLI
   

若要查看语音 CLI 的帮助，请输入 spx 或 spx help。

字体限制

在 Windows 上，语音 CLI 只能显示本地计算机上命令提示符适用的字体。 Windows 终端支持语音 CLI 以交互方式生成的所有字体。

如果输出到文件，文本编辑器（例如记事本）或 web 浏览器（例如 Microsoft Edge）也可以显示所有字体。

Linux

使用语音 CLI 的 x64 体系结构支持以下 Linux 分发版：

• Ubuntu 20.04/22.04/24.04
• Debian 11/12

注意

语音 SDK（而不是语音 CLI）支持其他体系结构。 有关详细信息，请参阅关于语音 SDK。

按照以下步骤在 x64 CPU 上安装 Linux 上的语音 CLI：

1. 安装 .NET 6。

2. 通过输入以下命令，使用 .NET CLI 安装语音 CLI：

   dotnet tool install --global Microsoft.CognitiveServices.Speech.CLI
   

   若要更新语音 CLI，请输入以下命令：

   dotnet tool update --global Microsoft.CognitiveServices.Speech.CLI
   

3. 安装 GStreamer 以支持压缩音频。

若要查看语音 CLI 的帮助，请输入 spx。

macOS

按照以下步骤在 macOS 10.14 或更高版本上安装语音 CLI：

1. 安装 .NET 6。

2. 通过输入以下命令，使用 .NET CLI 安装语音 CLI：

   dotnet tool install --global Microsoft.CognitiveServices.Speech.CLI
   

   若要更新语音 CLI，请输入以下命令：

   dotnet tool update --global Microsoft.CognitiveServices.Speech.CLI
   

若要查看语音 CLI 的帮助，请输入 spx 或 spx help。

Docker (Windows, Linux, macOS)

以下示例从 Docker Hub 拉取公共容器映像。 建议首先对 Docker Hub 帐户 (docker login) 进行身份验证，而不是发出匿名拉取请求。 若要在使用公共内容时提高可靠性，请在专用 Azure 容器注册表中导入和管理映像。 详细了解如何使用公共映像。

按照以下步骤在 Docker 容器中安装语音 CLI：

1. 为你的平台安装 Docker Desktop（如果尚未安装）。
2. 在新的命令提示符或终端中，输入以下命令：

   docker pull msftspeech/spx
   

若要显示语音 CLI 的帮助信息，请输入以下命令：

docker run -it --rm msftspeech/spx help

在容器中装载目录

语音 CLI 工具将配置设置保存为文件。 它会在执行任何命令（帮助命令除外）时加载这些文件。

在 Docker 容器中使用语音 CLI 时，必须从容器装载本地目录，以便该工具：

• 存储或查找配置设置。
• 读取或写入命令所需的任何文件，例如语音音频文件。

在 Windows 上，输入以下命令以创建一个语音 CLI 可以在容器内使用的本地目录：

mkdir c:\spx-data

在 Linux 或 macOS 上，在终端中输入以下命令以创建目录并查看其绝对路径：

mkdir ~/spx-data
cd ~/spx-data
pwd

调用语音 CLI 时，将使用绝对路径。

在容器中运行语音 CLI

本文档显示了在非 Docker 安装中使用的语音 CLI spx 命令。 在 Docker 容器中调用 spx 命令时，必须将容器中的目录装载到文件系统中，语音 CLI 可在其中存储和查找配置值以及读取和写入文件。

在 Windows 上，命令如下所示：

docker run -it -v c:\spx-data:/data --rm msftspeech/spx

在 Linux 或 macOS 上，命令如以下示例所示。 将 ABSOLUTE_PATH 替换为已装载的目录的绝对路径。 上一部分中的 pwd 命令返回了此路径。 如果在设置密钥和区域之前运行此命令，则将收到一条错误消息，提示你设置密钥和区域。

sudo docker run -it -v ABSOLUTE_PATH:/data --rm msftspeech/spx

若要使用安装在容器中的 spx 命令，请始终输入前面示例中所示的完整命令，然后输入请求的参数。 例如，在 Windows 上，此命令将设置密钥：

docker run -it -v c:\spx-data:/data --rm msftspeech/spx config @key --set SUBSCRIPTION-KEY

若要使用命令行工具进行更扩展的交互，可以通过添加 entrypoint 参数启动具有交互式 Bash shell 的容器。 在 Windows 上，输入以下命令启动一个容器，该容器会公开可输入多个 spx 命令的交互式命令行接口：

docker run -it --entrypoint=/bin/bash -v c:\spx-data:/data --rm msftspeech/spx

可以将它与 AZ Login 结合使用，并让 SPX Init 引导你创建语音密钥并选择匹配的数据区域，无需使用 Azure 门户。 系统将自动存储这些密钥以供以后使用。

docker run -it --rm --entrypoint /bin/bash -v c:\spx-data:/data msftspeech/spx

az login
spx init

创建资源配置

终端

要开始使用，你需要一个语音资源键和区域标识符（例如 eastus、westus）。 在 Azure 门户中创建语音资源。 有关详细信息，请参阅创建 Azure AI 服务资源。

若要配置你的资源密钥和区域标识符，请运行以下命令：

spx config @key --set SPEECH-KEY
spx config @region --set SPEECH-REGION

将存储密钥和区域以用于将来的语音 CLI 命令。 若要查看当前配置，请运行以下命令：

spx config @key
spx config @region

根据需要，请包含 clear 选项以删除任一存储值：

spx config @key --clear
spx config @region --clear

PowerShell

要开始使用，你需要一个语音资源键和区域标识符（例如 eastus、westus）。 在 Azure 门户中创建语音资源。

若要配置你的语音资源密钥和区域标识符，请在 PowerShell 中运行以下命令：

spx --% config @key --set SPEECH-KEY
spx --% config @region --set SPEECH-REGION

将存储密钥和区域以用于将来的 SPX 命令。 若要查看当前配置，请运行以下命令：

spx --% config @key
spx --% config @region

根据需要，请包含 clear 选项以删除任一存储值：

spx --% config @key --clear
spx --% config @region --clear

基本用法

重要

在容器中使用语音 CLI 时，请包含 --host 选项。 还必须指定 --key none 以确保 CLI 不会尝试使用语音密钥进行身份验证。 例如，运行 spx recognize --key none --host wss://localhost:5000/ --file myaudio.wav 以识别语音转文本容器中的音频文件中的语音。

本部分介绍了一些基本的 SPX 命令，这些命令对于首次测试和试验通常非常有用。 运行以下命令以查看工具内帮助：

spx

可按关键字搜索帮助主题。 例如，要查看语音 CLI 用法示例列表，请运行以下命令：

spx help find --topics "examples"

要查看 recognize 命令的选项，请运行以下命令：

spx help recognize

控制台输出中列出了更多帮助命令。 可输入这些命令以获取有关子命令的详细帮助。

语音转文本（语音识别）

注意

在 Docker 容器中运行语音 CLI 时，不能使用计算机的麦克风。 但你可以在本地装载的目录中读取和保存音频文件。

要使用系统的默认麦克风将语音转换为文本（语音识别），请运行以下命令：

spx recognize --microphone

运行该命令后，SPX 开始在当前活动的输入设备上侦听音频。 当你选择 Enter 时，SPX 将停止侦听。 然后，语音音频将被识别并转换为控制台输出中的文本。

使用语音 CLI，你还可以识别音频文件中的语音。 运行以下命令：

spx recognize --file /path/to/file.wav

提示

若你遇到问题或者想要详细了解语音 CLI 的识别选项，可以运行 spx help recognize。

文本转语音（语音合成）

以下命令会将文本作为输入，然后将合成的语音输出到当前活动的输出设备（例如计算机扬声器）。

spx synthesize --text "Testing synthesis using the Speech CLI" --speakers

你还可将合成的输出保存到文件中。 在此示例中，我们可以在运行命令的目录中创建一个名为 my-sample 的文件。

spx synthesize --text "Enjoy using the Speech CLI." --audio output my-sample.wav

这些示例假定你是以英语进行测试的。 但语音服务支持多种语言的语音合成。 你可通过运行以下命令或访问语言支持页面来拉取完整的语音列表。

spx synthesize --voices

以下是使用已发现语音的命令。

spx synthesize --text "Bienvenue chez moi." --voice fr-FR-AlainNeural --speakers

提示

若你遇到问题或者想要详细了解语音 CLI 的识别选项，可以运行 spx help synthesize。

语音到文本的转换

借助语音 CLI，你还可以执行语音到文本的转换。 运行以下命令，可从默认的麦克风捕获音频，并以文本形式输出转换。 记住，你需要通过 translate 命令提供 source 和 target 语言。

spx translate --microphone --source en-US --target ru-RU

将语音翻译成多种语言时，请用分号 (;)分隔语言代码。

spx translate --microphone --source en-US --target 'ru-RU;fr-FR;es-ES'

如果要保存转换的输出，请使用 --output 标志。 在本例中，还可以从文件中进行读取。

spx translate --file /some/file/path/input.wav --source en-US --target ru-RU --output file /some/file/path/russian_translation.txt

提示

若你遇到问题或者想要详细了解语音 CLI 的识别选项，可以运行 spx help translate。

后续步骤

• 安装 GStreamer 以使用 MP3 和其他格式的语音 CLI
• 语音 CLI 的配置选项
• 使用语音 CLI 的批处理操作