Uso de la transcripción por lotes

La transcripción por lotes es un conjunto de operaciones de API REST que permite transcribir una gran cantidad de audio en el almacenamiento. Puede apuntar a archivos de audio mediante un identificador URI típico de firma de acceso compartido (SAS) y recibir los resultados de las transcripciones de forma asincrónica. Con la API v3.0, puede transcribir uno o varios archivos de audio o procesar un contenedor de almacenamiento completo.

Puede usar las API REST de transcripción por lotes para llamar a los métodos siguientes:

Puede revisar y probar la API detallada, que está disponible como un documento de Swagger.

Los trabajos de transcripción por lotes se programan de la mejor manera posible. 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. 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.

Requisitos previos

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.

Si tiene previsto personalizar los modelos, siga los pasos descritos en Personalización acústica y Personalización de idioma. Para usar los modelos creados en la transcripción por lotes, necesita sus ubicaciones. Puede recuperar la ubicación del modelo al inspeccionar los detalles del modelo (propiedad self). No es necesario un punto de conexión personalizado implementado para el servicio de transcripción por lotes.

API de transcripciones de Azure Batch

La API Batch Transcription admite los siguientes formatos:

En el caso de las secuencias de audio estéreo, los canales izquierdo y derecho se dividen durante la transcripción. Para cada canal se crea un archivo de resultados JSON. Para crear una transcripción final ordenada, utilice las marcas de tiempo generadas por expresión.

Configuración

Los parámetros de configuración se proporcionan como JSON.

Transcripción de uno o varios archivos individuales. Si desea transcribir más de un archivo, es aconsejable enviar varios en una sola solicitud. En el ejemplo siguiente se usan tres archivos:

{
  "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. La SAS del contenedor deben incluir permisos r (lectura) y l (lista):

{
  "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. En el ejemplo se usan tres archivos:

{
  "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ón

Utilice estas propiedades opcionales para configurar la transcripción:

Storage

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.

Resultado de la transcripción por lotes

Para cada entrada de audio, se crea un archivo de resultado de transcripción. La operación Get transcripciones files devuelve una lista de archivos de resultados para esta transcripción. 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.

Cada uno de los archivos de resultado de transcripción tiene el siguiente formato:

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

El resultado contiene los siguientes campos:

Separación de altavoces (diarización)

La diarización es el proceso de separación de los altavoces en una parte del audio. La canalización por lotes admite la diarización y es capaz de reconocer dos altavoces en grabaciones monocanal. La característica no está disponible en las grabaciones estéreo.

La salida de la transcripción con la opción de diarización habilitada contiene una entrada Speaker para cada frase transcrita. Si no se usa la diarización, la propiedad Speaker no está presente en la salida del archivo JSON. Para la diarización, se admiten dos voces, por lo que los oradores se identifican como 1 o 2.

Para solicitar la diarización, establezca la propiedad diarizationEnabled en true, tal y como se muestra en la solicitud HTTP a continuación.

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

Procedimientos recomendados

El servicio transcripción por lotes puede manejar un elevado número de transcripciones enviadas. Puede consultar el estado de las transcripciones mediante Get transcriptions. Realice una llamada a Delete transcription periódicamente desde el servicio cuando se hayan recuperado los resultados. También puede establecer la propiedad timeToLive para garantizar que los resultados se eliminen eventualmente.

Código de ejemplo

Hay ejemplos completos disponibles en el repositorio de ejemplos de GitHub dentro del subdirectorio samples/batch.

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.

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.CreateTranscriptionAsync(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. A continuación, sondea la información de estado e imprime los detalles sobre el progreso de la transcripción.

// 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. Para ver el ejemplo completo aquí mostrado, vaya a GitHub en el subdirectorio samples/batch.

En este ejemplo se usa una configuración asincrónica para publicar audio y recibir el estado de la transcripción. El método PostTranscriptions envía los detalles del archivo de audio y el método GetTranscriptions recibe los estados. PostTranscriptions devuelve un identificador y GetTranscriptions lo usa para crear un identificador y obtener el estado de la transcripción.

Este código de ejemplo no especifica un modelo personalizado. El servicio usa el modelo base de referencia para transcribir los archivos. Para especificar el modelo, puede pasar la referencia de modelo del modelo personalizado en el mismo método.

Pasos siguientes

• Referencia de la API Conversión de voz en texto v3