Uso de la transcripción por lotesHow to use batch transcription

La transcripción por lotes es un conjunto de operaciones de API REST que permite transcribir una gran cantidad de audio en el almacenamiento.Batch transcription is a set of REST API operations that enables you to transcribe a large amount of audio in storage. Puede apuntar a archivos de audio mediante un identificador URI de firma de acceso compartido (SAS) y recibir los resultados de las transcripciones de forma asincrónica.You can point to audio files using a typical URI or a shared access signature (SAS) URI and asynchronously receive transcription results. Con la API v3.0, puede transcribir uno o varios archivos de audio o procesar un contenedor de almacenamiento completo.With the v3.0 API, you can transcribe one or more audio files, or process a whole storage container.

Puede usar las API REST de transcripción por lotes para llamar a los métodos siguientes:You can use batch transcription REST APIs to call the following methods:

Operación de transcripción por lotesBatch Transcription Operation MétodoMethod Llamada a API RESTREST API Call
Crea una transcripción nueva.Creates a new transcription. POSTPOST speechtotext/v3.0/transcriptionsspeechtotext/v3.0/transcriptions
Recupera una lista de transcripciones para la suscripción autenticada.Retrieves a list of transcriptions for the authenticated subscription. GETGET speechtotext/v3.0/transcriptionsspeechtotext/v3.0/transcriptions
Obtiene una lista de configuraciones regionales admitidas para las transcripciones sin conexión.Gets a list of supported locales for offline transcriptions. GETGET speechtotext/v3.0/transcriptions/localesspeechtotext/v3.0/transcriptions/locales
Actualiza los detalles mutables de la transcripción identificada por su id.Updates the mutable details of the transcription identified by its ID. PATCHPATCH speechtotext/v3.0/transcriptions/{id}speechtotext/v3.0/transcriptions/{id}
Elimina la tarea de transcripción especificada.Deletes the specified transcription task. DeleteDELETE speechtotext/v3.0/transcriptions/{id}speechtotext/v3.0/transcriptions/{id}
Obtiene la transcripción identificada por el id. especificado.Gets the transcription identified by the given ID. GETGET speechtotext/v3.0/transcriptions/{id}speechtotext/v3.0/transcriptions/{id}
Obtiene los archivos de resultado de la transcripción identificada por el id. especificado.Gets the result files of the transcription identified by the given ID. GETGET speechtotext/v3.0/transcriptions/{id}/filesspeechtotext/v3.0/transcriptions/{id}/files

Puede revisar y probar la API detallada, que está disponible como un documento de Swagger.You can review and test the detailed API, which is available as a Swagger document.

Los trabajos de transcripción por lotes se programan de la mejor manera posible.Batch transcription jobs are scheduled on a best effort basis. No es posible determinar el momento en que un trabajo cambiará al estado en ejecución, pero debería suceder en cuestión de minutos con una carga normal del sistema.You cannot estimate when a job will change into the running state, but it should happen within minutes under normal system load. Una vez que la transcripción tiene el estado "En ejecución", se produce más rápido que la velocidad de reproducción de audio en tiempo de ejecución.Once in the running state, the transcription occurs faster than the audio runtime playback speed.

Requisitos previosPrerequisites

Como sucede con todas las características del servicio Voz, puede crear una clave de suscripción en Azure Portal siguiendo nuestra guía de inicio.As with all features of the Speech service, you create a subscription key from the Azure portal by following our Get started guide.

Nota

Se requiere una suscripción estándar (S0) para el servicio de voz para usar la transcripción de lotes.A standard subscription (S0) for Speech service is required to use batch transcription. Las claves de suscripción gratuita (F0) no funcionarán.Free subscription keys (F0) will not work. Para obtener más información, consulte los precios y límites.For more information, see pricing and limits.

Si tiene previsto personalizar los modelos, siga los pasos descritos en Personalización acústica y Personalización de idioma.If you plan to customize models, follow the steps in Acoustic customization and Language customization. Para usar los modelos creados en la transcripción por lotes, necesita sus ubicaciones.To use the created models in batch transcription, you need their model location. Puede recuperar la ubicación del modelo al inspeccionar los detalles del modelo (propiedad self).You can retrieve the model location when you inspect the details of the model (self property). No es necesario un punto de conexión personalizado implementado para el servicio de transcripción por lotes.A deployed custom endpoint is not needed for the batch transcription service.

Nota

Al formar arte de la API REST, Batch Transcription tiene un conjunto de cuotas y límites, y es aconsejable examinarlos.As a part of the REST API, Batch Transcription has a set of quotas and limits, which we encourage to review. Para sacar el máximo partido de la capacidad de Batch Transcription para transcribir eficazmente un gran número de archivos de audio, se recomienda enviar siempre varios archivos por solicitud o apuntar los archivos de audio que se van a transcribir a un contenedor de Blob Storage.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. El servicio transcribirá los archivos de forma concurrente, lo que reducirá el tiempo de respuesta.The service will transcribe the files concurrently reducing the turnaround time. El uso de varios archivos en una sola solicitud es una operación sencilla y directa (consulte la sección Configuración).Using multiple files in a single request is very simple and straightforward - see Configuration section.

API de transcripciones de Azure BatchBatch transcription API

La API Batch Transcription admite los siguientes formatos:The batch transcription API supports the following formats:

FormatoFormat CódecCodec Bits por muestraBits Per Sample Velocidad de muestreoSample Rate
WAVWAV PCMPCM 16 bits16-bit 8 kHz o 16 kHz, mono o estéreo8 kHz or 16 kHz, mono or stereo
MP3MP3 PCMPCM 16 bits16-bit 8 kHz o 16 kHz, mono o estéreo8 kHz or 16 kHz, mono or stereo
OGGOGG OPUSOPUS 16 bits16-bit 8 kHz o 16 kHz, mono o estéreo8 kHz or 16 kHz, mono or stereo

En el caso de las secuencias de audio estéreo, los canales izquierdo y derecho se dividen durante la transcripción.For stereo audio streams, the left and right channels are split during the transcription. Para cada canal se crea un archivo de resultados JSON.A JSON result file is being created for each channel. Para crear una transcripción final ordenada, utilice las marcas de tiempo generadas por expresión.To create an ordered final transcript, use the timestamps generated per utterance.

ConfiguraciónConfiguration

Los parámetros de configuración se proporcionan como JSON.Configuration parameters are provided as JSON.

Transcripción de uno o varios archivos individuales.Transcribing one or more individual files. Si desea transcribir más de un archivo, es aconsejable enviar varios en una sola solicitud.If you have more than one file to transcribe, we recommend sending multiple files in one request. En el ejemplo siguiente se usan tres archivos: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"
}

Procesamiento de un contenedor de almacenamiento completo:Processing a whole storage container:

{
  "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"
}

Uso de un modelo entrenado personalizado en una transcripción por lotes.Use a custom trained model in a batch transcription. En el ejemplo se usan tres archivos: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"
}

Propiedades de configuraciónConfiguration properties

Utilice estas propiedades opcionales para configurar la transcripción:Use these optional properties to configure transcription:

ParámetroParameter

DescripciónDescription

profanityFilterMode

(Opcional) El valor predeterminado es Masked.Optional, defaults to Masked. Especifica cómo controlar las palabras soeces en los resultados del reconocimiento.Specifies how to handle profanity in recognition results. Los valores aceptados son None, para deshabilitar el filtrado de palabras soeces; Masked, para reemplazar las palabras soeces con asteriscos; Removed, para quitar todas las palabras soeces del resultado; o Tags, para agregar etiquetas de "palabras soeces".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

(Opcional) El valor predeterminado es DictatedAndAutomatic.Optional, defaults to DictatedAndAutomatic. Especifica cómo controlar la puntuación en los resultados del reconocimiento.Specifies how to handle punctuation in recognition results. Los valores aceptados son None, para deshabilitar la puntuación; Dictated, para implicar signos de puntuación explícitos (hablados); Automatic, para permitir que el descodificador trate con signos de puntuación o DictatedAndAutomatic, para usar la puntuación dictada y automática.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

(Opcional) false es el valor predeterminado.Optional, false by default. Especifica si las marcas de tiempo de nivel de palabra se deben agregar a la salida.Specifies if word level timestamps should be added to the output.

diarizationEnabled

(Opcional) false es el valor predeterminado.Optional, false by default. Especifica que el análisis de la diarización se debe llevar a cabo en la entrada que se espera sea un canal mono que contenga dos voces.Specifies that diarization analysis should be carried out on the input, which is expected to be mono channel containing two voices. Nota: Se requiere que wordLevelTimestampsEnabled se establezca en true.Note: Requires wordLevelTimestampsEnabled to be set to true.

channels

(Opcional) 0 y 1 se transcriben de forma predeterminada.Optional, 0 and 1 transcribed by default. Matriz de números de canal para procesar.An array of channel numbers to process. Aquí se puede especificar un subconjunto de los canales disponibles en el archivo de audio para procesarse (por ejemplo, solo 0).Here a subset of the available channels in the audio file can be specified to be processed (for example 0 only).

timeToLive

(Opcional) No se elimina de forma predeterminada.Optional, no deletion by default. Plazo para eliminar automáticamente las transcripciones después de completar el proceso de transcripción.A duration to automatically delete transcriptions after completing the transcription. timeToLive resulta útil en el procesamiento en masa de transcripciones, para asegurarse de que se eliminarán (por ejemplo, PT12H para 12 horas).The timeToLive is useful in mass processing transcriptions to ensure they will be eventually deleted (for example, PT12H for 12 hours).

destinationContainerUrl

URL opcional con SAS ad hoc de servicio en un contenedor grabable de Azure.Optional URL with Service ad hoc SAS to a writeable container in Azure. El resultado se almacena en este contenedor.The result is stored in this container. No se admite SAS con directiva de acceso almacenada.SAS with stored access policy are not supported. Cuando no se especifica, Microsoft almacena los resultados en un contenedor de almacenamiento administrado por Microsoft.When not specified, Microsoft stores the results in a storage container managed by Microsoft. Cuando se elimina la transcripción mediante una llamada a Delete transcription, también se eliminan los datos del resultado.When the transcription is deleted by calling Delete transcription, the result data will also be deleted.

StorageStorage

La transcripción por lotes puede leer audio desde un URI de Internet visible públicamente, además de leer transcripciones de audio o de escritura mediante un URI de SAS con Azure Blob Storage.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.

Resultado de la transcripción por lotesBatch transcription result

Para cada entrada de audio, se crea un archivo de resultado de transcripción.For each audio input, one transcription result file is created. La operación Get transcripciones files devuelve una lista de archivos de resultados para esta transcripción.The Get transcriptions files operation returns a list of result files for this transcription. Para buscar el archivo de transcripción de un archivo de entrada específico, filtre todos los archivos devueltos con kind == Transcription y 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.

Cada uno de los archivos de resultado de transcripción tiene el siguiente formato: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"
      "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
          "speaker": 1,                 // if `diarizationEnabled` is `true`, this is the identified speaker (1 or 2), otherwise this property is not present
          "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
            }
          ]
        }
      ]    
    }
  ]
}

El resultado contiene los siguientes campos:The result contains the following fields:

CampoField

ContenidoContent

lexical

Las palabras reales reconocidas.The actual words recognized.

itn

El formato de normalización inversa de texto del texto reconocido.Inverse-text-normalized form of the recognized text. Se aplican las abreviaturas ("doctor Pérez" a "Dr Pérez"), los números de teléfono y otras transformaciones.Abbreviations ("doctor smith" to "dr smith"), phone numbers, and other transformations are applied.

maskedITN

El formato ITN con enmascaramiento de palabras soeces aplicado.The ITN form with profanity masking applied.

display

El formato mostrado del texto reconocido.The display form of the recognized text. Se incluyen el uso de mayúsculas y minúsculas y la puntuación que se agrega.Added punctuation and capitalization are included.

Separación de altavoces (diarización)Speaker separation (diarization)

La diarización es el proceso de separación de los altavoces en una parte del audio.Diarization is the process of separating speakers in a piece of audio. La canalización por lotes admite la diarización y es capaz de reconocer dos altavoces en grabaciones monocanal.The batch pipeline supports diarization and is capable of recognizing two speakers on mono channel recordings. La característica no está disponible en las grabaciones estéreo.The feature is not available on stereo recordings.

La salida de la transcripción con la opción de diarización habilitada contiene una entrada Speaker para cada frase transcrita.The output of transcription with diarization enabled contains a Speaker entry for each transcribed phrase. Si no se usa la diarización, la propiedad Speaker no está presente en la salida del archivo JSON.If diarization is not used, the Speaker property is not present in the JSON output. Para la diarización, se admiten dos voces, por lo que los oradores se identifican como 1 o 2.For diarization we support two voices, so the speakers are identified as 1 or 2.

Para solicitar la diarización, establezca la propiedad diarizationEnabled en true, tal y como se muestra en la solicitud HTTP a continuación.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"
}

Las marcas de tiempo de nivel de palabra deben habilitarse, como indican los parámetros de la solicitud anterior.Word-level timestamps must be enabled as the parameters in the above request indicate.

Procedimientos recomendadosBest practices

El servicio transcripción por lotes puede manejar un elevado número de transcripciones enviadas.The batch transcription service can handle large number of submitted transcriptions. Puede consultar el estado de las transcripciones mediante Get transcriptions.You can query the status of your transcriptions with Get transcriptions. Realice una llamada a Delete transcription periódicamente desde el servicio cuando se hayan recuperado los resultados.Call Delete transcription regularly from the service once you retrieved the results. También puede establecer la propiedad timeToLive para garantizar que los resultados se eliminen eventualmente.Alternatively set timeToLive property to ensure eventual deletion of the results.

Código de ejemploSample code

Hay ejemplos completos disponibles en el repositorio de ejemplos de GitHub dentro del subdirectorio samples/batch.Complete samples are available in the GitHub sample repository inside the samples/batch subdirectory.

Si utiliza un modelo personalizado, actualice el código de ejemplo con la información de suscripción, la región del servicio, el URI que apunta al archivo de audio que se va a transcribir y la ubicación del modelo.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}");

El código de ejemplo configura el cliente y envía la solicitud de transcripción.The sample code sets up the client and submits the transcription request. A continuación, sondea la información de estado e imprime los detalles sobre el progreso de la transcripción.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);
}

Para más información sobre las llamadas anteriores, consulte nuestro documento de Swagger.For full details about the preceding calls, see our Swagger document. Para ver el ejemplo completo aquí mostrado, vaya a GitHub en el subdirectorio samples/batch.For the full sample shown here, go to GitHub in the samples/batch subdirectory.

En este ejemplo se usa una configuración asincrónica para publicar audio y recibir el estado de la transcripción.This sample uses an asynchronous setup to post audio and receive transcription status. El método PostTranscriptions envía los detalles del archivo de audio y el método GetTranscriptions recibe los estados.The PostTranscriptions method sends the audio file details and the GetTranscriptions method receives the states. PostTranscriptions devuelve un identificador y GetTranscriptions lo usa para crear un identificador y obtener el estado de la transcripción.PostTranscriptions returns a handle, and GetTranscriptions uses it to create a handle to get the transcription status.

Este código de ejemplo no especifica un modelo personalizado.This sample code doesn't specify a custom model. El servicio usa el modelo base de referencia para transcribir los archivos.The service uses the baseline model for transcribing the file or files. Para especificar el modelo, puede pasar la referencia de modelo del modelo personalizado en el mismo método.To specify the model, you can pass on the same method the model reference for the custom model.

Nota

En el caso de las transcripciones de base de referencia, no es necesario declarar los identificadores del modelo de base de referencia.For baseline transcriptions, you don't need to declare the ID for the baseline model.

Pasos siguientesNext steps