Come usare la trascrizione batchHow to use batch transcription

La trascrizione batch è un set di operazioni API REST che consente di trascrivere una grande quantità di audio nell'archivio.Batch transcription is a set of REST API operations that enables you to transcribe a large amount of audio in storage. È possibile puntare a file audio usando un URI tipico o un URI di firma di accesso condiviso e ricevere in modo asincrono i risultati della trascrizione.You can point to audio files using a typical URI or a shared access signature (SAS) URI and asynchronously receive transcription results. Con l'API v 3.0 è possibile trascrivere uno o più file audio oppure elaborare un intero contenitore di archiviazione.With the v3.0 API, you can transcribe one or more audio files, or process a whole storage container.

È possibile usare le API REST per la trascrizione batch per chiamare i metodi seguenti:You can use batch transcription REST APIs to call the following methods:

Operazione di trascrizione batchBatch Transcription Operation MetodoMethod Chiamata API RESTREST API Call
Crea una nuova trascrizione.Creates a new transcription. POSTPOST speechtotext/v 3.0/trascrizionispeechtotext/v3.0/transcriptions
Recupera un elenco di trascrizioni per la sottoscrizione autenticata.Retrieves a list of transcriptions for the authenticated subscription. GETGET speechtotext/v 3.0/trascrizionispeechtotext/v3.0/transcriptions
Ottiene un elenco di impostazioni locali supportate per le trascrizioni offline.Gets a list of supported locales for offline transcriptions. GETGET speechtotext/v 3.0/trascrizioni/impostazioni localispeechtotext/v3.0/transcriptions/locales
Aggiorna i dettagli modificabili della trascrizione identificata dal relativo ID.Updates the mutable details of the transcription identified by its ID. PATCHPATCH speechtotext/v 3.0/trascrizioni/{ID}speechtotext/v3.0/transcriptions/{id}
Elimina l'attività di trascrizione specificata.Deletes the specified transcription task. DELETEDELETE speechtotext/v 3.0/trascrizioni/{ID}speechtotext/v3.0/transcriptions/{id}
Ottiene la trascrizione identificata dall'ID specificato.Gets the transcription identified by the given ID. GETGET speechtotext/v 3.0/trascrizioni/{ID}speechtotext/v3.0/transcriptions/{id}
Ottiene i file di risultati della trascrizione identificata dall'ID specificato.Gets the result files of the transcription identified by the given ID. GETGET speechtotext/v 3.0/trascrizioni/{ID}/filespeechtotext/v3.0/transcriptions/{id}/files

È possibile esaminare e testare l'API dettagliata, disponibile come documento di spavalderia.You can review and test the detailed API, which is available as a Swagger document.

I processi di trascrizione batch sono pianificati in base al massimo sforzo.Batch transcription jobs are scheduled on a best effort basis. Non è possibile stimare il momento in cui un processo cambierà nello stato in esecuzione, ma dovrebbe verificarsi entro pochi minuti sotto il normale carico di sistema.You cannot estimate when a job will change into the running state, but it should happen within minutes under normal system load. Una volta nello stato di esecuzione, la trascrizione viene eseguita più velocemente della velocità di riproduzione del runtime audio.Once in the running state, the transcription occurs faster than the audio runtime playback speed.

PrerequisitiPrerequisites

Come per tutte le funzionalità del servizio Voce, si crea una chiave di sottoscrizione dal portale di Azure seguendo la guida introduttiva.As with all features of the Speech service, you create a subscription key from the Azure portal by following our Get started guide.

Nota

Per usare la trascrizione batch, è necessaria una sottoscrizione standard (S0) per il servizio di riconoscimento vocale.A standard subscription (S0) for Speech service is required to use batch transcription. Le chiavi di sottoscrizione gratuita (F0) non funzioneranno.Free subscription keys (F0) will not work. Per altre informazioni, vedere prezzi e limiti.For more information, see pricing and limits.

Se si prevede di personalizzare i modelli, attenersi alla procedura descritta in personalizzazione acustica e personalizzazione della lingua.If you plan to customize models, follow the steps in Acoustic customization and Language customization. Per usare i modelli creati nella trascrizione batch, è necessario il percorso del modello.To use the created models in batch transcription, you need their model location. È possibile recuperare il percorso del modello quando si esaminano i dettagli del modello ( self proprietà).You can retrieve the model location when you inspect the details of the model (self property). Un endpoint personalizzato distribuito non è necessario per il servizio di trascrizione batch.A deployed custom endpoint is not needed for the batch transcription service.

Nota

Come parte dell'API REST, la trascrizione batch presenta un set di quote e limitiche è consigliabile esaminare.As a part of the REST API, Batch Transcription has a set of quotas and limits, which we encourage to review. Per sfruttare al meglio la capacità di trascrizione batch di trascrivere in modo efficiente un numero elevato di file audio, è consigliabile inviare sempre più file per ogni richiesta o puntare a un contenitore di archiviazione BLOB con i file audio da trascrivere.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. Il servizio trascriverà i file simultaneamente riducendo il tempo di inversione.The service will transcribe the files concurrently reducing the turnaround time. L'uso di più file in una singola richiesta è molto semplice e semplice. vedere la sezione relativa alla configurazione .Using multiple files in a single request is very simple and straightforward - see Configuration section.

API di trascrizione BatchBatch transcription API

L'API trascrizione batch supporta i formati seguenti:The batch transcription API supports the following formats:

FormatoFormat CodecCodec BITS per campioneBits Per Sample Frequenza di campionamentoSample Rate
WAVWAV PCMPCM 16 bit16-bit 8 kHz o 16 kHz, mono o stereo8 kHz or 16 kHz, mono or stereo
MP3MP3 PCMPCM 16 bit16-bit 8 kHz o 16 kHz, mono o stereo8 kHz or 16 kHz, mono or stereo
OGGOGG OPUSOPUS 16 bit16-bit 8 kHz o 16 kHz, mono o stereo8 kHz or 16 kHz, mono or stereo

Per i flussi audio stereo, i canali sinistro e destro vengono suddivisi durante la trascrizione.For stereo audio streams, the left and right channels are split during the transcription. È in corso la creazione di un file di risultati JSON per ogni canale.A JSON result file is being created for each channel. Per creare una trascrizione finale ordinata, usare i timestamp generati per espressione.To create an ordered final transcript, use the timestamps generated per utterance.

ConfigurazioneConfiguration

I parametri di configurazione vengono forniti come JSON.Configuration parameters are provided as JSON.

Trascrizione di uno o più singoli file.Transcribing one or more individual files. Se è presente più di un file da trascrivere, è consigliabile inviare più file in un'unica richiesta.If you have more than one file to transcribe, we recommend sending multiple files in one request. L'esempio seguente usa tre file: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"
}

Elaborazione di un intero contenitore di archiviazione.Processing a whole storage container. La firma di accesso condiviso del contenitore deve contenere r le autorizzazioni (lettura) e l (elenco):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"
}

Usare un modello sottoposto a training personalizzato in una trascrizione batch.Use a custom trained model in a batch transcription. L'esempio usa tre file: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"
}

Proprietà di configurazioneConfiguration properties

Usare queste proprietà facoltative per configurare la trascrizione:Use these optional properties to configure transcription:

ParametroParameter

DescrizioneDescription

profanityFilterMode

Facoltativo. il valore predefinito è Masked .Optional, defaults to Masked. Specifica come gestire il linguaggio volgare nei risultati del riconoscimento.Specifies how to handle profanity in recognition results. I valori accettati sono None la disabilitazione del filtro per la volgarità, Masked la sostituzione della volgarità con gli asterischi, Removed la rimozione di tutti i messaggi profani dal risultato o l' Tags aggiunta di tag di "volgarità".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

Facoltativo. il valore predefinito è DictatedAndAutomatic .Optional, defaults to DictatedAndAutomatic. Specifica come gestire la punteggiatura nei risultati del riconoscimento.Specifies how to handle punctuation in recognition results. I valori accettati sono None la disabilitazione della punteggiatura, Dictated per implicare la punteggiatura esplicita (pronunciata), Automatic per consentire al decodificatore di gestire la punteggiatura o DictatedAndAutomatic di usare la punteggiatura dettata e automatica.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

Facoltativo, false per impostazione predefinita.Optional, false by default. Specifica se i timestamp a livello di parola devono essere aggiunti all'output.Specifies if word level timestamps should be added to the output.

diarizationEnabled

Facoltativo, false per impostazione predefinita.Optional, false by default. Specifica che l'analisi della fase di esecuzione deve essere eseguita nell'input, che dovrebbe essere canale mono contenente due voci.Specifies that diarization analysis should be carried out on the input, which is expected to be mono channel containing two voices. Nota: wordLevelTimestampsEnabled è necessario che sia impostato su true .Note: Requires wordLevelTimestampsEnabled to be set to true.

channels

Facoltativo 0 e 1 trascritto per impostazione predefinita.Optional, 0 and 1 transcribed by default. Matrice di numeri di canale da elaborare.An array of channel numbers to process. Qui è possibile specificare un subset dei canali disponibili nel file audio da elaborare, ad esempio 0 solo.Here a subset of the available channels in the audio file can be specified to be processed (for example 0 only).

timeToLive

Facoltativo, nessuna eliminazione per impostazione predefinita.Optional, no deletion by default. Durata per eliminare automaticamente le trascrizioni dopo aver completato la trascrizione.A duration to automatically delete transcriptions after completing the transcription. timeToLiveÈ utile nelle trascrizioni di elaborazione di massa per assicurarsi che vengano eliminate, ad esempio per PT12H 12 ore.The timeToLive is useful in mass processing transcriptions to ensure they will be eventually deleted (for example, PT12H for 12 hours).

destinationContainerUrl

URL facoltativo con SAS ad hoc in un contenitore scrivibile in Azure.Optional URL with ad hoc SAS to a writeable container in Azure. Il risultato viene archiviato in questo contenitore.The result is stored in this container. La firma di accesso condiviso con criteri di accesso archiviati non è supportata.SAS with stored access policy are not supported. Quando non è specificato, Microsoft archivia i risultati in un contenitore di archiviazione gestito da Microsoft.When not specified, Microsoft stores the results in a storage container managed by Microsoft. Quando la trascrizione viene eliminata chiamando la trascrizione Delete, verranno eliminati anche i dati del risultato.When the transcription is deleted by calling Delete transcription, the result data will also be deleted.

ArchiviazioneStorage

La trascrizione batch può leggere l'audio da un URI Internet visibile pubblicamente ed è in grado di leggere audio o scrivere trascrizioni usando un URI SAS con archiviazione BLOB di Azure.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.

Risultato trascrizione batchBatch transcription result

Per ogni input audio, viene creato un file di risultati della trascrizione.For each audio input, one transcription result file is created. L'operazione Get trascrizioni files restituisce un elenco di file di risultati per la trascrizione.The Get transcriptions files operation returns a list of result files for this transcription. Per trovare il file di trascrizione per un file di input specifico, filtrare tutti i file restituiti con kind == Transcription e 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.

Il formato di ogni file di risultati della trascrizione è il seguente: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
            }
          ]
        }
      ]
    }
  ]
}

Il risultato contiene i campi seguenti:The result contains the following fields:

CampoField

ContenutoContent

lexical

Parole effettive riconosciute.The actual words recognized.

itn

Formato inverso-testo normalizzato del testo riconosciuto.Inverse-text-normalized form of the recognized text. Vengono applicate le abbreviazioni ("Doctor Smith" a "Dr Smith"), i numeri di telefono e altre trasformazioni.Abbreviations ("doctor smith" to "dr smith"), phone numbers, and other transformations are applied.

maskedITN

Il form ITN con la maschera volgare applicata.The ITN form with profanity masking applied.

display

Il form di visualizzazione del testo riconosciuto.The display form of the recognized text. Sono inclusi la punteggiatura e le maiuscole aggiunte.Added punctuation and capitalization are included.

Separazione dei relatoriSpeaker separation (diarization)

La deframmentazione è il processo di separazione degli altoparlanti in un audio.Diarization is the process of separating speakers in a piece of audio. La pipeline batch supporta la registrazione ed è in grado di riconoscere due altoparlanti nelle registrazioni del canale mono.The batch pipeline supports diarization and is capable of recognizing two speakers on mono channel recordings. La funzionalità non è disponibile nelle registrazioni stereo.The feature is not available on stereo recordings.

L'output della trascrizione con la registrazione abilitata contiene una Speaker voce per ogni frase trascritta.The output of transcription with diarization enabled contains a Speaker entry for each transcribed phrase. Se la non viene usata, la Speaker proprietà non è presente nell'output JSON.If diarization is not used, the Speaker property is not present in the JSON output. Per la tua operazione sono supportate due voci, quindi i relatori sono identificati come 1 o 2 .For diarization we support two voices, so the speakers are identified as 1 or 2.

Per richiedere la messa in pagina, aggiungere la diarizationEnabled proprietà su true come la richiesta http Mostra di seguito.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"
}

I timestamp a livello di parola devono essere abilitati perché i parametri nella richiesta precedente indicano.Word-level timestamps must be enabled as the parameters in the above request indicate.

Procedure consigliateBest practices

Il servizio di trascrizione batch può gestire un numero elevato di trascrizioni inviate.The batch transcription service can handle large number of submitted transcriptions. È possibile eseguire una query sullo stato delle trascrizioni con le trascrizioni Get.You can query the status of your transcriptions with Get transcriptions. Chiamare la trascrizione Delete regolarmente dal servizio una volta recuperati i risultati.Call Delete transcription regularly from the service once you retrieved the results. In alternativa timeToLive , impostare la proprietà per garantire l'eventuale eliminazione dei risultati.Alternatively set timeToLive property to ensure eventual deletion of the results.

Codice di esempioSample code

Gli esempi completi sono disponibili nel repository di esempio GitHub all'interno della samples/batch sottodirectory.Complete samples are available in the GitHub sample repository inside the samples/batch subdirectory.

Aggiornare il codice di esempio con le informazioni sulla sottoscrizione, l'area del servizio, l'URI che punta al file audio da trascrivere e il percorso del modello se si usa un modello personalizzato.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}");

Il codice di esempio configura il client e Invia la richiesta di trascrizione.The sample code sets up the client and submits the transcription request. Esegue quindi il polling delle informazioni sullo stato e i dettagli di stampa sullo stato della trascrizione.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);
}

Per dettagli completi sulle chiamate precedenti, vedere il documento di spavalderia.For full details about the preceding calls, see our Swagger document. L'esempio completo illustrato qui è disponibile in GitHub, nella sottodirectory samples/batch.For the full sample shown here, go to GitHub in the samples/batch subdirectory.

In questo esempio viene utilizzata una configurazione asincrona per pubblicare audio e ricevere lo stato della trascrizione.This sample uses an asynchronous setup to post audio and receive transcription status. Il PostTranscriptions metodo invia i dettagli del file audio e il GetTranscriptions metodo riceve gli Stati.The PostTranscriptions method sends the audio file details and the GetTranscriptions method receives the states. PostTranscriptions restituisce un handle e GetTranscriptions usa l'handle per crearne uno nuovo per ottenere lo stato della trascrizione.PostTranscriptions returns a handle, and GetTranscriptions uses it to create a handle to get the transcription status.

Questo codice di esempio non specifica un modello personalizzato.This sample code doesn't specify a custom model. Il servizio usa il modello di base per la trascrizione del file o dei file.The service uses the baseline model for transcribing the file or files. Per specificare il modello, è possibile passare lo stesso metodo al riferimento del modello per il modello personalizzato.To specify the model, you can pass on the same method the model reference for the custom model.

Nota

Per le trascrizioni di base, non è necessario dichiarare l'ID per il modello di base.For baseline transcriptions, you don't need to declare the ID for the baseline model.

Passaggi successiviNext steps