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

创建批量听录

使用批量听录,可以批量提交音频数据。 该服务听录音频数据,并将结果存储在存储容器中。 然后,可以从存储容器检索结果

重要

新定价适用于通过语音转文本 REST API v3.2 进行的批量听录。 有关详细信息,请参阅定价指南

先决条件

你需要标准 (S0) 语音资源。 不支持免费资源 (F0)。

创建听录作业

若要创建批量听录作业,请使用语音转文本 REST APITranscriptions_Create 操作。 根据以下说明构造请求正文:

  • 必须设置 contentContainerUrlcontentUrls 属性。 有关适用于批量听录的 Azure blob 存储的详细信息,请参阅找到批量听录的音频文件
  • 设置所需的 locale 属性。 此值应与要听录的音频数据的预期区域设置相匹配。 之后无法更改区域设置。
  • 设置所需的 displayName 属性。 选择稍后可以引用的听录名称。 听录名称不必是独一无二的,以后可以更改。
  • (可选)若要使用基础模型以外的模型,请将 model 属性设置为模型 ID。 有关详细信息,请参阅使用自定义模型和使用 Whisper 模型
  • (可选)将 wordLevelTimestampsEnabled 属性设置为 true 以在听录结果中启用单词级时间戳。 默认值为 false。 对于 Whisper 模型,请改为设置 displayFormWordLevelTimestampsEnabled 属性。 耳语模型是一种仅显示信息的模型,因此不会在听录内容中填充词法字段。
  • (可选)设置 languageIdentification 属性。 语言标识用于在与支持的语言列表比较时确定音频中所说的语言。 如果设置 languageIdentification 属性,则还必须使用候选区域设置设定 languageIdentification.candidateLocales

有关详细信息,请参阅请求配置选项

发出使用 URI 的 HTTP POST 请求,如以下 Transcriptions_Create 示例所示。

  • YourSubscriptionKey 替换为语音资源密钥。
  • YourServiceRegion 替换为你所在的语音资源区域。
  • 如前文所述,设置请求正文属性。
curl -v -X POST -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey" -H "Content-Type: application/json" -d '{
  "contentUrls": [
    "https://crbn.us/hello.wav",
    "https://crbn.us/whatstheweatherlike.wav"
  ],
  "locale": "en-US",
  "displayName": "My Transcription",
  "model": null,
  "properties": {
    "wordLevelTimestampsEnabled": true,
    "languageIdentification": {
      "candidateLocales": [
        "en-US", "de-DE", "es-ES"
      ],
    }
  },
}'  "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions"

你应该会收到以下格式的响应正文:

{
  "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/db474955-ab85-4c6c-ba6e-3bfe63d041ba",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/5988d691-0893-472c-851e-8e36a0fe7aaf"
  },
  "links": {
    "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/db474955-ab85-4c6c-ba6e-3bfe63d041ba/files"
  },
  "properties": {
    "diarizationEnabled": false,
    "wordLevelTimestampsEnabled": true,
    "channels": [
      0,
      1
    ],
    "punctuationMode": "DictatedAndAutomatic",
    "profanityFilterMode": "Masked",
    "languageIdentification": {
      "candidateLocales": [
        "en-US",
        "de-DE",
        "es-ES"
      ]
    }
  },
  "lastActionDateTime": "2024-05-21T14:18:06Z",
  "status": "NotStarted",
  "createdDateTime": "2024-05-21T14:18:06Z",
  "locale": "en-US",
  "displayName": "My Transcription"
}

响应正文中的顶级 self 属性是听录的 URI。 使用此 URI 可获取详细信息,例如听录和听录报告文件的 URI。 还可以使用此 URI 来更新删除听录。

可以通过 Transcriptions_Get 操作查询听录的状态。

检索结果后,请定期从服务中调用 Transcriptions_Delete。 或者,设置 timeToLive 属性以确保最终删除结果。

提示

还可以在 GitHub 上使用 Python、C# 或 Node.js 尝试批量听录 API。

若要创建听录,请使用 spx batch transcription create 命令。 根据以下说明构造请求参数:

  • 设置所需的 content 参数。 可以指定一系列由逗号分隔的各个文件,或指定整个容器的 URL。 有关适用于批量听录的 Azure blob 存储的详细信息,请参阅找到批量听录的音频文件
  • 设置所需的 language 属性。 此值应与要听录的音频数据的预期区域设置相匹配。 之后无法更改区域设置。 语音 CLI language 参数对应于 JSON 请求和响应中的 locale 属性。
  • 设置所需的 name 属性。 选择稍后可以引用的听录名称。 听录名称不必是独一无二的,以后可以更改。 语音 CLI name 参数对应于 JSON 请求和响应中的 displayName 属性。

下面是创建听录作业的语音 CLI 命令的示例:

spx batch transcription create --name "My Transcription" --language "en-US" --content https://crbn.us/hello.wav,https://crbn.us/whatstheweatherlike.wav

你应该会收到以下格式的响应正文:

{
  "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/7f4232d5-9873-47a7-a6f7-4a3f00d00dc0",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/5988d691-0893-472c-851e-8e36a0fe7aaf"
  },
  "links": {
    "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/7f4232d5-9873-47a7-a6f7-4a3f00d00dc0/files"
  },
  "properties": {
    "diarizationEnabled": false,
    "wordLevelTimestampsEnabled": false,
    "channels": [
      0,
      1
    ],
    "punctuationMode": "DictatedAndAutomatic",
    "profanityFilterMode": "Masked"
  },
  "lastActionDateTime": "2024-05-21T14:21:59Z",
  "status": "NotStarted",
  "createdDateTime": "2024-05-21T14:21:59Z",
  "locale": "en-US",
  "displayName": "My Transcription",
  "description": ""
}

响应正文中的顶级 self 属性是听录的 URI。 使用此 URI 可获取详细信息,例如听录和听录报告文件的 URI。 还可以使用此 URI 来更新或删除听录。

若要获取听录的语音 CLI 帮助,请运行以下命令:

spx help batch transcription

请求配置选项

下面是一些属性选项,可用于在调用 Transcriptions_Create 操作时配置听录。 可以在同一页上找到更多示例,例如使用语言识别创建听录

properties 说明
channels 待处理的声道编号数组。 默认情况下会听录频道 01
contentContainerUrl 可以提交单个音频文件或整个存储容器。

必须通过 contentContainerUrlcontentUrls 属性指定音频数据位置。 有关适用于批量听录的 Azure blob 存储的详细信息,请参阅找到批量听录的音频文件

不会在响应中返回此属性。
contentUrls 可以提交单个音频文件或整个存储容器。

必须通过 contentContainerUrlcontentUrls 属性指定音频数据位置。 有关详细信息,请参阅找到批量听录的音频文件

不会在响应中返回此属性。
destinationContainerUrl 结果可以存储在 Azure 容器中。 如果未指定容器,语音服务会将结果存储在由 Microsoft 管理的容器中。 删除听录作业时,听录结果数据也会被删除。 有关详细信息(例如支持的安全方案),请参阅指定目标容器 URL
diarization 表示语音服务应尝试对输入(预期为包含多个声音的单声道通道)进行分割聚类分析。 此功能不适用于立体声录音。

分割聚类是将说话者语音分隔成音频数据的过程。 批处理管道可以在单声道录制中识别和分隔多位说话者。

指定可能存在的说话者的最大和最小数。 还必须将 diarizationEnabled 属性设置为 true听录文件包含每个已听录短语的 speaker 条目。

需要三个或更多个扬声器时,需要使用此属性。 对于两个扬声器的情况,将 diarizationEnabled 属性设置为 true 就足够了。 有关属性用法的示例,请参阅 Transcriptions_Create

要分割的最大讲述人数必须小于 36 且大于或等于 minSpeakers 属性。 有关示例,请参阅 Transcriptions_Create

选择此属性后,源音频长度不能超过每个文件 240 分钟。

注意:此属性仅适用于语音转文本 REST API 版本 3.1 及更高版本。 如果使用任何之前的版本(例如版本 3.0)设置此属性,则会忽略该属性,并且仅标识两个扬声器。
diarizationEnabled 指定语音服务应尝试对输入(预期为包含两个声音的单声道通道)进行分割聚类分析。 默认值为 false

对于三个或更多声音,还需要使用属性 diarization。 仅适用于语音转文本 REST API 版本 3.1 及更高版本。

选择此属性后,源音频长度不能超过每个文件 240 分钟。
displayName 批量听录的名称。 选择稍后可以引用的名称。 显示名称不必是唯一的。

此属性是必需项。
displayFormWordLevelTimestampsEnabled 指定是否在听录结果的显示形式中包含字级别的时间戳。 结果在听录文件的 displayWords 属性中返回。 默认值为 false

注意:此属性仅适用于语音转文本 REST API 版本 3.1 及更高版本。
languageIdentification 语言标识用于在与支持的语言列表比较时确定音频中所说的语言。

如果设置 languageIdentification 属性,则还必须设置其封闭 candidateLocales 属性。
languageIdentification.candidateLocales 语言标识的候选区域设置,例如 "properties": { "languageIdentification": { "candidateLocales": ["en-US", "de-DE", "es-ES"]}}。 支持至少两个和最多十个候选区域设置,包括听录的主要区域设置。
locale 批量听录的区域设置。 此值应与要听录的音频数据的预期区域设置相匹配。 以后无法更改区域设置。

此属性是必需项。
model 可以将 model 属性设置为使用特定基础模型或自定义语音模型。 如果没有指定 model,则使用区域设置的默认基础模型。 有关详细信息,请参阅使用自定义模型和使用 Whisper 模型
profanityFilterMode 指定如何处理识别结果中的不雅内容。 接受的值为 None(禁用不雅内容筛选)、Masked(将不雅内容替换为星号)、Removed(从结果中删除所有不雅内容)或 Tags(添加不雅内容标记)。 默认值为 Masked
punctuationMode 指定如何处理识别结果中的标点。 接受的值为 None(禁用标点)、Dictated(暗示显式(口述)标点)、Automatic(让解码器处理标点),或 DictatedAndAutomatic(使用听写标点和自动标点)。 默认值为 DictatedAndAutomatic

此属性不适用于耳语模型。
timeToLive 创建听录作业后的持续时间,之后会自动删除听录结果。 该值是 ISO 8601 编码持续时间。 例如指定 PT12H 为 12 小时。 或者,检索听录结果后,可定期调用 Transcriptions_Delete
wordLevelTimestampsEnabled 指定是否应在输出中包含字级时间戳。 默认值为 false

此属性不适用于耳语模型。 耳语模型是一种仅显示信息的模型,因此不会在听录内容中填充词法字段。

若要获取听录配置选项的语音 CLI 帮助,请运行以下命令:

spx help batch transcription create advanced

使用自定义模型

批处理听录使用指定区域设置的默认基本模型。 无需设置任何属性即可使用默认基础模型。

(可选)可以通过将 model 属性设置为使用特定的基本模型或自定义语音模型来修改前面的创建听录示例

curl -v -X POST -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey" -H "Content-Type: application/json" -d '{
  "contentUrls": [
    "https://crbn.us/hello.wav",
    "https://crbn.us/whatstheweatherlike.wav"
  ],
  "locale": "en-US",
  "displayName": "My Transcription",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/5988d691-0893-472c-851e-8e36a0fe7aaf"
  },
  "properties": {
    "wordLevelTimestampsEnabled": true,
  },
}'  "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions"
spx batch transcription create --name "My Transcription" --language "en-US" --content https://crbn.us/hello.wav,https://crbn.us/whatstheweatherlike.wav --model "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/5988d691-0893-472c-851e-8e36a0fe7aaf"

若要使用自定义语音模型进行批量听录,你需要模型的 URI。 响应正文中的顶级 self 属性是模型的 URI。 创建或获取模型时,可以检索模型位置。 有关详细信息,请参阅“创建模型”中的 JSON 响应示例。

提示

无需托管部署终结点即可将自定义语音与批量听录服务配合使用。 如果仅将自定义语音模型用于批量听录,则可以节省资源。

已到期模型的批量听录请求会失败,并出现 4xx 错误。 将 model 属性设置为未过期的基础模型或自定义模型。 否则,请不要添加 model 属性,以始终使用最新的基本模型。 有关详细信息,请参阅选择模型自定义语音模型生命周期

使用 Whisper 模型

Azure AI 语音通过批量听录 API 支持 OpenAI 的 Whisper 模型。 可以使用 Whisper 模型进行批量听录。

注意

Azure OpenAI 服务还支持通过同步 REST API 使用 OpenAI 的 Whisper 模型的语音转文本功能。 有关详细信息,请参阅 Azure OpenAI Whisper 模型的语音转文本。 有关何时使用 Azure AI 语音与 Azure OpenAI 服务,请参阅什么是 Whisper 模型?

若要对批量听录使用 Whisper 模型,还需要设置 model 属性。 耳语模型是一种仅显示信息的模型,因此不会在响应中填充词法字段。

重要

在耳语模型中,应始终使用语音转文本 API 版本 3.2

使用 Whisper 模型的批量听录在以下区域受支持:澳大利亚东部、美国中部、美国东部、美国中北部、美国中南部、东南亚和西欧。

可以发出 Models_ListBaseModels 请求,以获取所有区域设置的可用基本模型。

针对 eastus 区域发出 HTTP GET 请求,如以下示例所示。 将 YourSubscriptionKey 替换为语音资源密钥。 如果使用其他区域,请替换 eastus

curl -v -X GET "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base" -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey"

默认仅返回 100 个最早的基本模型。 使用 skiptop 查询参数来翻阅浏览结果。 例如,以下请求返回前 100 个之后的 100 个基础模型。

curl -v -X GET "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base?skip=100&top=100" -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey"

确保在某个受支持的区域中为语音资源设置配置变量。 可以运行 spx csr list --base 命令以获取所有区域设置的可用基本模型。

spx csr list --base --api-version v3.2

耳语模型的 displayName 属性包含了“Whisper”,如以下示例所示。 耳语模型是一种仅显示信息的模型,因此不会在听录内容中填充词法字段。

{
  "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/e418c4a9-9937-4db7-b2c9-8afbff72d950",
  "links": {
    "manifest": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/e418c4a9-9937-4db7-b2c9-8afbff72d950/manifest"
  },
  "properties": {
    "deprecationDates": {
      "adaptationDateTime": "2025-04-15T00:00:00Z",
      "transcriptionDateTime": "2026-04-15T00:00:00Z"
    },
    "features": {
      "supportsTranscriptions": true,
      "supportsEndpoints": false,
      "supportsTranscriptionsOnSpeechContainers": false,
      "supportsAdaptationsWith": [
        "Acoustic"
      ],
      "supportedOutputFormats": [
        "Display"
      ]
    },
    "chargeForAdaptation": true
  },
  "lastActionDateTime": "2024-02-29T15:53:28Z",
  "status": "Succeeded",
  "createdDateTime": "2024-02-29T15:46:07Z",
  "locale": "en-US",
  "displayName": "20240228 Whisper Large V2",
  "description": "OpenAI Whisper Model in Azure AI Speech (Whisper v2-large)"
},

eastus 区域设置完整的模型 URI,如本示例所示。 将 YourSubscriptionKey 替换为语音资源密钥。 如果使用其他区域,请替换 eastus

curl -v -X POST -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey" -H "Content-Type: application/json" -d '{
  "contentUrls": [
    "https://crbn.us/hello.wav",
    "https://crbn.us/whatstheweatherlike.wav"
  ],
  "locale": "en-US",
  "displayName": "My Transcription",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/e418c4a9-9937-4db7-b2c9-8afbff72d950"
  },
  "properties": {
    "wordLevelTimestampsEnabled": true,
  },
}'  "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions"

eastus 区域设置完整的模型 URI,如本示例所示。 如果使用其他区域,请替换 eastus

spx batch transcription create --name "My Transcription" --language "en-US" --content https://crbn.us/hello.wav,https://crbn.us/whatstheweatherlike.wav --model "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/e418c4a9-9937-4db7-b2c9-8afbff72d950" --api-version v3.2

指定目标容器 URL

听录结果可以存储在 Azure 容器中。 如果未指定容器,语音服务会将结果存储在由 Microsoft 管理的容器中。 在这种情况下,删除听录作业的同时,也会删除听录结果数据。

可以使用批量听录创建请求中的选项 destinationContainerUrl 将批量听录的结果存储到可写的 Azure Blob 存储容器中。 此选项仅使用临时 SAS URI,不支持受信任的 Azure 服务安全机制。 此选项也不支持基于访问策略的 SAS。 目标容器的存储帐户资源必须允许所有外部流量。

如果想通过受信任的 Azure 服务安全机制将听录结果存储在 Azure Blob 存储容器中,可考虑使用自带存储 (BYOS)。 有关详细信息,请参阅使用“自带存储”(BYOS) 语音资源将语音转文本