Início Rápido: Biblioteca de clientes de criação do LUIS (Reconhecimento vocal)Quickstart: Language Understanding (LUIS) authoring client library

Introdução à biblioteca de clientes do LUIS (Reconhecimento vocal).Get started with the Language Understanding (LUIS) client library. Siga estas etapas para instalar o SDK e experimentar o código de exemplo para tarefas básicas.Follow these steps to install the SDK and try out the example code for basic tasks. O Reconhecimento Vocal (LUIS) permite aplicar inteligência de aprendizado de máquina personalizado em um texto de linguagem natural de conversação do usuário para prever o significado geral e extrair informações detalhadas relevantes.Language Understanding (LUIS) enables you to apply custom machine-learning intelligence to a user's conversational, natural language text to predict overall meaning, and pull out relevant, detailed information.

Use a biblioteca de clientes de criação de LUIS (Reconhecimento Vocal) para .NET com o objetivo de:Use the Language Understanding (LUIS) authoring client library for .NET to:

  • Criar um aplicativoCreate an app
  • Adicionar intenções, entidades e enunciadosAdd intents, entities, and example utterances
  • Adicionar recursos, como uma lista de frasesAdd features such as a phrase list
  • Treinar e publicar o aplicativoTrain and publish app

Documentação de referência | Código-fonte da biblioteca | Pacote de Criação (NuGet) | Exemplos de C#Reference documentation | Library source code | Authoring Package (NuGet) | C# Samples

Pré-requisitosPrerequisites

  • Assinatura do Azure – Criar uma gratuitamenteAzure subscription - Create one for free
  • A versão atual do .NET Core.The current version of .NET Core.
  • Quando você tiver sua assinatura do Azure, crie um recurso de criação do Reconhecimento vocal no portal do Azure para obter a chave e o ponto de extremidade.Once you have your Azure subscription, create a Language Understanding authoring resource in the Azure portal to get your key and endpoint. Aguarde até que ele seja implantado e clique no botão Ir para o recurso.Wait for it to deploy and click the Go to resource button.
    • Você precisará da chave e do ponto de extremidade do recurso que você criar para conectar seu aplicativo à criação do Reconhecimento vocal.You will need the key and endpoint from the resource you create to connect your application to Language Understanding authoring. Cole a chave e o ponto de extremidade no código abaixo mais adiante no guia de início rápido.You'll paste your key and endpoint into the code below later in the quickstart. Você pode usar o tipo de preço gratuito (F0) para experimentar o serviço.You can use the free pricing tier (F0) to try the service.

ConfigurandoSetting up

Criar um aplicativo em C#Create a new C# application

Crie um novo aplicativo .NET Core em seu IDE ou editor preferido.Create a new .NET Core application in your preferred editor or IDE.

  1. Em uma janela de console (como cmd, PowerShell ou Bash), use o comando new para criar um novo aplicativo do console com o nome language-understanding-quickstart.In a console window (such as cmd, PowerShell, or Bash), use the dotnet new command to create a new console app with the name language-understanding-quickstart. Esse comando cria um projeto simples em C# do tipo "Olá, Mundo" com um arquivo de origem único: Program.cs.This command creates a simple "Hello World" C# project with a single source file: Program.cs.

    dotnet new console -n language-understanding-quickstart
    
  2. Altere o diretório para a pasta do aplicativo recém-criado.Change your directory to the newly created app folder.

  3. É possível criar o aplicativo com:You can build the application with:

    dotnet build
    

    A saída de compilação não deve conter nenhum aviso ou erro.The build output should contain no warnings or errors.

    ...
    Build succeeded.
     0 Warning(s)
     0 Error(s)
    ...
    

Instalar o SDKInstall the SDK

Dentro do diretório do aplicativo, instale a biblioteca de clientes de criação do LUIS (Reconhecimento Vocal) para .NET com o seguinte comando:Within the application directory, install the Language Understanding (LUIS) authoring client library for .NET with the following command:

dotnet add package Microsoft.Azure.CognitiveServices.Language.LUIS.Authoring --version 3.0.0

Se você estiver usando o IDE do Visual Studio, a biblioteca de clientes estará disponível como um pacote baixável do NuGet.If you're using the Visual Studio IDE, the client library is available as a downloadable NuGet package.

Modelo de objetoObject model

O cliente de criação do LUIS (Reconhecimento Vocal) é um objeto LUISAuthoringClient que se autentica no Azure, que contém sua chave de criação.The Language Understanding (LUIS) authoring client is a LUISAuthoringClient object that authenticates to Azure, which contains your authoring key.

Depois que o cliente for criado, use-o para acessar a funcionalidade, incluindo:Once the client is created, use this client to access functionality including:

Exemplos de códigoCode examples

Estes snippets de códigos mostram como fazer o seguinte com a biblioteca de clientes do LUIS (Reconhecimento Vocal) para .NET:These code snippets show you how to do the following with the Language Understanding (LUIS) authoring client library for .NET:

Adicionar as dependênciasAdd the dependencies

No diretório do projeto, abra o arquivo Program.cs no IDE ou no editor de sua preferência.From the project directory, open the Program.cs file in your preferred editor or IDE. Substitua o código using existente pelas seguintes diretivas de using:Replace the existing using code with the following using directives:

using Microsoft.Azure.CognitiveServices.Language.LUIS.Authoring;
using Microsoft.Azure.CognitiveServices.Language.LUIS.Authoring.Models;

using System;
using System.Collections.Generic;
using System.Linq;
using System.Security;
using System.Threading.Tasks;

Autenticar o clienteAuthenticate the client

  1. Crie uma variável para armazenar sua chave e o ponto de extremidade de criação.Create a variable to hold your authoring key and authoring endpoint.

    private static readonly string authoring_key = "REPLACE-WITH-ASSIGNED-AUTHORING-KEY";
    
    private static readonly string authoring_endpoint = "https://REPLACE-WITH-RESOURCE-NAME.cognitiveservices.azure.com/";
    
  2. Crie um objeto ApiKeyServiceClientCredentials com a sua chave e use-o com o ponto de extremidade para criar um objeto LUISAuthoringClient.Create an ApiKeyServiceClientCredentials object with your key, and use it with your endpoint to create an LUISAuthoringClient object.

    // Generate the credentials and create the client.
    var credentials = new Microsoft.Azure.CognitiveServices.Language.LUIS.Authoring.ApiKeyServiceClientCredentials(authoring_key);
    var client = new LUISAuthoringClient(credentials, new System.Net.Http.DelegatingHandler[] { })
    {
        Endpoint = authoring_endpoint
    };
    

Criar um aplicativo LUISCreate a LUIS app

  1. Crie um aplicativo LUIS para conter o modelo de NLP (processamento de idioma natural) que contém tentativas, entidades e exemplo de enunciados.Create a LUIS app to contain the natural language processing (NLP) model holding intents, entities, and example utterances.

  2. Crie um ApplicationCreateObject.Create a ApplicationCreateObject. O nome e a cultura do idioma são propriedades obrigatórias.The name and language culture are required properties.

  3. Chame o método Apps.AddAsync.Call the Apps.AddAsync method. A resposta é a ID do aplicativo.The response is the app ID.

    // Return the application ID and version.
    async static Task<ApplicationInfo> CreateApplication(LUISAuthoringClient client)
    {
        string app_name =           String.Format("Contoso {0}", DateTime.Now);
        string app_description =    "Flight booking app built with LUIS .NET SDK.";
        string app_version =        "0.1";
        string app_culture =        "en-us";
    
        var app_info = new ApplicationCreateObject()
        {
            Name = app_name,
            InitialVersionId = app_version,
            Description = app_description,
            Culture = app_culture
        };
        var app_id = await client.Apps.AddAsync(app_info);
        Console.WriteLine("Created new LUIS application {0}\n with ID {1}.", app_info.Name, app_id);
        return new ApplicationInfo() { ID = app_id, Version = app_version };
    }
    

Criar intenção para o aplicativoCreate intent for the app

O objeto principal no modelo de um aplicativo do LUIS é a intenção.The primary object in a LUIS app's model is the intent. A intenção se alinha com um agrupamento de intenções de enunciado do usuário.The intent aligns's with a grouping of user utterance intentions. Um usuário pode fazer uma pergunta ou uma declaração procurando uma resposta desejada específica de um bot (ou outro aplicativo cliente).A user may ask a question, or make a statement looking for a particular intended response from a bot (or other client application). Exemplos de intenções são: reservar um voo, perguntar sobre o tempo em uma cidade de destino e solicitar informações de contato para o atendimento ao cliente.Examples of intentions are booking a flight, asking about weather in a destination city, and asking about contact information for customer service.

Crie um ModelCreateObject com o nome da intenção exclusiva e, em seguida, passe a ID do aplicativo, a ID da versão e o método ModelCreateObject para o método Model.AddIntentAsync.Create a ModelCreateObject with the name of the unique intent then pass the app ID, version ID, and the ModelCreateObject to the Model.AddIntentAsync method. A resposta é a ID da intenção.The response is the intent ID.

async static Task AddIntents(LUISAuthoringClient client, ApplicationInfo app_info)
{
    await client.Model.AddIntentAsync(app_info.ID, app_info.Version, new ModelCreateObject()
    {
        Name = "FindFlights"
    });
    Console.WriteLine("Created intent FindFlights");
}

Criar entidades para o aplicativoCreate entities for the app

Embora as entidades não sejam necessárias, são encontradas na maioria dos aplicativos.While entities are not required, they are found in most apps. A entidade extrai informações do enunciado do usuário, necessárias para atender à intenção do usuário.The entity extracts information from the user utterance, necessary to fullfil the user's intention. Há vários tipos de entidades predefinidas e personalizadas, cada uma com seus próprios modelos de DTO (objeto de transformação de dados).There are several types of prebuilt and custom entities, each with their own data transformation object (DTO) models. Entidades predefinidas comuns para adicionar ao seu aplicativo number, datetimeV2, geographyV2, ordinal.Common prebuilt entities to add to your app include number, datetimeV2, geographyV2, ordinal.

Esse método AddEntities criou uma entidade simples Location com duas funções, uma entidade simples Class, uma entidade composta Flight e adiciona várias entidades predefinidas.This AddEntities method created a Location simple entity with two roles, a Class simple entity, a Flight composite entity and adds several prebuilt entities.

É importante saber que as entidades não estão marcadas com uma intenção.It is important to know that entities are not marked with an intent. Em geral, elas podem se aplicar a muitas intenções.They can and usually do apply to many intents. Somente os exemplos de enunciados de usuário são marcados para uma única intenção específica.Only example user utterances are marked for a specific, single intent.

Os métodos de criação para as entidades fazem parte da classe do Modelo.Creation methods for entities are part of the Model class. Cada tipo de entidade tem seu próprio modelo de DTO (objeto de transformação de dados), geralmente contendo palavra model no namespace Modelos.Each entity type has its own data transformation object (DTO) model, usually containing the word model in the Models namespace.

// Create entity objects
async static Task AddEntities(LUISAuthoringClient client, ApplicationInfo app_info)
{
    // Add simple entity
    var simpleEntityIdLocation = await client.Model.AddEntityAsync(app_info.ID, app_info.Version, new ModelCreateObject()
    {
        Name = "Location"
    });

    // Add 'Origin' role to simple entity
    await client.Model.CreateEntityRoleAsync(app_info.ID, app_info.Version, simpleEntityIdLocation, new EntityRoleCreateObject()
    {
        Name = "Origin"
    });

    // Add 'Destination' role to simple entity
    await client.Model.CreateEntityRoleAsync(app_info.ID, app_info.Version, simpleEntityIdLocation, new EntityRoleCreateObject()
    {
        Name = "Destination"
    });

    // Add simple entity
    var simpleEntityIdClass = await client.Model.AddEntityAsync(app_info.ID, app_info.Version, new ModelCreateObject()
    {
        Name = "Class"
    });


    // Add prebuilt number and datetime
    await client.Model.AddPrebuiltAsync(app_info.ID, app_info.Version, new List<string>
    {
        "number",
        "datetimeV2",
        "geographyV2",
        "ordinal"
    });

    // Composite entity
    await client.Model.AddCompositeEntityAsync(app_info.ID, app_info.Version, new CompositeEntityModel()
    {
        Name = "Flight",
        Children = new List<string>() { "Location", "Class", "number", "datetimeV2", "geographyV2", "ordinal" }
    });
    Console.WriteLine("Created entities Location, Class, number, datetimeV2, geographyV2, ordinal.");
}

Adicionar exemplo de enunciado para intençãoAdd example utterance to intent

A fim de determinar a intenção de um enunciado e extrair entidades, o aplicativo precisa de exemplos de enunciados.In order to determine an utterance's intention and extract entities, the app needs examples of utterances. Os exemplos precisam ter como destino uma única intenção específica e devem marcar todas as entidades personalizadas.The examples need to target a specific, single intent and should mark all custom entities. As entidades predefinidas não precisam ser marcadas.Prebuilt entities do not need to be marked.

Adicione exemplos de enunciado ao criar uma lista de objetos ExampleLabelObject, um objeto para cada exemplo de enunciado.Add example utterances by creating a list of ExampleLabelObject objects, one object for each example utterance. Cada exemplo deve marcar todas as entidades com um dicionário de pares de nome/valor do nome da entidade e do valor da entidade.Each example should mark all entities with a dictionary of name/value pairs of entity name and entity value. O valor da entidade deve exatamente o mesmo que aparece no texto do exemplo de enunciado.The entity value should be exactly as it appears in the text of the example utterance.

Chame Examples.BatchAsync com a ID do aplicativo, a ID da versão e a lista de exemplos.Call Examples.BatchAsync with the app ID, version ID, and the list of examples. A chamada responde com uma lista de resultados.The call responds with a list of results. Você precisa verificar o resultado de cada exemplo para verificar se ele foi adicionado ao modelo com êxito.You need to check each example's result to make sure it was successfully added to the model.

async static Task AddUtterances(LUISAuthoringClient client, ApplicationInfo app_info)
{
    var utterances = new List<ExampleLabelObject>()
    {
        CreateUtterance ("FindFlights", "find flights in economy to Madrid on July 1st", new Dictionary<string, string>() { {"Flight", "economy to Madrid"}, { "Location", "Madrid" }, { "Class", "economy" } }),
        CreateUtterance ("FindFlights", "find flights from seattle to London in first class", new Dictionary<string, string>() { { "Flight", "London in first class" }, { "Location", "London" }, { "Class", "first" } }),
        CreateUtterance ("FindFlights", "find flights to London in first class", new Dictionary<string, string>()  { { "Flight", "London in first class" }, { "Location", "London" }, { "Class", "first" } }),

        //Role not supported in SDK yet
        //CreateUtterance ("FindFlights", "find flights to Paris in first class", new Dictionary<string, string>()  { { "Flight", "London in first class" }, { "Location::Destination", "Paris" }, { "Class", "first" } })
    };
    var resultsList = await client.Examples.BatchAsync(app_info.ID, app_info.Version, utterances);

    foreach (var x in resultsList)
    {
        var result = (!x.HasError.GetValueOrDefault()) ? "succeeded": "failed";
        Console.WriteLine("{0} {1}", x.Value.ExampleId, result);
    }
}
// Create utterance with marked text for entities
static ExampleLabelObject CreateUtterance(string intent, string utterance, Dictionary<string, string> labels)
{
    var entity_labels = labels.Select(kv => CreateLabel(utterance, kv.Key, kv.Value)).ToList();
    return new ExampleLabelObject()
    {
        IntentName = intent,
        Text = utterance,
        EntityLabels = entity_labels
    };
}
// Mark beginning and ending of entity text in utterance
static EntityLabelObject CreateLabel(string utterance, string key, string value)
{
    var start_index = utterance.IndexOf(value, StringComparison.InvariantCultureIgnoreCase);
    return new EntityLabelObject()
    {
        EntityName = key,
        StartCharIndex = start_index,
        EndCharIndex = start_index + value.Length
    };
}

Os métodos CreateUtterance e CreateLabel são métodos utilitários para ajudá-lo a criar objetos.The CreateUtterance and CreateLabel methods are utility methods to help you create objects.

Treinar o aplicativoTrain the app

Depois que o modelo for criado, o aplicativo LUIS precisará ser treinado para esta versão do modelo.Once the model is created, the LUIS app needs to be trained for this version of the model. Um modelo treinado pode ser usado em um contêiner ou publicado nos slots de preparo ou de produto.A trained model can be used in a container, or published to the staging or product slots.

O método Train.TrainVersionAsync precisa da ID do aplicativo e da ID da versão.The Train.TrainVersionAsync method needs the app ID and the version ID.

Um modelo muito pequeno, como este guia de início rápido mostra, será treinado muito rapidamente.A very small model, such as this quickstart shows, will train very quickly. Para aplicativos de nível de produção, o treinamento do aplicativo deve incluir uma chamada de sondagem para o método GetStatusAsync para determinar quando ou se o treinamento foi bem-sucedido.For production-level applications, training the app should include a polling call to the GetStatusAsync method to determine when or if the training succeeded. A resposta é uma lista de objetos ModelTrainingInfo com um status separado para cada objeto.The response is a list of ModelTrainingInfo objects with a separate status for each object. Todos os objetos devem ter êxito para que o treinamento seja considerado concluído.All objects must be successful for the training to be considered complete.

async static Task Train_App(LUISAuthoringClient client, ApplicationInfo app)
{
    var response = await client.Train.TrainVersionAsync(app.ID, app.Version);
    Console.WriteLine("Training status: " + response.Status);
}

Publicar um aplicativo de Reconhecimento VocalPublish a Language Understanding app

Publique o aplicativo do LUIS usando o método PublishAsync.Publish the LUIS app using the PublishAsync method. Isso publica a versão treinada atual no slot especificado no ponto de extremidade.This publishes the current trained version to the specified slot at the endpoint. Seu aplicativo cliente usa esse ponto de extremidade para enviar enunciados de usuário para previsão de extração de intenção e entidade.Your client application uses this endpoint to send user utterances for prediction of intent and entity extraction.

// Publish app, display endpoint URL for the published application.
async static Task Publish_App(LUISAuthoringClient client, ApplicationInfo app)
{
    ApplicationPublishObject obj = new ApplicationPublishObject
    {
        VersionId = app.Version,
        IsStaging = true
    };
    var info = await client.Apps.PublishAsync(app.ID, obj);
    Console.WriteLine("Endpoint URL: " + info.EndpointUrl);
}

Executar o aplicativoRun the application

Execute o aplicativo com o comando dotnet run do seu próprio diretório de aplicativo.Run the application with the dotnet run command from your application directory.

dotnet run

Limpar os recursosClean up resources

Se você quiser limpar, exclua o aplicativo do LUIS.If you want to clean up, you can delete the LUIS app. A exclusão do aplicativo é feita com o método Apps.DeleteAsync.Deleting the app is done with the Apps.DeleteAsync method. Você também pode excluir o aplicativo do Portal do LUIS.You can also delete the app from the LUIS portal.

Use a biblioteca de clientes de criação do LUIS (Reconhecimento vocal) para Node.js com o objetivo de:Use the Language Understanding (LUIS) authoring client library for Node.js to:

  • Criar um aplicativo.Create an app.
  • Adicionar intenções, entidades e enunciados.Add intents, entities, and example utterances.
  • Adicionar recursos, como uma lista de frases.Add features, such as a phrase list.
  • Treinar e publicar um aplicativo.Train and publish an app.
  • Excluir aplicativoDelete app

Documentação de referência | Código-fonte da biblioteca | Pacote de Criação (NPM), Pacote de Runtime (NPM) | ExemplosReference documentation | Library source code | Authoring Package (NPM), Runtime Package (NPM) | Samples

Pré-requisitosPrerequisites

ConfigurandoSetting up

Obtenha sua chave inicial do LUIS (Reconhecimento vocal)Get your Language Understanding (LUIS) starter key

Obtenha sua chave inicial criando um recurso de criação do LUIS.Get your starter key by creating a LUIS authoring resource. Mantenha sua chave e o ponto de extremidade da chave para a próxima etapa.Keep your key, and the endpoint of the key for the next step.

Criar uma variável de ambienteCreate an environment variable

Usando a chave e a região da chave, crie duas variáveis de ambiente para autenticação:Using your key, and the region for the key, create two environment variables for authentication:

  • LUIS_AUTHORING_KEY – a chave de recurso para autenticar as solicitações.LUIS_AUTHORING_KEY - The resource key for authenticating your requests.
  • LUIS_AUTHORING_ENDPOINT: o ponto de extremidade associado à chave.LUIS_AUTHORING_ENDPOINT - The endpoint associated with your key.

Use as instruções para seu sistema operacional.Use the instructions for your operating system.

setx LUIS_AUTHORING_KEY <replace-with-your-luis-authoring-key
setx LUIS_AUTHORING_ENDPOINT <replace-with-your-luis-authoring-endpoint>

Depois de adicionar a variável de ambiente, reinicie a janela do console.After you add the environment variable, restart the console window.

Instalar a biblioteca do npm para criação do LUISInstall the NPM library for LUIS authoring

No diretório do aplicativo, instale as dependências com o seguinte comando:Within the application directory, install the dependencies with the following command:

npm install @azure/cognitiveservices-luis-authoring @azure/ms-rest-js

Modelo de objetoObject model

O cliente de criação do LUIS (Reconhecimento Vocal) é um objeto LUISAuthoringClient que se autentica no Azure, que contém sua chave de criação.The Language Understanding (LUIS) authoring client is a LUISAuthoringClient object that authenticates to Azure, which contains your authoring key.

Depois que o cliente for criado, use-o para acessar a funcionalidade, incluindo:Once the client is created, use this client to access functionality including:

Exemplos de códigoCode examples

Estes snippets de código mostram como fazer o seguinte com a biblioteca de clientes de criação do LUIS (Reconhecimento vocal) para Node.js:These code snippets show you how to do the following with the Language Understanding (LUIS) authoring client library for Node.js:

Criar um novo aplicativo do Node.jsCreate a new Node.js application

Crie um arquivo de texto em seu editor ou seu IDE preferido chamado luis_authoring_quickstart.js.Create a new text file in your preferred editor or IDE named luis_authoring_quickstart.js. Em seguida, adicione as dependências a seguir.Then add the following dependencies.

const msRest = require("@azure/ms-rest-js");
const LUIS = require("@azure/cognitiveservices-luis-authoring");

Crie variáveis para a chave e o ponto de extremidade do Azure do recurso.Create variables for your resource's Azure endpoint and key. Se você criou a variável de ambiente depois de iniciar o aplicativo, será necessário fechar e recarregar o editor, o IDE ou o shell em execução para acessar a variável.If you created the environment variable after you launched the application, you will need to close and reopen the editor, IDE, or shell running it to access the variable.

const key = 'REPLACE-WITH-YOUR-ASSIGNED-AUTHORING-KEY';

const endpoint = "https://REPLACE-WITH-RESOURCE-NAME.cognitiveservices.azure.com/"

Autenticar o clienteAuthenticate the client

Crie um objeto CognitiveServicesCredentials com a sua chave e use-o com o ponto de extremidade para criar um objeto LUISAuthoringClient.Create an CognitiveServicesCredentials object with your key, and use it with your endpoint to create an LUISAuthoringClient object.

const luisAuthoringCredentials = new msRest.ApiKeyCredentials({
  inHeader: { "Ocp-Apim-Subscription-Key": key }
});
const luisAuthoringClient = new LUIS.LUISAuthoringClient(
  luisAuthoringCredentials,
  endpoint
);

Criar um aplicativo LUISCreate a LUIS app

  1. Crie um aplicativo LUIS para conter o modelo de NLP (processamento de idioma natural) que contém tentativas, entidades e exemplo de enunciados.Create a LUIS app to contain the natural language processing (NLP) model holding intents, entities, and example utterances.

  2. Crie um add objeto AppsOperation para criar o aplicativo.Create a AppsOperation object's add method to create the app. O nome e a cultura do idioma são propriedades obrigatórias.The name and language culture are required properties.

    const create_app = async () => {
      const create_app_payload = {
        name: "Contoso",
        description: "Flight booking app built with Azure SDK for Java.",
        initialVersionId: "0.1",
        culture: "en-us"
      };
    
      const createAppResult = await luisAuthoringClient.apps.add(
        create_app_payload
      );
    
      console.log(`Created LUIS app with ID ${createAppResult.body}`);
    
      return {
        id: createAppResult.body,
        version: create_app_payload.initialVersionId
      };
    }
    

Criar intenção para o aplicativoCreate intent for the app

O objeto principal no modelo de um aplicativo do LUIS é a intenção.The primary object in a LUIS app's model is the intent. A intenção se alinha com um agrupamento de intenções de enunciado do usuário.The intent aligns's with a grouping of user utterance intentions. Um usuário pode fazer uma pergunta ou uma declaração procurando uma resposta desejada específica de um bot (ou outro aplicativo cliente).A user may ask a question, or make a statement looking for a particular intended response from a bot (or other client application). Exemplos de intenções são: reservar um voo, perguntar sobre o tempo em uma cidade de destino e solicitar informações de contato para o atendimento ao cliente.Examples of intentions are booking a flight, asking about weather in a destination city, and asking about contact information for customer service.

Use o método model.add_intent com o nome da intenção exclusiva e, em seguida, passe a ID do aplicativo, a ID da versão e o nome da nova tentativa.Use the model.add_intent method with the name of the unique intent then pass the app ID, version ID, and new intent name.

const add_intents = async app_info => {
  const addIntentFindFlightsResult = await luisAuthoringClient.model.addIntent(
    app_info.id,
    app_info.version,
    { name: "FindFlights" }
  );
  console.log("Intent FindFlights added.");
};

Criar entidades para o aplicativoCreate entities for the app

Embora as entidades não sejam necessárias, são encontradas na maioria dos aplicativos.While entities are not required, they are found in most apps. A entidade extrai informações do enunciado do usuário, necessárias para atender à intenção do usuário.The entity extracts information from the user utterance, necessary to fullfil the user's intention. Há vários tipos de entidades predefinidas e personalizadas, cada uma com seus próprios modelos de DTO (objeto de transformação de dados).There are several types of prebuilt and custom entities, each with their own data transformation object (DTO) models. Entidades predefinidas comuns para adicionar ao seu aplicativo number, datetimeV2, geographyV2, ordinal.Common prebuilt entities to add to your app include number, datetimeV2, geographyV2, ordinal.

Esse método add_entities criou uma entidade simples Location com duas funções, uma entidade simples Class, uma entidade composta Flight e adiciona várias entidades predefinidas.This add_entities method created a Location simple entity with two roles, a Class simple entity, a Flight composite entity and adds several prebuilt entities.

É importante saber que as entidades não estão marcadas com uma intenção.It is important to know that entities are not marked with an intent. Em geral, elas podem se aplicar a muitas intenções.They can and usually do apply to many intents. Somente os exemplos de enunciados de usuário são marcados para uma única intenção específica.Only example user utterances are marked for a specific, single intent.

Os métodos de criação para as entidades fazem parte da classe do Modelo.Creation methods for entities are part of the Model class. Cada tipo de entidade tem seu próprio modelo de DTO (objeto de transformação de dados).Each entity type has its own data transformation object (DTO) model.

const add_entities = async app_info => {
  const addEntityDestinationResult = await luisAuthoringClient.model.addEntity(
    app_info.id,
    app_info.version,
    { name: "Destination" }
  );
  console.log("Entity Destination created.");

  const addEntityClassResult = await luisAuthoringClient.model.addEntity(
    app_info.id,
    app_info.version,
    { name: "Class" }
  );
  console.log("Entity Class created.");

  const addEntityFlightResult = await luisAuthoringClient.model.addEntity(
    app_info.id,
    app_info.version,
    { name: "Flight" }
  );
  console.log("Entity Flight created.");
}

Adicionar exemplo de enunciado para intençãoAdd example utterance to intent

A fim de determinar a intenção de um enunciado e extrair entidades, o aplicativo precisa de exemplos de enunciados.In order to determine an utterance's intention and extract entities, the app needs examples of utterances. Os exemplos precisam ter como destino uma única intenção específica e devem marcar todas as entidades personalizadas.The examples need to target a specific, single intent and should mark all custom entities. As entidades predefinidas não precisam ser marcadas.Prebuilt entities do not need to be marked.

Adicione exemplos de enunciado ao criar uma lista de objetos ExampleLabelObject, um objeto para cada exemplo de enunciado.Add example utterances by creating a list of ExampleLabelObject objects, one object for each example utterance. Cada exemplo deve marcar todas as entidades com um dicionário de pares de nome/valor do nome da entidade e do valor da entidade.Each example should mark all entities with a dictionary of name/value pairs of entity name and entity value. O valor da entidade deve exatamente o mesmo que aparece no texto do exemplo de enunciado.The entity value should be exactly as it appears in the text of the example utterance.

Chame examples.batch com a ID do aplicativo, a ID da versão e a lista de exemplos.Call examples.batch with the app ID, version ID, and the list of examples. A chamada responde com uma lista de resultados.The call responds with a list of results. Você precisa verificar o resultado de cada exemplo para verificar se ele foi adicionado ao modelo com êxito.You need to check each example's result to make sure it was successfully added to the model.

const create_utterance = (intent, text, labels) => {
  var entityLabels = new Array();

  labels.forEach((value, key, map) => {
    const start_index = text.toLowerCase().indexOf(value.toLowerCase());
    const end_index = start_index + value.length;

    if (start_index > -1) {
      entityLabels.push({
        entityName: key,
        startCharIndex: start_index,
        endCharIndex: end_index
      });
    }
  });

  console.log(`Created ${entityLabels.length} entity labels.`);

  return { text: text, entityLabels: entityLabels, intentName: intent };
}

const add_utterances = async app_info => {
  const utterance_1 = create_utterance(
    "FindFlights",
    "find flights in economy to Madrid",
    new Map([
      ["Flight", "economy to Madrid"],
      ["Destination", "Madrid"],
      ["Class", "economy"]
    ])
  );
  const utterance_2 = create_utterance(
    "FindFlights",
    "find flights to London in first class",
    new Map([
      ["Flight", "London in first class"],
      ["Destination", "London"],
      ["Class", "first"]
    ])
  );
  const utterance_3 = create_utterance(
    "FindFlights",
    "find flights from seattle to London in first class",
    new Map([
      ["Flight", "flights from seattle to London in first class"],
      ["Location", "London"],
      ["Location", "Seattle"],
      ["Class", "first"]
    ])
  );

  const luisExamplesBatchResult = await luisAuthoringClient.examples.batch(
    app_info.id,
    app_info.version,
    [utterance_1, utterance_2, utterance_3]
  );
  console.log("Example utterances added.");
}

Treinar o aplicativoTrain the app

Depois que o modelo for criado, o aplicativo LUIS precisará ser treinado para esta versão do modelo.Once the model is created, the LUIS app needs to be trained for this version of the model. Um modelo treinado pode ser usado em um contêiner ou publicado nos slots de preparo ou de produto.A trained model can be used in a container, or published to the staging or product slots.

O método train.trainVersion precisa da ID do aplicativo e da ID da versão.The train.trainVersion method needs the app ID and the version ID.

Um modelo muito pequeno, como este guia de início rápido mostra, será treinado muito rapidamente.A very small model, such as this quickstart shows, will train very quickly. Para aplicativos de nível de produção, o treinamento do aplicativo deve incluir uma chamada de sondagem para o método get_status para determinar quando ou se o treinamento foi bem-sucedido.For production-level applications, training the app should include a polling call to the get_status method to determine when or if the training succeeded. A resposta é uma lista de objetos ModelTrainingInfo com um status separado para cada objeto.The response is a list of ModelTrainingInfo objects with a separate status for each object. Todos os objetos devem ter êxito para que o treinamento seja considerado concluído.All objects must be successful for the training to be considered complete.

const train_app = async app_info => {
  const trainResult = await luisAuthoringClient.train.trainVersion(
    app_info.id,
    app_info.version
  );

  console.log("Waiting for train operation to finish...");

  const operationResult = await wait_for_operation(app_info);
}

O treinamento de todos os modelos leva tempo.Training all models takes time. Use o operationResult para verificar o status do treinamento.Use the operationResult to check the training status.

const wait_for_operation = async app_info => {
  let operationResult = null;
  let modelUniqueStatus = ["InProgress"];

  while (
    modelUniqueStatus.includes("InProgress") ||
    modelUniqueStatus.includes("Queued")
  ) {
    await delayTimer(1000);

    operationResult = await luisAuthoringClient.train.getStatus(
      app_info.id,
      app_info.version
    );

    modelUniqueStatus = [
      ...new Set(operationResult.map(op => op.details.status))
    ];

    console.log(`Current model status: ${JSON.stringify(modelUniqueStatus)}`);
  }

  return operationResult;
}

Publicar um aplicativo de Reconhecimento VocalPublish a Language Understanding app

Publique o aplicativo do LUIS usando o método app.publish.Publish the LUIS app using the app.publish method. Isso publica a versão treinada atual no slot especificado no ponto de extremidade.This publishes the current trained version to the specified slot at the endpoint. Seu aplicativo cliente usa esse ponto de extremidade para enviar enunciados de usuário para previsão de extração de intenção e entidade.Your client application uses this endpoint to send user utterances for prediction of intent and entity extraction.

const publish_app = async app_info => {
  const publishResult = await luisAuthoringClient.apps.publish(app_info.id, {
    versionId: app_info.version,
    isStaging: true
  });

  console.log(
    `Application published. Endpoint URL: ${publishResult.endpointUrl}`
  );
}

Excluir um aplicativo de Reconhecimento vocalDelete a Language Understanding app

Exclua o aplicativo LUIS usando o método app.deleteMethod.Delete the LUIS app using the app.deleteMethod method. Isso excluirá o aplicativo atual.This deletes the current app.

const delete_app = async app_info => {
  const deleteResult = await luisAuthoringClient.apps.deleteMethod(app_info.id);

  console.log(
    `Application with ID ${app_info.id} deleted. Operation result: ${deleteResult.message}`
  );
}

Listar os aplicativos de Reconhecimento vocalList Language understanding apps

Obter uma lista de aplicativos associados à chave do Reconhecimento vocalGet a list of apps associated with the Language understanding key

const list_apps = async () => {
  const apps = await luisAuthoringClient.apps.list;

  for (let app of apps) {
    console.log(`ID ${app.id}, NAME ${app.name}`);
  }
}

Executar o aplicativoRun the application

Execute o aplicativo com o comando node luis_authoring_quickstart.js no seu arquivo de início rápido.Run the application with the node luis_authoring_quickstart.js command on your quickstart file.

node luis_authoring_quickstart.js

A saída da linha de comando do aplicativo é:The command line output of the application is:

Created LUIS app with ID e137a439-b3e0-4e16-a7a8-a9746e0715f7
Entity Destination created.
Entity Class created.
Entity Flight created.
Intent FindFlights added.
Created 3 entity labels.
Created 3 entity labels.
Created 3 entity labels.
Example utterances added.
Waiting for train operation to finish...
Current model status: ["Queued"]
Current model status: ["InProgress"]
Current model status: ["InProgress"]
Current model status: ["InProgress"]
Current model status: ["Success"]
Application published. Endpoint URL: https://westus.api.cognitive.microsoft.com/luis/v2.0/apps/e137a439-b3e0-4e16-a7a8-a9746e0715f7
Application with ID e137a439-b3e0-4e16-a7a8-a9746e0715f7 deleted. Operation result: Operation Successful

Use a biblioteca de clientes de criação de LUIS (Reconhecimento Vocal) para Python com o objetivo de:Use the Language Understanding (LUIS) authoring client library for Python to:

  • Criar um aplicativo.Create an app.
  • Adicionar intenções, entidades e enunciados.Add intents, entities, and example utterances.
  • Adicionar recursos, como uma lista de frases.Add features, such as a phrase list.
  • Treinar e publicar um aplicativo.Train and publish an app.

Documentação de referência | Código-fonte da biblioteca | Pacote de Criação (Pypi) | ExemplosReference documentation | Library source code | Authoring Package (Pypi) | Samples

Pré-requisitosPrerequisites

  • Assinatura do Azure – Criar uma gratuitamenteAzure subscription - Create one for free
  • A versão atual do Python 3.x.The current version of Python 3.x.
  • Quando você tiver sua assinatura do Azure, crie um recurso de criação do Reconhecimento vocal no portal do Azure para obter a chave e o ponto de extremidade.Once you have your Azure subscription, create a Language Understanding authoring resource in the Azure portal to get your key and endpoint. Aguarde até que ele seja implantado e clique no botão Ir para o recurso.Wait for it to deploy and click the Go to resource button.
    • Você precisará da chave e do ponto de extremidade do recurso que você criar para conectar seu aplicativo à criação do Reconhecimento vocal.You will need the key and endpoint from the resource you create to connect your application to Language Understanding authoring. Cole a chave e o ponto de extremidade no código abaixo mais adiante no guia de início rápido.You'll paste your key and endpoint into the code below later in the quickstart. Você pode usar o tipo de preço gratuito (F0) para experimentar o serviço.You can use the free pricing tier (F0) to try the service.

ConfigurandoSetting up

Instalar a biblioteca do Python para LUISInstall the Python library for LUIS

Dentro do diretório do aplicativo, instale a biblioteca de clientes de criação do LUIS (Reconhecimento Vocal) para Python com o seguinte comando:Within the application directory, install the Language Understanding (LUIS) authoring client library for python with the following command:

pip install azure-cognitiveservices-language-luis

Modelo de objetoObject model

O cliente de criação do LUIS (Reconhecimento Vocal) é um objeto LUISAuthoringClient que se autentica no Azure, que contém sua chave de criação.The Language Understanding (LUIS) authoring client is a LUISAuthoringClient object that authenticates to Azure, which contains your authoring key.

Depois que o cliente for criado, use-o para acessar a funcionalidade, incluindo:Once the client is created, use this client to access functionality including:

Exemplos de códigoCode examples

Estes snippets de códigos mostram como fazer o seguinte com a biblioteca de clientes do LUIS (Reconhecimento Vocal) para Python:These code snippets show you how to do the following with the Language Understanding (LUIS) authoring client library for python:

Criar um novo aplicativo PythonCreate a new python application

Crie um novo aplicativo Python em seu IDE ou editor preferido.Create a new Python application in your preferred editor or IDE. Depois, importe as bibliotecas a seguir.Then import the following libraries.

from azure.cognitiveservices.language.luis.authoring import LUISAuthoringClient
from msrest.authentication import CognitiveServicesCredentials

import datetime, json, os, time
authoring_key = 'REPLACE-WITH-YOUR-ASSIGNED-AUTHORING-KEY'

authoring_endpoint = "https://REPLACE-WITH-RESOURCE-NAME.cognitiveservices.azure.com/"

Autenticar o clienteAuthenticate the client

Crie um objeto CognitiveServicesCredentials com a sua chave e use-o com o ponto de extremidade para criar um objeto LUISAuthoringClient.Create an CognitiveServicesCredentials object with your key, and use it with your endpoint to create an LUISAuthoringClient object.

# Instantiate a LUIS client
client = LUISAuthoringClient(authoring_endpoint, CognitiveServicesCredentials(authoring_key))

Criar um aplicativo LUISCreate a LUIS app

  1. Crie um aplicativo LUIS para conter o modelo de NLP (processamento de idioma natural) que contém tentativas, entidades e exemplo de enunciados.Create a LUIS app to contain the natural language processing (NLP) model holding intents, entities, and example utterances.

  2. Crie um add objeto AppsOperation para criar o aplicativo.Create a AppsOperation object's add method to create the app. O nome e a cultura do idioma são propriedades obrigatórias.The name and language culture are required properties.

    def create_app():
        # Create a new LUIS app
        app_name    = "Contoso {}".format(datetime.datetime.now())
        app_desc    = "Flight booking app built with LUIS Python SDK."
        app_version = "0.1"
        app_locale  = "en-us"
    
        app_id = client.apps.add(dict(name=app_name,
                                        initial_version_id=app_version,
                                        description=app_desc,
                                        culture=app_locale))
    
        print("Created LUIS app {}\n    with ID {}".format(app_name, app_id))
        return app_id, app_version
    

Criar intenção para o aplicativoCreate intent for the app

O objeto principal no modelo de um aplicativo do LUIS é a intenção.The primary object in a LUIS app's model is the intent. A intenção se alinha com um agrupamento de intenções de enunciado do usuário.The intent aligns's with a grouping of user utterance intentions. Um usuário pode fazer uma pergunta ou uma declaração procurando uma resposta desejada específica de um bot (ou outro aplicativo cliente).A user may ask a question, or make a statement looking for a particular intended response from a bot (or other client application). Exemplos de intenções são: reservar um voo, perguntar sobre o tempo em uma cidade de destino e solicitar informações de contato para o atendimento ao cliente.Examples of intentions are booking a flight, asking about weather in a destination city, and asking about contact information for customer service.

Use o método model.add_intent com o nome da intenção exclusiva e, em seguida, passe a ID do aplicativo, a ID da versão e o nome da nova tentativa.Use the model.add_intent method with the name of the unique intent then pass the app ID, version ID, and new intent name.

def add_intents(app_id, app_version):
    intentId = client.model.add_intent(app_id, app_version, "FindFlights")

    print("Intent FindFlights {} added.".format(intentId))

Criar entidades para o aplicativoCreate entities for the app

Embora as entidades não sejam necessárias, são encontradas na maioria dos aplicativos.While entities are not required, they are found in most apps. A entidade extrai informações do enunciado do usuário, necessárias para atender à intenção do usuário.The entity extracts information from the user utterance, necessary to fullfil the user's intention. Há vários tipos de entidades predefinidas e personalizadas, cada uma com seus próprios modelos de DTO (objeto de transformação de dados).There are several types of prebuilt and custom entities, each with their own data transformation object (DTO) models. Entidades predefinidas comuns para adicionar ao seu aplicativo number, datetimeV2, geographyV2, ordinal.Common prebuilt entities to add to your app include number, datetimeV2, geographyV2, ordinal.

Esse método add_entities criou uma entidade simples Location com duas funções, uma entidade simples Class, uma entidade composta Flight e adiciona várias entidades predefinidas.This add_entities method created a Location simple entity with two roles, a Class simple entity, a Flight composite entity and adds several prebuilt entities.

É importante saber que as entidades não estão marcadas com uma intenção.It is important to know that entities are not marked with an intent. Em geral, elas podem se aplicar a muitas intenções.They can and usually do apply to many intents. Somente os exemplos de enunciados de usuário são marcados para uma única intenção específica.Only example user utterances are marked for a specific, single intent.

Os métodos de criação para as entidades fazem parte da classe ModelOperations.Creation methods for entities are part of the ModelOperations class. Cada tipo de entidade tem seu próprio modelo de DTO (objeto de transformação de dados).Each entity type has its own data transformation object (DTO) model.

def add_entities(app_id, app_version):

    destinationEntityId = client.model.add_entity(app_id, app_version, name="Destination")
    print("destinationEntityId {} added.".format(destinationEntityId))

    classEntityId = client.model.add_entity(app_id, app_version, name="Class")
    print("classEntityId {} added.".format(classEntityId))

    flightEntityId = client.model.add_entity(app_id, app_version, name="Flight")
    print("flightEntityId {} added.".format(flightEntityId))

Adicionar exemplo de enunciado para intençãoAdd example utterance to intent

A fim de determinar a intenção de um enunciado e extrair entidades, o aplicativo precisa de exemplos de enunciados.In order to determine an utterance's intention and extract entities, the app needs examples of utterances. Os exemplos precisam ter como destino uma única intenção específica e devem marcar todas as entidades personalizadas.The examples need to target a specific, single intent and should mark all custom entities. As entidades predefinidas não precisam ser marcadas.Prebuilt entities do not need to be marked.

Adicione exemplos de enunciado ao criar uma lista de objetos ExampleLabelObject, um objeto para cada exemplo de enunciado.Add example utterances by creating a list of ExampleLabelObject objects, one object for each example utterance. Cada exemplo deve marcar todas as entidades com um dicionário de pares de nome/valor do nome da entidade e do valor da entidade.Each example should mark all entities with a dictionary of name/value pairs of entity name and entity value. O valor da entidade deve exatamente o mesmo que aparece no texto do exemplo de enunciado.The entity value should be exactly as it appears in the text of the example utterance.

Chame examples.batch com a ID do aplicativo, a ID da versão e a lista de exemplos.Call examples.batch with the app ID, version ID, and the list of examples. A chamada responde com uma lista de resultados.The call responds with a list of results. Você precisa verificar o resultado de cada exemplo para verificar se ele foi adicionado ao modelo com êxito.You need to check each example's result to make sure it was successfully added to the model.

def add_utterances(app_id, app_version):
    # Now define the utterances
    utterances = [create_utterance("FindFlights", "find flights in economy to Madrid",
                            ("Flight", "economy to Madrid"),
                            ("Destination", "Madrid"),
                            ("Class", "economy")),

                  create_utterance("FindFlights", "find flights to London in first class",
                            ("Flight", "London in first class"),
                            ("Destination", "London"),
                            ("Class", "first")),

                  create_utterance("FindFlights", "find flights from seattle to London in first class",
                            ("Flight", "flights from seattle to London in first class"),
                            ("Destination", "London"),
                            ("Class", "first"))]

    # Add the utterances in batch. You may add any number of example utterances
    # for any number of intents in one call.
    client.examples.batch(app_id, app_version, utterances)
    print("{} example utterance(s) added.".format(len(utterances)))

Treinar o aplicativoTrain the app

Depois que o modelo for criado, o aplicativo LUIS precisará ser treinado para esta versão do modelo.Once the model is created, the LUIS app needs to be trained for this version of the model. Um modelo treinado pode ser usado em um contêiner ou publicado nos slots de preparo ou de produto.A trained model can be used in a container, or published to the staging or product slots.

O método train.train_version precisa da ID do aplicativo e da ID da versão.The train.train_version method needs the app ID and the version ID.

Um modelo muito pequeno, como este guia de início rápido mostra, será treinado muito rapidamente.A very small model, such as this quickstart shows, will train very quickly. Para aplicativos de nível de produção, o treinamento do aplicativo deve incluir uma chamada de sondagem para o método get_status para determinar quando ou se o treinamento foi bem-sucedido.For production-level applications, training the app should include a polling call to the get_status method to determine when or if the training succeeded. A resposta é uma lista de objetos ModelTrainingInfo com um status separado para cada objeto.The response is a list of ModelTrainingInfo objects with a separate status for each object. Todos os objetos devem ter êxito para que o treinamento seja considerado concluído.All objects must be successful for the training to be considered complete.

def train_app(app_id, app_version):
    response = client.train.train_version(app_id, app_version)
    waiting = True
    while waiting:
        info = client.train.get_status(app_id, app_version)

        # get_status returns a list of training statuses, one for each model. Loop through them and make sure all are done.
        waiting = any(map(lambda x: 'Queued' == x.details.status or 'InProgress' == x.details.status, info))
        if waiting:
            print ("Waiting 10 seconds for training to complete...")
            time.sleep(10)

Publicar um aplicativo de Reconhecimento VocalPublish a Language Understanding app

Publique o aplicativo do LUIS usando o método app.publish.Publish the LUIS app using the app.publish method. Isso publica a versão treinada atual no slot especificado no ponto de extremidade.This publishes the current trained version to the specified slot at the endpoint. Seu aplicativo cliente usa esse ponto de extremidade para enviar enunciados de usuário para previsão de extração de intenção e entidade.Your client application uses this endpoint to send user utterances for prediction of intent and entity extraction.

def publish_app(app_id, app_version):
    responseEndpointInfo = client.apps.publish(app_id, app_version, is_staging=True)
    print("Application published. Endpoint URL: " + responseEndpointInfo.endpoint_url)

Executar o aplicativoRun the application

Execute o aplicativo com o comando python no seu arquivo de início rápido.Run the application with the python command on your quickstart file.

python quickstart-file.py

Limpar os recursosClean up resources

Ao concluir suas previsões, limpe o trabalho deste início rápido excluindo o arquivo e os subdiretórios dele.When you are done with your predictions, clean up the work from this quickstart by deleting the file and its subdirectories.

Próximas etapasNext steps