Avvio rapido: Introduzione all'interfaccia della riga di comando di Voce di Azure AI

In questo articolo si apprende come usare l'interfaccia della riga di comando di Voce di Azure AI per accedere a servizi Voce quali riconoscimento vocale, sintesi vocale e traduzione vocale, senza dover scrivere codice. L'interfaccia della riga di comando per Voce è pronta per la produzione ed è possibile usarla per automatizzare flussi di lavoro semplici nel servizio Voce, usando .bat o script della shell.

Questo articolo presuppone che si abbia una conoscenza operativa della finestra del prompt dei comandi, del terminale o di PowerShell.

Nota

In PowerShell, il token stop-parsing (--%) deve seguire spx. Ad esempio, eseguire spx --% config @region per visualizzare il valore di configurazione dell'area corrente.

Scaricare e installare

Windows

Per installare l’interfaccia della riga di comando di Voce su Windows, seguire questa procedura:

1. Installare Microsoft Visual C++ Redistributable per Visual Studio 2019 per la piattaforma in uso. La prima installazione potrebbe richiedere un riavvio.

2. Installare .NET 6.

3. Installare l'interfaccia della riga di comando di Voce tramite l'interfaccia della riga di comando di .NET immettendo questo comando:

   dotnet tool install --global Microsoft.CognitiveServices.Speech.CLI
   

   Per aggiornare l'interfaccia della riga di comando di Voce, immettere questo comando:

   dotnet tool update --global Microsoft.CognitiveServices.Speech.CLI
   

Immettere spx o spx help per visualizzare la guida dell'interfaccia della riga di comando di Voce.

Limitazioni dei tipi di carattere

In Windows, l'interfaccia della riga di comando di Voce può visualizzare solo i tipi di carattere disponibili per il prompt dei comandi nel computer locale. Il terminale Windows supporta tutti i tipi di carattere prodotti dall'interfaccia della riga di comando di Voce in modo interattivo.

Se l'output viene restituito in un file, è possibile che anche un editor di testo come Blocco note o un Web browser come Microsoft Edge visualizzi tutti i tipi di carattere.

Linux

Le distribuzioni Linux seguenti sono supportate per le architetture x64 che usano l'interfaccia della riga di comando di Voce:

• Ubuntu 20.04/22.04/24.04
• Debian 11/12

Nota

Speech SDK supporta architetture aggiuntive rispetto all'interfaccia della riga di comando di Voce. Per altre informazioni, vedere Informazioni su Speech SDK.

Per installare l’interfaccia della riga di comando di Voce su Linux su una CPU x64, seguire questa procedura:

1. Installare .NET 6.

2. Installare l'interfaccia della riga di comando di Voce tramite l'interfaccia della riga di comando di .NET immettendo questo comando:

   dotnet tool install --global Microsoft.CognitiveServices.Speech.CLI
   

   Per aggiornare l'interfaccia della riga di comando di Voce, immettere questo comando:

   dotnet tool update --global Microsoft.CognitiveServices.Speech.CLI
   

3. Installare GStreamer per il supporto audio compresso.

Immettere spx per visualizzare la guida dell'interfaccia della riga di comando di Voce.

macOS

Per installare l'interfaccia della riga di comando di Voce su macOS 10.14 o versioni successive, seguire questa procedura:

1. Installare .NET 6.

2. Installare l'interfaccia della riga di comando di Voce tramite l'interfaccia della riga di comando di .NET immettendo questo comando:

   dotnet tool install --global Microsoft.CognitiveServices.Speech.CLI
   

   Per aggiornare l'interfaccia della riga di comando di Voce, immettere questo comando:

   dotnet tool update --global Microsoft.CognitiveServices.Speech.CLI
   

Immettere spx o spx help per visualizzare la guida dell'interfaccia della riga di comando di Voce.

Docker (Windows, Linux, macOS)

L'esempio seguente esegue il pull di un'immagine del contenitore pubblica da Docker Hub. È consigliabile eseguire prima l'autenticazione con l'account Docker Hub (docker login) anziché effettuare una richiesta pull anonima. Per migliorare l'affidabilità quando si usa contenuto pubblico, importare e gestire l'immagine in un registro Azure Container privato. Altre informazioni sull'uso delle immagini pubbliche.

Seguire questa procedura per installare l'interfaccia della riga di comando di Voce in un contenitore Docker:

1. Installare Docker Desktop per la piattaforma se non è già stato fatto.
2. In un nuovo prompt dei comandi o terminale immettere questo comando:

   docker pull msftspeech/spx
   

Immettere questo comando per visualizzare le informazioni della Guida per l'interfaccia della riga di comando di Voce:

docker run -it --rm msftspeech/spx help

Montare una directory nel contenitore

Lo strumento interfaccia della riga di comando di Voce salva le impostazioni di configurazione come file. Carica questi file quando si esegue qualsiasi comando (ad eccezione dei comandi della Guida).

Quando si usa l'interfaccia della riga di comando di Voce all'interno di un contenitore Docker, occorre installare una directory locale dal contenitore, in modo che lo strumento possa:

• Archiviare o trovare le impostazioni di configurazione.
• Leggere o scrivere file richiesti dal comando, ad esempio file audio di sintesi vocale.

In Windows, immettere questo comando per creare una directory locale che possa essere usata dall'interfaccia della riga di comando di Voce all'interno del contenitore:

mkdir c:\spx-data

In Linux o macOS, immettere questo comando in un terminale per creare una directory e visualizzarne il percorso assoluto:

mkdir ~/spx-data
cd ~/spx-data
pwd

Il percorso assoluto verrà usato per chiamare l'interfaccia della riga di comando di Voce.

Eseguire l'interfaccia della riga di comando di Voce nel contenitore

Questa documentazione mostra il comando spx dell'interfaccia della riga di comando di Voce usato nelle installazioni non Docker. Quando si chiama il comando spx in un contenitore Docker, occorre installare una directory nel contenitore nel file system in cui l'interfaccia della riga di comando di Voce può archiviare e trovare i valori di configurazione e leggere e scrivere file.

In Windows i comandi iniziano nel modo seguente:

docker run -it -v c:\spx-data:/data --rm msftspeech/spx

In Linux o macOS i comandi sono simili all'esempio seguente. Sostituire ABSOLUTE_PATH con il percorso assoluto della directory montata. Il comando pwd ha restituito questo percorso nella sezione precedente. Se si esegue questo comando prima di impostare la chiave e l'area, si riceverà un messaggio di errore che informa che è necessario impostare questi elementi.

sudo docker run -it -v ABSOLUTE_PATH:/data --rm msftspeech/spx

Per usare il comando spx installato in un contenitore, immettere sempre il comando completo mostrato nell'esempio precedente, seguito dai parametri della richiesta specifica. Ad esempio, in Windows questo comando configura la chiave:

docker run -it -v c:\spx-data:/data --rm msftspeech/spx config @key --set SUBSCRIPTION-KEY

Per un'interazione più estesa con lo strumento da riga di comando, è possibile avviare un contenitore con una shell Bash interattiva aggiungendo un parametro entrypoint. In Windows, immettere questo comando per avviare un contenitore che espone un'interfaccia della riga di comando interattiva in cui è possibile immettere più comandi spx:

docker run -it --entrypoint=/bin/bash -v c:\spx-data:/data --rm msftspeech/spx

È possibile combinare questa opzione con AZ Login e usare SPX Init per creare le chiavi di sintesi vocale e selezionare un'area dati corrispondente senza dover usare il portale di Azure. Le chiavi verranno archiviate automaticamente per un uso successivo.

docker run -it --rm --entrypoint /bin/bash -v c:\spx-data:/data msftspeech/spx

az login
spx init

Creare una configurazione delle risorse

Terminale

Per iniziare, sono necessari una chiave e un identificatore di area della risorsa di Voce (ad esempio, eastus, westus). Creare una risorsa di Voce nel portale di Azure. Per altre informazioni, vedere Creare una risorsa di Servizi di Azure AI.

Per configurare la chiave e l'identificatore di area della risorsa Voce, eseguire i comandi seguenti:

spx config @key --set SPEECH-KEY
spx config @region --set SPEECH-REGION

La chiave e l'area vengono archiviate per i comandi futuri dell'interfaccia della riga di comando di Voce. Per visualizzare la configurazione corrente, eseguire i comandi seguenti:

spx config @key
spx config @region

Se necessario, includere l'opzione clear per rimuovere i valori archiviati:

spx config @key --clear
spx config @region --clear

PowerShell

Per iniziare, sono necessari una chiave e un identificatore di area della risorsa di Voce (ad esempio, eastus, westus). Creare una risorsa di Voce nel portale di Azure.

Per configurare la chiave e l'identificatore di area della risorsa Voce, eseguire i comandi seguenti in PowerShell:

spx --% config @key --set SPEECH-KEY
spx --% config @region --set SPEECH-REGION

La chiave e l'area vengono archiviate per i comandi SPX futuri. Per visualizzare la configurazione corrente, eseguire i comandi seguenti:

spx --% config @key
spx --% config @region

Se necessario, includere l'opzione clear per rimuovere i valori archiviati:

spx --% config @key --clear
spx --% config @region --clear

Utilizzo di base

Importante

Quando si usa l'interfaccia della riga di comando di Voce in un contenitore, includere l'opzione --host. Occorre anche specificare --key none per assicurarsi che l'interfaccia della riga di comando non tenti di usare una chiave di Voce per l'autenticazione. Ad esempio, eseguire spx recognize --key none --host wss://localhost:5000/ --file myaudio.wav per riconoscere il parlato da un file audio in un contenitore di riconoscimento vocale.

Questa sezione illustra alcuni comandi SPX di base spesso utili per eseguire i primi test e la prima sperimentazione. Eseguire il comando seguente per visualizzare la Guida in-tool:

spx

È possibile cercare gli argomenti della Guida per parola chiave. Ad esempio, per visualizzare un elenco di esempi di utilizzo dell'interfaccia della riga di comando di Voce, eseguire il comando seguente:

spx help find --topics "examples"

Per visualizzare le opzioni per il comando recognize, eseguire il comando seguente:

spx help recognize

Nell'output della console sono elencati altri comandi della Guida. È possibile immettere questi comandi per ottenere informazioni dettagliate della Guida sui sottocomandi.

Riconoscimento vocale

Nota

Quando si esegue l'interfaccia della riga di comando di Voce in un contenitore Docker non è possibile usare il microfono del computer. Tuttavia è possibile leggere e salvare i file audio nella directory montata locale.

Per convertire il riconoscimento vocale (conversione della voce in testo scritto) usando il microfono predefinito del sistema, eseguire il comando seguente:

spx recognize --microphone

Dopo l'esecuzione del comando, SPX inizia ad ascoltare l'audio sul dispositivo di input attivo corrente. Per interrompere l'ascolto, premere INVIO. L'audio parlato viene quindi riconosciuto e convertito in testo nell'output della console.

Con l'interfaccia della riga di comando di Voce è anche possibile riconoscere la voce da un file audio. Esegui questo comando:

spx recognize --file /path/to/file.wav

Suggerimento

In caso di difficoltà o per saperne di più sulle opzioni di riconoscimento dell'interfaccia della riga di comando di Voce, è possibile eseguire spx help recognize.

Sintesi vocale

Il comando seguente accetta il testo immesso come input e restituisce la voce sintetizzata al dispositivo di output attivo corrente (ad esempio, gli altoparlanti del computer).

spx synthesize --text "Testing synthesis using the Speech CLI" --speakers

Si può anche salvare l'output sintetizzato in un file. In questo esempio viene creato un file denominato my-sample.wav nella directory in cui si esegue il comando.

spx synthesize --text "Enjoy using the Speech CLI." --audio output my-sample.wav

Questi esempi presuppongono che si stia testando in lingua inglese. Tuttavia, il servizio Voce supporta la sintesi vocale in molte lingue. È possibile ottenere un elenco completo di voci eseguendo il comando seguente oppure visitando la pagina delle lingue supportate.

spx synthesize --voices

Il comando seguente consente di usare una delle voci individuate.

spx synthesize --text "Bienvenue chez moi." --voice fr-FR-AlainNeural --speakers

Suggerimento

In caso di difficoltà o per saperne di più sulle opzioni di riconoscimento dell'interfaccia della riga di comando di Voce, è possibile eseguire spx help synthesize.

Traduzione da voce in testo scritto

L'interfaccia della riga di comando di Voce consente anche di eseguire la traduzione del testo prodotto dal riconoscimento vocale. Eseguire il comando seguente per acquisire l'audio dal microfono predefinito e restituire la traduzione come testo. Tenere presente che è necessario specificare le lingue source e target con il comando translate.

spx translate --microphone --source en-US --target ru-RU

Quando si esegue la traduzione in più lingue, separare i codici di lingua con un punto e virgola (;).

spx translate --microphone --source en-US --target 'ru-RU;fr-FR;es-ES'

Per salvare l'output della traduzione, usare il flag --output. In questo esempio viene anche eseguita la lettura da un file.

spx translate --file /some/file/path/input.wav --source en-US --target ru-RU --output file /some/file/path/russian_translation.txt

Suggerimento

In caso di difficoltà o per saperne di più sulle opzioni di riconoscimento dell'interfaccia della riga di comando di Voce, è possibile eseguire spx help translate.

Passaggi successivi

• Installare GStreamer per usare l'interfaccia della riga di comando di Voce con il formato MP3 e altri formati
• Opzioni di configurazione dell'interfaccia della riga di comando di Voce
• Operazioni in batch con l'interfaccia della riga di comando di Voce