Rozhraní REST API pro převod řeči na text pro krátký zvuk

  • Článek

Případy použití rozhraní REST API pro převod řeči na text jsou omezené. Používejte ho jenom v případech, kdy nemůžete použít sadu Speech SDK.

Než použijete rozhraní REST API pro převod řeči na text pro krátký zvuk, zvažte následující omezení:

Než použijete rozhraní Speech k textovému rozhraní REST API pro krátký zvuk, uvědomte si, že pro přístup ke službě potřebujete dokončit výměnu tokenů. Další informace najdete v tématu Ověřování.

Oblasti a koncové body

Koncový bod rozhraní REST API pro krátký zvuk má tento formát:

https://<REGION_IDENTIFIER>.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1

Nahraďte <REGION_IDENTIFIER> identifikátorem, který odpovídá oblasti vašeho prostředku služby Speech.

Poznámka:

Informace o suverénních cloudech najdete v tomto článku o suverénních cloudech pro Azure Government a Microsoft Azure provozované koncovými body 21Vianet.

Formáty zvuku

Zvuk se odešle v textu požadavku HTTP POST . Musí být v jednom z formátů v této tabulce:

Formát Kodek Přenosová rychlost Vzorkovací frekvence
WAV PCM 256 kb/s 16 kHz, mono
OGG OPUS 256 kb/s 16 kHz, mono

Poznámka:

Předchozí formáty jsou podporovány prostřednictvím rozhraní REST API pro krátký zvuk a WebSocket ve službě Speech. Sada Speech SDK podporuje formát WAV s kodekem PCM a dalšími formáty.

Záhlaví žádosti

Tato tabulka obsahuje seznam povinných a volitelných hlaviček pro požadavky na převod řeči na text:

Hlavička Popis Požadované nebo volitelné
Ocp-Apim-Subscription-Key Váš klíč prostředku pro službu Speech Buď toto záhlaví, nebo Authorization je povinné.
Authorization Autorizační token před slovem Bearer. Další informace najdete v tématu Ověřování. Buď toto záhlaví, nebo Ocp-Apim-Subscription-Key je povinné.
Pronunciation-Assessment Určuje parametry pro zobrazení skóre výslovnosti ve výsledcích rozpoznávání. Tato skóre vyhodnocují kvalitu výslovnosti vstupu řeči s indikátory, jako je přesnost, plynulost a úplnost.

Tento parametr je JSON kódovaný kódem Base64, který obsahuje více podrobných parametrů. Informace o tom, jak vytvořit tuto hlavičku, najdete v tématu Parametry posouzení výslovnosti.		 Volitelné
Content-type Popisuje formát a kodek zadaných zvukových dat. Přijaté hodnoty jsou audio/wav; codecs=audio/pcm; samplerate=16000 a audio/ogg; codecs=opus. Požaduje se
Transfer-Encoding Určuje, že se odesílají blokovaná zvuková data, nikoli jeden soubor. Tato hlavička se používá jenom v případě, že data zvuku blokujete. Volitelné
Expect Pokud používáte blokovaný přenos, odešlete Expect: 100-continue. Služba Speech uznává počáteční požadavek a čeká na další data. Vyžaduje se, pokud odesíláte blokovaná zvuková data.
Accept V případě potřeby musí být application/json. Služba Speech poskytuje výsledky ve formátu JSON. Některé architektury požadavků poskytují nekompatibilní výchozí hodnotu. Je vhodné vždy zahrnout Accept. Volitelné, ale doporučené.

Parametry dotazů

Tyto parametry mohou být zahrnuty do řetězce dotazu požadavku REST.

Poznámka:

Abyste se vyhnuli chybě HTTP 4xx, musíte k adrese URL připojit parametr jazyka. Například jazyk nastavený na angličtinu v USA prostřednictvím koncového bodu USA – západ je: https://westus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US.

Parametr Popis Požadované nebo volitelné
language Identifikuje mluvený jazyk, který je rozpoznán. Viz podporované jazyky. Požaduje se
format Určuje formát výsledku. Přijaté hodnoty jsou simple a detailed. Mezi jednoduché výsledky patří RecognitionStatus, DisplayText, Offseta Duration. Podrobné odpovědi zahrnují čtyři různé reprezentace zobrazovaného textu. Výchozí nastavení je simple. Volitelné
profanity Určuje způsob zpracování vulgárních výrazů ve výsledcích rozpoznávání. Přijaté hodnoty jsou:

masked, který nahrazuje vulgární výraz hvězdičkami.
removed, který z výsledku odebere všechny vulgární výrazy.
rawvčetně vulgárních výrazů ve výsledku.

Výchozí nastavení je masked.		 Volitelné
cid Když k vytváření vlastních modelů používáte Speech Studio, můžete využít hodnotu ID koncového bodu na stránce Nasazení. Jako argument pro parametr řetězce dotazu použijte hodnotu ID koncového cid bodu. Volitelné

Parametry posouzení výslovnosti

Tato tabulka obsahuje seznam povinných a volitelných parametrů pro vyhodnocení výslovnosti:

Parametr Popis Požadované nebo volitelné
ReferenceText Text, proti kterému je výslovnost vyhodnocena. Požaduje se
GradingSystem Bodový systém pro kalibraci skóre. Systém FivePoint získá skóre s plovoucí deseti desetinou čárkou 0–5 a HundredMark získá skóre s plovoucí desetinou čárkou 0–100. Výchozí hodnota: FivePoint. Volitelné
Granularity Členitost vyhodnocení. Přijaté hodnoty jsou:

Phoneme, který zobrazuje skóre na úrovni fulltextu, slova a fofonu.
Word, který zobrazuje skóre na úrovni fulltextu a slov.
FullText, který zobrazuje skóre pouze na úrovni fulltextu.

Výchozí nastavení je Phoneme.		 Volitelné
Dimension Definuje výstupní kritéria. Přijaté hodnoty jsou:

Basic, který zobrazuje pouze skóre přesnosti.
Comprehensive, který zobrazuje skóre na více dimenzích (například skóre fluency a completeness score na úrovni fulltextu a typ chyby na úrovni slova).

Pokud chcete zobrazit definice různých dimenzí skóre a typů chyb slov, podívejte se na vlastnosti odpovědi. Výchozí nastavení je Basic.		 Volitelné
EnableMiscue Povolí výpočet chybného vzorce. Když je tento parametr povolený, výrazná slova se porovnávají s referenčním textem. Jsou označeny vynecháním nebo vložením na základě porovnání. Přijaté hodnoty jsou False a True. Výchozí nastavení je False. Volitelné
ScenarioId Identifikátor GUID, který označuje přizpůsobený bodový systém. Volitelné

Tady je příklad KÓDU JSON, který obsahuje parametry vyhodnocení výslovnosti:

{
  "ReferenceText": "Good morning.",
  "GradingSystem": "HundredMark",
  "Granularity": "FullText",
  "Dimension": "Comprehensive"
}

Následující ukázkový kód ukazuje, jak do hlavičky Pronunciation-Assessment sestavit parametry vyhodnocení výslovnosti:

var pronAssessmentParamsJson = $"{{\"ReferenceText\":\"Good morning.\",\"GradingSystem\":\"HundredMark\",\"Granularity\":\"FullText\",\"Dimension\":\"Comprehensive\"}}";
var pronAssessmentParamsBytes = Encoding.UTF8.GetBytes(pronAssessmentParamsJson);
var pronAssessmentHeader = Convert.ToBase64String(pronAssessmentParamsBytes);

Při odesílání zvukových dat důrazně doporučujeme nahrávat streamované (blokované přenosy), což může výrazně snížit latenci. Informace o povolení streamování najdete v ukázkovém kódu v různých programovacích jazycích.

Poznámka:

Další informace najdete v tématu Hodnocení výslovnosti.

Ukázkový požadavek

Následující ukázka obsahuje název hostitele a požadované hlavičky. Je důležité si uvědomit, že služba také očekává zvuková data, která nejsou součástí této ukázky. Jak už bylo zmíněno dříve, doporučuje se, ale nevyžaduje se vytváření bloků dat.

POST speech/recognition/conversation/cognitiveservices/v1?language=en-US&format=detailed HTTP/1.1
Accept: application/json;text/xml
Content-Type: audio/wav; codecs=audio/pcm; samplerate=16000
Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY
Host: westus.stt.speech.microsoft.com
Transfer-Encoding: chunked
Expect: 100-continue

Pokud chcete povolit hodnocení výslovnosti, můžete přidat následující hlavičku. Informace o tom, jak vytvořit tuto hlavičku, najdete v tématu Parametry posouzení výslovnosti.

Pronunciation-Assessment: eyJSZWZlcm...

Stavové kódy HTTP

Stavový kód HTTP pro každou odpověď označuje úspěch nebo běžné chyby.

Stavový kód HTTP Popis Možné příčiny
100 Pokračovat Počáteční požadavek se přijme. Pokračujte v odesílání zbývajících dat. (Tento kód se používá s blokovaným přenosem.)
200 OK Požadavek byl úspěšný. Tělo odpovědi je objekt JSON.
400 Chybný požadavek Kód jazyka nebyl poskytnut, jazyk není podporovaný nebo je zvukový soubor neplatný (například).
401 Neautorizováno Klíč prostředku nebo autorizační token je v zadané oblasti neplatný nebo koncový bod je neplatný.
403 Zakázáno Chybí klíč prostředku nebo autorizační token.

Ukázkové odpovědi

Tady je typická odpověď pro simple rozpoznávání:

{
  "RecognitionStatus": "Success",
  "DisplayText": "Remind me to buy 5 pencils.",
  "Offset": "1236645672289",
  "Duration": "1236645672289"
}

Tady je typická odpověď pro detailed rozpoznávání:

{
  "RecognitionStatus": "Success",
  "Offset": "1236645672289",
  "Duration": "1236645672289",
  "NBest": [
    {
      "Confidence": 0.9052885,
      "Display": "What's the weather like?",
      "ITN": "what's the weather like",
      "Lexical": "what's the weather like",
      "MaskedITN": "what's the weather like"
    },
    {
      "Confidence": 0.92459863,
      "Display": "what is the weather like",
      "ITN": "what is the weather like",
      "Lexical": "what is the weather like",
      "MaskedITN": "what is the weather like"
    }
  ]
}

Tady je typická odpověď pro rozpoznávání pomocí vyhodnocení výslovnosti:

{
  "RecognitionStatus": "Success",
  "Offset": "400000",
  "Duration": "11000000",
  "NBest": [
      {
        "Confidence" : "0.87",
        "Lexical" : "good morning",
        "ITN" : "good morning",
        "MaskedITN" : "good morning",
        "Display" : "Good morning.",
        "PronScore" : 84.4,
        "AccuracyScore" : 100.0,
        "FluencyScore" : 74.0,
        "CompletenessScore" : 100.0,
        "Words": [
            {
              "Word" : "Good",
              "AccuracyScore" : 100.0,
              "ErrorType" : "None",
              "Offset" : 500000,
              "Duration" : 2700000
            },
            {
              "Word" : "morning",
              "AccuracyScore" : 100.0,
              "ErrorType" : "None",
              "Offset" : 5300000,
              "Duration" : 900000
            }
        ]
      }
  ]
}

Vlastnosti odpovědi

Výsledky jsou k dispozici ve formátu JSON. Formát simple obsahuje následující pole nejvyšší úrovně:

Vlastnost Popis
RecognitionStatus Stav, například Success pro úspěšné uznání. Podívejte se na další tabulku.
DisplayText Rozpoznaný text po psaní velkých písmen, interpunkci, normalizaci inverzního textu a maskování vulgárních výrazů. Prezentovat pouze při úspěchu. Inverzní normalizace textu je převod mluveného textu na kratší formy, například 200 pro "dvě stě" nebo "Dr. Smith" pro "doktor smith".
Offset Čas (v 100 nanosekundových jednotkách), kdy rozpoznaná řeč začíná ve zvukovém streamu.
Duration Doba trvání rozpoznané řeči ve zvukovém streamu (v 100 nanosekundových jednotkách).

Pole RecognitionStatus může obsahovat tyto hodnoty:

Status Popis
Success Rozpoznávání bylo úspěšné a DisplayText pole je přítomné.
NoMatch Ve zvukovém streamu byla zjištěna řeč, ale nebyla nalezena žádná slova z cílového jazyka. Tento stav obvykle znamená, že jazyk rozpoznávání se liší od jazyka, který uživatel mluví.
InitialSilenceTimeout Začátek zvukového streamu obsahoval pouze ticho a služba vypršela při čekání na řeč.
BabbleTimeout Začátek zvukového streamu obsahoval pouze šum a při čekání na řeč vypršel časový limit služby.
Error Služba rozpoznávání zjistila vnitřní chybu a nemohla pokračovat. Pokud je to možné, zkuste to znovu.

Poznámka:

Pokud se zvuk skládá pouze z vulgárních výrazů a profanity parametr dotazu je nastavený na remove, služba nevrací výsledek řeči.

Formát detailed obsahuje více forem rozpoznaných výsledků. Pokud používáte detailed formát, DisplayText zobrazí se pro Display každý výsledek v NBest seznamu.

Objekt v NBest seznamu může obsahovat:

Vlastnost Popis
Confidence Skóre spolehlivosti položky, od 0,0 (bez spolehlivosti) do 1,0 (úplná spolehlivost).
Lexical Lexikální forma rozpoznaného textu: skutečná slova rozpoznaná.
ITN Inverzní text normalizovaný (ITN) nebo kanonický tvar rozpoznaného textu s telefonními čísly, čísly, zkratkami ("doktor smith" na "dr smith") a dalšími použitými transformacemi.
MaskedITN Formulář ITN s použitým maskováním vulgárních výrazů v případě potřeby.
Display Formát zobrazení rozpoznaného textu s přidanou interpunkcí a velkými písmeny Tento parametr je stejný jako parametr, který DisplayText poskytuje, když je formát nastaven na simple.
AccuracyScore Přesnost výslovnosti řeči Přesnost udává, jak přesně fonély odpovídají výslovnosti rodilého mluvčího. Skóre přesnosti na úrovni slova a fulltextu se agreguje z skóre přesnosti na úrovni foonemu.
FluencyScore Plynulost poskytnuté řeči. Plynulost označuje, jak přesně řeč odpovídá použití tichých konců mezi slovy rodilého mluvčího.
CompletenessScore Úplnost řeči určená výpočtem poměru výrazných slov k odkazování na textové zadání
PronScore Celkové skóre, které označuje kvalitu výslovnosti poskytnuté řeči. Toto skóre se agreguje z AccuracyScore, FluencyScorea CompletenessScore s hmotností.
ErrorType Hodnota, která označuje, zda je slovo vynecháno, vloženo nebo špatně vyslovováno ve srovnání s ReferenceText. Možné hodnoty jsou None (tj. bez chyby v tomto slově), Omission, Insertiona Mispronunciation.

Přenos s blokem dat

Blokovaný přenos (Transfer-Encoding: chunked) může pomoct snížit latenci rozpoznávání. Služba Speech umožňuje zahájit zpracování zvukového souboru během přenosu. Rozhraní REST API pro krátký zvuk neposkytuje částečné ani dočasné výsledky.

Následující ukázka kódu ukazuje, jak odeslat zvuk v blocích dat. Záhlaví zvukového souboru by mělo obsahovat pouze první blok dat. requestHttpWebRequest je objekt, který je připojený k příslušnému koncovému bodu REST. audioFile je cesta ke zvukovému souboru na disku.

var request = (HttpWebRequest)HttpWebRequest.Create(requestUri);
request.SendChunked = true;
request.Accept = @"application/json;text/xml";
request.Method = "POST";
request.ProtocolVersion = HttpVersion.Version11;
request.Host = host;
request.ContentType = @"audio/wav; codecs=audio/pcm; samplerate=16000";
request.Headers["Ocp-Apim-Subscription-Key"] = "YOUR_RESOURCE_KEY";
request.AllowWriteStreamBuffering = false;

using (var fs = new FileStream(audioFile, FileMode.Open, FileAccess.Read))
{
    // Open a request stream and write 1,024-byte chunks in the stream one at a time.
    byte[] buffer = null;
    int bytesRead = 0;
    using (var requestStream = request.GetRequestStream())
    {
        // Read 1,024 raw bytes from the input audio file.
        buffer = new Byte[checked((uint)Math.Min(1024, (int)fs.Length))];
        while ((bytesRead = fs.Read(buffer, 0, buffer.Length)) != 0)
        {
            requestStream.Write(buffer, 0, bytesRead);
        }

        requestStream.Flush();
    }
}

Ověřování

Každý požadavek vyžaduje autorizační hlavičku. Tato tabulka znázorňuje, která záhlaví jsou pro každou funkci podporovaná:

Podporovaná autorizační hlavička Převod řeči na text Text na řeč
Ocp-Apim-Subscription-Key Ano Ano
Authorization: Bearer Ano Yes

Pokud používáte hlavičku Ocp-Apim-Subscription-Key , musíte zadat jenom svůj klíč prostředku. Příklad:

'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'

Když používáte hlavičku Authorization: Bearer , musíte do koncového issueToken bodu zadat požadavek. V této žádosti si vyměníte svůj klíč prostředku za přístupový token, který je platný 10 minut.

Jak získat přístupový token

Pokud chcete získat přístupový token, musíte do koncového issueToken bodu vytvořit požadavek pomocí Ocp-Apim-Subscription-Key svého klíče prostředku.

Koncový issueToken bod má tento formát:

https://<REGION_IDENTIFIER>.api.cognitive.microsoft.com/sts/v1.0/issueToken

Nahraďte <REGION_IDENTIFIER> identifikátorem, který odpovídá oblasti vašeho předplatného.

K vytvoření žádosti o přístupový token použijte následující ukázky.

Ukázka PROTOKOLU HTTP

Tento příklad je jednoduchý požadavek HTTP pro získání tokenu. Nahraďte YOUR_SUBSCRIPTION_KEY klíčem prostředku pro službu Speech. Pokud vaše předplatné není v oblasti USA – západ, nahraďte Host záhlaví názvem hostitele vaší oblasti.

POST /sts/v1.0/issueToken HTTP/1.1
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
Host: eastus.api.cognitive.microsoft.com
Content-type: application/x-www-form-urlencoded
Content-Length: 0

Text odpovědi obsahuje přístupový token ve formátu JSON Web Token (JWT).

Ukázka PowerShellu

Tento příklad je jednoduchý skript PowerShellu pro získání přístupového tokenu. Nahraďte YOUR_SUBSCRIPTION_KEY klíčem prostředku pro službu Speech. Ujistěte se, že používáte správný koncový bod pro oblast, která odpovídá vašemu předplatnému. Tento příklad je aktuálně nastavený na USA – západ.

$FetchTokenHeader = @{
  'Content-type'='application/x-www-form-urlencoded';
  'Content-Length'= '0';
  'Ocp-Apim-Subscription-Key' = 'YOUR_SUBSCRIPTION_KEY'
}

$OAuthToken = Invoke-RestMethod -Method POST -Uri https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken
 -Headers $FetchTokenHeader

# show the token received
$OAuthToken

Ukázka cURL

cURL je nástroj příkazového řádku dostupný v Linuxu (a v Subsystém Windows pro Linux). Tento příkaz cURL ukazuje, jak získat přístupový token. Nahraďte YOUR_SUBSCRIPTION_KEY klíčem prostředku pro službu Speech. Ujistěte se, že používáte správný koncový bod pro oblast, která odpovídá vašemu předplatnému. Tento příklad je aktuálně nastavený na USA – západ.

curl -v -X POST \
 "https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken" \
 -H "Content-type: application/x-www-form-urlencoded" \
 -H "Content-Length: 0" \
 -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY"

Ukázka v jazyce C#

Tato třída jazyka C# ukazuje, jak získat přístupový token. Klíč prostředku pro službu Speech předejte při vytváření instance třídy. Pokud vaše předplatné není v oblasti USA – západ, změňte hodnotu FetchTokenUri tak, aby odpovídala oblasti vašeho předplatného.

public class Authentication
{
    public static readonly string FetchTokenUri =
        "https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken";
    private string subscriptionKey;
    private string token;

    public Authentication(string subscriptionKey)
    {
        this.subscriptionKey = subscriptionKey;
        this.token = FetchTokenAsync(FetchTokenUri, subscriptionKey).Result;
    }

    public string GetAccessToken()
    {
        return this.token;
    }

    private async Task<string> FetchTokenAsync(string fetchUri, string subscriptionKey)
    {
        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
            UriBuilder uriBuilder = new UriBuilder(fetchUri);

            var result = await client.PostAsync(uriBuilder.Uri.AbsoluteUri, null);
            Console.WriteLine("Token Uri: {0}", uriBuilder.Uri.AbsoluteUri);
            return await result.Content.ReadAsStringAsync();
        }
    }
}

Ukázka Pythonu

# Request module must be installed.
# Run pip install requests if necessary.
import requests

subscription_key = 'REPLACE_WITH_YOUR_KEY'


def get_token(subscription_key):
    fetch_token_url = 'https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken'
    headers = {
        'Ocp-Apim-Subscription-Key': subscription_key
    }
    response = requests.post(fetch_token_url, headers=headers)
    access_token = str(response.text)
    print(access_token)

Jak používat přístupový token

Přístupový token by měl být odeslán do služby jako hlavička Authorization: Bearer <TOKEN> . Každý přístupový token je platný po dobu 10 minut. Nový token můžete kdykoli získat, ale pokud chcete minimalizovat síťový provoz a latenci, doporučujeme použít stejný token po dobu devíti minut.

Tady je ukázkový požadavek HTTP na rozhraní REST API pro převod řeči na text pro krátký zvuk:

POST /cognitiveservices/v1 HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Host: westus.stt.speech.microsoft.com
Content-type: application/ssml+xml
Content-Length: 199
Connection: Keep-Alive

// Message body here...

Další kroky