Speech-service gebruiken via een privé-eindpunt

Artikel
01/22/2024

Met Azure Private Link kunt u verbinding maken met services in Azure met behulp van een privé-eindpunt. Een privé-eindpunt is een privé-IP-adres dat alleen toegankelijk is binnen een specifiek virtueel netwerk en subnet.

In dit artikel wordt uitgelegd hoe u Private Link en privé-eindpunten instelt en gebruikt met de Speech-service. In dit artikel wordt vervolgens beschreven hoe u later privé-eindpunten verwijdert, maar nog steeds de Spraak-resource gebruikt.

Notitie

Bekijk voordat u verdergaat hoe u virtuele netwerken gebruikt met Azure AI-services.

Voor het instellen van een Spraak-resource voor de scenario's met privé-eindpunten moet u de volgende taken uitvoeren:

Een aangepaste domeinnaam maken
Privé-eindpunten inschakelen
Bestaande toepassingen en oplossingen aanpassen

Privé-eindpunten en service-eindpunten voor virtueel netwerk

Azure biedt privé-eindpunten en service-eindpunten voor virtueel netwerk voor verkeer dat wordt getunneld via het privé-Azure-backbonenetwerk. Het doel en de onderliggende technologieën van deze eindpunttypen zijn vergelijkbaar. Er zijn echter verschillen tussen de twee technologieën. We raden u aan meer te weten te komen over de voor- en nadelen van beide voordat u uw netwerk ontwerpt.

Er zijn enkele dingen die u moet overwegen wanneer u besluit welke technologie u wilt gebruiken:

Beide technologieën zorgen ervoor dat verkeer tussen het virtuele netwerk en de Spraakresource niet via het openbare internet wordt verplaatst.
Een privé-eindpunt biedt een toegewezen privé-IP-adres voor uw spraakresource. Dit IP-adres is alleen toegankelijk binnen een specifiek virtueel netwerk en subnet. U hebt volledige controle over de toegang tot dit IP-adres binnen uw netwerkinfrastructuur.
Service-eindpunten voor virtual network bieden geen toegewezen privé-IP-adres voor de Spraak-resource. In plaats daarvan kapselen ze alle pakketten in die naar de Spraak-resource worden verzonden en leveren ze rechtstreeks via het Backbone-netwerk van Azure.
Beide technologieën ondersteunen on-premises scenario's. Wanneer ze service-eindpunten voor virtuele netwerken gebruiken, kunnen Azure-servicebronnen die zijn beveiligd met virtuele netwerken, standaard niet worden bereikt vanuit on-premises netwerken. Maar u kunt dat gedrag wijzigen.
Service-eindpunten voor virtueel netwerk worden vaak gebruikt om de toegang voor een Spraak-resource te beperken op basis van de virtuele netwerken waaruit het verkeer afkomstig is.
Voor Azure AI-services dwingt het inschakelen van het service-eindpunt van het virtuele netwerk het verkeer voor alle Azure AI-services-resources door het privé-backbonenetwerk. Hiervoor is expliciete configuratie van netwerktoegang vereist. (Zie voor meer informatie Virtuele netwerken en de netwerkinstellingen voor spraakresources configureren.) Privé-eindpunten hebben deze beperking niet en bieden meer flexibiliteit voor uw netwerkconfiguratie. U hebt toegang tot de ene resource via de privé-backbone en een andere via het openbare internet met hetzelfde subnet van hetzelfde virtuele netwerk.
Voor privé-eindpunten worden extra kosten in rekening gebracht. Service-eindpunten voor virtual network zijn gratis.
Voor privé-eindpunten is extra DNS-configuratie vereist.
Eén Spraak-resource kan tegelijkertijd werken met zowel privé-eindpunten als service-eindpunten voor virtual network.

We raden u aan beide eindpunttypen uit te proberen voordat u een beslissing neemt over uw productieontwerp.

Raadpleeg deze hulpbronnen voor meer informatie:

In dit artikel wordt het gebruik van de privé-eindpunten met de Speech-service beschreven. Het gebruik van de VNet-service-eindpunten wordt hier beschreven.

Een aangepaste domeinnaam maken

Let op

Een Spraak-resource waarvoor een aangepaste domeinnaam is ingeschakeld, maakt gebruik van een andere manier om te communiceren met de Speech-service. Mogelijk moet u uw toepassingscode aanpassen voor beide scenario's: met een privé-eindpunt en zonder privé-eindpunt.

Volg deze stappen om een aangepaste subdomeinnaam te maken voor Azure AI-services voor uw Speech-resource.

Let op

Wanneer u een aangepaste domeinnaam inschakelt, is de bewerking niet omkeerbaar. De enige manier om terug te gaan naar de regionale naam is door een nieuwe Spraak-resource te maken.

Als uw Speech-resource veel aangepaste modellen en projecten bevat die zijn gemaakt via Speech Studio, raden we u ten zeerste aan om de configuratie uit te voeren met een testresource voordat u de resource die in productie wordt gebruikt, wijzigt.

Voer de volgende stappen uit om een aangepaste domeinnaam te maken met behulp van Azure Portal:

Ga naar Azure Portal en meld u aan bij uw account.
Selecteer de vereiste spraakresource.
Selecteer Netwerken in de groep Resourcebeheer in het linkerdeelvenster.
Selecteer Op het tabblad Firewalls en virtuele netwerken de optie Aangepaste domeinnaam genereren. Er wordt een nieuw rechterdeelvenster weergegeven met instructies voor het maken van een uniek aangepast subdomein voor uw resource.
Voer in het deelvenster Aangepaste domeinnaam genereren een aangepaste domeinnaam in. Uw volledige aangepaste domein ziet er als volgt uit: https://{your custom name}.cognitiveservices.azure.com.

Nadat u een aangepaste domeinnaam hebt gemaakt, kan deze niet meer worden gewijzigd.

Nadat u uw aangepaste domeinnaam hebt ingevoerd, selecteert u Opslaan.
Nadat de bewerking is voltooid, selecteert u sleutels en eindpunt in de resourcebeheergroep. Controleer of de naam van het nieuwe eindpunt van uw resource op deze manier wordt gestart: https://{your custom name}.cognitiveservices.azure.com.

Als u een aangepaste domeinnaam wilt maken met behulp van PowerShell, controleert u of uw computer PowerShell versie 7.x of hoger heeft met de Azure PowerShell-module versie 5.1.0 of hoger. Voer de volgende stappen uit om de versies van deze hulpprogramma's te bekijken:

Voer in een PowerShell-venster het volgende in:

$PSVersionTable

Controleer of de PSVersion waarde 7.x of hoger is. Als u PowerShell wilt upgraden, volgt u de instructies bij het installeren van verschillende versies van PowerShell.
Voer in een PowerShell-venster het volgende in:

Get-Module -ListAvailable Az

Als er niets wordt weergegeven of als die versie van de Azure PowerShell-module ouder is dan 5.1.0, volgt u de instructies bij Het installeren van de Azure PowerShell-module om een upgrade uit te voeren .

Voordat u verdergaat, voert u de opdracht uit Connect-AzAccount om een verbinding met Azure te maken.

Controleer of er een aangepaste domeinnaam beschikbaar is

Controleer of het aangepaste domein dat u wilt gebruiken beschikbaar is. Met de volgende code wordt bevestigd dat het domein beschikbaar is met behulp van de bewerking Domein beschikbaarheid controleren in de REST API van Azure AI-services.

Notitie

De volgende code werkt niet in 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

Als de gewenste naam beschikbaar is, ziet u een antwoord als volgt:

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

Als de naam al is gebruikt, ziet u het volgende antwoord:

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

Uw aangepaste domeinnaam maken

Als u een aangepaste domeinnaam wilt inschakelen voor de geselecteerde Speech-resource, gebruikt u de cmdlet Set-AzCognitiveServicesAccount .

Let op

Nadat de volgende code is uitgevoerd, maakt u een aangepaste domeinnaam voor uw Speech-resource. Houd er rekening mee dat deze naam niet kan worden gewijzigd.

$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

Vereisten

Gebruik de Bash-omgeving in Azure Cloud Shell. Zie quickstart voor Bash in Azure Cloud Shell voor meer informatie.
Installeer de Azure CLI, indien gewenst, om CLI-referentieopdrachten uit te voeren. Als u in Windows of macOS werkt, kunt u Azure CLI uitvoeren in een Docker-container. Zie De Azure CLI uitvoeren in een Docker-container voor meer informatie.
- Als u een lokale installatie gebruikt, meldt u zich aan bij Azure CLI met behulp van de opdracht az login. Volg de stappen die worden weergegeven in de terminal, om het verificatieproces te voltooien. Raadpleeg Aanmelden bij Azure CLI voor aanvullende aanmeldingsopties.
- Installeer de Azure CLI-extensie bij het eerste gebruik, wanneer u hierom wordt gevraagd. Raadpleeg Extensies gebruiken met Azure CLI voor meer informatie over extensies.
- Voer az version uit om de geïnstalleerde versie en afhankelijke bibliotheken te vinden. Voer az upgrade uit om te upgraden naar de nieuwste versie.

Voor deze sectie is de nieuwste versie van de Azure CLI vereist. Als u Azure Cloud Shell gebruikt, is de nieuwste versie al geïnstalleerd.

Controleer of de aangepaste domeinnaam beschikbaar is

Controleer of het aangepaste domein dat u wilt gebruiken, gratis is. Gebruik de methode Beschikbaarheid van domein controleren vanuit de REST API van Azure AI-services.

Kopieer het volgende codeblok, voeg de gewenste aangepaste domeinnaam in en sla het bestand subdomain.jsonop.

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

Kopieer het bestand naar uw huidige map of upload het naar Azure Cloud Shell en voer de volgende opdracht uit. Vervang xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx door de id van uw Azure-abonnement.

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

Als de gewenste naam beschikbaar is, ziet u een antwoord als volgt:

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

Als de naam al is gebruikt, ziet u het volgende antwoord:

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

Een aangepaste domeinnaam inschakelen

Als u een aangepaste domeinnaam wilt gebruiken met de geselecteerde Speech-resource, gebruikt u de opdracht az cognitiveservices account update .

(Als uw Azure-account slechts één actief abonnement heeft, kunt u deze stap overslaan.) Selecteer het Azure-abonnement dat de Speech-resource bevat. Vervang xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx door de id van uw Azure-abonnement.

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

Stel de aangepaste domeinnaam in op de geselecteerde resource. Vervang de voorbeeldparameterwaarden door de werkelijke waarden en voer de volgende opdracht uit.

Let op

Nadat de volgende opdracht is uitgevoerd, maakt u een aangepaste domeinnaam voor uw Spraak-resource. Houd er rekening mee dat deze naam niet kan worden gewijzigd.

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

Privé-eindpunten inschakelen

U wordt aangeraden de privé-DNS-zone te gebruiken die is gekoppeld aan het virtuele netwerk met de benodigde updates voor de privé-eindpunten. U kunt tijdens het inrichtingsproces een privé-DNS-zone maken. Als u uw eigen DNS-server gebruikt, moet u mogelijk ook uw DNS-configuratie wijzigen.

Bepaal een DNS-strategie voordat u privé-eindpunten inricht voor een spraakresource voor productie. En test uw DNS-wijzigingen, vooral als u uw eigen DNS-server gebruikt.

Gebruik een van de volgende artikelen om privé-eindpunten te maken. In deze artikelen wordt een web-app gebruikt als voorbeeldresource om deze beschikbaar te maken via privé-eindpunten.

Gebruik deze parameters in plaats van de parameters in het artikel dat u hebt gekozen:

Instelling	Weergegeven als
Brontype	Microsoft.CognitiveServices/accounts
Bron	<naam van uw spraak-resource>
Stel subresource in	account

DNS voor privé-eindpunten: bekijk de algemene principes van DNS voor privé-eindpunten in Azure AI-services-resources. Controleer vervolgens of uw DNS-configuratie correct werkt door de controles uit te voeren die in de volgende secties worden beschreven.

DNS oplossen vanuit het virtuele netwerk

Deze controle is vereist.

Volg deze stappen om de aangepaste DNS-vermelding vanuit uw virtuele netwerk te testen:

Meld u aan bij een virtuele machine in het virtuele netwerk waaraan u uw privé-eindpunt hebt gekoppeld.

Open een Windows-opdrachtprompt of een Bash-shell, voer deze uit nslookupen controleer of de aangepaste domeinnaam van uw resource is omgezet.

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

Controleer of het IP-adres overeenkomt met het IP-adres van uw privé-eindpunt.

DNS van andere netwerken oplossen

Voer deze controle alleen uit als u de optie Alle netwerken of de optie Geselecteerde netwerken en privé-eindpunten hebt ingeschakeld in de sectie Netwerken van uw resource.

Als u van plan bent om toegang te krijgen tot de resource met behulp van alleen een privé-eindpunt, kunt u deze sectie overslaan.

Meld u aan bij een computer die is gekoppeld aan een netwerk dat toegang heeft tot de resource.

Open een Windows-opdrachtprompt of Bash-shell, voer deze uit nslookupen controleer of de aangepaste domeinnaam van uw resource is omgezet.

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

Notitie

Het opgeloste IP-adres verwijst naar een proxy-eindpunt voor een virtueel netwerk, waarmee het netwerkverkeer naar het privé-eindpunt voor de spraakresource wordt verzonden. Het gedrag verschilt voor een resource met een aangepaste domeinnaam, maar zonder privé-eindpunten. Zie deze sectie voor meer informatie.

Een toepassing aanpassen voor het gebruik van een Spraak-resource met een privé-eindpunt

Een Spraak-resource met een aangepast domein communiceert op een andere manier met de Speech-service. Dit geldt voor een spraakresource met aangepast domein, zowel met als zonder privé-eindpunten. Informatie in deze sectie is van toepassing op beide scenario's.

Volg de instructies in deze sectie om bestaande toepassingen en oplossingen aan te passen voor het gebruik van een Spraak-resource met een aangepaste domeinnaam en een privé-eindpunt ingeschakeld.

Een Spraak-resource met een aangepaste domeinnaam en een privé-eindpunt dat is ingeschakeld, maakt gebruik van een andere manier om te communiceren met de Speech-service. In deze sectie wordt uitgelegd hoe u een dergelijke resource gebruikt met de REST API's van de Speech-service en de Speech SDK.

Notitie

Een Spraak-resource zonder privé-eindpunten die een aangepaste domeinnaam gebruiken, heeft ook een speciale manier om te communiceren met de Speech-service. Deze manier verschilt van het scenario van een Spraak-resource die gebruikmaakt van een privé-eindpunt. Dit is belangrijk om rekening mee te houden, omdat u later kunt besluiten om privé-eindpunten te verwijderen. Zie Een toepassing aanpassen om een Spraak-resource te gebruiken zonder privé-eindpunten verderop in dit artikel.

Spraakresource met een aangepaste domeinnaam en een privé-eindpunt: Gebruik met de REST API's

We gebruiken my-private-link-speech.cognitiveservices.azure.com als voorbeeld van de DNS-naam van de spraakresource (aangepast domein) voor deze sectie.

Speech-service heeft REST API's voor spraak-naar-tekst en tekst-naar-spraak. Houd rekening met de volgende informatie voor het scenario met privé-eindpunten.

Spraak-naar-tekst heeft twee REST API's. Elke API heeft een ander doel, maakt gebruik van verschillende eindpunten en vereist een andere benadering wanneer u deze gebruikt in het scenario met privé-eindpunten.

De REST API's voor spraak-naar-tekst zijn:

Rest API voor spraak-naar-tekst, die wordt gebruikt voor Batch-transcriptie en aangepaste spraak.
Rest API voor spraak-naar-tekst voor korte audio, die wordt gebruikt voor realtime spraak naar tekst.

Het gebruik van de REST API voor spraak-naar-tekst voor korte audio en de Text to Speech REST API in het scenario met privé-eindpunten is hetzelfde. Dit is gelijk aan de Speech SDK-case die verderop in dit artikel wordt beschreven.

De REST API voor spraak-naar-tekst maakt gebruik van een andere set eindpunten. Hiervoor is een andere benadering vereist voor het scenario waarvoor privé-eindpunten zijn ingeschakeld.

In de volgende subsecties worden beide gevallen beschreven.

REST API voor spraak-naar-tekst

Spraakresources maken meestal gebruik van regionale eindpunten van Azure AI-services voor communicatie met de REST API voor spraak-naar-tekst. Deze resources hebben de volgende naamgevingsindeling:

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

Dit is een voorbeeldaanvraag-URL:

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

Notitie

Zie dit artikel voor Azure Government en Microsoft Azure beheerd door 21Vianet-eindpunten.

Nadat u een aangepast domein hebt ingeschakeld voor een Spraak-resource (die nodig is voor privé-eindpunten), gebruikt die resource het volgende DNS-naampatroon voor het basis-REST API-eindpunt:

{your custom name}.cognitiveservices.azure.com

Dat betekent dat in ons voorbeeld de naam van het REST API-eindpunt het volgende is:

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

En de voorbeeldaanvraag-URL moet worden geconverteerd naar:

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

Deze URL moet bereikbaar zijn vanuit het virtuele netwerk waaraan het privé-eindpunt is gekoppeld (mits de juiste DNS-resolutie).

Nadat u een aangepaste domeinnaam voor een Spraak-resource hebt ingeschakeld, vervangt u doorgaans de hostnaam in alle aanvraag-URL's door de nieuwe aangepaste domeinnaamhostnaam. Alle andere onderdelen van de aanvraag (zoals het pad /speechtotext/v3.1/transcriptions in het eerdere voorbeeld) blijven hetzelfde.

Tip

Sommige klanten ontwikkelen toepassingen die gebruikmaken van het regiogedeelte van de DNS-naam van het regionale eindpunt (bijvoorbeeld om de aanvraag te verzenden naar de spraakresource die is geïmplementeerd in de specifieke Azure-regio).

Een aangepast domein voor een Spraak-resource bevat geen informatie over de regio waar de resource is geïmplementeerd. De toepassingslogica die eerder is beschreven, werkt dus niet en moet worden gewijzigd.

REST API voor spraak-naar-tekst voor korte audio en tekst-naar-spraak-REST API

De REST API voor spraak-naar-tekst voor korte audio en de REST API voor tekst naar spraak gebruiken twee typen eindpunten:

Regionale eindpunten van Azure AI-services voor communicatie met de REST API van Azure AI-services om een autorisatietoken te verkrijgen
Speciale eindpunten voor alle andere bewerkingen

Notitie

Zie dit artikel voor Azure Government en Azure beheerd door 21Vianet-eindpunten.

De gedetailleerde beschrijving van de speciale eindpunten en hoe hun URL moet worden getransformeerd voor een spraakresource met privé-eindpunten, wordt in deze subsectie gegeven over gebruik met de Speech SDK. Hetzelfde principe dat voor de SDK wordt beschreven, is van toepassing op de Speech to Text REST API voor korte audio en de Text to Speech REST API.

Maak kennis met het materiaal in de subsectie die in de vorige alinea is genoemd en bekijk het volgende voorbeeld. In het voorbeeld wordt de REST API voor tekst naar spraak beschreven. Het gebruik van de REST API voor spraak-naar-tekst voor korte audio is volledig gelijkwaardig.

Notitie

Wanneer u de Spraak-naar-tekst-REST API gebruikt voor korte audio- en tekst-naar-spraak-REST API in privé-eindpuntscenario's, gebruikt u een resourcesleutel die wordt doorgegeven via de Ocp-Apim-Subscription-Key header. (Zie details voor REST API voor spraak naar tekst voor korte audio en tekst naar spraak REST API)

Als u een autorisatietoken gebruikt en doorgeeft aan het speciale eindpunt via de Authorization header, werkt dit alleen als u de optie Alle netwerken-toegang hebt ingeschakeld in de sectie Netwerken van uw spraakresource. In andere gevallen krijgt Forbidden u een of BadRequest meer fouten bij het verkrijgen van een autorisatietoken.

Voorbeeld van rest API-gebruik van tekst-naar-spraak

We gebruiken Europa - west als een Azure-voorbeeldregio en my-private-link-speech.cognitiveservices.azure.com als een voorbeeld van de DNS-naam van de Spraakresource (aangepast domein). De aangepaste domeinnaam my-private-link-speech.cognitiveservices.azure.com in ons voorbeeld behoort tot de spraakresource die is gemaakt in de regio Europa - west.

Voer de volgende aanvraag uit om de lijst met stemmen op te halen die in de regio worden ondersteund:

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

Zie meer informatie in de rest API-documentatie voor tekst-naar-spraak.

Voor de spraakresource met privé-eindpunt moet de eindpunt-URL voor dezelfde bewerking worden gewijzigd. Dezelfde aanvraag ziet er als volgt uit:

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

Zie een gedetailleerde uitleg in de subsectie Eindpunt-URL voor construct voor de Speech SDK.

Spraakresource met een aangepaste domeinnaam en een privé-eindpunt: Gebruik met de Speech SDK

Als u de Speech SDK gebruikt met een aangepaste domeinnaam en spraakresources met een privé-eindpunt, moet u de toepassingscode controleren en waarschijnlijk wijzigen.

We gebruiken my-private-link-speech.cognitiveservices.azure.com als voorbeeld van de DNS-naam van de spraakresource (aangepast domein) voor deze sectie.

Eindpunt-URL samenstellen

Meestal in SDK-scenario's (en in de spraak-naar-tekst-REST API voor korte audio- en tekst-naar-spraak-REST API-scenario's), gebruiken Speech-resources de toegewezen regionale eindpunten voor verschillende serviceaanbiedingen. De DNS-naamindeling voor deze eindpunten is:

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

Een voorbeeld van een DNS-naam is:

westeurope.stt.speech.microsoft.com

Alle mogelijke waarden voor de regio (het eerste element van de DNS-naam) worden vermeld in ondersteunde regio's van de Speech-service. (Zie dit artikel voor Azure Government en Azure beheerd door 21Vianet-eindpunten.) In de volgende tabel ziet u de mogelijke waarden voor de Speech-service (tweede element van de DNS-naam):

DNS-naamwaarde	Speech Service-aanbieding
`commands`	Aangepaste opdrachten
`convai`	Transcriptie van vergadering
`s2s`	Spraakomzetting
`stt`	Spraak naar tekst
`tts`	Tekst naar spraak
`voice`	Aangepaste stem

Het eerdere voorbeeld (westeurope.stt.speech.microsoft.com) staat dus voor een eindpunt voor spraak-naar-tekst in Europa - west.

Eindpunten met privé-eindpunten communiceren met de Speech-service via een speciale proxy. Daarom moet u de URL's van de eindpuntverbinding wijzigen.

Een 'standaard'-eindpunt-URL ziet er als volgt uit:

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

Een PRIVÉ-eindpunt-URL ziet er als volgt uit:

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

Voorbeeld 1. Een toepassing communiceert met behulp van de volgende URL (spraakherkenning met behulp van het basismodel voor Amerikaans-Engels in Europa - west):

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

Als u dit wilt gebruiken in het scenario met privé-eindpunten wanneer de aangepaste domeinnaam van de Spraak-resource is my-private-link-speech.cognitiveservices.azure.com, moet u de URL als volgt wijzigen:

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

Let op de details:

De hostnaam westeurope.stt.speech.microsoft.com wordt vervangen door de naam van de aangepaste domeinnaam my-private-link-speech.cognitiveservices.azure.com.
Het tweede element van de oorspronkelijke DNS-naam (stt) wordt het eerste element van het URL-pad en gaat vooraf aan het oorspronkelijke pad. De oorspronkelijke URL /speech/recognition/conversation/cognitiveservices/v1?language=en-US wordt /stt/speech/recognition/conversation/cognitiveservices/v1?language=en-USdus .

Voorbeeld 2. Een toepassing gebruikt de volgende URL om spraak te synthetiseren in Europa - west:

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

De volgende equivalente URL maakt gebruik van een privé-eindpunt, waarbij de aangepaste domeinnaam van de Speech-resource is my-private-link-speech.cognitiveservices.azure.com:

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

Hetzelfde principe in voorbeeld 1 wordt toegepast, maar het belangrijkste element is dit keer tts.

Toepassingen wijzigen

Volg deze stappen om uw code te wijzigen:

Bepaal de URL van het toepassingseindpunt:

Schakel logboekregistratie voor uw toepassing in en voer deze uit om activiteiten te registreren.
Zoek in het logboekbestand naar SPEECH-ConnectionUrl. In overeenkomende regels bevat de value parameter de volledige URL die uw toepassing heeft gebruikt om de Speech-service te bereiken.

Voorbeeld:

(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'

De URL die de toepassing in dit voorbeeld gebruikt, is dus:

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

Maak een SpeechConfig exemplaar met behulp van een volledige eindpunt-URL:
1. Wijzig het eindpunt dat u hebt bepaald, zoals beschreven in de eerdere sectie Eindpunt-URL van construct.
2. Wijzig hoe u het exemplaar van SpeechConfig. De kans is groot dat uw toepassing iets als volgt gebruikt:
```
var config = SpeechConfig.FromSubscription(speechKey, azureRegion);
```
  Dit voorbeeld werkt niet voor een spraakresource met een privé-eindpunt vanwege de hostnaam en URL-wijzigingen die we in de vorige secties hebben beschreven. Als u uw bestaande toepassing zonder wijzigingen probeert uit te voeren met behulp van de sleutel van een resource met een privé-eindpunt, krijgt u een verificatiefout (401).
  
  Als u dit wilt laten werken, wijzigt u hoe u de SpeechConfig klasse instantiëren en gebruikt u initialisatie 'van eindpunt'/'met eindpunt'. Stel dat de volgende twee variabelen zijn gedefinieerd:
  - speechKey bevat de sleutel van de spraakresource met privé-eindpunt.
  - endPoint bevat de volledige gewijzigde eindpunt-URL (met behulp van het type dat is vereist voor de bijbehorende programmeertaal). In ons voorbeeld moet deze variabele het volgende bevatten:
```
wss://my-private-link-speech.cognitiveservices.azure.com/stt/speech/recognition/conversation/cognitiveservices/v1?language=en-US
```
  SpeechConfig Een exemplaar maken:
```
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);
```

Tip

De queryparameters die zijn opgegeven in de eindpunt-URI, worden niet gewijzigd, zelfs niet als ze zijn ingesteld door andere API's. Als de herkenningstaal bijvoorbeeld is gedefinieerd in de URI als queryparameter language=en-USen ook is ingesteld ru-RU op via de bijbehorende eigenschap, wordt de taalinstelling in de URI gebruikt. De effectieve taal is dan en-US.

Parameters die zijn ingesteld in de eindpunt-URI, hebben altijd voorrang. Andere API's kunnen alleen parameters overschrijven die niet zijn opgegeven in de eindpunt-URI.

Na deze wijziging moet uw toepassing werken met de spraakresources met privé-eindpunten. We werken aan naadlozere ondersteuning van scenario's voor privé-eindpunten.

Gebruik van Speech Studio

Speech Studio is een webportal met hulpprogramma's voor het bouwen en integreren van de Azure AI Speech-service in uw toepassing. Wanneer u in Speech Studio-projecten werkt, worden netwerkverbindingen en API-aanroepen naar de bijbehorende Speech-resource namens u gemaakt. Als u werkt met privé-eindpunten, service-eindpunten voor virtuele netwerken en andere netwerkbeveiligingsopties, kunt u de beschikbaarheid van Speech Studio-functies beperken. Normaal gesproken gebruikt u Speech Studio bij het werken met functies, zoals aangepaste spraak, aangepaste neurale spraak en het maken van audio-inhoud.

Speech Studio-webportal bereiken vanuit een virtueel netwerk

Als u Speech Studio wilt gebruiken vanaf een virtuele machine in een virtueel Azure-netwerk, moet u uitgaande verbindingen met de vereiste set servicetags voor dit virtuele netwerk toestaan. Hier vindt u meer informatie.

Toegang tot het eindpunt van de Spraak-resource is niet gelijk aan toegang tot de Speech Studio-webportal. Toegang tot de Speech Studio-webportal via privé- of virtual network-service-eindpunten wordt niet ondersteund.

Werken met Speech Studio-projecten

In deze sectie wordt beschreven hoe u werkt met het verschillende type Speech Studio-projecten voor de verschillende netwerkbeveiligingsopties van de Speech-resource. Er wordt verwacht dat de webbrowserverbinding met Speech Studio tot stand is gebracht. De beveiligingsinstellingen voor spraakresources zijn ingesteld in Azure Portal.

Ga naar Azure Portal en meld u aan bij uw account.
Selecteer de spraakresource.
Selecteer in de groep Resourcebeheer in het linkerdeelvenster Netwerkfirewalls>en virtuele netwerken.
Selecteer één optie in alle netwerken, geselecteerde netwerken en privé-eindpunten of uitgeschakeld.

Aangepaste spraak

In de volgende tabel wordt de toegankelijkheid van aangepast spraakproject beschreven per Netwerkfirewalls voor spraakresources >en beveiligingsinstelling voor virtuele netwerken.

Notitie

Als u alleen privé-eindpunten toestaat via het >tabblad Verbindingen met privé-eindpunten voor netwerken, kunt u Speech Studio niet gebruiken met de Spraak-resource. U kunt nog steeds de Speech-resource buiten Speech Studio gebruiken.

Beveiligingsinstelling voor spraakresourcenetwerk	Toegankelijkheid van Speech Studio-project
Alle netwerken	Geen beperkingen
Geselecteerde netwerken en privé-eindpunten	Toegankelijk vanaf toegestane openbare IP-adressen
Uitgeschakeld	Niet toegankelijk

Als u Geselecteerde netwerken en privé-eindpunten selecteert, ziet u een tabblad met configuratieopties voor virtuele netwerken en firewalltoegang. In de sectie Firewall moet u ten minste één openbaar IP-adres toestaan en dit adres gebruiken voor de browserverbinding met Speech Studio.

Als u alleen toegang via een virtueel netwerk toestaat, staat u in feite geen toegang tot de Spraak-resource toe via Speech Studio. U kunt nog steeds de Speech-resource buiten Speech Studio gebruiken.

Als u aangepaste spraak wilt gebruiken zonder dat de netwerktoegangsbeperkingen voor uw spraakresource in uw productieomgeving worden versoepeld, kunt u een van deze tijdelijke oplossingen overwegen.

Maak een andere Spraak-resource voor ontwikkeling die kan worden gebruikt in een openbaar netwerk. Bereid uw aangepaste model in Speech Studio voor op de ontwikkelingsresource en kopieer het model vervolgens naar uw productieresource. Zie de Models_CopyTo REST-aanvraag met De REST API voor spraak naar tekst.
U kunt Speech Studio niet gebruiken voor aangepaste spraak. Gebruik de REST API voor spraak naar tekst voor alle aangepaste spraakbewerkingen.

Aangepaste spraak- en audio-inhoud maken

U kunt alleen aangepaste spraak- en audio-inhoudscreatie in Speech Studio-projecten gebruiken wanneer de beveiligingsinstelling voor het spraakresourcenetwerk Alle netwerken is.

Een toepassing aanpassen om een Spraak-resource te gebruiken zonder privé-eindpunten

In dit artikel hebben we meerdere keren opgemerkt dat het inschakelen van een aangepast domein voor een Spraakresource niet ongedaan kan worden gemaakt. Een dergelijke resource maakt gebruik van een andere manier om te communiceren met de Speech-service, vergeleken met de resources die regionale eindpuntnamen gebruiken.

In deze sectie wordt uitgelegd hoe u een Speech-resource gebruikt met een aangepaste domeinnaam, maar zonder privé-eindpunten met de REST API's van de Speech-service en de Speech SDK. Dit kan een resource zijn die eenmaal is gebruikt in een scenario met een privé-eindpunt, maar vervolgens de privé-eindpunten zijn verwijderd.

DNS-configuratie

Vergeet niet hoe een aangepaste DNS-naam van de spraakresource met een privé-eindpunt wordt omgezet vanuit openbare netwerken. In dit geval verwijst het IP-adres naar een proxy-eindpunt voor een virtueel netwerk. Dit eindpunt wordt gebruikt voor het verzenden van het netwerkverkeer naar de azure AI-servicesresource met privé-eindpunten.

Wanneer echter alle privé-eindpunten voor resources worden verwijderd (of direct na het inschakelen van de aangepaste domeinnaam), wordt de CNAME-record van de Speech-resource opnieuw geïmplementeerd. Het verwijst nu naar het IP-adres van het bijbehorende regionale eindpunt van Azure AI-services.

De uitvoer van de nslookup opdracht ziet er dus als volgt uit:

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

Vergelijk deze met de uitvoer van deze sectie.

Spraakresource met een aangepaste domeinnaam en zonder privé-eindpunten: Gebruik met de REST API's

REST API voor spraak-naar-tekst

Spraak-naar-tekst-REST API-gebruik is volledig gelijk aan het geval van spraakresources met privé-eindpunten.

REST API voor spraak-naar-tekst voor korte audio en tekst-naar-spraak-REST API

In dit geval heeft het gebruik van de SPRAAK-naar-tekst-REST API voor korte audio en het gebruik van de REST API voor tekst naar spraak geen verschillen van het algemene geval, met één uitzondering. (Zie de volgende opmerking.) U moet beide API's gebruiken zoals beschreven in de Speech to Text REST API voor korte audio - en tekst-naar-spraak-REST API-documentatie .

Notitie

Wanneer u de Spraak-naar-tekst-REST API gebruikt voor korte audio- en tekst-naar-spraak-REST API in aangepaste domeinscenario's, gebruikt u een Spraak-resourcesleutel die wordt doorgegeven via de Ocp-Apim-Subscription-Key header. (Zie details voor REST API voor spraak naar tekst voor korte audio en tekst naar spraak REST API)

Spraakresource met een aangepaste domeinnaam en zonder privé-eindpunten: Gebruik met de Speech SDK

Het gebruik van de Speech SDK met spraakresources met aangepast domein zonder privé-eindpunten is gelijk aan het algemene geval, zoals beschreven in de Speech SDK-documentatie.

Als u uw code hebt gewijzigd voor gebruik met een spraakresource met privé-eindpunt, kunt u het volgende overwegen.

In de sectie over spraakresources waarvoor privé-eindpunten zijn ingeschakeld, hebben we uitgelegd hoe u de eindpunt-URL kunt bepalen, wijzigen en deze kunt laten werken via initialisatie van het SpeechConfig klasse-exemplaar met eindpunt/eindpunt.

Als u echter dezelfde toepassing probeert uit te voeren nadat alle privé-eindpunten zijn verwijderd (waardoor de bijbehorende DNS-record opnieuw kan worden geïmplementeerd), krijgt u een interne servicefout (404). De reden hiervoor is dat de DNS-record nu verwijst naar het regionale Azure AI-services-eindpunt in plaats van de proxy van het virtuele netwerk, en dat de URL-paden zoals /stt/speech/recognition/conversation/cognitiveservices/v1?language=en-US daar niet worden gevonden.

U moet uw toepassing terugdraaien naar de standaard instantiëring van SpeechConfig de stijl van de volgende code:

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

Gelijktijdig gebruik van privé-eindpunten en service-eindpunten voor virtueel netwerk

U kunt privé-eindpunten en service-eindpunten van virtual network gebruiken om tegelijkertijd toegang te krijgen tot dezelfde Spraak-resource. Als u dit gelijktijdig gebruik wilt inschakelen, moet u de optie Geselecteerde netwerken en privé-eindpunten gebruiken in de netwerkinstellingen van de Spraakresource in Azure Portal. Andere opties worden niet ondersteund voor dit scenario.

Prijzen

Zie prijzen van Azure Private Link voor meer informatie over prijzen.

Speech-service gebruiken via een privé-eindpunt

Privé-eindpunten en service-eindpunten voor virtueel netwerk

Een aangepaste domeinnaam maken

Controleer of er een aangepaste domeinnaam beschikbaar is

Uw aangepaste domeinnaam maken

Vereisten

Controleer of de aangepaste domeinnaam beschikbaar is

Een aangepaste domeinnaam inschakelen

Privé-eindpunten inschakelen

DNS oplossen vanuit het virtuele netwerk

DNS van andere netwerken oplossen

Een toepassing aanpassen voor het gebruik van een Spraak-resource met een privé-eindpunt

Spraakresource met een aangepaste domeinnaam en een privé-eindpunt: Gebruik met de REST API's

REST API voor spraak-naar-tekst

REST API voor spraak-naar-tekst voor korte audio en tekst-naar-spraak-REST API

Spraakresource met een aangepaste domeinnaam en een privé-eindpunt: Gebruik met de Speech SDK

Eindpunt-URL samenstellen

Toepassingen wijzigen

Gebruik van Speech Studio

Speech Studio-webportal bereiken vanuit een virtueel netwerk

Werken met Speech Studio-projecten

Aangepaste spraak

Aangepaste spraak- en audio-inhoud maken

Een toepassing aanpassen om een Spraak-resource te gebruiken zonder privé-eindpunten

DNS-configuratie

Spraakresource met een aangepaste domeinnaam en zonder privé-eindpunten: Gebruik met de REST API's

REST API voor spraak-naar-tekst

REST API voor spraak-naar-tekst voor korte audio en tekst-naar-spraak-REST API

Spraakresource met een aangepaste domeinnaam en zonder privé-eindpunten: Gebruik met de Speech SDK

Gelijktijdig gebruik van privé-eindpunten en service-eindpunten voor virtueel netwerk

Prijzen

Meer informatie

Aanvullende resources