مشاركة عبر

  • مقالة

Build Status

مكتبة عميل Azure Conversational Language Understanding ل Python - الإصدار 1.1.0

فهم لغة المحادثة - المعروف أيضا باسم CLU باختصار - هي خدمة الذكاء الاصطناعي محادثة مستندة إلى السحابة توفر العديد من قدرات فهم اللغة مثل:

  • تطبيق المحادثة: يستخدم في استخراج الأهداف والكيانات في المحادثات
  • تطبيق سير العمل: يعمل كمنسق لتحديد أفضل مرشح لتحليل المحادثات للحصول على أفضل استجابة من تطبيقات مثل Qna و Luis و Conversation App
  • تلخيص المحادثة: يستخدم لتحليل المحادثات في شكل مشكلات/حل، وعنوان الفصل، والملخصات السردية

التعليمات البرمجية | المصدر الحزمة (PyPI) | حزمة (Conda) | الوثائق | المرجعية لواجهة برمجة التطبيقاتعينات | وثائق | المنتج وثائق واجهة برمجة تطبيقات REST

الشروع في العمل

المتطلبات الأساسية

تثبيت الحِزَمة

قم بتثبيت مكتبة عميل Azure Conversations ل Python باستخدام pip:

pip install azure-ai-language-conversations

ملاحظة: يتم تعيين هذا الإصدار من مكتبة العميل افتراضيا إلى إصدار 2023-04-01 من الخدمة

مصادقة العميل

للتفاعل مع خدمة CLU، ستحتاج إلى إنشاء مثيل لفئة ConversationAnalysisClient أو فئة ConversationAuthoringClient . ستحتاج إلى نقطة نهاية، ومفتاح API لإنشاء مثيل لكائن عميل. لمزيد من المعلومات حول المصادقة باستخدام الخدمات المعرفية، راجع مصادقة الطلبات إلى خدمات Azure المعرفية.

الحصول على مفتاح API

يمكنك الحصول على نقطة النهايةومفتاح API من مورد الخدمات المعرفية في مدخل Microsoft Azure.

بدلا من ذلك، استخدم أمر Azure CLI الموضح أدناه للحصول على مفتاح API من مورد الخدمة المعرفية.

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

إنشاء ConversationAnalysisClient

بمجرد تحديد نقطة النهايةومفتاح API ، يمكنك إنشاء ConversationAnalysisClientمثيل :

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

بمجرد تحديد نقطة النهايةومفتاح API ، يمكنك إنشاء ConversationAuthoringClientمثيل :

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

لاستخدام بيانات اعتماد الرمز المميز ل Azure Active Directory (AAD)، قم بتوفير مثيل لنوع بيانات الاعتماد المطلوب الذي تم الحصول عليه من مكتبة هوية azure . لاحظ أن نقاط النهاية الإقليمية لا تدعم مصادقة AAD. إنشاء اسم مجال فرعي مخصص لموردك لاستخدام هذا النوع من المصادقة.

تتطلب المصادقة مع AAD بعض الإعداد الأولي:

بعد الإعداد، يمكنك اختيار نوع بيانات الاعتماد من azure.identity لاستخدامها. على سبيل المثال، يمكن استخدام DefaultAzureCredential لمصادقة العميل:

تعيين قيم معرف العميل ومعرف المستأجر وسر العميل لتطبيق AAD كمتغيرات بيئة: AZURE_CLIENT_ID، ، AZURE_TENANT_IDAZURE_CLIENT_SECRET

استخدم بيانات اعتماد الرمز المميز الذي تم إرجاعه لمصادقة العميل:

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)

المفاهيم الرئيسية

ConversationAnalysisClient

ConversationAnalysisClient هي الواجهة الأساسية لإجراء تنبؤات باستخدام نماذج المحادثات المنشورة. بالنسبة للعمليات غير المتزامنة، يوجد غير متزامن ConversationAnalysisClient في azure.ai.language.conversation.aio مساحة الاسم.

ConversationAuthoringClient

يمكنك استخدام ConversationAuthoringClient للواجهة مع مدخل لغة Azure لتنفيذ عمليات التأليف على مورد/مشروع اللغة. على سبيل المثال، يمكنك استخدامه لإنشاء مشروع، والتعبئة ببيانات التدريب، والتدريب، والاختبار، والنشر. بالنسبة للعمليات غير المتزامنة، يوجد غير متزامن ConversationAuthoringClient في azure.ai.language.conversation.authoring.aio مساحة الاسم.

أمثلة

azure-ai-language-conversation توفر مكتبة العميل واجهات برمجة التطبيقات المتزامنة وغير المتزامنة.

توضح الأمثلة التالية السيناريوهات الشائعة باستخدام ما clientتم إنشاؤه أعلاه.

تحليل النص باستخدام تطبيق المحادثة

إذا كنت ترغب في استخراج الأهداف والكيانات المخصصة من تعبير المستخدم، يمكنك استدعاء 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"]))

تحليل النص باستخدام تطبيق التنسيق

إذا كنت ترغب في تمرير تعبير المستخدم إلى تطبيق المنسق (worflow)، يمكنك استدعاء client.analyze_conversation() الأسلوب باسم مشروع التنسيق الخاص بك. ينسق مشروع المنسق ببساطة تعبير المستخدم المرسل بين تطبيقات اللغة الخاصة بك (Luis والمحادثة والإجابة على الأسئلة) للحصول على أفضل استجابة وفقا لهدف المستخدم. راجع المثال التالي:

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

تلخيص المحادثة

يمكنك استخدام هذه العينة إذا كنت بحاجة إلى تلخيص محادثة في شكل مشكلة، والحل النهائي. على سبيل المثال، مربع حوار من الدعم التقني:

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

استيراد مشروع محادثة

يعرض هذا النموذج سيناريو شائعا لجزء التأليف من 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)

التكوين الاختياري

يمكن تمرير وسيطات الكلمات الأساسية الاختيارية على مستوى العميل وكل عملية. تصف الوثائق المرجعية azure-core التكوينات المتوفرة لإعادة المحاولة والتسجيل وبروتوكولات النقل والمزيد.

استكشاف الأخطاء وإصلاحها

عام

سيقوم عميل المحادثات برفع الاستثناءات المحددة في Azure Core.

تسجيل الدخول

تستخدم هذه المكتبة مكتبة التسجيل القياسية للتسجيل. يتم تسجيل المعلومات الأساسية حول جلسات HTTP (عناوين URL والعناوين وما إلى ذلك) على مستوى INFO.

يمكن تمكين تسجيل مستوى تتبع الأخطاء المفصل، بما في ذلك هيئات الطلب/الاستجابة والعناوين غير النشطة، على عميل باستخدام الوسيطة logging_enable .

راجع وثائق تسجيل SDK الكاملة مع أمثلة هنا.

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

وبالمثل، logging_enable يمكن تمكين تسجيل مفصل لعملية واحدة، حتى عندما لا يتم تمكين للعميل:

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

الخطوات التالية

المزيد من نماذج التعليمات البرمجية

راجع نموذج README للعديد من القصاصات البرمجية التي توضح الأنماط الشائعة المستخدمة في واجهة برمجة تطبيقات CLU Python.

المساهمة

راجع CONTRIBUTING.md للحصول على تفاصيل حول إنشاء هذه المكتبة واختبارها والمساهمة فيها.

هذا المشروع يرحب بالمساهمات والاقتراحات. معظم المساهمات تتطلب منك الموافقة على اتفاقية ترخيص المساهم (CLA) التي تعلن أن لديك الحق في منحنا حق استخدام مساهمتك. للحصول على التفاصيل، تفضل بزيارة cla.microsoft.com.

عند إرسال طلب سحب، سيحدد روبوت CLA-bot تلقائيًا ما إذا كنت بحاجة إلى تقديم CLA وتزيين العلاقات العامة بشكل مناسب (على سبيل المثال، التسمية أو التعليق). ما عليك سوى اتباع التعليمات التي يقدمها الروبوت. ستحتاج فقط إلى القيام بذلك مرة واحدة عبر جميع عمليات إعادة الشراء باستخدام CLA الخاص بنا.

اعتمد هذا المشروع مدونة السلوك من المصادر المفتوحة من Microsoft. لمزيد من المعلومات، راجع الأسئلة المتداولة حول قواعد السلوك أو الاتصال opencode@microsoft.com بأي أسئلة أو تعليقات إضافية.

مرات الظهور