Eseguire la migrazione del codice dalla versione 3.0 alla versione 3.1 dell'API REST

  • Articolo

L'API REST Riconoscimento vocale viene usata per trascrizione rapida, trascrizione batch e riconoscimento vocale personalizzato. Le modifiche dalla versione 3.0 alla 3.1 sono descritte nelle sezioni seguenti.

Importante

La versione 2024-11-15 dell'API REST riconoscimento vocale è la versione più recente disponibile a livello generale.

  • La versione 2024-05-15-preview dell'API REST riconoscimento vocale verrà ritirata in una data da annunciare.
  • L'API v3.0REST riconoscimento vocale, , v3.1v3.2, 3.2-preview.1e 3.2-preview.2 verrà ritirata il 1° aprile 2026.

Per altre informazioni sull'aggiornamento, vedere Le guide alla migrazione dell'API REST Riconoscimento vocale v3.0 alla versione 3.1, dalla versione 3.1 alla versione 3.2 e dalla versione 3.2 alla versione 2024-11-15.

Percorso base

È necessario aggiornare il percorso di base nel codice da /speechtotext/v3.0 a /speechtotext/v3.1. Ad esempio, per ottenere modelli di base nell'area eastus, usare https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base anziché https://eastus.api.cognitive.microsoft.com/speechtotext/v3.0/models/base.

Si notino queste altre modifiche:

  • L'operazione /models/{id}/copyto (include '/') nella versione 3.0 viene sostituita dall'operazione /models/{id}:copyto (include ':') nella versione 3.1.
  • L'operazione /webhooks/{id}/ping (include “/”) nella versione 3.0 viene sostituita dall'operazione di /webhooks/{id}:ping (include “:”) nella versione 3.1.
  • L'operazione /webhooks/{id}/test (include '/') nella versione 3.0 viene sostituita dall'operazione /webhooks/{id}:test (include ':') nella versione 3.1.

Per altre informazioni, vedere ID operazione più avanti in questa guida.

Trascrizione batch

Nota

Non usare REST API di riconoscimento vocale v3.0 per recuperare una trascrizione creata tramite l'API REST di Riconoscimento vocale nel v3.1. Verrà visualizzato un messaggio di errore simile al seguente: "La versione dell'API non può essere usata per accedere a questa trascrizione. Usare l'API versione 3.1 o successiva".

Nell'operazione Transcriptions_Create vengono aggiunte le tre proprietà seguenti:

  • La proprietà displayFormWordLevelTimestampsEnabled può essere utilizzata per abilitare la creazione di report di timestamp a livello di parola in forma di visualizzazione dei risultati della trascrizione. I risultati vengono restituiti nella proprietà displayWords del file di trascrizione.
  • La proprietà diarization può essere usata per specificare i suggerimenti per il numero minimo e massimo di etichette di altoparlante da generare quando si esegue la diarizzazione facoltativa (separazione altoparlante). Con questa funzionalità, il servizio è ora in grado di generare etichette voce per più di due altoparlanti. Per utilizzare questa proprietà, è necessario impostare anche la proprietà diarizationEnabled su true. Con l'API v3.1 è stato aumentato il numero di altoparlanti che possono essere identificati tramite la diarizzazione dai due altoparlanti supportati dall'API v3.0. È consigliabile mantenere il numero di altoparlanti inferiore a 30 per ottenere prestazioni migliori.
  • La proprietà languageIdentification può essere usata per specificare le impostazioni per l'identificazione della lingua nell'input prima della trascrizione. Per l'identificazione della lingua sono supportate fino a 10 impostazioni locali candidate. La trascrizione restituita include una nuova proprietà locale per la lingua riconosciuta o le impostazioni locali specificate.

La proprietà filter viene aggiunta alle operazioni Transcriptions_List, Transcriptions_ListFiles e Projects_ListTranscriptions. L'espressione filter può essere usata per selezionare un subset delle risorse disponibili. È possibile filtrare in base a displayName, description, createdDateTime, lastActionDateTime, status e locale. Ad esempio: filter=createdDateTime gt 2022-02-01T11:00:00Z

Se si usa webhook per ricevere notifiche sullo stato di trascrizione, tenere presente che i webhook creati tramite l'API V3.0 non possono ricevere notifiche per le richieste di trascrizione V3.1. È necessario creare un nuovo endpoint webhook tramite l'API V3.1 per ricevere notifiche per le richieste di trascrizione V3.1.

Riconoscimento vocale personalizzato

Set di dati

Vengono aggiunte le operazioni seguenti per il caricamento e la gestione di più blocchi di dati per un set di dati:

  • Datasets_UploadBlock: caricare un blocco di dati per il set di dati. La dimensione massima del blocco è 8MiB.
  • Datasets_GetBlocks: ottenere l'elenco dei blocchi caricati per questo set di dati.
  • Datasets_CommitBlocks: eseguire il commit dell’elenco elementi bloccati per completare il caricamento del set di dati.

Per supportare l'adattamento del modello con testo strutturato nei dati markdown, l'operazione Datasets_Create supporta ora il tipo di dati LanguageMarkdown. Per altre informazioni, vedere caricare set di dati.

Modelli

Le operazioni Models_ListBaseModels e Models_GetBaseModel restituiscono informazioni sul tipo di adattamento supportato da ogni modello di base.

"features": {
    "supportsAdaptationsWith": [
        "Acoustic",
        "Language",
        "LanguageMarkdown",
        "Pronunciation"
    ]
}

L'operazione Models_Create include una nuova proprietà customModelWeightPercent in cui è possibile specificare il peso usato quando il modello linguistico personalizzato, sottoposto a training da dati di testo semplice o strutturato, viene combinato con il modello linguistico di base. I valori validi sono numeri interi compresi tra 1 e 100. Il valore predefinito è attualmente 30.

La proprietà filter viene aggiunta alle operazioni seguenti:

L'espressione filter può essere usata per selezionare un subset delle risorse disponibili. È possibile filtrare in base a displayName, description, createdDateTime, lastActionDateTime, status, locale e kind. Ad esempio: filter=locale eq 'en-US'

Operazione Models_ListFiles aggiunta per ottenere i file del modello identificato dall'ID specificato.

Operazione Models_GetFile aggiunta per ottenere un file specifico, identificato con fileId, da un modello, identificato con ID. In questo modo è possibile recuperare un file ModelReport che fornisce informazioni sui dati elaborati durante il training.

ID operazione

È necessario aggiornare il percorso di base nel codice da /speechtotext/v3.0 a /speechtotext/v3.1. Ad esempio, per ottenere modelli di base nell'area eastus, usare https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base anziché https://eastus.api.cognitive.microsoft.com/speechtotext/v3.0/models/base.

Il nome di ogni operationId nella versione 3.1 è preceduto dal nome dell'oggetto. Ad esempio, operationId per “Crea modello” è stato modificato da CreateModel nella versione 3.0 a Models_Create nella versione 3.1.

L'operazione /models/{id}/copyto (include '/') nella versione 3.0 viene sostituita dall'operazione /models/{id}:copyto (include ':') nella versione 3.1.

L'operazione /webhooks/{id}/ping (include “/”) nella versione 3.0 viene sostituita dall'operazione di /webhooks/{id}:ping (include “:”) nella versione 3.1.

L'operazione /webhooks/{id}/test (include '/') nella versione 3.0 viene sostituita dall'operazione /webhooks/{id}:test (include ':') nella versione 3.1.

Passaggi successivi