• Artikel

Buildstatus

Azure Conversational Language Understanding-Clientbibliothek für Python– Version 1.1.0

Conversational Language Understanding – kurz CLU – ist ein cloudbasierter Ki-Dienst für Unterhaltungen, der viele Sprachverständnisfunktionen bietet, z. B.:

  • Konversations-App: Sie wird zum Extrahieren von Absichten und Entitäten in Unterhaltungen verwendet.
  • Workflow-App: Fungiert wie ein Orchestrator, um den besten Kandidaten für die Analyse von Unterhaltungen auszuwählen, um die beste Antwort von Apps wie Qna, Luis und Conversation App zu erhalten
  • Konversationszusammenfassung: Wird verwendet, um Unterhaltungen in Form von Problemen/Lösungen, Kapiteltiteln und narrativen Zusammenfassungen zu analysieren

Quellcode | Paket (PyPI) | Paket (Conda) | API-Referenzdokumentation | Proben | Produktdokumentation | DOKUMENTATION ZUR REST-API

Erste Schritte

Voraussetzungen

Installieren des Pakets

Installieren Sie die Azure Conversations-Clientbibliothek für Python mit pip:

pip install azure-ai-language-conversations

Hinweis: Diese Version der Clientbibliothek ist standardmäßig auf die Version 2023-04-01 des Diensts festgelegt.

Authentifizieren des Clients

Um mit dem CLU-Dienst zu interagieren, müssen Sie eine instance der ConversationAnalysisClient-Klasse oder der ConversationAuthoringClient-Klasse erstellen. Sie benötigen einen Endpunkt und einen API-Schlüssel , um ein Clientobjekt zu instanziieren. Weitere Informationen zur Authentifizierung mit Cognitive Services finden Sie unter Authentifizieren von Anforderungen an Azure Cognitive Services.

Abrufen eines API-Schlüssels

Sie können den Endpunkt und einen API-Schlüssel aus der Cognitive Services-Ressource im Azure-Portal abrufen.

Alternativ können Sie den unten gezeigten Azure CLI-Befehl verwenden, um den API-Schlüssel aus der Cognitive Service-Ressource abzurufen.

az cognitiveservices account keys list --resource-group <resource-group-name> --name <resource-name>

Erstellen von ConversationAnalysisClient

Nachdem Sie Ihren Endpunkt und API-Schlüssel ermittelt haben, können Sie einen ConversationAnalysisClientinstanziieren:

from azure.core.credentials import AzureKeyCredential
from azure.ai.language.conversations import ConversationAnalysisClient

endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api-key>")
client = ConversationAnalysisClient(endpoint, credential)

Erstellen von ConversationAuthoringClient

Nachdem Sie Ihren Endpunkt und API-Schlüssel ermittelt haben, können Sie einen ConversationAuthoringClientinstanziieren:

from azure.core.credentials import AzureKeyCredential
from azure.ai.language.conversations.authoring import ConversationAuthoringClient

endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api-key>")
client = ConversationAuthoringClient(endpoint, credential)

Erstellen eines Clients mit Azure Active Directory-Anmeldeinformationen

Um Azure Active Directory-Tokenanmeldeinformationen (AAD) zu verwenden, geben Sie eine instance des gewünschten Anmeldeinformationstyps an, der aus der Azure-Identity-Bibliothek abgerufen wird. Beachten Sie, dass regionale Endpunkte die AAD-Authentifizierung nicht unterstützen. Erstellen Sie einen benutzerdefinierten Unterdomänennamen für Ihre Ressource, um diese Art der Authentifizierung zu verwenden.

Die Authentifizierung mit AAD erfordert eine anfängliche Einrichtung:

Nach dem Setup können Sie auswählen, welcher Typ von Anmeldeinformationen aus azure.identity verwendet werden soll. Als Beispiel kann DefaultAzureCredential verwendet werden, um den Client zu authentifizieren:

Legen Sie die Werte der Client-ID, mandanten-ID und des geheimen Clientschlüssels der AAD-Anwendung als Umgebungsvariablen fest: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Verwenden Sie die zurückgegebenen Tokenanmeldeinformationen, um den Client zu authentifizieren:

from azure.ai.language.conversations import ConversationAnalysisClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
client = ConversationAnalysisClient(endpoint="https://<my-custom-subdomain>.cognitiveservices.azure.com/", credential=credential)

Wichtige Begriffe

ConversationAnalysisClient

ConversationAnalysisClient ist die primäre Schnittstelle zum Treffen von Vorhersagen mithilfe Ihrer bereitgestellten Konversationsmodelle. Bei asynchronen Vorgängen befindet sich im Namespace eine asynchrone ConversationAnalysisClientazure.ai.language.conversation.aio .

ConversationAuthoringClient

Sie können conversationAuthoringClient verwenden, um eine Schnittstelle mit dem Azure-Sprachportal zu erstellen, um Erstellungsvorgänge für Ihre Sprachressource/Ihr Sprachprojekt durchzuführen. Sie können es beispielsweise verwenden, um ein Projekt zu erstellen, mit Trainingsdaten aufzufüllen, zu trainieren, zu testen und bereitzustellen. Bei asynchronen Vorgängen befindet sich im Namespace eine asynchrone ConversationAuthoringClientazure.ai.language.conversation.authoring.aio .

Beispiele

Die azure-ai-language-conversation Clientbibliothek stellt synchrone und asynchrone APIs bereit.

Die folgenden Beispiele zeigen häufige Szenarien mit dem clientoben erstellten.

Analysieren von Text mit einer Konversations-App

Wenn Sie benutzerdefinierte Absichten und Entitäten aus einer Benutzeräußerung extrahieren möchten, können Sie die Methode mit dem client.analyze_conversation() Projektnamen Ihrer Unterhaltung wie folgt aufrufen:

# import libraries
import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.conversations import ConversationAnalysisClient

# get secrets
clu_endpoint = os.environ["AZURE_CONVERSATIONS_ENDPOINT"]
clu_key = os.environ["AZURE_CONVERSATIONS_KEY"]
project_name = os.environ["AZURE_CONVERSATIONS_PROJECT_NAME"]
deployment_name = os.environ["AZURE_CONVERSATIONS_DEPLOYMENT_NAME"]

# analyze quey
client = ConversationAnalysisClient(clu_endpoint, AzureKeyCredential(clu_key))
with client:
    query = "Send an email to Carol about the tomorrow's demo"
    result = client.analyze_conversation(
        task={
            "kind": "Conversation",
            "analysisInput": {
                "conversationItem": {
                    "participantId": "1",
                    "id": "1",
                    "modality": "text",
                    "language": "en",
                    "text": query
                },
                "isLoggingEnabled": False
            },
            "parameters": {
                "projectName": project_name,
                "deploymentName": deployment_name,
                "verbose": True
            }
        }
    )

# view result
print("query: {}".format(result["result"]["query"]))
print("project kind: {}\n".format(result["result"]["prediction"]["projectKind"]))

print("top intent: {}".format(result["result"]["prediction"]["topIntent"]))
print("category: {}".format(result["result"]["prediction"]["intents"][0]["category"]))
print("confidence score: {}\n".format(result["result"]["prediction"]["intents"][0]["confidenceScore"]))

print("entities:")
for entity in result["result"]["prediction"]["entities"]:
    print("\ncategory: {}".format(entity["category"]))
    print("text: {}".format(entity["text"]))
    print("confidence score: {}".format(entity["confidenceScore"]))
    if "resolutions" in entity:
        print("resolutions")
        for resolution in entity["resolutions"]:
            print("kind: {}".format(resolution["resolutionKind"]))
            print("value: {}".format(resolution["value"]))
    if "extraInformation" in entity:
        print("extra info")
        for data in entity["extraInformation"]:
            print("kind: {}".format(data["extraInformationKind"]))
            if data["extraInformationKind"] == "ListKey":
                print("key: {}".format(data["key"]))
            if data["extraInformationKind"] == "EntitySubtype":
                print("value: {}".format(data["value"]))

Analysieren von Text mit einer Orchestrierungs-App

Wenn Sie die Benutzeräußerung an Ihre Orchestrator-App (worflow) übergeben möchten, können Sie die Methode mit dem client.analyze_conversation() Projektnamen Ihrer Orchestrierung aufrufen. Das Orchestratorprojekt orchestriert einfach die übermittelte Benutzeräußerung zwischen Ihren Sprach-Apps (Luis, Konversation und Frageantwort), um die beste Antwort gemäß der Benutzerabsicht zu erhalten. Sehen Sie sich das nächste Beispiel an:

# import libraries
import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.conversations import ConversationAnalysisClient

# get secrets
clu_endpoint = os.environ["AZURE_CONVERSATIONS_ENDPOINT"]
clu_key = os.environ["AZURE_CONVERSATIONS_KEY"]
project_name = os.environ["AZURE_CONVERSATIONS_WORKFLOW_PROJECT_NAME"]
deployment_name = os.environ["AZURE_CONVERSATIONS_WORKFLOW_DEPLOYMENT_NAME"]

# analyze query
client = ConversationAnalysisClient(clu_endpoint, AzureKeyCredential(clu_key))
with client:
    query = "Reserve a table for 2 at the Italian restaurant"
    result = client.analyze_conversation(
        task={
            "kind": "Conversation",
            "analysisInput": {
                "conversationItem": {
                    "participantId": "1",
                    "id": "1",
                    "modality": "text",
                    "language": "en",
                    "text": query
                },
                "isLoggingEnabled": False
            },
            "parameters": {
                "projectName": project_name,
                "deploymentName": deployment_name,
                "verbose": True
            }
        }
    )

# view result
print("query: {}".format(result["result"]["query"]))
print("project kind: {}\n".format(result["result"]["prediction"]["projectKind"]))

# top intent
top_intent = result["result"]["prediction"]["topIntent"]
print("top intent: {}".format(top_intent))
top_intent_object = result["result"]["prediction"]["intents"][top_intent]
print("confidence score: {}".format(top_intent_object["confidenceScore"]))
print("project kind: {}".format(top_intent_object["targetProjectKind"]))

if top_intent_object["targetProjectKind"] == "Luis":
    print("\nluis response:")
    luis_response = top_intent_object["result"]["prediction"]
    print("top intent: {}".format(luis_response["topIntent"]))
    print("\nentities:")
    for entity in luis_response["entities"]:
        print("\n{}".format(entity))

Konversationszusammenfassung

Sie können dieses Beispiel verwenden, wenn Sie eine Unterhaltung in Form eines Problems und einer endgültigen Lösung zusammenfassen müssen. Beispielsweise ein Dialog vom technischen Support:

# import libraries
import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.conversations import ConversationAnalysisClient
# get secrets
endpoint = os.environ["AZURE_CONVERSATIONS_ENDPOINT"]
key = os.environ["AZURE_CONVERSATIONS_KEY"]
# analyze query
client = ConversationAnalysisClient(endpoint, AzureKeyCredential(key))
with client:
    poller = client.begin_conversation_analysis(
        task={
            "displayName": "Analyze conversations from xxx",
            "analysisInput": {
                "conversations": [
                    {
                        "conversationItems": [
                            {
                                "text": "Hello, how can I help you?",
                                "modality": "text",
                                "id": "1",
                                "participantId": "Agent"
                            },
                            {
                                "text": "How to upgrade Office? I am getting error messages the whole day.",
                                "modality": "text",
                                "id": "2",
                                "participantId": "Customer"
                            },
                            {
                                "text": "Press the upgrade button please. Then sign in and follow the instructions.",
                                "modality": "text",
                                "id": "3",
                                "participantId": "Agent"
                            }
                        ],
                        "modality": "text",
                        "id": "conversation1",
                        "language": "en"
                    },
                ]
            },
            "tasks": [
                {
                    "taskName": "Issue task",
                    "kind": "ConversationalSummarizationTask",
                    "parameters": {
                        "summaryAspects": ["issue"]
                    }
                },
                {
                    "taskName": "Resolution task",
                    "kind": "ConversationalSummarizationTask",
                    "parameters": {
                        "summaryAspects": ["resolution"]
                    }
                },
            ]
        }
    )

    # view result
    result = poller.result()
    task_results = result["tasks"]["items"]
    for task in task_results:
        print(f"\n{task['taskName']} status: {task['status']}")
        task_result = task["results"]
        if task_result["errors"]:
            print("... errors occurred ...")
            for error in task_result["errors"]:
                print(error)
        else:
            conversation_result = task_result["conversations"][0]
            if conversation_result["warnings"]:
                print("... view warnings ...")
                for warning in conversation_result["warnings"]:
                    print(warning)
            else:
                summaries = conversation_result["summaries"]
                print("... view task result ...")
                for summary in summaries:
                    print(f"{summary['aspect']}: {summary['text']}")

Importieren eines Konversationsprojekts

Dieses Beispiel zeigt ein gängiges Szenario für den Erstellungsteil des SDK.

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.conversations.authoring import ConversationAuthoringClient

clu_endpoint = os.environ["AZURE_CONVERSATIONS_ENDPOINT"]
clu_key = os.environ["AZURE_CONVERSATIONS_KEY"]

project_name = "test_project"

exported_project_assets = {
    "projectKind": "Conversation",
    "intents": [{"category": "Read"}, {"category": "Delete"}],
    "entities": [{"category": "Sender"}],
    "utterances": [
        {
            "text": "Open Blake's email",
            "dataset": "Train",
            "intent": "Read",
            "entities": [{"category": "Sender", "offset": 5, "length": 5}],
        },
        {
            "text": "Delete last email",
            "language": "en-gb",
            "dataset": "Test",
            "intent": "Delete",
            "entities": [],
        },
    ],
}

client = ConversationAuthoringClient(
    clu_endpoint, AzureKeyCredential(clu_key)
)
poller = client.begin_import_project(
    project_name=project_name,
    project={
        "assets": exported_project_assets,
        "metadata": {
            "projectKind": "Conversation",
            "settings": {"confidenceThreshold": 0.7},
            "projectName": "EmailApp",
            "multilingual": True,
            "description": "Trying out CLU",
            "language": "en-us",
        },
        "projectFileVersion": "2022-05-01",
    },
)
response = poller.result()
print(response)

Optionale Konfiguration

Optionale Schlüsselwort (keyword) Argumente können auf Client- und Vorgangsebene übergeben werden. Die azure-core-Referenzdokumentation beschreibt verfügbare Konfigurationen für Wiederholungen, Protokollierung, Transportprotokolle und vieles mehr.

Problembehandlung

Allgemein

Der Conversations-Client löst die in Azure Core definierten Ausnahmen aus.

Protokollierung

Diese Bibliothek verwendet die Standardprotokollierungsbibliothek für die Protokollierung. Grundlegende Informationen zu HTTP-Sitzungen (URLs, Header usw.) werden auf INFO-Ebene protokolliert.

Eine detaillierte Protokollierung auf DEBUG-Ebene, einschließlich Anforderungs-/Antworttexten und nicht ausgeführten Headern, kann auf einem Client mit dem logging_enable Argument aktiviert werden.

Sehen Sie sich die vollständige SDK-Protokollierungsdokumentation mit Beispielen hier an.

import sys
import logging
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.conversations import ConversationAnalysisClient

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<my-api-key>")

# This client will log detailed information about its HTTP sessions, at DEBUG level
client = ConversationAnalysisClient(endpoint, credential, logging_enable=True)
result = client.analyze_conversation(...)

Ebenso kann über logging_enable die ausführliche Protokollierung für einen einzelnen Vorgang aktiviert werden, auch wenn diese Funktion für den Client nicht aktiviert ist:

result = client.analyze_conversation(..., logging_enable=True)

Nächste Schritte

Weiterer Beispielcode

In der Readme-Beispieldatei finden Sie mehrere Codeausschnitte, die gängige Muster veranschaulichen, die in der CLU-Python-API verwendet werden.

Mitwirken

Weitere Informationen zum Erstellen, Testen und Mitwirken zu dieser Bibliothek finden Sie im CONTRIBUTING.md .

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Aufrufe