This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Note
Access to this page requires authorization. You can trysigning in orchanging directories.
Access to this page requires authorization. You can trychanging directories.
Conversational Language Understanding - akaCLU for short - is a cloud-based conversational AI service which provides many language understanding capabilities like:
Source code|Package (PyPI)|Package (Conda)|API reference documentation|Samples|Product documentation|REST API documentation
Install the Azure Conversations client library for Python withpip:
pip install azure-ai-language-conversations
Note: This version of the client library defaults to the 2023-04-01 version of the service
In order to interact with the CLU service, you'll need to create an instance of theConversationAnalysisClient class, orConversationAuthoringClient class. You will need anendpoint, and anAPI key to instantiate a client object. For more information regarding authenticating with Cognitive Services, seeAuthenticate requests to Azure Cognitive Services.
You can get theendpoint and anAPI key from the Cognitive Services resource in theAzure Portal.
Alternatively, use theAzure CLI command shown below to get the API key from the Cognitive Service resource.
az cognitiveservices account keys list --resource-group <resource-group-name> --name <resource-name>
Once you've determined yourendpoint andAPI key you can instantiate aConversationAnalysisClient
:
from azure.core.credentials import AzureKeyCredentialfrom azure.ai.language.conversations import ConversationAnalysisClientendpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/"credential = AzureKeyCredential("<api-key>")client = ConversationAnalysisClient(endpoint, credential)
Once you've determined yourendpoint andAPI key you can instantiate aConversationAuthoringClient
:
from azure.core.credentials import AzureKeyCredentialfrom azure.ai.language.conversations.authoring import ConversationAuthoringClientendpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/"credential = AzureKeyCredential("<api-key>")client = ConversationAuthoringClient(endpoint, credential)
To use anAzure Active Directory (AAD) token credential,provide an instance of the desired credential type obtained from theazure-identity library.Note that regional endpoints do not support AAD authentication. Create acustom subdomainname for your resource in order to use this type of authentication.
Authentication with AAD requires some initial setup:
After setup, you can choose which type ofcredential from azure.identity to use.As an example,DefaultAzureCredentialcan be used to authenticate the client:
Set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables:AZURE_CLIENT_ID
,AZURE_TENANT_ID
,AZURE_CLIENT_SECRET
Use the returned token credential to authenticate the client:
from azure.ai.language.conversations import ConversationAnalysisClientfrom azure.identity import DefaultAzureCredentialcredential = DefaultAzureCredential()client = ConversationAnalysisClient(endpoint="https://<my-custom-subdomain>.cognitiveservices.azure.com/", credential=credential)
TheConversationAnalysisClient is the primary interface for making predictions using your deployed Conversations models. For asynchronous operations, an asyncConversationAnalysisClient
is in theazure.ai.language.conversation.aio
namespace.
You can use theConversationAuthoringClient to interface with theAzure Language Portal to carry out authoring operations on your language resource/project. For example, you can use it to create a project, populate with training data, train, test, and deploy. For asynchronous operations, an asyncConversationAuthoringClient
is in theazure.ai.language.conversation.authoring.aio
namespace.
Theazure-ai-language-conversation
client library provides both synchronous and asynchronous APIs.
The following examples show common scenarios using theclient
created above.
If you would like to extract custom intents and entities from a user utterance, you can call theclient.analyze_conversation()
method with your conversation's project name as follows:
# import librariesimport osfrom azure.core.credentials import AzureKeyCredentialfrom azure.ai.language.conversations import ConversationAnalysisClient# get secretsclu_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 queyclient = 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 resultprint("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"]))
If you would like to pass the user utterance to your orchestrator (worflow) app, you can call theclient.analyze_conversation()
method with your orchestration's project name. The orchestrator project simply orchestrates the submitted user utterance between your language apps (Luis, Conversation, and Question Answering) to get the best response according to the user intent. See the next example:
# import librariesimport osfrom azure.core.credentials import AzureKeyCredentialfrom azure.ai.language.conversations import ConversationAnalysisClient# get secretsclu_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 queryclient = 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 resultprint("query: {}".format(result["result"]["query"]))print("project kind: {}\n".format(result["result"]["prediction"]["projectKind"]))# top intenttop_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))
You can use this sample if you need to summarize a conversation in the form of an issue, and final resolution. For example, a dialog from tech support:
# import librariesimport osfrom azure.core.credentials import AzureKeyCredentialfrom azure.ai.language.conversations import ConversationAnalysisClient# get secretsendpoint = os.environ["AZURE_CONVERSATIONS_ENDPOINT"]key = os.environ["AZURE_CONVERSATIONS_KEY"]# analyze queryclient = 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']}")
This sample shows a common scenario for the authoring part of the SDK
import osfrom azure.core.credentials import AzureKeyCredentialfrom azure.ai.language.conversations.authoring import ConversationAuthoringClientclu_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)
Optional keyword arguments can be passed in at the client and per-operation level. The azure-corereference documentation describes available configurations for retries, logging, transport protocols, and more.
The Conversations client will raise exceptions defined inAzure Core.
This library uses the standardlogging library for logging.Basic information about HTTP sessions (URLs, headers, etc.) is logged at INFOlevel.
Detailed DEBUG level logging, including request/response bodies and unredactedheaders, can be enabled on a client with thelogging_enable
argument.
See full SDK logging documentation with exampleshere.
import sysimport loggingfrom azure.core.credentials import AzureKeyCredentialfrom azure.ai.language.conversations import ConversationAnalysisClient# Create a logger for the 'azure' SDKlogger = logging.getLogger('azure')logger.setLevel(logging.DEBUG)# Configure a console outputhandler = 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 levelclient = ConversationAnalysisClient(endpoint, credential, logging_enable=True)result = client.analyze_conversation(...)
Similarly,logging_enable
can enable detailed logging for a single operation, even when it isn't enabled for the client:
result = client.analyze_conversation(..., logging_enable=True)
See theSample README for several code snippets illustrating common patterns used in the CLU Python API.
See theCONTRIBUTING.md for details on building, testing, and contributing to this library.
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visitcla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted theMicrosoft Open Source Code of Conduct. For more information see theCode of Conduct FAQ or contactopencode@microsoft.com with any additional questions or comments.
Was this page helpful?
Was this page helpful?