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

2025-08-26

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

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

注意

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

下载并安装

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

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

通过输入以下命令，使用 .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）也可以显示所有字体。

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

Ubuntu 20.04/22.04/24.04
Debian 11/12

注意

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

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

安装 .NET 8。

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

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

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

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

安装 GStreamer 以支持压缩音频。

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

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

安装 .NET 8。

通过输入以下命令，使用 .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 Hub 拉取公共容器映像。建议首先对 Docker Hub 帐户 (docker login) 进行身份验证，而不是发出匿名拉取请求。若要提高使用公共内容时的可靠性，请导入和管理专用 Azure 容器注册表中的映像。详细了解如何使用公共映像。

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

为你的平台安装 Docker Desktop（如果尚未安装）。
在新的命令提示符或终端中，输入以下命令：
```
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

如果要开始使用，需要 API 密钥和区域标识符（例如，chinanorth2、chinaeast2）。在 Azure 门户中创建适用于语音的 AI 服务资源。有关详细信息，请参阅创建 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

如果要开始使用，需要 API 密钥和区域标识符（例如，chinanorth2、chinaeast2）。在 Azure 门户中创建适用于语音的 AI 服务资源。

若要配置你的语音资源密钥和区域标识符，请在 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

基本用法

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

spx

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

spx help find --topics "examples"

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

spx help recognize

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

语音转文本（语音识别）

提示

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

识别来自麦克风的语音

运行以下命令，从麦克风开始进行语音识别：
```
spx recognize --microphone --source en-US
```
对麦克风说话，随后可以看到字词会实时转录为文本。 +如果停止说话 30 秒，或者选择 “CtrlC”，语音 CLI 将停止。
```
Connection CONNECTED...
RECOGNIZED: I'm excited to try speech to text.
```

注意

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

从文件中识别语音

若要识别音频文件中的语音，请使用 --file 而不是 --microphone。对于压缩的音频文件（如 MP4），请安装 GStreamer 并使用 --format。有关详细信息，请参阅如何使用压缩的输入音频。

终端
PowerShell

spx recognize --file YourAudioFile.wav
spx recognize --file YourAudioFile.mp4 --format any

spx recognize --file YourAudioFile.wav
spx --% recognize --file YourAudioFile.mp4 --format any

短语列表

若要提高特定字词或语句的识别准确性，请使用短语列表。使用 recognize 命令时也可以在行中加入短语列表或文本文件：

终端
PowerShell

spx recognize --microphone --phrases "Contoso;Jessie;Rehaan;"
spx recognize --microphone --phrases @phrases.txt

spx --% recognize --microphone --phrases "Contoso;Jessie;Rehaan;"
spx --% recognize --microphone --phrases @phrases.txt

语言支持

若要更改语音识别语言，请将 en-US 替换为其他支持的语言。例如，使用 es-ES 表示西班牙语（西班牙）。如果未指定语言，则默认值为 en-US。

spx recognize --microphone --source es-ES

连续识别

若要连续识别超过 30 秒的音频，请追加 --continuous：

spx recognize --microphone --source es-ES --continuous

文本转语音（语音合成）

提示

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

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

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 translate。

翻译来自麦克风的语音

运行以下命令，从麦克风启动语音翻译：

spx translate --source en-US --target it --microphone

对着麦克风说话，并实时看到翻译后的语音转录。 +如果停止说话 30 秒，或者选择 “CtrlC”，语音 CLI 将停止。

Connection CONNECTED...
TRANSLATING into 'it': Sono (from 'I'm')
TRANSLATING into 'it': Sono entusiasta (from 'I'm excited to')
TRANSLATING into 'it': Sono entusiasta di provare la parola (from 'I'm excited to try speech')
TRANSLATED into 'it': Sono entusiasta di provare la traduzione vocale. (from 'I'm excited to try speech translation.')

注意

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

从文件中翻译语音

若要从音频文件翻译语音，请使用 --file 而不是 --microphone。对于压缩的音频文件（如 MP4），请安装 GStreamer 并使用 --format。有关详细信息，请参阅如何使用压缩的输入音频。

终端
PowerShell

spx translate --source en-US --target it --file YourAudioFile.wav
spx translate --source en-US --target it --file YourAudioFile.mp4 --format any

spx translate --source en-US --target it --file YourAudioFile.wav
spx translate --source en-US --target it --file YourAudioFile.mp4 --format any

短语列表

若要提高特定字词或语句的识别准确性，请使用短语列表。使用 translate 命令时也可以在行中加入短语列表或文本文件：

终端
PowerShell

spx translate --source en-US --target it --microphone --phrases "Contoso;Jessie;Rehaan;"
spx translate --source en-US --target it --microphone --phrases @phrases.txt

spx --% translate --source en-US --target it --microphone --phrases "Contoso;Jessie;Rehaan;"
spx --% translate --source en-US --target it --microphone --phrases @phrases.txt

语言支持

若要更改语音识别语言，请将 en-US 替换为其他支持的语言。指定具有短划线 (-) 分隔符的完整区域设置。例如，es-ES 代表西班牙语（西班牙）。如果未指定语言，则默认语言为 en-US。

spx translate --microphone --source es-ES

若要更改翻译目标语言，请将 it 替换为其他支持的语言。在极少数情况下，只需指定区域设置短划线 (-) 分隔符前面的语言代码。例如，对于西班牙语（西班牙）使用 es（而不是 es-ES）。如果未指定语言，则默认语言为 en。

spx translate --microphone --target es

多个目标语言

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

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

连续翻译

对于超过 30 秒的音频连续翻译，请追加 --continuous：

spx translate --source en-US --target it --microphone --continuous

通过

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

下载并安装

字体限制

创建资源配置

基本用法

语音转文本（语音识别）

识别来自麦克风的语音

从文件中识别语音

短语列表

语言支持

连续识别

文本转语音（语音合成）

语音到文本的转换

翻译来自麦克风的语音

从文件中翻译语音

短语列表

语言支持

多个目标语言

保存翻译输出

连续翻译

后续步骤

其他资源