Makale
06/14/2023

Python için Azure Konuşma Language Understanding istemci kitaplığı - sürüm 1.1.0

Konuşma Language Understanding (kısaca CLU) aşağıdakiler gibi birçok dil anlama özelliği sağlayan bulut tabanlı bir konuşma yapay zeka hizmetidir:

Konuşma Uygulaması: Konuşmalardaki amaçları ve varlıkları ayıklamada kullanılır
İş akışı uygulaması: Qna, Luis ve Konuşma Uygulaması gibi uygulamalardan en iyi yanıtı almak için konuşmaları analiz etmek için en iyi adayı seçen bir düzenleyici gibi davranır
Konuşma Özetlemesi: Konuşmaları sorunlar/çözüm, bölüm başlığı ve anlatı özetlemeleri biçiminde analiz etmek için kullanılır

Başlarken

Önkoşullar

Bu paketi kullanmak için Python 3.7 veya üzeri gereklidir.
Azure aboneliği
Dil hizmeti kaynağı

Paketi yükleme

Pip ile Python için Azure Konuşmaları istemci kitaplığını yükleyin:

pip install azure-ai-language-conversations

Not: İstemci kitaplığının bu sürümü varsayılan olarak hizmetin 2023-04-01 sürümünü kullanır

İstemcinin kimliğini doğrulama

CLU hizmetiyle etkileşim kurmak için ConversationAnalysisClient sınıfının veya ConversationAuthoringClient sınıfının bir örneğini oluşturmanız gerekir. İstemci nesnesinin örneğini oluşturmak için bir uç nokta ve API anahtarı gerekir. Bilişsel Hizmetler ile kimlik doğrulaması hakkında daha fazla bilgi için bkz. Azure Bilişsel Hizmetler'de isteklerin kimliğini doğrulama.

API anahtarı alma

Uç noktayı ve API anahtarınıAzure Portal'daki Bilişsel Hizmetler kaynağından alabilirsiniz.

Alternatif olarak, Bilişsel Hizmet kaynağından API anahtarını almak için aşağıda gösterilen Azure CLI komutunu kullanın.

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

ConversationAnalysisClient Oluşturma

Uç noktanızı ve API anahtarınızı belirledikten sonra örneği ConversationAnalysisClientoluşturabilirsiniz:

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 Oluşturma

Uç noktanızı ve API anahtarınızı belirledikten sonra örneği ConversationAuthoringClientoluşturabilirsiniz:

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)

Azure Active Directory Kimlik Bilgileri ile istemci oluşturma

Azure Active Directory (AAD) belirteci kimlik bilgilerini kullanmak için azure-identity kitaplığından elde edilen istenen kimlik bilgisi türünün bir örneğini sağlayın. Bölgesel uç noktaların AAD kimlik doğrulamayı desteklemediğini unutmayın. Bu kimlik doğrulama türünü kullanmak için kaynağınız için özel bir alt etki alanı adı oluşturun.

AAD ile kimlik doğrulaması için bazı ilk kurulumlar gerekir:

azure-identity yükleme
Yeni bir AAD uygulaması kaydetme
Hizmet sorumlunuza "Bilişsel Hizmetler Dil Okuyucusu" rolünü atayarak Dil hizmetine erişim izni verin.

Kurulumdan sonra azure.identity'den kullanılacak kimlik bilgisi türünü seçebilirsiniz. Örneğin, istemcinin kimliğini doğrulamak için DefaultAzureCredential kullanılabilir:

AAD uygulamasının istemci kimliği, kiracı kimliği ve istemci gizli dizisi değerlerini ortam değişkenleri olarak ayarlayın: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

İstemcinin kimliğini doğrulamak için döndürülen belirteç kimlik bilgilerini kullanın:

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)

Önemli kavramlar

ConversationAnalysisClient

ConversationAnalysisClient, dağıtılan Konuşmalar modellerinizi kullanarak tahminde bulunmaya yönelik birincil arabirimdir. Zaman uyumsuz işlemler için ad alanında azure.ai.language.conversation.aio bir zaman uyumsuz ConversationAnalysisClient vardır.

ConversationAuthoringClient

Language kaynağınızda/projenizde yazma işlemlerini gerçekleştirmek üzere Azure Dil Portalı ile arabirim oluşturma amacıyla ConversationAuthoringClient kullanabilirsiniz. Örneğin, bunu kullanarak bir proje oluşturabilir, eğitim verileriyle doldurabilir, eğitebilir, test edebilir ve dağıtabilirsiniz. Zaman uyumsuz işlemler için ad alanında azure.ai.language.conversation.authoring.aio bir zaman uyumsuz ConversationAuthoringClient vardır.

Örnekler

azure-ai-language-conversation İstemci kitaplığı hem zaman uyumlu hem de zaman uyumsuz API'ler sağlar.

Aşağıdaki örneklerde, yukarıda oluşturulan kullanılarak client yaygın senaryolar gösterilir.

Konuşma Uygulaması ile Metin Çözümleme

Bir kullanıcı konuşmasından özel amaçları ve varlıkları ayıklamak isterseniz, yöntemini konuşmanızın proje adıyla aşağıdaki gibi çağırabilirsiniz client.analyze_conversation() :

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

Orchestration Uygulaması ile Metin Çözümleme

Kullanıcı konuşmasını düzenleyici (worflow) uygulamanıza geçirmek isterseniz, düzenlemenizin proje adıyla yöntemini çağırabilirsiniz client.analyze_conversation() . Orchestrator projesi, kullanıcı amacına göre en iyi yanıtı almak için dil uygulamalarınız (Luis, Konuşma ve Soru Yanıtlama) arasında gönderilen kullanıcı konuşmasını düzenler. Sonraki örne bakın:

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

Konuşma Özetlemesi

Bir konuşmayı sorun ve son çözüm biçiminde özetlemeniz gerekiyorsa bu örneği kullanabilirsiniz. Örneğin, teknik destekten bir iletişim kutusu:

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

Konuşma Projesini İçeri Aktarma

Bu örnekte SDK'nın yazma bölümü için yaygın bir senaryo gösterilmektedir

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)

İsteğe Bağlı Yapılandırma

İsteğe bağlı anahtar sözcük bağımsız değişkenleri istemci ve işlem başına düzeyinde geçirilebilir. Azure-core başvuru belgelerinde yeniden denemeler, günlüğe kaydetme, aktarım protokolleri ve daha fazlası için kullanılabilir yapılandırmalar açıklanmaktadır.

Sorun giderme

Genel

Konuşmalar istemcisi , Azure Core'da tanımlanan özel durumları tetikler.

Günlüğe Kaydetme

Bu kitaplık , günlüğe kaydetme için standart günlük kitaplığını kullanır. HTTP oturumları (URL'ler, üst bilgiler vb.) hakkındaki temel bilgiler BİlGİ düzeyinde günlüğe kaydedilir.

İstek/yanıt gövdeleri ve kaydedilmemiş üst bilgiler de dahil olmak üzere ayrıntılı HATA AYıKLAMA düzeyi günlüğü bağımsız değişkeniyle logging_enable bir istemcide etkinleştirilebilir.

Burada örneklerin bulunduğu tam SDK günlük belgelerine bakın.

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

Benzer şekilde, logging_enable istemci için etkinleştirilmemiş olsa bile tek bir işlem için ayrıntılı günlüğe kaydetmeyi etkinleştirebilir:

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

Sonraki adımlar

Daha fazla örnek kod

CLU Python API'sinde kullanılan yaygın desenleri gösteren çeşitli kod parçacıkları için Örnek BENİOKU'ya bakın.

Katkıda bulunma

Bu kitaplığı oluşturma, test etme ve bu kitaplığa katkıda bulunma hakkında ayrıntılı bilgi için CONTRIBUTING.md bakın.

Bu proje, katkı ve önerilere açıktır. Çoğu durumda, sağladığınız katkıyı kullanmamız için bize hak tanıma hakkına sahip olduğunuzu ve bu hakkı bize tanıdığınızı bildiren bir Katkıda Bulunan Lisans Sözleşmesi’ni (CLA) kabul etmeniz gerekir. Ayrıntılar için cla.microsoft.com adresini ziyaret edin.

Bir çekme isteği gönderdiğinizde, CLA robotu bir CLA sağlamanız gerekip gerekmediğini otomatik olarak belirler ve çekme isteğini uygun şekilde donatır (örn. etiket, açıklama). Robot tarafından sağlanan yönergeleri izlemeniz yeterlidir. Bu işlemi, CLA’mızı kullanarak tüm depolarda yalnızca bir kere yapmanız gerekir.

Bu proje Microsoft Open Source Code of Conduct (Microsoft Açık Kaynak Kullanım Kuralları) belgesinde listelenen kurallara uygundur. Daha fazla bilgi için Kullanım Kuralları SSS bölümüne bakın veya ek sorularınız veya yorumlarınızla iletişime geçin opencode@microsoft.com .

İzlenimler

Aracılığıyla paylaş