Bibliothèque de client Azure Conversational Language Understanding pour Python - version 1.1.0
L’Language Understanding conversationnelle( CLU) est un service d’IA conversationnelle basé sur le cloud qui fournit de nombreuses fonctionnalités de compréhension du langage, telles que :
- Application conversation : elle est utilisée pour extraire des intentions et des entités dans des conversations
- Application de flux de travail : agit comme un orchestrateur pour sélectionner le meilleur candidat pour analyser les conversations afin d’obtenir la meilleure réponse à partir d’applications telles que Qna, Luis et Conversation App
- Résumé conversationnel : utilisé pour analyser les conversations sous la forme de problèmes/résolution, de titre de chapitre et de résumés narratifs
| Code sourcePackage (PyPI) | Package (Conda) | Documentation de référence sur les | API Échantillons | | Documentation produitDocumentation sur l’API REST
Prise en main
Prérequis
- Python 3.7 ou version ultérieure est requis pour utiliser ce package.
- Un abonnement Azure
- Une ressource du service Language
Installer le package
Installez la bibliothèque de client Azure Conversations pour Python avec pip :
pip install azure-ai-language-conversations
Remarque : Cette version de la bibliothèque cliente utilise par défaut la version 2023-04-01 du service
Authentifier le client
Pour interagir avec le service CLU, vous devez créer un instance de la classe ConversationAnalysisClient ou ConversationAuthoringClient. Vous aurez besoin d’un point de terminaison et d’une clé API pour instancier un objet client. Pour plus d’informations sur l’authentification auprès de Cognitive Services, consultez Authentifier les demandes auprès d’Azure Cognitive Services.
Obtenir une clé API
Vous pouvez obtenir le point de terminaison et une clé API à partir de la ressource Cognitive Services dans le portail Azure.
Vous pouvez également utiliser la commande Azure CLI illustrée ci-dessous pour obtenir la clé API à partir de la ressource Cognitive Service.
az cognitiveservices account keys list --resource-group <resource-group-name> --name <resource-name>
Créer ConversationAnalysisClient
Une fois que vous avez déterminé votre point de terminaison et votre clé API , vous pouvez instancier un 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)
Créer ConversationAuthoringClient
Une fois que vous avez déterminé votre point de terminaison et votre clé API , vous pouvez instancier un 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)
Créer un client avec des informations d’identification Azure Active Directory
Pour utiliser des informations d’identification de jeton Azure Active Directory (AAD), fournissez une instance du type d’informations d’identification souhaité obtenu à partir de la bibliothèque azure-identity. Notez que les points de terminaison régionaux ne prennent pas en charge l’authentification AAD. Créez un nom de sous-domaine personnalisé pour votre ressource afin d’utiliser ce type d’authentification.
L’authentification avec AAD nécessite une configuration initiale :
- Installer azure-identity
- Inscrire une nouvelle application AAD
- Accordez l’accès au service Language en attribuant le rôle « Lecteur de langue Cognitive Services » à votre principal de service.
Après l’installation, vous pouvez choisir le type d’informations d’identification d’azure.identity à utiliser. Par exemple, DefaultAzureCredential peut être utilisé pour authentifier le client :
Définissez les valeurs de l’ID client, de l’ID de locataire et de la clé secrète client de l’application AAD en tant que variables d’environnement : AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET
Utilisez les informations d’identification de jeton retournées pour authentifier le client :
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)
Concepts clés
ConversationAnalysisClient
ConversationAnalysisClient est l’interface principale pour effectuer des prédictions à l’aide de vos modèles Conversations déployés. Pour les opérations asynchrones, un async ConversationAnalysisClient se trouve dans l’espace de azure.ai.language.conversation.aio noms.
ConversationAuthoringClient
Vous pouvez utiliser ConversationAuthoringClient pour interfacer avec le portail de langage Azure afin d’effectuer des opérations de création sur votre ressource/projet linguistique. Par exemple, vous pouvez l’utiliser pour créer un projet, remplir avec des données d’entraînement, entraîner, tester et déployer. Pour les opérations asynchrones, un async ConversationAuthoringClient se trouve dans l’espace de azure.ai.language.conversation.authoring.aio noms.
Exemples
La azure-ai-language-conversation bibliothèque cliente fournit des API synchrones et asynchrones.
Les exemples suivants illustrent les scénarios courants utilisant le clientcréé ci-dessus.
Analyser du texte avec une application conversation
Si vous souhaitez extraire des intentions et des entités personnalisées d’un énoncé utilisateur, vous pouvez appeler la méthode avec le client.analyze_conversation() nom de projet de votre conversation comme suit :
# 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"]))
Analyser du texte avec une application d’orchestration
Si vous souhaitez passer l’énoncé utilisateur à votre application orchestrator (worflow), vous pouvez appeler la méthode avec le client.analyze_conversation() nom de projet de votre orchestration. Le projet d’orchestrateur orchestre simplement l’énoncé utilisateur envoyé entre vos applications linguistiques (Luis, Conversation et Réponses aux questions) pour obtenir la meilleure réponse en fonction de l’intention de l’utilisateur. Consultez l’exemple suivant :
# 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))
Résumé conversationnel
Vous pouvez utiliser cet exemple si vous avez besoin de résumer une conversation sous la forme d’un problème et d’une résolution finale. Par exemple, une boîte de dialogue du support technique :
# 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']}")
Importer un projet de conversation
Cet exemple montre un scénario courant pour la partie de création du Kit de développement logiciel (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)
Configuration facultative
Les arguments mot clé facultatifs peuvent être passés au niveau du client et par opération. La documentation de référence azure-core décrit les configurations disponibles pour les nouvelles tentatives, la journalisation, les protocoles de transport, etc.
Dépannage
Général
Le client Conversations déclenche des exceptions définies dans Azure Core.
Journalisation
Cette bibliothèque utilise la bibliothèque de journalisation standard pour la journalisation. Les informations de base sur les sessions HTTP (URL, en-têtes, etc.) sont enregistrées au niveau INFO.
La journalisation détaillée au niveau DEBUG, y compris les corps de requête/réponse et les en-têtes non expurgés, peut être activée sur un client avec l’argument logging_enable .
Consultez la documentation complète sur la journalisation du KIT de développement logiciel (SDK) avec des exemples ici.
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(...)
De la même façon, logging_enable peut activer la journalisation détaillée pour une seule opération, même quand elle n’est pas activée pour le client :
result = client.analyze_conversation(..., logging_enable=True)
Étapes suivantes
Autres exemples de code
Consultez l’exemple README pour obtenir plusieurs extraits de code illustrant les modèles courants utilisés dans l’API Python CLU.
Contribution
Consultez la CONTRIBUTING.md pour plus d’informations sur la création, le test et la contribution à cette bibliothèque.
Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez cla.microsoft.com.
Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.
Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.
Azure SDK for Python