通过专用终结点使用语音服务

Azure 专用链接允许使用专用终结点连接到 Azure 中的服务。专用终结点是只能在特定虚拟网络和子网中访问的专用 IP 地址。

本文介绍如何在语音服务中设置和使用专用链接和专用终结点。然后，它介绍如何在以后移除私有终结点，但仍然可以使用语音资源。

概述步骤

任务	CLI 命令	时间估计
创建自定义域	`az cognitiveservices account update --custom-domain <name>`	1 分钟
检查域可用性	`az rest --method post --url ".../checkDomainAvailability"`	30 秒
创建专用终结点	`az network private-endpoint create ...`	2-3 分钟
配置专用 DNS	`az network private-dns zone create ...`	2-3 分钟
验证 DNS 解析	`nslookup <custom-name>.cognitiveservices.azure.cn`	30 秒

先决条件

在继续操作之前，请查看如何通过 Azure AI 服务使用虚拟网络。

一份 Azure 订阅。如果没有试用版，请创建试用版。使用 az account show 进行验证。
Azure CLI（最新版本）。使用az upgrade安装或更新。使用 az --version 进行验证。
语音资源（S0 级别）。使用 az cognitiveservices account create --kind SpeechServices --sku S0 .... 使用 az cognitiveservices account show --name <name> --resource-group <rg> 进行验证。
包含子网的虚拟网络。使用 az network vnet create .... 使用 az network vnet show --name <vnet> --resource-group <rg> 进行验证。

注意

如果使用 PowerShell 而不是 Azure CLI，则需要 PowerShell 7.x 或更高版本，并安装 Azure PowerShell 模块 5.1.0 或更高版本。使用 $PSVersionTable 和 Get-Module -ListAvailable Az.

为专用终结点方案配置语音资源需要以下任务：

创建自定义域名
启用专用端点
调整现有应用程序和解决方案

专用终结点和虚拟网络服务终结点

Azure为通过Private Azure主干网络隧道的流量提供专用终结点和虚拟网络服务终结点。这些终结点类型的用途和基础技术类似。但这两种技术之间存在差异。建议在设计网络之前了解这两种方法的优缺点。

确定要使用的技术时，需要考虑以下事项：

这两种技术都可确保虚拟网络和语音资源之间的流量不会通过公共 Internet 传输。
专用终结点为语音资源提供专门的专用 IP 地址。只有在特定的虚拟网络和子网中可以访问此 IP 地址。你可以完全控制你的网络基础结构中对此 IP 地址的访问权限。
虚拟网络服务终结点不提供语音资源的专用 IP 地址。相反，它们封装发送到语音资源的所有数据包，并直接通过Azure主干网络传送这些数据包。
这两种技术都支持本地方案。默认情况下，使用虚拟网络服务终结点时，从本地网络无法访问安全地连接到虚拟网络中的Azure服务资源。但你可以更改此行为。
虚拟网络服务端点通常用于根据虚拟网络流量来源控制 AI 服务资源的语音访问权限。
对于Azure AI 服务，启用虚拟网络服务终结点会强制所有Azure AI 服务资源的流量通过专用主干网络。这需要显式网络访问配置。（有关详细信息，请参阅配置虚拟网络和语音资源网络设置。）专用终结点没有此限制，可为你的网络配置提供更大的灵活性。通过使用同一虚拟网络的同一子网，可以实现通过专用主干访问一项资源，同时可以通过公共 Internet 访问另一项资源。
专用终结点会产生额外的费用。虚拟网络服务终结点是免费的。
专用终结点需要额外的 DNS 配置。
一个语音资源可与专用终结点和虚拟网络服务终结点同时工作。

建议先试用这两种终结点类型，再决定生产设计。

有关详细信息，请参阅以下资源：

本文介绍专用终结点与语音服务的用法。 VNet 服务终结点的用法在通过 VNet 服务终结点使用语音服务中介绍。

创建自定义域名

注意

启用了自定义域名的语音资源使用不同的方式与语音服务交互。可能必须为以下两种方案调整应用程序代码：使用专用终结点以及不使用专用终结点。

按照以下步骤为你的语音资源创建 Azure AI 服务的自定义子域名称。

注意

启用自定义域名时，此操作不可逆。返回到区域名称的唯一方法是创建一个新的语音服务资源。

如果语音资源具有大量通过 Speech Studio 创建的关联自定义模型和项目，则强烈建议在修改生产中使用的资源之前，使用测试资源尝试配置。

若要使用 Azure 门户创建自定义域名，请执行以下步骤：

转到 Azure 门户并登录到Azure帐户。
选择所需语音资源。
在左窗格的“资源管理”组中，选择“网络” 。
在“防火墙和虚拟网络”选项卡上，选择“生成自定义域名” 。一个新的右面板随即出现，其中包含有关为资源创建唯一自定义子域的说明。
在“生成自定义域名”面板中，输入自定义域名。完整自定义域会如下所示：https://{your custom name}.cognitiveservices.azure.cn。

请记住，创建自定义域名后，无法更改域名。

输入自定义域名后，请选择“保存”。
操作完成后，在“资源管理”组中，选择“密钥和终结点” 。确认资源的新终结点名称以这种方式开始：https://{your custom name}.cognitiveservices.azure.cn。

若要使用 PowerShell 创建自定义域名，请使用 Azure PowerShell 模块版本 5.1.0 或更高版本确认计算机具有 PowerShell 7.x 或更高版本。若要查看这些工具的版本，请执行以下步骤：

在 PowerShell 窗口中，输入：

$PSVersionTable

确认 PSVersion 值为 7.x 或更高。若要升级 PowerShell，请按照安装各种版本的 PowerShell 中的说明进行操作。
在 PowerShell 窗口中，输入：

Get-Module -ListAvailable Az

如果未显示任何内容，或者Azure PowerShell模块的版本低于 5.1.0，请按照安装 Azure PowerShell 模块的说明进行升级。

在继续之前，请运行 Connect-AzAccount -Environment AzureChinaCloud 以创建与Azure的连接。

验证自定义域名是否可用

检查要使用的自定义域是否可用。以下代码确认域在 Azure AI 服务 REST API 中使用 Check 域可用性操作可用。

$subscriptionId = "Your Azure subscription Id"
$subdomainName = "custom domain name"

# Select the Azure subscription that contains the Speech resource.
# You can skip this step if your Azure account has only one active subscription.
Set-AzContext -SubscriptionId $subscriptionId

# Prepare the OAuth token to use in the request to the Azure AI services REST API.
$Context = Get-AzContext
$AccessToken = (Get-AzAccessToken -TenantId $Context.Tenant.Id).Token
$token = ConvertTo-SecureString -String $AccessToken -AsPlainText -Force

# Prepare and send the request to the Azure AI services REST API.
$uri = "https://management.chinacloudapi.cn/subscriptions/" + $subscriptionId + `
    "/providers/Microsoft.CognitiveServices/checkDomainAvailability?api-version=2017-04-18"
$body = @{
subdomainName = $subdomainName
type = "Microsoft.CognitiveServices/accounts"
}
$jsonBody = $body | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri $uri -ContentType "application/json" -Authentication Bearer `
    -Token $token -Body $jsonBody | Format-List

如果所需名称可用，你会看到如下所示的响应：

isSubdomainAvailable : True
reason               :
type                 :
subdomainName        : my-custom-name

如果名称已被占用，你会看到以下响应：

isSubdomainAvailable : False
reason               : Sub domain name 'my-custom-name' is already used. Please pick a different name.
type                 :
subdomainName        : my-custom-name

创建自定义域名

若要为所选语音资源启用自定义域名，请使用 Set-AzCognitiveServicesAccount cmdlet。

注意

在以下代码成功运行后，你会为语音资源创建自定义域名。请记住，此名称无法更改。

$resourceGroup = "Resource group name where Speech resource is located"
$speechResourceName = "Your Speech resource name"
$subdomainName = "custom domain name"

# Select the Azure subscription that contains the Speech resource.
# You can skip this step if your Azure account has only one active subscription.
$subscriptionId = "Your Azure subscription Id"
Set-AzContext -SubscriptionId $subscriptionId

# Set the custom domain name to the selected resource.
# WARNING: THIS CANNOT BE CHANGED OR UNDONE!
Set-AzCognitiveServicesAccount -ResourceGroupName $resourceGroup `
    -Name $speechResourceName -CustomSubdomainName $subdomainName

如果希望在本地运行 CLI 引用命令，install Azure CLI。如果在 Windows 或 macOS 上运行，请考虑在 Docker 容器中运行Azure CLI。有关详细信息，请参阅如何在 Docker 容器中运行Azure CLI。
- 如果使用本地安装，请使用 az login 命令登录到Azure CLI。若要完成身份验证过程，请遵循终端中显示的步骤。有关其他登录选项，请参阅Azure CLI登录。
- 出现提示时，请在首次使用时安装 Azure CLI 扩展。有关扩展的详细信息，请参阅使用 Azure CLI 的扩展。
- 运行 az version 以查找安装的版本和依赖库。若要升级到最新版本，请运行 az upgrade。

本部分需要最新版本的Azure CLI。

验证自定义域名是否可用

检查要使用的自定义域是否免费。使用 Azure AI 服务 REST API 中的 Check 域可用性方法。

复制以下代码块，插入首选自定义域名，并保存到文件 subdomain.json。

{
    "subdomainName": "custom domain name",
    "type": "Microsoft.CognitiveServices/accounts"
}

运行以下命令。将 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 替换为Azure订阅 ID。

az rest --method post --url "https://management.chinacloudapi.cn/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/providers/Microsoft.CognitiveServices/checkDomainAvailability?api-version=2017-04-18" --body @subdomain.json

如果所需名称可用，你会看到如下所示的响应：

{
  "isSubdomainAvailable": true,
  "reason": null,
  "subdomainName": "my-custom-name",
  "type": null
}

如果名称已被占用，你会看到以下响应：

{
  "isSubdomainAvailable": false,
  "reason": "Sub domain name 'my-custom-name' is already used. Please pick a different name.",
  "subdomainName": "my-custom-name",
  "type": null
}

启用自定义域名

若要为所选语音资源使用自定义域名，请使用 az cognitiveservices account update 命令。

（如果Azure帐户只有一个活动订阅，则可以跳过此步骤。选择包含语音资源的Azure订阅。将 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 替换为Azure订阅 ID。

az account set --subscription xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

将自定义域名设置为所选资源。将示例参数值替换为实际参数值，并运行以下命令。

注意

成功执行以下命令后，你会为语音资源创建自定义域名。请记住，此名称无法更改。

az cognitiveservices account update --name my-speech-resource-name --resource-group my-resource-group-name --custom-domain my-custom-name

启用专用终结点

将附加到虚拟网络的专用 DNS 区域与专用终结点的必要更新配合使用。你可以在预配过程中创建专用 DNS 区域。如果使用自己的 DNS 服务器，则可能需要更改 DNS 配置。

在为生产语音资源预配专用终结点之前，决定 DNS 策略。测试 DNS 更改，尤其是在使用自己的 DNS 服务器时。

创建专用终结点

使用以下步骤为语音资源创建专用终结点。将占位符值替换为实际值：

步骤 1： 确保子网已禁用专用终结点网络策略：

az network vnet subnet update \
  --name <your-subnet-name> \
  --resource-group <your-resource-group-name> \
  --vnet-name <your-vnet-name> \
  --private-endpoint-network-policies Disabled

步骤 2： 创建专用终结点。使用 account 作为Azure AI 服务的目标子资源：

az network private-endpoint create \
  --name <your-private-endpoint-name> \
  --resource-group <your-resource-group-name> \
  --vnet-name <your-vnet-name> \
  --subnet <your-subnet-name> \
  --private-connection-resource-id $(az cognitiveservices account show \
    --name <your-speech-resource-name> \
    --resource-group <your-resource-group-name> \
    --query "id" -o tsv) \
  --group-id account \
  --connection-name <your-connection-name> \
  --location <your-location>

参数	值
资源类型	`Microsoft.CognitiveServices/accounts`
资源	`<your-speech-resource-name>`
目标子资源	`account`

验证： 确认已创建专用终结点：

az network private-endpoint show \
  --name <your-private-endpoint-name> \
  --resource-group <your-resource-group-name> \
  --query "{state:provisioningState, status:privateLinkServiceConnections[0].privateLinkServiceConnectionState.status}" \
  -o json

预期输出： provisioningState 是 Succeeded 且 status 为 Approved.

步骤 3： 创建专用 DNS 区域并将其链接到虚拟网络：

# Create the private DNS zone
az network private-dns zone create \
  --resource-group <your-resource-group-name> \
  --name privatelink.cognitiveservices.azure.cn

# Link the DNS zone to your virtual network
az network private-dns link vnet create \
  --resource-group <your-resource-group-name> \
  --zone-name privatelink.cognitiveservices.azure.cn \
  --name <your-dns-link-name> \
  --virtual-network <your-vnet-name> \
  --registration-enabled false

# Create DNS zone group for automatic DNS record management
az network private-endpoint dns-zone-group create \
  --resource-group <your-resource-group-name> \
  --endpoint-name <your-private-endpoint-name> \
  --name default \
  --private-dns-zone privatelink.cognitiveservices.azure.cn \
  --zone-name cognitiveservices

验证： 确认已创建 DNS A 记录：

az network private-dns record-set a list \
  --resource-group <your-resource-group-name> \
  --zone-name privatelink.cognitiveservices.azure.cn \
  --query "[].{name:name, ip:aRecords[0].ipv4Address}" \
  -o table

预期输出：自定义域名的记录解析为专用终结点的 IP（例如，10.0.0.4）。

专用终结点的DNS：查看 Azure AI 服务资源中专用终结点的 DNS 的一般原则。然后通过执行以下各节中所述的检查，来确认 DNS 配置是否正常工作。

解析来自虚拟网络的 DNS

此检查是必需的。

按照以下步骤测试来自虚拟网络的自定义 DNS 条目：

登录位于专用终结点连接到的虚拟网络中的虚拟机。

打开Windows命令提示符或 Bash shell，运行 nslookup，并确认它已成功解析资源的自定义域名。

C:\>nslookup my-private-link-speech.cognitiveservices.azure.cn
Server:  UnKnown
Address:  168.63.129.16

Non-authoritative answer:
Name:    my-private-link-speech.privatelink.cognitiveservices.azure.cn
Address:  172.28.0.10
Aliases:  my-private-link-speech.cognitiveservices.azure.cn

确认 IP 地址与专用终结点的 IP 地址匹配。

验证： 解析的 IP 地址（例如， 172.28.0.10）与上一步中分配的专用终结点 IP 匹配。该 Name 字段包括在 privatelink 域中。

解析来自其他网络的 DNS

仅当在资源的“网络”部分中打开“所有网络”选项或“所选网络和专用终结点访问”选项时，才执行此检查。

如果计划仅使用专用终结点访问资源，则可以跳过此部分。

登录连接到允许访问资源的网络的计算机。

打开Windows命令提示符或 Bash shell，运行 nslookup，并确认它已成功解析资源的自定义域名。

C:\>nslookup my-private-link-speech.cognitiveservices.azure.cn
Server:  UnKnown
Address:  fe80::1

Non-authoritative answer:
Name:    vnetproxyv1-weu-prod.chinanorth.chinacloudapp.cn
Address:  13.69.67.71
Aliases:  my-private-link-speech.cognitiveservices.azure.cn
          my-private-link-speech.privatelink.cognitiveservices.azure.cn
          chinanorth.prod.vnet.cog.trafficmanager.cn

注意

解析的 IP 地址指向虚拟网络代理终结点，该终结点将网络流量调度到语音资源的专用终结点。对于具有自定义域名但 不包含 专用终结点的资源，行为有所不同。有关详细信息，请参阅 DNS 配置部分。

调整应用程序以将语音资源与专用终结点配合使用

具有自定义域的 Azure AI 语音服务资源以一种不同的方式与语音服务交互。对于启用自定义域的语音资源，无论是否配置专用终结点，情况都是如此。此节中的信息适用于这两种方案。

按照本部分中的说明调整现有应用程序和解决方案，以使用具有自定义域名和专用终结点的语音资源。

注意

使用自定义域名但没有私人终节点的 Azure AI 语音服务资源与语音服务交互时也有特殊的方式。这与使用专用终结点的 Azure AI 服务语音资源方案不同。请务必考虑这一点，因为以后可能会决定删除专用终结点。请参阅本文后面的部分 “调整应用程序以在没有专用终结点的情况下使用语音资源”。

使用 REST API 接口

语音服务具有用于语音转文本和文本转语音的 REST API。对于启用了专用终结点的应用场景，请考虑以下信息。

语音转文本具有两个 REST API。每个 API 使用不同的用途，使用不同的终结点，并在启用专用终结点的方案中使用它时需要采用不同的方法。

语音转文本 REST API 包括：

语音转文本 REST API，用于批量听录和自定义语音识别。
适用于短音频的语音转文本 REST API，用于实时语音转文本。

适用于短音频的语音转文本 REST API 和文本转语音 REST API 在专用终结点方案中的用法是相同的。它相当于本文后面所述的语音 SDK 情况。

语音转文本 REST API 使用一组不同的终结点，因此它要求对启用专用终结点的方案采用不同的方法。

语音转文本 REST API

通常，语音资源使用 Azure AI 服务区域终结点与语音转文本 REST API 通信。这些资源具有以下命名格式：

{region}.api.cognitive.azure.cn

下面是一个示例请求 URL：

https://api.cognitive.azure.cn/speechtotext/v3.1/transcriptions

注意

请参阅本文，了解 Microsoft Azure 由世纪互联节点运营。

启用自定义域名以用于 Azure AI 服务中的语音资源（对于私有终结点是必需的）后，该资源会对基本 REST API 终结点使用以下 DNS 名称模式：

{your-custom-name}.cognitiveservices.azure.cn

在前面的示例中，REST API 终结点名称变为：

my-private-link-speech.cognitiveservices.azure.cn

示例请求 URL 转换为：

https://my-private-link-speech.cognitiveservices.azure.cn/speechtotext/v3.1/transcriptions

此 URL 应该可以从连接了专用终结点的虚拟网络进行访问（如果提供正确的 DNS 解析）。

为 Azure AI 服务的语音资源启用自定义域名后，您通常会将所有请求 URL 中的主机名替换为新的自定义域名。请求的所有其他部分（如前面示例中的路径 /speechtotext/v3.1/transcriptions）会保持不变。

验证： 通过运行来测试终结点：

curl -s -H "Ocp-Apim-Subscription-Key: <your-speech-key>" \
  "https://<your-custom-name>.cognitiveservices.azure.cn/speechtotext/v3.1/transcriptions" | head -c 200

预期输出：包含 values 数组的 JSON 响应（对于新资源可能为空）。

提示

某些客户开发使用区域终结点 DNS 名称的区域部分的应用程序（例如，将请求发送到在特定 Azure 区域中部署的语音资源）。语音资源的自定义域 不包含 有关部署资源的区域的信息。因此，前面所述的应用程序逻辑不起作用，需要更改。

适用于短音频的语音转文本 REST API 和文本转语音 REST API

适用于短音频的语音转文本 REST API 和文本转语音 REST API 使用两种类型的终结点：

Azure AI 服务区域端点，用于通过 Azure AI 服务 REST API 进行通信，以获取授权令牌。
所有其他操作的特殊终结点

注意

请参阅该文章以了解由世纪互联运营的Azure端点。

有关如何将专用终结点启用的语音资源的 URL 转换为私有终结点用途的详细说明，请参阅语音 SDK 使用部分中的构造终结点 URL子节。针对 SDK 介绍的相同原则适用于短音频的语音转文本 REST API 和文本转语音 REST API。熟悉上一段落中提到的小节中的材料，并查看以下示例。该示例说明文本转语音 REST API。适用于短音频的语音转文本 REST API 的用法完全等效。

文本转语音 REST API 使用示例

在此示例中，中国北部是Azure区域，my-private-link-speech.cognitiveservices.azure.cn是语音资源 DNS 名称（自定义域）。自定义域 my-private-link-speech.cognitiveservices.azure.cn 属于在“中国北部”区域创建的语音资源。

若要获取区域中支持的语音列表，请运行：

https://chinanorth.tts.speech.azure.cn/cognitiveservices/voices/list

对于启用了专用终结点的语音资源，相同操作的终结点 URL 将发生更改。相同的请求如下所示：

https://my-private-link-speech.cognitiveservices.azure.cn/tts/cognitiveservices/voices/list

验证： 测试文字转语音 (TTS) 端点：

curl -s -H "Ocp-Apim-Subscription-Key: <your-speech-key>" \
  "https://<your-custom-name>.cognitiveservices.azure.cn/tts/cognitiveservices/voices/list" | head -c 200

预期输出：语音对象的 JSON 数组。非空响应确认终结点正常工作。

请参阅语音 SDK 的构造终结点 URL 小节中的详细说明。

注意

在专用终结点方案中，当使用语音转文本 REST API 处理短音频，或使用文本转语音 REST API 时，请使用通过 Ocp-Apim-Subscription-Key 标头传递的资源密钥。（请参阅适用于短音频的语音转文本 REST API 和文本转语音 REST API 的详细信息）

仅当在语音资源的Authorization”部分中打开“所有网络访问”选项时，才能使用授权令牌并通过标头将其传递给特殊终结点。在其他情况下，尝试获取授权令牌时可能会遇到 Forbidden 或 BadRequest 错误。

使用语音 SDK

将语音 SDK 与启用了自定义域名和专用终结点的语音资源结合使用需要查看并可能会更改应用程序代码。

本部分用 my-private-link-speech.cognitiveservices.azure.cn 作为示例语音资源的 DNS 名称（自定义域）。

构造终结点 URL

通常，在 SDK 方案中（以及语音转文本 REST API 中的短音频和文本转语音 REST API 方案），语音资源将专用区域终结点用于不同的服务产品/服务。这些终结点的 DNS 名称格式为：

{region}.{speech-service-offering}.speech.azure.cn

示例 DNS 名称为：

chinanorth.stt.speech.azure.cn

区域（DNS 名称的第一个元素）的所有可能值都在语音服务支持的区域中列出。（请参阅本文，了解由世纪互联运营的 Azure 终结点。）下表显示了语音服务产品的可能值（DNS 名称的第二个元素）：

DNS 名称值	语音服务产品
`s2s`	语音翻译
`stt`	语音转文本
`tts`	文本转语音

因此，前面的示例 (chinanorth.stt.speech.azure.cn) 代表中国北部的语音转文本终结点。

启用专用终结点的终结点通过特殊代理与语音服务通信。因此，必须更改终结点连接 URL。

“标准”终结点 URL 如下所示：

{region}.{speech-service-offering}.speech.azure.cn/{URL-path}

专用终结点 URL 格式如下：

{your-custom-name}.cognitiveservices.azure.cn/{URL-path}

语音 SDK 会根据所使用的服务自动配置 /{URL-path} 。只需配置基础 URL。

修改应用程序

请按照以下步骤修改代码：

确定应用程序终结点 URL。转到 Azure 门户，打开语音资源，然后在“资源管理”组中选择“密钥和终结点”。或者，使用 CLI：
```
az cognitiveservices account show \
  --name <your-speech-resource-name> \
  --resource-group <your-resource-group-name> \
  --query "properties.endpoint" -o tsv
```
终结点如下所示： https://my-private-link-speech.cognitiveservices.azure.cn/

通过终结点 URL 创建SpeechConfig实例。现有代码可能使用如下内容：

var config = SpeechConfig.FromSubscription(speechKey, azureRegion);

这不适用于启用了专用终结点的语音资源，因为主机名和 URL 发生更改。如果尝试使用已启用专用终结点的资源的密钥来运行现有应用程序而不进行任何修改，则会收到身份验证错误 (401)。

若要解决此问题，请修改实例化 SpeechConfig 类以使用基于终结点的初始化的方式。定义以下两个变量：

speechKey 包含启用了专用终结点的语音资源的密钥。

endPoint 包含完整的已修改端点 URL：

wss://my-private-link-speech.cognitiveservices.azure.cn

然后创建一个 SpeechConfig 实例：

C#:

var config = SpeechConfig.FromEndpoint(endPoint, speechKey);

C++：

auto config = SpeechConfig::FromEndpoint(endPoint, speechKey);

爪哇岛：

SpeechConfig config = SpeechConfig.fromEndpoint(endPoint, speechKey);

Python：

import azure.cognitiveservices.speech as speechsdk
config = speechsdk.SpeechConfig(endpoint=endPoint, subscription=speechKey)

Objective-C：

SPXSpeechConfiguration *config = [[SPXSpeechConfiguration alloc] initWithEndpoint:endPoint subscription:speechKey];

JavaScript：

import * as sdk from "microsoft-cognitiveservices-speech-sdk";
const config = sdk.SpeechConfig.fromEndpoint(new URL(endPoint), speechKey);

进行此修改后，应用程序应使用启用了专用终结点的语音资源。

不使用专用终结点的使用情况

使用启用了自定义域且没有专用终结点的语音资源进行语音 SDK 配置，与本文档所述的包含专用终结点的配置等效。

使用 Speech Studio

Speech Studio 是一个 Web 门户，用于在应用程序中构建和集成Azure语音服务。当你在 Speech Studio 项目中工作时，将代表你进行对相应语音资源的网络连接和 API 调用。使用专用终结点、虚拟网络服务终结点和其他网络安全选项可能会限制 Speech Studio 功能的可用性。使用自定义语音和音频内容创建等功能时，通常使用 Speech Studio。

从虚拟网络访问 Speech Studio

若要从Azure虚拟网络中的虚拟机使用 Speech Studio，请允许与该虚拟网络所需的 service tags 集建立传出连接。请参阅支持的区域和服务产品/服务中的详细信息。

对语音资源端点的访问不等于访问 Speech Studio 门户。不支持通过专用或 VNet 服务终结点访问 Speech Studio。

在 Speech Studio 项目中工作

本部分描述如何使用不同类型的 Speech Studio 项目来应对语音资源的不同网络安全配置。预计应已建立 Web 浏览器与 Speech Studio 的连接。在Azure门户中或使用 CLI 设置语音资源网络安全：

Azure CLI

# View current network settings
az cognitiveservices account show \
  --name <your-speech-resource-name> \
  --resource-group <your-resource-group-name> \
  --query "{publicAccess:properties.publicNetworkAccess, networkRules:properties.networkAcls}" \
  -o json

# Change public network access (options: Enabled, Disabled)
az cognitiveservices account update \
  --name <your-speech-resource-name> \
  --resource-group <your-resource-group-name> \
  --public-network-access Enabled

Azure 门户

转到 Azure 门户并登录到Azure帐户。
选择语音资源。
在左侧窗格的“资源管理”组中，选择“网络”“防火墙和虚拟网络”。
从“所有网络”、“选定的网络和专用终结点”或“禁用”中选择一个选项。

自定义语音和音频内容创建

下表介绍了每个语音资源的“网络”“防火墙和虚拟网络”安全设置的自定义语音识别/有声内容创作辅助功能>。

注意

如果仅允许专用终结点通过 “网络>专用终结点连接 ”选项卡，则不能将 Speech Studio 与语音资源一起使用。仍可以在 Speech Studio 外部使用语音资源。

语音资源网络安全设置	Speech Studio 项目可访问性
所有网络	无限制
所选网络和专用终结点	可从允许的公共 IP 地址访问
已禁用	不可访问

如果选择“ 所选网络”和“专用终结点”，则会看到包含 虚拟网络 和 防火墙 访问配置选项的选项卡。在“防火墙”部分，必须允许至少一个公共 IP 地址，并将该地址用于浏览器与 Speech Studio 的连接。

若要在不放宽对生产语音资源的网络访问限制的情况下使用自定义语音，请考虑以下解决方法之一：

为开发创建另一个可在公共网络上使用的语音资源。在开发资源上的 Speech Studio 中准备自定义模型，然后将该模型复制到你的生产资源。请参阅Models_CopyTo REST 请求和语音转文本 REST API。
可以对所有自定义语音操作（而不是 Speech Studio）使用语音转文本 REST API 。

若要在不放宽对生产语音资源的网络访问限制的情况下使用自定义语音，请考虑以下解决方法之一：

为开发创建另一个可在公共网络上使用的语音资源。在开发资源的 Speech Studio 中准备自定义模型，然后提交 Azure 支持请求，请求协助将模型复制到生产资源。

调整应用程序以在没有专用终结点的情况下使用语音资源

在本文中，多个实例指出，为Azure AI服务的语音资源启用自定义域是不可逆转的。与使用区域终结点名称的方法相比，此类资源会使用不同方式与语音服务通信。

本部分介绍如何使用自定义域名的 Azure AI Services 资源，与语音服务 REST API 和 Speech SDK 集成，且无需专用终结点。这可能是曾经在专用终结点方案中使用过的资源，但随后删除了专用终结点。

DNS 配置

请记住启用了专用终结点的语音资源的自定义域 DNS 名称如何从公用网络进行解析。在这种情况下，解析的 IP 地址指向虚拟网络的代理终结点。该端点用于将网络流量调度到启用专用终端的 Azure AI 服务资源。

但是，删除所有资源专用终结点后（或在启用自定义域名后），会重新预配语音资源的 CNAME 记录。它现在指向相应 Azure AI 服务区域终结点的 IP 地址。

因此，nslookup 命令的输出将如下所示：

C:\>nslookup my-private-link-speech.cognitiveservices.azure.cn
Server:  UnKnown
Address:  fe80::1

Non-authoritative answer:
Name:    apimgmthskquihpkz6d90kmhvnabrx3ms3pdubscpdfk1tsx3a.chinacloudapp.cn
Address:  13.93.122.1
Aliases:  my-private-link-speech.cognitiveservices.azure.cn
          api.cognitive.azure.cn
          cognitiveweprod.trafficmanager.cn
          cognitiveweprod.azure-api.net
          apimgmttmdjylckcx6clmh2isu2wr38uqzm63s8n4ub2y3e6xs.trafficmanager.cn
          cognitiveweprod-chinanorth-01.regional.azure-api.net

将其与从其他网络解析 DNS部分的输出进行比较。

使用 REST API（没有专用终结点）

语音转文本 REST API

语音转文本 REST API 用法完全等同于启用了专用终结点的语音资源的情况。

适用于短音频的语音转文本 REST API 和文本转语音 REST API

在这种情况下，适用于短音频的语音转文本 REST API 的用法和文本转语音 REST API 的用法与常规情况没有区别，但有一个例外。请参阅以下说明。按照短音频语音转文本 REST API 和文本转语音 REST API 文档中的描述，使用这两个 API。

注意

在自定义域场景中使用语音转文本 REST API 进行短音频处理和使用文本转语音 REST API 时，请利用通过Ocp-Apim-Subscription-Key标头传递的 API 密钥。（请参阅适用于短音频的语音转文本 REST API 和文本转语音 REST API 的详细信息）

同时使用专用终结点和虚拟网络服务终结点

可以使用私有终结点和虚拟网络服务终结点来同时访问相同的语音资源。若要启用此同时使用，需要在 Azure 门户中语音资源的网络设置中使用 Selected Networks and Private Endpoints 选项。在这种情况下不支持其他选项。

验证： 通过 CLI 确认网络设置：

az cognitiveservices account show \
  --name <your-speech-resource-name> \
  --resource-group <your-resource-group-name> \
  --query "properties.publicNetworkAccess" -o tsv

在这种情况下不支持其他选项。

清理行动

若要删除在此配置期间创建的资源，请按相反顺序删除它们：

# Delete private endpoint
az network private-endpoint delete \
  --name <your-private-endpoint-name> \
  --resource-group <your-resource-group-name>

# Delete DNS zone group, link, and zone
az network private-dns link vnet delete \
  --resource-group <your-resource-group-name> \
  --zone-name privatelink.cognitiveservices.azure.cn \
  --name <your-dns-link-name> --yes

az network private-dns zone delete \
  --resource-group <your-resource-group-name> \
  --name privatelink.cognitiveservices.azure.cn --yes

注意

删除专用终结点不会删除自定义域名。自定义域保持活动状态，语音资源使用不同的 DNS 解析模式。请参阅 DNS 配置部分。

故障排除

启用自定义域后出现身份验证错误（401）

如果在启用自定义域后收到 401 错误，则应用程序可能仍在使用基于 SpeechConfig.FromSubscription() 区域的初始化。按照SpeechConfig.FromEndpoint()“修改应用程序”部分中所述切换到基于终结点的初始化。

DNS 解析返回公共 IP 而不是专用 IP

如果 nslookup 返回公共 IP 而不是专用终结点 IP：

验证专用 DNS 区域是否存在： az network private-dns zone show --resource-group <rg> --name privatelink.cognitiveservices.azure.cn
验证 VNet 链接是否存在： az network private-dns link vnet list --resource-group <rg> --zone-name privatelink.cognitiveservices.azure.cn -o table
验证 A 记录是否存在： az network private-dns record-set a list --resource-group <rg> --zone-name privatelink.cognitiveservices.azure.cn -o table
如果使用自定义 DNS 服务器，请确保它转发到 Azure 专用 DNS 区域。

使用授权令牌时禁止或出现错误请求

在专用终结点方案中将Authorization标头与持有者令牌一起使用时，语音服务可能会返回Forbidden或BadRequest。如果未将 “网络 ”设置设置为 “所有网络”，则会发生这种情况。请改用 Ocp-Apim-Subscription-Key 资源密钥的标头。

语音工作室不可访问

如果 Speech Studio 不适用于网络受限的语音资源，请检查公共 IP 地址是否位于 防火墙 允许列表中。如果仅允许 VNet 访问，语音工作室将不起作用，请改用 REST API。

定价

有关定价详细信息，请参阅 Azure 专用链接定价。

了解更多信息

Last updated on 2026-04-27

通过专用终结点使用语音服务

概述步骤

先决条件

专用终结点和虚拟网络服务终结点

创建自定义域名

启用专用终结点

创建专用终结点

解析来自虚拟网络的 DNS

解析来自其他网络的 DNS

调整应用程序以将语音资源与专用终结点配合使用

使用 REST API 接口

语音转文本 REST API

适用于短音频的语音转文本 REST API 和文本转语音 REST API

使用语音 SDK

构造终结点 URL

修改应用程序

不使用专用终结点的使用情况

使用 Speech Studio

从虚拟网络访问 Speech Studio

在 Speech Studio 项目中工作

自定义语音和音频内容创建

调整应用程序以在没有专用终结点的情况下使用语音资源

DNS 配置

使用 REST API（没有专用终结点）

语音转文本 REST API

适用于短音频的语音转文本 REST API 和文本转语音 REST API

同时使用专用终结点和虚拟网络服务终结点

清理行动

故障排除

启用自定义域后出现身份验证错误 （401）

DNS 解析返回公共 IP 而不是专用 IP

使用授权令牌时禁止或出现错误请求

语音工作室不可访问

定价

了解更多信息

その他のリソース

启用自定义域后出现身份验证错误（401）