Delen via

Azure Cognitive Language Service-clientbibliotheek voor vragen beantwoorden voor Python - versie 1.1.0

  • Artikel

Vragen beantwoorden is een cloudgebaseerde API-service waarmee u een gesprekslaag voor vragen en antwoorden kunt maken over uw bestaande gegevens. Gebruik het om een Knowledge Base te bouwen door vragen en antwoorden te extraheren uit uw semi-gestructureerde inhoud, inclusief veelgestelde vragen, handleidingen en documenten. Beantwoord de vragen van gebruikers automatisch met de beste antwoorden van de QnA's in uw Knowledge Base. Uw Knowledge Base wordt ook slimmer, omdat het voortdurend leert van het gedrag van gebruikers.

Broncode | Pakket (PyPI) | API-referentiedocumentatie | Productdocumentatie | Monsters

Disclaimer

Ondersteuning voor Azure SDK Python-pakketten voor Python 2.7 is beëindigd op 01 januari 2022. Voor meer informatie en vragen raadpleegt u https://github.com/Azure/azure-sdk-for-python/issues/20691

Aan de slag

Vereisten

Het pakket installeren

Installeer de Azure Question Answering-clientbibliotheek voor Python met pip:

pip install azure-ai-language-questionanswering

Opmerking: deze versie van de clientbibliotheek is standaard ingesteld op de service-API-versie 2021-10-01.

De client verifiëren

Als u wilt communiceren met de service Vraag beantwoorden, moet u een exemplaar van de klasse QuestionAnsweringClient of een exemplaar van de AuthoringClient maken voor het beheren van projecten binnen uw resource. U hebt een eindpunt en een API-sleutel nodig om een clientobject te instantiëren. Zie Aanvragen verifiëren bij Azure Cognitive Services voor meer informatie over verificatie met Cognitive Services.

Een API-sleutel ophalen

U kunt het eindpunt en een API-sleutel ophalen uit de taalresource in Azure Portal.

U kunt ook de Azure CLI-opdracht gebruiken die hieronder wordt weergegeven om de API-sleutel op te halen uit de taalresource.

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

QuestionAnsweringClient maken

Zodra u uw eindpunt en API-sleutel hebt bepaald, kunt u een QuestionAnsweringClient instantiëren:

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)

AuthoringClient maken

Met uw eindpunt en API-sleutel kunt u een AuthoringClient instantiëren:

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)

Een client maken met een Azure Active Directory-referentie

Als u een AAD-tokenreferentie (Azure Active Directory) wilt gebruiken, geeft u een exemplaar op van het gewenste referentietype dat is verkregen uit de azure-identity-bibliotheek . Houd er rekening mee dat regionale eindpunten geen ondersteuning bieden voor AAD-verificatie. Maak een aangepaste subdomeinnaam voor uw resource om dit type verificatie te kunnen gebruiken.

Voor verificatie met AAD is enige initiële installatie vereist:

Na de installatie kunt u kiezen welk type referentie van azure.identity u wilt gebruiken. Als voorbeeld kan DefaultAzureCredential worden gebruikt om de client te verifiëren:

Stel de waarden van de client-id, tenant-id en clientgeheim van de AAD-toepassing in als omgevingsvariabelen: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Gebruik de geretourneerde tokenreferentie om de client te verifiëren:

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)

Belangrijkste concepten

QuestionAnsweringClient

De QuestionAnsweringClient is de primaire interface voor het stellen van vragen met behulp van een Knowledge Base met uw eigen informatie of tekstinvoer met behulp van vooraf getrainde modellen. Voor asynchrone bewerkingen bevindt zich een asynchroon QuestionAnsweringClient in de azure.ai.language.questionanswering.aio naamruimte.

AuthoringClient

De AuthoringClient biedt een interface voor het beheren van projecten voor het beantwoorden van vragen. Voorbeelden van de beschikbare bewerkingen zijn het maken en implementeren van projecten, het bijwerken van uw kennisbronnen en het bijwerken van vraag- en antwoordparen. Het biedt zowel synchrone als asynchrone API's.

Voorbeelden

QuestionAnsweringClient

De azure-ai-language-questionanswering clientbibliotheek biedt zowel synchrone als asynchrone API's.

Stel een vraag

De enige invoer die nodig is om een vraag te stellen met behulp van een Knowledge Base, is alleen de vraag zelf:

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

U kunt extra trefwoordopties instellen om het aantal antwoorden te beperken, een minimale betrouwbaarheidsscore op te geven en meer.

Een vervolgvraag stellen

Als uw Knowledge Base is geconfigureerd voor chit-chat, kunnen de antwoorden van de Knowledge Base suggesties voor vervolgvragen bevatten om een gesprek te starten. U kunt een vervolgvraag stellen door de id van het gekozen antwoord op te geven als context voor het vervolggesprek:

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

Een nieuw project maken

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

Een kennisbron toevoegen

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

Uw project implementeren

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 bewerkingen

De bovenstaande voorbeelden kunnen ook asynchroon worden uitgevoerd met behulp van de clients in de aio naamruimte:

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

Optionele configuratie

Optionele trefwoordargumenten kunnen worden doorgegeven op het niveau van de client en per bewerking. In de naslagdocumentatie van Azure Core worden de beschikbare configuraties beschreven voor nieuwe pogingen, logboekregistratie, transportprotocollen en meer.

Problemen oplossen

Algemeen

Azure-vragen beantwoordende clients genereren uitzonderingen die zijn gedefinieerd in Azure Core. Wanneer u communiceert met de clientbibliotheek vragen beantwoorden van de Cognitive Language Service met behulp van de Python SDK, komen fouten die door de service worden geretourneerd, overeen met dezelfde HTTP-statuscodes die worden geretourneerd voor REST API-aanvragen .

Als u bijvoorbeeld een vraag indient naar een niet-bestaande Knowledge Base, wordt er een 400 fout geretourneerd die 'Ongeldige aanvraag' aangeeft.

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

Logboekregistratie

Deze bibliotheek maakt gebruik van de standaardbibliotheek voor logboekregistratie voor logboekregistratie. Basisinformatie over HTTP-sessies (URL's, headers, enzovoort) wordt geregistreerd op INFO-niveau.

Gedetailleerde logboekregistratie op foutopsporingsniveau, inclusief aanvraag-/antwoordteksten en niet-bewerkte headers, kan worden ingeschakeld op een client met het logging_enable argument .

Bekijk hier de volledige documentatie voor SDK-logboekregistratie met voorbeelden.

Volgende stappen

Bijdragen

Zie de CONTRIBUTING.md voor meer informatie over het bouwen, testen en bijdragen aan deze bibliotheek.

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar cla.microsoft.com voor meer informatie.

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit maar eenmaal te doen voor alle repo's waar gebruik wordt gemaakt van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Zie de Veelgestelde vragen over de gedragscode voor meer informatie of neem contact op opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.

Weergaven