Creare una trascrizione batch

Articolo
04/15/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 effettivi per la trascrizione batch usando l'API REST Riconoscimento vocale v3.2. Per altre informazioni, vedere la guida ai prezzi.

Prerequisiti

Speech SDK installato.
Una risorsa voce standard (S0). Le risorse gratuite (F0) non sono supportate.

Creare un processo di trascrizione

Per creare una trascrizione, usare l'operazione Transcriptions_Create dell'API REST Riconoscimento vocale. Costruire il corpo della richiesta in base alle istruzioni seguenti:

È necessario impostare la contentContainerUrl proprietà o contentUrls . Per altre informazioni sull'archiviazione BLOB di Azure per la trascrizione batch, vedere Individuare i file audio per la trascrizione batch.
Impostare la proprietà obbligatoria locale . 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à obbligatoria displayName . Scegliere un nome di 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 model proprietà sull'ID modello. Per altre informazioni, vedere Usare un modello personalizzato e Usare un modello Whisper.
Facoltativamente, impostare la wordLevelTimestampsEnabled proprietà 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 displayFormWordLevelTimestampsEnabled proprietà . Whisper è un modello di sola visualizzazione, quindi il campo lessicale non viene popolato nella trascrizione.
Facoltativamente, impostare la languageIdentification proprietà . L'identificazione della lingua viene usata per identificare le lingue parlate nell'audio rispetto a un elenco di lingue supportate. Se si imposta la languageIdentification proprietà , è necessario impostare languageIdentification.candidateLocales anche con le impostazioni locali candidate.

Per altre informazioni, vedere Richiedere le opzioni di configurazione.

Effettuare una richiesta HTTP POST che usa l'URI come illustrato nell'esempio di 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.1/transcriptions"

Dovrebbe essere visualizzato un corpo della risposta nel formato seguente:

{
  "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 proprietà di primo livello self nel corpo della risposta è l'URI della trascrizione. Usare questo URI per ottenere dettagli quali l'URI delle trascrizioni e i file di 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 di Transcriptions_Get .

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

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

Impostare il parametro obbligatorio content . È possibile specificare un elenco delimitato da punti e virgola di singoli file o l'URL per un intero contenitore. Per altre informazioni sull'archiviazione BLOB di Azure per la trascrizione batch, vedere Individuare i file audio per la trascrizione batch.
Impostare la proprietà obbligatoria language . 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 dell'interfaccia della locale riga di comando language di Voce corrisponde alla proprietà nella richiesta e nella risposta JSON.
Impostare la proprietà obbligatoria name . Scegliere un nome di 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 dell'interfaccia della displayName riga di comando name di Voce corrisponde alla proprietà 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.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": ""
}

Per la guida dell'interfaccia della riga di comando di Voce con le trascrizioni, eseguire il comando seguente:

spx help batch transcription

Opzioni di configurazione della richiesta

Ecco alcune opzioni di proprietà che è possibile usare per configurare una trascrizione quando si chiama l'operazione di Transcriptions_Create .

Proprietà	Descrizione
`channels`	Matrice di numeri di canale da elaborare. Canali `0` e `1` sono 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 `contentContainerUrl` proprietà o `contentUrls` . Per altre informazioni sull'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 `contentContainerUrl` proprietà 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 degli altoparlanti nei dati audio. La pipeline batch può riconoscere e separare più altoparlanti nelle registrazioni dei canali mono. Specificare il numero minimo e massimo di persone che potrebbero parlare. È inoltre necessario impostare la `diarizationEnabled` proprietà su `true`. Il file di trascrizione contiene una `speaker` voce per ogni frase trascritta. È necessario usare questa proprietà quando ci si aspetta tre o più altoparlanti. Per due altoparlanti, l'impostazione della `diarizationEnabled` proprietà su `true` è sufficiente. Per un esempio di utilizzo delle proprietà, vedere Transcriptions_Create. Il numero massimo di altoparlanti per la diarizzazione deve essere minore di 36 e maggiore o uguale alla `minSpeakers` proprietà . Per un esempio, vedere Transcriptions_Create. Quando questa proprietà è selezionata, la lunghezza 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 altoparlanti.
`diarizationEnabled`	Specifica che il servizio Voce deve tentare l'analisi della diarizzazione sull'input, che dovrebbe essere un canale mono che contiene due 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 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. Il nome visualizzato non deve essere univoco. Questa proprietà è obbligatoria.
`displayFormWordLevelTimestampsEnabled`	Specifica se includere timestamp a livello di parola nella forma di visualizzazione dei risultati della trascrizione. I risultati vengono restituiti nella `displayWords` proprietà 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 `languageIdentification` proprietà , è necessario impostarne anche la proprietà racchiusa `candidateLocales` .
`languageIdentification.candidateLocales`	Impostazioni locali candidate per l'identificazione della lingua, ad esempio `"properties": { "languageIdentification": { "candidateLocales": ["en-US", "de-DE", "es-ES"]}}`. È supportato almeno 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 `model` proprietà 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 riguardano `None` la disabilitazione del filtro delle espressioni volgari, `Masked` per sostituire il contenuto volgare con asterischi, `Removed` per rimuovere tutte le espressioni volgari dal risultato o `Tags` per aggiungere tag di volgarità. Il valore predefinito è `Masked`.
`punctuationMode`	Specifica come gestire la punteggiatura nei risultati del riconoscimento. I valori accettati consentono `None` di disabilitare la punteggiatura, `Dictated` di implicare la punteggiatura `Automatic` esplicita (pronunciata), di consentire al decodificatore di gestire la punteggiatura o `DictatedAndAutomatic` di usare punteggiatura dettata e automatica. Il valore predefinito è `DictatedAndAutomatic`. Questa proprietà non è applicabile ai modelli Whisper.
`timeToLive`	Durata dopo la creazione del processo di trascrizione, quando 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 regolarmente Transcriptions_Delete 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 informazioni sull'interfaccia della riga di comando di Voce con 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 l'esempio di trascrizione di creazione precedente impostando la model proprietà per 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.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"

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

Un endpoint di distribuzione ospitato non è necessario per usare il riconoscimento vocale personalizzato con il servizio di trascrizione batch. È possibile risparmiare risorse se si usa il modello di riconoscimento vocale personalizzato solo per la trascrizione batch.

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

Usare un modello Whisper

Riconoscimento vocale di Azure per intelligenza artificiale supporta il modello Whisper di OpenAI usando l'API di trascrizione batch. È possibile usare il modello Whisper per la trascrizione batch.

Nota

Il servizio OpenAI di Azure supporta anche il modello Whisper di OpenAI per la sintesi vocale con un'API REST sincrona. Per altre informazioni, vedere Riconoscimento vocale con il modello Azure OpenAI Whisper. Per altre informazioni su quando usare Il servizio Voce di Intelligenza artificiale di Azure e Il servizio OpenAI di Azure, vedere Che cos'è il modello Whisper?

Per usare un modello Whisper per la trascrizione batch, è necessario impostare la model proprietà . 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 per il testo.

I modelli Sussurra per trascrizione batch sono supportati 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 di Models_ListBaseModels per ottenere 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-preview.2/models/base" -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey"

Per impostazione predefinita, vengono restituiti solo i 100 modelli di base meno recenti. Usare i skip parametri di query 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-preview.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 spx csr list --base comando per ottenere i modelli di base disponibili per tutte le impostazioni locali.

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

La displayName proprietà 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-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)"
},

Impostare l'URI del modello completo, 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-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

Specificare un URL del contenitore di destinazione

Il risultato della trascrizione 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. 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 anche la firma di accesso condiviso basata su criteri di accesso. La risorsa account Archiviazione del contenitore di destinazione deve consentire tutto il traffico esterno.

Se si vuole archiviare i risultati della trascrizione in un contenitore di archiviazione BLOB di Azure usando il meccanismo di sicurezza dei servizi di Azure attendibili, è consigliabile usare Bring-your-own-storage (BYOS). Per altre informazioni, vedere Usare la risorsa Bring Your Own Storage (BYOS) Speech per il riconoscimento vocale.