Azure Cognitive Language Service-Clientbibliothek zur Fragebeantwortung für Python – Version 1.1.0
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
- Für die Verwendung dieses Pakets ist Python 3.7 oder höher erforderlich.
- Ein Azure-Abonnement
- Eine Sprachdienstressource
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:
- Installieren von azure-identity
- Registrieren einer neuen AAD-Anwendung
- Gewähren Sie dem Sprachdienst Zugriff, indem Sie Ihrem Dienstprinzipal die Rolle "Cognitive Services Language Reader" zuweisen.
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 QuestionAnsweringClient
azure.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.
- Eine Frage stellen
- Stellen sie eine Folgefrage
- Erstellen eines neuen Projekts
- Hinzufügen einer Wissensquelle
- Bereitstellen Ihres Projekts
- Asynchrone Vorgänge
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
- Sehen Sie sich unsere Beispiele an.
- Erfahren Sie mehr über die verschiedenen Funktionen des Diensts für die Fragebeantwortung.
- Probieren Sie unsere Servicedemos aus.
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.
Azure SDK for Python