Azure Conversational Language Understanding Python ügyfélkódtár – 1.1.0-s verzió
A társalgási Language Understanding – röviden CLU – egy felhőalapú beszélgetési AI-szolgáltatás, amely számos nyelvfelismerési funkciót kínál, például:
- Beszélgetési alkalmazás: Szándékok és entitások kinyerésére használatos a beszélgetésekben
- Munkafolyamat-alkalmazás: Vezénylőként működik, és kiválasztja a beszélgetések elemzésére legalkalmasabb jelöltet, hogy a legjobb választ kapja az olyan alkalmazásoktól, mint a Qna, a Luis és a Conversation App
- Beszélgetési összegzés: A beszélgetések problémák/megoldás, fejezetcím és elbeszélő összegzések formájában történő elemzésére szolgál
Forráskód | Csomag (PyPI) | Csomag (Conda) | API-referenciadokumentáció | Minták | Termékdokumentáció | REST API-dokumentáció
Első lépések
Előfeltételek
- A csomag használatához Python 3.7 vagy újabb verzió szükséges.
- Azure-előfizetés
- Nyelvi szolgáltatás erőforrása
A csomag telepítése
Telepítse a Pythonhoz készült Azure Conversations ügyfélkódtárat a pip használatával:
pip install azure-ai-language-conversations
Megjegyzés: Az ügyfélkódtár ezen verziója alapértelmezés szerint a szolgáltatás 2023-04-01-es verziójára van bekapcsolva
Az ügyfél hitelesítése
A CLU szolgáltatás használatához létre kell hoznia a ConversationAnalysisClient osztály vagy a ConversationAuthoringClient osztály egy példányát . Szüksége lesz egy végpontra és egy API-kulcsra egy ügyfélobjektum példányosításához. A Cognitive Services-hitelesítéssel kapcsolatos további információkért lásd: Kérelmek hitelesítése az Azure Cognitive Servicesbe.
API-kulcs beszerzése
A végpontot és egy API-kulcsot az Azure Portal Cognitive Services-erőforrásából szerezheti be.
Másik lehetőségként az alább látható Azure CLI-paranccsal kérje le az API-kulcsot a Cognitive Service-erőforrásból.
az cognitiveservices account keys list --resource-group <resource-group-name> --name <resource-name>
ConversationAnalysisClient létrehozása
Miután meghatározta a végpontot és az API-kulcsot, példányosíthat egy példányt: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 létrehozása
Miután meghatározta a végpontot és az API-kulcsot, példányosíthat egy példányt: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)
Ügyfél létrehozása Azure Active Directory-hitelesítő adatokkal
Azure Active Directory- (AAD-) jogkivonat hitelesítő adatainak használatához adja meg az azure-identity kódtárból beszerzett kívánt hitelesítőadat-típus egy példányát. Vegye figyelembe, hogy a regionális végpontok nem támogatják az AAD-hitelesítést. Hozzon létre egy egyéni altartománynevet az erőforráshoz az ilyen típusú hitelesítés használatához.
Az AAD-vel történő hitelesítéshez kezdeti beállítás szükséges:
- Az azure-identity telepítése
- Új AAD-alkalmazás regisztrálása
- A Nyelvi szolgáltatáshoz való hozzáférés biztosításához rendelje hozzá a "Cognitive Services Nyelvolvasó" szerepkört a szolgáltatásnévhez.
A beállítás után kiválaszthatja, hogy az azure.identity milyen típusú hitelesítő adatokat használjon. Példaként a DefaultAzureCredential használható az ügyfél hitelesítésére:
Állítsa be az AAD-alkalmazás ügyfél-azonosítójának, bérlőazonosítójának és titkos ügyfélkulcsának értékeit környezeti változóként: AZURE_CLIENT_ID
, , AZURE_TENANT_ID
AZURE_CLIENT_SECRET
Használja a visszaadott jogkivonat hitelesítő adatait az ügyfél hitelesítéséhez:
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)
Fő fogalmak
ConversationAnalysisClient
A ConversationAnalysisClient az üzembe helyezett Beszélgetések modellek használatával történő előrejelzések készítésének elsődleges felülete. Aszinkron műveletek esetén az aszinkron ConversationAnalysisClient
a névtérben azure.ai.language.conversation.aio
található.
ConversationAuthoringClient
A ConversationAuthoringClient használatával csatlakozhat az Azure Language Portalhoz , hogy szerzői műveleteket hajtson végre a nyelvi erőforráson/projekten. Használhatja például egy projekt létrehozásához, a betanítási adatokkal való feltöltéshez, a betanításhoz, a teszteléshez és az üzembe helyezéshez. Aszinkron műveletek esetén az aszinkron ConversationAuthoringClient
a névtérben azure.ai.language.conversation.authoring.aio
található.
Példák
Az azure-ai-language-conversation
ügyfélkódtár szinkron és aszinkron API-kat is biztosít.
Az alábbi példák a fentiekbenclient
létrehozott gyakori forgatókönyveket mutatják be.
Szöveg elemzése beszélgetési alkalmazással
Ha egyéni szándékokat és entitásokat szeretne kinyerni egy felhasználói kimondott szövegből, meghívhatja a metódust a client.analyze_conversation()
beszélgetés projektnevével az alábbiak szerint:
# 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"]))
Szöveg elemzése vezénylési alkalmazással
Ha át szeretné adni a felhasználói kimondott szöveget a vezénylő (worflow) alkalmazásnak, meghívhatja a metódust a client.analyze_conversation()
vezénylés projektnevével. A vezénylési projekt egyszerűen vezényli a beküldött felhasználói kimondott szöveget a nyelvi alkalmazások (Luis, Beszélgetés és Kérdés megválaszolása) között, hogy a felhasználói szándéknak megfelelően a legjobb választ kapja. Lásd a következő példát:
# 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))
Beszélgetési összegzés
Ezt a mintát akkor használhatja, ha egy beszélgetést probléma formájában kell összegeznie, és végleges megoldást kell adnia. Például a technikai támogatás párbeszédpanelje:
# 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']}")
Beszélgetési projekt importálása
Ez a minta az SDK szerzői részének gyakori forgatókönyvét mutatja be
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)
Választható konfiguráció
Az opcionális kulcsszóargumentumok az ügyfél és a művelet szintjén is átadhatók. Az Azure-Core referenciadokumentációja többek között az újrapróbálkozásokhoz, a naplózáshoz, az átviteli protokollokhoz és egyebekhez elérhető konfigurációkat ismerteti.
Hibaelhárítás
Általános kérdések
A Conversations-ügyfél kivételeket hoz létre az Azure Core-ban.
Naplózás
Ez a kódtár a szabványos naplózási kódtárat használja a naplózáshoz. A HTTP-munkamenetekkel (URL-címekkel, fejlécekkel stb.) kapcsolatos alapvető információkat az INFO szinten naplózza a rendszer.
A RÉSZLETES HIBAKERESÉSi szint naplózása, beleértve a kérés-/választörzseket és a nem felügyelt fejléceket, engedélyezhető az logging_enable
argumentummal rendelkező ügyfélen.
A teljes SDK-naplózási dokumentációt itt találja példákkal.
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(...)
Hasonlóképpen logging_enable
engedélyezheti a részletes naplózást egyetlen művelethez, még akkor is, ha nincs engedélyezve az ügyfél számára:
result = client.analyze_conversation(..., logging_enable=True)
Következő lépések
További mintakód
A CLU Python API-ban használt gyakori mintákat bemutató kódrészletekért tekintse meg a MINTA README című cikket.
Közreműködés
A kódtár létrehozásával, tesztelésével és közreműködésével kapcsolatos részletekért tekintse meg a CONTRIBUTING.md.
A projektben szívesen fogadjuk a hozzájárulásokat és a javaslatokat. A legtöbb hozzájáruláshoz el kell fogadnia egy Közreműködői licencszerződést (CLA-t), amelyben kijelenti, hogy jogosult arra, hogy ránk ruházza hozzájárulása felhasználási jogát, és ezt ténylegesen meg is teszi. Részletekért látogasson el cla.microsoft.com.
A lekéréses kérelmek elküldésekor egy CLA-robot automatikusan meghatározza, hogy kell-e biztosítania CLA-t, és megfelelően kitölti a lekéréses kérelmet (például címke, megjegyzés). Egyszerűen csak kövesse a robot által megadott utasításokat. Ezt csak egyszer kell elvégeznie az összes olyan tárházban, amely a CLA-t használja.
A projekt a Microsoft nyílt forráskódú projekteket szabályozó etikai kódexe, a Microsoft Open Source Code of Conduct hatálya alá esik. További információkért lásd a viselkedési szabályzattal kapcsolatos gyakori kérdéseket , vagy vegye fel a kapcsolatot opencode@microsoft.com az esetleges további kérdésekkel vagy megjegyzésekkel.
Azure SDK for Python
Visszajelzés
https://aka.ms/ContentUserFeedback.
Hamarosan elérhető: 2024-ben fokozatosan kivezetjük a GitHub-problémákat a tartalom visszajelzési mechanizmusaként, és lecseréljük egy új visszajelzési rendszerre. További információ:Visszajelzés küldése és megtekintése a következőhöz: