Creación de una transcripción por lotes

Artículo
04/15/2024

Con las transcripciones por lotes, se envían datos de audio en un lote. El servicio transcribe los datos de audio y almacena los resultados en un contenedor de almacenamiento. A continuación, puede recuperar los resultados del contenedor de almacenamiento.

Importante

Los nuevos precios están en vigor para la transcripción por lotes a través de la API de REST de conversión de voz en texto v3.2. Para obtener más información, consulte la guía de precios.

Requisitos previos

El SDK de Voz instalado.
Un recurso de voz estándar (S0). Los recursos libres (F0) no son compatibles.

Creación de un trabajo de transcripción

Para crear una transcripción, use la operación Transcriptions_Create de la API de REST de Conversión de voz en texto. Construya el cuerpo de la solicitud según las instrucciones siguientes:

Debe establecer una de las siguientes opciones contentContainerUrl o contentUrls. Para más información sobre Azure Blob Storage para la transcripción por lotes, consulte Búsqueda de archivos de audio para la transcripción por lotes.
Establezca la propiedad locale requerida. Esto debe coincidir con la configuración regional esperada de los datos de audio que se van a transcribir. No podrá cambiar la configuración regional más adelante.
Establezca la propiedad displayName requerida. Elija un nombre de transcripción al que pueda hacer referencia más adelante. El nombre de transcripción no tiene que ser único y se puede cambiar más adelante.
Opcionalmente, para usar un modelo distinto del modelo base, establezca la propiedad model en el id. del modelo. Para obtener más información, consulte Uso del modelo personalizado y Uso del modelo Whisper.
Opcionalmente, puede establecer la propiedad wordLevelTimestampsEnabled en true para habilitar las marcas de tiempo de nivel de palabra en los resultados de la transcripción. El valor predeterminado es false. En el caso de los modelos Whisper, establezca la propiedad displayFormWordLevelTimestampsEnabled en su lugar. Whisper es un modelo de solo presentación, por lo que el campo léxico no se rellena en la transcripción.
Opcionalmente, establezca la propiedad languageIdentification. La identificación del idioma se usa para identificar los idiomas que se hablan en el audio mediante la comparación con una lista de idiomas admitidos. Si establece la propiedad languageIdentification, también deberá establecer languageIdentification.candidateLocales con configuraciones regionales candidatas.

Para más información, consulte Opciones de configuración de solicitudes.

Haga una solicitud HTTP POST con el URI como se muestra en el siguiente ejemplo de Transcriptions_Create.

Reemplace YourSubscriptionKey por su clave de recurso de Voz.
Reemplace YourServiceRegion por la región del recurso de Voz.
Establezca las propiedades del cuerpo de la solicitud como se ha descrito anteriormente.

curl -v -X POST -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey" -H "Content-Type: application/json" -d '{
  "contentUrls": [
    "https://crbn.us/hello.wav",
    "https://crbn.us/whatstheweatherlike.wav"
  ],
  "locale": "en-US",
  "displayName": "My Transcription",
  "model": null,
  "properties": {
    "wordLevelTimestampsEnabled": true,
    "languageIdentification": {
      "candidateLocales": [
        "en-US", "de-DE", "es-ES"
      ],
    }
  },
}'  "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions"

Debe recibir un cuerpo de respuesta en el formato siguiente:

{
  "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions/db474955-ab85-4c6c-ba6e-3bfe63d041ba",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"
  },
  "links": {
    "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions/db474955-ab85-4c6c-ba6e-3bfe63d041ba/files"
  },
  "properties": {
    "diarizationEnabled": false,
    "wordLevelTimestampsEnabled": true,
    "channels": [
      0,
      1
    ],
    "punctuationMode": "DictatedAndAutomatic",
    "profanityFilterMode": "Masked",
    "languageIdentification": {
      "candidateLocales": [
        "en-US",
        "de-DE",
        "es-ES"
      ]
    }
  },
  "lastActionDateTime": "2022-10-21T14:18:06Z",
  "status": "NotStarted",
  "createdDateTime": "2022-10-21T14:18:06Z",
  "locale": "en-US",
  "displayName": "My Transcription"
}

La propiedad self de nivel superior del cuerpo de respuesta es el URI de la transcripción. Use este URI para obtener detalles, como el URI de las transcripciones y los archivos de informe de transcripción. Use también este URI para actualizar o eliminar una transcripción.

Puede consultar el estado de las transcripciones mediante la operación Transcriptions_Get.

Llame a Transcriptions_Delete periódicamente desde el servicio después de recuperar los resultados. También puede establecer la propiedad timeToLive para garantizar que lo resultados se eliminan eventualmente.

Para crear una transcripción, use el comando spx batch transcription create. Construya los parámetros de solicitud según las instrucciones siguientes:

Establezca el parámetro content necesario. Puede especificar una lista delimitada por punto y coma de archivos individuales o la dirección URL de un contenedor completo. Para más información sobre Azure Blob Storage para la transcripción por lotes, consulte Búsqueda de archivos de audio para la transcripción por lotes.
Establezca la propiedad language requerida. Esto debe coincidir con la configuración regional esperada de los datos de audio que se van a transcribir. No podrá cambiar la configuración regional más adelante. El parámetro language de la CLI de Voz corresponde a la propiedad locale de la solicitud y respuesta JSON.
Establezca la propiedad name requerida. Elija un nombre de transcripción al que pueda hacer referencia más adelante. El nombre de transcripción no tiene que ser único y se puede cambiar más adelante. El parámetro name de la CLI de Voz corresponde a la propiedad displayName de la solicitud y respuesta JSON.

Este es un ejemplo de comando de la CLI de Voz que crea un trabajo de transcripción:

spx batch transcription create --name "My Transcription" --language "en-US" --content https://crbn.us/hello.wav;https://crbn.us/whatstheweatherlike.wav

Debe recibir un cuerpo de respuesta en el formato siguiente:

{
  "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions/7f4232d5-9873-47a7-a6f7-4a3f00d00dc0",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"
  },
  "links": {
    "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions/7f4232d5-9873-47a7-a6f7-4a3f00d00dc0/files"
  },
  "properties": {
    "diarizationEnabled": false,
    "wordLevelTimestampsEnabled": false,
    "channels": [
      0,
      1
    ],
    "punctuationMode": "DictatedAndAutomatic",
    "profanityFilterMode": "Masked"
  },
  "lastActionDateTime": "2022-10-21T14:21:59Z",
  "status": "NotStarted",
  "createdDateTime": "2022-10-21T14:21:59Z",
  "locale": "en-US",
  "displayName": "My Transcription",
  "description": ""
}

Para obtener ayuda sobre la CLI de Voz con las transcripciones, ejecute el siguiente comando:

spx help batch transcription

Solicitud de opciones de configuración

Estas son algunas opciones de propiedades que puede usar para configurar una transcripción al llamar a la operación Transcriptions_Delete.

Propiedad	Descripción
`channels`	Matriz de números de canal para procesar. Los canales `0` y `1` se transcriben de forma predeterminada.
`contentContainerUrl`	Puede enviar archivos de audio individuales o un contenedor de almacenamiento completo. Debe especificar la ubicación de datos de audio a través de la propiedad `contentContainerUrl` o `contentUrls`. Para más información sobre Azure Blob Storage para la transcripción por lotes, consulte Búsqueda de archivos de audio para la transcripción por lotes. Esta propiedad no se devuelve en la respuesta.
`contentUrls`	Puede enviar archivos de audio individuales o un contenedor de almacenamiento completo. Debe especificar la ubicación de datos de audio a través de la propiedad `contentContainerUrl` o `contentUrls`. Para más información, consulte Búsqueda de archivos de audio para la transcripción por lotes. Esta propiedad no se devuelve en la respuesta.
`destinationContainerUrl`	El resultado se puede almacenar en un contenedor de Azure. Si no se especifica ningún contenedor, el servicio de Voz almacena los resultados en un contenedor administrado por Microsoft. Cuando se elimina el trabajo de transcripción, también se eliminan los datos del resultado de la transcripción. Para obtener más información, como los escenarios de seguridad admitidos, consulte Especificar la dirección URL del contenedor de destino.
`diarization`	Indica que el servicio de Voz debe intentar el análisis de diarización en la entrada, que se espera que sea un canal mono que contenga varias voces. La característica no está disponible en las grabaciones estéreo. La diarización es el proceso de separación de los altavoces en datos de audio. La canalización por lotes puede reconocer y separar varios altavoces en grabaciones de canal mono. Especifique el número mínimo y máximo de personas que podrían estar hablando. También debe establecer la propiedad `diarizationEnabled` en `true`. El archivo de transcripción contiene una entrada `speaker` para cada frase transcrita. Debe usar esta propiedad cuando espere tres o más altavoces. Para dos altavoces, es suficiente establecer la propiedad `diarizationEnabled` en `true`. Para obtener un ejemplo del uso de propiedades, consulte Transcriptions_Create. El número máximo de altavoces para la diarización debe ser menor que 36 y mayor o igual que la propiedad `minSpeakers`. Para obtener un ejemplo, consulte Transcriptions_Create. Cuando se selecciona esta propiedad, la longitud del audio de origen no puede superar los 240 minutos por archivo. Nota: esta propiedad solo está disponible con la versión 3.1 y versiones posteriores de la API de REST de conversión de voz en texto. Si establece esta propiedad con cualquier versión anterior (como la versión 3.0), se omitirá y solo se identificarán dos oradores.
`diarizationEnabled`	Especifica que el servicio de Voz debe intentar el análisis de diarización en la entrada, que se espera que sea un canal mono que contenga dos voces. El valor predeterminado es `false`. Para tres o más voces también debe usar la propiedad `diarization`. Use solo con la API de REST de conversión de voz en texto versión 3.1 y posteriores. Cuando se selecciona esta propiedad, la longitud del audio de origen no puede superar los 240 minutos por archivo.
`displayName`	Nombre de la transcripción por lotes. Elija un nombre al que pueda hacer referencia más adelante. El nombre para mostrar no tiene que ser único. Esta propiedad es obligatoria.
`displayFormWordLevelTimestampsEnabled`	Especifica si se deben incluir marcas de tiempo de nivel de palabra en el formulario de presentación de los resultados de la transcripción. Los resultados se devuelven en la propiedad `displayWords` del archivo de transcripción. El valor predeterminado es `false`. Nota: esta propiedad solo está disponible con la versión 3.1 y versiones posteriores de la API de REST de conversión de voz en texto.
`languageIdentification`	La identificación del idioma se usa para identificar los idiomas que se hablan en el audio mediante la comparación con una lista de idiomas admitidos. Si establece la propiedad `languageIdentification`, también deberá establecer su propiedad delimitada `candidateLocales`.
`languageIdentification.candidateLocales`	Configuraciones regionales candidatas para la identificación del idioma, como `"properties": { "languageIdentification": { "candidateLocales": ["en-US", "de-DE", "es-ES"]}}`. Se admite un mínimo de 2 y un máximo de 10 configuraciones regionales candidatas, incluyendo la configuración regional principal para la transcripción.
`locale`	Configuración regional de la transcripción por lotes. Esto debe coincidir con la configuración regional esperada de los datos de audio que se van a transcribir. Esta configuración regional no se podrá modificar más adelante. Esta propiedad es obligatoria.
`model`	Puede establecer la propiedad `model` para usar un modelo base específico o un modelo de voz personalizada. Si no especifica `model`, se usa el modelo base predeterminado para la configuración regional. Para obtener más información, consulte Uso del modelo personalizado y Uso del modelo Whisper.
`profanityFilterMode`	Especifica cómo controlar las palabras soeces en los resultados del reconocimiento. Los valores aceptados son `None` para deshabilitar el filtrado de palabras soeces, `Masked` para reemplazar las palabras soeces por asteriscos, `Removed` para quitar todas las palabras soeces del resultado o `Tags` para agregar etiquetas de palabras soeces. El valor predeterminado es `Masked`.
`punctuationMode`	Especifica cómo controlar la puntuación en los resultados del reconocimiento. 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. El valor predeterminado es `DictatedAndAutomatic`. Esta propiedad no es aplicable a los modelos de Whisper.
`timeToLive`	Una duración después de crear el trabajo de transcripción, cuando los resultados de la transcripción se eliminarán automáticamente. El valor es una duración codificada según la ISO 8601. Por ejemplo, especifique `PT12H` durante 12 horas. Como alternativa, puede llamar a Transcriptions_Delete periódicamente después de recuperar los resultados de la transcripción.
`wordLevelTimestampsEnabled`	Especifica si las marcas de tiempo de nivel de palabra se deben agregar a la salida. El valor predeterminado es `false`. Esta propiedad no es aplicable a los modelos de Whisper. Whisper es un modelo de solo presentación, por lo que el campo léxico no se rellena en la transcripción.

Para obtener ayuda sobre la CLI de Voz con las opciones de configuración, ejecute el siguiente comando:

spx help batch transcription create advanced

Usar un modelo personalizado

La transcripción por lotes usa el modelo base predeterminado para la configuración regional que especifique. No es necesario establecer ninguna propiedad para usar el modelo base predeterminado.

Opcionalmente, puede modificar el ejemplo de creación de transcripción anterior estableciendo la propiedad model para usar un modelo base específico o un modelo de voz personalizada.

curl -v -X POST -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey" -H "Content-Type: application/json" -d '{
  "contentUrls": [
    "https://crbn.us/hello.wav",
    "https://crbn.us/whatstheweatherlike.wav"
  ],
  "locale": "en-US",
  "displayName": "My Transcription",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base/1aae1070-7972-47e9-a977-87e3b05c457d"
  },
  "properties": {
    "wordLevelTimestampsEnabled": true,
  },
}'  "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions"

spx batch transcription create --name "My Transcription" --language "en-US" --content https://crbn.us/hello.wav;https://crbn.us/whatstheweatherlike.wav --model "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base/1aae1070-7972-47e9-a977-87e3b05c457d"

Para usar un modelo de voz personalizada para la transcripción por lotes, necesita el URI del modelo. La propiedad self de nivel superior en el cuerpo de la respuesta es el URI del proyecto. Puede recuperar la ubicación del modelo al crear u obtener un modelo. Para obtener más información, consulte el ejemplo de respuesta JSON en Creación de un modelo.

Sugerencia

No se requiere un punto de conexión de implementación hospedado para usar Habla personalizada con el servicio de transcripción de Batch. Es posible conservar los recursos si el modelo de voz personalizado solo se usa para la transcripción por lotes.

Las solicitudes de transcripción por lotes para los modelos expirados generan un error 4xx. Establezca la propiedad model en un modelo base o en un modelo personalizado que no haya expirado. De lo contrario, no incluya la propiedad model para usar siempre el modelo base más reciente. Para más información, consulte Elección del modelo y Ciclo de vida del modelo de voz personalizado.

Uso del modelo Whisper

Voz de Azure AI admite el modelo Whisper de OpenAI mediante la API de transcripción por lotes. Puede usar el modelo Whisper para la transcripción por lotes.

Nota:

Azure OpenAI Service también admite el modelo Whisper de OpenAI para la conversión de voz en texto con una API de REST sincrónica. Para más información, consulte Conversión de voz en texto con el modelo Whisper de Azure OpenAI. Para más información sobre cuándo usar Voz de Azure AI frente a Azure OpenAI Service, consulte ¿Qué es el modelo Whisper?

Para usar un modelo Whisper para la transcripción por lotes, también se debe establecer la propiedad model. Whisper es un modelo de solo presentación, por lo que el campo léxico no se rellena en la respuesta.

Importante

En el caso de los modelos de Whisper, siempre debe usar la versión 3.2 de la API de conversión de voz en texto.

Los modelos de susurro por transcripción por lotes se admiten en las regiones Este de Australia, Centro de EE. UU., Este de EE. UU., Centro-norte de EE. UU., Centro-sur de EE. UU., Sudeste de Asia y Oeste de Europa.

Puede realizar una solicitud Models_ListBaseModels a fin de obtener los modelos base disponibles para todas las configuraciones regionales.

Cree una solicitud HTTP GET como se muestra en el ejemplo siguiente de la región eastus. Reemplace YourSubscriptionKey por su clave de recurso de Voz. Si usa otra región, reemplace eastus.

curl -v -X GET "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/models/base" -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey"

De forma predeterminada, solo se devuelven los 100 modelos base más antiguos. Use los parámetros de consulta skip y top para paginar los resultados. Por ejemplo, la siguiente solicitud devuelve los siguientes 100 modelos base después de los primeros 100.

curl -v -X GET "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/models/base?skip=100&top=100" -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey"

Asegúrese de establecer las variables de configuración de un recurso de Voz en una de las regiones admitidas. Puede ejecutar el comando spx csr list --base a fin de obtener los modelos base disponibles para todas las configuraciones regionales.

spx csr list --base --api-version v3.2-preview.2

La propiedad displayName de un modelo de Whisper contiene "Whisper" como se muestra en este ejemplo. Whisper es un modelo de solo presentación, por lo que el campo léxico no se rellena en la transcripción.

{
  "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/models/base/e418c4a9-9937-4db7-b2c9-8afbff72d950",
  "links": {
    "manifest": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/models/base/e418c4a9-9937-4db7-b2c9-8afbff72d950/manifest"
  },
  "properties": {
    "deprecationDates": {
      "adaptationDateTime": "2025-04-15T00:00:00Z",
      "transcriptionDateTime": "2026-04-15T00:00:00Z"
    },
    "features": {
      "supportsTranscriptions": true,
      "supportsEndpoints": false,
      "supportsTranscriptionsOnSpeechContainers": false,
      "supportsAdaptationsWith": [
        "Acoustic"
      ],
      "supportedOutputFormats": [
        "Display"
      ]
    },
    "chargeForAdaptation": true
  },
  "lastActionDateTime": "2024-02-29T15:53:28Z",
  "status": "Succeeded",
  "createdDateTime": "2024-02-29T15:46:07Z",
  "locale": "en-US",
  "displayName": "20240228 Whisper Large V2",
  "description": "OpenAI Whisper Model in Azure AI Speech (Whisper v2-large)"
},

El URI completo del modelo se establece como se muestra en este ejemplo para la región eastus. Reemplace YourSubscriptionKey por su clave de recurso de Voz. Si usa otra región, reemplace eastus.

curl -v -X POST -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey" -H "Content-Type: application/json" -d '{
  "contentUrls": [
    "https://crbn.us/hello.wav",
    "https://crbn.us/whatstheweatherlike.wav"
  ],
  "locale": "en-US",
  "displayName": "My Transcription",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/models/base/d9cbeee6-582b-47ad-b5c1-6226583c92b6"
  },
  "properties": {
    "wordLevelTimestampsEnabled": true,
  },
}'  "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/transcriptions"

spx batch transcription create --name "My Transcription" --language "en-US" --content https://crbn.us/hello.wav;https://crbn.us/whatstheweatherlike.wav --model "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/models/base/d9cbeee6-582b-47ad-b5c1-6226583c92b6" --api-version v3.2-preview.2

Especificar la dirección URL del contenedor de destino

El resultado de la transcripción se puede almacenar en un contenedor de Azure. Si no se especifica ningún contenedor, el servicio de Voz almacena los resultados en un contenedor administrado por Microsoft. En ese caso, cuando se elimina el trabajo de transcripción, también se eliminan los datos del resultado de la transcripción.

Puede almacenar los resultados de una transcripción por lotes en un contenedor de Azure Blob Storage grabable mediante la opción destinationContainerUrl de la solicitud de creación de transcripción por lotes. Esta opción usa solo un URI de SAS ad hoc y no admite el mecanismo de seguridad de los servicios de Azure de confianza. Esta opción tampoco admite SAS basada en directivas de acceso. El recurso de la cuenta de almacenamiento del contenedor de destino debe permitir todo el tráfico externo.

Si desea almacenar los resultados de la transcripción en un contenedor de Azure Blob Storage mediante el mecanismo de seguridad de servicios de Azure de confianza, debe considerar la posibilidad de usar la opción Traiga su propio almacenamiento (BYOS). Para obtener más información, consulte Uso del recurso de voz Traiga su propio almacenamiento (BYOS) para la conversión de voz en texto.