Criar uma transcrição em lote

Artigo
04/15/2024

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

Importante

Novos preços estão em vigor para transcrição em lote usando Speech to text REST API v3.2. Para obter mais informações, consulte o guia de preços.

Pré-requisitos

O SDK de fala instalado.
Um recurso de fala padrão (S0). Recursos livres (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 fala para texto. Construa o corpo da solicitação de acordo com as seguintes instruções:

Você deve definir a contentContainerUrl propriedade ou contentUrls . Para obter mais informações sobre o armazenamento de blob do Azure para transcrição em lote, consulte Localizar arquivos de áudio para transcrição em lote.
Defina a propriedade necessária locale . Esse valor deve corresponder à localidade esperada dos dados de áudio a serem transcritos. Não é possível alterar a localidade mais tarde.
Defina a propriedade necessária displayName . Escolha um nome de transcrição ao qual possa fazer referência mais tarde. O nome da transcrição não precisa ser exclusivo e pode ser alterado posteriormente.
Opcionalmente, para usar um modelo diferente do modelo base, defina a model propriedade como a ID do modelo. Para obter mais informações, consulte Usar um modelo personalizado e Usar um modelo Whisper.
Opcionalmente, defina a wordLevelTimestampsEnabled propriedade como true para habilitar carimbos de data/hora no nível da palavra nos resultados da transcrição. O valor predefinido é false. Para modelos Whisper, defina a displayFormWordLevelTimestampsEnabled propriedade em vez disso. Whisper é um modelo somente de exibição, portanto, o campo lexical não é preenchido na transcrição.
Opcionalmente, defina a languageIdentification propriedade. A identificação de idioma é usada para identificar idiomas falados em áudio quando comparados com uma lista de idiomas suportados. Se você definir a languageIdentification propriedade, também deverá definir languageIdentification.candidateLocales com localidades candidatas.

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

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

Substitua YourSubscriptionKey pela chave de recurso de fala.
Substitua YourServiceRegion pela região de recursos 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"

Deverá 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 de nível self superior no corpo da resposta é o URI da transcrição. Use esse URI para obter detalhes, como o URI das transcrições e dos arquivos de relatório de transcrição. Você também usa esse URI para atualizar ou excluir uma transcrição.

Você pode consultar o status de suas transcrições com a operação Transcriptions_Get .

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

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

Defina o parâmetro necessário content . 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 blob do Azure para transcrição em lote, consulte Localizar arquivos de áudio para transcrição em lote.
Defina a propriedade necessária language . Esse valor deve corresponder à localidade esperada dos dados de áudio a serem transcritos. Não é possível alterar a localidade mais tarde. O parâmetro Speech CLI language corresponde à locale propriedade na solicitação e resposta JSON.
Defina a propriedade necessária name . Escolha um nome de transcrição ao qual possa fazer referência mais tarde. O nome da transcrição não precisa ser exclusivo e pode ser alterado posteriormente. O parâmetro Speech CLI name corresponde à displayName propriedade na solicitação e resposta JSON.

Aqui está 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

Deverá 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 transcrições, execute o seguinte comando:

spx help batch transcription

Solicitar opções de configuração

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

Property	Description
`channels`	Uma matriz de números de canal para processar. 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ê deve especificar o local dos dados de áudio usando a `contentContainerUrl` propriedade ou `contentUrls` . Para obter mais informações sobre o armazenamento de blob do Azure para transcrição em lote, consulte Localizar arquivos de áudio para transcrição em lote. Esta propriedade não é retornada na resposta.
`contentUrls`	Você pode enviar arquivos de áudio individuais ou um contêiner de armazenamento inteiro. Você deve especificar o local dos dados de áudio usando a `contentContainerUrl` propriedade ou `contentUrls` . Para obter mais informações, consulte Localizar arquivos de áudio para transcrição em lote. Esta propriedade não é retornada na resposta.
`destinationContainerUrl`	O resultado pode ser armazenado em um contêiner do Azure. Se você não especificar um contêiner, o serviço de Fala armazenará os resultados em um contêiner gerenciado pela Microsoft. Quando o trabalho de transcrição é excluído, os dados do resultado da transcrição também são excluídos. Para obter mais informações, como os cenários de segurança suportados, consulte Especificar uma URL de contêiner de destino.
`diarization`	Indica que o serviço de Fala deve tentar a análise de diarização na entrada, que se espera que seja um canal mono que contenha várias vozes. O recurso não está disponível com gravações estéreo. Diarização é o processo de separação de alto-falantes em dados de áudio. O pipeline de lote pode reconhecer e separar vários alto-falantes em gravações de canal mono. Especifique o número mínimo e máximo de pessoas que podem estar falando. Você também deve definir a `diarizationEnabled` propriedade como `true`. O ficheiro de transcrição contém uma `speaker` entrada para cada frase transcrita. Você precisa usar essa propriedade quando espera três ou mais alto-falantes. Para dois alto-falantes, definir `diarizationEnabled` a propriedade como `true` é suficiente. Para obter um exemplo do uso da propriedade, consulte Transcriptions_Create. O número máximo de falantes para diarização deve ser inferior a 36 e superior ou igual à `minSpeakers` propriedade. Para obter um exemplo, consulte Transcriptions_Create. Quando essa propriedade é selecionada, o comprimento do áudio de origem não pode exceder 240 minutos por arquivo. Nota: Esta propriedade só está disponível com a API REST de fala para texto versão 3.1 e posterior. Se você definir essa propriedade com qualquer versão anterior, como a versão 3.0, ela será ignorada e apenas dois alto-falantes serão identificados.
`diarizationEnabled`	Especifica que o serviço de Fala deve tentar a análise de diarização na entrada, que se espera que seja um canal mono que contenha duas vozes. O valor predefinido é `false`. Para três ou mais vozes, você também precisa usar a propriedade `diarization`. Use somente com a API REST de fala para texto versão 3.1 e posterior. Quando essa propriedade é selecionada, o comprimento do áudio de origem não pode exceder 240 minutos por arquivo.
`displayName`	O nome da transcrição do lote. Escolha um nome ao qual possa referir-se mais tarde. O nome para 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 no formulário de exibição dos resultados da transcrição. Os resultados são retornados na `displayWords` propriedade do arquivo de transcrição. O valor predefinido é `false`. Nota: Esta propriedade só está disponível com a API REST de fala para texto versão 3.1 e posterior.
`languageIdentification`	A identificação de idioma é usada para identificar idiomas falados em áudio quando comparados com uma lista de idiomas suportados. Se você definir a `languageIdentification` propriedade, então você também deve definir sua propriedade inclusa `candidateLocales` .
`languageIdentification.candidateLocales`	As localidades do candidato para identificação de idioma, como `"properties": { "languageIdentification": { "candidateLocales": ["en-US", "de-DE", "es-ES"]}}`. Um mínimo de duas e um máximo de dez localidades candidatas, incluindo a localidade principal para a transcrição, são suportadas.
`locale`	A localidade da transcrição do lote. Esse valor deve corresponder à localidade esperada dos dados de áudio a serem transcritos. A localidade não pode ser alterada posteriormente. Esta propriedade é necessária.
`model`	Você pode definir a `model` propriedade para usar um modelo base específico ou um modelo de fala personalizado. Se você não especificar o `model`, o modelo base padrão para a localidade será usado. Para obter mais informações, consulte Usar um modelo personalizado e Usar um modelo Whisper.
`profanityFilterMode`	Especifica como lidar com palavrões em resultados de reconhecimento. Os valores aceites são `None` desativar a filtragem de palavrões, `Masked` substituir palavrões por asteriscos, `Removed` remover todos os palavrões do resultado ou `Tags` adicionar etiquetas de palavrões. O valor predefinido é `Masked`.
`punctuationMode`	Especifica como lidar com a pontuação nos resultados de reconhecimento. Os valores aceites são `None` desativar a pontuação, `Dictated` implicar pontuação explícita (falada), `Automatic` deixar o descodificador lidar com a pontuação ou `DictatedAndAutomatic` utilizar pontuação ditada e automática. O valor predefinido é `DictatedAndAutomatic`. Esta propriedade não é aplicável a modelos Whisper.
`timeToLive`	Uma duração após a criação do trabalho de transcrição, quando os resultados da transcrição serão excluídos automaticamente. O valor é uma duração codificada pela ISO 8601. Por exemplo, especifique `PT12H` para 12 horas. Como alternativa, você pode ligar para Transcriptions_Delete regularmente depois de recuperar os resultados da transcrição.
`wordLevelTimestampsEnabled`	Especifica se carimbos de data/hora no nível da palavra devem ser incluídos na saída. O valor predefinido é `false`. Esta propriedade não é aplicável a modelos Whisper. Whisper é um modelo somente de exibição, portanto, o campo lexical não é preenchido na transcrição.

Para obter ajuda da CLI de fala com as opções de configuração de transcrição, execute o seguinte comando:

spx help batch transcription create advanced

Usar um modelo personalizado

A transcrição em lote usa o modelo base padrão para a localidade especificada. Não é necessário definir nenhuma propriedade para usar o modelo base padrão.

Opcionalmente, você pode modificar o exemplo de transcrição de criação anterior definindo a model propriedade para usar um modelo base específico ou um 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 de nível self superior no corpo da resposta é o URI do modelo. Você pode recuperar o local do modelo ao criar ou obter um modelo. Para obter mais informações, consulte o exemplo de resposta JSON em Criar um modelo.

Gorjeta

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

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

Use um modelo Whisper

O Azure AI Speech dá suporte ao modelo Whisper da OpenAI usando a API de transcrição em lote. Você pode usar o modelo Whisper para transcrição em lote.

Nota

O Serviço OpenAI do Azure também suporta o modelo Whisper da OpenAI para conversão de voz em texto com uma API REST síncrona. Para saber mais, consulte Fala em texto com o modelo Azure OpenAI Whisper. Para obter mais informações sobre quando usar o Azure AI Speech vs. Azure OpenAI Service, consulte O que é o modelo Whisper?

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

Importante

Para modelos Whisper, você deve sempre usar a versão 3.2 da API de fala para texto.

Os modelos de sussurro por transcrição em lote são suportados nas regiões Leste da Austrália, Centro dos EUA, Leste dos EUA, Centro-Norte dos EUA, Centro-Sul dos EUA, Sudeste Asiático e Europa Ocidental.

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

Faça uma solicitação HTTP GET como mostrado no exemplo a seguir para a eastus região. Substitua YourSubscriptionKey pela chave de recurso de fala. Substitua eastus se 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 modelos básicos mais antigos são retornados. Use os skip parâmetros e top consulta para percorrer os resultados. Por exemplo, a solicitação a seguir retorna os próximos 100 modelos básicos 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 definir as variáveis de configuração para um recurso de fala em uma das regiões suportadas. Você pode executar o spx csr list --base comando para obter modelos base disponíveis para todas as localidades.

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

A displayName propriedade de um modelo Whisper contém "Whisper", conforme mostrado neste exemplo. Whisper é um modelo somente de exibição, portanto, o campo lexical 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 como mostrado neste exemplo para a eastus região. Substitua YourSubscriptionKey pela chave de recurso de fala. Substitua eastus se 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. Se você não especificar um contêiner, o serviço de Fala armazenará os resultados em um contêiner gerenciado pela Microsoft. Nesse caso, quando o trabalho de transcrição é excluído, os dados do 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 Blob do Azure gravável usando a opção destinationContainerUrl na solicitação de criação de transcrição em lote. Esta opção utiliza apenas um URI SAS ad hoc e não suporta o mecanismo de segurança de serviços fidedignos do Azure. Esta opção também não suporta SAS baseada em política de acesso. O recurso de conta de armazenamento do contêiner de destino deve permitir todo o tráfego externo.

Se você quiser armazenar os resultados da transcrição em um contêiner de armazenamento de Blob do Azure usando o mecanismo de segurança de serviços confiáveis do Azure, considere usar o BYOS (traga seu próprio armazenamento). Para obter mais informações, consulte Usar o recurso de fala Bring your own storage (BYOS) para conversão de fala em texto.