Creare una trascrizione batch

Articolo
09/12/2024

Con le trascrizioni batch, si inviano dati audio in un batch. Il servizio trascrive i dati audio e archivia i risultati in un contenitore di archiviazione. È quindi possibile recuperare i risultati dal contenitore di archiviazione.

Importante

I nuovi prezzi sono validi per la trascrizione batch tramite l'API REST Riconoscimento vocale v3.2. Per altre informazioni, vedere la guida ai prezzi.

Prerequisiti

È necessaria una risorsa Voce standard (S0). Le risorse gratuite (F0) non sono supportate.

Creare un processo di trascrizione

Per creare un processo di trascrizione batch, usare l'operazione Transcriptions_Create dell'API REST di riconoscimento vocale. Creare il corpo della richiesta in base alle istruzioni seguenti:

È necessario impostare la proprietà contentContainerUrl o contentUrls. Per altre informazioni su Archiviazione BLOB di Azure per la trascrizione batch, vedere Individuare i file audio per la trascrizione batch.
Impostare la proprietà locale obbligatoria. Questo valore deve corrispondere alle impostazioni locali previste dei dati audio da trascrivere. Non è possibile modificare le impostazioni locali in un secondo momento.
Impostare la proprietà displayName obbligatoria. Scegliere un nome per la trascrizione a cui è possibile fare riferimento in un secondo momento. Il nome della trascrizione non deve essere univoco e può essere modificato in un secondo momento.
Facoltativamente, per usare un modello diverso dal modello di base, impostare la proprietà model sull'ID modello. Per altre informazioni, vedere Usare un modello personalizzato e Usare un modello Whisper.
Facoltativamente, impostare la proprietà wordLevelTimestampsEnabled su true per abilitare i timestamp a livello di parola nei risultati della trascrizione. Il valore predefinito è false. Per i modelli Whisper, impostare invece la proprietà displayFormWordLevelTimestampsEnabled. Whisper è un modello di sola visualizzazione, quindi il campo lessicale non viene popolato nella trascrizione.
Facoltativamente, impostare la proprietà languageIdentification. L'identificazione della lingua viene usata per identificare le lingue parlate nell'audio rispetto a un elenco di lingue supportate. Se si imposta la proprietà languageIdentification, è necessario impostare anche languageIdentification.candidateLocales con le impostazioni locali candidate.

Per altre informazioni, vedere Opzioni di configurazione delle richieste.

Effettuare una richiesta HTTP POST che usi l'URI come illustrato nell'esempio Transcriptions_Create seguente.

Sostituire YourSubscriptionKey con la chiave della risorsa Voce.
Sostituire YourServiceRegion con l'area della risorsa Voce.
Impostare le proprietà del corpo della richiesta come descritto in precedenza.

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.2/transcriptions"

Dovrebbe essere visualizzato un corpo della risposta nel formato seguente:

{
  "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/db474955-ab85-4c6c-ba6e-3bfe63d041ba",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/5988d691-0893-472c-851e-8e36a0fe7aaf"
  },
  "links": {
    "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/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": "2024-05-21T14:18:06Z",
  "status": "NotStarted",
  "createdDateTime": "2024-05-21T14:18:06Z",
  "locale": "en-US",
  "displayName": "My Transcription"
}

La proprietà self di primo livello nel corpo della risposta è l'URI della trascrizione. Usare questo URI per ottenere dettagli, ad esempio l'URI dei file delle trascrizioni e dei report di trascrizione. È anche possibile usare questo URI per aggiornare o eliminare una trascrizione.

È possibile eseguire una query sullo stato delle trascrizioni con l'operazione Transcriptions_Get.

Chiamare Transcriptions_Delete regolarmente dal servizio dopo aver recuperato i risultati. In alternativa, impostare la proprietà timeToLive per garantire l'eliminazione finale dei risultati.

Suggerimento

È anche possibile provare l'API di trascrizione batch usando Python, C# o Node.js in GitHub.

Per creare una trascrizione, usare il comando spx batch transcription create. Creare i parametri della richiesta in base alle istruzioni seguenti:

Impostare il parametro content obbligatorio. È possibile specificare un elenco delimitato da virgole di singoli file o l'URL per un intero contenitore. Per altre informazioni su Archiviazione BLOB di Azure per la trascrizione batch, vedere Individuare i file audio per la trascrizione batch.
Impostare la proprietà language obbligatoria. Questo valore deve corrispondere alle impostazioni locali previste dei dati audio da trascrivere. Non è possibile modificare le impostazioni locali in un secondo momento. Il parametro language dell'interfaccia della riga di comando di Voce corrisponde alla proprietà locale nella richiesta e nella risposta JSON.
Impostare la proprietà name obbligatoria. Scegliere un nome per la trascrizione a cui è possibile fare riferimento in un secondo momento. Il nome della trascrizione non deve essere univoco e può essere modificato in un secondo momento. Il parametro name dell'interfaccia della riga di comando di Voce corrisponde alla proprietà displayName nella richiesta e nella risposta JSON.

Ecco un esempio di comando dell'interfaccia della riga di comando di Voce che crea un processo di trascrizione:

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

Dovrebbe essere visualizzato un corpo della risposta nel formato seguente:

{
  "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/7f4232d5-9873-47a7-a6f7-4a3f00d00dc0",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/5988d691-0893-472c-851e-8e36a0fe7aaf"
  },
  "links": {
    "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/7f4232d5-9873-47a7-a6f7-4a3f00d00dc0/files"
  },
  "properties": {
    "diarizationEnabled": false,
    "wordLevelTimestampsEnabled": false,
    "channels": [
      0,
      1
    ],
    "punctuationMode": "DictatedAndAutomatic",
    "profanityFilterMode": "Masked"
  },
  "lastActionDateTime": "2024-05-21T14:21:59Z",
  "status": "NotStarted",
  "createdDateTime": "2024-05-21T14:21:59Z",
  "locale": "en-US",
  "displayName": "My Transcription",
  "description": ""
}

Per visualizzare le informazioni della Guida dell'interfaccia della riga di comando di Voce per le trascrizioni, eseguire il comando seguente:

spx help batch transcription

Opzioni di configurazione delle richieste

Ecco alcune opzioni di proprietà che è possibile usare per configurare una trascrizione quando si chiama l'operazione Transcriptions_Create. Nella stessa pagina è possibile trovare anche altri esempi, ad esempio per la creazione di una trascrizione con identificazione della lingua.

Proprietà	Descrizione
`channels`	Matrice di numeri di canale da elaborare. I canali `0` e `1` vengono trascritti per impostazione predefinita.
`contentContainerUrl`	È possibile inviare singoli file audio o un intero contenitore di archiviazione. È necessario specificare la posizione dei dati audio usando la proprietà `contentContainerUrl` o `contentUrls`. Per altre informazioni su Archiviazione BLOB di Azure per la trascrizione batch, vedere Individuare i file audio per la trascrizione batch. Questa proprietà non viene restituita nella risposta.
`contentUrls`	È possibile inviare singoli file audio o un intero contenitore di archiviazione. È necessario specificare la posizione dei dati audio usando la proprietà `contentContainerUrl` o `contentUrls`. Per altre informazioni, vedere Individuare i file audio per la trascrizione batch. Questa proprietà non viene restituita nella risposta.
`destinationContainerUrl`	Il risultato può essere archiviato in un contenitore di Azure. Se non si specifica un contenitore, il servizio Voce archivia i risultati in un contenitore gestito da Microsoft. Quando il processo di trascrizione viene eliminato, vengono eliminati anche i dati dei risultati della trascrizione. Per altre informazioni, ad esempio gli scenari di sicurezza supportati, vedere Specificare un URL del contenitore di destinazione.
`diarization`	Indica che il servizio Voce deve tentare l'analisi della diarizzazione sull'input, che dovrebbe essere un canale mono che contiene più voci. La funzionalità non è disponibile con le registrazioni stereo. La diarizzazione è il processo di separazione dei parlanti nei dati audio. La pipeline batch può riconoscere e separare più parlanti nelle registrazioni dei canali mono. Specificare il numero minimo e massimo di persone che potrebbero parlare. È anche necessario impostare la proprietà `diarizationEnabled` su `true`. Il file di trascrizione contiene una voce `speaker` per ogni frase trascritta. È necessario usare questa proprietà quando sono previsti tre o più parlanti. Per due parlanti, impostare la proprietà `diarizationEnabled` su `true` è sufficiente. Per un esempio di utilizzo delle proprietà, vedere Transcriptions_Create. Il numero massimo di parlanti per la diarizzazione deve essere minore di 36 e maggiore o uguale alla proprietà `minCount`. Per un esempio, vedere Transcriptions_Create. Quando questa proprietà è selezionata, la lunghezza dell'audio di origine non può superare i 240 minuti per ogni file. Nota: questa proprietà è disponibile solo con l'API REST Riconoscimento vocale versione 3.1 e successive. Se si imposta questa proprietà con qualsiasi versione precedente, ad esempio la versione 3.0, viene ignorata e vengono identificati solo due parlanti.
`diarizationEnabled`	Specifica che il servizio Voce deve tentare l'analisi della diarizzazione sull'input, che dovrebbe essere un canale mono che contiene più voci. Il valore predefinito è `false`. Per tre o più voci è necessario usare anche la proprietà `diarization`. Usare solo con l'API REST Riconoscimento vocale versione 3.1 e successive. Quando questa proprietà è selezionata, la lunghezza dell'audio di origine non può superare i 240 minuti per ogni file.
`displayName`	Nome della trascrizione batch. Scegliere un nome a cui è possibile fare riferimento in un secondo momento. Non è necessario che il nome visualizzato sia univoco. Questa proprietà è obbligatoria.
`displayFormWordLevelTimestampsEnabled`	Specifica se includere timestamp a livello di parola nella forma visualizzata dei risultati della trascrizione. I risultati vengono restituiti nella proprietà `displayWords` del file di trascrizione. Il valore predefinito è `false`. Nota: questa proprietà è disponibile solo con l'API REST Riconoscimento vocale versione 3.1 e successive.
`languageIdentification`	L'identificazione della lingua viene usata per identificare le lingue parlate nell'audio rispetto a un elenco di lingue supportate. Se si imposta la proprietà `languageIdentification`, è necessario impostare anche la proprietà `candidateLocales` correlata.
`languageIdentification.candidateLocales`	Impostazioni locali candidate per l'identificazione della lingua, ad esempio `"properties": { "languageIdentification": { "candidateLocales": ["en-US", "de-DE", "es-ES"]}}`. Sono supportate un minimo due e un massimo di dieci impostazioni locali candidate, incluse le impostazioni locali principali per la trascrizione.
`locale`	Impostazioni locali della trascrizione batch. Questo valore deve corrispondere alle impostazioni locali previste dei dati audio da trascrivere. Le impostazioni locali non possono essere modificate in un secondo momento. Questa proprietà è obbligatoria.
`model`	È possibile impostare la proprietà `model` per usare un modello di base specifico o un modello di riconoscimento vocale personalizzato. Se non si specifica `model`, viene usato il modello di base predefinito per le impostazioni locali. Per altre informazioni, vedere Usare un modello personalizzato e Usare un modello Whisper.
`profanityFilterMode`	Specifica come gestire il linguaggio volgare nei risultati del riconoscimento. I valori accettati sono `None` per disabilitare i filtri del contenuto volgare, `Masked` per sostituire il contenuto volgare con asterischi, `Removed` per rimuovere tutto il contenuto volgare dal risultato o `Tags` per aggiungere i tag per il contenuto volgare. Il valore predefinito è `Masked`.
`punctuationMode`	Specifica come gestire la punteggiatura nei risultati del riconoscimento. I valori accettati sono `None` per disabilitare la punteggiatura, `Dictated` per implicare la punteggiatura esplicita (pronunciata), `Automatic` per consentire al decodificatore di gestire la punteggiatura o `DictatedAndAutomatic` per usare la punteggiatura dettata e automatica. Il valore predefinito è `DictatedAndAutomatic`. Questa proprietà non è applicabile ai modelli Whisper.
`timeToLive`	Periodo di tempo dopo la creazione del processo di trascrizione al termine del quale i risultati della trascrizione verranno eliminati automaticamente. Il valore è una durata con codifica ISO 8601. Ad esempio, specificare `PT12H` per 12 ore. In alternativa, è possibile chiamare Transcriptions_Delete regolarmente dopo aver recuperato i risultati della trascrizione.
`wordLevelTimestampsEnabled`	Specifica se i timestamp a livello di parola devono essere inclusi nell'output. Il valore predefinito è `false`. Questa proprietà non è applicabile ai modelli Whisper. Whisper è un modello di sola visualizzazione, quindi il campo lessicale non viene popolato nella trascrizione.

Per visualizzare le informazioni della Guida dell'interfaccia della riga di comando di Voce per le opzioni di configurazione della trascrizione, eseguire il comando seguente:

spx help batch transcription create advanced

Usare un modello personalizzato

La trascrizione batch usa il modello di base predefinito per le impostazioni locali specificate. Non è necessario impostare proprietà per usare il modello di base predefinito.

Facoltativamente, è possibile modificare il precedente esempio di creazione della trascrizione impostando la proprietà model in modo da usare un modello di base specifico o un modello di riconoscimento vocale personalizzato.

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/models/base/5988d691-0893-472c-851e-8e36a0fe7aaf"
  },
  "properties": {
    "wordLevelTimestampsEnabled": true,
  },
}'  "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.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/models/base/5988d691-0893-472c-851e-8e36a0fe7aaf"

Per usare un modello di riconoscimento vocale personalizzato per la trascrizione batch, è necessario l'URI del modello. La proprietà di primo livello self nel corpo della risposta è l'URI del modello. È possibile recuperare la posizione del modello quando si crea o si ottiene un modello. Per altre informazioni, vedere l'esempio di risposta JSON in Creare un modello.

Suggerimento

Per usare la conversione voce/testo personalizzata con il servizio di trascrizione batch non è necessario un endpoint di distribuzione ospitata. È possibile risparmiare risorse se il modello di riconoscimento vocale personalizzato viene usato solo per la trascrizione batch.

Le richieste di trascrizione batch per i modelli scaduti avranno esito negativo con un errore 4xx. Impostare la proprietà model su un modello di base o un modello personalizzato ancora non scaduto. In caso contrario, non includere la proprietà model per usare sempre il modello di base più recente. Per altre informazioni, vedere Scegliere un modello e Ciclo di vita del modello di riconoscimento vocale personalizzato.

Usare un modello Whisper

Voce di Azure AI supporta il modello Whisper di OpenAI tramite l'API di trascrizione batch. È possibile usare il modello Whisper per la trascrizione batch.

Nota

Servizio OpenAI di Azure supporta anche il modello Whisper di OpenAI per il riconoscimento vocale con API REST sincrona. Per altre informazioni, vedere Riconoscimento vocale con il modello Whisper di Azure OpenAI. Per altre informazioni su quando usare Voce di Azure AI e quando il Servizio OpenAI di Azure, vedere Che cos'è il modello Whisper?

Per usare un modello Whisper per la trascrizione batch, è necessario impostare la proprietà model. Whisper è un modello di sola visualizzazione, quindi il campo lessicale non viene popolato nella risposta.

Importante

Per i modelli Whisper è consigliabile usare sempre la versione 3.2 dell'API Riconoscimento vocale.

La trascrizione batch con modelli Whisper è supportata nelle aree Australia orientale, Stati Uniti centrali, Stati Uniti orientali, Stati Uniti centro-settentrionali, Stati Uniti centro-meridionali, Asia sud-orientale ed Europa occidentale.

È possibile effettuare una richiesta Models_ListBaseModels per ottenere i modelli di base disponibili per tutte le impostazioni locali.

Effettuare una richiesta HTTP GET come illustrato nell'esempio seguente per l'area eastus. Sostituire YourSubscriptionKey con la chiave della risorsa Voce. Sostituire eastus se si usa un'area diversa.

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

Per impostazione predefinita vengono restituiti solo i 100 modelli di base meno recenti. Usare i parametri di query skip e top per scorrere i risultati. Ad esempio, la richiesta seguente restituisce i 100 modelli di base successivi dopo i primi 100.

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

Assicurarsi di impostare le variabili di configurazione per una risorsa Voce in una delle aree supportate. È possibile eseguire il comando spx csr list --base per ottenere i modelli di base disponibili per tutte le impostazioni locali.

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

La proprietà displayName di un modello Whisper contiene "Whisper", come illustrato in questo esempio. Whisper è un modello di sola visualizzazione, quindi il campo lessicale non viene popolato nella trascrizione.

{
  "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/e418c4a9-9937-4db7-b2c9-8afbff72d950",
  "links": {
    "manifest": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.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)"
},

Impostare l'URI completo del modello, come illustrato in questo esempio per l'area eastus. Sostituire YourSubscriptionKey con la chiave della risorsa Voce. Sostituire eastus se si usa un'area diversa.

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/models/base/e418c4a9-9937-4db7-b2c9-8afbff72d950"
  },
  "properties": {
    "wordLevelTimestampsEnabled": true,
  },
}'  "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions"

Impostare l'URI completo del modello, come illustrato in questo esempio per l'area eastus. Sostituire eastus se si usa un'area diversa.

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/models/base/e418c4a9-9937-4db7-b2c9-8afbff72d950" --api-version v3.2

Specificare un URL del contenitore di destinazione

Il risultato della trascrizione essere archiviato in un contenitore di Azure. Se non si specifica un contenitore, il servizio Voce archivia i risultati in un contenitore gestito da Microsoft. In tal caso, quando il processo di trascrizione viene eliminato, vengono eliminati anche i dati dei risultati della trascrizione.

È possibile archiviare i risultati di una trascrizione batch in un contenitore di Archiviazione BLOB di Azure scrivibile usando l'opzione destinationContainerUrl nella richiesta di creazione della trascrizione batch. Questa opzione usa solo un URI di firma di accesso condiviso ad hoc e non supporta il meccanismo di sicurezza dei servizi di Azure attendibili. Questa opzione non supporta inoltre la firma di accesso condiviso basata su criteri di accesso. La risorsa dell'account di archiviazione del contenitore di destinazione deve consentire tutto il traffico esterno.

Se si vogliono archiviare i risultati della trascrizione in un contenitore di Archiviazione BLOB di Azure tramite il meccanismo di sicurezza dei servizi di Azure attendibili, prendere in considerazione l'uso di BYOS (Bring Your Own Storage). Per altre informazioni, vedere Usare la risorsa Voce BYOS (Bring Your Own Storage) per il riconoscimento vocale.

Condividi tramite

Creare una trascrizione batch

Prerequisiti

Creare un processo di trascrizione

Opzioni di configurazione delle richieste

Usare un modello personalizzato

Usare un modello Whisper

Specificare un URL del contenitore di destinazione

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Creare una trascrizione batch

Prerequisiti

Creare un processo di trascrizione

Opzioni di configurazione delle richieste

Usare un modello personalizzato

Usare un modello Whisper

Specificare un URL del contenitore di destinazione

Contenuto correlato

Commenti e suggerimenti

Risorse aggiuntive