A Batch-átírás használataHow to use batch transcription

A Batch átírása REST API művelet, amely lehetővé teszi nagy mennyiségű hang tárolását.Batch transcription is a set of REST API operations that enables you to transcribe a large amount of audio in storage. A hangfájlokra egy tipikus URI vagy egy közös hozzáférésű aláírás (SAS) URI használatával, valamint az átírási eredmények aszinkron fogadásával is rámutathat.You can point to audio files using a typical URI or a shared access signature (SAS) URI and asynchronously receive transcription results. A v 3.0 API-val egy vagy több hangfájlt is átadhat, vagy feldolgozhatja a teljes tárolót.With the v3.0 API, you can transcribe one or more audio files, or process a whole storage container.

A Batch átírása REST API-kkal a következő módszereket hívhatja:You can use batch transcription REST APIs to call the following methods:

Kötegelt átírási műveletBatch Transcription Operation MetódusMethod REST API hívásREST API Call
Új átírást hoz létre.Creates a new transcription. POSTPOST speechtotext/v 3.0/átiratokspeechtotext/v3.0/transcriptions
Lekéri a hitelesített előfizetéshez tartozó átírások listáját.Retrieves a list of transcriptions for the authenticated subscription. GETGET speechtotext/v 3.0/átiratokspeechtotext/v3.0/transcriptions
Lekéri a támogatott területi beállítások listáját az offline átírásokhoz.Gets a list of supported locales for offline transcriptions. GETGET speechtotext/v 3.0/átiratok/területi beállításokspeechtotext/v3.0/transcriptions/locales
Frissíti az azonosító alapján azonosított átirat megváltoztathatatlan részleteit.Updates the mutable details of the transcription identified by its ID. JAVÍTÁSPATCH speechtotext/v 3.0/átiratok/{azonosító}speechtotext/v3.0/transcriptions/{id}
Törli a megadott átírási feladatot.Deletes the specified transcription task. DELETEDELETE speechtotext/v 3.0/átiratok/{azonosító}speechtotext/v3.0/transcriptions/{id}
Lekéri az adott azonosító által azonosított átírást.Gets the transcription identified by the given ID. GETGET speechtotext/v 3.0/átiratok/{azonosító}speechtotext/v3.0/transcriptions/{id}
Lekéri a megadott azonosító által azonosított átirat eredményének fájljait.Gets the result files of the transcription identified by the given ID. GETGET speechtotext/v 3.0/átiratok/{azonosító}/fájlokspeechtotext/v3.0/transcriptions/{id}/files

Áttekintheti és tesztelheti a részletes API-t, amely hencegő dokumentumkéntérhető el.You can review and test the detailed API, which is available as a Swagger document.

A Batch-átírási feladatok ütemezése a lehető legjobb megoldás szerint történik.Batch transcription jobs are scheduled on a best effort basis. Nem lehet megbecsülni, ha a feladat futási állapotba változik, de a normál rendszerterhelésnek megfelelően perceken belül meg kell történnie.You cannot estimate when a job will change into the running state, but it should happen within minutes under normal system load. Ha a futó állapotban van, az átirat gyorsabb, mint a lejátszási idő lejátszási sebessége.Once in the running state, the transcription occurs faster than the audio runtime playback speed.

ElőfeltételekPrerequisites

Ahogy a Speech Service összes funkciója esetében, létrehozhat egy előfizetési kulcsot a Azure Portal az első lépéseket ismertető útmutatóban.As with all features of the Speech service, you create a subscription key from the Azure portal by following our Get started guide.

Megjegyzés

A Batch-átírás használatához standard előfizetés (S0) szükséges a Speech Service-hez.A standard subscription (S0) for Speech service is required to use batch transcription. Az ingyenes előfizetés kulcsa (F0) nem fog működni.Free subscription keys (F0) will not work. További információ: díjszabás és korlátok.For more information, see pricing and limits.

Ha azt tervezi, hogy testreszabja a modelleket, kövesse az akusztikai Testreszabás és a nyelvi Testreszabáslépéseit.If you plan to customize models, follow the steps in Acoustic customization and Language customization. Ha a létrehozott modelleket a Batch-átírásban szeretné használni, szüksége lesz a modell helyére.To use the created models in batch transcription, you need their model location. A modell helyét a modell (tulajdonság) részleteinek vizsgálatával kérheti le self .You can retrieve the model location when you inspect the details of the model (self property). A Batch átíró szolgáltatáshoz nem szükséges egy telepített egyéni végpont.A deployed custom endpoint is not needed for the batch transcription service.

Megjegyzés

A REST API részeként a Batch-átírás kvótákat és korlátokattartalmaz, amelyeket javasoljuk, hogy tekintse át.As a part of the REST API, Batch Transcription has a set of quotas and limits, which we encourage to review. Ha szeretné kihasználni a Batch átírási képességét, hogy hatékonyan átmásolja a nagy mennyiségű hangfájlt, javasoljuk, hogy mindig több fájlt küldjön, vagy mutasson egy Blob Storage tárolóra a hangfájlok segítségével.To take the full advantage of Batch Transcription ability to efficiently transcribe a large number of audio files we recommend always sending multiple files per request or pointing to a Blob Storage container with the audio files to transcribe. A szolgáltatás az átfutási idő csökkentése érdekében egyszerre fogja átírni a fájlokat.The service will transcribe the files concurrently reducing the turnaround time. Egyetlen kérelemben több fájl használata nagyon egyszerű és egyértelmű – lásd a konfigurációs szakaszt.Using multiple files in a single request is very simple and straightforward - see Configuration section.

Batch-átírási APIBatch transcription API

A Batch transzkripciós API a következő formátumokat támogatja:The batch transcription API supports the following formats:

FormátumFormat CodecCodec Bit/mintaBits Per Sample Mintavételezési aránySample Rate
WAVWAV PCMPCM 16 bites16-bit 8 kHz vagy 16 kHz, monó vagy sztereó8 kHz or 16 kHz, mono or stereo
MP3MP3 PCMPCM 16 bites16-bit 8 kHz vagy 16 kHz, monó vagy sztereó8 kHz or 16 kHz, mono or stereo
VORBISOGG OPUSOPUS 16 bites16-bit 8 kHz vagy 16 kHz, monó vagy sztereó8 kHz or 16 kHz, mono or stereo

A sztereó hangadatfolyamok esetében a bal és a jobb oldali csatorna az átírás során oszlik meg.For stereo audio streams, the left and right channels are split during the transcription. Minden csatornához létre kell hozni egy JSON-eredményhalmaz fájlját.A JSON result file is being created for each channel. Rendezett végleges átirat létrehozásához használja a kiíráskor generált időbélyeget.To create an ordered final transcript, use the timestamps generated per utterance.

KonfigurációConfiguration

A konfigurációs paraméterek JSON-ként vannak megadva.Configuration parameters are provided as JSON.

Egy vagy több különálló fájl átirata.Transcribing one or more individual files. Ha egynél több fájlt szeretne átírni, javasoljuk, hogy több fájlt küldjön egy kérelembe.If you have more than one file to transcribe, we recommend sending multiple files in one request. Az alábbi példa három fájlt használ:The example below is using three files:

{
  "contentUrls": [
    "<URL to an audio file 1 to transcribe>",
    "<URL to an audio file 2 to transcribe>",
    "<URL to an audio file 3 to transcribe>"
  ],
  "properties": {
    "wordLevelTimestampsEnabled": true
  },
  "locale": "en-US",
  "displayName": "Transcription of file using default model for en-US"
}

Teljes tároló feldolgozása.Processing a whole storage container. A tároló sas -nak tartalmaznia kell r (olvasási) és l (lista) engedélyeket:Container SAS should contain r (read) and l (list) permissions:

{
  "contentContainerUrl": "<SAS URL to the Azure blob container to transcribe>",
  "properties": {
    "wordLevelTimestampsEnabled": true
  },
  "locale": "en-US",
  "displayName": "Transcription of container using default model for en-US"
}

Egyéni betanított modellt használhat a Batch-átíráshoz.Use a custom trained model in a batch transcription. A példa három fájlt használ:The example is using three files:

{
  "contentUrls": [
    "<URL to an audio file 1 to transcribe>",
    "<URL to an audio file 2 to transcribe>",
    "<URL to an audio file 3 to transcribe>"
  ],
  "properties": {
    "wordLevelTimestampsEnabled": true
  },
  "locale": "en-US",
  "model": {
    "self": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.0/models/{id}"
  },
  "displayName": "Transcription of file using default model for en-US"
}

Konfigurációs tulajdonságokConfiguration properties

Ezeket a választható tulajdonságokat az átírás konfigurálásához használhatja:Use these optional properties to configure transcription:

ParaméterParameter

LeírásDescription

profanityFilterMode

Nem kötelező, alapértelmezett érték: Masked .Optional, defaults to Masked. Meghatározza, hogyan kezelhető a káromkodás az eredmények felismerésében.Specifies how to handle profanity in recognition results. Az elfogadott értékek a None káromkodás szűrésének letiltására, a Masked káromkodás és a csillagokkal való kiváltására, Removed az eredményből való káromkodás eltávolítására, vagy a Tags "káromkodás" címkék hozzáadására szolgálnak.Accepted values are None to disable profanity filtering, Masked to replace profanity with asterisks, Removed to remove all profanity from the result, or Tags to add "profanity" tags.

punctuationMode

Nem kötelező, alapértelmezett érték: DictatedAndAutomatic .Optional, defaults to DictatedAndAutomatic. Meghatározza, hogyan kezelhető a központozás a felismerési eredményekben.Specifies how to handle punctuation in recognition results. Az elfogadott értékek az None írásjelek letiltására szolgálnak, a Dictated explicit (szóbeli) írásjelek megjelenítéséhez, Automatic hogy a dekóder a központozással legyen kezelve, vagy DictatedAndAutomatic pedig diktált és automatikus írásjeleket használjon.Accepted values are None to disable punctuation, Dictated to imply explicit (spoken) punctuation, Automatic to let the decoder deal with punctuation, or DictatedAndAutomatic to use dictated and automatic punctuation.

wordLevelTimestampsEnabled

Alapértelmezés szerint nem kötelező false .Optional, false by default. Megadja, hogy a rendszer hozzáadja-e a Word szintű időbélyegeket a kimenethez.Specifies if word level timestamps should be added to the output.

diarizationEnabled

Alapértelmezés szerint nem kötelező false .Optional, false by default. Meghatározza, hogy a diarization-elemzést a bemeneten kell végrehajtani, amely a várt két hangokat tartalmazó monó-csatorna.Specifies that diarization analysis should be carried out on the input, which is expected to be mono channel containing two voices. Megjegyzés: a használatához a szükséges értékre wordLevelTimestampsEnabled kell állítani true .Note: Requires wordLevelTimestampsEnabled to be set to true.

channels

Nem kötelező, 0 és 1 alapértelmezés szerint az átirata.Optional, 0 and 1 transcribed by default. A feldolgozandó csatorna-számok tömbje.An array of channel numbers to process. Itt megadhatja a hangfájlban található elérhető csatornák egy részhalmazát (például 0 csak).Here a subset of the available channels in the audio file can be specified to be processed (for example 0 only).

timeToLive

Nem kötelező, alapértelmezés szerint nincs törlés.Optional, no deletion by default. Az átiratok befejezését követő automatikus törlési időtartam.A duration to automatically delete transcriptions after completing the transcription. A a timeToLive tömeges feldolgozás során hasznos, hogy a rendszer végül törölni lehessen őket (például PT12H 12 órára).The timeToLive is useful in mass processing transcriptions to ensure they will be eventually deleted (for example, PT12H for 12 hours).

destinationContainerUrl

Opcionális URL-cím ad hoc sas -vel egy írható tárolóhoz az Azure-ban.Optional URL with ad hoc SAS to a writeable container in Azure. Az eredmény ebben a tárolóban tárolódik.The result is stored in this container. A tárolt hozzáférési házirenddel rendelkező SAS nem támogatott.SAS with stored access policy are not supported. Ha nincs megadva, a Microsoft az eredményeket a Microsoft által kezelt tároló tárolóban tárolja.When not specified, Microsoft stores the results in a storage container managed by Microsoft. Ha az átírást törli az átírásmeghívásával, a rendszer törli az eredményül kapott adatértéket is.When the transcription is deleted by calling Delete transcription, the result data will also be deleted.

TárolásStorage

A Batch-átírás képes a nyilvánosan látható internetes URI-n keresztül olvasni a hanganyagot, és az Azure Blob Storage-t használó sas URI-val képes hang-és írási átírásokat olvasni.Batch transcription can read audio from a public-visible internet URI, and can read audio or write transcriptions using a SAS URI with Azure Blob storage.

Köteg átírásának eredményeBatch transcription result

Minden hangbemenethez létrejön egy átírási eredmény fájl.For each audio input, one transcription result file is created. Az átírási fájlok beolvasása művelet az átíráshoz tartozó találatok listáját adja vissza.The Get transcriptions files operation returns a list of result files for this transcription. Egy adott bemeneti fájl átírási fájljának megkereséséhez szűrje az összes visszaadott fájlt a és a értékkel kind == Transcription name == {originalInputName.suffix}.json .To find the transcription file for a specific input file, filter all returned files with kind == Transcription and name == {originalInputName.suffix}.json.

Az átírási eredmények fájljának formátuma a következő:Each transcription result file has this format:

{
  "source": "...",                      // sas url of a given contentUrl or the path relative to the root of a given container
  "timestamp": "2020-06-16T09:30:21Z",  // creation time of the transcription, ISO 8601 encoded timestamp, combined date and time
  "durationInTicks": 41200000,          // total audio duration in ticks (1 tick is 100 nanoseconds)
  "duration": "PT4.12S",                // total audio duration, ISO 8601 encoded duration
  "combinedRecognizedPhrases": [        // concatenated results for simple access in single string for each channel
    {
      "channel": 0,                     // channel number of the concatenated results
      "lexical": "hello world",
      "itn": "hello world",
      "maskedITN": "hello world",
      "display": "Hello world."
    }
  ],
  "recognizedPhrases": [                // results for each phrase and each channel individually
    {
      "recognitionStatus": "Success",   // recognition state, e.g. "Success", "Failure"          
      "speaker": 1,                     // if `diarizationEnabled` is `true`, this is the identified speaker (1 or 2), otherwise this property is not present
      "channel": 0,                     // channel number of the result
      "offset": "PT0.07S",              // offset in audio of this phrase, ISO 8601 encoded duration 
      "duration": "PT1.59S",            // audio duration of this phrase, ISO 8601 encoded duration
      "offsetInTicks": 700000.0,        // offset in audio of this phrase in ticks (1 tick is 100 nanoseconds)
      "durationInTicks": 15900000.0,    // audio duration of this phrase in ticks (1 tick is 100 nanoseconds)

      // possible transcriptions of the current phrase with confidences
      "nBest": [
        {
          "confidence": 0.898652852,    // confidence value for the recognition of the whole phrase
          "lexical": "hello world",
          "itn": "hello world",
          "maskedITN": "hello world",
          "display": "Hello world.",

          // if wordLevelTimestampsEnabled is `true`, there will be a result for each word of the phrase, otherwise this property is not present
          "words": [
            {
              "word": "hello",
              "offset": "PT0.09S",
              "duration": "PT0.48S",
              "offsetInTicks": 900000.0,
              "durationInTicks": 4800000.0,
              "confidence": 0.987572
            },
            {
              "word": "world",
              "offset": "PT0.59S",
              "duration": "PT0.16S",
              "offsetInTicks": 5900000.0,
              "durationInTicks": 1600000.0,
              "confidence": 0.906032
            }
          ]
        }
      ]
    }
  ]
}

Az eredmény a következő mezőket tartalmazza:The result contains the following fields:

MezőField

TartalomContent

lexical

A tényleges szavak felismerhetők.The actual words recognized.

itn

Inverz szöveg – a felismert szöveg normalizált formája.Inverse-text-normalized form of the recognized text. A rövidítések ("doktor Smith" a "Dr Smith"), a telefonszámok és más átalakítások alkalmazása.Abbreviations ("doctor smith" to "dr smith"), phone numbers, and other transformations are applied.

maskedITN

A ITN űrlap a káromkodás maszkolásával lett alkalmazva.The ITN form with profanity masking applied.

display

A felismert szöveg megjelenítési formájaThe display form of the recognized text. A rendszer a hozzáadott írásjeleket és a nagybetűket is tartalmazza.Added punctuation and capitalization are included.

Beszélő elkülönítése (diarization)Speaker separation (diarization)

A Diarization a hangszórók elválasztásának folyamata egy hanganyagban.Diarization is the process of separating speakers in a piece of audio. A Batch-folyamat támogatja a diarization, és képes a Mono Channel-felvételek két hangszórójának felismerésére.The batch pipeline supports diarization and is capable of recognizing two speakers on mono channel recordings. A szolgáltatás nem érhető el a sztereó felvételeken.The feature is not available on stereo recordings.

Az diarization-mel rendelkező átiratok kimenete Speaker minden egyes átmásolt kifejezéshez tartalmaz egy bejegyzést.The output of transcription with diarization enabled contains a Speaker entry for each transcribed phrase. Ha a diarization nincs használatban, a Speaker tulajdonság nem szerepel a JSON-kimenetben.If diarization is not used, the Speaker property is not present in the JSON output. A diarization két hangokat támogatunk, így a hangszórók a vagy a néven azonosíthatók 1 2 .For diarization we support two voices, so the speakers are identified as 1 or 2.

A diarization igényléséhez adja hozzá a diarizationEnabled tulajdonságot úgy, hogy true az alábbihoz hasonló HTTP-kérést adjon meg.To request diarization, add set the diarizationEnabled property to true like the HTTP request shows below.

{
 "contentUrls": [
   "<URL to an audio file to transcribe>",
 ],
 "properties": {
   "diarizationEnabled": true,
   "wordLevelTimestampsEnabled": true,
   "punctuationMode": "DictatedAndAutomatic",
   "profanityFilterMode": "Masked"
 },
 "locale": "en-US",
 "displayName": "Transcription of file using default model for en-US"
}

A Word-szintű időbélyegeket engedélyezni kell, ha a fenti kérelemben szereplő paraméterek jelzik.Word-level timestamps must be enabled as the parameters in the above request indicate.

Ajánlott eljárásokBest practices

A Batch transzkripciós szolgáltatás nagy számú beküldött átírást képes kezelni.The batch transcription service can handle large number of submitted transcriptions. Lekérdezheti az átiratok állapotát a Get transzkripcióshasználatával.You can query the status of your transcriptions with Get transcriptions. Az eredmények lekérése után rendszeresen hívja meg a delete átiratot a szolgáltatásból.Call Delete transcription regularly from the service once you retrieved the results. Másik lehetőségként állítsa be timeToLive a tulajdonságot az eredmények végleges törlésének biztosítására.Alternatively set timeToLive property to ensure eventual deletion of the results.

MintakódSample code

A teljes minták a GitHub minta adattárában érhetők el az samples/batch alkönyvtáron belül.Complete samples are available in the GitHub sample repository inside the samples/batch subdirectory.

Frissítse a mintát az előfizetési adatokkal, a szolgáltatási régióval, a hangfájlra mutató URI-val, és a modell helyére, ha egyéni modellt használ.Update the sample code with your subscription information, service region, URI pointing to the audio file to transcribe, and model location if you're using a custom model.

var newTranscription = new Transcription
{
    DisplayName = DisplayName, 
    Locale = Locale, 
    ContentUrls = new[] { RecordingsBlobUri },
    //ContentContainerUrl = ContentAzureBlobContainer,
    Model = CustomModel,
    Properties = new TranscriptionProperties
    {
        IsWordLevelTimestampsEnabled = true,
        TimeToLive = TimeSpan.FromDays(1)
    }
};

newTranscription = await client.PostTranscriptionAsync(newTranscription).ConfigureAwait(false);
Console.WriteLine($"Created transcription {newTranscription.Self}");

A mintakód beállítja az ügyfelet, és elküldi az átírási kérelmet.The sample code sets up the client and submits the transcription request. Ezután lekérdezi az állapotadatok adatait, és kinyomtatja az átírási folyamat részleteit.It then polls for the status information and print details about the transcription progress.

// get the status of our transcriptions periodically and log results
int completed = 0, running = 0, notStarted = 0;
while (completed < 1)
{
    completed = 0; running = 0; notStarted = 0;

    // get all transcriptions for the user
    paginatedTranscriptions = null;
    do
    {
        // <transcriptionstatus>
        if (paginatedTranscriptions == null)
        {
            paginatedTranscriptions = await client.GetTranscriptionsAsync().ConfigureAwait(false);
        }
        else
        {
            paginatedTranscriptions = await client.GetTranscriptionsAsync(paginatedTranscriptions.NextLink).ConfigureAwait(false);
        }

        // delete all pre-existing completed transcriptions. If transcriptions are still running or not started, they will not be deleted
        foreach (var transcription in paginatedTranscriptions.Values)
        {
            switch (transcription.Status)
            {
                case "Failed":
                case "Succeeded":
                    // we check to see if it was one of the transcriptions we created from this client.
                    if (!createdTranscriptions.Contains(transcription.Self))
                    {
                        // not created form here, continue
                        continue;
                    }

                    completed++;

                    // if the transcription was successful, check the results
                    if (transcription.Status == "Succeeded")
                    {
                        var paginatedfiles = await client.GetTranscriptionFilesAsync(transcription.Links.Files).ConfigureAwait(false);

                        var resultFile = paginatedfiles.Values.FirstOrDefault(f => f.Kind == ArtifactKind.Transcription);
                        var result = await client.GetTranscriptionResultAsync(new Uri(resultFile.Links.ContentUrl)).ConfigureAwait(false);
                        Console.WriteLine("Transcription succeeded. Results: ");
                        Console.WriteLine(JsonConvert.SerializeObject(result, SpeechJsonContractResolver.WriterSettings));
                    }
                    else
                    {
                        Console.WriteLine("Transcription failed. Status: {0}", transcription.Properties.Error.Message);
                    }

                    break;

                case "Running":
                    running++;
                    break;

                case "NotStarted":
                    notStarted++;
                    break;
            }
        }

        // for each transcription in the list we check the status
        Console.WriteLine(string.Format("Transcriptions status: {0} completed, {1} running, {2} not started yet", completed, running, notStarted));
    }
    while (paginatedTranscriptions.NextLink != null);

    // </transcriptionstatus>
    // check again after 1 minute
    await Task.Delay(TimeSpan.FromMinutes(1)).ConfigureAwait(false);
}

Az előző hívásokkal kapcsolatos részletes információkért tekintse meg a hencegő dokumentumot.For full details about the preceding calls, see our Swagger document. Az itt látható teljes minta esetében lépjen a githubra az samples/batch alkönyvtárban.For the full sample shown here, go to GitHub in the samples/batch subdirectory.

Ez a példa egy aszinkron telepítőt használ a hang és a fogadás átírási állapotának elküldéséhez.This sample uses an asynchronous setup to post audio and receive transcription status. A PostTranscriptions metódus elküldi a hangfájl részleteit, és a GetTranscriptions metódus fogadja az állapotokat.The PostTranscriptions method sends the audio file details and the GetTranscriptions method receives the states. PostTranscriptions egy leírót ad vissza, és a GetTranscriptions használatával létrehoz egy leírót az átirat állapotának lekéréséhez.PostTranscriptions returns a handle, and GetTranscriptions uses it to create a handle to get the transcription status.

Ez a mintakód nem ad meg egyéni modellt.This sample code doesn't specify a custom model. A szolgáltatás az alapmodellt használja a fájl vagy fájlok átírásához.The service uses the baseline model for transcribing the file or files. A modell megadásához ugyanezt a módszert kell átadni az egyéni modellhez tartozó modell-referenciára.To specify the model, you can pass on the same method the model reference for the custom model.

Megjegyzés

Az alapértékek átírásakor nem kell deklarálnia az alapmodell AZONOSÍTÓját.For baseline transcriptions, you don't need to declare the ID for the baseline model.

Következő lépésekNext steps