Artikel
06/14/2023

Pustaka klien Pemahaman Bahasa Percakapan Azure untuk Python - versi 1.1.0

Singkatnya, Pemahaman Bahasa Percakapan - alias CLU - adalah layanan AI percakapan berbasis cloud yang menyediakan banyak kemampuan pemahaman bahasa seperti:

Aplikasi Percakapan: Ini digunakan dalam mengekstrak niat dan entitas dalam percakapan
Aplikasi alur kerja: Bertindak seperti orkestrator untuk memilih kandidat terbaik untuk menganalisis percakapan untuk mendapatkan respons terbaik dari aplikasi seperti Qna, Luis, dan Aplikasi Percakapan
Ringkasan Percakapan: Digunakan untuk menganalisis percakapan dalam bentuk masalah/resolusi, judul bab, dan ringkasan narasi

Memulai

Prasyarat

Python 3.7 atau yang lebih baru diharuskan untuk menggunakan paket ini.
Langganan Azure
Sumber daya layanan Bahasa

Instal paketnya

Instal pustaka klien Azure Conversations untuk Python dengan pip:

pip install azure-ai-language-conversations

Catatan: Versi pustaka klien ini default ke versi layanan 2023-04-01

Mengautentikasi klien

Untuk berinteraksi dengan layanan CLU, Anda harus membuat instans kelas ConversationAnalysisClient , atau kelas ConversationAuthoringClient . Anda akan memerlukan titik akhir, dan kunci API untuk membuat instans objek klien. Untuk informasi selengkapnya mengenai autentikasi dengan Cognitive Services, lihat Mengautentikasi permintaan ke Azure Cognitive Services.

Mendapatkan kunci API

Anda bisa mendapatkan titik akhir dan kunci API dari sumber daya Cognitive Services di Portal Microsoft Azure.

Atau, gunakan perintah Azure CLI yang ditunjukkan di bawah ini untuk mendapatkan kunci API dari sumber daya Cognitive Service.

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

Membuat ConversationAnalysisClient

Setelah menentukan titik akhir dan kunci API , Anda dapat membuat instans 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)

Membuat ConversationAuthoringClient

Setelah menentukan titik akhir dan kunci API , Anda dapat membuat instans 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)

Membuat klien dengan Kredensial Azure Active Directory

Untuk menggunakan kredensial token Azure Active Directory (AAD), berikan instans jenis kredensial yang diinginkan yang diperoleh dari pustaka identitas azure . Perhatikan bahwa titik akhir regional tidak mendukung autentikasi AAD. Buat nama subdomain kustom untuk sumber daya Anda untuk menggunakan jenis autentikasi ini.

Autentikasi dengan AAD memerlukan beberapa penyiapan awal:

Menginstal azure-identity
Mendaftarkan aplikasi AAD baru
Berikan akses ke layanan Bahasa dengan menetapkan peran "Pembaca Bahasa Cognitive Services" kepada perwakilan layanan Anda.

Setelah penyiapan, Anda dapat memilih jenis kredensial mana dari azure.identity yang akan digunakan. Sebagai contoh, DefaultAzureCredential dapat digunakan untuk mengautentikasi klien:

Atur nilai ID klien, ID penyewa, dan rahasia klien aplikasi AAD sebagai variabel lingkungan: AZURE_CLIENT_ID, , AZURE_TENANT_IDAZURE_CLIENT_SECRET

Gunakan kredensial token yang dikembalikan untuk mengautentikasi klien:

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)

Konsep utama

ConversationAnalysisClient

ConversationAnalysisClient adalah antarmuka utama untuk membuat prediksi menggunakan model Percakapan yang Anda sebarkan. Untuk operasi asinkron, asinkron ConversationAnalysisClient ada di azure.ai.language.conversation.aio namespace.

ConversationAuthoringClient

Anda dapat menggunakan ConversationAuthoringClient untuk berinteraksi dengan Portal Bahasa Azure untuk melakukan operasi penulisan pada sumber daya/proyek bahasa Anda. Misalnya, Anda dapat menggunakannya untuk membuat proyek, mengisi dengan data pelatihan, melatih, menguji, dan menyebarkan. Untuk operasi asinkron, asinkron ConversationAuthoringClient ada di azure.ai.language.conversation.authoring.aio namespace.

Contoh

azure-ai-language-conversation Pustaka klien menyediakan API sinkron dan asinkron.

Contoh berikut menunjukkan skenario umum menggunakan yang dibuat diclient atas.

Menganalisis Teks dengan Aplikasi Percakapan

Jika Anda ingin mengekstrak niat dan entitas kustom dari ucapan pengguna, Anda dapat memanggil client.analyze_conversation() metode dengan nama proyek percakapan Anda sebagai berikut:

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

Menganalisis Teks dengan Aplikasi Orkestrasi

Jika Anda ingin meneruskan ucapan pengguna ke aplikasi orkestrator (worflow), Anda dapat memanggil client.analyze_conversation() metode dengan nama proyek orkestrasi Anda. Proyek orkestrator hanya mengatur ucapan pengguna yang dikirimkan antara aplikasi bahasa Anda (Luis, Percakapan, dan Jawaban Atas Pertanyaan) untuk mendapatkan respons terbaik sesuai dengan niat pengguna. Lihat contoh berikutnya:

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

Ringkasan Percakapan

Anda dapat menggunakan sampel ini jika Anda perlu meringkas percakapan dalam bentuk masalah, dan resolusi akhir. Misalnya, dialog dari dukungan teknologi:

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

Mengimpor Proyek Percakapan

Sampel ini menunjukkan skenario umum untuk bagian penulisan 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)

Konfigurasi Opsional

Argumen kata kunci opsional dapat diteruskan di tingkat klien dan per operasi. Dokumentasi referensi azure-core menjelaskan konfigurasi yang tersedia untuk percobaan ulang, pengelogan, protokol transportasi, dan banyak lagi.

Pemecahan Masalah

Umum

Klien Percakapan akan memunculkan pengecualian yang ditentukan di Azure Core.

Pembuatan Log

Pustaka ini menggunakan pustaka pengelogan standar untuk pengelogan. Informasi dasar tentang sesi HTTP (URL, header, dll.) dicatat di tingkat INFO.

Pengelogan tingkat DEBUG terperinci, termasuk isi permintaan/respons dan header yang tidak diredaksikan, dapat diaktifkan pada klien dengan logging_enable argumen .

Lihat dokumentasi pengelogan SDK lengkap dengan contoh di sini.

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

Demikian pula, logging_enable dapat mengaktifkan pengelogan mendetail untuk satu operasi, meskipun tidak diaktifkan untuk klien:

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

Langkah berikutnya

Lebih banyak kode sampel

Lihat Sampel README untuk beberapa cuplikan kode yang mengilustrasikan pola umum yang digunakan dalam CLU Python API.

Berkontribusi

Lihat CONTRIBUTING.md untuk detail tentang membangun, menguji, dan berkontribusi pada pustaka ini.

Proyek ini menyambut baik kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi cla.microsoft.com.

Ketika Anda mengirimkan permintaan tarik, CLA-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repos menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat Tanya Jawab Umum Tata Tertib atau hubungi opencode@microsoft.com untuk pertanyaan atau komentar lainnya.

Tayangan

Bagikan melalui