Criar uma transcrição em lote

Artigo
04/15/2024

Com as transcrições em lote, você envia dados de áudio em um lote. O serviço transcreve os dados de áudio e armazena os resultados em um contêiner de armazenamento. Em seguida, você pode recuperar os resultados a partir do contêiner de armazenamento.

Importante

Novos preços estão em vigor para transcrições em lote por meio da API REST de Conversão de Fala em Texto v3.2. Para saber mais, consulte o guia de preços.

Pré-requisitos

O SDK de Fala instalado.
Um recurso de Fala padrão (S0). Os recursos gratuitos (F0) não são suportados.

Criar um trabalho de transcrição

Para criar uma transcrição, use a operação Transcriptions_Create da API REST de Conversão de fala em texto . Crie o corpo da solicitação de acordo com as seguintes instruções:

Você deve definir a propriedade contentContainerUrl ou contentUrls. Para obter mais informações sobre o armazenamento de blobs do Azure para transcrição em lote, confira Localizar arquivos de áudio para transcrição em lote.
Defina a propriedade locale obrigatória. Esse valor deve corresponder à localidade esperada dos dados de áudio a serem transcritos. Você não pode alterar a localidade mais tarde.
Defina a propriedade displayName obrigatória. Escolha um nome da transcrição para você poder consultar mais tarde. O nome da transcrição não precisa ser exclusivo e pode ser alterado depois.
Opcionalmente, para usar um modelo diferente do modelo básico, defina a propriedade model como a ID do modelo. Para obter mais informações, confira Usar um modelo personalizado e Usar um modelo Whisper.
Opcionalmente, você pode definir a propriedade wordLevelTimestampsEnabled como true para habilitar carimbos de data/hora no nível de palavra nos resultados da transcrição. O valor padrão é false. No caso dos modelos Whisper, defina a propriedade displayFormWordLevelTimestampsEnabled em vez disso. O Whisper é um modelo somente exibição, portanto, o campo léxico não é preenchido na transcrição.
Opcionalmente, defina a propriedade languageIdentification. A identificação de idioma é usada para identificar os idiomas falados em áudio quando comparado com uma lista de idiomas com suporte. Se você definir a propriedade languageIdentification, também deverá definir languageIdentification.candidateLocales com localidades candidatas.

Para obter mais informações, confira Opções de configuração da solicitação.

Faça uma solicitação HTTP POST que use o URI, conforme mostrado no exemplo Transcriptions_Create a seguir.

Substitua YourSubscriptionKey pela chave do recurso de Fala.
Substitua YourServiceRegion pela região do Recurso de Fala.
Defina as propriedades do corpo da solicitação conforme 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"

Você deve receber um corpo de resposta no seguinte formato:

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

A propriedade self de nível superior no corpo da resposta é o URI da transcrição. Use esse URI para obter detalhes como o URI das transcrições e os arquivos de relatório de transcrição. Esse URI também pode ser usado para atualizar ou excluir uma transcrição.

É possível consultar o status de suas transcrições com a operação Transcriptions_Get.

Chame Transcriptions_Delete regularmente no serviço depois de recuperar os resultados. Como alternativa, defina a propriedade timeToLive para garantir a exclusão eventual dos resultados.

Para criar uma transcrição, use o comando spx batch transcription create. Construa os parâmetros de solicitação de acordo com as seguintes instruções:

Defina o parâmetro content necessário. Você pode especificar uma lista delimitada por ponto e vírgula de arquivos individuais ou a URL para um contêiner inteiro. Para obter mais informações sobre o armazenamento de blobs do Azure para transcrição em lote, confira Localizar arquivos de áudio para transcrição em lote.
Defina a propriedade language obrigatória. Esse valor deve corresponder à localidade esperada dos dados de áudio a serem transcritos. Você não pode alterar a localidade mais tarde. O parâmetro language da CLI de Fala corresponde à propriedade locale na solicitação e na resposta JSON.
Defina a propriedade name obrigatória. Escolha um nome da transcrição para você poder consultar mais tarde. O nome da transcrição não precisa ser exclusivo e pode ser alterado depois. O parâmetro name da CLI de Fala corresponde à propriedade displayName na solicitação e na resposta JSON.

Confira um exemplo de comando da CLI de Fala que cria um trabalho de transcrição:

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

Você deve receber um corpo de resposta no seguinte formato:

{
  "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 obter ajuda da CLI de Fala com as transcrições, execute o comando a seguir:

spx help batch transcription

Solicitar opções de configuração

Confira algumas opções de propriedade que você pode usar para configurar uma transcrição ao chamar a operação Transcriptions_Create.

Propriedade	Descrição
`channels`	Uma matriz de números de canal para processar. Os canais `0` e `1` são transcritos por padrão.
`contentContainerUrl`	Você pode enviar arquivos de áudio individuais ou um contêiner de armazenamento inteiro. Você precisa especificar o local dos dados de áudio por meio da propriedade `contentContainerUrl` ou `contentUrls`. Para obter mais informações sobre o armazenamento de blobs do Azure para transcrição em lote, confira Localizar arquivos de áudio para transcrição em lote. Essa propriedade não é retornada na resposta.
`contentUrls`	Você pode enviar arquivos de áudio individuais ou um contêiner de armazenamento inteiro. Você precisa especificar o local dos dados de áudio por meio da propriedade `contentContainerUrl` ou `contentUrls`. Para obter mais informações, confira Localizar arquivos de áudio para transcrição em lote. Essa propriedade não é retornada na resposta.
`destinationContainerUrl`	O resultado pode ser armazenado em um contêiner do Azure. Quando você não especifica um contêiner, o Serviço de Fala armazena os resultados em um contêiner gerenciado pela Microsoft. Quando o trabalho de transcrição é excluído, os dados de resultado da transcrição também são excluídos. Para obter mais informações, como quais são os cenários de segurança com suporte, confira Especificar uma URL de contêiner de destino.
`diarization`	Indica que o serviço de Fala deve tentar uma análise de diarização na entrada de dados, que deve ser um canal mono contendo várias vozes. O recurso não está disponível nas gravações estéreo. A diarização é o processo de separar alto-falantes em dados de áudio. O pipeline do lote pode reconhecer e separar vários alto-falantes nas gravações de canal mono. Especificar o número mínimo e máximo de pessoas que podem estar falando. Você também deve definir a propriedade `diarizationEnabled` como `true`. O arquivo de transcrição contém uma entrada `speaker` para cada frase transcrita. Você precisa usar essa propriedade quando espera ter três ou mais locutores. Para dois locutores, definir a propriedade `diarizationEnabled` como `true` é suficiente. Para obter um exemplo do uso da propriedade, confira Transcriptions_Create. O número máximo de locutores para diarização deve ser menor que 36 e maior ou igual à propriedade `minSpeakers`. Para obter um exemplo, confira Transcriptions_Create. Quando essa propriedade é selecionada, a duração do áudio de origem não pode exceder 240 minutos por arquivo. Observação: essa propriedade só está disponível com a API REST de Conversão de fala em texto versão 3.1. Se você a definir com qualquer versão anterior (como a versão 3.0), essa propriedade será ignorada e apenas dois locutores serão identificados.
`diarizationEnabled`	Especifica que o serviço de Fala deve tentar uma análise de diarização na entrada de dados, que deve ser um canal mono contendo duas vozes. O valor padrão é `false`. Para três ou mais vozes, você também precisará usar a propriedade `diarization`. Use somente com a API REST de Conversão de Fala em Texto versão 3.1 e posterior. Quando essa propriedade é selecionada, a duração do áudio de origem não pode exceder 240 minutos por arquivo.
`displayName`	O nome da transcrição em lote. Escolha um nome para você poder consultar mais tarde. O nome de exibição não precisa ser exclusivo. Esta propriedade é necessária.
`displayFormWordLevelTimestampsEnabled`	Especifica se os carimbos de data/hora no nível da palavra devem ser incluídos na forma de exibição dos resultados da transcrição. Os resultados são retornados na propriedade `displayWords` do arquivo de transcrição. O valor padrão é `false`. Observação: essa propriedade só está disponível com a API REST de Conversão de fala em texto versão 3.1.
`languageIdentification`	A identificação de idioma é usada para identificar os idiomas falados em áudio quando comparado com uma lista de idiomas com suporte. Se você definir a propriedade `languageIdentification`, também deverá definir sua propriedade delimitada `candidateLocales`.
`languageIdentification.candidateLocales`	As localidades candidatas para a identificação do idioma, como, por exemplo, `"properties": { "languageIdentification": { "candidateLocales": ["en-US", "de-DE", "es-ES"]}}`. Há suporte para um mínimo de dois e um máximo de dez localidades candidatas, incluindo a localidade principal para a transcrição.
`locale`	O nome da transcrição em lote. Esse valor deve corresponder à localidade esperada dos dados de áudio a serem transcritos. Ela não poderá ser alterada posteriormente. Esta propriedade é necessária.
`model`	Você pode definir a propriedade `model` para usar um modelo básico específico ou um modelo de fala personalizado. Se você não especificar `model`, o modelo base padrão da localidade será usado. Para obter mais informações, confira Usar um modelo personalizado e Usar um modelo Whisper.
`profanityFilterMode`	Especifica como lidar com palavrões em resultados de reconhecimento. Os valores aceitos são `None` para desabilitar a filtragem de conteúdo ofensivo, `Masked` para substituir o conteúdo ofensivo por asteriscos, `Removed` para remover todo o conteúdo ofensivo do resultado ou `Tags` para adicionar marcas de conteúdo ofensivo. O valor padrão é `Masked`.
`punctuationMode`	Especifica como manipular a pontuação nos resultados do reconhecimento. Os valores aceitos são `None` para desabilitar a pontuação, `Dictated` para sugerir pontuação explícita (falada), `Automatic` para permitir que o decodificador lide com a pontuação ou `DictatedAndAutomatic` para usar pontuação ditada e automática. O valor padrão é `DictatedAndAutomatic`. Essa propriedade não é aplicável a modelos Whisper.
`timeToLive`	Uma duração é criada após o trabalho de transcrição, quando os resultados da transcrição serão excluídos automaticamente. O valor é uma duração codificada em ISO 8601. Por exemplo, especifique `PT12H` para 12 horas. Opcionalmente, você pode chamar regularmente Transcriptions_Delete após recuperar os resultados da transcrição.
`wordLevelTimestampsEnabled`	Especifica se os carimbos de data/hora no nível da palavra devem ser incluídos na saída. O valor padrão é `false`. Essa propriedade não é aplicável a modelos Whisper. O Whisper é um modelo somente exibição, portanto, o campo léxico não é preenchido na transcrição.

Para obter ajuda da CLI de Fala com as opções de configuração das transcrições, execute o comando a seguir:

spx help batch transcription create advanced

Usar um modelo personalizado

A transcrição em lote usa o modelo base padrão para a localidade que você especificar. Você não precisa definir nenhuma propriedade para usar o modelo base padrão.

Opcionalmente, você pode modificar o exemplo anterior criar transcrição definindo a propriedade model para usar um modelo de base específico ou o modelo de fala personalizado.

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 um modelo de fala personalizado para transcrição em lote, você precisa do URI do modelo. A propriedade self de nível superior no corpo da resposta é o URI do modelo. É possível recuperar a localização do modelo ao criar ou obter um modelo. Para obter mais informações, confira o exemplo de resposta JSON em Criar um modelo.

Dica

Um ponto de extremidade de implantação hospedado não é necessário para usar a fala personalizada com o serviço de transcrição em lote. Você poderá conservar recursos se usar o modelo de fala personalizado somente para transcrições em lote.

As solicitações de transcrição em lote para modelos expirados falham com um erro 4xx. Defina a propriedade model como um modelo básico ou um modelo personalizado que não estiver expirado. Caso contrário, não inclua a model propriedade de usar sempre o modelo base mais recente. Para obter mais informações, confira Escolher um modelo e Ciclo de vida de um modelo de fala personalizado.

Usar um modelo Whisper

A Fala de IA do Azure é compatível com o modelo Whisper do OpenAI com o uso da API de transcrições em lote. Você pode usar o modelo Whisper para transcrições em lote.

Observação

O Serviço OpenAI do Azure também dá suporte ao modelo Whisper do OpenAI para conversão de fala em texto com uma API REST síncrona. Para saber mais, confira Conversão de fala em texto com o modelo Whisper do OpenAI do Azure. Para obter mais informações sobre quando usar a Fala de IA do Azure ou o Serviço OpenAI do Azure, confira O que é o modelo Whisper?

Para usar um modelo Whisper para transcrições em lote, você precisa definir a propriedade model. O Whisper é um modelo somente exibição, portanto, o campo léxico não é preenchido na resposta.

Importante

Para modelos whisper, você sempre deve usar a versão 3.2 da API de conversão de fala em texto.

Os modelos Whisper por transcrição em lote têm suporte nas regiões Leste da Austrália, EUA Central, Leste dos EUA, Centro-Norte dos EUA, Centro-Sul dos EUA, Sudeste da Ásia e Oeste da Europa.

Você pode fazer uma solicitação Models_ListBaseModels para obter modelos base disponíveis de todas as localidades.

Faça uma solicitação HTTP GET conforme mostrado no exemplo a seguir para a região eastus. Substitua YourSubscriptionKey pela chave do recurso de Fala. Substitua eastus se você estiver usando uma região diferente.

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

Por padrão, apenas os 100 dos modelos básicos mais antigos são retornados. Use os parâmetros de consulta skip e top para paginar os resultados. Por exemplo, a solicitação a seguir retorna os próximos 100 modelos base após os primeiros 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"

Certifique-se de defina as variáveis de configuração para um recurso de Fala em uma das regiões com suporte. Você pode executar o spx csr list --base comando para obter modelos de base disponíveis para todas as localidades.

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

A propriedade displayName de um modelo Whisper contém "Whisper", conforme mostrado neste exemplo. O Whisper é um modelo somente exibição, portanto, o campo léxico não é preenchido na transcrição.

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

Você define o URI do modelo completo, conforme mostrado nesse exemplo para a região eastus. Substitua YourSubscriptionKey pela chave do recurso de Fala. Substitua eastus se você estiver usando uma região diferente.

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 uma URL de contêiner de destino

O resultado da transcrição pode ser armazenado em um contêiner do Azure. Quando você não especifica um contêiner, o Serviço de Fala armazena os resultados em um contêiner gerenciado pela Microsoft. Nesse caso, quando o trabalho de transcrição é excluído, os dados de resultado da transcrição também são excluídos.

Você pode armazenar os resultados de uma transcrição em lote em um contêiner de armazenamento de Blobs do Azure gravável usando a opção destinationContainerUrl na solicitação de criação de transcrição em lote. Essa opção usa apenas um URI de SAS ad hoc e não dá suporte ao Mecanismo de segurança dos serviços confiáveis do Azure. Essa opção também não dá suporte à SAS baseada em política de acesso. O recurso da conta de armazenamento do contêiner de destino deve permitir todo o tráfego externo.

Se quiser armazenar os resultados da transcrição em um contêiner de armazenamento de Blobs do Azure usando o Mecanismo de segurança dos serviços confiáveis do Azure, pense em usar o BYOS (Traga seu próprio armazenamento). Para obter mais informações, confira Usar o recurso de Fala do tipo BYOS (Traga seu próprio armazenamento) para a conversão de fala em texto.