Delen via

  • Artikel

Buildstatus

Azure Conversational Language Understanding-clientbibliotheek voor Python - versie 1.1.0

Conversational Language Understanding, ook wel CLU genoemd, is een cloudgebaseerde AI-service voor gesprekken die veel mogelijkheden voor taalbegrip biedt, zoals:

  • Gespreks-app: deze wordt gebruikt bij het extraheren van intenties en entiteiten in gesprekken
  • Werkstroom-app: fungeert als een orchestrator om de beste kandidaat te selecteren om gesprekken te analyseren om de beste reactie te krijgen van apps zoals Qna, Luis en Gespreks-app
  • Gesprekssamenvatting: wordt gebruikt voor het analyseren van gesprekken in de vorm van problemen/oplossing, hoofdstuktitel en samenvattingen van verhalen

Broncode | Pakket (PyPI) | Pakket (Conda) | API-referentiedocumentatie | Monsters | Productdocumentatie | REST API-documentatie

Aan de slag

Vereisten

Het pakket installeren

Installeer de Azure Conversations-clientbibliotheek voor Python met pip:

pip install azure-ai-language-conversations

Opmerking: deze versie van de clientbibliotheek is standaard ingesteld op versie 2023-04-01 van de service

De client verifiëren

Als u wilt communiceren met de CLU-service, moet u een exemplaar van de klasse ConversationAnalysisClient of de klasse ConversationAuthoringClient maken. U hebt een eindpunt en een API-sleutel nodig om een clientobject te instantiëren. Zie Aanvragen verifiëren bij Azure Cognitive Services voor meer informatie over verificatie met Cognitive Services.

Een API-sleutel ophalen

U kunt het eindpunt en een API-sleutel ophalen uit de Cognitive Services-resource in Azure Portal.

U kunt ook de Azure CLI-opdracht gebruiken die hieronder wordt weergegeven om de API-sleutel op te halen uit de Cognitive Service-resource.

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

ConversationAnalysisClient maken

Zodra u uw eindpunt en API-sleutel hebt bepaald, kunt u een ConversationAnalysisClientinstantiëren:

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)

ConversationAuthoringClient maken

Zodra u uw eindpunt en API-sleutel hebt bepaald, kunt u een ConversationAuthoringClientinstantiëren:

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)

Een client maken met een Azure Active Directory-referentie

Als u een AAD-tokenreferentie (Azure Active Directory) wilt gebruiken, geeft u een exemplaar op van het gewenste referentietype dat is verkregen uit de azure-identity-bibliotheek . Regionale eindpunten bieden geen ondersteuning voor AAD-verificatie. Maak een aangepaste subdomeinnaam voor uw resource om dit type verificatie te kunnen gebruiken.

Voor verificatie met AAD is enige initiële installatie vereist:

Na de installatie kunt u kiezen welk type referentie van azure.identity u wilt gebruiken. Als voorbeeld kan DefaultAzureCredential worden gebruikt om de client te verifiëren:

Stel de waarden van de client-id, tenant-id en clientgeheim van de AAD-toepassing in als omgevingsvariabelen: AZURE_CLIENT_ID, , AZURE_TENANT_IDAZURE_CLIENT_SECRET

Gebruik de geretourneerde tokenreferentie om de client te verifiëren:

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)

Belangrijkste concepten

ConversationAnalysisClient

De ConversationAnalysisClient is de primaire interface voor het maken van voorspellingen met behulp van uw geïmplementeerde gesprekkenmodellen. Voor asynchrone bewerkingen bevindt een asynchroon ConversationAnalysisClient zich in de azure.ai.language.conversation.aio naamruimte.

ConversationAuthoringClient

U kunt de ConversationAuthoringClient gebruiken om te communiceren met de Azure Language Portal om ontwerpbewerkingen uit te voeren op uw taalresource/-project. U kunt het bijvoorbeeld gebruiken om een project te maken, trainingsgegevens in te vullen, te trainen, te testen en te implementeren. Voor asynchrone bewerkingen bevindt een asynchroon ConversationAuthoringClient zich in de azure.ai.language.conversation.authoring.aio naamruimte.

Voorbeelden

De azure-ai-language-conversation clientbibliotheek biedt zowel synchrone als asynchrone API's.

In de volgende voorbeelden ziet u veelvoorkomende scenario's met behulp van de clienthierboven gemaakte scenario's.

Tekst analyseren met een gespreks-app

Als u aangepaste intenties en entiteiten wilt extraheren uit een gebruikersuiting, kunt u de methode als volgt aanroepen met de client.analyze_conversation() projectnaam van uw gesprek:

# 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"]))

Tekst analyseren met een Orchestration-app

Als u de uiting van de gebruiker wilt doorgeven aan uw orchestrator-app (worflow), kunt u de methode aanroepen met de client.analyze_conversation() projectnaam van uw indeling. Het orchestratorproject organiseert eenvoudigweg de ingediende gebruikersuiting tussen uw taal-apps (Luis, Gesprek en Vraag beantwoorden) om het beste antwoord te krijgen op basis van de intentie van de gebruiker. Zie het volgende voorbeeld:

# 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))

Samenvatting van gesprekken

U kunt dit voorbeeld gebruiken als u een gesprek wilt samenvatten in de vorm van een probleem en de uiteindelijke oplossing. Bijvoorbeeld een dialoogvenster van technische ondersteuning:

# 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']}")

Een gespreksproject importeren

In dit voorbeeld ziet u een veelvoorkomend scenario voor het ontwerponderdeel van de 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)

Optionele configuratie

Optionele trefwoordargumenten kunnen worden doorgegeven op het niveau van de client en per bewerking. In de referentiedocumentatie voor Azure Core worden de beschikbare configuraties beschreven voor nieuwe pogingen, logboekregistratie, transportprotocollen en meer.

Problemen oplossen

Algemeen

De Gesprekken-client genereert uitzonderingen die zijn gedefinieerd in Azure Core.

Logboekregistratie

Deze bibliotheek gebruikt de standaardbibliotheek voor logboekregistratie voor logboekregistratie. Basisinformatie over HTTP-sessies (URL's, headers, enzovoort) wordt geregistreerd op INFO-niveau.

Gedetailleerde logboekregistratie op foutopsporingsniveau, inclusief aanvraag-/antwoordteksten en niet-geredigeerde headers, kan worden ingeschakeld op een client met het logging_enable argument .

Zie hier de volledige documentatie voor SDK-logboekregistratie met voorbeelden.

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(...)

Op dezelfde manier kan logging_enable logboekregistratie voor één bewerking inschakelen, zelfs wanneer dit niet is ingeschakeld voor de client:

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

Volgende stappen

Meer voorbeeldcode

Zie de Voorbeeld-LEESMIJ voor verschillende codefragmenten die algemene patronen illustreren die worden gebruikt in de CLU Python-API.

Bijdragen

Zie de CONTRIBUTING.md voor meer informatie over het bouwen, testen en bijdragen aan deze bibliotheek.

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar cla.microsoft.com voor meer informatie.

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit maar eenmaal te doen voor alle repo's waar gebruik wordt gemaakt van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Zie voor meer informatie de veelgestelde vragen over de gedragscode of neem contact op opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.

Weergaven