Aggiungere la comprensione del linguaggio naturale al bot

Dopo ogni elaborazione dell'input utente, DialogBot salva lo stato corrente di UserState e ConversationState. Dopo aver raccolto tutte le informazioni necessarie, l'esempio di codifica crea una prenotazione demo di prenotazione dei voli. In questo articolo verranno illustrati gli aspetti LUIS di questo esempio. Tuttavia, il flusso generale dell'esempio è:

• Quando un nuovo utente si connette e visualizza una scheda di benvenuto, viene effettuata una chiamata a OnMembersAddedAsync.
• Per ogni input utente ricevuto, viene effettuata una chiamata a OnMessageActivityAsync,

Il modulo OnMessageActivityAsync esegue il dialogo appropriato tramite il metodo di estensione del dialogo Run. Il dialogo principale chiama quindi l'helper LUIS per trovare la finalità dell'utente con il punteggio più alto. Se la finalità con il punteggio massimo per l'input dell'utente restituisce "BookFlight", l'helper compila le informazioni dell'utente restituite da LUIS. Successivamente, il dialogo principale avvia BookingDialog, che acquisisce eventuali informazioni aggiuntive necessarie all'utente, ad esempio:

• Origin: la città di origine
• TravelDate: la data per cui prenotare il volo
• Destination: la città di destinazione

Dopo ogni elaborazione dell'input utente, dialogBot salva lo stato corrente di userState e conversationState. Dopo aver raccolto tutte le informazioni necessarie, l'esempio di codifica crea una prenotazione demo di prenotazione dei voli. In questo articolo verranno illustrati gli aspetti LUIS di questo esempio. Tuttavia, il flusso generale dell'esempio è:

• Quando un nuovo utente si connette e visualizza una scheda di benvenuto, viene effettuata una chiamata a onMembersAdded.
• Per ogni input utente ricevuto, viene effettuata una chiamata a OnMessage,

Il onMessage modulo esegue , che raccoglie l'input mainDialogdell'utente. Il dialogo principale chiama quindi l'helper LUIS FlightBookingRecognizer per trovare la finalità dell'utente con il punteggio più alto. Se la finalità con il punteggio massimo per l'input dell'utente restituisce "BookFlight", l'helper compila le informazioni dell'utente restituite da LUIS. Dopo aver ricevuto una risposta, mainDialog mantiene le informazioni per l'utente restituite da LUIS e avvia bookingDialog. bookingDialog acquisisce altre informazioni dell'utente, se necessario, ad esempio

• destination: la città di destinazione.
• origin: la città di origine.
• travelDate: la data per cui prenotare il volo.

1. Dopo ogni elaborazione dell'input utente, DialogBot salva lo stato corrente di UserState e ConversationState.
2. Dopo aver raccolto tutte le informazioni necessarie, l'esempio di codifica crea una prenotazione demo di prenotazione dei voli.
3. In questo articolo verranno illustrati gli aspetti LUIS di questo esempio. Tuttavia, il flusso generale dell'esempio è:

• Quando un nuovo utente si connette e visualizza una scheda di benvenuto, viene effettuata una chiamata a onMembersAdded.
• Per ogni input utente ricevuto, viene effettuata una chiamata a onMessageActivity,

Il modulo onMessageActivity esegue il dialogo appropriato tramite il metodo di estensione del dialogo run. Il dialogo principale chiama quindi l'helper LUIS per trovare la finalità dell'utente con il punteggio più alto. Se la finalità con il punteggio massimo per l'input dell'utente restituisce "BookFlight", l'helper compila le informazioni dell'utente restituite da LUIS. Successivamente, il dialogo principale avvia BookingDialog, che acquisisce eventuali informazioni aggiuntive necessarie all'utente, ad esempio:

• Origin: la città di origine
• TravelDate: la data per cui prenotare il volo
• Destination: la città di destinazione

Dopo ogni elaborazione dell'input utente, DialogBot salva lo stato corrente di user_state e conversation_state. Dopo aver raccolto tutte le informazioni necessarie, l'esempio di codifica crea una prenotazione demo di prenotazione dei voli. In questo articolo verranno illustrati gli aspetti LUIS di questo esempio. Tuttavia, il flusso generale dell'esempio è:

• Quando un nuovo utente si connette e visualizza una scheda di benvenuto, viene effettuata una chiamata a on_members_added_activity.
• Per ogni input utente ricevuto, viene effettuata una chiamata a on_message_activity,

Il modulo on_message_activity esegue il dialogo appropriato tramite il metodo di estensione del dialogo run_dialog. La finestra di dialogo principale chiama LuisHelper quindi per trovare la finalità dell'utente con punteggio superiore. Se la finalità con il punteggio più alto per l'input dell'utente restituisce "BookFlight", la funzione helper compila le informazioni dell'utente restituite da LUIS. Successivamente, il dialogo principale avvia BookingDialog, che acquisisce eventuali informazioni aggiuntive necessarie all'utente, ad esempio:

• destination: la città di destinazione.
• origin: la città di origine.
• travel_date: la data per cui prenotare il volo.

Aggiungere le informazioni necessarie per accedere all'app LUIS, inclusi l'ID applicazione, la chiave di creazione e l'area nel appsettings.json file. Nel passaggio precedente questi valori sono stati recuperati dall'app LUIS pubblicata. Il nome host dell'API deve essere nel formato <your region>.api.cognitive.microsoft.com.

appsetting.json

{
  "MicrosoftAppType": "",
  "MicrosoftAppId": "",
  "MicrosoftAppPassword": "",
  "MicrosoftAppTenantId": "",
  "LuisAppId": "",
  "LuisAPIKey": "",
  "LuisAPIHostName": ""
}

Aggiungere le informazioni necessarie per accedere all'app LUIS, inclusi l'ID applicazione, la chiave di creazione e l'area nel .env file. Nel passaggio precedente questi valori sono stati recuperati dall'app LUIS pubblicata. Il nome host dell'API deve essere nel formato <your region>.api.cognitive.microsoft.com.

.env

MicrosoftAppType=
MicrosoftAppId=
MicrosoftAppPassword=
MicrosoftAppTenantId=
LuisAppId=
LuisAPIKey=
LuisAPIHostName=

Aggiungere le informazioni necessarie per accedere all'app LUIS, inclusi l'ID applicazione, la chiave di creazione e l'area nel application.properties file. Nel passaggio precedente questi valori sono stati recuperati dall'app LUIS pubblicata. Il nome host dell'API deve essere nel formato <your region>.api.cognitive.microsoft.com.

application.properties

MicrosoftAppId=
MicrosoftAppPassword=
LuisAppId=
LuisAPIKey=
LuisAPIHostName=
server.port=3978

Aggiungere le informazioni necessarie per accedere all'app LUIS, inclusi l'ID applicazione, la chiave di creazione e l'area nel config.py file. Nel passaggio precedente questi valori sono stati recuperati dall'app LUIS pubblicata. Il nome host dell'API deve essere nel formato <your region>.api.cognitive.microsoft.com.

config.py

APP_ID = os.environ.get("MicrosoftAppId", "")
APP_PASSWORD = os.environ.get("MicrosoftAppPassword", "")
APP_TYPE = os.environ.get("MicrosoftAppType", "MultiTenant")
APP_TENANTID = os.environ.get("MicrosoftAppTenantId", "")
LUIS_APP_ID = os.environ.get("LuisAppId", "")
LUIS_API_KEY = os.environ.get("LuisAPIKey", "")

Assicurarsi che per il progetto sia installato il pacchetto NuGet Microsoft.Bot.Builder.AI.Luis.

Per connettersi al servizio LUIS, il bot esegue il pull delle informazioni aggiunte al file di appsetting.json. La classe FlightBookingRecognizer contiene il codice con le impostazioni dal file appsetting.json ed esegue una query sul servizio LUIS chiamando il metodo RecognizeAsync.

FlightBookingRecognizer.cs

public class FlightBookingRecognizer : IRecognizer
{
    private readonly LuisRecognizer _recognizer;

    public FlightBookingRecognizer(IConfiguration configuration)
    {
        var luisIsConfigured = !string.IsNullOrEmpty(configuration["LuisAppId"]) && !string.IsNullOrEmpty(configuration["LuisAPIKey"]) && !string.IsNullOrEmpty(configuration["LuisAPIHostName"]);
        if (luisIsConfigured)
        {
            var luisApplication = new LuisApplication(
                configuration["LuisAppId"],
                configuration["LuisAPIKey"],
                "https://" + configuration["LuisAPIHostName"]);
            // Set the recognizer options depending on which endpoint version you want to use.
            // More details can be found in https://docs.microsoft.com/en-gb/azure/cognitive-services/luis/luis-migration-api-v3
            var recognizerOptions = new LuisRecognizerOptionsV3(luisApplication)
            {
                PredictionOptions = new Bot.Builder.AI.LuisV3.LuisPredictionOptions
                {
                    IncludeInstanceData = true,
                }
            };

            _recognizer = new LuisRecognizer(recognizerOptions);
        }
    }

    // Returns true if luis is configured in the appsettings.json and initialized.
    public virtual bool IsConfigured => _recognizer != null;

    public virtual async Task<RecognizerResult> RecognizeAsync(ITurnContext turnContext, CancellationToken cancellationToken)
        => await _recognizer.RecognizeAsync(turnContext, cancellationToken);

    public virtual async Task<T> RecognizeAsync<T>(ITurnContext turnContext, CancellationToken cancellationToken)
        where T : IRecognizerConvert, new()
        => await _recognizer.RecognizeAsync<T>(turnContext, cancellationToken);
}

FlightBookingEx.cs contiene la logica per estrarre From, To e TravelDate, estende la classe parziale FlightBooking.cs usata per archiviare i risultati di LUIS quando si chiama FlightBookingRecognizer.RecognizeAsync<FlightBooking> da MainDialog.cs.

CognitiveModels\FlightBookingEx.cs

// Extends the partial FlightBooking class with methods and properties that simplify accessing entities in the luis results
public partial class FlightBooking
{
    public (string From, string Airport) FromEntities
    {
        get
        {
            var fromValue = Entities?._instance?.From?.FirstOrDefault()?.Text;
            var fromAirportValue = Entities?.From?.FirstOrDefault()?.Airport?.FirstOrDefault()?.FirstOrDefault();
            return (fromValue, fromAirportValue);
        }
    }

    public (string To, string Airport) ToEntities
    {
        get
        {
            var toValue = Entities?._instance?.To?.FirstOrDefault()?.Text;
            var toAirportValue = Entities?.To?.FirstOrDefault()?.Airport?.FirstOrDefault()?.FirstOrDefault();
            return (toValue, toAirportValue);
        }
    }

    // This value will be a TIMEX. And we are only interested in a Date so grab the first result and drop the Time part.
    // TIMEX is a format that represents DateTime expressions that include some ambiguity. e.g. missing a Year.
    public string TravelDate
        => Entities.datetime?.FirstOrDefault()?.Expressions.FirstOrDefault()?.Split('T')[0];
}

Per usare LUIS, è necessario installare il pacchetto npm botbuilder-ai per il progetto.

Per connettersi al servizio LUIS, il bot usa le informazioni aggiunte al .env file. La classe flightBookingRecognizer.js contiene il codice che importa le impostazioni dal file .env ed esegue una query sul servizio LUIS chiamando il metodo recognize().

dialogs/flightBookingRecognizer.js

class FlightBookingRecognizer {
    constructor(config) {
        const luisIsConfigured = config && config.applicationId && config.endpointKey && config.endpoint;
        if (luisIsConfigured) {
            // Set the recognizer options depending on which endpoint version you want to use e.g v2 or v3.
            // More details can be found in https://docs.microsoft.com/en-gb/azure/cognitive-services/luis/luis-migration-api-v3
            const recognizerOptions = {
                apiVersion: 'v3'
            };

            this.recognizer = new LuisRecognizer(config, recognizerOptions);
        }
    }

    get isConfigured() {
        return (this.recognizer !== undefined);
    }

    /**
     * Returns an object with preformatted LUIS results for the bot's dialogs to consume.
     * @param {TurnContext} context
     */
    async executeLuisQuery(context) {
        return await this.recognizer.recognize(context);
    }

    getFromEntities(result) {
        let fromValue, fromAirportValue;
        if (result.entities.$instance.From) {
            fromValue = result.entities.$instance.From[0].text;
        }
        if (fromValue && result.entities.From[0].Airport) {
            fromAirportValue = result.entities.From[0].Airport[0][0];
        }

        return { from: fromValue, airport: fromAirportValue };
    }

    getToEntities(result) {
        let toValue, toAirportValue;
        if (result.entities.$instance.To) {
            toValue = result.entities.$instance.To[0].text;
        }
        if (toValue && result.entities.To[0].Airport) {
            toAirportValue = result.entities.To[0].Airport[0][0];
        }

        return { to: toValue, airport: toAirportValue };
    }

    /**
     * This value will be a TIMEX. And we are only interested in a Date so grab the first result and drop the Time part.
     * TIMEX is a format that represents DateTime expressions that include some ambiguity. e.g. missing a Year.
     */
    getTravelDate(result) {
        const datetimeEntity = result.entities.datetime;
        if (!datetimeEntity || !datetimeEntity[0]) return undefined;

        const timex = datetimeEntity[0].timex;
        if (!timex || !timex[0]) return undefined;

        const datetime = timex[0].split('T')[0];
        return datetime;
    }
}

La logica per estrarre From, To e TravelDate viene implementata come metodi helper all'interno di flightBookingRecognizer.js. Questi metodi vengono usati dopo la chiamata a flightBookingRecognizer.executeLuisQuery() da mainDialog.js

Assicurarsi che il pacchetto com.microsoft.bot.bot-ai-luis-v3 venga aggiunto al file pom.xml.

<dependency>
  <groupId>com.microsoft.bot</groupId>
  <artifactId>bot-ai-luis-v3</artifactId>
  <version>4.14.1</version>
</dependency>

Per connettersi al servizio LUIS, il bot esegue il pull delle informazioni aggiunte al file application.properties. La FlightBookingRecognizer classe contiene codice con le impostazioni del file application.properties ed esegue una query sul servizio LUIS chiamando recognize il metodo .

FlightBookingRecognizer.java

/**
 * The constructor of the FlightBookingRecognizer class.
 *
 * @param configuration The Configuration object to use.
 */
public FlightBookingRecognizer(Configuration configuration) {
    Boolean luisIsConfigured = StringUtils.isNotBlank(configuration.getProperty("LuisAppId"))
        && StringUtils.isNotBlank(configuration.getProperty("LuisAPIKey"))
        && StringUtils.isNotBlank(configuration.getProperty("LuisAPIHostName"));
    if (luisIsConfigured) {
        LuisApplication luisApplication = new LuisApplication(
            configuration.getProperty("LuisAppId"),
            configuration.getProperty("LuisAPIKey"),
            String.format("https://%s", configuration.getProperty("LuisAPIHostName"))
        );
        // Set the recognizer options depending on which endpoint version you want to use.
        // More details can be found in
        // https://docs.microsoft.com/en-gb/azure/cognitive-services/luis/luis-migration-api-v3
        LuisRecognizerOptionsV3 recognizerOptions = new LuisRecognizerOptionsV3(luisApplication);
        recognizerOptions.setIncludeInstanceData(true);

        this.recognizer = new LuisRecognizer(recognizerOptions);
    }
}

/**
 * Runs an utterance through a recognizer and returns a generic recognizer result.
 *
 * @param turnContext Turn context.
 * @return Analysis of utterance.
 */
@Override
public CompletableFuture<RecognizerResult> recognize(TurnContext turnContext) {
    return this.recognizer.recognize(turnContext);
}

FlightBookingRecognizer.cs Contiene la logica da cui estrarre From, To e TravelDate e viene chiamato da MainDialog.java per decodificare i risultati del risultato della query Luis.

FlightBookingRecognizer.java

/**
 * Gets the From data from the entities which is part of the result.
 *
 * @param result The recognizer result.
 * @return The object node representing the From data.
 */
public ObjectNode getFromEntities(RecognizerResult result) {
    String fromValue = "", fromAirportValue = "";
    if (result.getEntities().get("$instance").get("From") != null) {
        fromValue = result.getEntities().get("$instance").get("From").get(0).get("text")
            .asText();
    }
    if (!fromValue.isEmpty()
        && result.getEntities().get("From").get(0).get("Airport") != null) {
        fromAirportValue = result.getEntities().get("From").get(0).get("Airport").get(0).get(0)
            .asText();
    }

    ObjectMapper mapper = new ObjectMapper().findAndRegisterModules();
    ObjectNode entitiesNode = mapper.createObjectNode();
    entitiesNode.put("from", fromValue);
    entitiesNode.put("airport", fromAirportValue);
    return entitiesNode;
}

/**
 * Gets the To data from the entities which is part of the result.
 *
 * @param result The recognizer result.
 * @return The object node representing the To data.
 */
public ObjectNode getToEntities(RecognizerResult result) {
    String toValue = "", toAirportValue = "";
    if (result.getEntities().get("$instance").get("To") != null) {
        toValue = result.getEntities().get("$instance").get("To").get(0).get("text").asText();
    }
    if (!toValue.isEmpty() && result.getEntities().get("To").get(0).get("Airport") != null) {
        toAirportValue = result.getEntities().get("To").get(0).get("Airport").get(0).get(0)
            .asText();
    }

    ObjectMapper mapper = new ObjectMapper().findAndRegisterModules();
    ObjectNode entitiesNode = mapper.createObjectNode();
    entitiesNode.put("to", toValue);
    entitiesNode.put("airport", toAirportValue);
    return entitiesNode;
}

/**
 * This value will be a TIMEX. And we are only interested in a Date so grab the first result and
 * drop the Time part. TIMEX is a format that represents DateTime expressions that include some
 * ambiguity. e.g. missing a Year.
 *
 * @param result A {link RecognizerResult}
 * @return The Timex value without the Time model
 */
public String getTravelDate(RecognizerResult result) {
    JsonNode datetimeEntity = result.getEntities().get("datetime");
    if (datetimeEntity == null || datetimeEntity.get(0) == null) {
        return null;
    }

    JsonNode timex = datetimeEntity.get(0).get("timex");
    if (timex == null || timex.get(0) == null) {
        return null;
    }

    String datetime = timex.get(0).asText().split("T")[0];
    return datetime;
}

Assicurarsi che per il progetto sia installato il pacchetto PyPI botbuilder-ai.

Per connettersi al servizio LUIS, il bot usa le informazioni aggiunte al config.py file. La classe FlightBookingRecognizer contiene il codice che importa le impostazioni dal file config.py ed esegue una query sul servizio LUIS chiamando il metodo recognize().

flight_booking_recognizer.py

class FlightBookingRecognizer(Recognizer):
    def __init__(self, configuration: DefaultConfig):
        self._recognizer = None

        luis_is_configured = (
            configuration.LUIS_APP_ID
            and configuration.LUIS_API_KEY
            and configuration.LUIS_API_HOST_NAME
        )
        if luis_is_configured:
            # Set the recognizer options depending on which endpoint version you want to use e.g v2 or v3.
            # More details can be found in https://docs.microsoft.com/azure/cognitive-services/luis/luis-migration-api-v3
            luis_application = LuisApplication(
                configuration.LUIS_APP_ID,
                configuration.LUIS_API_KEY,
                "https://" + configuration.LUIS_API_HOST_NAME,
            )

            self._recognizer = LuisRecognizer(luis_application)

    @property
    def is_configured(self) -> bool:
        # Returns true if luis is configured in the config.py and initialized.
        return self._recognizer is not None

    async def recognize(self, turn_context: TurnContext) -> RecognizerResult:
        return await self._recognizer.recognize(turn_context)

La logica per estrarre i valori di From, To e travel_date viene implementata come metodi helper della classe LuisHelper all'interno di luis_helper.py. Questi metodi vengono usati dopo la chiamata a LuisHelper.execute_luis_query() da main_dialog.py

helpers/luis_helper.py

class LuisHelper:
    @staticmethod
    async def execute_luis_query(
        luis_recognizer: LuisRecognizer, turn_context: TurnContext
    ) -> (Intent, object):
        """
        Returns an object with preformatted LUIS results for the bot's dialogs to consume.
        """
        result = None
        intent = None

        try:
            recognizer_result = await luis_recognizer.recognize(turn_context)

            intent = (
                sorted(
                    recognizer_result.intents,
                    key=recognizer_result.intents.get,
                    reverse=True,
                )[:1][0]
                if recognizer_result.intents
                else None
            )

            if intent == Intent.BOOK_FLIGHT.value:
                result = BookingDetails()

                # We need to get the result from the LUIS JSON which at every level returns an array.
                to_entities = recognizer_result.entities.get("$instance", {}).get(
                    "To", []
                )
                if len(to_entities) > 0:
                    if recognizer_result.entities.get("To", [{"$instance": {}}])[0][
                        "$instance"
                    ]:
                        result.destination = to_entities[0]["text"].capitalize()
                    else:
                        result.unsupported_airports.append(
                            to_entities[0]["text"].capitalize()
                        )

                from_entities = recognizer_result.entities.get("$instance", {}).get(
                    "From", []
                )
                if len(from_entities) > 0:
                    if recognizer_result.entities.get("From", [{"$instance": {}}])[0][
                        "$instance"
                    ]:
                        result.origin = from_entities[0]["text"].capitalize()
                    else:
                        result.unsupported_airports.append(
                            from_entities[0]["text"].capitalize()
                        )

                # This value will be a TIMEX. And we are only interested in a Date so grab the first result and drop
                # the Time part. TIMEX is a format that represents DateTime expressions that include some ambiguity.
                # e.g. missing a Year.
                date_entities = recognizer_result.entities.get("datetime", [])
                if date_entities:
                    timex = date_entities[0]["timex"]

                    if timex:
                        datetime = timex[0].split("T")[0]

                        result.travel_date = datetime

                else:
                    result.travel_date = None

        except Exception as exception:
            print(exception)

        return intent, result