Come riconoscere le finalità con criteri di entità personalizzati

Speech SDK per i servizi di intelligenza artificiale di Azure offre una funzionalità predefinita per fornire il riconoscimento delle finalità con criteri di linguaggio semplici. Una finalità è un'operazione che l'utente vuole eseguire: chiudere una finestra, contrassegnare una casella di controllo, inserire testo e così via.

In questa guida si usa Speech SDK per sviluppare un'applicazione console che deriva le finalità dalle espressioni vocali pronunciate tramite il microfono del dispositivo. Scopri come:

• Creare un progetto di Visual Studio che fa riferimento al pacchetto Speech SDK NuGet
• Creare una configurazione di riconoscimento vocale e ricevere un sistema di riconoscimento delle finalità
• Aggiungere finalità e modelli tramite l'API Speech SDK
• Aggiungere entità personalizzate tramite l'API Speech SDK
• Usare riconoscimento asincrono continuo basato su eventi

Quando usare criteri di ricerca

Usa criteri di ricerca se:

• Sei interessato solo alla corrispondenza rigorosamente a ciò che l'utente ha detto. Questi modelli corrispondono in modo più aggressivo rispetto a CLU (Conversational Language Understanding).
• Non si ha accesso a un modello CLU, ma si vogliono comunque finalità.

Per altre informazioni, vedere la panoramica dei criteri di ricerca.

Prerequisiti

Prima di iniziare questa guida, assicurarsi di avere gli elementi seguenti:

• Una risorsa dei servizi di intelligenza artificiale di Azure o una risorsa Riconoscimento vocale unificato
• Visual Studio 2019 (qualsiasi edizione).

Creare un progetto

Creare un nuovo progetto di applicazione console C# in Visual Studio 2019 e installare Speech SDK.

Iniziare con un codice boilerplate

Si aprirà Program.cs e si aggiungerà un codice che funzioni come scheletro per il progetto.

using System;
using System.Threading.Tasks;
using Microsoft.CognitiveServices.Speech;
using Microsoft.CognitiveServices.Speech.Intent;

namespace helloworld
{
    class Program
    {
        static void Main(string[] args)
        {
            IntentPatternMatchingWithMicrophoneAsync().Wait();
        }

        private static async Task IntentPatternMatchingWithMicrophoneAsync()
        {
            var config = SpeechConfig.FromSubscription("YOUR_SUBSCRIPTION_KEY", "YOUR_SUBSCRIPTION_REGION");
        }
    }
}

Creare una configurazione di Voce

Prima di poter inizializzare un IntentRecognizer oggetto, è necessario creare una configurazione che usa la chiave e l'area di Azure per la risorsa di stima dei servizi di intelligenza artificiale di Azure.

• Sostituire "YOUR_SUBSCRIPTION_KEY" con la chiave di stima dei servizi di intelligenza artificiale di Azure.
• Sostituire "YOUR_SUBSCRIPTION_REGION" con l'area delle risorse dei servizi di intelligenza artificiale di Azure.

Questo esempio usa il metodo FromSubscription() per creare SpeechConfig. Per un elenco completo dei metodi disponibili, vedere Classe SpeechConfig.

Inizializzare un oggetto IntentRecognizer

Creare ora un oggetto IntentRecognizer. Inserire questo codice immediatamente sotto la configurazione di Voce.

using (var recognizer = new IntentRecognizer(config))
{
    
}

Aggiungere alcune finalità

È necessario associare alcuni modelli a un PatternMatchingModel oggetto e applicarli a IntentRecognizer. Si inizierà creando un PatternMatchingModel oggetto e aggiungendo alcune finalità.

Nota

È possibile aggiungere più modelli a un oggetto PatternMatchingIntent.

Inserire questo codice all'interno del using blocco:

// Creates a Pattern Matching model and adds specific intents from your model. The
// Id is used to identify this model from others in the collection.
var model = new PatternMatchingModel("YourPatternMatchingModelId");

// Creates a pattern that uses groups of optional words. "[Go | Take me]" will match either "Go", "Take me", or "".
var patternWithOptionalWords = "[Go | Take me] to [floor|level] {floorName}";

// Creates a pattern that uses an optional entity and group that could be used to tie commands together.
var patternWithOptionalEntity = "Go to parking [{parkingLevel}]";

// You can also have multiple entities of the same name in a single pattern by adding appending a unique identifier
// to distinguish between the instances. For example:
var patternWithTwoOfTheSameEntity = "Go to floor {floorName:1} [and then go to floor {floorName:2}]";
// NOTE: Both floorName:1 and floorName:2 are tied to the same list of entries. The identifier can be a string
//       and is separated from the entity name by a ':'

// Creates the pattern matching intents and adds them to the model
model.Intents.Add(new PatternMatchingIntent("ChangeFloors", patternWithOptionalWords, patternWithOptionalEntity, patternWithTwoOfTheSameEntity));
model.Intents.Add(new PatternMatchingIntent("DoorControl", "{action} the doors", "{action} doors", "{action} the door", "{action} door"));

Aggiungere alcune entità personalizzate

Per sfruttare al meglio il matcher dei criteri, è possibile personalizzare le entità. Faremo "floorName" un elenco dei piani disponibili. Creeremo anche "parkingLevel" un'entità integer.

Inserire questo codice sotto le finalità:

// Creates the "floorName" entity and set it to type list.
// Adds acceptable values. NOTE the default entity type is Any and so we do not need
// to declare the "action" entity.
model.Entities.Add(PatternMatchingEntity.CreateListEntity("floorName", EntityMatchMode.Strict, "ground floor", "lobby", "1st", "first", "one", "1", "2nd", "second", "two", "2"));

// Creates the "parkingLevel" entity as a pre-built integer
model.Entities.Add(PatternMatchingEntity.CreateIntegerEntity("parkingLevel"));

Applicare il modello a Recognizer

È ora necessario applicare il modello all'oggetto IntentRecognizer. È possibile usare più modelli contemporaneamente in modo che l'API prenda una raccolta di modelli.

Inserire questo codice sotto le entità:

var modelCollection = new LanguageUnderstandingModelCollection();
modelCollection.Add(model);

recognizer.ApplyLanguageModels(modelCollection);

Riconoscere una finalità

Dall'oggetto IntentRecognizer chiamare il metodo RecognizeOnceAsync(). Questo metodo chiede al servizio Voce di riconoscere la voce in una singola frase e di interrompere il riconoscimento vocale dopo l'identificazione della frase.

Inserire questo codice dopo l'applicazione dei modelli linguistici:

Console.WriteLine("Say something...");

var result = await recognizer.RecognizeOnceAsync();

Visualizzare i risultati (o gli errori) del riconoscimento

Quando il risultato del riconoscimento viene restituito dal servizio Voce, il risultato verrà stampato.

Inserire questo codice sotto var result = await recognizer.RecognizeOnceAsync();:

if (result.Reason == ResultReason.RecognizedIntent)
{
    Console.WriteLine($"RECOGNIZED: Text={result.Text}");
    Console.WriteLine($"       Intent Id={result.IntentId}.");

    var entities = result.Entities;
    switch (result.IntentId)
    {
        case "ChangeFloors":
            if (entities.TryGetValue("floorName", out string floorName))
            {
                Console.WriteLine($"       FloorName={floorName}");
            }

            if (entities.TryGetValue("floorName:1", out floorName))
            {
                Console.WriteLine($"     FloorName:1={floorName}");
            }

            if (entities.TryGetValue("floorName:2", out floorName))
            {
                Console.WriteLine($"     FloorName:2={floorName}");
            }

            if (entities.TryGetValue("parkingLevel", out string parkingLevel))
            {
                Console.WriteLine($"    ParkingLevel={parkingLevel}");
            }

            break;

        case "DoorControl":
            if (entities.TryGetValue("action", out string action))
            {
                Console.WriteLine($"          Action={action}");
            }
            break;
    }
}
else if (result.Reason == ResultReason.RecognizedSpeech)
{
    Console.WriteLine($"RECOGNIZED: Text={result.Text}");
    Console.WriteLine($"    Intent not recognized.");
}
else if (result.Reason == ResultReason.NoMatch)
{
    Console.WriteLine($"NOMATCH: Speech could not be recognized.");
}
else if (result.Reason == ResultReason.Canceled)
{
    var cancellation = CancellationDetails.FromResult(result);
    Console.WriteLine($"CANCELED: Reason={cancellation.Reason}");

    if (cancellation.Reason == CancellationReason.Error)
    {
        Console.WriteLine($"CANCELED: ErrorCode={cancellation.ErrorCode}");
        Console.WriteLine($"CANCELED: ErrorDetails={cancellation.ErrorDetails}");
        Console.WriteLine($"CANCELED: Did you set the speech resource key and region values?");
    }
}

Controllare il codice

A questo punto il codice dovrà avere questo aspetto:

using System;
using System.Threading.Tasks;
using Microsoft.CognitiveServices.Speech;
using Microsoft.CognitiveServices.Speech.Intent;

namespace helloworld
{
    class Program
    {
        static void Main(string[] args)
        {
            IntentPatternMatchingWithMicrophoneAsync().Wait();
        }

        private static async Task IntentPatternMatchingWithMicrophoneAsync()
        {
            var config = SpeechConfig.FromSubscription("YOUR_SUBSCRIPTION_KEY", "YOUR_SUBSCRIPTION_REGION");

            using (var recognizer = new IntentRecognizer(config))
            {
                // Creates a Pattern Matching model and adds specific intents from your model. The
                // Id is used to identify this model from others in the collection.
                var model = new PatternMatchingModel("YourPatternMatchingModelId");

                // Creates a pattern that uses groups of optional words. "[Go | Take me]" will match either "Go", "Take me", or "".
                var patternWithOptionalWords = "[Go | Take me] to [floor|level] {floorName}";

                // Creates a pattern that uses an optional entity and group that could be used to tie commands together.
                var patternWithOptionalEntity = "Go to parking [{parkingLevel}]";

                // You can also have multiple entities of the same name in a single pattern by adding appending a unique identifier
                // to distinguish between the instances. For example:
                var patternWithTwoOfTheSameEntity = "Go to floor {floorName:1} [and then go to floor {floorName:2}]";
                // NOTE: Both floorName:1 and floorName:2 are tied to the same list of entries. The identifier can be a string
                //       and is separated from the entity name by a ':'

                // Adds some intents to look for specific patterns.
                model.Intents.Add(new PatternMatchingIntent("ChangeFloors", patternWithOptionalWords, patternWithOptionalEntity, patternWithTwoOfTheSameEntity));
                model.Intents.Add(new PatternMatchingIntent("DoorControl", "{action} the doors", "{action} doors", "{action} the door", "{action} door"));

                // Creates the "floorName" entity and set it to type list.
                // Adds acceptable values. NOTE the default entity type is Any and so we do not need
                // to declare the "action" entity.
                model.Entities.Add(PatternMatchingEntity.CreateListEntity("floorName", EntityMatchMode.Strict, "ground floor", "lobby", "1st", "first", "one", "1", "2nd", "second", "two", "2"));

                // Creates the "parkingLevel" entity as a pre-built integer
                model.Entities.Add(PatternMatchingEntity.CreateIntegerEntity("parkingLevel"));

                var modelCollection = new LanguageUnderstandingModelCollection();
                modelCollection.Add(model);

                recognizer.ApplyLanguageModels(modelCollection);

                Console.WriteLine("Say something...");

                var result = await recognizer.RecognizeOnceAsync();

                if (result.Reason == ResultReason.RecognizedIntent)
                {
                    Console.WriteLine($"RECOGNIZED: Text={result.Text}");
                    Console.WriteLine($"       Intent Id={result.IntentId}.");

                    var entities = result.Entities;
                    switch (result.IntentId)
                    {
                        case "ChangeFloors":
                            if (entities.TryGetValue("floorName", out string floorName))
                            {
                                Console.WriteLine($"       FloorName={floorName}");
                            }

                            if (entities.TryGetValue("floorName:1", out floorName))
                            {
                                Console.WriteLine($"     FloorName:1={floorName}");
                            }

                            if (entities.TryGetValue("floorName:2", out floorName))
                            {
                                Console.WriteLine($"     FloorName:2={floorName}");
                            }

                            if (entities.TryGetValue("parkingLevel", out string parkingLevel))
                            {
                                Console.WriteLine($"    ParkingLevel={parkingLevel}");
                            }

                            break;

                        case "DoorControl":
                            if (entities.TryGetValue("action", out string action))
                            {
                                Console.WriteLine($"          Action={action}");
                            }
                            break;
                    }
                }
                else if (result.Reason == ResultReason.RecognizedSpeech)
                {
                    Console.WriteLine($"RECOGNIZED: Text={result.Text}");
                    Console.WriteLine($"    Intent not recognized.");
                }
                else if (result.Reason == ResultReason.NoMatch)
                {
                    Console.WriteLine($"NOMATCH: Speech could not be recognized.");
                }
                else if (result.Reason == ResultReason.Canceled)
                {
                    var cancellation = CancellationDetails.FromResult(result);
                    Console.WriteLine($"CANCELED: Reason={cancellation.Reason}");

                    if (cancellation.Reason == CancellationReason.Error)
                    {
                        Console.WriteLine($"CANCELED: ErrorCode={cancellation.ErrorCode}");
                        Console.WriteLine($"CANCELED: ErrorDetails={cancellation.ErrorDetails}");
                        Console.WriteLine($"CANCELED: Did you set the speech resource key and region values?");
                    }
                }
            }
        }
    }
}

Compilare ed eseguire l'app

A questo punto è possibile compilare l'app e testare il riconoscimento vocale con il servizio Voce.

1. Compilare il codice: dalla barra dei menu di Visual Studio scegliere Compila>Compila soluzione.
2. Avviare l'app: dalla barra dei menu scegliere Debug>Avvia debug o premere F5.
3. Avvia riconoscimento : ti chiederà di dire qualcosa. La lingua predefinita è l'italiano. La voce viene inviata al servizio Voce, trascritta come testo e visualizzata nella console.

Ad esempio, se si dice "Portami al piano 2", questo dovrebbe essere l'output:

Say something...
RECOGNIZED: Text=Take me to floor 2.
       Intent Id=ChangeFloors.
       FloorName=2

Come un altro esempio se si dice "Portami al piano 7", questo dovrebbe essere l'output:

Say something...
RECOGNIZED: Text=Take me to floor 7.
    Intent not recognized.

Nessuna finalità riconosciuta perché 7 non era presente nell'elenco di valori validi per floorName.

Creare un progetto

Creare un nuovo progetto di applicazione console C++ in Visual Studio 2019 e installare Speech SDK.

Iniziare con un codice boilerplate

Si aprirà helloworld.cpp e si aggiungerà un codice che funzioni come scheletro per il progetto.

#include <iostream>
#include <speechapi_cxx.h>

using namespace Microsoft::CognitiveServices::Speech;
using namespace Microsoft::CognitiveServices::Speech::Intent;

int main()
{
    std::cout << "Hello World!\n";

    auto config = SpeechConfig::FromSubscription("YOUR_SUBSCRIPTION_KEY", "YOUR_SUBSCRIPTION_REGION");
}

Creare una configurazione di Voce

Prima di poter inizializzare un IntentRecognizer oggetto, è necessario creare una configurazione che usa la chiave e l'area di Azure per la risorsa di stima dei servizi di intelligenza artificiale di Azure.

• Sostituire "YOUR_SUBSCRIPTION_KEY" con la chiave di stima dei servizi di intelligenza artificiale di Azure.
• Sostituire "YOUR_SUBSCRIPTION_REGION" con l'area delle risorse dei servizi di intelligenza artificiale di Azure.

Questo esempio usa il metodo FromSubscription() per creare SpeechConfig. Per un elenco completo dei metodi disponibili, vedere Classe SpeechConfig.

Inizializzare un oggetto IntentRecognizer

Creare ora un oggetto IntentRecognizer. Inserire questo codice immediatamente sotto la configurazione di Voce.

    auto intentRecognizer = IntentRecognizer::FromConfig(config);

Aggiungere alcune finalità

È necessario associare alcuni modelli a un PatternMatchingModel oggetto e applicarli a IntentRecognizer. Si inizierà creando un PatternMatchingModel oggetto e aggiungendo alcune finalità. PatternMatchingIntent è uno struct in modo da usare solo la sintassi in linea.

Nota

È possibile aggiungere più modelli a un oggetto PatternMatchingIntent.

auto model = PatternMatchingModel::FromId("myNewModel");

model->Intents.push_back({"Take me to floor {floorName}.", "Go to floor {floorName}."} , "ChangeFloors");
model->Intents.push_back({"{action} the door."}, "OpenCloseDoor");

Aggiungere alcune entità personalizzate

Per sfruttare al meglio il matcher dei criteri, è possibile personalizzare le entità. Faremo "floorName" un elenco dei piani disponibili.

model->Entities.push_back({ "floorName" , Intent::EntityType::List, Intent::EntityMatchMode::Strict, {"one", "1", "two", "2", "lobby", "ground floor"} });

Applicare il modello a Recognizer

È ora necessario applicare il modello all'oggetto IntentRecognizer. È possibile usare più modelli contemporaneamente in modo che l'API prenda una raccolta di modelli.

std::vector<std::shared_ptr<LanguageUnderstandingModel>> collection;

collection.push_back(model);
intentRecognizer->ApplyLanguageModels(collection);

Riconoscere una finalità

Dall'oggetto IntentRecognizer chiamare il metodo RecognizeOnceAsync(). Questo metodo chiede al servizio Voce di riconoscere la voce in una singola frase e di interrompere il riconoscimento vocale dopo l'identificazione della frase. Per semplicità, attendere il completamento della funzionalità restituita.

Inserire questo codice sotto le finalità:

std::cout << "Say something ..." << std::endl;
auto result = intentRecognizer->RecognizeOnceAsync().get();

Visualizzare i risultati (o gli errori) del riconoscimento

Quando il risultato del riconoscimento viene restituito dal servizio Voce, il risultato verrà stampato.

Inserire questo codice sotto auto result = intentRecognizer->RecognizeOnceAsync().get();:

switch (result->Reason)
{
case ResultReason::RecognizedSpeech:
        std::cout << "RECOGNIZED: Text = " << result->Text.c_str() << std::endl;
        std::cout << "NO INTENT RECOGNIZED!" << std::endl;
        break;
case ResultReason::RecognizedIntent:
    std::cout << "RECOGNIZED: Text = " << result->Text.c_str() << std::endl;
    std::cout << "  Intent Id = " << result->IntentId.c_str() << std::endl;
    auto entities = result->GetEntities();
    if (entities.find("floorName") != entities.end())
    {
        std::cout << "  Floor name: = " << entities["floorName"].c_str() << std::endl;
    }

    if (entities.find("action") != entities.end())
    {
        std::cout << "  Action: = " << entities["action"].c_str() << std::endl;
    }

    break;
case ResultReason::NoMatch:
{
    auto noMatch = NoMatchDetails::FromResult(result);
    switch (noMatch->Reason)
    {
    case NoMatchReason::NotRecognized:
        std::cout << "NOMATCH: Speech was detected, but not recognized." << std::endl;
        break;
    case NoMatchReason::InitialSilenceTimeout:
        std::cout << "NOMATCH: The start of the audio stream contains only silence, and the service timed out waiting for speech." << std::endl;
        break;
    case NoMatchReason::InitialBabbleTimeout:
        std::cout << "NOMATCH: The start of the audio stream contains only noise, and the service timed out waiting for speech." << std::endl;
        break;
    case NoMatchReason::KeywordNotRecognized:
        std::cout << "NOMATCH: Keyword not recognized" << std::endl;
        break;
    }
    break;
}
case ResultReason::Canceled:
{
    auto cancellation = CancellationDetails::FromResult(result);

    if (!cancellation->ErrorDetails.empty())
    {
        std::cout << "CANCELED: ErrorDetails=" << cancellation->ErrorDetails.c_str() << std::endl;
        std::cout << "CANCELED: Did you set the speech resource key and region values?" << std::endl;
    }
}
default:
    break;
}

Controllare il codice

A questo punto il codice dovrà avere questo aspetto:

#include <iostream>
#include <speechapi_cxx.h>

using namespace Microsoft::CognitiveServices::Speech;
using namespace Microsoft::CognitiveServices::Speech::Intent;

int main()
{
    auto config = SpeechConfig::FromSubscription("YOUR_SUBSCRIPTION_KEY", "YOUR_SUBSCRIPTION_REGION");
    auto intentRecognizer = IntentRecognizer::FromConfig(config);

    auto model = PatternMatchingModel::FromId("myNewModel");

    model->Intents.push_back({"Take me to floor {floorName}.", "Go to floor {floorName}."} , "ChangeFloors");
    model->Intents.push_back({"{action} the door."}, "OpenCloseDoor");

    model->Entities.push_back({ "floorName" , Intent::EntityType::List, Intent::EntityMatchMode::Strict, {"one", "1", "two", "2", "lobby", "ground floor"} });

    std::vector<std::shared_ptr<LanguageUnderstandingModel>> collection;

    collection.push_back(model);
    intentRecognizer->ApplyLanguageModels(collection);

    std::cout << "Say something ..." << std::endl;

    auto result = intentRecognizer->RecognizeOnceAsync().get();

    switch (result->Reason)
    {
    case ResultReason::RecognizedSpeech:
        std::cout << "RECOGNIZED: Text = " << result->Text.c_str() << std::endl;
        std::cout << "NO INTENT RECOGNIZED!" << std::endl;
        break;
    case ResultReason::RecognizedIntent:
        std::cout << "RECOGNIZED: Text = " << result->Text.c_str() << std::endl;
        std::cout << "  Intent Id = " << result->IntentId.c_str() << std::endl;
        auto entities = result->GetEntities();
        if (entities.find("floorName") != entities.end())
        {
            std::cout << "  Floor name: = " << entities["floorName"].c_str() << std::endl;
        }

        if (entities.find("action") != entities.end())
        {
            std::cout << "  Action: = " << entities["action"].c_str() << std::endl;
        }

        break;
    case ResultReason::NoMatch:
    {
        auto noMatch = NoMatchDetails::FromResult(result);
        switch (noMatch->Reason)
        {
        case NoMatchReason::NotRecognized:
            std::cout << "NOMATCH: Speech was detected, but not recognized." << std::endl;
            break;
        case NoMatchReason::InitialSilenceTimeout:
            std::cout << "NOMATCH: The start of the audio stream contains only silence, and the service timed out waiting for speech." << std::endl;
            break;
        case NoMatchReason::InitialBabbleTimeout:
            std::cout << "NOMATCH: The start of the audio stream contains only noise, and the service timed out waiting for speech." << std::endl;
            break;
        case NoMatchReason::KeywordNotRecognized:
            std::cout << "NOMATCH: Keyword not recognized." << std::endl;
            break;
        }
        break;
    }
    case ResultReason::Canceled:
    {
        auto cancellation = CancellationDetails::FromResult(result);

        if (!cancellation->ErrorDetails.empty())
        {
            std::cout << "CANCELED: ErrorDetails=" << cancellation->ErrorDetails.c_str() << std::endl;
            std::cout << "CANCELED: Did you set the speech resource key and region values?" << std::endl;
        }
    }
    default:
        break;
    }
}

Compilare ed eseguire l'app

A questo punto è possibile compilare l'app e testare il riconoscimento vocale con il servizio Voce.

1. Compilare il codice: dalla barra dei menu di Visual Studio scegliere Compila>Compila soluzione.
2. Avviare l'app: dalla barra dei menu scegliere Debug>Avvia debug o premere F5.
3. Avvia riconoscimento : ti chiederà di dire qualcosa. La lingua predefinita è l'italiano. La voce viene inviata al servizio Voce, trascritta come testo e visualizzata nella console.

Ad esempio, se si dice "Portami al piano 2", questo dovrebbe essere l'output:

Say something ...
RECOGNIZED: Text = Take me to floor 2.
  Intent Id = ChangeFloors
  Floor name: = 2

Un altro esempio se si dice "Portami al piano 7", questo dovrebbe essere l'output:

Say something ...
RECOGNIZED: Text = Take me to floor 7.
NO INTENT RECOGNIZED!

L'ID finalità è vuoto perché 7 non era presente nell'elenco.

Documentazione di riferimento | Esempi aggiuntivi su GitHub

In questa guida introduttiva si installa Speech SDK per Java.

Requisiti di piattaforma

Scegliere l'ambiente di destinazione:

Java Runtime

Speech SDK per Java è compatibile con Windows, Linux e macOS.

Windows

In Windows è necessario usare l'architettura di destinazione a 64 bit. È necessario Windows 10 o versione successiva.

Installare Microsoft Visual C++ Redistributable per Visual Studio 2015, 2017, 2019 e 2022 per la piattaforma. L'installazione di questo pacchetto per la prima volta potrebbe richiedere un riavvio.

Speech SDK per Java non supporta Windows in ARM64.

Linux

Attenzione

Questo articolo fa riferimento a CentOS, una distribuzione Linux prossima allo stato di EOL (End of Life, fine del ciclo di vita). Valutarne l'uso e la pianificazione di conseguenza. Per altre informazioni, vedere le linee guida per la fine della vita di CentOS.

Speech SDK per Java supporta le distribuzioni seguenti nelle architetture x64, ARM32 (Debian/Ubuntu) e ARM64 (Debian/Ubuntu):

• Ubuntu 18.04/20.04
• Debian 10/11
• Red Hat Enterprise Linux (RHEL) 7/8
• CentOS 7

Importante

Usare la versione LTS più recente della distribuzione linux. Ad esempio, se si usa Ubuntu 20.04 LTS, usare la versione più recente di Ubuntu 20.04.X.

Speech SDK dipende dalle librerie di sistema Linux seguenti:

• Le librerie condivise della libreria GNU C, inclusa la libreria di programmazione thread POSIX, libpthreads.
• Libreria OpenSSL (libssl) versione 1.x e certificati (ca-certificates).
• Libreria condivisa per le applicazioni ALSA (libasound).

È anche necessario installare ca-certificates per stabilire un websocket sicuro ed evitare l'errore WS_OPEN_ERROR_UNDERLYING_IO_OPEN_FAILED .

Importante

Speech SDK non supporta ancora OpenSSL 3.0, che è l'impostazione predefinita in Ubuntu 22.04 e Debian 12.

Ubuntu 18.04/20.04

Eseguire i comandi seguenti:

sudo apt-get update
sudo apt-get install build-essential libssl-dev ca-certificates libasound2 wget

Debian 10/11

Per usare Speech SDK in Alpine Linux, creare un ambiente chroot Debian come documentato nel Wiki di Alpine Linux per l'esecuzione di programmi glibc. Seguire quindi le istruzioni Debian qui.

sudo apt-get update
sudo apt-get install build-essential libssl-dev ca-certificates libasound2 wget

RHEL 7/8 e CentOS 7

Attenzione

Questo articolo fa riferimento a CentOS, una distribuzione Linux prossima allo stato di EOL (End of Life, fine del ciclo di vita). Valutarne l'uso e la pianificazione di conseguenza. Per altre informazioni, vedere le linee guida per la fine della vita di CentOS.

Installare gli strumenti e le librerie di sviluppo:

sudo yum update
sudo yum groupinstall "Development tools"
sudo yum install alsa-lib openssl wget

Importante

• In RHEL/CentOS 7, seguire le istruzioni riportate in Come configurare RHEL/CentOS 7 per Speech SDK.
• In RHEL seguire le istruzioni su come configurare OpenSSL per Linux.

macOS

È necessaria una versione macOS 10.14 o successiva.

Android

Speech SDK è compatibile con dispositivi Android con processore ARM a 32/64 bit e processori compatibili con Intel x86/x64.

Installare un Java Development Kit, ad esempio Azul Zulu OpenJDK. Dovrebbe funzionare anche Microsoft Build di OpenJDK o il JDK preferito.

Installare Speech SDK per Java

Alcune delle istruzioni usano una versione specifica dell'SDK, 1.24.2ad esempio . Per controllare la versione più recente, cercare il repository GitHub.

Scegliere l'ambiente di destinazione:

Java Runtime

Questa guida illustra come installare Speech SDK per Java in Java Runtime.

Sistemi operativi supportati

Il pacchetto Speech SDK per Java è disponibile per questi sistemi operativi:

• Windows: solo a 64 bit.
• Mac: macOS X versione 10.14 o successiva.
• Linux: vedere le distribuzioni e le architetture di destinazione linux supportate.

Maven

Seguire questa procedura per installare Speech SDK per Java usando Apache Maven:

1. Installare Apache Maven.

2. Aprire un prompt dei comandi in cui si vuole il nuovo progetto e creare un nuovo file pom.xml .

3. Copiare il contenuto XML seguente in pom.xml:

   <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
       <modelVersion>4.0.0</modelVersion>
       <groupId>com.microsoft.cognitiveservices.speech.samples</groupId>
       <artifactId>quickstart-eclipse</artifactId>
       <version>1.0.0-SNAPSHOT</version>
       <build>
           <sourceDirectory>src</sourceDirectory>
           <plugins>
           <plugin>
               <artifactId>maven-compiler-plugin</artifactId>
               <version>3.7.0</version>
               <configuration>
               <source>1.8</source>
               <target>1.8</target>
               </configuration>
           </plugin>
           </plugins>
       </build>
       <dependencies>
           <dependency>
           <groupId>com.microsoft.cognitiveservices.speech</groupId>
           <artifactId>client-sdk</artifactId>
           <version>1.37.0</version>
           </dependency>
       </dependencies>
   </project>
   

4. Eseguire il comando Maven seguente per installare Speech SDK e le dipendenze.

   mvn clean dependency:copy-dependencies
   

Eclipse

Creare un progetto di Eclipse e installare Speech SDK

1. Installare l'IDE Java eclipse. Per questo IDE è necessario che Java sia già installato.

2. Avviare Eclipse.

3. Nella casella Area di lavoro di Eclipse Launcher immettere il nome di una nuova directory dell'area di lavoro. Selezionare quindi Avvio.

   

4. Dopo qualche istante verrà visualizzata la finestra principale dell'IDE di Eclipse. Se è presente, chiudere la schermata iniziale.

5. Scegliere File>Nuovo>progetto dal menu Eclipse.

6. Verrà visualizzata la finestra di dialogo Nuovo progetto . Selezionare Progetto Java e quindi avanti.

   

7. Viene avviata la procedura guidata Nuovo progetto Java. Nel campo Nome progetto immettere guida introduttiva. Scegliere Java edizione Standard-1.8 come ambiente di esecuzione. Selezionare Fine.

   

8. Se viene visualizzata la finestra Aprire prospettiva associata?, selezionare Apri prospettiva.

9. In Esplora pacchetti fare clic con il pulsante destro del mouse sul progetto di avvio rapido. Selezionare Configura converti>in progetto Maven dal menu di scelta rapida.

   

10. Viene visualizzata la finestra Crea nuovo POM. Nel campo ID gruppo immettere com.microsoft.cognitiveservices.speech.samples. Nel campo Artifact ID (ID artefatto) immettere quickstart (Guida introduttiva). Quindi selezionare Fine.

    

11. Aprire il file pom.xml e modificarlo:

    1. Aggiungere un dependencies elemento alla fine del file, prima del tag </project>di chiusura , con Speech SDK come dipendenza:

    <dependencies>
      <dependency>
        <groupId>com.microsoft.cognitiveservices.speech</groupId>
        <artifactId>client-sdk</artifactId>
        <version>1.37.0</version>
      </dependency>
    </dependencies>
    

    1. Salvare le modifiche.

Gradle

Configurazioni gradle

Le configurazioni gradle richiedono un riferimento esplicito all'estensione di dipendenza .jar :

// build.gradle

dependencies {
    implementation group: 'com.microsoft.cognitiveservices.speech', name: 'client-sdk', version: "1.37.0", ext: "jar"
}

Android

Questa guida spiega come installare Speech SDK per Java su Android.

Speech SDK per Android è incluso in un pacchetto come file di archivio Android (AAR), che include le librerie necessarie e le autorizzazioni Android necessarie.

Installare Speech SDK con Android Studio

Creare un nuovo progetto in Android Studio e aggiungere Speech SDK per Java come dipendenza della libreria. La configurazione si basa sul pacchetto Maven speech SDK e su Android Studio Chipmunk 2021.2.1.

Creare un progetto vuoto

1. Aprire Android Studio e selezionare Nuovo progetto.

   

2. Nella finestra Nuovo progetto visualizzata selezionare Telefono e Tablet Empty Activity (Attività vuota tablet>) e quindi selezionare Avanti.

   

3. Immettere SpeechQuickstart nella casella di testo Nome .

   

4. Immettere samples.speech.cognitiveservices.microsoft.com nella casella di testo Nome pacchetto.

5. Selezionare una directory del progetto nella casella di selezione Salva percorso .

6. Selezionare Java nella casella di selezione Lingua .

7. Selezionare API 23: Android 6.0 (Marshmallow) nella casella di selezione Livello API minimo.

8. Selezionare Fine.

Android Studio richiede del tempo per preparare il nuovo progetto. Per la prima volta che si usa Android Studio, potrebbero essere necessari alcuni minuti per impostare le preferenze, accettare licenze e completare la procedura guidata.

Installare Speech SDK per Java in Android

Aggiungere Speech SDK come dipendenza nel progetto.

1. Selezionare File>Project structure Dependencies App (Dipendenze>struttura>progetto file).

2. Selezionare il simbolo più (+) per aggiungere una dipendenza in Dipendenze dichiarate. Selezionare quindi Dipendenza libreria dal menu a discesa.

   

3. Nella finestra Aggiungi dipendenza libreria visualizzata immettere il nome e la versione di Speech SDK per Java: com.microsoft.cognitiveservices.speech:client-sdk:1.37.0. Quindi seleziona Cerca.

4. Assicurarsi che l'ID gruppo selezionato sia com.microsoft.cognitiveservices.speech e quindi selezionare OK.

5. Scegliere OK per chiudere la finestra Project Structure (Struttura del progetto) e applicare le modifiche apportate al progetto.

Iniziare con un codice boilerplate

1. Aprire Main.java dal src dir.

2. Sostituire il contenuto del file con quanto segue:

import java.util.ArrayList;
import java.util.Dictionary;
import java.util.concurrent.ExecutionException;


import com.microsoft.cognitiveservices.speech.*;
import com.microsoft.cognitiveservices.speech.intent.*;

public class Main {
    public static void main(String[] args) throws InterruptedException, ExecutionException {
        IntentPatternMatchingWithMicrophone();
    }

    public static void IntentPatternMatchingWithMicrophone() throws InterruptedException, ExecutionException {
        SpeechConfig config = SpeechConfig.fromSubscription("YOUR_SUBSCRIPTION_KEY", "YOUR_SUBSCRIPTION_REGION");
    }
}

Creare una configurazione di Voce

Prima di poter inizializzare un IntentRecognizer oggetto, è necessario creare una configurazione che usa la chiave e l'area di Azure per la risorsa di stima dei servizi di intelligenza artificiale di Azure.

• Sostituire "YOUR_SUBSCRIPTION_KEY" con la chiave di stima dei servizi di intelligenza artificiale di Azure.
• Sostituire "YOUR_SUBSCRIPTION_REGION" con l'area delle risorse dei servizi di intelligenza artificiale di Azure.

Questo esempio usa il metodo fromSubscription() per creare SpeechConfig. Per un elenco completo dei metodi disponibili, vedere Classe SpeechConfig.

Inizializzare un oggetto IntentRecognizer

Creare ora un oggetto IntentRecognizer. Inserire questo codice immediatamente sotto la configurazione di Voce. Questa operazione viene eseguita in un tentativo in modo da sfruttare l'interfaccia autoclosable.

try (IntentRecognizer recognizer = new IntentRecognizer(config)) {

}

Aggiungere alcune finalità

È necessario associare alcuni modelli a un PatternMatchingModel oggetto e applicarli a IntentRecognizer. Si inizierà creando un PatternMatchingModel oggetto e aggiungendo alcune finalità.

Nota

È possibile aggiungere più modelli a un oggetto PatternMatchingIntent.

Inserire questo codice all'interno del try blocco:

// Creates a Pattern Matching model and adds specific intents from your model. The
// Id is used to identify this model from others in the collection.
PatternMatchingModel model = new PatternMatchingModel("YourPatternMatchingModelId");

// Creates a pattern that uses groups of optional words. "[Go | Take me]" will match either "Go", "Take me", or "".
String patternWithOptionalWords = "[Go | Take me] to [floor|level] {floorName}";

// Creates a pattern that uses an optional entity and group that could be used to tie commands together.
String patternWithOptionalEntity = "Go to parking [{parkingLevel}]";

// You can also have multiple entities of the same name in a single pattern by adding appending a unique identifier
// to distinguish between the instances. For example:
String patternWithTwoOfTheSameEntity = "Go to floor {floorName:1} [and then go to floor {floorName:2}]";
// NOTE: Both floorName:1 and floorName:2 are tied to the same list of entries. The identifier can be a string
//       and is separated from the entity name by a ':'

// Creates the pattern matching intents and adds them to the model
model.getIntents().put(new PatternMatchingIntent("ChangeFloors", patternWithOptionalWords, patternWithOptionalEntity, patternWithTwoOfTheSameEntity));
model.getIntents().put(new PatternMatchingIntent("DoorControl", "{action} the doors", "{action} doors", "{action} the door", "{action} door"));

Aggiungere alcune entità personalizzate

Per sfruttare al meglio il matcher dei criteri, è possibile personalizzare le entità. Faremo "floorName" un elenco dei piani disponibili. Creeremo anche "parkingLevel" un'entità integer.

Inserire questo codice sotto le finalità:

// Creates the "floorName" entity and set it to type list.
// Adds acceptable values. NOTE the default entity type is Any and so we do not need
// to declare the "action" entity.
model.getEntities().put(PatternMatchingEntity.CreateListEntity("floorName", PatternMatchingEntity.EntityMatchMode.Strict, "ground floor", "lobby", "1st", "first", "one", "1", "2nd", "second", "two", "2"));

// Creates the "parkingLevel" entity as a pre-built integer
model.getEntities().put(PatternMatchingEntity.CreateIntegerEntity("parkingLevel"));

Applicare il modello a Recognizer

È ora necessario applicare il modello all'oggetto IntentRecognizer. È possibile usare più modelli contemporaneamente in modo che l'API prenda una raccolta di modelli.

Inserire questo codice sotto le entità:

ArrayList<LanguageUnderstandingModel> modelCollection = new ArrayList<LanguageUnderstandingModel>();
modelCollection.add(model);

recognizer.applyLanguageModels(modelCollection);

Riconoscere una finalità

Dall'oggetto IntentRecognizer chiamare il metodo RecognizeOnceAsync(). Questo metodo chiede al servizio Voce di riconoscere la voce in una singola frase e di interrompere il riconoscimento vocale dopo l'identificazione della frase.

Inserire questo codice dopo l'applicazione dei modelli linguistici:

System.out.println("Say something...");

IntentRecognitionResult result = recognizer.recognizeOnceAsync().get();

Visualizzare i risultati (o gli errori) del riconoscimento

Quando il risultato del riconoscimento viene restituito dal servizio Voce, il risultato verrà stampato.

Inserire questo codice sotto IntentRecognitionResult result = recognizer.recognizeOnceAsync.get();:

if (result.getReason() == ResultReason.RecognizedSpeech) {
    System.out.println("RECOGNIZED: Text= " + result.getText());
    System.out.println(String.format("%17s", "Intent not recognized."));
}
else if (result.getReason() == ResultReason.RecognizedIntent)
{
    System.out.println("RECOGNIZED: Text= " + result.getText());
    System.out.println(String.format("%17s %s", "Intent Id=", result.getIntentId() + "."));
    Dictionary<String, String> entities = result.getEntities();

    switch (result.getIntentId())
    {
        case "ChangeFloors":
            if (entities.get("floorName") != null) {
                System.out.println(String.format("%17s %s", "FloorName=", entities.get("floorName")));
            }
            if (entities.get("floorName:1") != null) {
                System.out.println(String.format("%17s %s", "FloorName:1=", entities.get("floorName:1")));
            }
            if (entities.get("floorName:2") != null) {
                System.out.println(String.format("%17s %s", "FloorName:2=", entities.get("floorName:2")));
            }
            if (entities.get("parkingLevel") != null) {
                System.out.println(String.format("%17s %s", "ParkingLevel=", entities.get("parkingLevel")));
            }
            break;
        case "DoorControl":
            if (entities.get("action") != null) {
                System.out.println(String.format("%17s %s", "Action=", entities.get("action")));
            }
            break;
    }
}
else if (result.getReason() == ResultReason.NoMatch) {
    System.out.println("NOMATCH: Speech could not be recognized.");
}
else if (result.getReason() == ResultReason.Canceled) {
    CancellationDetails cancellation = CancellationDetails.fromResult(result);
    System.out.println("CANCELED: Reason=" + cancellation.getReason());

    if (cancellation.getReason() == CancellationReason.Error)
    {
        System.out.println("CANCELED: ErrorCode=" + cancellation.getErrorCode());
        System.out.println("CANCELED: ErrorDetails=" + cancellation.getErrorDetails());
        System.out.println("CANCELED: Did you update the subscription info?");
    }
}

Controllare il codice

A questo punto il codice dovrà avere questo aspetto:

package quickstart;
import java.util.ArrayList;
import java.util.concurrent.ExecutionException;
import java.util.Dictionary;

import com.microsoft.cognitiveservices.speech.*;
import com.microsoft.cognitiveservices.speech.intent.*;

public class Main {
    public static void main(String[] args) throws InterruptedException, ExecutionException {
        IntentPatternMatchingWithMicrophone();
    }

    public static void IntentPatternMatchingWithMicrophone() throws InterruptedException, ExecutionException {
        SpeechConfig config = SpeechConfig.fromSubscription("YOUR_SUBSCRIPTION_KEY", "YOUR_SUBSCRIPTION_REGION");
        try (IntentRecognizer recognizer = new IntentRecognizer(config)) {
            // Creates a Pattern Matching model and adds specific intents from your model. The
            // Id is used to identify this model from others in the collection.
            PatternMatchingModel model = new PatternMatchingModel("YourPatternMatchingModelId");

            // Creates a pattern that uses groups of optional words. "[Go | Take me]" will match either "Go", "Take me", or "".
            String patternWithOptionalWords = "[Go | Take me] to [floor|level] {floorName}";

            // Creates a pattern that uses an optional entity and group that could be used to tie commands together.
            String patternWithOptionalEntity = "Go to parking [{parkingLevel}]";

            // You can also have multiple entities of the same name in a single pattern by adding appending a unique identifier
            // to distinguish between the instances. For example:
            String patternWithTwoOfTheSameEntity = "Go to floor {floorName:1} [and then go to floor {floorName:2}]";
            // NOTE: Both floorName:1 and floorName:2 are tied to the same list of entries. The identifier can be a string
            // and is separated from the entity name by a ':'

            // Creates the pattern matching intents and adds them to the model
            model.getIntents().put(new PatternMatchingIntent("ChangeFloors", patternWithOptionalWords, patternWithOptionalEntity, patternWithTwoOfTheSameEntity));
            model.getIntents().put(new PatternMatchingIntent("DoorControl", "{action} the doors", "{action} doors", "{action} the door", "{action} door"));

            // Creates the "floorName" entity and set it to type list.
            // Adds acceptable values. NOTE the default entity type is Any and so we do not need
            // to declare the "action" entity.
            model.getEntities().put(PatternMatchingEntity.CreateListEntity("floorName", PatternMatchingEntity.EntityMatchMode.Strict, "ground floor", "lobby", "1st", "first", "one", "1", "2nd", "second", "two", "2"));

            // Creates the "parkingLevel" entity as a pre-built integer
            model.getEntities().put(PatternMatchingEntity.CreateIntegerEntity("parkingLevel"));

            ArrayList<LanguageUnderstandingModel> modelCollection = new ArrayList<LanguageUnderstandingModel>();
            modelCollection.add(model);

            recognizer.applyLanguageModels(modelCollection);

            System.out.println("Say something...");

            IntentRecognitionResult result = recognizer.recognizeOnceAsync().get();

            if (result.getReason() == ResultReason.RecognizedSpeech) {
                System.out.println("RECOGNIZED: Text= " + result.getText());
                System.out.println(String.format("%17s", "Intent not recognized."));
            }
            else if (result.getReason() == ResultReason.RecognizedIntent)
            {
                System.out.println("RECOGNIZED: Text= " + result.getText());
                System.out.println(String.format("%17s %s", "Intent Id=", result.getIntentId() + "."));
                Dictionary<String, String> entities = result.getEntities();

                switch (result.getIntentId())
                {
                    case "ChangeFloors":
                        if (entities.get("floorName") != null) {
                            System.out.println(String.format("%17s %s", "FloorName=", entities.get("floorName")));
                        }
                        if (entities.get("floorName:1") != null) {
                            System.out.println(String.format("%17s %s", "FloorName:1=", entities.get("floorName:1")));
                        }
                        if (entities.get("floorName:2") != null) {
                            System.out.println(String.format("%17s %s", "FloorName:2=", entities.get("floorName:2")));
                        }
                        if (entities.get("parkingLevel") != null) {
                            System.out.println(String.format("%17s %s", "ParkingLevel=", entities.get("parkingLevel")));
                        }
                        break;

                    case "DoorControl":
                        if (entities.get("action") != null) {
                            System.out.println(String.format("%17s %s", "Action=", entities.get("action")));
                        }
                        break;
                }
            }
            else if (result.getReason() == ResultReason.NoMatch) {
                System.out.println("NOMATCH: Speech could not be recognized.");
            }
            else if (result.getReason() == ResultReason.Canceled) {
                CancellationDetails cancellation = CancellationDetails.fromResult(result);
                System.out.println("CANCELED: Reason=" + cancellation.getReason());

                if (cancellation.getReason() == CancellationReason.Error)
                {
                    System.out.println("CANCELED: ErrorCode=" + cancellation.getErrorCode());
                    System.out.println("CANCELED: ErrorDetails=" + cancellation.getErrorDetails());
                    System.out.println("CANCELED: Did you update the subscription info?");
                }
            }
        }
    }
}

Compilare ed eseguire l'app

A questo momento si è pronti per compilare l'app e testare il riconoscimento delle finalità usando il servizio di riconoscimento vocale e il matcher modello incorporato.

Selezionare il pulsante Esegui in Eclipse o premere CTRL+F11, quindi osservare l'output per "Say something..." prompt. Una volta visualizzata, pronunciare l'espressione e osservare l'output.

Ad esempio, se si dice "Portami al piano 2", questo dovrebbe essere l'output:

Say something...
RECOGNIZED: Text=Take me to floor 2.
       Intent Id=ChangeFloors.
       FloorName=2

Come un altro esempio se si dice "Portami al piano 7", questo dovrebbe essere l'output:

Say something...
RECOGNIZED: Text=Take me to floor 7.
    Intent not recognized.

Nessuna finalità riconosciuta perché 7 non era presente nell'elenco di valori validi per floorName.