Azure Cognitive Language Service-Clientbibliothek zur Fragebeantwortung für Python – Version 1.1.0

  • Artikel

Die Frageantwort ist ein cloudbasierter API-Dienst, mit dem Sie eine Konversations-Frage-Antwort-Ebene über Ihre vorhandenen Daten erstellen können. Verwenden Sie es, um eine Wissensdatenbank zu erstellen, indem Sie Fragen und Antworten aus Ihren teilstrukturierten Inhalten extrahieren, einschließlich FAQ, Handbüchern und Dokumenten. Beantworten Sie Die Fragen der Benutzer mit den besten Antworten aus den QnAs in Ihrem Wissensdatenbank – automatisch. Ihr Wissensdatenbank wird auch intelligenter, da es kontinuierlich aus dem Verhalten der Benutzer lernt.

Quellcode | Paket (PyPI) | API-Referenzdokumentation | Produktdokumentation | Proben

Haftungsausschluss

Die Unterstützung von Azure SDK Python-Paketen für Python 2.7 endete am 01. Januar 2022. Weitere Informationen und Antworten finden Sie unter https://github.com/Azure/azure-sdk-for-python/issues/20691.

Erste Schritte

Voraussetzungen

Installieren des Pakets

Installieren Sie die Azure-Fragenantwort-Clientbibliothek für Python mit pip:

pip install azure-ai-language-questionanswering

Hinweis: In dieser Version der Clientbibliothek wird standardmäßig die Dienst-API-Version verwendet 2021-10-01.

Authentifizieren des Clients

Um mit dem Fragebeantwortungsdienst zu interagieren, müssen Sie eine Instanz der QuestionAnsweringClient-Klasse oder eine Instanz des AuthoringClient zum Verwalten von Projekten in Ihrer Ressource erstellen. Sie benötigen einen Endpunkt und einen API-Schlüssel , um ein Clientobjekt zu instanziieren. Weitere Informationen zur Authentifizierung mit Cognitive Services finden Sie unter Authentifizieren von Anforderungen an Azure Cognitive Services.

Abrufen eines API-Schlüssels

Sie können den Endpunkt und einen API-Schlüssel aus der Sprachressource im Azure-Portal abrufen.

Alternativ können Sie den unten gezeigten Azure CLI-Befehl verwenden, um den API-Schlüssel aus der Language-Ressource abzurufen.

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

Erstellen von QuestionAnsweringClient

Nachdem Sie Ihren Endpunkt und API-Schlüssel ermittelt haben, können Sie einen QuestionAnsweringClient instanziieren:

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)

Erstellen von AuthoringClient

Mit Ihrem Endpunkt und API-Schlüssel können Sie einen AuthoringClient instanziieren:

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)

Erstellen eines Clients mit Azure Active Directory-Anmeldeinformationen

Um Azure Active Directory-Tokenanmeldeinformationen (AAD) zu verwenden, geben Sie eine Instanz des gewünschten Anmeldeinformationstyps an, der aus der Azure-Identity-Bibliothek abgerufen wird. Beachten Sie, dass regionale Endpunkte die AAD-Authentifizierung nicht unterstützen. Erstellen Sie einen benutzerdefinierten Unterdomänennamen für Ihre Ressource, um diese Art der Authentifizierung zu verwenden.

Für die Authentifizierung mit AAD ist eine anfängliche Einrichtung erforderlich:

Nach dem Setup können Sie auswählen, welcher Typ von Anmeldeinformationen aus azure.identity verwendet werden soll. Als Beispiel kann DefaultAzureCredential verwendet werden, um den Client zu authentifizieren:

Legen Sie die Werte der Client-ID, mandanten-ID und des geheimen Clientschlüssels der AAD-Anwendung als Umgebungsvariablen fest: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Verwenden Sie die zurückgegebenen Tokenanmeldeinformationen, um den Client zu authentifizieren:

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)

Wichtige Begriffe

QuestionAnsweringClient

Der QuestionAnsweringClient ist die primäre Schnittstelle zum Stellen von Fragen mithilfe einer Wissensdatenbank mit eigenen Informationen oder texteingaben mithilfe von vortrainierten Modellen. Bei asynchronen Vorgängen befindet sich im Namespace eine asynchrone QuestionAnsweringClientazure.ai.language.questionanswering.aio .

AuthoringClient

Der AuthoringClient bietet eine Schnittstelle zum Verwalten von Fragenbeantwortungsprojekten. Beispiele für die verfügbaren Vorgänge sind das Erstellen und Bereitstellen von Projekten, das Aktualisieren Ihrer Wissensquellen und das Aktualisieren von Frage-Antwort-Paaren. Es bietet sowohl synchrone als auch asynchrone APIs.

Beispiele

QuestionAnsweringClient

Die azure-ai-language-questionanswering Clientbibliothek stellt synchrone und asynchrone APIs bereit.

Fragen stellen

Die einzige Eingabe, die erforderlich ist, um eine Frage mit einem Wissensdatenbank zu stellen, ist nur die Frage selbst:

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))

Sie können zusätzliche Schlüsselwortoptionen festlegen, um die Anzahl der Antworten zu begrenzen, eine minimale Konfidenzbewertung anzugeben und vieles mehr.

Stellen sie eine Folgefrage

Wenn Ihr Wissensdatenbank für Chit-Chat konfiguriert ist, können die Antworten aus dem Wissensdatenbank vorgeschlagene Aufforderungen für Folgefragen enthalten, um eine Konversation zu initiieren. Sie können eine Folgefrage stellen, indem Sie die ID Ihrer gewählten Antwort als Kontext für die fortgesetzte Unterhaltung angeben:

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))

Erstellen eines neuen Projekts

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"]))

Hinzufügen einer Wissensquelle

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"]))

Bereitstellen des Projekts

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)

Asynchrone Vorgänge

Die obigen Beispiele können auch mit den Clients im aio Namespace asynchron ausgeführt werden:

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"
)

Optionale Konfiguration

Optionale Schlüsselwortargumente können auf Client- und Vorgangsebene übergeben werden. Die azure-core-Referenzdokumentation beschreibt verfügbare Konfigurationen für Wiederholungen, Protokollierung, Transportprotokolle und vieles mehr.

Problembehandlung

Allgemein

Azure-Fragenantwortclients lösen ausnahmen aus, die in Azure Core definiert sind. Wenn Sie mit der Cognitive Language Service-Clientbibliothek zur Beantwortung von Fragen mithilfe des Python SDK interagieren, entsprechen vom Dienst zurückgegebene Fehler den gleichen HTTP-Statuscodes, die für REST-API-Anforderungen zurückgegeben werden.

Wenn Sie beispielsweise eine Frage an eine nicht vorhandene Wissensdatenbank senden, wird ein 400 Fehler zurückgegeben, der auf "Ungültige Anforderung" hinweist.

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))

Protokollierung

Diese Bibliothek verwendet die Standardprotokollierungsbibliothek für die Protokollierung. Grundlegende Informationen zu HTTP-Sitzungen (URLs, Header usw.) werden auf INFO-Ebene protokolliert.

Eine detaillierte Protokollierung auf DEBUG-Ebene, einschließlich Anforderungs-/Antworttexten und nicht ausgeführten Headern, kann auf einem Client mit dem logging_enable Argument aktiviert werden.

Sehen Sie sich die vollständige SDK-Protokollierungsdokumentation mit Beispielen hier an.

Nächste Schritte

Mitwirken

Weitere Informationen zum Erstellen, Testen und Mitwirken zu dieser Bibliothek finden Sie im CONTRIBUTING.md .

Beiträge und Vorschläge für dieses Projekt sind willkommen. 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. Weitere Informationen finden Sie unter cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Aufrufe