• Článek

Stav sestavení

Klientská knihovna Azure Conversational Language Understanding pro Python – verze 1.1.0

Konverzační Language Understanding – zkráceně CLU – je cloudová konverzační služba AI, která poskytuje mnoho funkcí pro porozumění jazyku, jako jsou:

  • Konverzační aplikace: Používá se při extrahování záměrů a entit v konverzacích.
  • Aplikace pracovního postupu: Funguje jako orchestrátor, který vybere nejlepšího kandidáta pro analýzu konverzací a získá nejlepší odezvu z aplikací, jako jsou Qna, Luis a Conversation App.
  • Shrnutí konverzací: Používá se k analýze konverzací ve formě problémů a řešení, nadpisu kapitoly a shrnutí vyprávění.

Zdrojový kód | Balíček (PyPI) | Balíček (Conda) | Referenční dokumentace k | rozhraní API Vzorky | Dokumentace k | produktu Dokumentace k rozhraní REST API

Začínáme

Požadavky

Instalace balíčku

Nainstalujte klientskou knihovnu Azure Conversations pro Python pomocí pipu:

pip install azure-ai-language-conversations

Poznámka: Tato verze klientské knihovny má výchozí verzi služby z 2023-04-01.

Ověření klienta

Abyste mohli pracovat se službou CLU, budete muset vytvořit instanci třídy ConversationAnalysisClient nebo Třídy ConversationAuthoringClient . K vytvoření instance objektu klienta budete potřebovat koncový bod a klíč rozhraní API . Další informace o ověřování pomocí služeb Cognitive Services najdete v tématu Ověřování požadavků do služeb Azure Cognitive Services.

Získání klíče rozhraní API

Koncový bod a klíč rozhraní API můžete získat z prostředku Cognitive Services na webu Azure Portal.

Případně můžete pomocí následujícího příkazu Azure CLI získat klíč rozhraní API z prostředku služby Cognitive Service.

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

Vytvořit ConversationAnalysisClient

Jakmile určíte koncový bod a klíč rozhraní API , můžete vytvořit ConversationAnalysisClientinstanci :

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)

Vytvořit ConversationAuthoringClient

Jakmile určíte koncový bod a klíč rozhraní API , můžete vytvořit ConversationAuthoringClientinstanci :

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)

Vytvoření klienta s přihlašovacími údaji Azure Active Directory

Pokud chcete použít přihlašovací údaje tokenu Azure Active Directory (AAD), zadejte instanci požadovaného typu přihlašovacích údajů získaného z knihovny azure-identity . Upozorňujeme, že místní koncové body nepodporují ověřování AAD. Vytvořte vlastní název subdomény pro váš prostředek, abyste mohli použít tento typ ověřování.

Ověřování pomocí AAD vyžaduje počáteční nastavení:

Po nastavení můžete zvolit, který typ přihlašovacích údajů z azure.identity chcete použít. Jako příklad lze k ověření klienta použít DefaultAzureCredential :

Nastavte hodnoty ID klienta, ID tenanta a tajného klíče klienta aplikace AAD jako proměnné prostředí: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

K ověření klienta použijte vrácené přihlašovací údaje tokenu:

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)

Klíčové koncepty

ConversationAnalysisClient

ConversationAnalysisClient je primární rozhraní pro vytváření předpovědí pomocí nasazených modelů Konverzace. Pro asynchronní operace je azure.ai.language.conversation.aio asynchronní ConversationAnalysisClient v oboru názvů.

ConversationAuthoringClient

Můžete použít ConversationAuthoringClient k propojení s portálem Azure Language Portal a provádět operace vytváření s vaším jazykovým prostředkem nebo projektem. Můžete ho například použít k vytvoření projektu, naplnění trénovacími daty, trénování, testování a nasazení. Pro asynchronní operace je azure.ai.language.conversation.authoring.aio asynchronní ConversationAuthoringClient v oboru názvů.

Příklady

Klientská azure-ai-language-conversation knihovna poskytuje synchronní i asynchronní rozhraní API.

Následující příklady ukazují běžné scénáře s využitím výše vytvořeného objektuclient.

Analýza textu pomocí konverzační aplikace

Pokud chcete extrahovat vlastní záměry a entity z promluvy uživatele, můžete metodu client.analyze_conversation() zavolat s názvem projektu konverzace následujícím způsobem:

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

Analýza textu pomocí aplikace orchestrace

Pokud chcete předat promluvu uživatele do aplikace orchestrátoru (worflow), můžete metodu client.analyze_conversation() volat s názvem projektu orchestrace. Projekt orchestrátoru jednoduše orchestruje odeslanou promluvu uživatele mezi vašimi jazykovými aplikacemi (Luis, Konverzace a Odpovědi na otázky), aby získal nejlepší odpověď podle záměru uživatele. Podívejte se na další příklad:

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

Konverzační souhrn

Tuto ukázku můžete použít, pokud potřebujete shrnout konverzaci ve formě problému a konečného řešení. Například dialogové okno od technické podpory:

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

Import projektu konverzace

Tato ukázka ukazuje běžný scénář pro část sdk pro vytváření obsahu.

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)

Volitelná konfigurace

Volitelné argumenty klíčových slov je možné předat na úrovni klienta a na úrovni jednotlivých operací. Referenční dokumentace azure-core popisuje dostupné konfigurace pro opakování, protokolování, přenosové protokoly a další.

Poradce při potížích

Obecné

Klient Konverzace vyvolá výjimky definované v Azure Core.

protokolování

Tato knihovna používá pro protokolování standardní knihovnu protokolování . Základní informace o relacích HTTP (adresy URL, hlavičky atd.) se protokolují na úrovni INFO.

Na klientovi s argumentem logging_enable je možné povolit podrobné protokolování úrovně LADĚNÍ, včetně těl požadavků/odpovědí a nereagovaných hlaviček.

Kompletní dokumentaci k protokolování sady SDK s příklady najdete tady.

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

Podobně logging_enable může povolit podrobné protokolování pro jednu operaci, i když není povolené pro klienta:

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

Další kroky

Další ukázkový kód

V ukázkovém souboru README najdete několik fragmentů kódu, které ilustrují běžné vzory používané v rozhraní API Pythonu CLU.

Přispívání

Podrobnosti o sestavování, testování a přispívání do této knihovny najdete v CONTRIBUTING.md .

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete na cla.microsoft.com.

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo se obraťte na opencode@microsoft.com případné další dotazy nebo komentáře.

Imprese