Usar os serviços de Fala por meio de um ponto de extremidade privado

O Link Privado do Azure permite que você se conecte a serviços no Azure usando um ponto de extremidade privado. Um ponto de extremidade privado é um endereço IP privado acessível somente em uma rede virtual e uma sub-rede específicas.

Este artigo explica como configurar e usar o Link Privado e pontos de extremidade privados com o Serviço de Fala. O artigo também descreve como remover os pontos de extremidade privados e continuar usando o recurso de Fala.

Observação

Antes de continuar, revise como usar redes virtuais com os serviços de IA do Azure.

Configurar um recurso de Fala para os cenários de ponto de extremidade privado requer a execução das seguintes tarefas:

1. Criar um nome de domínio personalizado
2. Ativar pontos de extremidade privados
3. Ajustar aplicativos e soluções existentes

Pontos de extremidade privados e pontos de extremidade de serviço de rede virtual

O Azure fornece pontos de extremidade privados e pontos de extremidade de serviço de rede virtual para o tráfego encapsulado através da rede de backbone privada do Azure. A finalidade e as tecnologias subjacentes desses tipos de ponto de extremidade são semelhantes. Mas há diferenças entre as duas tecnologias. Recomendamos que você saiba mais sobre os prós e contras dos dois antes de projetar sua rede.

Há algumas coisas a serem consideradas ao decidir qual tecnologia usar:

• Ambas as tecnologias garantem que o tráfego entre a rede virtual e o Recurso de fala não percorra a Internet pública.
• Um ponto de extremidade privado fornece um endereço IP privado dedicado ao recurso de Fala. Esse endereço IP é acessível somente dentro de uma rede virtual e uma sub-rede específicas. Você tem controle total do acesso a esse endereço IP na infraestrutura de rede.
• Os pontos de extremidade de serviço de rede virtual não fornecem um endereço IP privado dedicado para o Recurso de fala. Em vez disso, eles encapsulam todos os pacotes enviados para o Recurso de fala e os entregam diretamente pela rede de backbone do Azure.
• Ambas as tecnologias dão suporte a cenários locais. Por padrão, quando usam pontos de extremidade de serviço de rede virtual, os recursos de serviço do Azure protegidos para as redes virtuais não podem ser acessados de redes locais. Mas você pode alterar esse comportamento.
• Os pontos de extremidade de serviço de rede virtual geralmente são usados para restringir o acesso de um recurso de fala baseado nas redes virtuais das quais o tráfego se origina.
• Para os serviços de IA do Azure, a habilitação do ponto de extremidade de serviço de rede virtual força o tráfego de todos os recursos dos serviços de IA do Azure a passar pela rede de backbone privada. Isso exige uma configuração explícita de acesso à rede. (Para obter mais informações, consulte Configurar redes virtuais e definir configurações de rede para o recurso de Fala.) Os pontos de extremidade privados não têm essa limitação e fornecem mais flexibilidade para sua configuração de rede. Você pode acessar um recurso por meio do backbone privado e outro por meio da Internet pública usando a mesma sub-rede da mesma rede virtual.
• Os pontos de extremidade privados geram custos extras. Os pontos de extremidade de serviço de rede virtual são gratuitos.
• Os pontos de extremidade privados exigem uma configuração de DNS extra.
• Um recurso de Fala pode funcionar simultaneamente com pontos de extremidade privados e pontos de extremidade de serviço de rede virtual.

Recomendamos que você experimente os dois tipos de ponto de extremidade antes de tomar uma decisão sobre o design de produção.

Para obter mais informações, consulte estes recursos:

• Documentação do Link Privado do Azure e do ponto de extremidade privado
• Documentação dos pontos de extremidade de serviço de rede virtual

Este artigo descreve o uso dos pontos de extremidade privados com o serviço de Fala. O uso dos pontos de extremidade de serviço de VNet é descrito aqui.

Criar um nome de domínio personalizado

Cuidado

Um recurso de Fala com um nome de domínio personalizado e um ponto de extremidade privado ativados interage de maneira diferente com os serviços de Fala. Talvez seja preciso ajustar o código do aplicativo para ambos os cenários: com ponto de extremidade privado e sem ponto de extremidade privado.

Siga as etapas a seguir para criar um nome de subdomínio personalizado para os serviços de IA do Azure para seu recurso de Fala.

Cuidado

Quando você ativa um nome de domínio personalizado, a operação não é reversível. A única maneira de voltar para o nome regional é criar outro recurso de Fala.

Se o recurso de Fala tem muitos modelos e projetos personalizados associados criados por meio do Speech Studio, é altamente recomendável experimentar a configuração com um recurso de teste antes de modificar o recurso usado na produção.

Portal do Azure

Para criar um nome de domínio personalizado usando o portal do Azure, siga estas etapas:

1. Vá para o portal do Azure e entre em sua conta do Azure.

2. Selecione o recurso de Fala necessário.

3. No grupo Gerenciamento de Recursos no painel esquerdo, selecione Rede.

4. Na guia Firewalls e redes virtuais, selecione Gerar nome de domínio personalizado. Um novo painel é exibido à direita, com instruções para criar um subdomínio personalizado exclusivo para o recurso.

5. No painel Gerar nome de domínio personalizado, insira um nome de domínio personalizado. O domínio personalizado completo terá a seguinte aparência: https://{your custom name}.cognitiveservices.azure.com.

   Lembre-se de que, após você criar um nome de domínio personalizado, ele não poderá ser alterado.

   Depois de inserir o nome de domínio personalizado, selecione Salvar.

6. Após a conclusão da operação, no grupo Gerenciamento de recursos, selecione Chaves e ponto de extremidade. Confirme se o novo nome do ponto de extremidade do recurso é iniciado dessa maneira: https://{your custom name}.cognitiveservices.azure.com.

PowerShell

Para criar um nome de domínio personalizado usando o PowerShell, confirme se o computador tem o PowerShell versão 7.x ou posterior com o módulo do Azure PowerShell versão 5.1.0 ou posterior. Para ver as versões dessas ferramentas, siga estas etapas:

1. Em uma janela do PowerShell, digite:

   $PSVersionTable

   Confirme se o valor de PSVersion é 7.x ou posterior. Para atualizar o PowerShell, siga as instruções em Instalando várias versões do PowerShell.

2. Em uma janela do PowerShell, digite:

   Get-Module -ListAvailable Az

   Se nada aparecer ou se a versão do módulo do Azure PowerShell for anterior à 5.1.0, siga as instruções em Instalar o módulo do Azure PowerShell para atualizar.

Antes de continuar, execute Connect-AzAccount para criar uma conexão com o Azure.

Verificar se o nome de domínio personalizado está disponível

Verifique se o domínio personalizado que você deseja usar está disponível. O código a seguir confirma que o domínio está disponível usando a operação Verificar Disponibilidade de Domínio na API REST dos serviços de IA do Azure.

Observação

O código a seguir não funciona no Azure Cloud Shell.

$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.azure.com/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

Se o nome desejado estiver disponível, você verá uma resposta como esta:

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

Se o nome já estiver em uso, você verá a seguinte resposta:

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

Criar o nome de domínio personalizado

Para ativar um nome de domínio personalizado para o recurso de Fala selecionado, use o cmdlet Set-AzCognitiveServicesAccount.

Cuidado

Depois que o código a seguir for executado com êxito, você criará um nome de domínio personalizado para o recurso de Fala. Lembre-se de que o nome não pode ser alterado.

$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 do Azure

Pré-requisitos

• Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.

  

• Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.

  • Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.

  • Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.

  • Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.

Esta seção exige a última versão da CLI do Azure. Se você está usando o Azure Cloud Shell, a última versão já está instalada.

Verificar se o nome de domínio personalizado está disponível

Verifique se o domínio personalizado que deseja usar está disponível. Use o método Verificar Disponibilidade do Domínio da API REST dos serviços de IA do Azure.

Copie o bloco de código a seguir, insira o nome de domínio personalizado de sua experiência e salve-o no arquivo subdomain.json.

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

Copie o arquivo para a pasta atual ou carregue-o no Azure Cloud Shell e execute o comando a seguir. Substitua xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx por sua ID da assinatura do Azure.

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

Se o nome desejado estiver disponível, você verá uma resposta como esta:

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

Se o nome já estiver em uso, você verá a seguinte resposta:

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

Ativar um nome de domínio personalizado

Para usar um nome de domínio personalizado com o recurso de Fala selecionado, use o comando az cognitiveservices account update.

(Se sua conta do Azure tiver apenas uma assinatura ativa, você poderá ignorar esta etapa.) Selecione a assinatura do Azure que contém o recurso de Fala. Substitua xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx por sua ID da assinatura do Azure.

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

Defina o nome de domínio personalizado do recurso selecionado. Substitua os valores de parâmetro de exemplo pelos reais e execute o comando a seguir.

Cuidado

Após a execução bem-sucedida do comando a seguir, você criará um nome de domínio personalizado para o recurso de Fala. Lembre-se de que o nome não pode ser alterado.

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

Ativar pontos de extremidade privados

É recomendável usar a zona DNS privada anexada à rede virtual com as atualizações necessárias para os pontos de extremidade privados. Você pode criar uma zona DNS privada durante o processo de provisionamento. Se estiver usando seu servidor DNS, talvez você precise alterar a configuração do DNS.

Decida sobre a estratégia de DNS antes de provisionar os pontos de extremidade privados para um recurso de Fala na produção. E teste as alterações de DNS, especialmente se você usa seu servidor DNS.

Use um dos artigos a seguir para criar pontos de extremidade privados. Esses artigos usam um aplicativo Web como recurso de exemplo a ser disponibilizado por meio de pontos de extremidade privados.

• Criar um ponto de extremidade privado usando o portal do Azure
• Criar um ponto de extremidade privado usando o Azure PowerShell
• Criar um ponto de extremidade privado usando a CLI do Azure

Use estes parâmetros em vez daqueles no artigo que você escolheu:

Configuração	Valor
Tipo de recurso	Microsoft.CognitiveServices/accounts
Recurso	<nome-do-seu-recurso-de-fala>
Sub-recurso de destino	conta

DNS para pontos de extremidade privados: examine os princípios gerais do DNS para pontos de extremidade privados em recursos dos serviços de IA do Azure. Em seguida, confirme se a configuração do DNS está funcionando corretamente executando as verificações descritas nas seções a seguir.

Resolver o DNS da rede virtual

Essa verificação é obrigatória.

Siga estas etapas para testar a entrada de DNS personalizada da rede virtual:

1. Entre em uma máquina virtual localizada na rede virtual à qual você anexou seu ponto de extremidade privado.

2. Abra um prompt de comando do Windows ou um shell Bash, execute nslookup e confirme que ele resolve com êxito o nome de domínio personalizado do recurso.

   C:\>nslookup my-private-link-speech.cognitiveservices.azure.com
   Server:  UnKnown
   Address:  168.63.129.16
   
   Non-authoritative answer:
   Name:    my-private-link-speech.privatelink.cognitiveservices.azure.com
   Address:  172.28.0.10
   Aliases:  my-private-link-speech.cognitiveservices.azure.com
   

3. Confirme se o endereço IP corresponde ao do ponto de extremidade privado.

Resolver o DNS de outras redes

Execute essa verificação somente se você ativou a opção Todas as redes ou a opção de acesso a Redes e pontos de extremidade privados selecionados na seção Rede do recurso.

Se você planeja acessar o recurso usando apenas um ponto de extremidade privado, ignore esta seção.

1. Entre em um computador anexado a uma rede com permissão para acessar o recurso.

2. Abra um prompt de comando do Windows ou um shell Bash, execute nslookup e confirme que ele resolve com êxito o nome de domínio personalizado do recurso.

   C:\>nslookup my-private-link-speech.cognitiveservices.azure.com
   Server:  UnKnown
   Address:  fe80::1
   
   Non-authoritative answer:
   Name:    vnetproxyv1-weu-prod.westeurope.cloudapp.azure.com
   Address:  13.69.67.71
   Aliases:  my-private-link-speech.cognitiveservices.azure.com
             my-private-link-speech.privatelink.cognitiveservices.azure.com
             westeurope.prod.vnet.cog.trafficmanager.net
   

Observação

O endereço IP resolvido aponta para um ponto de extremidade de proxy de rede virtual, que despacha o tráfego de rede para o ponto de extremidade privado para o recurso de Fala. O comportamento é diferente para um recurso com um nome de domínio personalizado, mas sem pontos de extremidade privados. Confira esta seção para conhecer os detalhes.

Ajustar um aplicativo para usar um recurso de Fala com um ponto de extremidade privado

Um recurso de Fala com um domínio personalizado interage com o Serviço de Fala de maneira diferente. Isso vale para um recurso de Fala habilitado para domínio personalizado com e sem pontos de extremidade privados. As informações nesta seção se aplicam aos dois cenários.

Siga as instruções nesta seção para ajustar os aplicativos e as soluções existentes para usar um recurso de Fala com um nome de domínio personalizado e um ponto de extremidade privado ativados.

Um recurso de Fala com um nome de domínio personalizado e um ponto de extremidade privado ativados interage de maneira diferente com o Serviço de Fala. Esta seção explica como usar esse recurso com as APIs REST do Serviço de Fala e o SDK de Fala.

Observação

Um recurso de Fala sem pontos de extremidade privados que usa um nome de domínio personalizado também tem uma forma especial de interagir com o Serviço de Fala. Essa maneira é diferente do cenário de um recurso de Fala que usa um ponto de extremidade privado. É importante considerar isso porque você pode optar por remover os pontos de extremidade privados posteriormente. Confira Ajustar um aplicativo para usar um recurso de Fala sem pontos de extremidade privados posteriormente neste artigo.

Recurso de Fala com um nome de domínio personalizado e um ponto de extremidade privado: uso com as APIs REST

Usamos my-private-link-speech.cognitiveservices.azure.com como exemplo de nome DNS de recurso de fala (domínio personalizado) para esta seção.

O serviço de Fala tem APIs REST para Conversão de fala em texto e Conversão de texto em fala. Considere as informações a seguir para o cenário de ponto de extremidade privado habilitado.

A Conversão de fala em texto tem duas APIs REST. Cada API tem uma finalidade diferente, usa pontos de extremidade diferentes e requer uma abordagem diferente quando você a está utilizando no cenário com ponto de extremidade privado habilitado.

As APIs REST de Conversão de fala em texto são:

• API REST de reconhecimento de fala, que é usada para Transcrição em lote e Fala personalizada.
• API REST de Conversão de fala em texto para áudios curtos, que é usada para conversão de fala em texto em tempo real.

O uso da API REST de Conversão de fala em texto para áudios curtos e da API REST de Conversão de texto em fala no cenário de ponto de extremidade privado é o mesmo. É equivalente ao caso do SDK de Fala descrito posteriormente neste artigo.

A API REST de Conversão de fala em texto usa um conjunto diferente de pontos de extremidade, portanto, requer uma abordagem diferente para o cenário habilitado para pontos de extremidade privados.

As subseções a seguir descrevem os dois casos.

API REST de conversão de fala em texto

Normalmente, os recursos de fala usam os Pontos de extremidade regionais dos serviços de IA do Azure para se comunicar com a API REST de Conversão de fala em texto. Esses recursos têm o seguinte formato de nomenclatura:

{region}.api.cognitive.microsoft.com.

Esta é uma URL de solicitação de exemplo:

https://westeurope.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions

Observação

Consulte esse artigo para Azure Governamental e Microsoft Azure operados por pontos de extremidade 21Vianet.

Depois de você ativar um domínio personalizado para um recurso de Fala (que é necessário para pontos de extremidade privados), esse recurso usará o seguinte padrão de nome DNS para o ponto de extremidade básico da API REST:

{your custom name}.cognitiveservices.azure.com

Isso significa que, em nosso exemplo, o nome do ponto de extremidade da API REST é:

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

E a URL de solicitação de exemplo precisa ser convertida em:

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

Essa URL deve ser acessível da rede virtual com o ponto de extremidade privado anexado (com a resolução de DNS correta).

Depois de ativar um nome de domínio personalizado para um recurso de Fala, você normalmente substitui o nome do host em todas as URLs de solicitação pelo novo nome de host do domínio personalizado. Todas as outras partes da solicitação (como o caminho /speechtotext/v3.1/transcriptions no exemplo anterior) permanecem as mesmas.

Dica

Alguns clientes desenvolvem aplicativos que usam a parte da região do nome DNS do ponto de extremidade regional (por exemplo, para enviar a solicitação para o recurso de Fala implantado na região específica do Azure).

Um domínio personalizado para um recurso de Fala não contém informações sobre a região em que o recurso foi implantado. Portanto, a lógica de aplicativo descrita anteriormente não funcionará e precisará ser alterada.

API REST de conversão de fala em texto para áudios curtos e API REST de conversão de texto em fala

A API REST de Conversão de fala em texto para áudios curtos e a API REST de Conversão de texto em fala usam dois tipos de pontos de extremidade:

• Pontos de extremidade regionais dos serviços de IA do Azure para se comunicar com a API REST dos serviços de IA do Azure para obter um token de autorização
• Pontos de extremidade especiais para todas as outras operações

Observação

Consulte esse artigo para Azure Governamental e Azure operados por pontos de extremidade 21Vianet.

A descrição detalhada dos pontos de extremidade especiais e de como a URL deles deve ser transformada para um recurso de Fala com ponto de extremidade privado habilitado é fornecida nesta subseção sobre o uso com o SDK de Fala. O mesmo princípio descrito para o SDK se aplica à API REST de Conversão de fala em texto para áudios curtos e à API REST de Conversão de texto em fala.

Familiarize-se com o material na subseção mencionada no parágrafo anterior e veja o exemplo a seguir. O exemplo descreve a API REST de Conversão de texto em fala. O uso da API REST de Conversão de fala em texto para áudios curtos é totalmente equivalente.

Observação

Quando você estiver usando a API REST de Conversão de fala em texto para áudios curtos e a API REST de Conversão de texto em fala em cenários de ponto de extremidade privado, use uma chave de recurso passada pelo cabeçalho Ocp-Apim-Subscription-Key. (Consulte os detalhes da API REST de Conversão de fala em texto para áudios curtos e a API REST de Conversão de texto em fala)

Usar um token de autorização e passá-lo para o ponto de extremidade especial por meio do cabeçalho Authorization funcionará apenas se você tiver ativado a opção de acesso a Todas as redes na seção Rede de seu recurso de Fala. Em outros casos, você receberá um erro Forbidden ou BadRequest ao tentar obter um token de autorização.

Exemplo de uso da API REST de conversão de texto em fala

Usamos a Europa Ocidental como uma amostra da região do Azure e my-private-link-speech.cognitiveservices.azure.com como uma amostra do nome DNS do recurso de Fala (domínio personalizado). O nome de domínio personalizado my-private-link-speech.cognitiveservices.azure.com em nosso exemplo pertence ao recurso de Fala criado na região Oeste da Europa.

Para obter a lista das vozes com suporte na região, execute a seguinte solicitação:

https://westeurope.tts.speech.microsoft.com/cognitiveservices/voices/list

Veja mais detalhes na documentação da API REST de Conversão de texto em fala.

Para o recurso de Fala com ponto de extremidade privado habilitado, a URL do ponto de extremidade para a mesma operação precisa ser modificada. A mesma solicitação tem a seguinte aparência:

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

Confira uma explicação detalhada na subseção Construir a URL do ponto de extremidade para o SDK de Fala.

Recurso de Fala com um nome de domínio personalizado e um ponto de extremidade privado: uso com o SDK de Fala

Usar o SDK de Fala com um nome de domínio personalizado e recursos de Fala com ponto de extremidade privado habilitado exige que você examine e, provavelmente, altere o código do aplicativo.

Usamos my-private-link-speech.cognitiveservices.azure.com como exemplo de nome DNS de recurso de fala (domínio personalizado) para esta seção.

Construir a URL do ponto de extremidade

Normalmente, em cenários de SDK de Fala (e na API REST de conversão de fala em texto para cenários de API REST de áudio curto e de conversão de texto em fala), os recursos de Fala usam os pontos de extremidade regionais dedicados para diferentes ofertas de serviço. O formato de nome DNS para esses pontos de extremidade é:

{region}.{speech service offering}.speech.microsoft.com

Um exemplo de nome DNS é:

westeurope.stt.speech.microsoft.com

Todos os valores possíveis para a região (primeiro elemento do nome DNS) estão listados em Regiões com suporte do serviço de Fala. (Confira este artigo para conhecer os pontos de extremidade do Microsoft Azure Governamental e do Azure operado por 21Vianet.) A seguinte tabela apresenta os possíveis valores para a oferta de serviços de Fala (segundo elemento do nome DNS):

Valor do nome DNS	Oferta de serviço de Fala
commands	Comandos personalizados
convai	Transcrição da reunião
s2s	Tradução de Fala
stt	Conversão de fala em texto
tts	Conversão de texto em fala
voice	Voz personalizada

Portanto, o exemplo anterior (westeurope.stt.speech.microsoft.com) representa um ponto de extremidade de Conversão de fala em texto no Oeste da Europa.

Pontos de extremidade habilitados para pontos de extremidade privados se comunicam com os serviços de Fala por meio de um proxy especial. Por isso, você precisa alterar as URLs de conexão do ponto de extremidade.

Uma URL de ponto de extremidade "padrão" é semelhante a:

{region}.{speech service offering}.speech.microsoft.com/{URL path}

Uma URL de ponto de extremidade privado é semelhante a:

{your custom name}.cognitiveservices.azure.com/{speech service offering}/{URL path}

Exemplo 1. Um aplicativo está se comunicando usando a seguinte URL (reconhecimento de fala usando o modelo de base de inglês dos EUA no Oeste da Europa):

wss://westeurope.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US

Para usá-lo no cenário com ponto de extremidade privado habilitado em que o nome de domínio personalizado do recurso de Fala é my-private-link-speech.cognitiveservices.azure.com, você deve modificar a URL da seguinte maneira:

wss://my-private-link-speech.cognitiveservices.azure.com/stt/speech/recognition/conversation/cognitiveservices/v1?language=en-US

Observe os detalhes:

• O nome do host westeurope.stt.speech.microsoft.com é substituído pelo nome do host de domínio personalizado my-private-link-speech.cognitiveservices.azure.com.
• O segundo elemento do nome DNS original (stt) torna-se o primeiro elemento do caminho da URL e precede o caminho original. Assim, a URL original /speech/recognition/conversation/cognitiveservices/v1?language=en-US se torna /stt/speech/recognition/conversation/cognitiveservices/v1?language=en-US.

Exemplo 2. Um aplicativo usa a seguinte URL para sintetizar a fala no Oeste da Europa:

wss://westeurope.tts.speech.microsoft.com/cognitiveservices/websocket/v1

A seguinte URL equivalente usa um ponto de extremidade privado, em que o nome de domínio personalizado do recurso de Fala é my-private-link-speech.cognitiveservices.azure.com:

wss://my-private-link-speech.cognitiveservices.azure.com/tts/cognitiveservices/websocket/v1

O mesmo princípio do Exemplo 1 é aplicado, mas o elemento chave desta vez é tts.

Modificando aplicativos

Siga estas etapas para modificar o código:

1. Determine a URL do ponto de extremidade do aplicativo:

   • Ative o registro em log para o aplicativo e execute-o para registrar a atividade.
   • No arquivo de log, pesquise por SPEECH-ConnectionUrl. Nas linhas correspondentes, o parâmetro value contém a URL completa que o aplicativo usou para acessar o serviço de Fala.

   Exemplo:

   (114917): 41ms SPX_DBG_TRACE_VERBOSE:  property_bag_impl.cpp:138 ISpxPropertyBagImpl::LogPropertyAndValue: this=0x0000028FE4809D78; name='SPEECH-ConnectionUrl'; value='wss://westeurope.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?traffictype=spx&language=en-US'
   

   Portanto, a URL usada pelo aplicativo neste exemplo é:

   wss://westeurope.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US
   

2. Crie uma instância de SpeechConfig usando uma URL de ponto de extremidade completa:

   1. Modifique o ponto de extremidade que você determinou, conforme descrito na seção anterior Constructo da URL do ponto de extremidade.

   2. Modifique como você cria a instância de SpeechConfig. Provavelmente, seu aplicativo está usando algo assim:

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

      Esse exemplo não funciona para um recurso de fala habilitado para ponto de extremidade privado devido às alterações de nome de host e URL que descrevemos nas seções anteriores. Se você tentar executar seu aplicativo existente sem nenhuma modificação usando a chave de um recurso habilitado para ponto de extremidade privado, receberá um erro de autenticação (401).

      Para fazê-lo funcionar, modifique como você cria a instância da classe SpeechConfig e use a inicialização "do ponto de extremidade"/"com ponto de extremidade". Suponha que tenhamos estas duas variáveis definidas:

      • speechKey contém a chave do recurso de Fala com ponto de extremidade privado habilitado.
      • endPoint contém a URL de ponto de extremidade modificada completa (usando o tipo exigido pela linguagem de programação correspondente). Em nosso exemplo, essa variável deve conter:

        wss://my-private-link-speech.cognitiveservices.azure.com/stt/speech/recognition/conversation/cognitiveservices/v1?language=en-US
        

      Crie uma instância de SpeechConfig:

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

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

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

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

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

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

Dica

Os parâmetros de consulta especificados no URI do ponto de extremidade não serão alterados, mesmo se estiverem definidos por outras APIs. Por exemplo, se o idioma de reconhecimento estiver definido no URI como o parâmetro de consulta language=en-US e também estiver definido como ru-RU por meio da propriedade correspondente, a configuração de idioma no URI será usada. O idioma efetivo é en-US.

Os parâmetros definidos no URI do ponto de extremidade sempre têm precedência. Outras APIs podem substituir apenas parâmetros que não são especificados no URI do ponto de extremidade.

Após essa modificação, seu aplicativo deve funcionar com os recursos de Fala com ponto de extremidade privado habilitado. Estamos trabalhando em um suporte mais contínuo para cenários de ponto de extremidade privado.

Uso do Speech Studio

O Speech Studio é um portal da Web com ferramentas para criar e integrar o serviço de Fala de IA do Azure no seu aplicativo. Quando você trabalha em projetos do Speech Studio, as conexões de rede e as chamadas à API para o recurso de Fala correspondente são feitas em seu nome. Trabalhar com pontos de extremidade privados, pontos de extremidade de serviço de rede virtual e outras opções de segurança de rede pode limitar a disponibilidade dos recursos do Speech Studio. Normalmente, você usa o Speech Studio ao trabalhar com recursos como fala personalizada, voz neural personalizada e Criação de conteúdo de áudio.

Acessar o portal da Web do Speech Studio em uma rede virtual

Para usar o Speech Studio em uma máquina virtual em uma rede virtual do Azure, você deve permitir conexões de saída para o conjunto de marcas de serviço necessário para essa rede virtual. Veja os detalhes aqui.

O acesso ao ponto de extremidade do recurso de Fala não é igual ao acesso ao portal da Web do Speech Studio. Não há suporte para o acesso ao portal da Web do Speech Studio por meio de pontos de extremidade privados ou de serviço da Rede Virtual.

Como trabalhar com projetos do Speech Studio

Esta seção descreve como trabalhar com os diferentes tipos de projetos do Speech Studio para as diferentes opções de segurança de rede do recurso de Fala. Espera-se que a conexão do navegador da Web com o Speech Studio seja estabelecida. As configurações de segurança de rede dos recursos de Fala são definidas no portal do Azure.

1. Vá para o portal do Azure e entre em sua conta do Azure.
2. Selecione o recurso de Fala.
3. No grupo Gerenciamento de Recursos no painel esquerdo, selecione Rede>Firewalls e redes virtuais.
4. Selecione uma opção em Todas as redes, Redes e Pontos de Extremidade Privados Selecionados ou Desabilitado.

Fala Personalizada, Voz Personalizada e Criação de Conteúdo de Áudio

A tabela a seguir descreve a configuração de segurança Rede>Firewalls e redes virtuais de acessibilidade de projeto de Fala Personalizada/Voz Personalizada/Criação de Conteúdo de Áudio por recurso de Fala.

Observação

Se você permitir apenas pontos de extremidade privados por meio da guia Rede>Conexões de ponto de extremidade privado, não poderá usar o Speech Studio com o recurso de Fala. Você ainda pode usar o recurso de Fala fora do Speech Studio.

Configuração de segurança de rede do recurso de Fala	Acessibilidade dos projetos do Speech Studio
Todas as redes	Sem restrições
Redes e pontos de extremidade privados selecionados	Acessível a partir de endereços IP públicos permitidos
Desabilitado	Não acessível

Se você selecionar Redes e pontos de extremidade privados selecionados, verá uma guia com as Redes virtuais e opções de configuração de acesso ao Firewall. Na seção Firewall, você deve permitir pelo menos um endereço IP público e usar esse endereço para a conexão do navegador com o Speech Studio.

Se você permitir apenas o acesso por meio da Rede virtual, na verdade, não permitirá o acesso ao recurso de Fala por meio do Speech Studio. Você ainda pode usar o recurso de Fala fora do Speech Studio.

Para usar a fala personalizada sem flexibilizar as restrições de acesso à rede no recurso de Fala de produção, considere uma destas soluções alternativas.

• Crie outro recurso de Fala para desenvolvimento que possa ser usado em uma rede pública. Prepare o modelo personalizado no Speech Studio no recurso de desenvolvimento e copie o modelo para o recurso de produção. Consulte a solicitação REST Models_CopyTo com a API REST de Conversão de fala em texto.
• Você tem a opção de não usar o Speech Studio para fala personalizada. Use a API REST de Conversão de fala em texto para todas as operações de fala personalizadas.

Para usar a Voz Personalizada sem relaxar as restrições de acesso à rede em seu recurso de Fala de produção, considere usar a API REST de Voz Personalizada para todas as operações de Voz Personalizada.

Ajustar um aplicativo para usar um recurso de Fala sem um ponto de extremidade privado

Neste artigo, observamos várias vezes que a ativação de um domínio personalizado para um recurso de Fala é irreversível. Esse recurso usa uma maneira diferente de se comunicar com o serviço de Fala, em comparação com aqueles que estão usando nomes de ponto de extremidade regionais.

Esta seção explica como usar um recurso de Fala com um nome de domínio personalizado, mas sem nenhum ponto de extremidade privado com as APIs REST do serviço de Fala e o SDK de Fala. Esse pode ser um recurso que era usado em um cenário de ponto de extremidade privado e cujos pontos de extremidade privados foram excluídos.

Configuração de DNS

Lembre-se de como um nome DNS de domínio personalizado do recurso de Fala com ponto de extremidade privado habilitado é resolvido de redes públicas. Nesse caso, o endereço IP resolvido aponta para um ponto de extremidade de proxy para uma rede virtual. Esse ponto de extremidade é usado para despachar o tráfego de rede para o recurso dos serviços de IA do Azure com ponto de extremidade privado habilitado.

No entanto, quando todos os pontos de extremidade privados do recurso são removidos (ou logo após a habilitação do nome de domínio personalizado), o registro CNAME do recurso de Fala é provisionado novamente. Agora, ele aponta para o endereço IP do ponto de extremidade regional dos serviços de IA do Azure correspondente.

Portanto, a saída do comando nslookup tem a seguinte aparência:

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

Non-authoritative answer:
Name:    apimgmthskquihpkz6d90kmhvnabrx3ms3pdubscpdfk1tsx3a.cloudapp.net
Address:  13.93.122.1
Aliases:  my-private-link-speech.cognitiveservices.azure.com
          westeurope.api.cognitive.microsoft.com
          cognitiveweprod.trafficmanager.net
          cognitiveweprod.azure-api.net
          apimgmttmdjylckcx6clmh2isu2wr38uqzm63s8n4ub2y3e6xs.trafficmanager.net
          cognitiveweprod-westeurope-01.regional.azure-api.net

Compare-a com a saída desta seção.

Recurso de Fala com um nome de domínio personalizado e sem pontos de extremidade privados: uso com as APIs REST

API REST de conversão de fala em texto

O uso da API REST de Conversão de fala em texto é totalmente equivalente ao caso de recursos de fala habilitados para pontos de extremidade privados.

API REST de conversão de fala em texto para áudios curtos e API REST de conversão de texto em fala

Nesse caso, o uso da API REST de Conversão de fala em texto para áudios curtos e o uso da API REST de Conversão de texto em fala não têm diferenças em relação ao caso geral, com uma exceção. (Veja a observação a seguir.) Você deve usar ambas as APIs conforme descrito na documentação API REST de Conversão de fala em texto para áudios curtos e API REST de Conversão de texto em fala.

Observação

Quando você estiver usando a API REST de Conversão de fala em texto para áudios curtos e a API REST de Conversão de texto em fala em cenários de domínio personalizados, use uma chave de recurso de Fala passada pelo cabeçalhoOcp-Apim-Subscription-Key. (Consulte os detalhes da API REST de Conversão de fala em texto para áudios curtos e a API REST de Conversão de texto em fala)

Usar um token de autorização e passá-lo para o ponto de extremidade especial por meio do cabeçalho Authorization funcionará apenas se você tiver ativado a opção de acesso a Todas as redes na seção Rede de seu recurso de Fala. Em outros casos, você receberá um erro Forbidden ou BadRequest ao tentar obter um token de autorização.

Recurso de Fala com um nome de domínio personalizado e sem pontos de extremidade privados: uso com o SDK de Fala

Usar o SDK de Fala com recursos de Fala com domínio personalizado habilitado sem pontos de extremidade privados é equivalente ao caso geral, conforme descrito na documentação do SDK de Fala.

Caso você tenha modificado seu código para usá-lo com um recurso de Fala com ponto de extremidade privado habilitado, considere o seguinte.

Na seção sobre recursos de Fala com ponto de extremidade privado habilitado, explicamos como determinar a URL do ponto de extremidade, modificá-la e fazê-la funcionar por meio da inicialização "do ponto de extremidade"/"com o ponto de extremidade" da instância de classe SpeechConfig.

No entanto, se você tentar executar o mesmo aplicativo depois de ter todos os pontos de extremidade privados removidos (aguardando algum tempo para o reprovisionamento de registro DNS correspondente), receberá um erro de serviço interno (404). O motivo é que o registro DNS agora aponta para o ponto de extremidade regional dos serviços de IA do Azure em vez do proxy de rede virtual, e os caminhos de URL como /stt/speech/recognition/conversation/cognitiveservices/v1?language=en-US não são encontrados lá.

Você precisa reverter o aplicativo para a instanciação padrão de SpeechConfig no estilo do seguinte código:

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

Uso simultâneo de pontos de extremidade privados e pontos de extremidade de serviço de rede virtual

Você pode usar os pontos de extremidade privados e os pontos de extremidade de serviço de rede virtual para acessar o mesmo recurso de Fala simultaneamente. Para habilitar esse uso simultâneo, você precisa usar a opção Redes e pontos de extremidade privados selecionados nas configurações de rede do recurso de Fala no portal do Azure. Não há suporte para outras opções nesse cenário.

Preços

Para obter detalhes de preço, confira Preço do Link Privado do Azure.

Saiba mais

• Usar o serviço de Fala por meio de um ponto de extremidade de serviço de rede virtual
• Link Privado do Azure
• Ponto de extremidade do serviço VNet do Azure
• SDK da fala
• API REST de conversão de fala em texto
• API REST de Conversão de texto em fala