Libreria client di Azure Conversational Language Understanding per Python - versione 1.1.0
Conversational Language Understanding, noto anche come CLU, è un servizio di intelligenza artificiale conversazionale basato sul cloud che offre molte funzionalità di comprensione del linguaggio, ad esempio:
- App di conversazione: viene usata per estrarre finalità ed entità nelle conversazioni
- App flusso di lavoro: agisce come un agente di orchestrazione per selezionare il candidato migliore per analizzare le conversazioni per ottenere una risposta ottimale da app come Qna, Luis e App di conversazione
- Riepilogo conversazionale: usato per analizzare le conversazioni sotto forma di problemi/risoluzione, titolo del capitolo e riepiloghi narrativi
Codice | sorgente Pacchetto (PyPI) | Pacchetto (Conda) | Documentazione | di riferimento sulle APICampioni | Documentazione | del prodotto Documentazione dell'API REST
Introduzione
Prerequisiti
- Python 3.7 o versione successiva è necessario per usare questo pacchetto.
- Una sottoscrizione di Azure
- Una risorsa del servizio di linguaggio
Installare il pacchetto
Installare la libreria client di Conversazioni di Azure per Python con pip:
pip install azure-ai-language-conversations
Nota: questa versione della libreria client per impostazione predefinita è la versione 2023-04-01 del servizio
Autenticare il client
Per interagire con il servizio CLU, è necessario creare un'istanza della classe ConversationAnalysisClient o della classe ConversationAuthoringClient . È necessario un endpoint e una chiave API per creare un'istanza di un oggetto client. Per altre informazioni sull'autenticazione con Servizi cognitivi, vedere Autenticare le richieste a Servizi cognitivi di Azure.
Ottenere una chiave API
È possibile ottenere l'endpoint e una chiave API dalla risorsa Servizi cognitivi nel portale di Azure.
In alternativa, usare il comando dell'interfaccia della riga di comando di Azure illustrato di seguito per ottenere la chiave API dalla risorsa Servizi cognitivi.
az cognitiveservices account keys list --resource-group <resource-group-name> --name <resource-name>
Creare ConversationAnalysisClient
Dopo aver determinato l'endpoint e la chiave API , è possibile creare un'istanza di 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)
Creare ConversationAuthoringClient
Dopo aver determinato l'endpoint e la chiave API , è possibile creare un'istanza di 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)
Creare un client con credenziali di Azure Active Directory
Per usare una credenziale del token di Azure Active Directory (AAD), specificare un'istanza del tipo di credenziale desiderato ottenuto dalla libreria azure-identity . Si noti che gli endpoint a livello di area non supportano l'autenticazione AAD. Creare un nome di sottodominio personalizzato per la risorsa per usare questo tipo di autenticazione.
L'autenticazione con AAD richiede una configurazione iniziale:
- Installare azure-identity
- Registrare una nuova applicazione AAD
- Concedere l'accesso al servizio lingua assegnando il ruolo "Lettore lingua servizi cognitivi" all'entità servizio.
Dopo l'installazione, è possibile scegliere il tipo di credenziale da usare azure.identity. Ad esempio, DefaultAzureCredential può essere usato per autenticare il client:
Impostare i valori dell'ID client, dell'ID tenant e del segreto client dell'applicazione AAD come variabili di ambiente: AZURE_CLIENT_ID, , AZURE_TENANT_IDAZURE_CLIENT_SECRET
Usare le credenziali del token restituite per autenticare il 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)
Concetti chiave
ConversationAnalysisClient
ConversationAnalysisClient è l'interfaccia principale per eseguire stime usando i modelli conversazioni distribuiti. Per le operazioni asincrone, uno asincrono ConversationAnalysisClient si trova nello spazio dei azure.ai.language.conversation.aio nomi .
ConversationAuthoringClient
È possibile usare ConversationAuthoringClient per interfacciarsi con il portale di linguaggio di Azure per eseguire operazioni di creazione sulla risorsa/progetto di linguaggio. Ad esempio, è possibile usarlo per creare un progetto, popolare con dati di training, training, test e distribuzione. Per le operazioni asincrone, uno asincrono ConversationAuthoringClient si trova nello spazio dei azure.ai.language.conversation.authoring.aio nomi .
Esempio
La azure-ai-language-conversation libreria client fornisce API sincrone e asincrone.
Gli esempi seguenti illustrano scenari comuni che usano l'oggetto clientcreato in precedenza.
Analizzare il testo con un'app di conversazione
Se si desidera estrarre finalità ed entità personalizzate da un'espressione utente, è possibile chiamare il metodo con il client.analyze_conversation() nome del progetto della conversazione come indicato di seguito:
# 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"]))
Analizzare il testo con un'app di orchestrazione
Se vuoi passare l'espressione utente all'app dell'agente di orchestrazione (worflow), puoi chiamare il metodo con il client.analyze_conversation() nome del progetto dell'orchestrazione. Il progetto dell'agente di orchestrazione orchestra semplicemente orchestra l'espressione utente inviata tra le app per la lingua (Luis, Conversation e Question Answering) per ottenere la risposta migliore in base alla finalità dell'utente. Vedere l'esempio seguente:
# 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))
Riepilogo conversazionale
È possibile usare questo esempio se è necessario riepilogare una conversazione sotto forma di problema e risoluzione finale. Ad esempio, un dialogo del supporto tecnico:
# 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']}")
Importare un progetto di conversazione
Questo esempio illustra uno scenario comune per la parte di creazione dell'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)
Configurazione facoltativa
Gli argomenti di parole chiave facoltativi possono essere passati al client e al livello di operazione. La documentazione di riferimento di azure-core descrive le configurazioni disponibili per tentativi, registrazione, protocolli di trasporto e altro ancora.
Risoluzione dei problemi
Generale
Il client Conversazioni genererà eccezioni definite in Azure Core.
Registrazione
Questa libreria usa la libreria di registrazione standard per la registrazione. Le informazioni di base sulle sessioni HTTP (URL, intestazioni e così via) vengono registrate a livello di INFO.
La registrazione dettagliata a livello di DEBUG, inclusi i corpi di richiesta/risposta e le intestazioni non contrassegnate, può essere abilitata in un client con l'argomento logging_enable .
Vedere la documentazione completa sulla registrazione dell'SDK con esempi qui.
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(...)
Analogamente, logging_enable può abilitare la registrazione dettagliata per una singola operazione, anche quando non è abilitata per il client:
result = client.analyze_conversation(..., logging_enable=True)
Passaggi successivi
Altro codice di esempio
Vedere sample README per diversi frammenti di codice che illustrano i modelli comuni usati nell'API Python CLU.
Contributo
Per informazioni dettagliate sulla compilazione, il test e il contributo a questa libreria, vedere la CONTRIBUTING.md .
In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, visitare cla.microsoft.com.
Quando si invia una richiesta pull, un bot CLA determina automaticamente se è necessario specificare un contratto CLA e completare la richiesta pull in modo appropriato (ad esempio con un'etichetta e un commento). Seguire le istruzioni specificate dal bot. È sufficiente eseguire questa operazione una sola volta per tutti i repository che usano il contratto CLA Microsoft.
Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.
Azure SDK for Python