Schnellstart: LUIS-Erstellungsclientbibliothek (Language Understanding) für PythonQuickstart: Language Understanding (LUIS) authoring client library for Python

Hier finden Sie Informationen zu den ersten Schritten mit der LUIS-Erstellungsclientbibliothek (Language Understanding) für Python.Get started with the Language Understanding (LUIS) authoring client library for python. Führen Sie die nachfolgenden Schritte zum Installieren des Pakets aus, und testen Sie den Beispielcode für grundlegende Aufgaben.Follow these steps to install the package and try out the example code for basic tasks. Language Understanding (LUIS) ermöglicht das Anwenden benutzerdefinierter Machine Learning-Intelligenz auf Benutzertext mit natürlicher Sprache, um die allgemeine Bedeutung vorherzusagen sowie relevante, detaillierte Informationen zu extrahieren.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.

Verwenden Sie die LUIS-Erstellungsclientbibliothek (Language Understanding) für Python für Folgendes:Use the Language Understanding (LUIS) authoring client library for Python to:

  • Erstellen einer AppCreate an app.
  • Hinzufügen von Absichten, Entitäten und BeispieläußerungenAdd intents, entities, and example utterances.
  • Hinzufügen von Features (beispielsweise eine Ausdrucksliste)Add features, such as a phrase list.
  • Trainieren und Veröffentlichen einer AppTrain and publish an app.

Referenzdokumentation | Quellcode der Bibliothek | Erstellungspaket (Pypi) | BeispieleReference documentation | Library source code | Authoring Package (Pypi) | Samples

VoraussetzungenPrerequisites

EinrichtenSetting up

Abrufen Ihres LUIS-Startschlüssels (Language Understanding)Get your Language Understanding (LUIS) starter key

Sie rufen Ihren Startschlüssel ab, indem Sie eine LUIS-Erstellungsressource erstellen.Get your starter key by creating a LUIS authoring resource. Bewahren Sie den Schlüssel und die Region des Schlüssels für den nächsten Schritt auf.Keep your key, and the region of the key for the next step.

Erstellen einer UmgebungsvariablenCreate an environment variable

Erstellen Sie unter Verwendung des Schlüssels und der Region für den Schlüssel zwei Umgebungsvariablen für die Authentifizierung:Using your key, and the region for the key, create two environment variables for authentication:

  • LUIS_AUTHORING_KEY: Der Ressourcenschlüssel zum Authentifizieren Ihrer Anforderungen.LUIS_AUTHORING_KEY - The resource key for authenticating your requests.
  • LUIS_REGION: Region, die Ihrem Schlüssel zugeordnet ist.LUIS_REGION - The region associated with your key. Beispiel: westus.For example westus.

Führen Sie die Schritte für Ihr Betriebssystem aus:Use the instructions for your operating system.

setx LUIS_AUTHORING_KEY <replace-with-your-luis-authoring-key
setx LUIS_REGION <replace-with-your-luis-region>

Starten Sie das Konsolenfenster neu, nachdem Sie die Umgebungsvariable hinzugefügt haben.After you add the environment variable, restart the console window.

Installieren der Python-Bibliothek für LUISInstall the Python library for LUIS

Installieren Sie innerhalb des Anwendungsverzeichnisses die LUIS-Erstellungsclientbibliothek (Language Understanding) für Python mithilfe des folgenden Befehls:Within the application directory, install the Language Understanding (LUIS) authoring client library for python with the following command:

pip install azure-cognitiveservices-language-luis

ObjektmodellObject model

Der LUIS-Erstellungsclient (Language Understanding) ist ein Objekt vom Typ LUISAuthoringClient, das sich bei Azure authentifiziert und Ihren Erstellungsschlüssel enthält.The Language Understanding (LUIS) authoring client is a LUISAuthoringClient object that authenticates to Azure, which contains your authoring key.

Nach der Erstellung des Clients können Sie damit unter anderem auf folgende Funktionen zugreifen:Once the client is created, use this client to access functionality including:

CodebeispieleCode examples

In den bereitgestellten Codeausschnitten wird veranschaulicht, wie Sie die folgenden Vorgänge mit der LUIS-Erstellungsclientbibliothek (Language Understanding) für Python ausführen:These code snippets show you how to do the following with the Language Understanding (LUIS) authoring client library for python:

Erstellen einer neuen Python-AnwendungCreate a new python application

Erstellen Sie eine neue Python-Anwendung in Ihrem bevorzugten Editor oder Ihrer bevorzugten IDE.Create a new Python application in your preferred editor or IDE. Importieren Sie dann die folgenden Bibliotheken:Then import the following libraries.

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

import datetime, json, os, time

Erstellen Sie Variablen für den Azure-Endpunkt und -Schlüssel Ihrer Ressource.Create variables for your resource's Azure endpoint and key. Wenn Sie die Umgebungsvariable nach dem Start der Anwendung erstellt haben, müssen der Editor, die IDE oder die Shell, in dem bzw. der sie ausgeführt wird, geschlossen und erneut geöffnet werden, damit der Zugriff auf die Variable möglich ist.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.

key_var_name = 'LUIS_AUTHORING_KEY'
if not key_var_name in os.environ:
    raise Exception('Please set/export the environment variable: {}'.format(key_var_name))
authoring_key = os.environ[key_var_name]

endpoint_var_name = 'LUIS_AUTHORING_ENDPOINT'
if not endpoint_var_name in os.environ:
    raise Exception('Please set/export the environment variable: {}'.format(endpoint_var_name))
endpoint = os.environ[endpoint_var_name]

Authentifizieren des ClientsAuthenticate the client

Erstellen Sie ein Objekt vom Typ CognitiveServicesCredentials mit Ihrem Schlüssel, und verwenden Sie es mit Ihrem Endpunkt, um ein Objekt vom Typ LUISAuthoringClient zu erstellen.Create an CognitiveServicesCredentials object with your key, and use it with your endpoint to create an LUISAuthoringClient object.

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

Erstellen einer LUIS-AppCreate a LUIS app

  1. Erstellen Sie eine LUIS-App für das NLP-Modell (Natural Language Processing, Verarbeitung natürlicher Sprache) mit Absichten, Entitäten und Beispieläußerungen.Create a LUIS app to contain the natural language processing (NLP) model holding intents, entities, and example utterances.

  2. Erstellen Sie zum Generieren der App eine Methode vom Typ add für das AppsOperation-Objekt.Create a AppsOperation object's add method to create the app. Name und Sprachkultur sind erforderliche Eigenschaften.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
    

Erstellen der Absicht für die AppCreate intent for the app

Das primäre Objekt im Modell einer LUIS-App ist die Absicht.The primary object in a LUIS app's model is the intent. Die Absicht orientiert sich an einer Gruppierung der Absichten von Benutzeräußerungen.The intent aligns's with a grouping of user utterance intentions. Ein Benutzer kann eine Frage stellen oder etwas sagen, um eine bestimmte beabsichtigte Antwort von einem Bot (oder von einer anderen Clientanwendung) zu erhalten.A user may ask a question, or make a statement looking for a particular intended response from a bot (or other client application). Beispiele für Absichten wären etwa das Buchen eines Flugs, das Einholen von Wetterinformationen für eine Zielstadt oder das Erfragen von Kontaktinformationen für den Kundendienst.Examples of intentions are booking a flight, asking about weather in a destination city, and asking about contact information for customer service.

Verwenden Sie die Methode model.add_intent mit dem Namen der eindeutigen Absicht, und übergeben Sie anschließend die App-ID, die Versions-ID und den Namen der neuen Absicht.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))

Erstellen von Entitäten für die AppCreate entities for the app

Entitäten sind zwar nicht erforderlich, aber in den meisten Apps vorhanden.While entities are not required, they are found in most apps. Die Entität extrahiert Informationen aus der Benutzeräußerung, die zur Erfüllung der Absicht des Benutzers erforderlich sind.The entity extracts information from the user utterance, necessary to fullfil the user's intention. Es gibt mehrere Arten von vordefinierten und benutzerdefinierten Entitäten, die jeweils über ein eigenes DTO-Modell (Data Transformation Object) verfügen.There are several types of prebuilt and custom entities, each with their own data transformation object (DTO) models. Zu den gängigen vordefinierten Entitäten, die Sie Ihrer App hinzufügen können, zählen etwa number, datetimeV2, geographyV2 und ordinal.Common prebuilt entities to add to your app include number, datetimeV2, geographyV2, ordinal.

Diese Methode vom Typ add_entities hat die einfache Entität Location mit zwei Rollen, die einfache Entität Class und die zusammengesetzte Entität Flight erstellt und fügt mehrere vordefinierte Entitäten hinzu.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.

Wichtig: Entitäten sind nicht mit einer Absicht gekennzeichnet.It is important to know that entities are not marked with an intent. Sie gelten in der Regel für mehrere Absichten.They can and usually do apply to many intents. Nur exemplarische Benutzeräußerungen sind für eine bestimmte, einzelne Absicht gekennzeichnet.Only example user utterances are marked for a specific, single intent.

Erstellungsmethoden für Entitäten sind Teil der Klasse ModelOperations.Creation methods for entities are part of the ModelOperations class. Jeder Entitätstyp verfügt über ein eigenes DTO-Modell (Data Transformation Object).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)) 

Hinzufügen einer Beispieläußerung zu einer AbsichtAdd example utterance to intent

Um die Absicht einer Äußerung ermitteln und Entitäten extrahieren zu können, benötigt die App Beispiele für Äußerungen.In order to determine an utterance's intention and extract entities, the app needs examples of utterances. Die Beispiele müssen auf eine bestimmte, einzelne Absicht ausgerichtet sein und alle benutzerdefinierten Entitäten markieren.The examples need to target a specific, single intent and should mark all custom entities. Vordefinierte Entitäten müssen nicht markiert werden.Prebuilt entities do not need to be marked.

Fügen Sie Beispieläußerungen hinzu, indem Sie eine Liste mit Objekten vom Typ ExampleLabelObject erstellen (jeweils ein Objekt pro Beispieläußerung).Add example utterances by creating a list of ExampleLabelObject objects, one object for each example utterance. Jedes Beispiel muss alle Entitäten mit einem Wörterbuch mit Name-Wert-Paaren (Entitätsname und Entitätswert) markieren.Each example should mark all entities with a dictionary of name/value pairs of entity name and entity value. Der Entitätswert muss exakt dem Vorkommen im Text der Beispieläußerung entsprechen.The entity value should be exactly as it appears in the text of the example utterance.

Rufen Sie examples.batch mit der App-ID, der Versions-ID und der Liste mit Beispielen auf.Call examples.batch with the app ID, version ID, and the list of examples. Daraufhin wird eine Liste mit Ergebnissen zurückgegeben.The call responds with a list of results. Überprüfen Sie das Ergebnis der einzelnen Beispiele, um sich zu vergewissern, dass es dem Modell erfolgreich hinzugefügt wurde.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)))

Trainieren der AppTrain the app

Nach Erstellung des Modells muss die LUIS-App für diese Version des Modells trainiert werden.Once the model is created, the LUIS app needs to be trained for this version of the model. Ein trainiertes Modell kann in einem Container verwendet oder in den Staging- oder Produktslots veröffentlicht werden.A trained model can be used in a container, or published to the staging or product slots.

Für die Methode train.train_version müssen die App-ID und die Versions-ID angegeben werden.The train.train_version method needs the app ID and the version ID.

Bei sehr kleinen Modellen (wie etwa in dieser Schnellstartanleitung) dauert das Training nicht sehr lang.A very small model, such as this quickstart shows, will train very quickly. Bei Produktionsanwendungen muss das App-Training auch einen Abfrageaufruf für die Methode get_status enthalten, um zu bestimmen, wann bzw. ob das Training erfolgreich war.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. Die Antwort ist eine Liste mit Objekten vom Typ ModelTrainingInfo, die jeweils einen separaten Status für die einzelnen Objekte besitzen.The response is a list of ModelTrainingInfo objects with a separate status for each object. Alle Objekte müssen erfolgreich sein, damit das Training als abgeschlossen gilt.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)

Veröffentlichen einer Language Understanding-AppPublish a Language Understanding app

Veröffentlichen Sie die LUIS-App mithilfe der Methode app.publish.Publish the LUIS app using the app.publish method. Dadurch wird die aktuelle trainierte Version im angegebenen Slot am Endpunkt veröffentlicht.This publishes the current trained version to the specified slot at the endpoint. Ihre Clientanwendung verwendet diesen Endpunkt zum Senden von Benutzeräußerungen für die Absichtsvorhersage und die Entitätsextraktion.Your client application uses this endpoint to send user utterances for prediction of intent and entity extraction.

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

Ausführen der AnwendungRun the application

Führen Sie die Anwendung mit dem Befehl python für die Schnellstartdatei aus.Run the application with the python command on your quickstart file.

python quickstart-file.py

Bereinigen von RessourcenClean up resources

Wenn Sie ein Cognitive Services-Abonnement bereinigen und entfernen möchten, können Sie die Ressource oder die Ressourcengruppe löschen.If you want to clean up and remove a Cognitive Services subscription, you can delete the resource or resource group. Wenn Sie die Ressourcengruppe löschen, werden auch alle anderen Ressourcen gelöscht, die ihr zugeordnet sind.Deleting the resource group also deletes any other resources associated with it.

Nächste SchritteNext steps