Condividi tramite

Azure Cognitive Language Service Domande sulla risposta alla libreria client per Python - versione 1.1.0

  • Articolo

La risposta alle domande è un servizio API basato sul cloud che consente di creare un livello di domande e risposte conversazionali sui dati esistenti. Usarlo per creare un knowledge base estraendo domande e risposte dal contenuto semistrutturato, incluse domande frequenti, manuali e documenti. Rispondere alle domande degli utenti con le risposte migliori dai QnAs nel knowledge base, automaticamente. Anche il tuo knowledge base diventa più intelligente, perché impara continuamente dal comportamento degli utenti.

Codice | sorgente Pacchetto (PyPI) | Documentazione di | riferimento sulle API Documentazione | del prodotto Campioni

Dichiarazione di non responsabilità

Il supporto dei pacchetti Python di Azure SDK per Python 2.7 è terminato 01 gennaio 2022. Per altre informazioni e domande, vedere https://github.com/Azure/azure-sdk-for-python/issues/20691

Introduzione

Prerequisiti

Installare il pacchetto

Installare la libreria client di Risposta alle domande di Azure per Python con pip:

pip install azure-ai-language-questionanswering

Nota: questa versione della libreria client viene predefinita per la versione 2021-10-01dell'API del servizio .

Autenticare il client

Per interagire con il servizio Risposta alla domanda, è necessario creare un'istanza della classe QuestionAnsweringClient o un'istanza di AuthoringClient per la gestione dei progetti all'interno della risorsa. È 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 lingua 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 Language.

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

Creare QuestionAnsweringClient

Dopo aver determinato l'endpoint e la chiave API , è possibile creare un'istanza di QuestionAnsweringClient:

from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering import QuestionAnsweringClient

endpoint = "https://{myaccount}.api.cognitive.microsoft.com"
credential = AzureKeyCredential("{api-key}")

client = QuestionAnsweringClient(endpoint, credential)

Creare AuthoringClient

Con l'endpoint e la chiave API è possibile creare un'istanza di AuthoringClient:

from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering.authoring import AuthoringClient

endpoint = "https://{myaccount}.api.cognitive.microsoft.com"
credential = AzureKeyCredential("{api-key}")

client = AuthoringClient(endpoint, credential)

Creare un client con una credenziale di Azure Active Directory

Per usare una credenziale token di Azure Active Directory (AAD), specificare un'istanza del tipo di credenziali 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:

Dopo la configurazione, è possibile scegliere il tipo di credenziali da azure.identity da usare. 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.questionanswering import QuestionAnsweringClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
client = QuestionAnsweringClient(endpoint="https://<my-custom-subdomain>.cognitiveservices.azure.com/", credential=credential)

Concetti chiave

QuestionAnsweringClient

QuestionAnsweringClient è l'interfaccia primaria per porre domande usando un knowledge base con le proprie informazioni o l'input di testo usando modelli pre-sottoposti a training. Per le operazioni asincrone, un asincrono QuestionAnsweringClient si trova nello azure.ai.language.questionanswering.aio spazio dei nomi.

Creazione diClient

AuthoringClient fornisce un'interfaccia per la gestione dei progetti di risposta alle domande. Esempi delle operazioni disponibili includono la creazione e la distribuzione di progetti, l'aggiornamento delle origini conoscenze e l'aggiornamento delle coppie di domande e risposte. Fornisce sia API sincrone che asincrone.

Esempio

QuestionAnsweringClient

La azure-ai-language-questionanswering libreria client fornisce api sincrone e asincrone.

Fai una domanda

L'unico input necessario per porre una domanda usando un knowledge base è solo la domanda stessa:

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering import QuestionAnsweringClient

endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

client = QuestionAnsweringClient(endpoint, AzureKeyCredential(key))

output = client.get_answers(
    question="How long should my Surface battery last?",
    project_name="FAQ",
    deployment_name="test"
)
for candidate in output.answers:
    print("({}) {}".format(candidate.confidence, candidate.answer))
    print("Source: {}".format(candidate.source))

È possibile impostare opzioni di parole chiave aggiuntive per limitare il numero di risposte, specificare un punteggio minimo di attendibilità e altro ancora.

Porre una domanda di completamento

Se il knowledge base è configurato per chit-chat, le risposte del knowledge base possono includere richieste suggerite per le domande di completamento per avviare una conversazione. È possibile porre una domanda di completamento fornendo l'ID della risposta scelta come contesto per la conversazione continua:

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering import QuestionAnsweringClient
from azure.ai.language.questionanswering import models

endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

client = QuestionAnsweringClient(endpoint, AzureKeyCredential(key))

output = client.get_answers(
    question="How long should charging take?",
    answer_context=models.KnowledgeBaseAnswerContext(
        previous_qna_id=previous_answer.qna_id
    ),
    project_name="FAQ",
    deployment_name="live"
)
for candidate in output.answers:
    print("({}) {}".format(candidate.confidence, candidate.answer))
    print("Source: {}".format(candidate.source))

Creare un nuovo progetto

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering.authoring import AuthoringClient

# get service secrets
endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

# create client
client = AuthoringClient(endpoint, AzureKeyCredential(key))
with client:

    # create project
    project_name = "IssacNewton"
    project = client.create_project(
        project_name=project_name,
        options={
            "description": "biography of Sir Issac Newton",
            "language": "en",
            "multilingualResource": True,
            "settings": {
                "defaultAnswer": "no answer"
            }
        })

    print("view created project info:")
    print("\tname: {}".format(project["projectName"]))
    print("\tlanguage: {}".format(project["language"]))
    print("\tdescription: {}".format(project["description"]))

Aggiungere un'origine della conoscenza

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering.authoring import AuthoringClient

# get service secrets
endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

# create client
client = AuthoringClient(endpoint, AzureKeyCredential(key))

project_name = "IssacNewton"
update_sources_poller = client.begin_update_sources(
    project_name=project_name,
    sources=[
        {
            "op": "add",
            "value": {
                "displayName": "Issac Newton Bio",
                "sourceUri": "https://wikipedia.org/wiki/Isaac_Newton",
                "sourceKind": "url"
            }
        }
    ]
)
update_sources_poller.result()

# list sources
print("list project sources")
sources = client.list_sources(
    project_name=project_name
)
for source in sources:
    print("project: {}".format(source["displayName"]))
    print("\tsource: {}".format(source["source"]))
    print("\tsource Uri: {}".format(source["sourceUri"]))
    print("\tsource kind: {}".format(source["sourceKind"]))

Distribuire il progetto

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering.authoring import AuthoringClient

# get service secrets
endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

# create client
client = AuthoringClient(endpoint, AzureKeyCredential(key))

project_name = "IssacNewton"

# deploy project
deployment_poller = client.begin_deploy_project(
    project_name=project_name,
    deployment_name="production"
)
deployment_poller.result()

# list all deployments
deployments = client.list_deployments(
    project_name=project_name
)

print("view project deployments")
for d in deployments:
    print(d)

Operazioni asincrone

Gli esempi precedenti possono anche essere eseguiti in modo asincrono usando i client nello aio spazio dei nomi:

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering.aio import QuestionAnsweringClient

endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

client = QuestionAnsweringClient(endpoint, AzureKeyCredential(key))

output = await client.get_answers(
    question="How long should my Surface battery last?",
    project_name="FAQ",
    deployment_name="production"
)

Configurazione facoltativa

Gli argomenti delle parole chiave facoltativi possono essere passati al client e a 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

I client di risposta alle domande di Azure generano eccezioni definite in Azure Core. Quando si interagisce con la libreria client di risposte al servizio di linguaggio cognitivo usando Python SDK, gli errori restituiti dal servizio corrispondono agli stessi codici di stato HTTP restituiti per le richieste api REST .

Ad esempio, se si invia una domanda a un knowledge base non esistente, viene restituito un 400 errore che indica "Richiesta non valida".

from azure.core.exceptions import HttpResponseError

try:
    client.get_answers(
        question="Why?",
        project_name="invalid-knowledge-base",
        deployment_name="test"
    )
except HttpResponseError as error:
    print("Query failed: {}".format(error.message))

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 del livello DEBUG, inclusi i corpi di richiesta/risposta e le intestazioni non attendibili, può essere abilitata in un client con l'argomento logging_enable .

Vedere la documentazione completa sulla registrazione sdk con esempi qui.

Passaggi successivi

Contributo

Per informazioni dettagliate sulla creazione, 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.

Impression